1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename gnat_rm.info 4@documentencoding UTF-8 5@ifinfo 6@*Generated by Sphinx 1.4.6.@* 7@end ifinfo 8@settitle GNAT Reference Manual 9@defindex ge 10@paragraphindent 0 11@exampleindent 4 12@finalout 13@dircategory GNU Ada Tools 14@direntry 15* gnat_rm: (gnat_rm.info). gnat_rm 16@end direntry 17 18@definfoenclose strong,`,' 19@definfoenclose emph,`,' 20@c %**end of header 21 22@copying 23@quotation 24GNAT Reference Manual , Dec 11, 2020 25 26AdaCore 27 28Copyright @copyright{} 2008-2021, Free Software Foundation 29@end quotation 30 31@end copying 32 33@titlepage 34@title GNAT Reference Manual 35@insertcopying 36@end titlepage 37@contents 38 39@c %** start of user preamble 40 41@c %** end of user preamble 42 43@ifnottex 44@node Top 45@top GNAT Reference Manual 46@insertcopying 47@end ifnottex 48 49@c %**start of body 50@anchor{gnat_rm doc}@anchor{0} 51@emph{GNAT, The GNU Ada Development Environment} 52 53 54@include gcc-common.texi 55GCC version @value{version-GCC}@* 56AdaCore 57 58Permission is granted to copy, distribute and/or modify this document 59under the terms of the GNU Free Documentation License, Version 1.3 or 60any later version published by the Free Software Foundation; with no 61Invariant Sections, with the Front-Cover Texts being "GNAT Reference 62Manual", and with no Back-Cover Texts. A copy of the license is 63included in the section entitled @ref{1,,GNU Free Documentation License}. 64 65@menu 66* About This Guide:: 67* Implementation Defined Pragmas:: 68* Implementation Defined Aspects:: 69* Implementation Defined Attributes:: 70* Standard and Implementation Defined Restrictions:: 71* Implementation Advice:: 72* Implementation Defined Characteristics:: 73* Intrinsic Subprograms:: 74* Representation Clauses and Pragmas:: 75* Standard Library Routines:: 76* The Implementation of Standard I/O:: 77* The GNAT Library:: 78* Interfacing to Other Languages:: 79* Specialized Needs Annexes:: 80* Implementation of Specific Ada Features:: 81* Implementation of Ada 2012 Features:: 82* 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 Aggregate_Individually_Assign:: 107* Pragma Allow_Integer_Address:: 108* Pragma Annotate:: 109* Pragma Assert:: 110* Pragma Assert_And_Cut:: 111* Pragma Assertion_Policy:: 112* Pragma Assume:: 113* Pragma Assume_No_Invalid_Values:: 114* Pragma Async_Readers:: 115* Pragma Async_Writers:: 116* Pragma Attribute_Definition:: 117* Pragma C_Pass_By_Copy:: 118* Pragma Check:: 119* Pragma Check_Float_Overflow:: 120* Pragma Check_Name:: 121* Pragma Check_Policy:: 122* Pragma Comment:: 123* Pragma Common_Object:: 124* Pragma Compile_Time_Error:: 125* Pragma Compile_Time_Warning:: 126* Pragma Compiler_Unit:: 127* Pragma Compiler_Unit_Warning:: 128* Pragma Complete_Representation:: 129* Pragma Complex_Representation:: 130* Pragma Component_Alignment:: 131* Pragma Constant_After_Elaboration:: 132* Pragma Contract_Cases:: 133* Pragma Convention_Identifier:: 134* Pragma CPP_Class:: 135* Pragma CPP_Constructor:: 136* Pragma CPP_Virtual:: 137* Pragma CPP_Vtable:: 138* Pragma CPU:: 139* Pragma Deadline_Floor:: 140* Pragma Default_Initial_Condition:: 141* Pragma Debug:: 142* Pragma Debug_Policy:: 143* Pragma Default_Scalar_Storage_Order:: 144* Pragma Default_Storage_Pool:: 145* Pragma Depends:: 146* Pragma Detect_Blocking:: 147* Pragma Disable_Atomic_Synchronization:: 148* Pragma Dispatching_Domain:: 149* Pragma Effective_Reads:: 150* Pragma Effective_Writes:: 151* Pragma Elaboration_Checks:: 152* Pragma Eliminate:: 153* Pragma Enable_Atomic_Synchronization:: 154* Pragma Export_Function:: 155* Pragma Export_Object:: 156* Pragma Export_Procedure:: 157* Pragma Export_Value:: 158* Pragma Export_Valued_Procedure:: 159* Pragma Extend_System:: 160* Pragma Extensions_Allowed:: 161* Pragma Extensions_Visible:: 162* Pragma External:: 163* Pragma External_Name_Casing:: 164* Pragma Fast_Math:: 165* Pragma Favor_Top_Level:: 166* Pragma Finalize_Storage_Only:: 167* Pragma Float_Representation:: 168* Pragma Ghost:: 169* Pragma Global:: 170* Pragma Ident:: 171* Pragma Ignore_Pragma:: 172* Pragma Implementation_Defined:: 173* Pragma Implemented:: 174* Pragma Implicit_Packing:: 175* Pragma Import_Function:: 176* Pragma Import_Object:: 177* Pragma Import_Procedure:: 178* Pragma Import_Valued_Procedure:: 179* Pragma Independent:: 180* Pragma Independent_Components:: 181* Pragma Initial_Condition:: 182* Pragma Initialize_Scalars:: 183* Pragma Initializes:: 184* Pragma Inline_Always:: 185* Pragma Inline_Generic:: 186* Pragma Interface:: 187* Pragma Interface_Name:: 188* Pragma Interrupt_Handler:: 189* Pragma Interrupt_State:: 190* Pragma Invariant:: 191* Pragma Keep_Names:: 192* Pragma License:: 193* Pragma Link_With:: 194* Pragma Linker_Alias:: 195* Pragma Linker_Constructor:: 196* Pragma Linker_Destructor:: 197* Pragma Linker_Section:: 198* Pragma Lock_Free:: 199* Pragma Loop_Invariant:: 200* Pragma Loop_Optimize:: 201* Pragma Loop_Variant:: 202* Pragma Machine_Attribute:: 203* Pragma Main:: 204* Pragma Main_Storage:: 205* Pragma Max_Queue_Length:: 206* Pragma No_Body:: 207* Pragma No_Caching:: 208* Pragma No_Component_Reordering:: 209* Pragma No_Elaboration_Code_All:: 210* Pragma No_Heap_Finalization:: 211* Pragma No_Inline:: 212* Pragma No_Return:: 213* Pragma No_Strict_Aliasing:: 214* Pragma No_Tagged_Streams:: 215* Pragma Normalize_Scalars:: 216* Pragma Obsolescent:: 217* Pragma Optimize_Alignment:: 218* Pragma Ordered:: 219* Pragma Overflow_Mode:: 220* Pragma Overriding_Renamings:: 221* Pragma Partition_Elaboration_Policy:: 222* Pragma Part_Of:: 223* Pragma Passive:: 224* Pragma Persistent_BSS:: 225* Pragma Post:: 226* Pragma Postcondition:: 227* Pragma Post_Class:: 228* Pragma 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_Caching:: 331* Aspect No_Elaboration_Code_All:: 332* Aspect No_Inline:: 333* Aspect No_Tagged_Streams:: 334* Aspect Object_Size:: 335* Aspect Obsolescent:: 336* Aspect Part_Of:: 337* Aspect Persistent_BSS:: 338* Aspect Predicate:: 339* Aspect Pure_Function:: 340* Aspect Refined_Depends:: 341* Aspect Refined_Global:: 342* Aspect Refined_Post:: 343* Aspect Refined_State:: 344* Aspect Relaxed_Initialization:: 345* Aspect Remote_Access_Type:: 346* Aspect Secondary_Stack_Size:: 347* Aspect Scalar_Storage_Order:: 348* Aspect Shared:: 349* Aspect Simple_Storage_Pool:: 350* Aspect Simple_Storage_Pool_Type:: 351* Aspect SPARK_Mode:: 352* Aspect Suppress_Debug_Info:: 353* Aspect Suppress_Initialization:: 354* Aspect Test_Case:: 355* Aspect Thread_Local_Storage:: 356* Aspect Universal_Aliasing:: 357* Aspect Universal_Data:: 358* Aspect Unmodified:: 359* Aspect Unreferenced:: 360* Aspect Unreferenced_Objects:: 361* Aspect Value_Size:: 362* Aspect Volatile_Full_Access:: 363* Aspect Volatile_Function:: 364* Aspect Warnings:: 365 366Implementation Defined Attributes 367 368* Attribute Abort_Signal:: 369* Attribute Address_Size:: 370* Attribute Asm_Input:: 371* Attribute Asm_Output:: 372* Attribute Atomic_Always_Lock_Free:: 373* Attribute Bit:: 374* Attribute Bit_Position:: 375* Attribute Code_Address:: 376* Attribute Compiler_Version:: 377* Attribute Constrained:: 378* Attribute Default_Bit_Order:: 379* Attribute Default_Scalar_Storage_Order:: 380* Attribute Deref:: 381* Attribute Descriptor_Size:: 382* Attribute Elaborated:: 383* Attribute Elab_Body:: 384* Attribute Elab_Spec:: 385* Attribute Elab_Subp_Body:: 386* Attribute Emax:: 387* Attribute Enabled:: 388* Attribute Enum_Rep:: 389* Attribute Enum_Val:: 390* Attribute Epsilon:: 391* Attribute Fast_Math:: 392* Attribute Finalization_Size:: 393* Attribute Fixed_Value:: 394* Attribute From_Any:: 395* Attribute Has_Access_Values:: 396* Attribute Has_Discriminants:: 397* Attribute Has_Tagged_Values:: 398* Attribute Img:: 399* Attribute Initialized:: 400* Attribute Integer_Value:: 401* Attribute Invalid_Value:: 402* Attribute Iterable:: 403* Attribute Large:: 404* Attribute Library_Level:: 405* Attribute Lock_Free:: 406* Attribute Loop_Entry:: 407* Attribute Machine_Size:: 408* Attribute Mantissa:: 409* Attribute Maximum_Alignment:: 410* Attribute Max_Integer_Size:: 411* Attribute Mechanism_Code:: 412* Attribute Null_Parameter:: 413* Attribute Object_Size:: 414* Attribute Old:: 415* Attribute Passed_By_Reference:: 416* Attribute Pool_Address:: 417* Attribute Range_Length:: 418* Attribute Restriction_Set:: 419* Attribute Result:: 420* Attribute Safe_Emax:: 421* Attribute Safe_Large:: 422* Attribute Safe_Small:: 423* Attribute Scalar_Storage_Order:: 424* Attribute Simple_Storage_Pool:: 425* Attribute Small:: 426* Attribute Small_Denominator:: 427* Attribute Small_Numerator:: 428* Attribute Storage_Unit:: 429* Attribute Stub_Type:: 430* Attribute System_Allocator_Alignment:: 431* Attribute Target_Name:: 432* Attribute To_Address:: 433* Attribute To_Any:: 434* Attribute Type_Class:: 435* Attribute Type_Key:: 436* Attribute TypeCode:: 437* Attribute Unconstrained_Array:: 438* Attribute Universal_Literal_String:: 439* Attribute Unrestricted_Access:: 440* Attribute Update:: 441* Attribute Valid_Scalars:: 442* Attribute VADS_Size:: 443* Attribute Value_Size:: 444* Attribute Wchar_T_Size:: 445* Attribute Word_Size:: 446 447Standard and Implementation Defined Restrictions 448 449* Partition-Wide Restrictions:: 450* Program Unit Level Restrictions:: 451 452Partition-Wide Restrictions 453 454* Immediate_Reclamation:: 455* Max_Asynchronous_Select_Nesting:: 456* Max_Entry_Queue_Length:: 457* Max_Protected_Entries:: 458* Max_Select_Alternatives:: 459* Max_Storage_At_Blocking:: 460* Max_Task_Entries:: 461* Max_Tasks:: 462* No_Abort_Statements:: 463* No_Access_Parameter_Allocators:: 464* No_Access_Subprograms:: 465* No_Allocators:: 466* No_Anonymous_Allocators:: 467* No_Asynchronous_Control:: 468* No_Calendar:: 469* No_Coextensions:: 470* No_Default_Initialization:: 471* No_Delay:: 472* No_Dependence:: 473* No_Direct_Boolean_Operators:: 474* No_Dispatch:: 475* No_Dispatching_Calls:: 476* No_Dynamic_Attachment:: 477* No_Dynamic_Priorities:: 478* No_Entry_Calls_In_Elaboration_Code:: 479* No_Enumeration_Maps:: 480* No_Exception_Handlers:: 481* No_Exception_Propagation:: 482* No_Exception_Registration:: 483* No_Exceptions:: 484* No_Finalization:: 485* No_Fixed_Point:: 486* No_Floating_Point:: 487* No_Implicit_Conditionals:: 488* No_Implicit_Dynamic_Code:: 489* No_Implicit_Heap_Allocations:: 490* No_Implicit_Protected_Object_Allocations:: 491* No_Implicit_Task_Allocations:: 492* No_Initialize_Scalars:: 493* No_IO:: 494* No_Local_Allocators:: 495* No_Local_Protected_Objects:: 496* No_Local_Timing_Events:: 497* No_Long_Long_Integers:: 498* No_Multiple_Elaboration:: 499* No_Nested_Finalization:: 500* No_Protected_Type_Allocators:: 501* No_Protected_Types:: 502* No_Recursion:: 503* No_Reentrancy:: 504* No_Relative_Delay:: 505* No_Requeue_Statements:: 506* No_Secondary_Stack:: 507* No_Select_Statements:: 508* No_Specific_Termination_Handlers:: 509* No_Specification_of_Aspect:: 510* No_Standard_Allocators_After_Elaboration:: 511* No_Standard_Storage_Pools:: 512* No_Stream_Optimizations:: 513* No_Streams:: 514* No_Task_Allocators:: 515* No_Task_At_Interrupt_Priority:: 516* No_Task_Attributes_Package:: 517* No_Task_Hierarchy:: 518* No_Task_Termination:: 519* No_Tasking:: 520* No_Terminate_Alternatives:: 521* No_Unchecked_Access:: 522* No_Unchecked_Conversion:: 523* No_Unchecked_Deallocation:: 524* No_Use_Of_Entity:: 525* Pure_Barriers:: 526* Simple_Barriers:: 527* Static_Priorities:: 528* Static_Storage_Size:: 529 530Program Unit Level Restrictions 531 532* No_Elaboration_Code:: 533* No_Dynamic_Sized_Objects:: 534* No_Entry_Queue:: 535* No_Implementation_Aspect_Specifications:: 536* No_Implementation_Attributes:: 537* No_Implementation_Identifiers:: 538* No_Implementation_Pragmas:: 539* No_Implementation_Restrictions:: 540* No_Implementation_Units:: 541* No_Implicit_Aliasing:: 542* No_Implicit_Loops:: 543* No_Obsolescent_Features:: 544* No_Wide_Characters:: 545* Static_Dispatch_Tables:: 546* SPARK_05:: 547 548Implementation Advice 549 550* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 551* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 552* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 553* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 554* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 555* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 556* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 557* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 558* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 559* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 560* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 561* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 562* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 563* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 564* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 565* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 566* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 567* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 568* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 569* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 570* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 571* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 572* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 573* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 574* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 575* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 576* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 577* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 578* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 579* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 580* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 581* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. 582* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 583* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 584* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 585* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 586* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 587* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 588* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 589* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 590* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 591* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 592* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 593* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 594* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 595* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 596* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 597* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 598* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 599* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 600* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 601* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 602* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 603* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 604* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 605* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 606* RM F(7); COBOL Support: RM F 7 COBOL Support. 607* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 608* RM G; Numerics: RM G Numerics. 609* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 610* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 611* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 612* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 613* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 614 615Intrinsic Subprograms 616 617* Intrinsic Operators:: 618* Compilation_ISO_Date:: 619* Compilation_Date:: 620* Compilation_Time:: 621* Enclosing_Entity:: 622* Exception_Information:: 623* Exception_Message:: 624* Exception_Name:: 625* File:: 626* Line:: 627* Shifts and Rotates:: 628* Source_Location:: 629 630Representation Clauses and Pragmas 631 632* Alignment Clauses:: 633* Size Clauses:: 634* Storage_Size Clauses:: 635* Size of Variant Record Objects:: 636* Biased Representation:: 637* Value_Size and Object_Size Clauses:: 638* Component_Size Clauses:: 639* Bit_Order Clauses:: 640* Effect of Bit_Order on Byte Ordering:: 641* Pragma Pack for Arrays:: 642* Pragma Pack for Records:: 643* Record Representation Clauses:: 644* Handling of Records with Holes:: 645* Enumeration Clauses:: 646* Address Clauses:: 647* Use of Address Clauses for Memory-Mapped I/O:: 648* Effect of Convention on Representation:: 649* Conventions and Anonymous Access Types:: 650* Determining the Representations chosen by GNAT:: 651 652The Implementation of Standard I/O 653 654* Standard I/O Packages:: 655* FORM Strings:: 656* Direct_IO:: 657* Sequential_IO:: 658* Text_IO:: 659* Wide_Text_IO:: 660* Wide_Wide_Text_IO:: 661* Stream_IO:: 662* Text Translation:: 663* Shared Files:: 664* Filenames encoding:: 665* File content encoding:: 666* Open Modes:: 667* Operations on C Streams:: 668* Interfacing to C Streams:: 669 670Text_IO 671 672* Stream Pointer Positioning:: 673* Reading and Writing Non-Regular Files:: 674* Get_Immediate:: 675* Treating Text_IO Files as Streams:: 676* Text_IO Extensions:: 677* Text_IO Facilities for Unbounded Strings:: 678 679Wide_Text_IO 680 681* Stream Pointer Positioning: Stream Pointer Positioning<2>. 682* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 683 684Wide_Wide_Text_IO 685 686* Stream Pointer Positioning: Stream Pointer Positioning<3>. 687* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 688 689The GNAT Library 690 691* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 692* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 693* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 694* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 695* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 696* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 697* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 698* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 699* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 700* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 701* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 702* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 703* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 704* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 705* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 706* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 707* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 708* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 709* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 710* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 711* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 712* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 713* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 714* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 715* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 716* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 717* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 718* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 719* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. 720* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 721* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 722* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 723* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 724* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 725* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 726* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 727* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 728* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 729* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 730* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 731* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 732* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 733* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 734* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 735* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 736* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. 737* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 738* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 739* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 740* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 741* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 742* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 743* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 744* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 745* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 746* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 747* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 748* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 749* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 750* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 751* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 752* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 753* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 754* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 755* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 756* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 757* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 758* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 759* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 760* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 761* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 762* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 763* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 764* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 765* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 766* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 767* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 768* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 769* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 770* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 771* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 772* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 773* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 774* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 775* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 776* GNAT.IO (g-io.ads): GNAT IO g-io ads. 777* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 778* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 779* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 780* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 781* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 782* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 783* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 784* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 785* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 786* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 787* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 788* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 789* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 790* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 791* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 792* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 793* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 794* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 795* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 796* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 797* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 798* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 799* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 800* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 801* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 802* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 803* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 804* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 805* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 806* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 807* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 808* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 809* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 810* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 811* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 812* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 813* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 814* GNAT.Table (g-table.ads): GNAT Table g-table ads. 815* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 816* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 817* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 818* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 819* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 820* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 821* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 822* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 823* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 824* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 825* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 826* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 827* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 828* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 829* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 830* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 831* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 832* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 833* System.Assertions (s-assert.ads): System Assertions s-assert ads. 834* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 835* System.Memory (s-memory.ads): System Memory s-memory ads. 836* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 837* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 838* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 839* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 840* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 841* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 842* System.Rident (s-rident.ads): System Rident s-rident ads. 843* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 844* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 845* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 846* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 847 848Interfacing to Other Languages 849 850* Interfacing to C:: 851* Interfacing to C++:: 852* Interfacing to COBOL:: 853* Interfacing to Fortran:: 854* Interfacing to non-GNAT Ada code:: 855 856Implementation of Specific Ada Features 857 858* Machine Code Insertions:: 859* GNAT Implementation of Tasking:: 860* GNAT Implementation of Shared Passive Packages:: 861* Code Generation for Array Aggregates:: 862* The Size of Discriminated Records with Default Discriminants:: 863* Strict Conformance to the Ada Reference Manual:: 864 865GNAT Implementation of Tasking 866 867* Mapping Ada Tasks onto the Underlying Kernel Threads:: 868* Ensuring Compliance with the Real-Time Annex:: 869* Support for Locking Policies:: 870 871Code Generation for Array Aggregates 872 873* Static constant aggregates with static bounds:: 874* Constant aggregates with unconstrained nominal types:: 875* Aggregates with static bounds:: 876* Aggregates with nonstatic bounds:: 877* Aggregates in assignment statements:: 878 879Obsolescent Features 880 881* pragma No_Run_Time:: 882* pragma Ravenscar:: 883* pragma Restricted_Run_Time:: 884* pragma Task_Info:: 885* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 886 887Compatibility and Porting Guide 888 889* Writing Portable Fixed-Point Declarations:: 890* Compatibility with Ada 83:: 891* Compatibility between Ada 95 and Ada 2005:: 892* Implementation-dependent characteristics:: 893* Compatibility with Other Ada Systems:: 894* Representation Clauses:: 895* Compatibility with HP Ada 83:: 896 897Compatibility with Ada 83 898 899* Legal Ada 83 programs that are illegal in Ada 95:: 900* More deterministic semantics:: 901* Changed semantics:: 902* Other language compatibility issues:: 903 904Implementation-dependent characteristics 905 906* Implementation-defined pragmas:: 907* Implementation-defined attributes:: 908* Libraries:: 909* Elaboration order:: 910* Target-specific aspects:: 911 912@end detailmenu 913@end menu 914 915@node About This Guide,Implementation Defined Pragmas,Top,Top 916@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} 917@chapter About This Guide 918 919 920 921This manual contains useful information in writing programs using the 922GNAT compiler. It includes information on implementation dependent 923characteristics of GNAT, including all the information required by 924Annex M of the Ada language standard. 925 926GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be 927invoked in Ada 83 compatibility mode. 928By default, GNAT assumes Ada 2012, 929but you can override with a compiler switch 930to explicitly specify the language version. 931(Please refer to the @emph{GNAT User's Guide} for details on these switches.) 932Throughout this manual, references to 'Ada' without a year suffix 933apply to all the Ada versions of the language. 934 935Ada is designed to be highly portable. 936In general, a program will have the same effect even when compiled by 937different compilers on different platforms. 938However, since Ada is designed to be used in a 939wide variety of applications, it also contains a number of system 940dependent features to be used in interfacing to the external world. 941 942@geindex Implementation-dependent features 943 944@geindex Portability 945 946Note: Any program that makes use of implementation-dependent features 947may be non-portable. You should follow good programming practice and 948isolate and clearly document any sections of your program that make use 949of these features in a non-portable manner. 950 951@menu 952* What This Reference Manual Contains:: 953* Conventions:: 954* Related Information:: 955 956@end menu 957 958@node What This Reference Manual Contains,Conventions,,About This Guide 959@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} 960@section What This Reference Manual Contains 961 962 963This reference manual contains the following chapters: 964 965 966@itemize * 967 968@item 969@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent 970pragmas, which can be used to extend and enhance the functionality of the 971compiler. 972 973@item 974@ref{8,,Implementation Defined Attributes}, lists GNAT 975implementation-dependent attributes, which can be used to extend and 976enhance the functionality of the compiler. 977 978@item 979@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT 980implementation-dependent restrictions, which can be used to extend and 981enhance the functionality of the compiler. 982 983@item 984@ref{a,,Implementation Advice}, provides information on generally 985desirable behavior which are not requirements that all compilers must 986follow since it cannot be provided on all systems, or which may be 987undesirable on some systems. 988 989@item 990@ref{b,,Implementation Defined Characteristics}, provides a guide to 991minimizing implementation dependent features. 992 993@item 994@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms 995implemented by GNAT, and how they can be imported into user 996application programs. 997 998@item 999@ref{d,,Representation Clauses and Pragmas}, describes in detail the 1000way that GNAT represents data, and in particular the exact set 1001of representation clauses and pragmas that is accepted. 1002 1003@item 1004@ref{e,,Standard Library Routines}, provides a listing of packages and a 1005brief description of the functionality that is provided by Ada's 1006extensive set of standard library routines as implemented by GNAT. 1007 1008@item 1009@ref{f,,The Implementation of Standard I/O}, details how the GNAT 1010implementation of the input-output facilities. 1011 1012@item 1013@ref{10,,The GNAT Library}, is a catalog of packages that complement 1014the Ada predefined library. 1015 1016@item 1017@ref{11,,Interfacing to Other Languages}, describes how programs 1018written in Ada using GNAT can be interfaced to other programming 1019languages. 1020 1021@item 1022@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all 1023of the specialized needs annexes. 1024 1025@item 1026@ref{13,,Implementation of Specific Ada Features}, discusses issues related 1027to GNAT's implementation of machine code insertions, tasking, and several 1028other features. 1029 1030@item 1031@ref{14,,Implementation of Ada 2012 Features}, describes the status of the 1032GNAT implementation of the Ada 2012 language standard. 1033 1034@item 1035@ref{15,,Obsolescent Features} documents implementation dependent features, 1036including pragmas and attributes, which are considered obsolescent, since 1037there are other preferred ways of achieving the same results. These 1038obsolescent forms are retained for backwards compatibility. 1039 1040@item 1041@ref{16,,Compatibility and Porting Guide} presents some guidelines for 1042developing portable Ada code, describes the compatibility issues that 1043may arise between GNAT and other Ada compilation systems (including those 1044for Ada 83), and shows how GNAT can expedite porting applications 1045developed in other Ada environments. 1046 1047@item 1048@ref{1,,GNU Free Documentation License} contains the license for this document. 1049@end itemize 1050 1051@geindex Ada 95 Language Reference Manual 1052 1053@geindex Ada 2005 Language Reference Manual 1054 1055This reference manual assumes a basic familiarity with the Ada 95 language, as 1056described in the 1057@cite{International Standard ANSI/ISO/IEC-8652:1995}. 1058It does not require knowledge of the new features introduced by Ada 2005 or 1059Ada 2012. 1060All three reference manuals are included in the GNAT documentation 1061package. 1062 1063@node Conventions,Related Information,What This Reference Manual Contains,About This Guide 1064@anchor{gnat_rm/about_this_guide conventions}@anchor{17} 1065@section Conventions 1066 1067 1068@geindex Conventions 1069@geindex typographical 1070 1071@geindex Typographical conventions 1072 1073Following are examples of the typographical and graphic conventions used 1074in this guide: 1075 1076 1077@itemize * 1078 1079@item 1080@code{Functions}, @code{utility program names}, @code{standard names}, 1081and @code{classes}. 1082 1083@item 1084@code{Option flags} 1085 1086@item 1087@code{File names} 1088 1089@item 1090@code{Variables} 1091 1092@item 1093@emph{Emphasis} 1094 1095@item 1096[optional information or parameters] 1097 1098@item 1099Examples are described by text 1100 1101@example 1102and then shown this way. 1103@end example 1104 1105@item 1106Commands that are entered by the user are shown as preceded by a prompt string 1107comprising the @code{$} character followed by a space. 1108@end itemize 1109 1110@node Related Information,,Conventions,About This Guide 1111@anchor{gnat_rm/about_this_guide related-information}@anchor{18} 1112@section Related Information 1113 1114 1115See the following documents for further information on GNAT: 1116 1117 1118@itemize * 1119 1120@item 1121@cite{GNAT User's Guide for Native Platforms}, 1122which provides information on how to use the 1123GNAT development environment. 1124 1125@item 1126@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. 1127 1128@item 1129@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 1130of the Ada 95 standard. The annotations describe 1131detailed aspects of the design decision, and in particular contain useful 1132sections on Ada 83 compatibility. 1133 1134@item 1135@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. 1136 1137@item 1138@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version 1139of the Ada 2005 standard. The annotations describe 1140detailed aspects of the design decision. 1141 1142@item 1143@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. 1144 1145@item 1146@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, 1147which contains specific information on compatibility between GNAT and 1148DEC Ada 83 systems. 1149 1150@item 1151@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which 1152describes in detail the pragmas and attributes provided by the DEC Ada 83 1153compiler system. 1154@end itemize 1155 1156@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top 1157@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} 1158@chapter Implementation Defined Pragmas 1159 1160 1161Ada defines a set of pragmas that can be used to supply additional 1162information to the compiler. These language defined pragmas are 1163implemented in GNAT and work as described in the Ada Reference Manual. 1164 1165In addition, Ada allows implementations to define additional pragmas 1166whose meaning is defined by the implementation. GNAT provides a number 1167of these implementation-defined pragmas, which can be used to extend 1168and enhance the functionality of the compiler. This section of the GNAT 1169Reference Manual describes these additional pragmas. 1170 1171Note that any program using these pragmas might not be portable to other 1172compilers (although GNAT implements this set of pragmas on all 1173platforms). Therefore if portability to other compilers is an important 1174consideration, the use of these pragmas should be minimized. 1175 1176@menu 1177* Pragma Abort_Defer:: 1178* Pragma Abstract_State:: 1179* Pragma Ada_83:: 1180* Pragma Ada_95:: 1181* Pragma Ada_05:: 1182* Pragma Ada_2005:: 1183* Pragma Ada_12:: 1184* Pragma Ada_2012:: 1185* Pragma Aggregate_Individually_Assign:: 1186* Pragma Allow_Integer_Address:: 1187* Pragma Annotate:: 1188* Pragma Assert:: 1189* Pragma Assert_And_Cut:: 1190* Pragma Assertion_Policy:: 1191* Pragma Assume:: 1192* Pragma Assume_No_Invalid_Values:: 1193* Pragma Async_Readers:: 1194* Pragma Async_Writers:: 1195* Pragma Attribute_Definition:: 1196* Pragma C_Pass_By_Copy:: 1197* Pragma Check:: 1198* Pragma Check_Float_Overflow:: 1199* Pragma Check_Name:: 1200* Pragma Check_Policy:: 1201* Pragma Comment:: 1202* Pragma Common_Object:: 1203* Pragma Compile_Time_Error:: 1204* Pragma Compile_Time_Warning:: 1205* Pragma Compiler_Unit:: 1206* Pragma Compiler_Unit_Warning:: 1207* Pragma Complete_Representation:: 1208* Pragma Complex_Representation:: 1209* Pragma Component_Alignment:: 1210* Pragma Constant_After_Elaboration:: 1211* Pragma Contract_Cases:: 1212* Pragma Convention_Identifier:: 1213* Pragma CPP_Class:: 1214* Pragma CPP_Constructor:: 1215* Pragma CPP_Virtual:: 1216* Pragma CPP_Vtable:: 1217* Pragma CPU:: 1218* Pragma Deadline_Floor:: 1219* Pragma Default_Initial_Condition:: 1220* Pragma Debug:: 1221* Pragma Debug_Policy:: 1222* Pragma Default_Scalar_Storage_Order:: 1223* Pragma Default_Storage_Pool:: 1224* Pragma Depends:: 1225* Pragma Detect_Blocking:: 1226* Pragma Disable_Atomic_Synchronization:: 1227* Pragma Dispatching_Domain:: 1228* Pragma Effective_Reads:: 1229* Pragma Effective_Writes:: 1230* Pragma Elaboration_Checks:: 1231* Pragma Eliminate:: 1232* Pragma Enable_Atomic_Synchronization:: 1233* Pragma Export_Function:: 1234* Pragma Export_Object:: 1235* Pragma Export_Procedure:: 1236* Pragma Export_Value:: 1237* Pragma Export_Valued_Procedure:: 1238* Pragma Extend_System:: 1239* Pragma Extensions_Allowed:: 1240* Pragma Extensions_Visible:: 1241* Pragma External:: 1242* Pragma External_Name_Casing:: 1243* Pragma Fast_Math:: 1244* Pragma Favor_Top_Level:: 1245* Pragma Finalize_Storage_Only:: 1246* Pragma Float_Representation:: 1247* Pragma Ghost:: 1248* Pragma Global:: 1249* Pragma Ident:: 1250* Pragma Ignore_Pragma:: 1251* Pragma Implementation_Defined:: 1252* Pragma Implemented:: 1253* Pragma Implicit_Packing:: 1254* Pragma Import_Function:: 1255* Pragma Import_Object:: 1256* Pragma Import_Procedure:: 1257* Pragma Import_Valued_Procedure:: 1258* Pragma Independent:: 1259* Pragma Independent_Components:: 1260* Pragma Initial_Condition:: 1261* Pragma Initialize_Scalars:: 1262* Pragma Initializes:: 1263* Pragma Inline_Always:: 1264* Pragma Inline_Generic:: 1265* Pragma Interface:: 1266* Pragma Interface_Name:: 1267* Pragma Interrupt_Handler:: 1268* Pragma Interrupt_State:: 1269* Pragma Invariant:: 1270* Pragma Keep_Names:: 1271* Pragma License:: 1272* Pragma Link_With:: 1273* Pragma Linker_Alias:: 1274* Pragma Linker_Constructor:: 1275* Pragma Linker_Destructor:: 1276* Pragma Linker_Section:: 1277* Pragma Lock_Free:: 1278* Pragma Loop_Invariant:: 1279* Pragma Loop_Optimize:: 1280* Pragma Loop_Variant:: 1281* Pragma Machine_Attribute:: 1282* Pragma Main:: 1283* Pragma Main_Storage:: 1284* Pragma Max_Queue_Length:: 1285* Pragma No_Body:: 1286* Pragma No_Caching:: 1287* Pragma No_Component_Reordering:: 1288* Pragma No_Elaboration_Code_All:: 1289* Pragma No_Heap_Finalization:: 1290* Pragma No_Inline:: 1291* Pragma No_Return:: 1292* Pragma No_Strict_Aliasing:: 1293* Pragma No_Tagged_Streams:: 1294* Pragma Normalize_Scalars:: 1295* Pragma Obsolescent:: 1296* Pragma Optimize_Alignment:: 1297* Pragma Ordered:: 1298* Pragma Overflow_Mode:: 1299* Pragma Overriding_Renamings:: 1300* Pragma Partition_Elaboration_Policy:: 1301* Pragma Part_Of:: 1302* Pragma Passive:: 1303* Pragma Persistent_BSS:: 1304* Pragma Post:: 1305* Pragma Postcondition:: 1306* Pragma Post_Class:: 1307* Pragma Rename_Pragma:: 1308* Pragma Pre:: 1309* Pragma Precondition:: 1310* Pragma Predicate:: 1311* Pragma Predicate_Failure:: 1312* Pragma Preelaborable_Initialization:: 1313* Pragma Prefix_Exception_Messages:: 1314* Pragma Pre_Class:: 1315* Pragma Priority_Specific_Dispatching:: 1316* Pragma Profile:: 1317* Pragma Profile_Warnings:: 1318* Pragma Propagate_Exceptions:: 1319* Pragma Provide_Shift_Operators:: 1320* Pragma Psect_Object:: 1321* Pragma Pure_Function:: 1322* Pragma Rational:: 1323* Pragma Ravenscar:: 1324* Pragma Refined_Depends:: 1325* Pragma Refined_Global:: 1326* Pragma Refined_Post:: 1327* Pragma Refined_State:: 1328* Pragma Relative_Deadline:: 1329* Pragma Remote_Access_Type:: 1330* Pragma Restricted_Run_Time:: 1331* Pragma Restriction_Warnings:: 1332* Pragma Reviewable:: 1333* Pragma Secondary_Stack_Size:: 1334* Pragma Share_Generic:: 1335* Pragma Shared:: 1336* Pragma Short_Circuit_And_Or:: 1337* Pragma Short_Descriptors:: 1338* Pragma Simple_Storage_Pool_Type:: 1339* Pragma Source_File_Name:: 1340* Pragma Source_File_Name_Project:: 1341* Pragma Source_Reference:: 1342* Pragma SPARK_Mode:: 1343* Pragma Static_Elaboration_Desired:: 1344* Pragma Stream_Convert:: 1345* Pragma Style_Checks:: 1346* Pragma Subtitle:: 1347* Pragma Suppress:: 1348* Pragma Suppress_All:: 1349* Pragma Suppress_Debug_Info:: 1350* Pragma Suppress_Exception_Locations:: 1351* Pragma Suppress_Initialization:: 1352* Pragma Task_Name:: 1353* Pragma Task_Storage:: 1354* Pragma Test_Case:: 1355* Pragma Thread_Local_Storage:: 1356* Pragma Time_Slice:: 1357* Pragma Title:: 1358* Pragma Type_Invariant:: 1359* Pragma Type_Invariant_Class:: 1360* Pragma Unchecked_Union:: 1361* Pragma Unevaluated_Use_Of_Old:: 1362* Pragma Unimplemented_Unit:: 1363* Pragma Universal_Aliasing:: 1364* Pragma Universal_Data:: 1365* Pragma Unmodified:: 1366* Pragma Unreferenced:: 1367* Pragma Unreferenced_Objects:: 1368* Pragma Unreserve_All_Interrupts:: 1369* Pragma Unsuppress:: 1370* Pragma Use_VADS_Size:: 1371* Pragma Unused:: 1372* Pragma Validity_Checks:: 1373* Pragma Volatile:: 1374* Pragma Volatile_Full_Access:: 1375* Pragma Volatile_Function:: 1376* Pragma Warning_As_Error:: 1377* Pragma Warnings:: 1378* Pragma Weak_External:: 1379* Pragma Wide_Character_Encoding:: 1380 1381@end menu 1382 1383@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas 1384@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1b} 1385@section Pragma Abort_Defer 1386 1387 1388@geindex Deferring aborts 1389 1390Syntax: 1391 1392@example 1393pragma Abort_Defer; 1394@end example 1395 1396This pragma must appear at the start of the statement sequence of a 1397handled sequence of statements (right after the @code{begin}). It has 1398the effect of deferring aborts for the sequence of statements (but not 1399for the declarations or handlers, if any, associated with this statement 1400sequence). This can also be useful for adding a polling point in Ada code, 1401where asynchronous abort of tasks is checked when leaving the statement 1402sequence, and is lighter than, for example, using @code{delay 0.0;}, since with 1403zero-cost exception handling, propagating exceptions (implicitly used to 1404implement task abort) cannot be done reliably in an asynchronous way. 1405 1406An example of usage would be: 1407 1408@example 1409-- Add a polling point to check for task aborts 1410 1411begin 1412 pragma Abort_Defer; 1413end; 1414@end example 1415 1416@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas 1417@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1c}@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d} 1418@section Pragma Abstract_State 1419 1420 1421Syntax: 1422 1423@example 1424pragma Abstract_State (ABSTRACT_STATE_LIST); 1425 1426ABSTRACT_STATE_LIST ::= 1427 null 1428 | STATE_NAME_WITH_OPTIONS 1429 | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) 1430 1431STATE_NAME_WITH_OPTIONS ::= 1432 STATE_NAME 1433 | (STATE_NAME with OPTION_LIST) 1434 1435OPTION_LIST ::= OPTION @{, OPTION@} 1436 1437OPTION ::= 1438 SIMPLE_OPTION 1439 | NAME_VALUE_OPTION 1440 1441SIMPLE_OPTION ::= Ghost | Synchronous 1442 1443NAME_VALUE_OPTION ::= 1444 Part_Of => ABSTRACT_STATE 1445 | External [=> EXTERNAL_PROPERTY_LIST] 1446 1447EXTERNAL_PROPERTY_LIST ::= 1448 EXTERNAL_PROPERTY 1449 | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) 1450 1451EXTERNAL_PROPERTY ::= 1452 Async_Readers [=> boolean_EXPRESSION] 1453 | Async_Writers [=> boolean_EXPRESSION] 1454 | Effective_Reads [=> boolean_EXPRESSION] 1455 | Effective_Writes [=> boolean_EXPRESSION] 1456 others => boolean_EXPRESSION 1457 1458STATE_NAME ::= defining_identifier 1459 1460ABSTRACT_STATE ::= name 1461@end example 1462 1463For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in 1464the SPARK 2014 Reference Manual, section 7.1.4. 1465 1466@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas 1467@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1e} 1468@section Pragma Ada_83 1469 1470 1471Syntax: 1472 1473@example 1474pragma Ada_83; 1475@end example 1476 1477A configuration pragma that establishes Ada 83 mode for the unit to 1478which it applies, regardless of the mode set by the command line 1479switches. In Ada 83 mode, GNAT attempts to be as compatible with 1480the syntax and semantics of Ada 83, as defined in the original Ada 148183 Reference Manual as possible. In particular, the keywords added by Ada 95 1482and Ada 2005 are not recognized, optional package bodies are allowed, 1483and generics may name types with unknown discriminants without using 1484the @code{(<>)} notation. In addition, some but not all of the additional 1485restrictions of Ada 83 are enforced. 1486 1487Ada 83 mode is intended for two purposes. Firstly, it allows existing 1488Ada 83 code to be compiled and adapted to GNAT with less effort. 1489Secondly, it aids in keeping code backwards compatible with Ada 83. 1490However, there is no guarantee that code that is processed correctly 1491by GNAT in Ada 83 mode will in fact compile and execute with an Ada 149283 compiler, since GNAT does not enforce all the additional checks 1493required by Ada 83. 1494 1495@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas 1496@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{1f} 1497@section Pragma Ada_95 1498 1499 1500Syntax: 1501 1502@example 1503pragma Ada_95; 1504@end example 1505 1506A configuration pragma that establishes Ada 95 mode for the unit to which 1507it applies, regardless of the mode set by the command line switches. 1508This mode is set automatically for the @code{Ada} and @code{System} 1509packages and their children, so you need not specify it in these 1510contexts. This pragma is useful when writing a reusable component that 1511itself uses Ada 95 features, but which is intended to be usable from 1512either Ada 83 or Ada 95 programs. 1513 1514@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas 1515@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{20} 1516@section Pragma Ada_05 1517 1518 1519Syntax: 1520 1521@example 1522pragma Ada_05; 1523pragma Ada_05 (local_NAME); 1524@end example 1525 1526A configuration pragma that establishes Ada 2005 mode for the unit to which 1527it applies, regardless of the mode set by the command line switches. 1528This pragma is useful when writing a reusable component that 1529itself uses Ada 2005 features, but which is intended to be usable from 1530either Ada 83 or Ada 95 programs. 1531 1532The one argument form (which is not a configuration pragma) 1533is used for managing the transition from 1534Ada 95 to Ada 2005 in the run-time library. If an entity is marked 1535as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 1536mode will generate a warning. In addition, in Ada_83 or Ada_95 1537mode, a preference rule is established which does not choose 1538such an entity unless it is unambiguously specified. This avoids 1539extra subprograms marked this way from generating ambiguities in 1540otherwise legal pre-Ada_2005 programs. The one argument form is 1541intended for exclusive use in the GNAT run-time library. 1542 1543@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas 1544@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{21} 1545@section Pragma Ada_2005 1546 1547 1548Syntax: 1549 1550@example 1551pragma Ada_2005; 1552@end example 1553 1554This configuration pragma is a synonym for pragma Ada_05 and has the 1555same syntax and effect. 1556 1557@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas 1558@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{22} 1559@section Pragma Ada_12 1560 1561 1562Syntax: 1563 1564@example 1565pragma Ada_12; 1566pragma Ada_12 (local_NAME); 1567@end example 1568 1569A configuration pragma that establishes Ada 2012 mode for the unit to which 1570it applies, regardless of the mode set by the command line switches. 1571This mode is set automatically for the @code{Ada} and @code{System} 1572packages and their children, so you need not specify it in these 1573contexts. This pragma is useful when writing a reusable component that 1574itself uses Ada 2012 features, but which is intended to be usable from 1575Ada 83, Ada 95, or Ada 2005 programs. 1576 1577The one argument form, which is not a configuration pragma, 1578is used for managing the transition from Ada 15792005 to Ada 2012 in the run-time library. If an entity is marked 1580as Ada_2012 only, then referencing the entity in any pre-Ada_2012 1581mode will generate a warning. In addition, in any pre-Ada_2012 1582mode, a preference rule is established which does not choose 1583such an entity unless it is unambiguously specified. This avoids 1584extra subprograms marked this way from generating ambiguities in 1585otherwise legal pre-Ada_2012 programs. The one argument form is 1586intended for exclusive use in the GNAT run-time library. 1587 1588@node Pragma Ada_2012,Pragma Aggregate_Individually_Assign,Pragma Ada_12,Implementation Defined Pragmas 1589@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{23} 1590@section Pragma Ada_2012 1591 1592 1593Syntax: 1594 1595@example 1596pragma Ada_2012; 1597@end example 1598 1599This configuration pragma is a synonym for pragma Ada_12 and has the 1600same syntax and effect. 1601 1602@node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2012,Implementation Defined Pragmas 1603@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{24} 1604@section Pragma Aggregate_Individually_Assign 1605 1606 1607Syntax: 1608 1609@example 1610pragma Aggregate_Individually_Assign; 1611@end example 1612 1613Where possible, GNAT will store the binary representation of a record aggregate 1614in memory for space and performance reasons. This configuration pragma changes 1615this behavior so that record aggregates are instead always converted into 1616individual assignment statements. 1617 1618@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas 1619@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{25} 1620@section Pragma Allow_Integer_Address 1621 1622 1623Syntax: 1624 1625@example 1626pragma Allow_Integer_Address; 1627@end example 1628 1629In almost all versions of GNAT, @code{System.Address} is a private 1630type in accordance with the implementation advice in the RM. This 1631means that integer values, 1632in particular integer literals, are not allowed as address values. 1633If the configuration pragma 1634@code{Allow_Integer_Address} is given, then integer expressions may 1635be used anywhere a value of type @code{System.Address} is required. 1636The effect is to introduce an implicit unchecked conversion from the 1637integer value to type @code{System.Address}. The reverse case of using 1638an address where an integer type is required is handled analogously. 1639The following example compiles without errors: 1640 1641@example 1642pragma Allow_Integer_Address; 1643with System; use System; 1644package AddrAsInt is 1645 X : Integer; 1646 Y : Integer; 1647 for X'Address use 16#1240#; 1648 for Y use at 16#3230#; 1649 m : Address := 16#4000#; 1650 n : constant Address := 4000; 1651 p : constant Address := Address (X + Y); 1652 v : Integer := y'Address; 1653 w : constant Integer := Integer (Y'Address); 1654 type R is new integer; 1655 RR : R := 1000; 1656 Z : Integer; 1657 for Z'Address use RR; 1658end AddrAsInt; 1659@end example 1660 1661Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} 1662is not a private type. In implementations of @code{GNAT} where 1663System.Address is a visible integer type, 1664this pragma serves no purpose but is ignored 1665rather than rejected to allow common sets of sources to be used 1666in the two situations. 1667 1668@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas 1669@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{26}@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{27} 1670@section Pragma Annotate 1671 1672 1673Syntax: 1674 1675@example 1676pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); 1677 1678ARG ::= NAME | EXPRESSION 1679@end example 1680 1681This pragma is used to annotate programs. IDENTIFIER identifies 1682the type of annotation. GNAT verifies that it is an identifier, but does 1683not otherwise analyze it. The second optional identifier is also left 1684unanalyzed, and by convention is used to control the action of the tool to 1685which the annotation is addressed. The remaining ARG arguments 1686can be either string literals or more generally expressions. 1687String literals (and concatenations of string literals) are assumed to be 1688either of type 1689@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} 1690depending on the character literals they contain. 1691All other kinds of arguments are analyzed as expressions, and must be 1692unambiguous. The last argument if present must have the identifier 1693@code{Entity} and GNAT verifies that a local name is given. 1694 1695The analyzed pragma is retained in the tree, but not otherwise processed 1696by any part of the GNAT compiler, except to generate corresponding note 1697lines in the generated ALI file. For the format of these note lines, see 1698the compiler source file lib-writ.ads. This pragma is intended for use by 1699external tools, including ASIS. The use of pragma Annotate does not 1700affect the compilation process in any way. This pragma may be used as 1701a configuration pragma. 1702 1703@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas 1704@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{28} 1705@section Pragma Assert 1706 1707 1708Syntax: 1709 1710@example 1711pragma Assert ( 1712 boolean_EXPRESSION 1713 [, string_EXPRESSION]); 1714@end example 1715 1716The effect of this pragma depends on whether the corresponding command 1717line switch is set to activate assertions. The pragma expands into code 1718equivalent to the following: 1719 1720@example 1721if assertions-enabled then 1722 if not boolean_EXPRESSION then 1723 System.Assertions.Raise_Assert_Failure 1724 (string_EXPRESSION); 1725 end if; 1726end if; 1727@end example 1728 1729The string argument, if given, is the message that will be associated 1730with the exception occurrence if the exception is raised. If no second 1731argument is given, the default message is @code{file}:@code{nnn}, 1732where @code{file} is the name of the source file containing the assert, 1733and @code{nnn} is the line number of the assert. 1734 1735Note that, as with the @code{if} statement to which it is equivalent, the 1736type of the expression is either @code{Standard.Boolean}, or any type derived 1737from this standard type. 1738 1739Assert checks can be either checked or ignored. By default they are ignored. 1740They will be checked if either the command line switch @emph{-gnata} is 1741used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used 1742to enable @code{Assert_Checks}. 1743 1744If assertions are ignored, then there 1745is no run-time effect (and in particular, any side effects from the 1746expression will not occur at run time). (The expression is still 1747analyzed at compile time, and may cause types to be frozen if they are 1748mentioned here for the first time). 1749 1750If assertions are checked, then the given expression is tested, and if 1751it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called 1752which results in the raising of @code{Assert_Failure} with the given message. 1753 1754You should generally avoid side effects in the expression arguments of 1755this pragma, because these side effects will turn on and off with the 1756setting of the assertions mode, resulting in assertions that have an 1757effect on the program. However, the expressions are analyzed for 1758semantic correctness whether or not assertions are enabled, so turning 1759assertions on and off cannot affect the legality of a program. 1760 1761Note that the implementation defined policy @code{DISABLE}, given in a 1762pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. 1763 1764Note: this is a standard language-defined pragma in versions 1765of Ada from 2005 on. In GNAT, it is implemented in all versions 1766of Ada, and the DISABLE policy is an implementation-defined 1767addition. 1768 1769@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas 1770@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{29} 1771@section Pragma Assert_And_Cut 1772 1773 1774Syntax: 1775 1776@example 1777pragma Assert_And_Cut ( 1778 boolean_EXPRESSION 1779 [, string_EXPRESSION]); 1780@end example 1781 1782The effect of this pragma is identical to that of pragma @code{Assert}, 1783except that in an @code{Assertion_Policy} pragma, the identifier 1784@code{Assert_And_Cut} is used to control whether it is ignored or checked 1785(or disabled). 1786 1787The intention is that this be used within a subprogram when the 1788given test expresion sums up all the work done so far in the 1789subprogram, so that the rest of the subprogram can be verified 1790(informally or formally) using only the entry preconditions, 1791and the expression in this pragma. This allows dividing up 1792a subprogram into sections for the purposes of testing or 1793formal verification. The pragma also serves as useful 1794documentation. 1795 1796@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas 1797@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2a} 1798@section Pragma Assertion_Policy 1799 1800 1801Syntax: 1802 1803@example 1804pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); 1805 1806pragma Assertion_Policy ( 1807 ASSERTION_KIND => POLICY_IDENTIFIER 1808 @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); 1809 1810ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 1811 1812RM_ASSERTION_KIND ::= Assert | 1813 Static_Predicate | 1814 Dynamic_Predicate | 1815 Pre | 1816 Pre'Class | 1817 Post | 1818 Post'Class | 1819 Type_Invariant | 1820 Type_Invariant'Class | 1821 Default_Initial_Condition 1822 1823ID_ASSERTION_KIND ::= Assertions | 1824 Assert_And_Cut | 1825 Assume | 1826 Contract_Cases | 1827 Debug | 1828 Ghost | 1829 Initial_Condition | 1830 Invariant | 1831 Invariant'Class | 1832 Loop_Invariant | 1833 Loop_Variant | 1834 Postcondition | 1835 Precondition | 1836 Predicate | 1837 Refined_Post | 1838 Statement_Assertions | 1839 Subprogram_Variant 1840 1841POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible 1842@end example 1843 1844This is a standard Ada 2012 pragma that is available as an 1845implementation-defined pragma in earlier versions of Ada. 1846The assertion kinds @code{RM_ASSERTION_KIND} are those defined in 1847the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} 1848are implementation defined additions recognized by the GNAT compiler. 1849 1850The pragma applies in both cases to pragmas and aspects with matching 1851names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} 1852applies to both the @code{Precondition} pragma 1853and the aspect @code{Precondition}. Note that the identifiers for 1854pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not 1855Pre_Class and Post_Class), since these pragmas are intended to be 1856identical to the corresponding aspects). 1857 1858If the policy is @code{CHECK}, then assertions are enabled, i.e. 1859the corresponding pragma or aspect is activated. 1860If the policy is @code{IGNORE}, then assertions are ignored, i.e. 1861the corresponding pragma or aspect is deactivated. 1862This pragma overrides the effect of the @emph{-gnata} switch on the 1863command line. 1864If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, 1865however, if the @emph{-gnatp} switch is specified all assertions are ignored. 1866 1867The implementation defined policy @code{DISABLE} is like 1868@code{IGNORE} except that it completely disables semantic 1869checking of the corresponding pragma or aspect. This is 1870useful when the pragma or aspect argument references subprograms 1871in a with'ed package which is replaced by a dummy package 1872for the final build. 1873 1874The implementation defined assertion kind @code{Assertions} applies to all 1875assertion kinds. The form with no assertion kind given implies this 1876choice, so it applies to all assertion kinds (RM defined, and 1877implementation defined). 1878 1879The implementation defined assertion kind @code{Statement_Assertions} 1880applies to @code{Assert}, @code{Assert_And_Cut}, 1881@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. 1882 1883@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas 1884@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2b} 1885@section Pragma Assume 1886 1887 1888Syntax: 1889 1890@example 1891pragma Assume ( 1892 boolean_EXPRESSION 1893 [, string_EXPRESSION]); 1894@end example 1895 1896The effect of this pragma is identical to that of pragma @code{Assert}, 1897except that in an @code{Assertion_Policy} pragma, the identifier 1898@code{Assume} is used to control whether it is ignored or checked 1899(or disabled). 1900 1901The intention is that this be used for assumptions about the 1902external environment. So you cannot expect to verify formally 1903or informally that the condition is met, this must be 1904established by examining things outside the program itself. 1905For example, we may have code that depends on the size of 1906@code{Long_Long_Integer} being at least 64. So we could write: 1907 1908@example 1909pragma Assume (Long_Long_Integer'Size >= 64); 1910@end example 1911 1912This assumption cannot be proved from the program itself, 1913but it acts as a useful run-time check that the assumption 1914is met, and documents the need to ensure that it is met by 1915reference to information outside the program. 1916 1917@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas 1918@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2c} 1919@section Pragma Assume_No_Invalid_Values 1920 1921 1922@geindex Invalid representations 1923 1924@geindex Invalid values 1925 1926Syntax: 1927 1928@example 1929pragma Assume_No_Invalid_Values (On | Off); 1930@end example 1931 1932This is a configuration pragma that controls the assumptions made by the 1933compiler about the occurrence of invalid representations (invalid values) 1934in the code. 1935 1936The default behavior (corresponding to an Off argument for this pragma), is 1937to assume that values may in general be invalid unless the compiler can 1938prove they are valid. Consider the following example: 1939 1940@example 1941V1 : Integer range 1 .. 10; 1942V2 : Integer range 11 .. 20; 1943... 1944for J in V2 .. V1 loop 1945 ... 1946end loop; 1947@end example 1948 1949if V1 and V2 have valid values, then the loop is known at compile 1950time not to execute since the lower bound must be greater than the 1951upper bound. However in default mode, no such assumption is made, 1952and the loop may execute. If @code{Assume_No_Invalid_Values (On)} 1953is given, the compiler will assume that any occurrence of a variable 1954other than in an explicit @code{'Valid} test always has a valid 1955value, and the loop above will be optimized away. 1956 1957The use of @code{Assume_No_Invalid_Values (On)} is appropriate if 1958you know your code is free of uninitialized variables and other 1959possible sources of invalid representations, and may result in 1960more efficient code. A program that accesses an invalid representation 1961with this pragma in effect is erroneous, so no guarantees can be made 1962about its behavior. 1963 1964It is peculiar though permissible to use this pragma in conjunction 1965with validity checking (-gnatVa). In such cases, accessing invalid 1966values will generally give an exception, though formally the program 1967is erroneous so there are no guarantees that this will always be the 1968case, and it is recommended that these two options not be used together. 1969 1970@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas 1971@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{2d}@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2e} 1972@section Pragma Async_Readers 1973 1974 1975Syntax: 1976 1977@example 1978pragma Async_Readers [ (boolean_EXPRESSION) ]; 1979@end example 1980 1981For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in 1982the SPARK 2014 Reference Manual, section 7.1.2. 1983 1984@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas 1985@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{2f}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{30} 1986@section Pragma Async_Writers 1987 1988 1989Syntax: 1990 1991@example 1992pragma Async_Writers [ (boolean_EXPRESSION) ]; 1993@end example 1994 1995For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in 1996the SPARK 2014 Reference Manual, section 7.1.2. 1997 1998@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas 1999@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{31} 2000@section Pragma Attribute_Definition 2001 2002 2003Syntax: 2004 2005@example 2006pragma Attribute_Definition 2007 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 2008 [Entity =>] LOCAL_NAME, 2009 [Expression =>] EXPRESSION | NAME); 2010@end example 2011 2012If @code{Attribute} is a known attribute name, this pragma is equivalent to 2013the attribute definition clause: 2014 2015@example 2016for Entity'Attribute use Expression; 2017@end example 2018 2019If @code{Attribute} is not a recognized attribute name, the pragma is 2020ignored, and a warning is emitted. This allows source 2021code to be written that takes advantage of some new attribute, while remaining 2022compilable with earlier compilers. 2023 2024@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas 2025@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{32} 2026@section Pragma C_Pass_By_Copy 2027 2028 2029@geindex Passing by copy 2030 2031Syntax: 2032 2033@example 2034pragma C_Pass_By_Copy 2035 ([Max_Size =>] static_integer_EXPRESSION); 2036@end example 2037 2038Normally the default mechanism for passing C convention records to C 2039convention subprograms is to pass them by reference, as suggested by RM 2040B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change 2041this default, by requiring that record formal parameters be passed by 2042copy if all of the following conditions are met: 2043 2044 2045@itemize * 2046 2047@item 2048The size of the record type does not exceed the value specified for 2049@code{Max_Size}. 2050 2051@item 2052The record type has @code{Convention C}. 2053 2054@item 2055The formal parameter has this record type, and the subprogram has a 2056foreign (non-Ada) convention. 2057@end itemize 2058 2059If these conditions are met the argument is passed by copy; i.e., in a 2060manner consistent with what C expects if the corresponding formal in the 2061C prototype is a struct (rather than a pointer to a struct). 2062 2063You can also pass records by copy by specifying the convention 2064@code{C_Pass_By_Copy} for the record type, or by using the extended 2065@code{Import} and @code{Export} pragmas, which allow specification of 2066passing mechanisms on a parameter by parameter basis. 2067 2068@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas 2069@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{33} 2070@section Pragma Check 2071 2072 2073@geindex Assertions 2074 2075@geindex Named assertions 2076 2077Syntax: 2078 2079@example 2080pragma Check ( 2081 [Name =>] CHECK_KIND, 2082 [Check =>] Boolean_EXPRESSION 2083 [, [Message =>] string_EXPRESSION] ); 2084 2085CHECK_KIND ::= IDENTIFIER | 2086 Pre'Class | 2087 Post'Class | 2088 Type_Invariant'Class | 2089 Invariant'Class 2090@end example 2091 2092This pragma is similar to the predefined pragma @code{Assert} except that an 2093extra identifier argument is present. In conjunction with pragma 2094@code{Check_Policy}, this can be used to define groups of assertions that can 2095be independently controlled. The identifier @code{Assertion} is special, it 2096refers to the normal set of pragma @code{Assert} statements. 2097 2098Checks introduced by this pragma are normally deactivated by default. They can 2099be activated either by the command line option @emph{-gnata}, which turns on 2100all checks, or individually controlled using pragma @code{Check_Policy}. 2101 2102The identifiers @code{Assertions} and @code{Statement_Assertions} are not 2103permitted as check kinds, since this would cause confusion with the use 2104of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} 2105pragmas, where they are used to refer to sets of assertions. 2106 2107@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas 2108@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{34} 2109@section Pragma Check_Float_Overflow 2110 2111 2112@geindex Floating-point overflow 2113 2114Syntax: 2115 2116@example 2117pragma Check_Float_Overflow; 2118@end example 2119 2120In Ada, the predefined floating-point types (@code{Short_Float}, 2121@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are 2122defined to be @emph{unconstrained}. This means that even though each 2123has a well-defined base range, an operation that delivers a result 2124outside this base range is not required to raise an exception. 2125This implementation permission accommodates the notion 2126of infinities in IEEE floating-point, and corresponds to the 2127efficient execution mode on most machines. GNAT will not raise 2128overflow exceptions on these machines; instead it will generate 2129infinities and NaN's as defined in the IEEE standard. 2130 2131Generating infinities, although efficient, is not always desirable. 2132Often the preferable approach is to check for overflow, even at the 2133(perhaps considerable) expense of run-time performance. 2134This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit 2135range constraints -- and indeed such a subtype 2136can have the same base range as its base type. For example: 2137 2138@example 2139subtype My_Float is Float range Float'Range; 2140@end example 2141 2142Here @code{My_Float} has the same range as 2143@code{Float} but is constrained, so operations on 2144@code{My_Float} values will be checked for overflow 2145against this range. 2146 2147This style will achieve the desired goal, but 2148it is often more convenient to be able to simply use 2149the standard predefined floating-point types as long 2150as overflow checking could be guaranteed. 2151The @code{Check_Float_Overflow} 2152configuration pragma achieves this effect. If a unit is compiled 2153subject to this configuration pragma, then all operations 2154on predefined floating-point types including operations on 2155base types of these floating-point types will be treated as 2156though those types were constrained, and overflow checks 2157will be generated. The @code{Constraint_Error} 2158exception is raised if the result is out of range. 2159 2160This mode can also be set by use of the compiler 2161switch @emph{-gnateF}. 2162 2163@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas 2164@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{35} 2165@section Pragma Check_Name 2166 2167 2168@geindex Defining check names 2169 2170@geindex Check names 2171@geindex defining 2172 2173Syntax: 2174 2175@example 2176pragma Check_Name (check_name_IDENTIFIER); 2177@end example 2178 2179This is a configuration pragma that defines a new implementation 2180defined check name (unless IDENTIFIER matches one of the predefined 2181check names, in which case the pragma has no effect). Check names 2182are global to a partition, so if two or more configuration pragmas 2183are present in a partition mentioning the same name, only one new 2184check name is introduced. 2185 2186An implementation defined check name introduced with this pragma may 2187be used in only three contexts: @code{pragma Suppress}, 2188@code{pragma Unsuppress}, 2189and as the prefix of a @code{Check_Name'Enabled} attribute reference. For 2190any of these three cases, the check name must be visible. A check 2191name is visible if it is in the configuration pragmas applying to 2192the current unit, or if it appears at the start of any unit that 2193is part of the dependency set of the current unit (e.g., units that 2194are mentioned in @code{with} clauses). 2195 2196Check names introduced by this pragma are subject to control by compiler 2197switches (in particular -gnatp) in the usual manner. 2198 2199@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas 2200@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{36} 2201@section Pragma Check_Policy 2202 2203 2204@geindex Controlling assertions 2205 2206@geindex Assertions 2207@geindex control 2208 2209@geindex Check pragma control 2210 2211@geindex Named assertions 2212 2213Syntax: 2214 2215@example 2216pragma Check_Policy 2217 ([Name =>] CHECK_KIND, 2218 [Policy =>] POLICY_IDENTIFIER); 2219 2220pragma Check_Policy ( 2221 CHECK_KIND => POLICY_IDENTIFIER 2222 @{, CHECK_KIND => POLICY_IDENTIFIER@}); 2223 2224ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 2225 2226CHECK_KIND ::= IDENTIFIER | 2227 Pre'Class | 2228 Post'Class | 2229 Type_Invariant'Class | 2230 Invariant'Class 2231 2232The identifiers Name and Policy are not allowed as CHECK_KIND values. This 2233avoids confusion between the two possible syntax forms for this pragma. 2234 2235POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 2236@end example 2237 2238This pragma is used to set the checking policy for assertions (specified 2239by aspects or pragmas), the @code{Debug} pragma, or additional checks 2240to be checked using the @code{Check} pragma. It may appear either as 2241a configuration pragma, or within a declarative part of package. In the 2242latter case, it applies from the point where it appears to the end of 2243the declarative region (like pragma @code{Suppress}). 2244 2245The @code{Check_Policy} pragma is similar to the 2246predefined @code{Assertion_Policy} pragma, 2247and if the check kind corresponds to one of the assertion kinds that 2248are allowed by @code{Assertion_Policy}, then the effect is identical. 2249 2250If the first argument is Debug, then the policy applies to Debug pragmas, 2251disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or 2252@code{IGNORE}, and allowing them to execute with normal semantics if 2253the policy is @code{ON} or @code{CHECK}. In addition if the policy is 2254@code{DISABLE}, then the procedure call in @code{Debug} pragmas will 2255be totally ignored and not analyzed semantically. 2256 2257Finally the first argument may be some other identifier than the above 2258possibilities, in which case it controls a set of named assertions 2259that can be checked using pragma @code{Check}. For example, if the pragma: 2260 2261@example 2262pragma Check_Policy (Critical_Error, OFF); 2263@end example 2264 2265is given, then subsequent @code{Check} pragmas whose first argument is also 2266@code{Critical_Error} will be disabled. 2267 2268The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} 2269to turn on corresponding checks. The default for a set of checks for which no 2270@code{Check_Policy} is given is @code{OFF} unless the compiler switch 2271@emph{-gnata} is given, which turns on all checks by default. 2272 2273The check policy settings @code{CHECK} and @code{IGNORE} are recognized 2274as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for 2275compatibility with the standard @code{Assertion_Policy} pragma. The check 2276policy setting @code{DISABLE} causes the second argument of a corresponding 2277@code{Check} pragma to be completely ignored and not analyzed. 2278 2279@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas 2280@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{37} 2281@section Pragma Comment 2282 2283 2284Syntax: 2285 2286@example 2287pragma Comment (static_string_EXPRESSION); 2288@end example 2289 2290This is almost identical in effect to pragma @code{Ident}. It allows the 2291placement of a comment into the object file and hence into the 2292executable file if the operating system permits such usage. The 2293difference is that @code{Comment}, unlike @code{Ident}, has 2294no limitations on placement of the pragma (it can be placed 2295anywhere in the main source unit), and if more than one pragma 2296is used, all comments are retained. 2297 2298@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas 2299@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{38} 2300@section Pragma Common_Object 2301 2302 2303Syntax: 2304 2305@example 2306pragma Common_Object ( 2307 [Internal =>] LOCAL_NAME 2308 [, [External =>] EXTERNAL_SYMBOL] 2309 [, [Size =>] EXTERNAL_SYMBOL] ); 2310 2311EXTERNAL_SYMBOL ::= 2312 IDENTIFIER 2313| static_string_EXPRESSION 2314@end example 2315 2316This pragma enables the shared use of variables stored in overlaid 2317linker areas corresponding to the use of @code{COMMON} 2318in Fortran. The single 2319object @code{LOCAL_NAME} is assigned to the area designated by 2320the @code{External} argument. 2321You may define a record to correspond to a series 2322of fields. The @code{Size} argument 2323is syntax checked in GNAT, but otherwise ignored. 2324 2325@code{Common_Object} is not supported on all platforms. If no 2326support is available, then the code generator will issue a message 2327indicating that the necessary attribute for implementation of this 2328pragma is not available. 2329 2330@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas 2331@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{39}@anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3a} 2332@section Pragma Compile_Time_Error 2333 2334 2335Syntax: 2336 2337@example 2338pragma Compile_Time_Error 2339 (boolean_EXPRESSION, static_string_EXPRESSION); 2340@end example 2341 2342This pragma can be used to generate additional compile time 2343error messages. It 2344is particularly useful in generics, where errors can be issued for 2345specific problematic instantiations. The first parameter is a boolean 2346expression. The pragma ensures that the value of an expression 2347is known at compile time, and has the value False. The set of expressions 2348whose values are known at compile time includes all static boolean 2349expressions, and also other values which the compiler can determine 2350at compile time (e.g., the size of a record type set by an explicit 2351size representation clause, or the value of a variable which was 2352initialized to a constant and is known not to have been modified). 2353If these conditions are not met, an error message is generated using 2354the value given as the second argument. This string value may contain 2355embedded ASCII.LF characters to break the message into multiple lines. 2356 2357@node Pragma Compile_Time_Warning,Pragma Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas 2358@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3b} 2359@section Pragma Compile_Time_Warning 2360 2361 2362Syntax: 2363 2364@example 2365pragma Compile_Time_Warning 2366 (boolean_EXPRESSION, static_string_EXPRESSION); 2367@end example 2368 2369Same as pragma Compile_Time_Error, except a warning is issued instead 2370of an error message. If switch @emph{-gnatw_C} is used, a warning is only issued 2371if the value of the expression is known to be True at compile time, not when 2372the value of the expression is not known at compile time. 2373Note that if this pragma is used in a package that 2374is with'ed by a client, the client will get the warning even though it 2375is issued by a with'ed package (normally warnings in with'ed units are 2376suppressed, but this is a special exception to that rule). 2377 2378One typical use is within a generic where compile time known characteristics 2379of formal parameters are tested, and warnings given appropriately. Another use 2380with a first parameter of True is to warn a client about use of a package, 2381for example that it is not fully implemented. 2382 2383In previous versions of the compiler, combining @emph{-gnatwe} with 2384Compile_Time_Warning resulted in a fatal error. Now the compiler always emits 2385a warning. You can use @ref{3a,,Pragma Compile_Time_Error} to force the generation of 2386an error. 2387 2388@node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas 2389@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{3c} 2390@section Pragma Compiler_Unit 2391 2392 2393Syntax: 2394 2395@example 2396pragma Compiler_Unit; 2397@end example 2398 2399This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is 2400retained so that old versions of the GNAT run-time that use this pragma can 2401be compiled with newer versions of the compiler. 2402 2403@node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas 2404@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{3d} 2405@section Pragma Compiler_Unit_Warning 2406 2407 2408Syntax: 2409 2410@example 2411pragma Compiler_Unit_Warning; 2412@end example 2413 2414This pragma is intended only for internal use in the GNAT run-time library. 2415It indicates that the unit is used as part of the compiler build. The effect 2416is to generate warnings for the use of constructs (for example, conditional 2417expressions) that would cause trouble when bootstrapping using an older 2418version of GNAT. For the exact list of restrictions, see the compiler sources 2419and references to Check_Compiler_Unit. 2420 2421@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas 2422@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3e} 2423@section Pragma Complete_Representation 2424 2425 2426Syntax: 2427 2428@example 2429pragma Complete_Representation; 2430@end example 2431 2432This pragma must appear immediately within a record representation 2433clause. Typical placements are before the first component clause 2434or after the last component clause. The effect is to give an error 2435message if any component is missing a component clause. This pragma 2436may be used to ensure that a record representation clause is 2437complete, and that this invariant is maintained if fields are 2438added to the record in the future. 2439 2440@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas 2441@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3f} 2442@section Pragma Complex_Representation 2443 2444 2445Syntax: 2446 2447@example 2448pragma Complex_Representation 2449 ([Entity =>] LOCAL_NAME); 2450@end example 2451 2452The @code{Entity} argument must be the name of a record type which has 2453two fields of the same floating-point type. The effect of this pragma is 2454to force gcc to use the special internal complex representation form for 2455this record, which may be more efficient. Note that this may result in 2456the code for this type not conforming to standard ABI (application 2457binary interface) requirements for the handling of record types. For 2458example, in some environments, there is a requirement for passing 2459records by pointer, and the use of this pragma may result in passing 2460this type in floating-point registers. 2461 2462@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas 2463@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{40} 2464@section Pragma Component_Alignment 2465 2466 2467@geindex Alignments of components 2468 2469@geindex Pragma Component_Alignment 2470 2471Syntax: 2472 2473@example 2474pragma Component_Alignment ( 2475 [Form =>] ALIGNMENT_CHOICE 2476 [, [Name =>] type_LOCAL_NAME]); 2477 2478ALIGNMENT_CHOICE ::= 2479 Component_Size 2480| Component_Size_4 2481| Storage_Unit 2482| Default 2483@end example 2484 2485Specifies the alignment of components in array or record types. 2486The meaning of the @code{Form} argument is as follows: 2487 2488@quotation 2489 2490@geindex Component_Size (in pragma Component_Alignment) 2491@end quotation 2492 2493 2494@table @asis 2495 2496@item @emph{Component_Size} 2497 2498Aligns scalar components and subcomponents of the array or record type 2499on boundaries appropriate to their inherent size (naturally 2500aligned). For example, 1-byte components are aligned on byte boundaries, 25012-byte integer components are aligned on 2-byte boundaries, 4-byte 2502integer components are aligned on 4-byte boundaries and so on. These 2503alignment rules correspond to the normal rules for C compilers on all 2504machines except the VAX. 2505 2506@geindex Component_Size_4 (in pragma Component_Alignment) 2507 2508@item @emph{Component_Size_4} 2509 2510Naturally aligns components with a size of four or fewer 2511bytes. Components that are larger than 4 bytes are placed on the next 25124-byte boundary. 2513 2514@geindex Storage_Unit (in pragma Component_Alignment) 2515 2516@item @emph{Storage_Unit} 2517 2518Specifies that array or record components are byte aligned, i.e., 2519aligned on boundaries determined by the value of the constant 2520@code{System.Storage_Unit}. 2521 2522@geindex Default (in pragma Component_Alignment) 2523 2524@item @emph{Default} 2525 2526Specifies that array or record components are aligned on default 2527boundaries, appropriate to the underlying hardware or operating system or 2528both. The @code{Default} choice is the same as @code{Component_Size} (natural 2529alignment). 2530@end table 2531 2532If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must 2533refer to a local record or array type, and the specified alignment 2534choice applies to the specified type. The use of 2535@code{Component_Alignment} together with a pragma @code{Pack} causes the 2536@code{Component_Alignment} pragma to be ignored. The use of 2537@code{Component_Alignment} together with a record representation clause 2538is only effective for fields not specified by the representation clause. 2539 2540If the @code{Name} parameter is absent, the pragma can be used as either 2541a configuration pragma, in which case it applies to one or more units in 2542accordance with the normal rules for configuration pragmas, or it can be 2543used within a declarative part, in which case it applies to types that 2544are declared within this declarative part, or within any nested scope 2545within this declarative part. In either case it specifies the alignment 2546to be applied to any record or array type which has otherwise standard 2547representation. 2548 2549If the alignment for a record or array type is not specified (using 2550pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep 2551clause), the GNAT uses the default alignment as described previously. 2552 2553@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas 2554@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{42} 2555@section Pragma Constant_After_Elaboration 2556 2557 2558Syntax: 2559 2560@example 2561pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ]; 2562@end example 2563 2564For the semantics of this pragma, see the entry for aspect 2565@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. 2566 2567@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas 2568@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{44} 2569@section Pragma Contract_Cases 2570 2571 2572@geindex Contract cases 2573 2574Syntax: 2575 2576@example 2577pragma Contract_Cases ((CONTRACT_CASE @{, CONTRACT_CASE)); 2578 2579CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE 2580 2581CASE_GUARD ::= boolean_EXPRESSION | others 2582 2583CONSEQUENCE ::= boolean_EXPRESSION 2584@end example 2585 2586The @code{Contract_Cases} pragma allows defining fine-grain specifications 2587that can complement or replace the contract given by a precondition and a 2588postcondition. Additionally, the @code{Contract_Cases} pragma can be used 2589by testing and formal verification tools. The compiler checks its validity and, 2590depending on the assertion policy at the point of declaration of the pragma, 2591it may insert a check in the executable. For code generation, the contract 2592cases 2593 2594@example 2595pragma Contract_Cases ( 2596 Cond1 => Pred1, 2597 Cond2 => Pred2); 2598@end example 2599 2600are equivalent to 2601 2602@example 2603C1 : constant Boolean := Cond1; -- evaluated at subprogram entry 2604C2 : constant Boolean := Cond2; -- evaluated at subprogram entry 2605pragma Precondition ((C1 and not C2) or (C2 and not C1)); 2606pragma Postcondition (if C1 then Pred1); 2607pragma Postcondition (if C2 then Pred2); 2608@end example 2609 2610The precondition ensures that one and only one of the case guards is 2611satisfied on entry to the subprogram. 2612The postcondition ensures that for the case guard that was True on entry, 2613the corresponding consequence is True on exit. Other consequence expressions 2614are not evaluated. 2615 2616A precondition @code{P} and postcondition @code{Q} can also be 2617expressed as contract cases: 2618 2619@example 2620pragma Contract_Cases (P => Q); 2621@end example 2622 2623The placement and visibility rules for @code{Contract_Cases} pragmas are 2624identical to those described for preconditions and postconditions. 2625 2626The compiler checks that boolean expressions given in case guards and 2627consequences are valid, where the rules for case guards are the same as 2628the rule for an expression in @code{Precondition} and the rules for 2629consequences are the same as the rule for an expression in 2630@code{Postcondition}. In particular, attributes @code{'Old} and 2631@code{'Result} can only be used within consequence expressions. 2632The case guard for the last contract case may be @code{others}, to denote 2633any case not captured by the previous cases. The 2634following is an example of use within a package spec: 2635 2636@example 2637package Math_Functions is 2638 ... 2639 function Sqrt (Arg : Float) return Float; 2640 pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, 2641 Arg >= 100.0 => Sqrt'Result >= 10.0, 2642 others => Sqrt'Result = 0.0)); 2643 ... 2644end Math_Functions; 2645@end example 2646 2647The meaning of contract cases is that only one case should apply at each 2648call, as determined by the corresponding case guard evaluating to True, 2649and that the consequence for this case should hold when the subprogram 2650returns. 2651 2652@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas 2653@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{45} 2654@section Pragma Convention_Identifier 2655 2656 2657@geindex Conventions 2658@geindex synonyms 2659 2660Syntax: 2661 2662@example 2663pragma Convention_Identifier ( 2664 [Name =>] IDENTIFIER, 2665 [Convention =>] convention_IDENTIFIER); 2666@end example 2667 2668This pragma provides a mechanism for supplying synonyms for existing 2669convention identifiers. The @code{Name} identifier can subsequently 2670be used as a synonym for the given convention in other pragmas (including 2671for example pragma @code{Import} or another @code{Convention_Identifier} 2672pragma). As an example of the use of this, suppose you had legacy code 2673which used Fortran77 as the identifier for Fortran. Then the pragma: 2674 2675@example 2676pragma Convention_Identifier (Fortran77, Fortran); 2677@end example 2678 2679would allow the use of the convention identifier @code{Fortran77} in 2680subsequent code, avoiding the need to modify the sources. As another 2681example, you could use this to parameterize convention requirements 2682according to systems. Suppose you needed to use @code{Stdcall} on 2683windows systems, and @code{C} on some other system, then you could 2684define a convention identifier @code{Library} and use a single 2685@code{Convention_Identifier} pragma to specify which convention 2686would be used system-wide. 2687 2688@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas 2689@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{46} 2690@section Pragma CPP_Class 2691 2692 2693@geindex Interfacing with C++ 2694 2695Syntax: 2696 2697@example 2698pragma CPP_Class ([Entity =>] LOCAL_NAME); 2699@end example 2700 2701The argument denotes an entity in the current declarative region that is 2702declared as a record type. It indicates that the type corresponds to an 2703externally declared C++ class type, and is to be laid out the same way 2704that C++ would lay out the type. If the C++ class has virtual primitives 2705then the record must be declared as a tagged record type. 2706 2707Types for which @code{CPP_Class} is specified do not have assignment or 2708equality operators defined (such operations can be imported or declared 2709as subprograms as required). Initialization is allowed only by constructor 2710functions (see pragma @code{CPP_Constructor}). Such types are implicitly 2711limited if not explicitly declared as limited or derived from a limited 2712type, and an error is issued in that case. 2713 2714See @ref{47,,Interfacing to C++} for related information. 2715 2716Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 2717for backward compatibility but its functionality is available 2718using pragma @code{Import} with @code{Convention} = @code{CPP}. 2719 2720@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas 2721@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{48} 2722@section Pragma CPP_Constructor 2723 2724 2725@geindex Interfacing with C++ 2726 2727Syntax: 2728 2729@example 2730pragma CPP_Constructor ([Entity =>] LOCAL_NAME 2731 [, [External_Name =>] static_string_EXPRESSION ] 2732 [, [Link_Name =>] static_string_EXPRESSION ]); 2733@end example 2734 2735This pragma identifies an imported function (imported in the usual way 2736with pragma @code{Import}) as corresponding to a C++ constructor. If 2737@code{External_Name} and @code{Link_Name} are not specified then the 2738@code{Entity} argument is a name that must have been previously mentioned 2739in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name 2740must be of one of the following forms: 2741 2742 2743@itemize * 2744 2745@item 2746@strong{function} @code{Fname} @strong{return} T` 2747 2748@item 2749@strong{function} @code{Fname} @strong{return} T'Class 2750 2751@item 2752@strong{function} @code{Fname} (...) @strong{return} T` 2753 2754@item 2755@strong{function} @code{Fname} (...) @strong{return} T'Class 2756@end itemize 2757 2758where @code{T} is a limited record type imported from C++ with pragma 2759@code{Import} and @code{Convention} = @code{CPP}. 2760 2761The first two forms import the default constructor, used when an object 2762of type @code{T} is created on the Ada side with no explicit constructor. 2763The latter two forms cover all the non-default constructors of the type. 2764See the GNAT User's Guide for details. 2765 2766If no constructors are imported, it is impossible to create any objects 2767on the Ada side and the type is implicitly declared abstract. 2768 2769Pragma @code{CPP_Constructor} is intended primarily for automatic generation 2770using an automatic binding generator tool (such as the @code{-fdump-ada-spec} 2771GCC switch). 2772See @ref{47,,Interfacing to C++} for more related information. 2773 2774Note: The use of functions returning class-wide types for constructors is 2775currently obsolete. They are supported for backward compatibility. The 2776use of functions returning the type T leave the Ada sources more clear 2777because the imported C++ constructors always return an object of type T; 2778that is, they never return an object whose type is a descendant of type T. 2779 2780@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas 2781@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{49} 2782@section Pragma CPP_Virtual 2783 2784 2785@geindex Interfacing to C++ 2786 2787This pragma is now obsolete and, other than generating a warning if warnings 2788on obsolescent features are enabled, is completely ignored. 2789It is retained for compatibility 2790purposes. It used to be required to ensure compoatibility with C++, but 2791is no longer required for that purpose because GNAT generates 2792the same object layout as the G++ compiler by default. 2793 2794See @ref{47,,Interfacing to C++} for related information. 2795 2796@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas 2797@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4a} 2798@section Pragma CPP_Vtable 2799 2800 2801@geindex Interfacing with C++ 2802 2803This pragma is now obsolete and, other than generating a warning if warnings 2804on obsolescent features are enabled, is completely ignored. 2805It used to be required to ensure compatibility with C++, but 2806is no longer required for that purpose because GNAT generates 2807the same object layout as the G++ compiler by default. 2808 2809See @ref{47,,Interfacing to C++} for related information. 2810 2811@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas 2812@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4b} 2813@section Pragma CPU 2814 2815 2816Syntax: 2817 2818@example 2819pragma CPU (EXPRESSION); 2820@end example 2821 2822This pragma is standard in Ada 2012, but is available in all earlier 2823versions of Ada as an implementation-defined pragma. 2824See Ada 2012 Reference Manual for details. 2825 2826@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas 2827@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4c} 2828@section Pragma Deadline_Floor 2829 2830 2831Syntax: 2832 2833@example 2834pragma Deadline_Floor (time_span_EXPRESSION); 2835@end example 2836 2837This pragma applies only to protected types and specifies the floor 2838deadline inherited by a task when the task enters a protected object. 2839It is effective only when the EDF scheduling policy is used. 2840 2841@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas 2842@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4d}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4e} 2843@section Pragma Default_Initial_Condition 2844 2845 2846Syntax: 2847 2848@example 2849pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; 2850@end example 2851 2852For the semantics of this pragma, see the entry for aspect 2853@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. 2854 2855@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas 2856@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4f} 2857@section Pragma Debug 2858 2859 2860Syntax: 2861 2862@example 2863pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 2864 2865PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 2866 PROCEDURE_NAME 2867| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 2868@end example 2869 2870The procedure call argument has the syntactic form of an expression, meeting 2871the syntactic requirements for pragmas. 2872 2873If debug pragmas are not enabled or if the condition is present and evaluates 2874to False, this pragma has no effect. If debug pragmas are enabled, the 2875semantics of the pragma is exactly equivalent to the procedure call statement 2876corresponding to the argument with a terminating semicolon. Pragmas are 2877permitted in sequences of declarations, so you can use pragma @code{Debug} to 2878intersperse calls to debug procedures in the middle of declarations. Debug 2879pragmas can be enabled either by use of the command line switch @emph{-gnata} 2880or by use of the pragma @code{Check_Policy} with a first argument of 2881@code{Debug}. 2882 2883@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas 2884@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{50} 2885@section Pragma Debug_Policy 2886 2887 2888Syntax: 2889 2890@example 2891pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); 2892@end example 2893 2894This pragma is equivalent to a corresponding @code{Check_Policy} pragma 2895with a first argument of @code{Debug}. It is retained for historical 2896compatibility reasons. 2897 2898@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas 2899@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{51} 2900@section Pragma Default_Scalar_Storage_Order 2901 2902 2903@geindex Default_Scalar_Storage_Order 2904 2905@geindex Scalar_Storage_Order 2906 2907Syntax: 2908 2909@example 2910pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); 2911@end example 2912 2913Normally if no explicit @code{Scalar_Storage_Order} is given for a record 2914type or array type, then the scalar storage order defaults to the ordinary 2915default for the target. But this default may be overridden using this pragma. 2916The pragma may appear as a configuration pragma, or locally within a package 2917spec or declarative part. In the latter case, it applies to all subsequent 2918types declared within that package spec or declarative part. 2919 2920The following example shows the use of this pragma: 2921 2922@example 2923pragma Default_Scalar_Storage_Order (High_Order_First); 2924with System; use System; 2925package DSSO1 is 2926 type H1 is record 2927 a : Integer; 2928 end record; 2929 2930 type L2 is record 2931 a : Integer; 2932 end record; 2933 for L2'Scalar_Storage_Order use Low_Order_First; 2934 2935 type L2a is new L2; 2936 2937 package Inner is 2938 type H3 is record 2939 a : Integer; 2940 end record; 2941 2942 pragma Default_Scalar_Storage_Order (Low_Order_First); 2943 2944 type L4 is record 2945 a : Integer; 2946 end record; 2947 end Inner; 2948 2949 type H4a is new Inner.L4; 2950 2951 type H5 is record 2952 a : Integer; 2953 end record; 2954end DSSO1; 2955@end example 2956 2957In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar 2958storage order, and record types with names starting with @emph{H} have @code{High_Order_First}. 2959Note that in the case of @code{H4a}, the order is not inherited 2960from the parent type. Only an explicitly set @code{Scalar_Storage_Order} 2961gets inherited on type derivation. 2962 2963If this pragma is used as a configuration pragma which appears within a 2964configuration pragma file (as opposed to appearing explicitly at the start 2965of a single unit), then the binder will require that all units in a partition 2966be compiled in a similar manner, other than run-time units, which are not 2967affected by this pragma. Note that the use of this form is discouraged because 2968it may significantly degrade the run-time performance of the software, instead 2969the default scalar storage order ought to be changed only on a local basis. 2970 2971@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas 2972@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{52} 2973@section Pragma Default_Storage_Pool 2974 2975 2976@geindex Default_Storage_Pool 2977 2978Syntax: 2979 2980@example 2981pragma Default_Storage_Pool (storage_pool_NAME | null); 2982@end example 2983 2984This pragma is standard in Ada 2012, but is available in all earlier 2985versions of Ada as an implementation-defined pragma. 2986See Ada 2012 Reference Manual for details. 2987 2988@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas 2989@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{53}@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{54} 2990@section Pragma Depends 2991 2992 2993Syntax: 2994 2995@example 2996pragma Depends (DEPENDENCY_RELATION); 2997 2998DEPENDENCY_RELATION ::= 2999 null 3000 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 3001 3002DEPENDENCY_CLAUSE ::= 3003 OUTPUT_LIST =>[+] INPUT_LIST 3004 | NULL_DEPENDENCY_CLAUSE 3005 3006NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 3007 3008OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 3009 3010INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 3011 3012OUTPUT ::= NAME | FUNCTION_RESULT 3013INPUT ::= NAME 3014 3015where FUNCTION_RESULT is a function Result attribute_reference 3016@end example 3017 3018For the semantics of this pragma, see the entry for aspect @code{Depends} in the 3019SPARK 2014 Reference Manual, section 6.1.5. 3020 3021@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas 3022@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{55} 3023@section Pragma Detect_Blocking 3024 3025 3026Syntax: 3027 3028@example 3029pragma Detect_Blocking; 3030@end example 3031 3032This is a standard pragma in Ada 2005, that is available in all earlier 3033versions of Ada as an implementation-defined pragma. 3034 3035This is a configuration pragma that forces the detection of potentially 3036blocking operations within a protected operation, and to raise Program_Error 3037if that happens. 3038 3039@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas 3040@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{56} 3041@section Pragma Disable_Atomic_Synchronization 3042 3043 3044@geindex Atomic Synchronization 3045 3046Syntax: 3047 3048@example 3049pragma Disable_Atomic_Synchronization [(Entity)]; 3050@end example 3051 3052Ada requires that accesses (reads or writes) of an atomic variable be 3053regarded as synchronization points in the case of multiple tasks. 3054Particularly in the case of multi-processors this may require special 3055handling, e.g. the generation of memory barriers. This capability may 3056be turned off using this pragma in cases where it is known not to be 3057required. 3058 3059The placement and scope rules for this pragma are the same as those 3060for @code{pragma Suppress}. In particular it can be used as a 3061configuration pragma, or in a declaration sequence where it applies 3062till the end of the scope. If an @code{Entity} argument is present, 3063the action applies only to that entity. 3064 3065@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas 3066@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{57} 3067@section Pragma Dispatching_Domain 3068 3069 3070Syntax: 3071 3072@example 3073pragma Dispatching_Domain (EXPRESSION); 3074@end example 3075 3076This pragma is standard in Ada 2012, but is available in all earlier 3077versions of Ada as an implementation-defined pragma. 3078See Ada 2012 Reference Manual for details. 3079 3080@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas 3081@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{59} 3082@section Pragma Effective_Reads 3083 3084 3085Syntax: 3086 3087@example 3088pragma Effective_Reads [ (boolean_EXPRESSION) ]; 3089@end example 3090 3091For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in 3092the SPARK 2014 Reference Manual, section 7.1.2. 3093 3094@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas 3095@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5b} 3096@section Pragma Effective_Writes 3097 3098 3099Syntax: 3100 3101@example 3102pragma Effective_Writes [ (boolean_EXPRESSION) ]; 3103@end example 3104 3105For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} 3106in the SPARK 2014 Reference Manual, section 7.1.2. 3107 3108@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas 3109@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5c} 3110@section Pragma Elaboration_Checks 3111 3112 3113@geindex Elaboration control 3114 3115Syntax: 3116 3117@example 3118pragma Elaboration_Checks (Dynamic | Static); 3119@end example 3120 3121This is a configuration pragma which specifies the elaboration model to be 3122used during compilation. For more information on the elaboration models of 3123GNAT, consult the chapter on elaboration order handling in the @emph{GNAT User's 3124Guide}. 3125 3126The pragma may appear in the following contexts: 3127 3128 3129@itemize * 3130 3131@item 3132Configuration pragmas file 3133 3134@item 3135Prior to the context clauses of a compilation unit's initial declaration 3136@end itemize 3137 3138Any other placement of the pragma will result in a warning and the effects of 3139the offending pragma will be ignored. 3140 3141If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in 3142effect. If the pragma argument is @code{Static}, then the static elaboration model 3143is in effect. 3144 3145@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas 3146@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5d} 3147@section Pragma Eliminate 3148 3149 3150@geindex Elimination of unused subprograms 3151 3152Syntax: 3153 3154@example 3155pragma Eliminate ( 3156 [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , 3157 [ Entity => ] IDENTIFIER | 3158 SELECTED_COMPONENT | 3159 STRING_LITERAL 3160 [, Source_Location => SOURCE_TRACE ] ); 3161 3162 SOURCE_TRACE ::= STRING_LITERAL 3163@end example 3164 3165This pragma indicates that the given entity is not used in the program to be 3166compiled and built, thus allowing the compiler to 3167eliminate the code or data associated with the named entity. Any reference to 3168an eliminated entity causes a compile-time or link-time error. 3169 3170The pragma has the following semantics, where @code{U} is the unit specified by 3171the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} 3172argument: 3173 3174 3175@itemize * 3176 3177@item 3178@code{E} must be a subprogram that is explicitly declared either: 3179 3180o Within @code{U}, or 3181 3182o Within a generic package that is instantiated in @code{U}, or 3183 3184o As an instance of generic subprogram instantiated in @code{U}. 3185 3186Otherwise the pragma is ignored. 3187 3188@item 3189If @code{E} is overloaded within @code{U} then, in the absence of a 3190@code{Source_Location} argument, all overloadings are eliminated. 3191 3192@item 3193If @code{E} is overloaded within @code{U} and only some overloadings 3194are to be eliminated, then each overloading to be eliminated 3195must be specified in a corresponding pragma @code{Eliminate} 3196with a @code{Source_Location} argument identifying the line where the 3197declaration appears, as described below. 3198 3199@item 3200If @code{E} is declared as the result of a generic instantiation, then 3201a @code{Source_Location} argument is needed, as described below 3202@end itemize 3203 3204Pragma @code{Eliminate} allows a program to be compiled in a system-independent 3205manner, so that unused entities are eliminated but without 3206needing to modify the source text. Normally the required set of 3207@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. 3208 3209Any source file change that removes, splits, or 3210adds lines may make the set of @code{Eliminate} pragmas invalid because their 3211@code{Source_Location} argument values may get out of date. 3212 3213Pragma @code{Eliminate} may be used where the referenced entity is a dispatching 3214operation. In this case all the subprograms to which the given operation can 3215dispatch are considered to be unused (are never called as a result of a direct 3216or a dispatching call). 3217 3218The string literal given for the source location specifies the line number 3219of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: 3220 3221@example 3222SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] 3223 3224LBRACKET ::= '[' 3225RBRACKET ::= ']' 3226 3227SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 3228 3229LINE_NUMBER ::= DIGIT @{DIGIT@} 3230@end example 3231 3232Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. 3233 3234The source trace that is given as the @code{Source_Location} must obey the 3235following rules (or else the pragma is ignored), where @code{U} is 3236the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the 3237subprogram specified by the @code{Entity} argument: 3238 3239 3240@itemize * 3241 3242@item 3243@code{FILE_NAME} is the short name (with no directory 3244information) of the Ada source file for @code{U}, using the required syntax 3245for the underlying file system (e.g. case is significant if the underlying 3246operating system is case sensitive). 3247If @code{U} is a package and @code{E} is a subprogram declared in the package 3248specification and its full declaration appears in the package body, 3249then the relevant source file is the one for the package specification; 3250analogously if @code{U} is a generic package. 3251 3252@item 3253If @code{E} is not declared in a generic instantiation (this includes 3254generic subprogram instances), the source trace includes only one source 3255line reference. @code{LINE_NUMBER} gives the line number of the occurrence 3256of the declaration of @code{E} within the source file (as a decimal literal 3257without an exponent or point). 3258 3259@item 3260If @code{E} is declared by a generic instantiation, its source trace 3261(from left to right) starts with the source location of the 3262declaration of @code{E} in the generic unit and ends with the source 3263location of the instantiation, given in square brackets. This approach is 3264applied recursively with nested instantiations: the rightmost (nested 3265most deeply in square brackets) element of the source trace is the location 3266of the outermost instantiation, and the leftmost element (that is, outside 3267of any square brackets) is the location of the declaration of @code{E} in 3268the generic unit. 3269@end itemize 3270 3271Examples: 3272 3273@quotation 3274 3275@example 3276pragma Eliminate (Pkg0, Proc); 3277-- Eliminate (all overloadings of) Proc in Pkg0 3278 3279pragma Eliminate (Pkg1, Proc, 3280 Source_Location => "pkg1.ads:8"); 3281-- Eliminate overloading of Proc at line 8 in pkg1.ads 3282 3283-- Assume the following file contents: 3284-- gen_pkg.ads 3285-- 1: generic 3286-- 2: type T is private; 3287-- 3: package Gen_Pkg is 3288-- 4: procedure Proc(N : T); 3289-- ... ... 3290-- ... end Gen_Pkg; 3291-- 3292-- q.adb 3293-- 1: with Gen_Pkg; 3294-- 2: procedure Q is 3295-- 3: package Inst_Pkg is new Gen_Pkg(Integer); 3296-- ... -- No calls on Inst_Pkg.Proc 3297-- ... end Q; 3298 3299-- The following pragma eliminates Inst_Pkg.Proc from Q 3300pragma Eliminate (Q, Proc, 3301 Source_Location => "gen_pkg.ads:4[q.adb:3]"); 3302@end example 3303@end quotation 3304 3305@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas 3306@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5e} 3307@section Pragma Enable_Atomic_Synchronization 3308 3309 3310@geindex Atomic Synchronization 3311 3312Syntax: 3313 3314@example 3315pragma Enable_Atomic_Synchronization [(Entity)]; 3316@end example 3317 3318Ada requires that accesses (reads or writes) of an atomic variable be 3319regarded as synchronization points in the case of multiple tasks. 3320Particularly in the case of multi-processors this may require special 3321handling, e.g. the generation of memory barriers. This synchronization 3322is performed by default, but can be turned off using 3323@code{pragma Disable_Atomic_Synchronization}. The 3324@code{Enable_Atomic_Synchronization} pragma can be used to turn 3325it back on. 3326 3327The placement and scope rules for this pragma are the same as those 3328for @code{pragma Unsuppress}. In particular it can be used as a 3329configuration pragma, or in a declaration sequence where it applies 3330till the end of the scope. If an @code{Entity} argument is present, 3331the action applies only to that entity. 3332 3333@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas 3334@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5f} 3335@section Pragma Export_Function 3336 3337 3338@geindex Argument passing mechanisms 3339 3340Syntax: 3341 3342@example 3343pragma Export_Function ( 3344 [Internal =>] LOCAL_NAME 3345 [, [External =>] EXTERNAL_SYMBOL] 3346 [, [Parameter_Types =>] PARAMETER_TYPES] 3347 [, [Result_Type =>] result_SUBTYPE_MARK] 3348 [, [Mechanism =>] MECHANISM] 3349 [, [Result_Mechanism =>] MECHANISM_NAME]); 3350 3351EXTERNAL_SYMBOL ::= 3352 IDENTIFIER 3353| static_string_EXPRESSION 3354| "" 3355 3356PARAMETER_TYPES ::= 3357 null 3358| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3359 3360TYPE_DESIGNATOR ::= 3361 subtype_NAME 3362| subtype_Name ' Access 3363 3364MECHANISM ::= 3365 MECHANISM_NAME 3366| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3367 3368MECHANISM_ASSOCIATION ::= 3369 [formal_parameter_NAME =>] MECHANISM_NAME 3370 3371MECHANISM_NAME ::= Value | Reference 3372@end example 3373 3374Use this pragma to make a function externally callable and optionally 3375provide information on mechanisms to be used for passing parameter and 3376result values. We recommend, for the purposes of improving portability, 3377this pragma always be used in conjunction with a separate pragma 3378@code{Export}, which must precede the pragma @code{Export_Function}. 3379GNAT does not require a separate pragma @code{Export}, but if none is 3380present, @code{Convention Ada} is assumed, which is usually 3381not what is wanted, so it is usually appropriate to use this 3382pragma in conjunction with a @code{Export} or @code{Convention} 3383pragma that specifies the desired foreign convention. 3384Pragma @code{Export_Function} 3385(and @code{Export}, if present) must appear in the same declarative 3386region as the function to which they apply. 3387 3388The @code{internal_name} must uniquely designate the function to which the 3389pragma applies. If more than one function name exists of this name in 3390the declarative part you must use the @code{Parameter_Types} and 3391@code{Result_Type} parameters to achieve the required 3392unique designation. The @cite{subtype_mark}s in these parameters must 3393exactly match the subtypes in the corresponding function specification, 3394using positional notation to match parameters with subtype marks. 3395The form with an @code{'Access} attribute can be used to match an 3396anonymous access parameter. 3397 3398@geindex Suppressing external name 3399 3400Special treatment is given if the EXTERNAL is an explicit null 3401string or a static string expressions that evaluates to the null 3402string. In this case, no external name is generated. This form 3403still allows the specification of parameter mechanisms. 3404 3405@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas 3406@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{60} 3407@section Pragma Export_Object 3408 3409 3410Syntax: 3411 3412@example 3413pragma Export_Object 3414 [Internal =>] LOCAL_NAME 3415 [, [External =>] EXTERNAL_SYMBOL] 3416 [, [Size =>] EXTERNAL_SYMBOL] 3417 3418EXTERNAL_SYMBOL ::= 3419 IDENTIFIER 3420| static_string_EXPRESSION 3421@end example 3422 3423This pragma designates an object as exported, and apart from the 3424extended rules for external symbols, is identical in effect to the use of 3425the normal @code{Export} pragma applied to an object. You may use a 3426separate Export pragma (and you probably should from the point of view 3427of portability), but it is not required. @code{Size} is syntax checked, 3428but otherwise ignored by GNAT. 3429 3430@node Pragma Export_Procedure,Pragma Export_Value,Pragma Export_Object,Implementation Defined Pragmas 3431@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{61} 3432@section Pragma Export_Procedure 3433 3434 3435Syntax: 3436 3437@example 3438pragma Export_Procedure ( 3439 [Internal =>] LOCAL_NAME 3440 [, [External =>] EXTERNAL_SYMBOL] 3441 [, [Parameter_Types =>] PARAMETER_TYPES] 3442 [, [Mechanism =>] MECHANISM]); 3443 3444EXTERNAL_SYMBOL ::= 3445 IDENTIFIER 3446| static_string_EXPRESSION 3447| "" 3448 3449PARAMETER_TYPES ::= 3450 null 3451| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3452 3453TYPE_DESIGNATOR ::= 3454 subtype_NAME 3455| subtype_Name ' Access 3456 3457MECHANISM ::= 3458 MECHANISM_NAME 3459| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3460 3461MECHANISM_ASSOCIATION ::= 3462 [formal_parameter_NAME =>] MECHANISM_NAME 3463 3464MECHANISM_NAME ::= Value | Reference 3465@end example 3466 3467This pragma is identical to @code{Export_Function} except that it 3468applies to a procedure rather than a function and the parameters 3469@code{Result_Type} and @code{Result_Mechanism} are not permitted. 3470GNAT does not require a separate pragma @code{Export}, but if none is 3471present, @code{Convention Ada} is assumed, which is usually 3472not what is wanted, so it is usually appropriate to use this 3473pragma in conjunction with a @code{Export} or @code{Convention} 3474pragma that specifies the desired foreign convention. 3475 3476@geindex Suppressing external name 3477 3478Special treatment is given if the EXTERNAL is an explicit null 3479string or a static string expressions that evaluates to the null 3480string. In this case, no external name is generated. This form 3481still allows the specification of parameter mechanisms. 3482 3483@node Pragma Export_Value,Pragma Export_Valued_Procedure,Pragma Export_Procedure,Implementation Defined Pragmas 3484@anchor{gnat_rm/implementation_defined_pragmas pragma-export-value}@anchor{62} 3485@section Pragma Export_Value 3486 3487 3488Syntax: 3489 3490@example 3491pragma Export_Value ( 3492 [Value =>] static_integer_EXPRESSION, 3493 [Link_Name =>] static_string_EXPRESSION); 3494@end example 3495 3496This pragma serves to export a static integer value for external use. 3497The first argument specifies the value to be exported. The Link_Name 3498argument specifies the symbolic name to be associated with the integer 3499value. This pragma is useful for defining a named static value in Ada 3500that can be referenced in assembly language units to be linked with 3501the application. This pragma is currently supported only for the 3502AAMP target and is ignored for other targets. 3503 3504@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Value,Implementation Defined Pragmas 3505@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{63} 3506@section Pragma Export_Valued_Procedure 3507 3508 3509Syntax: 3510 3511@example 3512pragma Export_Valued_Procedure ( 3513 [Internal =>] LOCAL_NAME 3514 [, [External =>] EXTERNAL_SYMBOL] 3515 [, [Parameter_Types =>] PARAMETER_TYPES] 3516 [, [Mechanism =>] MECHANISM]); 3517 3518EXTERNAL_SYMBOL ::= 3519 IDENTIFIER 3520| static_string_EXPRESSION 3521| "" 3522 3523PARAMETER_TYPES ::= 3524 null 3525| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3526 3527TYPE_DESIGNATOR ::= 3528 subtype_NAME 3529| subtype_Name ' Access 3530 3531MECHANISM ::= 3532 MECHANISM_NAME 3533| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3534 3535MECHANISM_ASSOCIATION ::= 3536 [formal_parameter_NAME =>] MECHANISM_NAME 3537 3538MECHANISM_NAME ::= Value | Reference 3539@end example 3540 3541This pragma is identical to @code{Export_Procedure} except that the 3542first parameter of @code{LOCAL_NAME}, which must be present, must be of 3543mode @code{out}, and externally the subprogram is treated as a function 3544with this parameter as the result of the function. GNAT provides for 3545this capability to allow the use of @code{out} and @code{in out} 3546parameters in interfacing to external functions (which are not permitted 3547in Ada functions). 3548GNAT does not require a separate pragma @code{Export}, but if none is 3549present, @code{Convention Ada} is assumed, which is almost certainly 3550not what is wanted since the whole point of this pragma is to interface 3551with foreign language functions, so it is usually appropriate to use this 3552pragma in conjunction with a @code{Export} or @code{Convention} 3553pragma that specifies the desired foreign convention. 3554 3555@geindex Suppressing external name 3556 3557Special treatment is given if the EXTERNAL is an explicit null 3558string or a static string expressions that evaluates to the null 3559string. In this case, no external name is generated. This form 3560still allows the specification of parameter mechanisms. 3561 3562@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas 3563@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{64} 3564@section Pragma Extend_System 3565 3566 3567@geindex System 3568@geindex extending 3569 3570@geindex DEC Ada 83 3571 3572Syntax: 3573 3574@example 3575pragma Extend_System ([Name =>] IDENTIFIER); 3576@end example 3577 3578This pragma is used to provide backwards compatibility with other 3579implementations that extend the facilities of package @code{System}. In 3580GNAT, @code{System} contains only the definitions that are present in 3581the Ada RM. However, other implementations, notably the DEC Ada 83 3582implementation, provide many extensions to package @code{System}. 3583 3584For each such implementation accommodated by this pragma, GNAT provides a 3585package @code{Aux_@emph{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 3586implementation, which provides the required additional definitions. You 3587can use this package in two ways. You can @code{with} it in the normal 3588way and access entities either by selection or using a @code{use} 3589clause. In this case no special processing is required. 3590 3591However, if existing code contains references such as 3592@code{System.@emph{xxx}} where @emph{xxx} is an entity in the extended 3593definitions provided in package @code{System}, you may use this pragma 3594to extend visibility in @code{System} in a non-standard way that 3595provides greater compatibility with the existing code. Pragma 3596@code{Extend_System} is a configuration pragma whose single argument is 3597the name of the package containing the extended definition 3598(e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under 3599control of this pragma will be processed using special visibility 3600processing that looks in package @code{System.Aux_@emph{xxx}} where 3601@code{Aux_@emph{xxx}} is the pragma argument for any entity referenced in 3602package @code{System}, but not found in package @code{System}. 3603 3604You can use this pragma either to access a predefined @code{System} 3605extension supplied with the compiler, for example @code{Aux_DEC} or 3606you can construct your own extension unit following the above 3607definition. Note that such a package is a child of @code{System} 3608and thus is considered part of the implementation. 3609To compile it you will have to use the @emph{-gnatg} switch 3610for compiling System units, as explained in the 3611GNAT User's Guide. 3612 3613@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas 3614@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{65} 3615@section Pragma Extensions_Allowed 3616 3617 3618@geindex Ada Extensions 3619 3620@geindex GNAT Extensions 3621 3622Syntax: 3623 3624@example 3625pragma Extensions_Allowed (On | Off); 3626@end example 3627 3628This configuration pragma enables or disables the implementation 3629extension mode (the use of Off as a parameter cancels the effect 3630of the @emph{-gnatX} command switch). 3631 3632In extension mode, the latest version of the Ada language is 3633implemented (currently Ada 202x), and in addition a small number 3634of GNAT specific extensions are recognized as follows: 3635 3636 3637@itemize * 3638 3639@item 3640Constrained attribute for generic objects 3641 3642The @code{Constrained} attribute is permitted for objects of 3643generic types. The result indicates if the corresponding actual 3644is constrained. 3645 3646@item 3647@code{Static} aspect on intrinsic functions 3648 3649The Ada 202x @code{Static} aspect can be specified on Intrinsic imported 3650functions and the compiler will evaluate some of these intrinsic statically, 3651in particular the @code{Shift_Left} and @code{Shift_Right} intrinsics. 3652 3653@item 3654@code{'Reduce} attribute 3655 3656This attribute part of the Ada 202x language definition is provided for 3657now under -gnatX to confirm and potentially refine its usage and syntax. 3658 3659@item 3660@code{[]} aggregates 3661 3662This new aggregate syntax for arrays and containers is provided under -gnatX 3663to experiment and confirm this new language syntax. 3664@end itemize 3665 3666@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas 3667@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{66}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{67} 3668@section Pragma Extensions_Visible 3669 3670 3671Syntax: 3672 3673@example 3674pragma Extensions_Visible [ (boolean_EXPRESSION) ]; 3675@end example 3676 3677For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} 3678in the SPARK 2014 Reference Manual, section 6.1.7. 3679 3680@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas 3681@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{68} 3682@section Pragma External 3683 3684 3685Syntax: 3686 3687@example 3688pragma External ( 3689 [ Convention =>] convention_IDENTIFIER, 3690 [ Entity =>] LOCAL_NAME 3691 [, [External_Name =>] static_string_EXPRESSION ] 3692 [, [Link_Name =>] static_string_EXPRESSION ]); 3693@end example 3694 3695This pragma is identical in syntax and semantics to pragma 3696@code{Export} as defined in the Ada Reference Manual. It is 3697provided for compatibility with some Ada 83 compilers that 3698used this pragma for exactly the same purposes as pragma 3699@code{Export} before the latter was standardized. 3700 3701@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas 3702@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{69} 3703@section Pragma External_Name_Casing 3704 3705 3706@geindex Dec Ada 83 casing compatibility 3707 3708@geindex External Names 3709@geindex casing 3710 3711@geindex Casing of External names 3712 3713Syntax: 3714 3715@example 3716pragma External_Name_Casing ( 3717 Uppercase | Lowercase 3718 [, Uppercase | Lowercase | As_Is]); 3719@end example 3720 3721This pragma provides control over the casing of external names associated 3722with Import and Export pragmas. There are two cases to consider: 3723 3724 3725@itemize * 3726 3727@item 3728Implicit external names 3729 3730Implicit external names are derived from identifiers. The most common case 3731arises when a standard Ada Import or Export pragma is used with only two 3732arguments, as in: 3733 3734@example 3735pragma Import (C, C_Routine); 3736@end example 3737 3738Since Ada is a case-insensitive language, the spelling of the identifier in 3739the Ada source program does not provide any information on the desired 3740casing of the external name, and so a convention is needed. In GNAT the 3741default treatment is that such names are converted to all lower case 3742letters. This corresponds to the normal C style in many environments. 3743The first argument of pragma @code{External_Name_Casing} can be used to 3744control this treatment. If @code{Uppercase} is specified, then the name 3745will be forced to all uppercase letters. If @code{Lowercase} is specified, 3746then the normal default of all lower case letters will be used. 3747 3748This same implicit treatment is also used in the case of extended DEC Ada 83 3749compatible Import and Export pragmas where an external name is explicitly 3750specified using an identifier rather than a string. 3751 3752@item 3753Explicit external names 3754 3755Explicit external names are given as string literals. The most common case 3756arises when a standard Ada Import or Export pragma is used with three 3757arguments, as in: 3758 3759@example 3760pragma Import (C, C_Routine, "C_routine"); 3761@end example 3762 3763In this case, the string literal normally provides the exact casing required 3764for the external name. The second argument of pragma 3765@code{External_Name_Casing} may be used to modify this behavior. 3766If @code{Uppercase} is specified, then the name 3767will be forced to all uppercase letters. If @code{Lowercase} is specified, 3768then the name will be forced to all lowercase letters. A specification of 3769@code{As_Is} provides the normal default behavior in which the casing is 3770taken from the string provided. 3771@end itemize 3772 3773This pragma may appear anywhere that a pragma is valid. In particular, it 3774can be used as a configuration pragma in the @code{gnat.adc} file, in which 3775case it applies to all subsequent compilations, or it can be used as a program 3776unit pragma, in which case it only applies to the current unit, or it can 3777be used more locally to control individual Import/Export pragmas. 3778 3779It was primarily intended for use with OpenVMS systems, where many 3780compilers convert all symbols to upper case by default. For interfacing to 3781such compilers (e.g., the DEC C compiler), it may be convenient to use 3782the pragma: 3783 3784@example 3785pragma External_Name_Casing (Uppercase, Uppercase); 3786@end example 3787 3788to enforce the upper casing of all external symbols. 3789 3790@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas 3791@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6a} 3792@section Pragma Fast_Math 3793 3794 3795Syntax: 3796 3797@example 3798pragma Fast_Math; 3799@end example 3800 3801This is a configuration pragma which activates a mode in which speed is 3802considered more important for floating-point operations than absolutely 3803accurate adherence to the requirements of the standard. Currently the 3804following operations are affected: 3805 3806 3807@table @asis 3808 3809@item @emph{Complex Multiplication} 3810 3811The normal simple formula for complex multiplication can result in intermediate 3812overflows for numbers near the end of the range. The Ada standard requires that 3813this situation be detected and corrected by scaling, but in Fast_Math mode such 3814cases will simply result in overflow. Note that to take advantage of this you 3815must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} 3816under control of the pragma, rather than use the preinstantiated versions. 3817@end table 3818 3819@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas 3820@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6b}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6c} 3821@section Pragma Favor_Top_Level 3822 3823 3824Syntax: 3825 3826@example 3827pragma Favor_Top_Level (type_NAME); 3828@end example 3829 3830The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram 3831type. This pragma is an efficiency hint to the compiler, regarding the use of 3832@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. 3833The pragma means that nested subprograms are not used with this type, or are 3834rare, so that the generated code should be efficient in the top-level case. 3835When this pragma is used, dynamically generated trampolines may be used on some 3836targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. 3837 3838@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas 3839@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6d} 3840@section Pragma Finalize_Storage_Only 3841 3842 3843Syntax: 3844 3845@example 3846pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 3847@end example 3848 3849The argument of pragma @code{Finalize_Storage_Only} must denote a local type which 3850is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The 3851pragma suppresses the call to @code{Finalize} for declared library-level objects 3852of the argument type. This is mostly useful for types where finalization is 3853only used to deal with storage reclamation since in most environments it is 3854not necessary to reclaim memory just before terminating execution, hence the 3855name. Note that this pragma does not suppress Finalize calls for library-level 3856heap-allocated objects (see pragma @code{No_Heap_Finalization}). 3857 3858@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas 3859@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6e} 3860@section Pragma Float_Representation 3861 3862 3863Syntax: 3864 3865@example 3866pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 3867 3868FLOAT_REP ::= VAX_Float | IEEE_Float 3869@end example 3870 3871In the one argument form, this pragma is a configuration pragma which 3872allows control over the internal representation chosen for the predefined 3873floating point types declared in the packages @code{Standard} and 3874@code{System}. This pragma is only provided for compatibility and has no effect. 3875 3876The two argument form specifies the representation to be used for 3877the specified floating-point type. The argument must 3878be @code{IEEE_Float} to specify the use of IEEE format, as follows: 3879 3880 3881@itemize * 3882 3883@item 3884For a digits value of 6, 32-bit IEEE short format will be used. 3885 3886@item 3887For a digits value of 15, 64-bit IEEE long format will be used. 3888 3889@item 3890No other value of digits is permitted. 3891@end itemize 3892 3893@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas 3894@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{6f}@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{70} 3895@section Pragma Ghost 3896 3897 3898Syntax: 3899 3900@example 3901pragma Ghost [ (boolean_EXPRESSION) ]; 3902@end example 3903 3904For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK 39052014 Reference Manual, section 6.9. 3906 3907@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas 3908@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{71}@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{72} 3909@section Pragma Global 3910 3911 3912Syntax: 3913 3914@example 3915pragma Global (GLOBAL_SPECIFICATION); 3916 3917GLOBAL_SPECIFICATION ::= 3918 null 3919 | (GLOBAL_LIST) 3920 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 3921 3922MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 3923 3924MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 3925GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 3926GLOBAL_ITEM ::= NAME 3927@end example 3928 3929For the semantics of this pragma, see the entry for aspect @code{Global} in the 3930SPARK 2014 Reference Manual, section 6.1.4. 3931 3932@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas 3933@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{73} 3934@section Pragma Ident 3935 3936 3937Syntax: 3938 3939@example 3940pragma Ident (static_string_EXPRESSION); 3941@end example 3942 3943This pragma is identical in effect to pragma @code{Comment}. It is provided 3944for compatibility with other Ada compilers providing this pragma. 3945 3946@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas 3947@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{74} 3948@section Pragma Ignore_Pragma 3949 3950 3951Syntax: 3952 3953@example 3954pragma Ignore_Pragma (pragma_IDENTIFIER); 3955@end example 3956 3957This is a configuration pragma 3958that takes a single argument that is a simple identifier. Any subsequent 3959use of a pragma whose pragma identifier matches this argument will be 3960silently ignored. This may be useful when legacy code or code intended 3961for compilation with some other compiler contains pragmas that match the 3962name, but not the exact implementation, of a GNAT pragma. The use of this 3963pragma allows such pragmas to be ignored, which may be useful in CodePeer 3964mode, or during porting of legacy code. 3965 3966@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas 3967@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{75} 3968@section Pragma Implementation_Defined 3969 3970 3971Syntax: 3972 3973@example 3974pragma Implementation_Defined (local_NAME); 3975@end example 3976 3977This pragma marks a previously declared entity as implementation-defined. 3978For an overloaded entity, applies to the most recent homonym. 3979 3980@example 3981pragma Implementation_Defined; 3982@end example 3983 3984The form with no arguments appears anywhere within a scope, most 3985typically a package spec, and indicates that all entities that are 3986defined within the package spec are Implementation_Defined. 3987 3988This pragma is used within the GNAT runtime library to identify 3989implementation-defined entities introduced in language-defined units, 3990for the purpose of implementing the No_Implementation_Identifiers 3991restriction. 3992 3993@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas 3994@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{76} 3995@section Pragma Implemented 3996 3997 3998Syntax: 3999 4000@example 4001pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 4002 4003implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 4004@end example 4005 4006This is an Ada 2012 representation pragma which applies to protected, task 4007and synchronized interface primitives. The use of pragma Implemented provides 4008a way to impose a static requirement on the overriding operation by adhering 4009to one of the three implementation kinds: entry, protected procedure or any of 4010the above. This pragma is available in all earlier versions of Ada as an 4011implementation-defined pragma. 4012 4013@example 4014type Synch_Iface is synchronized interface; 4015procedure Prim_Op (Obj : in out Iface) is abstract; 4016pragma Implemented (Prim_Op, By_Protected_Procedure); 4017 4018protected type Prot_1 is new Synch_Iface with 4019 procedure Prim_Op; -- Legal 4020end Prot_1; 4021 4022protected type Prot_2 is new Synch_Iface with 4023 entry Prim_Op; -- Illegal 4024end Prot_2; 4025 4026task type Task_Typ is new Synch_Iface with 4027 entry Prim_Op; -- Illegal 4028end Task_Typ; 4029@end example 4030 4031When applied to the procedure_or_entry_NAME of a requeue statement, pragma 4032Implemented determines the runtime behavior of the requeue. Implementation kind 4033By_Entry guarantees that the action of requeueing will proceed from an entry to 4034another entry. Implementation kind By_Protected_Procedure transforms the 4035requeue into a dispatching call, thus eliminating the chance of blocking. Kind 4036By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 4037the target's overriding subprogram kind. 4038 4039@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas 4040@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{77} 4041@section Pragma Implicit_Packing 4042 4043 4044@geindex Rational Profile 4045 4046Syntax: 4047 4048@example 4049pragma Implicit_Packing; 4050@end example 4051 4052This is a configuration pragma that requests implicit packing for packed 4053arrays for which a size clause is given but no explicit pragma Pack or 4054specification of Component_Size is present. It also applies to records 4055where no record representation clause is present. Consider this example: 4056 4057@example 4058type R is array (0 .. 7) of Boolean; 4059for R'Size use 8; 4060@end example 4061 4062In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 4063does not change the layout of a composite object. So the Size clause in the 4064above example is normally rejected, since the default layout of the array uses 40658-bit components, and thus the array requires a minimum of 64 bits. 4066 4067If this declaration is compiled in a region of code covered by an occurrence 4068of the configuration pragma Implicit_Packing, then the Size clause in this 4069and similar examples will cause implicit packing and thus be accepted. For 4070this implicit packing to occur, the type in question must be an array of small 4071components whose size is known at compile time, and the Size clause must 4072specify the exact size that corresponds to the number of elements in the array 4073multiplied by the size in bits of the component type (both single and 4074multi-dimensioned arrays can be controlled with this pragma). 4075 4076@geindex Array packing 4077 4078Similarly, the following example shows the use in the record case 4079 4080@example 4081type r is record 4082 a, b, c, d, e, f, g, h : boolean; 4083 chr : character; 4084end record; 4085for r'size use 16; 4086@end example 4087 4088Without a pragma Pack, each Boolean field requires 8 bits, so the 4089minimum size is 72 bits, but with a pragma Pack, 16 bits would be 4090sufficient. The use of pragma Implicit_Packing allows this record 4091declaration to compile without an explicit pragma Pack. 4092 4093@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas 4094@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{78} 4095@section Pragma Import_Function 4096 4097 4098Syntax: 4099 4100@example 4101pragma Import_Function ( 4102 [Internal =>] LOCAL_NAME, 4103 [, [External =>] EXTERNAL_SYMBOL] 4104 [, [Parameter_Types =>] PARAMETER_TYPES] 4105 [, [Result_Type =>] SUBTYPE_MARK] 4106 [, [Mechanism =>] MECHANISM] 4107 [, [Result_Mechanism =>] MECHANISM_NAME]); 4108 4109EXTERNAL_SYMBOL ::= 4110 IDENTIFIER 4111| static_string_EXPRESSION 4112 4113PARAMETER_TYPES ::= 4114 null 4115| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4116 4117TYPE_DESIGNATOR ::= 4118 subtype_NAME 4119| subtype_Name ' Access 4120 4121MECHANISM ::= 4122 MECHANISM_NAME 4123| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4124 4125MECHANISM_ASSOCIATION ::= 4126 [formal_parameter_NAME =>] MECHANISM_NAME 4127 4128MECHANISM_NAME ::= 4129 Value 4130| Reference 4131@end example 4132 4133This pragma is used in conjunction with a pragma @code{Import} to 4134specify additional information for an imported function. The pragma 4135@code{Import} (or equivalent pragma @code{Interface}) must precede the 4136@code{Import_Function} pragma and both must appear in the same 4137declarative part as the function specification. 4138 4139The @code{Internal} argument must uniquely designate 4140the function to which the 4141pragma applies. If more than one function name exists of this name in 4142the declarative part you must use the @code{Parameter_Types} and 4143@code{Result_Type} parameters to achieve the required unique 4144designation. Subtype marks in these parameters must exactly match the 4145subtypes in the corresponding function specification, using positional 4146notation to match parameters with subtype marks. 4147The form with an @code{'Access} attribute can be used to match an 4148anonymous access parameter. 4149 4150You may optionally use the @code{Mechanism} and @code{Result_Mechanism} 4151parameters to specify passing mechanisms for the 4152parameters and result. If you specify a single mechanism name, it 4153applies to all parameters. Otherwise you may specify a mechanism on a 4154parameter by parameter basis using either positional or named 4155notation. If the mechanism is not specified, the default mechanism 4156is used. 4157 4158@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas 4159@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{79} 4160@section Pragma Import_Object 4161 4162 4163Syntax: 4164 4165@example 4166pragma Import_Object 4167 [Internal =>] LOCAL_NAME 4168 [, [External =>] EXTERNAL_SYMBOL] 4169 [, [Size =>] EXTERNAL_SYMBOL]); 4170 4171EXTERNAL_SYMBOL ::= 4172 IDENTIFIER 4173| static_string_EXPRESSION 4174@end example 4175 4176This pragma designates an object as imported, and apart from the 4177extended rules for external symbols, is identical in effect to the use of 4178the normal @code{Import} pragma applied to an object. Unlike the 4179subprogram case, you need not use a separate @code{Import} pragma, 4180although you may do so (and probably should do so from a portability 4181point of view). @code{size} is syntax checked, but otherwise ignored by 4182GNAT. 4183 4184@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas 4185@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7a} 4186@section Pragma Import_Procedure 4187 4188 4189Syntax: 4190 4191@example 4192pragma Import_Procedure ( 4193 [Internal =>] LOCAL_NAME 4194 [, [External =>] EXTERNAL_SYMBOL] 4195 [, [Parameter_Types =>] PARAMETER_TYPES] 4196 [, [Mechanism =>] MECHANISM]); 4197 4198EXTERNAL_SYMBOL ::= 4199 IDENTIFIER 4200| static_string_EXPRESSION 4201 4202PARAMETER_TYPES ::= 4203 null 4204| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4205 4206TYPE_DESIGNATOR ::= 4207 subtype_NAME 4208| subtype_Name ' Access 4209 4210MECHANISM ::= 4211 MECHANISM_NAME 4212| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4213 4214MECHANISM_ASSOCIATION ::= 4215 [formal_parameter_NAME =>] MECHANISM_NAME 4216 4217MECHANISM_NAME ::= Value | Reference 4218@end example 4219 4220This pragma is identical to @code{Import_Function} except that it 4221applies to a procedure rather than a function and the parameters 4222@code{Result_Type} and @code{Result_Mechanism} are not permitted. 4223 4224@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas 4225@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7b} 4226@section Pragma Import_Valued_Procedure 4227 4228 4229Syntax: 4230 4231@example 4232pragma Import_Valued_Procedure ( 4233 [Internal =>] LOCAL_NAME 4234 [, [External =>] EXTERNAL_SYMBOL] 4235 [, [Parameter_Types =>] PARAMETER_TYPES] 4236 [, [Mechanism =>] MECHANISM]); 4237 4238EXTERNAL_SYMBOL ::= 4239 IDENTIFIER 4240| static_string_EXPRESSION 4241 4242PARAMETER_TYPES ::= 4243 null 4244| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 4245 4246TYPE_DESIGNATOR ::= 4247 subtype_NAME 4248| subtype_Name ' Access 4249 4250MECHANISM ::= 4251 MECHANISM_NAME 4252| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 4253 4254MECHANISM_ASSOCIATION ::= 4255 [formal_parameter_NAME =>] MECHANISM_NAME 4256 4257MECHANISM_NAME ::= Value | Reference 4258@end example 4259 4260This pragma is identical to @code{Import_Procedure} except that the 4261first parameter of @code{LOCAL_NAME}, which must be present, must be of 4262mode @code{out}, and externally the subprogram is treated as a function 4263with this parameter as the result of the function. The purpose of this 4264capability is to allow the use of @code{out} and @code{in out} 4265parameters in interfacing to external functions (which are not permitted 4266in Ada functions). You may optionally use the @code{Mechanism} 4267parameters to specify passing mechanisms for the parameters. 4268If you specify a single mechanism name, it applies to all parameters. 4269Otherwise you may specify a mechanism on a parameter by parameter 4270basis using either positional or named notation. If the mechanism is not 4271specified, the default mechanism is used. 4272 4273Note that it is important to use this pragma in conjunction with a separate 4274pragma Import that specifies the desired convention, since otherwise the 4275default convention is Ada, which is almost certainly not what is required. 4276 4277@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas 4278@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7c} 4279@section Pragma Independent 4280 4281 4282Syntax: 4283 4284@example 4285pragma Independent (Local_NAME); 4286@end example 4287 4288This pragma is standard in Ada 2012 mode (which also provides an aspect 4289of the same name). It is also available as an implementation-defined 4290pragma in all earlier versions. It specifies that the 4291designated object or all objects of the designated type must be 4292independently addressable. This means that separate tasks can safely 4293manipulate such objects. For example, if two components of a record are 4294independent, then two separate tasks may access these two components. 4295This may place 4296constraints on the representation of the object (for instance prohibiting 4297tight packing). 4298 4299@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas 4300@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7d} 4301@section Pragma Independent_Components 4302 4303 4304Syntax: 4305 4306@example 4307pragma Independent_Components (Local_NAME); 4308@end example 4309 4310This pragma is standard in Ada 2012 mode (which also provides an aspect 4311of the same name). It is also available as an implementation-defined 4312pragma in all earlier versions. It specifies that the components of the 4313designated object, or the components of each object of the designated 4314type, must be 4315independently addressable. This means that separate tasks can safely 4316manipulate separate components in the composite object. This may place 4317constraints on the representation of the object (for instance prohibiting 4318tight packing). 4319 4320@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas 4321@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7e}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7f} 4322@section Pragma Initial_Condition 4323 4324 4325Syntax: 4326 4327@example 4328pragma Initial_Condition (boolean_EXPRESSION); 4329@end example 4330 4331For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} 4332in the SPARK 2014 Reference Manual, section 7.1.6. 4333 4334@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas 4335@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{80} 4336@section Pragma Initialize_Scalars 4337 4338 4339@geindex debugging with Initialize_Scalars 4340 4341Syntax: 4342 4343@example 4344pragma Initialize_Scalars 4345 [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; 4346 4347TYPE_VALUE_PAIR ::= 4348 SCALAR_TYPE => static_EXPRESSION 4349 4350SCALAR_TYPE := 4351 Short_Float 4352| Float 4353| Long_Float 4354| Long_Long_Flat 4355| Signed_8 4356| Signed_16 4357| Signed_32 4358| Signed_64 4359| Unsigned_8 4360| Unsigned_16 4361| Unsigned_32 4362| Unsigned_64 4363@end example 4364 4365This pragma is similar to @code{Normalize_Scalars} conceptually but has two 4366important differences. 4367 4368First, there is no requirement for the pragma to be used uniformly in all units 4369of a partition. In particular, it is fine to use this just for some or all of 4370the application units of a partition, without needing to recompile the run-time 4371library. In the case where some units are compiled with the pragma, and some 4372without, then a declaration of a variable where the type is defined in package 4373Standard or is locally declared will always be subject to initialization, as 4374will any declaration of a scalar variable. For composite variables, whether the 4375variable is initialized may also depend on whether the package in which the 4376type of the variable is declared is compiled with the pragma. 4377 4378The other important difference is that the programmer can control the value 4379used for initializing scalar objects. This effect can be achieved in several 4380different ways: 4381 4382 4383@itemize * 4384 4385@item 4386At compile time, the programmer can specify the invalid value for a 4387particular family of scalar types using the optional arguments of the pragma. 4388 4389The compile-time approach is intended to optimize the generated code for the 4390pragma, by possibly using fast operations such as @code{memset}. Note that such 4391optimizations require using values where the bytes all have the same binary 4392representation. 4393 4394@item 4395At bind time, the programmer has several options: 4396 4397 4398@itemize * 4399 4400@item 4401Initialization with invalid values (similar to Normalize_Scalars, though 4402for Initialize_Scalars it is not always possible to determine the invalid 4403values in complex cases like signed component fields with nonstandard 4404sizes). 4405 4406@item 4407Initialization with high values. 4408 4409@item 4410Initialization with low values. 4411 4412@item 4413Initialization with a specific bit pattern. 4414@end itemize 4415 4416See the GNAT User's Guide for binder options for specifying these cases. 4417 4418The bind-time approach is intended to provide fast turnaround for testing 4419with different values, without having to recompile the program. 4420 4421@item 4422At execution time, the programmer can specify the invalid values using an 4423environment variable. See the GNAT User's Guide for details. 4424 4425The execution-time approach is intended to provide fast turnaround for 4426testing with different values, without having to recompile and rebind the 4427program. 4428@end itemize 4429 4430Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction 4431with the enhanced validity checking that is now provided in GNAT, which checks 4432for invalid values under more conditions. Using this feature (see description 4433of the @emph{-gnatV} flag in the GNAT User's Guide) in conjunction with pragma 4434@code{Initialize_Scalars} provides a powerful new tool to assist in the detection 4435of problems caused by uninitialized variables. 4436 4437Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the 4438generated code. This may cause your code to be substantially larger. It may 4439also cause an increase in the amount of stack required, so it is probably a 4440good idea to turn on stack checking (see description of stack checking in the 4441GNAT User's Guide) when using this pragma. 4442 4443@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas 4444@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{81}@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{82} 4445@section Pragma Initializes 4446 4447 4448Syntax: 4449 4450@example 4451pragma Initializes (INITIALIZATION_LIST); 4452 4453INITIALIZATION_LIST ::= 4454 null 4455 | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) 4456 4457INITIALIZATION_ITEM ::= name [=> INPUT_LIST] 4458 4459INPUT_LIST ::= 4460 null 4461 | INPUT 4462 | (INPUT @{, INPUT@}) 4463 4464INPUT ::= name 4465@end example 4466 4467For the semantics of this pragma, see the entry for aspect @code{Initializes} in the 4468SPARK 2014 Reference Manual, section 7.1.5. 4469 4470@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas 4471@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{84} 4472@section Pragma Inline_Always 4473 4474 4475Syntax: 4476 4477@example 4478pragma Inline_Always (NAME [, NAME]); 4479@end example 4480 4481Similar to pragma @code{Inline} except that inlining is unconditional. 4482Inline_Always instructs the compiler to inline every direct call to the 4483subprogram or else to emit a compilation error, independently of any 4484option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level. 4485It is an error to take the address or access of @code{NAME}. It is also an error to 4486apply this pragma to a primitive operation of a tagged type. Thanks to such 4487restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. 4488 4489@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas 4490@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{85} 4491@section Pragma Inline_Generic 4492 4493 4494Syntax: 4495 4496@example 4497pragma Inline_Generic (GNAME @{, GNAME@}); 4498 4499GNAME ::= generic_unit_NAME | generic_instance_NAME 4500@end example 4501 4502This pragma is provided for compatibility with Dec Ada 83. It has 4503no effect in GNAT (which always inlines generics), other 4504than to check that the given names are all names of generic units or 4505generic instances. 4506 4507@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas 4508@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{86} 4509@section Pragma Interface 4510 4511 4512Syntax: 4513 4514@example 4515pragma Interface ( 4516 [Convention =>] convention_identifier, 4517 [Entity =>] local_NAME 4518 [, [External_Name =>] static_string_expression] 4519 [, [Link_Name =>] static_string_expression]); 4520@end example 4521 4522This pragma is identical in syntax and semantics to 4523the standard Ada pragma @code{Import}. It is provided for compatibility 4524with Ada 83. The definition is upwards compatible both with pragma 4525@code{Interface} as defined in the Ada 83 Reference Manual, and also 4526with some extended implementations of this pragma in certain Ada 83 4527implementations. The only difference between pragma @code{Interface} 4528and pragma @code{Import} is that there is special circuitry to allow 4529both pragmas to appear for the same subprogram entity (normally it 4530is illegal to have multiple @code{Import} pragmas. This is useful in 4531maintaining Ada 83/Ada 95 compatibility and is compatible with other 4532Ada 83 compilers. 4533 4534@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas 4535@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{87} 4536@section Pragma Interface_Name 4537 4538 4539Syntax: 4540 4541@example 4542pragma Interface_Name ( 4543 [Entity =>] LOCAL_NAME 4544 [, [External_Name =>] static_string_EXPRESSION] 4545 [, [Link_Name =>] static_string_EXPRESSION]); 4546@end example 4547 4548This pragma provides an alternative way of specifying the interface name 4549for an interfaced subprogram, and is provided for compatibility with Ada 455083 compilers that use the pragma for this purpose. You must provide at 4551least one of @code{External_Name} or @code{Link_Name}. 4552 4553@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas 4554@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{88} 4555@section Pragma Interrupt_Handler 4556 4557 4558Syntax: 4559 4560@example 4561pragma Interrupt_Handler (procedure_LOCAL_NAME); 4562@end example 4563 4564This program unit pragma is supported for parameterless protected procedures 4565as described in Annex C of the Ada Reference Manual. On the AAMP target 4566the pragma can also be specified for nonprotected parameterless procedures 4567that are declared at the library level (which includes procedures 4568declared at the top level of a library package). In the case of AAMP, 4569when this pragma is applied to a nonprotected procedure, the instruction 4570@code{IERET} is generated for returns from the procedure, enabling 4571maskable interrupts, in place of the normal return instruction. 4572 4573@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas 4574@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{89} 4575@section Pragma Interrupt_State 4576 4577 4578Syntax: 4579 4580@example 4581pragma Interrupt_State 4582 ([Name =>] value, 4583 [State =>] SYSTEM | RUNTIME | USER); 4584@end example 4585 4586Normally certain interrupts are reserved to the implementation. Any attempt 4587to attach an interrupt causes Program_Error to be raised, as described in 4588RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 4589many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is 4590reserved to the implementation, so that @code{Ctrl-C} can be used to 4591interrupt execution. Additionally, signals such as @code{SIGSEGV}, 4592@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific 4593Ada exceptions, or used to implement run-time functions such as the 4594@code{abort} statement and stack overflow checking. 4595 4596Pragma @code{Interrupt_State} provides a general mechanism for overriding 4597such uses of interrupts. It subsumes the functionality of pragma 4598@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not 4599available on Windows. On all other platforms than VxWorks, 4600it applies to signals; on VxWorks, it applies to vectored hardware interrupts 4601and may be used to mark interrupts required by the board support package 4602as reserved. 4603 4604Interrupts can be in one of three states: 4605 4606 4607@itemize * 4608 4609@item 4610System 4611 4612The interrupt is reserved (no Ada handler can be installed), and the 4613Ada run-time may not install a handler. As a result you are guaranteed 4614standard system default action if this interrupt is raised. This also allows 4615installing a low level handler via C APIs such as sigaction(), outside 4616of Ada control. 4617 4618@item 4619Runtime 4620 4621The interrupt is reserved (no Ada handler can be installed). The run time 4622is allowed to install a handler for internal control purposes, but is 4623not required to do so. 4624 4625@item 4626User 4627 4628The interrupt is unreserved. The user may install an Ada handler via 4629Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide 4630some other action. 4631@end itemize 4632 4633These states are the allowed values of the @code{State} parameter of the 4634pragma. The @code{Name} parameter is a value of the type 4635@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 4636@code{Ada.Interrupts.Names}. 4637 4638This is a configuration pragma, and the binder will check that there 4639are no inconsistencies between different units in a partition in how a 4640given interrupt is specified. It may appear anywhere a pragma is legal. 4641 4642The effect is to move the interrupt to the specified state. 4643 4644By declaring interrupts to be SYSTEM, you guarantee the standard system 4645action, such as a core dump. 4646 4647By declaring interrupts to be USER, you guarantee that you can install 4648a handler. 4649 4650Note that certain signals on many operating systems cannot be caught and 4651handled by applications. In such cases, the pragma is ignored. See the 4652operating system documentation, or the value of the array @code{Reserved} 4653declared in the spec of package @code{System.OS_Interface}. 4654 4655Overriding the default state of signals used by the Ada runtime may interfere 4656with an application's runtime behavior in the cases of the synchronous signals, 4657and in the case of the signal used to implement the @code{abort} statement. 4658 4659@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas 4660@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{8a}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8b} 4661@section Pragma Invariant 4662 4663 4664Syntax: 4665 4666@example 4667pragma Invariant 4668 ([Entity =>] private_type_LOCAL_NAME, 4669 [Check =>] EXPRESSION 4670 [,[Message =>] String_Expression]); 4671@end example 4672 4673This pragma provides exactly the same capabilities as the Type_Invariant aspect 4674defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 4675Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 4676requires the use of the aspect syntax, which is not available except in 2012 4677mode, it is not possible to use the Type_Invariant aspect in earlier versions 4678of Ada. However the Invariant pragma may be used in any version of Ada. Also 4679note that the aspect Invariant is a synonym in GNAT for the aspect 4680Type_Invariant, but there is no pragma Type_Invariant. 4681 4682The pragma must appear within the visible part of the package specification, 4683after the type to which its Entity argument appears. As with the Invariant 4684aspect, the Check expression is not analyzed until the end of the visible 4685part of the package, so it may contain forward references. The Message 4686argument, if present, provides the exception message used if the invariant 4687is violated. If no Message parameter is provided, a default message that 4688identifies the line on which the pragma appears is used. 4689 4690It is permissible to have multiple Invariants for the same type entity, in 4691which case they are and'ed together. It is permissible to use this pragma 4692in Ada 2012 mode, but you cannot have both an invariant aspect and an 4693invariant pragma for the same entity. 4694 4695For further details on the use of this pragma, see the Ada 2012 documentation 4696of the Type_Invariant aspect. 4697 4698@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas 4699@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8c} 4700@section Pragma Keep_Names 4701 4702 4703Syntax: 4704 4705@example 4706pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 4707@end example 4708 4709The @code{LOCAL_NAME} argument 4710must refer to an enumeration first subtype 4711in the current declarative part. The effect is to retain the enumeration 4712literal names for use by @code{Image} and @code{Value} even if a global 4713@code{Discard_Names} pragma applies. This is useful when you want to 4714generally suppress enumeration literal names and for example you therefore 4715use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you 4716want to retain the names for specific enumeration types. 4717 4718@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas 4719@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8d} 4720@section Pragma License 4721 4722 4723@geindex License checking 4724 4725Syntax: 4726 4727@example 4728pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 4729@end example 4730 4731This pragma is provided to allow automated checking for appropriate license 4732conditions with respect to the standard and modified GPL. A pragma 4733@code{License}, which is a configuration pragma that typically appears at 4734the start of a source file or in a separate @code{gnat.adc} file, specifies 4735the licensing conditions of a unit as follows: 4736 4737 4738@itemize * 4739 4740@item 4741Unrestricted 4742This is used for a unit that can be freely used with no license restrictions. 4743Examples of such units are public domain units, and units from the Ada 4744Reference Manual. 4745 4746@item 4747GPL 4748This is used for a unit that is licensed under the unmodified GPL, and which 4749therefore cannot be @code{with}ed by a restricted unit. 4750 4751@item 4752Modified_GPL 4753This is used for a unit licensed under the GNAT modified GPL that includes 4754a special exception paragraph that specifically permits the inclusion of 4755the unit in programs without requiring the entire program to be released 4756under the GPL. 4757 4758@item 4759Restricted 4760This is used for a unit that is restricted in that it is not permitted to 4761depend on units that are licensed under the GPL. Typical examples are 4762proprietary code that is to be released under more restrictive license 4763conditions. Note that restricted units are permitted to @code{with} units 4764which are licensed under the modified GPL (this is the whole point of the 4765modified GPL). 4766@end itemize 4767 4768Normally a unit with no @code{License} pragma is considered to have an 4769unknown license, and no checking is done. However, standard GNAT headers 4770are recognized, and license information is derived from them as follows. 4771 4772A GNAT license header starts with a line containing 78 hyphens. The following 4773comment text is searched for the appearance of any of the following strings. 4774 4775If the string 'GNU General Public License' is found, then the unit is assumed 4776to have GPL license, unless the string 'As a special exception' follows, in 4777which case the license is assumed to be modified GPL. 4778 4779If one of the strings 4780'This specification is adapted from the Ada Semantic Interface' or 4781'This specification is derived from the Ada Reference Manual' is found 4782then the unit is assumed to be unrestricted. 4783 4784These default actions means that a program with a restricted license pragma 4785will automatically get warnings if a GPL unit is inappropriately 4786@code{with}ed. For example, the program: 4787 4788@example 4789with Sem_Ch3; 4790with GNAT.Sockets; 4791procedure Secret_Stuff is 4792 ... 4793end Secret_Stuff 4794@end example 4795 4796if compiled with pragma @code{License} (@code{Restricted}) in a 4797@code{gnat.adc} file will generate the warning: 4798 4799@example 48001. with Sem_Ch3; 4801 | 4802 >>> license of withed unit "Sem_Ch3" is incompatible 4803 48042. with GNAT.Sockets; 48053. procedure Secret_Stuff is 4806@end example 4807 4808Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT 4809compiler and is licensed under the 4810GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 4811run time, and is therefore licensed under the modified GPL. 4812 4813@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas 4814@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8e} 4815@section Pragma Link_With 4816 4817 4818Syntax: 4819 4820@example 4821pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 4822@end example 4823 4824This pragma is provided for compatibility with certain Ada 83 compilers. 4825It has exactly the same effect as pragma @code{Linker_Options} except 4826that spaces occurring within one of the string expressions are treated 4827as separators. For example, in the following case: 4828 4829@example 4830pragma Link_With ("-labc -ldef"); 4831@end example 4832 4833results in passing the strings @code{-labc} and @code{-ldef} as two 4834separate arguments to the linker. In addition pragma Link_With allows 4835multiple arguments, with the same effect as successive pragmas. 4836 4837@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas 4838@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8f} 4839@section Pragma Linker_Alias 4840 4841 4842Syntax: 4843 4844@example 4845pragma Linker_Alias ( 4846 [Entity =>] LOCAL_NAME, 4847 [Target =>] static_string_EXPRESSION); 4848@end example 4849 4850@code{LOCAL_NAME} must refer to an object that is declared at the library 4851level. This pragma establishes the given entity as a linker alias for the 4852given target. It is equivalent to @code{__attribute__((alias))} in GNU C 4853and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol 4854@code{static_string_EXPRESSION} in the object file, that is to say no space 4855is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved 4856to the same address as @code{static_string_EXPRESSION} by the linker. 4857 4858The actual linker name for the target must be used (e.g., the fully 4859encoded name with qualification in Ada, or the mangled name in C++), 4860or it must be declared using the C convention with @code{pragma Import} 4861or @code{pragma Export}. 4862 4863Not all target machines support this pragma. On some of them it is accepted 4864only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. 4865 4866@example 4867-- Example of the use of pragma Linker_Alias 4868 4869package p is 4870 i : Integer := 1; 4871 pragma Export (C, i); 4872 4873 new_name_for_i : Integer; 4874 pragma Linker_Alias (new_name_for_i, "i"); 4875end p; 4876@end example 4877 4878@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas 4879@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{90} 4880@section Pragma Linker_Constructor 4881 4882 4883Syntax: 4884 4885@example 4886pragma Linker_Constructor (procedure_LOCAL_NAME); 4887@end example 4888 4889@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4890is declared at the library level. A procedure to which this pragma is 4891applied will be treated as an initialization routine by the linker. 4892It is equivalent to @code{__attribute__((constructor))} in GNU C and 4893causes @code{procedure_LOCAL_NAME} to be invoked before the entry point 4894of the executable is called (or immediately after the shared library is 4895loaded if the procedure is linked in a shared library), in particular 4896before the Ada run-time environment is set up. 4897 4898Because of these specific contexts, the set of operations such a procedure 4899can perform is very limited and the type of objects it can manipulate is 4900essentially restricted to the elementary types. In particular, it must only 4901contain code to which pragma Restrictions (No_Elaboration_Code) applies. 4902 4903This pragma is used by GNAT to implement auto-initialization of shared Stand 4904Alone Libraries, which provides a related capability without the restrictions 4905listed above. Where possible, the use of Stand Alone Libraries is preferable 4906to the use of this pragma. 4907 4908@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas 4909@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{91} 4910@section Pragma Linker_Destructor 4911 4912 4913Syntax: 4914 4915@example 4916pragma Linker_Destructor (procedure_LOCAL_NAME); 4917@end example 4918 4919@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4920is declared at the library level. A procedure to which this pragma is 4921applied will be treated as a finalization routine by the linker. 4922It is equivalent to @code{__attribute__((destructor))} in GNU C and 4923causes @code{procedure_LOCAL_NAME} to be invoked after the entry point 4924of the executable has exited (or immediately before the shared library 4925is unloaded if the procedure is linked in a shared library), in particular 4926after the Ada run-time environment is shut down. 4927 4928See @code{pragma Linker_Constructor} for the set of restrictions that apply 4929because of these specific contexts. 4930 4931@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas 4932@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{92}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{93} 4933@section Pragma Linker_Section 4934 4935 4936Syntax: 4937 4938@example 4939pragma Linker_Section ( 4940 [Entity =>] LOCAL_NAME, 4941 [Section =>] static_string_EXPRESSION); 4942@end example 4943 4944@code{LOCAL_NAME} must refer to an object, type, or subprogram that is 4945declared at the library level. This pragma specifies the name of the 4946linker section for the given entity. It is equivalent to 4947@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to 4948be placed in the @code{static_string_EXPRESSION} section of the 4949executable (assuming the linker doesn't rename the section). 4950GNAT also provides an implementation defined aspect of the same name. 4951 4952In the case of specifying this aspect for a type, the effect is to 4953specify the corresponding section for all library-level objects of 4954the type that do not have an explicit linker section set. Note that 4955this only applies to whole objects, not to components of composite objects. 4956 4957In the case of a subprogram, the linker section applies to all previously 4958declared matching overloaded subprograms in the current declarative part 4959which do not already have a linker section assigned. The linker section 4960aspect is useful in this case for specifying different linker sections 4961for different elements of such an overloaded set. 4962 4963Note that an empty string specifies that no linker section is specified. 4964This is not quite the same as omitting the pragma or aspect, since it 4965can be used to specify that one element of an overloaded set of subprograms 4966has the default linker section, or that one object of a type for which a 4967linker section is specified should has the default linker section. 4968 4969The compiler normally places library-level entities in standard sections 4970depending on the class: procedures and functions generally go in the 4971@code{.text} section, initialized variables in the @code{.data} section 4972and uninitialized variables in the @code{.bss} section. 4973 4974Other, special sections may exist on given target machines to map special 4975hardware, for example I/O ports or flash memory. This pragma is a means to 4976defer the final layout of the executable to the linker, thus fully working 4977at the symbolic level with the compiler. 4978 4979Some file formats do not support arbitrary sections so not all target 4980machines support this pragma. The use of this pragma may cause a program 4981execution to be erroneous if it is used to place an entity into an 4982inappropriate section (e.g., a modified variable into the @code{.text} 4983section). See also @code{pragma Persistent_BSS}. 4984 4985@example 4986-- Example of the use of pragma Linker_Section 4987 4988package IO_Card is 4989 Port_A : Integer; 4990 pragma Volatile (Port_A); 4991 pragma Linker_Section (Port_A, ".bss.port_a"); 4992 4993 Port_B : Integer; 4994 pragma Volatile (Port_B); 4995 pragma Linker_Section (Port_B, ".bss.port_b"); 4996 4997 type Port_Type is new Integer with Linker_Section => ".bss"; 4998 PA : Port_Type with Linker_Section => ".bss.PA"; 4999 PB : Port_Type; -- ends up in linker section ".bss" 5000 5001 procedure Q with Linker_Section => "Qsection"; 5002end IO_Card; 5003@end example 5004 5005@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas 5006@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{94}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{95} 5007@section Pragma Lock_Free 5008 5009 5010Syntax: 5011This pragma may be specified for protected types or objects. It specifies that 5012the implementation of protected operations must be implemented without locks. 5013Compilation fails if the compiler cannot generate lock-free code for the 5014operations. 5015 5016The current conditions required to support this pragma are: 5017 5018 5019@itemize * 5020 5021@item 5022Protected type declarations may not contain entries 5023 5024@item 5025Protected subprogram declarations may not have nonelementary parameters 5026@end itemize 5027 5028In addition, each protected subprogram body must satisfy: 5029 5030 5031@itemize * 5032 5033@item 5034May reference only one protected component 5035 5036@item 5037May not reference nonconstant entities outside the protected subprogram 5038scope. 5039 5040@item 5041May not contain address representation items, allocators, or quantified 5042expressions. 5043 5044@item 5045May not contain delay, goto, loop, or procedure-call statements. 5046 5047@item 5048May not contain exported and imported entities 5049 5050@item 5051May not dereferenced access values 5052 5053@item 5054Function calls and attribute references must be static 5055@end itemize 5056 5057@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas 5058@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{96} 5059@section Pragma Loop_Invariant 5060 5061 5062Syntax: 5063 5064@example 5065pragma Loop_Invariant ( boolean_EXPRESSION ); 5066@end example 5067 5068The effect of this pragma is similar to that of pragma @code{Assert}, 5069except that in an @code{Assertion_Policy} pragma, the identifier 5070@code{Loop_Invariant} is used to control whether it is ignored or checked 5071(or disabled). 5072 5073@code{Loop_Invariant} can only appear as one of the items in the sequence 5074of statements of a loop body, or nested inside block statements that 5075appear in the sequence of statements of a loop body. 5076The intention is that it be used to 5077represent a "loop invariant" assertion, i.e. something that is true each 5078time through the loop, and which can be used to show that the loop is 5079achieving its purpose. 5080 5081Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5082apply to the same loop should be grouped in the same sequence of 5083statements. 5084 5085To aid in writing such invariants, the special attribute @code{Loop_Entry} 5086may be used to refer to the value of an expression on entry to the loop. This 5087attribute can only be used within the expression of a @code{Loop_Invariant} 5088pragma. For full details, see documentation of attribute @code{Loop_Entry}. 5089 5090@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas 5091@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{97} 5092@section Pragma Loop_Optimize 5093 5094 5095Syntax: 5096 5097@example 5098pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); 5099 5100OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector 5101@end example 5102 5103This pragma must appear immediately within a loop statement. It allows the 5104programmer to specify optimization hints for the enclosing loop. The hints 5105are not mutually exclusive and can be freely mixed, but not all combinations 5106will yield a sensible outcome. 5107 5108There are five supported optimization hints for a loop: 5109 5110 5111@itemize * 5112 5113@item 5114Ivdep 5115 5116The programmer asserts that there are no loop-carried dependencies 5117which would prevent consecutive iterations of the loop from being 5118executed simultaneously. 5119 5120@item 5121No_Unroll 5122 5123The loop must not be unrolled. This is a strong hint: the compiler will not 5124unroll a loop marked with this hint. 5125 5126@item 5127Unroll 5128 5129The loop should be unrolled. This is a weak hint: the compiler will try to 5130apply unrolling to this loop preferably to other optimizations, notably 5131vectorization, but there is no guarantee that the loop will be unrolled. 5132 5133@item 5134No_Vector 5135 5136The loop must not be vectorized. This is a strong hint: the compiler will not 5137vectorize a loop marked with this hint. 5138 5139@item 5140Vector 5141 5142The loop should be vectorized. This is a weak hint: the compiler will try to 5143apply vectorization to this loop preferably to other optimizations, notably 5144unrolling, but there is no guarantee that the loop will be vectorized. 5145@end itemize 5146 5147These hints do not remove the need to pass the appropriate switches to the 5148compiler in order to enable the relevant optimizations, that is to say 5149@emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for 5150vectorization. 5151 5152@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas 5153@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{98} 5154@section Pragma Loop_Variant 5155 5156 5157Syntax: 5158 5159@example 5160pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); 5161LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION 5162CHANGE_DIRECTION ::= Increases | Decreases 5163@end example 5164 5165@code{Loop_Variant} can only appear as one of the items in the sequence 5166of statements of a loop body, or nested inside block statements that 5167appear in the sequence of statements of a loop body. 5168It allows the specification of quantities which must always 5169decrease or increase in successive iterations of the loop. In its simplest 5170form, just one expression is specified, whose value must increase or decrease 5171on each iteration of the loop. 5172 5173In a more complex form, multiple arguments can be given which are intepreted 5174in a nesting lexicographic manner. For example: 5175 5176@example 5177pragma Loop_Variant (Increases => X, Decreases => Y); 5178@end example 5179 5180specifies that each time through the loop either X increases, or X stays 5181the same and Y decreases. A @code{Loop_Variant} pragma ensures that the 5182loop is making progress. It can be useful in helping to show informally 5183or prove formally that the loop always terminates. 5184 5185@code{Loop_Variant} is an assertion whose effect can be controlled using 5186an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The 5187policy can be @code{Check} to enable the loop variant check, @code{Ignore} 5188to ignore the check (in which case the pragma has no effect on the program), 5189or @code{Disable} in which case the pragma is not even checked for correct 5190syntax. 5191 5192Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 5193apply to the same loop should be grouped in the same sequence of 5194statements. 5195 5196The @code{Loop_Entry} attribute may be used within the expressions of the 5197@code{Loop_Variant} pragma to refer to values on entry to the loop. 5198 5199@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas 5200@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{99} 5201@section Pragma Machine_Attribute 5202 5203 5204Syntax: 5205 5206@example 5207pragma Machine_Attribute ( 5208 [Entity =>] LOCAL_NAME, 5209 [Attribute_Name =>] static_string_EXPRESSION 5210 [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); 5211@end example 5212 5213Machine-dependent attributes can be specified for types and/or 5214declarations. This pragma is semantically equivalent to 5215@code{__attribute__((@emph{attribute_name}))} (if @code{info} is not 5216specified) or @code{__attribute__((@emph{attribute_name(info})))} 5217or @code{__attribute__((@emph{attribute_name(info,...})))} in GNU C, 5218where @emph{attribute_name} is recognized by the compiler middle-end 5219or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note 5220that a string literal for the optional parameter @code{info} or the 5221following ones is transformed by default into an identifier, 5222which may make this pragma unusable for some attributes. 5223For further information see @cite{GNU Compiler Collection (GCC) Internals}. 5224 5225@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas 5226@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9a} 5227@section Pragma Main 5228 5229 5230Syntax: 5231 5232@example 5233pragma Main 5234 (MAIN_OPTION [, MAIN_OPTION]); 5235 5236MAIN_OPTION ::= 5237 [Stack_Size =>] static_integer_EXPRESSION 5238| [Task_Stack_Size_Default =>] static_integer_EXPRESSION 5239| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 5240@end example 5241 5242This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5243no effect in GNAT, other than being syntax checked. 5244 5245@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas 5246@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9b} 5247@section Pragma Main_Storage 5248 5249 5250Syntax: 5251 5252@example 5253pragma Main_Storage 5254 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 5255 5256MAIN_STORAGE_OPTION ::= 5257 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 5258| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 5259@end example 5260 5261This pragma is provided for compatibility with OpenVMS VAX Systems. It has 5262no effect in GNAT, other than being syntax checked. 5263 5264@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas 5265@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9c}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9d} 5266@section Pragma Max_Queue_Length 5267 5268 5269Syntax: 5270 5271@example 5272pragma Max_Entry_Queue (static_integer_EXPRESSION); 5273@end example 5274 5275This pragma is used to specify the maximum callers per entry queue for 5276individual protected entries and entry families. It accepts a single 5277integer (-1 or more) as a parameter and must appear after the declaration of an 5278entry. 5279 5280A value of -1 represents no additional restriction on queue length. 5281 5282@node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas 5283@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9e} 5284@section Pragma No_Body 5285 5286 5287Syntax: 5288 5289@example 5290pragma No_Body; 5291@end example 5292 5293There are a number of cases in which a package spec does not require a body, 5294and in fact a body is not permitted. GNAT will not permit the spec to be 5295compiled if there is a body around. The pragma No_Body allows you to provide 5296a body file, even in a case where no body is allowed. The body file must 5297contain only comments and a single No_Body pragma. This is recognized by 5298the compiler as indicating that no body is logically present. 5299 5300This is particularly useful during maintenance when a package is modified in 5301such a way that a body needed before is no longer needed. The provision of a 5302dummy body with a No_Body pragma ensures that there is no interference from 5303earlier versions of the package body. 5304 5305@node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas 5306@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{9f}@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{a0} 5307@section Pragma No_Caching 5308 5309 5310Syntax: 5311 5312@example 5313pragma No_Caching [ (boolean_EXPRESSION) ]; 5314@end example 5315 5316For the semantics of this pragma, see the entry for aspect @code{No_Caching} in 5317the SPARK 2014 Reference Manual, section 7.1.2. 5318 5319@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas 5320@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a1} 5321@section Pragma No_Component_Reordering 5322 5323 5324Syntax: 5325 5326@example 5327pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; 5328@end example 5329 5330@code{type_LOCAL_NAME} must refer to a record type declaration in the current 5331declarative part. The effect is to preclude any reordering of components 5332for the layout of the record, i.e. the record is laid out by the compiler 5333in the order in which the components are declared textually. The form with 5334no argument is a configuration pragma which applies to all record types 5335declared in units to which the pragma applies and there is a requirement 5336that this pragma be used consistently within a partition. 5337 5338@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas 5339@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a2}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a3} 5340@section Pragma No_Elaboration_Code_All 5341 5342 5343Syntax: 5344 5345@example 5346pragma No_Elaboration_Code_All [(program_unit_NAME)]; 5347@end example 5348 5349This is a program unit pragma (there is also an equivalent aspect of the 5350same name) that establishes the restriction @code{No_Elaboration_Code} for 5351the current unit and any extended main source units (body and subunits). 5352It also has the effect of enforcing a transitive application of this 5353aspect, so that if any unit is implicitly or explicitly with'ed by the 5354current unit, it must also have the No_Elaboration_Code_All aspect set. 5355It may be applied to package or subprogram specs or their generic versions. 5356 5357@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas 5358@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a4} 5359@section Pragma No_Heap_Finalization 5360 5361 5362Syntax: 5363 5364@example 5365pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; 5366@end example 5367 5368Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a 5369type-specific pragma. 5370 5371In its configuration form, the pragma must appear within a configuration file 5372such as gnat.adc, without an argument. The pragma suppresses the call to 5373@code{Finalize} for heap-allocated objects created through library-level named 5374access-to-object types in cases where the designated type requires finalization 5375actions. 5376 5377In its type-specific form, the argument of the pragma must denote a 5378library-level named access-to-object type. The pragma suppresses the call to 5379@code{Finalize} for heap-allocated objects created through the specific access type 5380in cases where the designated type requires finalization actions. 5381 5382It is still possible to finalize such heap-allocated objects by explicitly 5383deallocating them. 5384 5385A library-level named access-to-object type declared within a generic unit will 5386lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not 5387appear at the library level. 5388 5389@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas 5390@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a5}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a6} 5391@section Pragma No_Inline 5392 5393 5394Syntax: 5395 5396@example 5397pragma No_Inline (NAME @{, NAME@}); 5398@end example 5399 5400This pragma suppresses inlining for the callable entity or the instances of 5401the generic subprogram designated by @code{NAME}, including inlining that 5402results from the use of pragma @code{Inline}. This pragma is always active, 5403in particular it is not subject to the use of option @emph{-gnatn} or 5404@emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and 5405pragma @code{Inline_Always} for the same @code{NAME}. 5406 5407@node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas 5408@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a7} 5409@section Pragma No_Return 5410 5411 5412Syntax: 5413 5414@example 5415pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); 5416@end example 5417 5418Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure 5419declarations in the current declarative part. A procedure to which this 5420pragma is applied may not contain any explicit @code{return} statements. 5421In addition, if the procedure contains any implicit returns from falling 5422off the end of a statement sequence, then execution of that implicit 5423return will cause Program_Error to be raised. 5424 5425One use of this pragma is to identify procedures whose only purpose is to raise 5426an exception. Another use of this pragma is to suppress incorrect warnings 5427about missing returns in functions, where the last statement of a function 5428statement sequence is a call to such a procedure. 5429 5430Note that in Ada 2005 mode, this pragma is part of the language. It is 5431available in all earlier versions of Ada as an implementation-defined 5432pragma. 5433 5434@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas 5435@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a8} 5436@section Pragma No_Strict_Aliasing 5437 5438 5439Syntax: 5440 5441@example 5442pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 5443@end example 5444 5445@code{type_LOCAL_NAME} must refer to an access type 5446declaration in the current declarative part. The effect is to inhibit 5447strict aliasing optimization for the given type. The form with no 5448arguments is a configuration pragma which applies to all access types 5449declared in units to which the pragma applies. For a detailed 5450description of the strict aliasing optimization, and the situations 5451in which it must be suppressed, see the section on Optimization and Strict Aliasing 5452in the @cite{GNAT User's Guide}. 5453 5454This pragma currently has no effects on access to unconstrained array types. 5455 5456@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas 5457@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{a9}@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{aa} 5458@section Pragma No_Tagged_Streams 5459 5460 5461Syntax: 5462 5463@example 5464pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; 5465@end example 5466 5467Normally when a tagged type is introduced using a full type declaration, 5468part of the processing includes generating stream access routines to be 5469used by stream attributes referencing the type (or one of its subtypes 5470or derived types). This can involve the generation of significant amounts 5471of code which is wasted space if stream routines are not needed for the 5472type in question. 5473 5474The @code{No_Tagged_Streams} pragma causes the generation of these stream 5475routines to be skipped, and any attempt to use stream operations on 5476types subject to this pragma will be statically rejected as illegal. 5477 5478There are two forms of the pragma. The form with no arguments must appear 5479in a declarative sequence or in the declarations of a package spec. This 5480pragma affects all subsequent root tagged types declared in the declaration 5481sequence, and specifies that no stream routines be generated. The form with 5482an argument (for which there is also a corresponding aspect) specifies a 5483single root tagged type for which stream routines are not to be generated. 5484 5485Once the pragma has been given for a particular root tagged type, all subtypes 5486and derived types of this type inherit the pragma automatically, so the effect 5487applies to a complete hierarchy (this is necessary to deal with the class-wide 5488dispatching versions of the stream routines). 5489 5490When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously 5491applied to a tagged type its Expanded_Name and External_Tag are initialized 5492with empty strings. This is useful to avoid exposing entity names at binary 5493level but has a negative impact on the debuggability of tagged types. 5494 5495@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas 5496@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ab} 5497@section Pragma Normalize_Scalars 5498 5499 5500Syntax: 5501 5502@example 5503pragma Normalize_Scalars; 5504@end example 5505 5506This is a language defined pragma which is fully implemented in GNAT. The 5507effect is to cause all scalar objects that are not otherwise initialized 5508to be initialized. The initial values are implementation dependent and 5509are as follows: 5510 5511 5512@table @asis 5513 5514@item @emph{Standard.Character} 5515 5516Objects whose root type is Standard.Character are initialized to 5517Character'Last unless the subtype range excludes NUL (in which case 5518NUL is used). This choice will always generate an invalid value if 5519one exists. 5520 5521@item @emph{Standard.Wide_Character} 5522 5523Objects whose root type is Standard.Wide_Character are initialized to 5524Wide_Character'Last unless the subtype range excludes NUL (in which case 5525NUL is used). This choice will always generate an invalid value if 5526one exists. 5527 5528@item @emph{Standard.Wide_Wide_Character} 5529 5530Objects whose root type is Standard.Wide_Wide_Character are initialized to 5531the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 5532which case NUL is used). This choice will always generate an invalid value if 5533one exists. 5534 5535@item @emph{Integer types} 5536 5537Objects of an integer type are treated differently depending on whether 5538negative values are present in the subtype. If no negative values are 5539present, then all one bits is used as the initial value except in the 5540special case where zero is excluded from the subtype, in which case 5541all zero bits are used. This choice will always generate an invalid 5542value if one exists. 5543 5544For subtypes with negative values present, the largest negative number 5545is used, except in the unusual case where this largest negative number 5546is in the subtype, and the largest positive number is not, in which case 5547the largest positive value is used. This choice will always generate 5548an invalid value if one exists. 5549 5550@item @emph{Floating-Point Types} 5551 5552Objects of all floating-point types are initialized to all 1-bits. For 5553standard IEEE format, this corresponds to a NaN (not a number) which is 5554indeed an invalid value. 5555 5556@item @emph{Fixed-Point Types} 5557 5558Objects of all fixed-point types are treated as described above for integers, 5559with the rules applying to the underlying integer value used to represent 5560the fixed-point value. 5561 5562@item @emph{Modular types} 5563 5564Objects of a modular type are initialized to all one bits, except in 5565the special case where zero is excluded from the subtype, in which 5566case all zero bits are used. This choice will always generate an 5567invalid value if one exists. 5568 5569@item @emph{Enumeration types} 5570 5571Objects of an enumeration type are initialized to all one-bits, i.e., to 5572the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal 5573whose Pos value is zero, in which case a code of zero is used. This choice 5574will always generate an invalid value if one exists. 5575@end table 5576 5577@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas 5578@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ac}@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ad} 5579@section Pragma Obsolescent 5580 5581 5582Syntax: 5583 5584@example 5585pragma Obsolescent; 5586 5587pragma Obsolescent ( 5588 [Message =>] static_string_EXPRESSION 5589[,[Version =>] Ada_05]]); 5590 5591pragma Obsolescent ( 5592 [Entity =>] NAME 5593[,[Message =>] static_string_EXPRESSION 5594[,[Version =>] Ada_05]] ); 5595@end example 5596 5597This pragma can occur immediately following a declaration of an entity, 5598including the case of a record component. If no Entity argument is present, 5599then this declaration is the one to which the pragma applies. If an Entity 5600parameter is present, it must either match the name of the entity in this 5601declaration, or alternatively, the pragma can immediately follow an enumeration 5602type declaration, where the Entity argument names one of the enumeration 5603literals. 5604 5605This pragma is used to indicate that the named entity 5606is considered obsolescent and should not be used. Typically this is 5607used when an API must be modified by eventually removing or modifying 5608existing subprograms or other entities. The pragma can be used at an 5609intermediate stage when the entity is still present, but will be 5610removed later. 5611 5612The effect of this pragma is to output a warning message on a reference to 5613an entity thus marked that the subprogram is obsolescent if the appropriate 5614warning option in the compiler is activated. If the @code{Message} parameter is 5615present, then a second warning message is given containing this text. In 5616addition, a reference to the entity is considered to be a violation of pragma 5617@code{Restrictions (No_Obsolescent_Features)}. 5618 5619This pragma can also be used as a program unit pragma for a package, 5620in which case the entity name is the name of the package, and the 5621pragma indicates that the entire package is considered 5622obsolescent. In this case a client @code{with}ing such a package 5623violates the restriction, and the @code{with} clause is 5624flagged with warnings if the warning option is set. 5625 5626If the @code{Version} parameter is present (which must be exactly 5627the identifier @code{Ada_05}, no other argument is allowed), then the 5628indication of obsolescence applies only when compiling in Ada 2005 5629mode. This is primarily intended for dealing with the situations 5630in the predefined library where subprograms or packages 5631have become defined as obsolescent in Ada 2005 5632(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. 5633 5634The following examples show typical uses of this pragma: 5635 5636@example 5637package p is 5638 pragma Obsolescent (p, Message => "use pp instead of p"); 5639end p; 5640 5641package q is 5642 procedure q2; 5643 pragma Obsolescent ("use q2new instead"); 5644 5645 type R is new integer; 5646 pragma Obsolescent 5647 (Entity => R, 5648 Message => "use RR in Ada 2005", 5649 Version => Ada_05); 5650 5651 type M is record 5652 F1 : Integer; 5653 F2 : Integer; 5654 pragma Obsolescent; 5655 F3 : Integer; 5656 end record; 5657 5658 type E is (a, bc, 'd', quack); 5659 pragma Obsolescent (Entity => bc) 5660 pragma Obsolescent (Entity => 'd') 5661 5662 function "+" 5663 (a, b : character) return character; 5664 pragma Obsolescent (Entity => "+"); 5665end; 5666@end example 5667 5668Note that, as for all pragmas, if you use a pragma argument identifier, 5669then all subsequent parameters must also use a pragma argument identifier. 5670So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} 5671argument is present, it must be preceded by @code{Message =>}. 5672 5673@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas 5674@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ae} 5675@section Pragma Optimize_Alignment 5676 5677 5678@geindex Alignment 5679@geindex default settings 5680 5681Syntax: 5682 5683@example 5684pragma Optimize_Alignment (TIME | SPACE | OFF); 5685@end example 5686 5687This is a configuration pragma which affects the choice of default alignments 5688for types and objects where no alignment is explicitly specified. There is a 5689time/space trade-off in the selection of these values. Large alignments result 5690in more efficient code, at the expense of larger data space, since sizes have 5691to be increased to match these alignments. Smaller alignments save space, but 5692the access code is slower. The normal choice of default alignments for types 5693and individual alignment promotions for objects (which is what you get if you 5694do not use this pragma, or if you use an argument of OFF), tries to balance 5695these two requirements. 5696 5697Specifying SPACE causes smaller default alignments to be chosen in two cases. 5698First any packed record is given an alignment of 1. Second, if a size is given 5699for the type, then the alignment is chosen to avoid increasing this size. For 5700example, consider: 5701 5702@example 5703type R is record 5704 X : Integer; 5705 Y : Character; 5706end record; 5707 5708for R'Size use 5*8; 5709@end example 5710 5711In the default mode, this type gets an alignment of 4, so that access to the 5712Integer field X are efficient. But this means that objects of the type end up 5713with a size of 8 bytes. This is a valid choice, since sizes of objects are 5714allowed to be bigger than the size of the type, but it can waste space if for 5715example fields of type R appear in an enclosing record. If the above type is 5716compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. 5717 5718However, there is one case in which SPACE is ignored. If a variable length 5719record (that is a discriminated record with a component which is an array 5720whose length depends on a discriminant), has a pragma Pack, then it is not 5721in general possible to set the alignment of such a record to one, so the 5722pragma is ignored in this case (with a warning). 5723 5724Specifying SPACE also disables alignment promotions for standalone objects, 5725which occur when the compiler increases the alignment of a specific object 5726without changing the alignment of its type. 5727 5728Specifying SPACE also disables component reordering in unpacked record types, 5729which can result in larger sizes in order to meet alignment requirements. 5730 5731Specifying TIME causes larger default alignments to be chosen in the case of 5732small types with sizes that are not a power of 2. For example, consider: 5733 5734@example 5735type R is record 5736 A : Character; 5737 B : Character; 5738 C : Boolean; 5739end record; 5740 5741pragma Pack (R); 5742for R'Size use 17; 5743@end example 5744 5745The default alignment for this record is normally 1, but if this type is 5746compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set 5747to 4, which wastes space for objects of the type, since they are now 4 bytes 5748long, but results in more efficient access when the whole record is referenced. 5749 5750As noted above, this is a configuration pragma, and there is a requirement 5751that all units in a partition be compiled with a consistent setting of the 5752optimization setting. This would normally be achieved by use of a configuration 5753pragma file containing the appropriate setting. The exception to this rule is 5754that units with an explicit configuration pragma in the same file as the source 5755unit are excluded from the consistency check, as are all predefined units. The 5756latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 5757pragma appears at the start of the file. 5758 5759@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas 5760@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{af} 5761@section Pragma Ordered 5762 5763 5764Syntax: 5765 5766@example 5767pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 5768@end example 5769 5770Most enumeration types are from a conceptual point of view unordered. 5771For example, consider: 5772 5773@example 5774type Color is (Red, Blue, Green, Yellow); 5775@end example 5776 5777By Ada semantics @code{Blue > Red} and @code{Green > Blue}, 5778but really these relations make no sense; the enumeration type merely 5779specifies a set of possible colors, and the order is unimportant. 5780 5781For unordered enumeration types, it is generally a good idea if 5782clients avoid comparisons (other than equality or inequality) and 5783explicit ranges. (A @emph{client} is a unit where the type is referenced, 5784other than the unit where the type is declared, its body, and its subunits.) 5785For example, if code buried in some client says: 5786 5787@example 5788if Current_Color < Yellow then ... 5789if Current_Color in Blue .. Green then ... 5790@end example 5791 5792then the client code is relying on the order, which is undesirable. 5793It makes the code hard to read and creates maintenance difficulties if 5794entries have to be added to the enumeration type. Instead, 5795the code in the client should list the possibilities, or an 5796appropriate subtype should be declared in the unit that declares 5797the original enumeration type. E.g., the following subtype could 5798be declared along with the type @code{Color}: 5799 5800@example 5801subtype RBG is Color range Red .. Green; 5802@end example 5803 5804and then the client could write: 5805 5806@example 5807if Current_Color in RBG then ... 5808if Current_Color = Blue or Current_Color = Green then ... 5809@end example 5810 5811However, some enumeration types are legitimately ordered from a conceptual 5812point of view. For example, if you declare: 5813 5814@example 5815type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 5816@end example 5817 5818then the ordering imposed by the language is reasonable, and 5819clients can depend on it, writing for example: 5820 5821@example 5822if D in Mon .. Fri then ... 5823if D < Wed then ... 5824@end example 5825 5826The pragma @emph{Ordered} is provided to mark enumeration types that 5827are conceptually ordered, alerting the reader that clients may depend 5828on the ordering. GNAT provides a pragma to mark enumerations as ordered 5829rather than one to mark them as unordered, since in our experience, 5830the great majority of enumeration types are conceptually unordered. 5831 5832The types @code{Boolean}, @code{Character}, @code{Wide_Character}, 5833and @code{Wide_Wide_Character} 5834are considered to be ordered types, so each is declared with a 5835pragma @code{Ordered} in package @code{Standard}. 5836 5837Normally pragma @code{Ordered} serves only as documentation and a guide for 5838coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that 5839requests warnings for inappropriate uses (comparisons and explicit 5840subranges) for unordered types. If this switch is used, then any 5841enumeration type not marked with pragma @code{Ordered} will be considered 5842as unordered, and will generate warnings for inappropriate uses. 5843 5844Note that generic types are not considered ordered or unordered (since the 5845template can be instantiated for both cases), so we never generate warnings 5846for the case of generic enumerated types. 5847 5848For additional information please refer to the description of the 5849@emph{-gnatw.u} switch in the GNAT User's Guide. 5850 5851@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas 5852@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b0} 5853@section Pragma Overflow_Mode 5854 5855 5856Syntax: 5857 5858@example 5859pragma Overflow_Mode 5860 ( [General =>] MODE 5861 [,[Assertions =>] MODE]); 5862 5863MODE ::= STRICT | MINIMIZED | ELIMINATED 5864@end example 5865 5866This pragma sets the current overflow mode to the given setting. For details 5867of the meaning of these modes, please refer to the 5868'Overflow Check Handling in GNAT' appendix in the 5869GNAT User's Guide. If only the @code{General} parameter is present, 5870the given mode applies to all expressions. If both parameters are present, 5871the @code{General} mode applies to expressions outside assertions, and 5872the @code{Eliminated} mode applies to expressions within assertions. 5873 5874The case of the @code{MODE} parameter is ignored, 5875so @code{MINIMIZED}, @code{Minimized} and 5876@code{minimized} all have the same effect. 5877 5878The @code{Overflow_Mode} pragma has the same scoping and placement 5879rules as pragma @code{Suppress}, so it can occur either as a 5880configuration pragma, specifying a default for the whole 5881program, or in a declarative scope, where it applies to the 5882remaining declarations and statements in that scope. 5883 5884The pragma @code{Suppress (Overflow_Check)} suppresses 5885overflow checking, but does not affect the overflow mode. 5886 5887The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) 5888overflow checking, but does not affect the overflow mode. 5889 5890@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas 5891@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b1} 5892@section Pragma Overriding_Renamings 5893 5894 5895@geindex Rational profile 5896 5897@geindex Rational compatibility 5898 5899Syntax: 5900 5901@example 5902pragma Overriding_Renamings; 5903@end example 5904 5905This is a GNAT configuration pragma to simplify porting 5906legacy code accepted by the Rational 5907Ada compiler. In the presence of this pragma, a renaming declaration that 5908renames an inherited operation declared in the same scope is legal if selected 5909notation is used as in: 5910 5911@example 5912pragma Overriding_Renamings; 5913... 5914package R is 5915 function F (..); 5916 ... 5917 function F (..) renames R.F; 5918end R; 5919@end example 5920 5921even though 5922RM 8.3 (15) stipulates that an overridden operation is not visible within the 5923declaration of the overriding operation. 5924 5925@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas 5926@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b2} 5927@section Pragma Partition_Elaboration_Policy 5928 5929 5930Syntax: 5931 5932@example 5933pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 5934 5935POLICY_IDENTIFIER ::= Concurrent | Sequential 5936@end example 5937 5938This pragma is standard in Ada 2005, but is available in all earlier 5939versions of Ada as an implementation-defined pragma. 5940See Ada 2012 Reference Manual for details. 5941 5942@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas 5943@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b3}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b4} 5944@section Pragma Part_Of 5945 5946 5947Syntax: 5948 5949@example 5950pragma Part_Of (ABSTRACT_STATE); 5951 5952ABSTRACT_STATE ::= NAME 5953@end example 5954 5955For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the 5956SPARK 2014 Reference Manual, section 7.2.6. 5957 5958@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas 5959@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b5} 5960@section Pragma Passive 5961 5962 5963Syntax: 5964 5965@example 5966pragma Passive [(Semaphore | No)]; 5967@end example 5968 5969Syntax checked, but otherwise ignored by GNAT. This is recognized for 5970compatibility with DEC Ada 83 implementations, where it is used within a 5971task definition to request that a task be made passive. If the argument 5972@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 5973treats the pragma as an assertion that the containing task is passive 5974and that optimization of context switch with this task is permitted and 5975desired. If the argument @code{No} is present, the task must not be 5976optimized. GNAT does not attempt to optimize any tasks in this manner 5977(since protected objects are available in place of passive tasks). 5978 5979For more information on the subject of passive tasks, see the section 5980'Passive Task Optimization' in the GNAT Users Guide. 5981 5982@node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas 5983@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b6}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b7} 5984@section Pragma Persistent_BSS 5985 5986 5987Syntax: 5988 5989@example 5990pragma Persistent_BSS [(LOCAL_NAME)] 5991@end example 5992 5993This pragma allows selected objects to be placed in the @code{.persistent_bss} 5994section. On some targets the linker and loader provide for special 5995treatment of this section, allowing a program to be reloaded without 5996affecting the contents of this data (hence the name persistent). 5997 5998There are two forms of usage. If an argument is given, it must be the 5999local name of a library-level object, with no explicit initialization 6000and whose type is potentially persistent. If no argument is given, then 6001the pragma is a configuration pragma, and applies to all library-level 6002objects with no explicit initialization of potentially persistent types. 6003 6004A potentially persistent type is a scalar type, or an untagged, 6005non-discriminated record, all of whose components have no explicit 6006initialization and are themselves of a potentially persistent type, 6007or an array, all of whose constraints are static, and whose component 6008type is potentially persistent. 6009 6010If this pragma is used on a target where this feature is not supported, 6011then the pragma will be ignored. See also @code{pragma Linker_Section}. 6012 6013@node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas 6014@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b8} 6015@section Pragma Post 6016 6017 6018@geindex Post 6019 6020@geindex Checks 6021@geindex postconditions 6022 6023Syntax: 6024 6025@example 6026pragma Post (Boolean_Expression); 6027@end example 6028 6029The @code{Post} pragma is intended to be an exact replacement for 6030the language-defined 6031@code{Post} aspect, and shares its restrictions and semantics. 6032It must appear either immediately following the corresponding 6033subprogram declaration (only other pragmas may intervene), or 6034if there is no separate subprogram declaration, then it can 6035appear at the start of the declarations in a subprogram body 6036(preceded only by other pragmas). 6037 6038@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas 6039@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b9} 6040@section Pragma Postcondition 6041 6042 6043@geindex Postcondition 6044 6045@geindex Checks 6046@geindex postconditions 6047 6048Syntax: 6049 6050@example 6051pragma Postcondition ( 6052 [Check =>] Boolean_Expression 6053 [,[Message =>] String_Expression]); 6054@end example 6055 6056The @code{Postcondition} pragma allows specification of automatic 6057postcondition checks for subprograms. These checks are similar to 6058assertions, but are automatically inserted just prior to the return 6059statements of the subprogram with which they are associated (including 6060implicit returns at the end of procedure bodies and associated 6061exception handlers). 6062 6063In addition, the boolean expression which is the condition which 6064must be true may contain references to function'Result in the case 6065of a function to refer to the returned value. 6066 6067@code{Postcondition} pragmas may appear either immediately following the 6068(separate) declaration of a subprogram, or at the start of the 6069declarations of a subprogram body. Only other pragmas may intervene 6070(that is appear between the subprogram declaration and its 6071postconditions, or appear before the postcondition in the 6072declaration sequence in a subprogram body). In the case of a 6073postcondition appearing after a subprogram declaration, the 6074formal arguments of the subprogram are visible, and can be 6075referenced in the postcondition expressions. 6076 6077The postconditions are collected and automatically tested just 6078before any return (implicit or explicit) in the subprogram body. 6079A postcondition is only recognized if postconditions are active 6080at the time the pragma is encountered. The compiler switch @emph{gnata} 6081turns on all postconditions by default, and pragma @code{Check_Policy} 6082with an identifier of @code{Postcondition} can also be used to 6083control whether postconditions are active. 6084 6085The general approach is that postconditions are placed in the spec 6086if they represent functional aspects which make sense to the client. 6087For example we might have: 6088 6089@example 6090function Direction return Integer; 6091pragma Postcondition 6092 (Direction'Result = +1 6093 or else 6094 Direction'Result = -1); 6095@end example 6096 6097which serves to document that the result must be +1 or -1, and 6098will test that this is the case at run time if postcondition 6099checking is active. 6100 6101Postconditions within the subprogram body can be used to 6102check that some internal aspect of the implementation, 6103not visible to the client, is operating as expected. 6104For instance if a square root routine keeps an internal 6105counter of the number of times it is called, then we 6106might have the following postcondition: 6107 6108@example 6109Sqrt_Calls : Natural := 0; 6110 6111function Sqrt (Arg : Float) return Float is 6112 pragma Postcondition 6113 (Sqrt_Calls = Sqrt_Calls'Old + 1); 6114 ... 6115end Sqrt 6116@end example 6117 6118As this example, shows, the use of the @code{Old} attribute 6119is often useful in postconditions to refer to the state on 6120entry to the subprogram. 6121 6122Note that postconditions are only checked on normal returns 6123from the subprogram. If an abnormal return results from 6124raising an exception, then the postconditions are not checked. 6125 6126If a postcondition fails, then the exception 6127@code{System.Assertions.Assert_Failure} is raised. If 6128a message argument was supplied, then the given string 6129will be used as the exception message. If no message 6130argument was supplied, then the default message has 6131the form "Postcondition failed at file_name:line". The 6132exception is raised in the context of the subprogram 6133body, so it is possible to catch postcondition failures 6134within the subprogram body itself. 6135 6136Within a package spec, normal visibility rules 6137in Ada would prevent forward references within a 6138postcondition pragma to functions defined later in 6139the same package. This would introduce undesirable 6140ordering constraints. To avoid this problem, all 6141postcondition pragmas are analyzed at the end of 6142the package spec, allowing forward references. 6143 6144The following example shows that this even allows 6145mutually recursive postconditions as in: 6146 6147@example 6148package Parity_Functions is 6149 function Odd (X : Natural) return Boolean; 6150 pragma Postcondition 6151 (Odd'Result = 6152 (x = 1 6153 or else 6154 (x /= 0 and then Even (X - 1)))); 6155 6156 function Even (X : Natural) return Boolean; 6157 pragma Postcondition 6158 (Even'Result = 6159 (x = 0 6160 or else 6161 (x /= 1 and then Odd (X - 1)))); 6162 6163end Parity_Functions; 6164@end example 6165 6166There are no restrictions on the complexity or form of 6167conditions used within @code{Postcondition} pragmas. 6168The following example shows that it is even possible 6169to verify performance behavior. 6170 6171@example 6172package Sort is 6173 6174 Performance : constant Float; 6175 -- Performance constant set by implementation 6176 -- to match target architecture behavior. 6177 6178 procedure Treesort (Arg : String); 6179 -- Sorts characters of argument using N*logN sort 6180 pragma Postcondition 6181 (Float (Clock - Clock'Old) <= 6182 Float (Arg'Length) * 6183 log (Float (Arg'Length)) * 6184 Performance); 6185end Sort; 6186@end example 6187 6188Note: postcondition pragmas associated with subprograms that are 6189marked as Inline_Always, or those marked as Inline with front-end 6190inlining (-gnatN option set) are accepted and legality-checked 6191by the compiler, but are ignored at run-time even if postcondition 6192checking is enabled. 6193 6194Note that pragma @code{Postcondition} differs from the language-defined 6195@code{Post} aspect (and corresponding @code{Post} pragma) in allowing 6196multiple occurrences, allowing occurences in the body even if there 6197is a separate spec, and allowing a second string parameter, and the 6198use of the pragma identifier @code{Check}. Historically, pragma 6199@code{Postcondition} was implemented prior to the development of 6200Ada 2012, and has been retained in its original form for 6201compatibility purposes. 6202 6203@node Pragma Post_Class,Pragma Rename_Pragma,Pragma Postcondition,Implementation Defined Pragmas 6204@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{ba} 6205@section Pragma Post_Class 6206 6207 6208@geindex Post 6209 6210@geindex Checks 6211@geindex postconditions 6212 6213Syntax: 6214 6215@example 6216pragma Post_Class (Boolean_Expression); 6217@end example 6218 6219The @code{Post_Class} pragma is intended to be an exact replacement for 6220the language-defined 6221@code{Post'Class} aspect, and shares its restrictions and semantics. 6222It must appear either immediately following the corresponding 6223subprogram declaration (only other pragmas may intervene), or 6224if there is no separate subprogram declaration, then it can 6225appear at the start of the declarations in a subprogram body 6226(preceded only by other pragmas). 6227 6228Note: This pragma is called @code{Post_Class} rather than 6229@code{Post'Class} because the latter would not be strictly 6230conforming to the allowed syntax for pragmas. The motivation 6231for provinding pragmas equivalent to the aspects is to allow a program 6232to be written using the pragmas, and then compiled if necessary 6233using an Ada compiler that does not recognize the pragmas or 6234aspects, but is prepared to ignore the pragmas. The assertion 6235policy that controls this pragma is @code{Post'Class}, not 6236@code{Post_Class}. 6237 6238@node Pragma Rename_Pragma,Pragma Pre,Pragma Post_Class,Implementation Defined Pragmas 6239@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{bb} 6240@section Pragma Rename_Pragma 6241 6242 6243@geindex Pragmas 6244@geindex synonyms 6245 6246Syntax: 6247 6248@example 6249pragma Rename_Pragma ( 6250 [New_Name =>] IDENTIFIER, 6251 [Renamed =>] pragma_IDENTIFIER); 6252@end example 6253 6254This pragma provides a mechanism for supplying new names for existing 6255pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for 6256the Renamed pragma. For example, suppose you have code that was originally 6257developed on a compiler that supports Inline_Only as an implementation defined 6258pragma. And suppose the semantics of pragma Inline_Only are identical to (or at 6259least very similar to) the GNAT implementation defined pragma 6260Inline_Always. You could globally replace Inline_Only with Inline_Always. 6261 6262However, to avoid that source modification, you could instead add a 6263configuration pragma: 6264 6265@example 6266pragma Rename_Pragma ( 6267 New_Name => Inline_Only, 6268 Renamed => Inline_Always); 6269@end example 6270 6271Then GNAT will treat "pragma Inline_Only ..." as if you had written 6272"pragma Inline_Always ...". 6273 6274Pragma Inline_Only will not necessarily mean the same thing as the other Ada 6275compiler; it's up to you to make sure the semantics are close enough. 6276 6277@node Pragma Pre,Pragma Precondition,Pragma Rename_Pragma,Implementation Defined Pragmas 6278@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{bc} 6279@section Pragma Pre 6280 6281 6282@geindex Pre 6283 6284@geindex Checks 6285@geindex preconditions 6286 6287Syntax: 6288 6289@example 6290pragma Pre (Boolean_Expression); 6291@end example 6292 6293The @code{Pre} pragma is intended to be an exact replacement for 6294the language-defined 6295@code{Pre} aspect, and shares its restrictions and semantics. 6296It must appear either immediately following the corresponding 6297subprogram declaration (only other pragmas may intervene), or 6298if there is no separate subprogram declaration, then it can 6299appear at the start of the declarations in a subprogram body 6300(preceded only by other pragmas). 6301 6302@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas 6303@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bd} 6304@section Pragma Precondition 6305 6306 6307@geindex Preconditions 6308 6309@geindex Checks 6310@geindex preconditions 6311 6312Syntax: 6313 6314@example 6315pragma Precondition ( 6316 [Check =>] Boolean_Expression 6317 [,[Message =>] String_Expression]); 6318@end example 6319 6320The @code{Precondition} pragma is similar to @code{Postcondition} 6321except that the corresponding checks take place immediately upon 6322entry to the subprogram, and if a precondition fails, the exception 6323is raised in the context of the caller, and the attribute 'Result 6324cannot be used within the precondition expression. 6325 6326Otherwise, the placement and visibility rules are identical to those 6327described for postconditions. The following is an example of use 6328within a package spec: 6329 6330@example 6331package Math_Functions is 6332 ... 6333 function Sqrt (Arg : Float) return Float; 6334 pragma Precondition (Arg >= 0.0) 6335 ... 6336end Math_Functions; 6337@end example 6338 6339@code{Precondition} pragmas may appear either immediately following the 6340(separate) declaration of a subprogram, or at the start of the 6341declarations of a subprogram body. Only other pragmas may intervene 6342(that is appear between the subprogram declaration and its 6343postconditions, or appear before the postcondition in the 6344declaration sequence in a subprogram body). 6345 6346Note: precondition pragmas associated with subprograms that are 6347marked as Inline_Always, or those marked as Inline with front-end 6348inlining (-gnatN option set) are accepted and legality-checked 6349by the compiler, but are ignored at run-time even if precondition 6350checking is enabled. 6351 6352Note that pragma @code{Precondition} differs from the language-defined 6353@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing 6354multiple occurrences, allowing occurences in the body even if there 6355is a separate spec, and allowing a second string parameter, and the 6356use of the pragma identifier @code{Check}. Historically, pragma 6357@code{Precondition} was implemented prior to the development of 6358Ada 2012, and has been retained in its original form for 6359compatibility purposes. 6360 6361@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas 6362@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{be}@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{bf} 6363@section Pragma Predicate 6364 6365 6366Syntax: 6367 6368@example 6369pragma Predicate 6370 ([Entity =>] type_LOCAL_NAME, 6371 [Check =>] EXPRESSION); 6372@end example 6373 6374This pragma (available in all versions of Ada in GNAT) encompasses both 6375the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in 6376Ada 2012. A predicate is regarded as static if it has an allowed form 6377for @code{Static_Predicate} and is otherwise treated as a 6378@code{Dynamic_Predicate}. Otherwise, predicates specified by this 6379pragma behave exactly as described in the Ada 2012 reference manual. 6380For example, if we have 6381 6382@example 6383type R is range 1 .. 10; 6384subtype S is R; 6385pragma Predicate (Entity => S, Check => S not in 4 .. 6); 6386subtype Q is R 6387pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); 6388@end example 6389 6390the effect is identical to the following Ada 2012 code: 6391 6392@example 6393type R is range 1 .. 10; 6394subtype S is R with 6395 Static_Predicate => S not in 4 .. 6; 6396subtype Q is R with 6397 Dynamic_Predicate => F(Q) or G(Q); 6398@end example 6399 6400Note that there are no pragmas @code{Dynamic_Predicate} 6401or @code{Static_Predicate}. That is 6402because these pragmas would affect legality and semantics of 6403the program and thus do not have a neutral effect if ignored. 6404The motivation behind providing pragmas equivalent to 6405corresponding aspects is to allow a program to be written 6406using the pragmas, and then compiled with a compiler that 6407will ignore the pragmas. That doesn't work in the case of 6408static and dynamic predicates, since if the corresponding 6409pragmas are ignored, then the behavior of the program is 6410fundamentally changed (for example a membership test 6411@code{A in B} would not take into account a predicate 6412defined for subtype B). When following this approach, the 6413use of predicates should be avoided. 6414 6415@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas 6416@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{c0} 6417@section Pragma Predicate_Failure 6418 6419 6420Syntax: 6421 6422@example 6423pragma Predicate_Failure 6424 ([Entity =>] type_LOCAL_NAME, 6425 [Message =>] String_Expression); 6426@end example 6427 6428The @code{Predicate_Failure} pragma is intended to be an exact replacement for 6429the language-defined 6430@code{Predicate_Failure} aspect, and shares its restrictions and semantics. 6431 6432@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas 6433@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c1} 6434@section Pragma Preelaborable_Initialization 6435 6436 6437Syntax: 6438 6439@example 6440pragma Preelaborable_Initialization (DIRECT_NAME); 6441@end example 6442 6443This pragma is standard in Ada 2005, but is available in all earlier 6444versions of Ada as an implementation-defined pragma. 6445See Ada 2012 Reference Manual for details. 6446 6447@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas 6448@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c2} 6449@section Pragma Prefix_Exception_Messages 6450 6451 6452@geindex Prefix_Exception_Messages 6453 6454@geindex exception 6455 6456@geindex Exception_Message 6457 6458Syntax: 6459 6460@example 6461pragma Prefix_Exception_Messages; 6462@end example 6463 6464This is an implementation-defined configuration pragma that affects the 6465behavior of raise statements with a message given as a static string 6466constant (typically a string literal). In such cases, the string will 6467be automatically prefixed by the name of the enclosing entity (giving 6468the package and subprogram containing the raise statement). This helps 6469to identify where messages are coming from, and this mode is automatic 6470for the run-time library. 6471 6472The pragma has no effect if the message is computed with an expression other 6473than a static string constant, since the assumption in this case is that 6474the program computes exactly the string it wants. If you still want the 6475prefixing in this case, you can always call 6476@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. 6477 6478@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas 6479@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c3} 6480@section Pragma Pre_Class 6481 6482 6483@geindex Pre_Class 6484 6485@geindex Checks 6486@geindex preconditions 6487 6488Syntax: 6489 6490@example 6491pragma Pre_Class (Boolean_Expression); 6492@end example 6493 6494The @code{Pre_Class} pragma is intended to be an exact replacement for 6495the language-defined 6496@code{Pre'Class} aspect, and shares its restrictions and semantics. 6497It must appear either immediately following the corresponding 6498subprogram declaration (only other pragmas may intervene), or 6499if there is no separate subprogram declaration, then it can 6500appear at the start of the declarations in a subprogram body 6501(preceded only by other pragmas). 6502 6503Note: This pragma is called @code{Pre_Class} rather than 6504@code{Pre'Class} because the latter would not be strictly 6505conforming to the allowed syntax for pragmas. The motivation 6506for providing pragmas equivalent to the aspects is to allow a program 6507to be written using the pragmas, and then compiled if necessary 6508using an Ada compiler that does not recognize the pragmas or 6509aspects, but is prepared to ignore the pragmas. The assertion 6510policy that controls this pragma is @code{Pre'Class}, not 6511@code{Pre_Class}. 6512 6513@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas 6514@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c4} 6515@section Pragma Priority_Specific_Dispatching 6516 6517 6518Syntax: 6519 6520@example 6521pragma Priority_Specific_Dispatching ( 6522 POLICY_IDENTIFIER, 6523 first_priority_EXPRESSION, 6524 last_priority_EXPRESSION) 6525 6526POLICY_IDENTIFIER ::= 6527 EDF_Across_Priorities | 6528 FIFO_Within_Priorities | 6529 Non_Preemptive_Within_Priorities | 6530 Round_Robin_Within_Priorities 6531@end example 6532 6533This pragma is standard in Ada 2005, but is available in all earlier 6534versions of Ada as an implementation-defined pragma. 6535See Ada 2012 Reference Manual for details. 6536 6537@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas 6538@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c5} 6539@section Pragma Profile 6540 6541 6542Syntax: 6543 6544@example 6545pragma Profile (Ravenscar | Restricted | Rational | Jorvik | 6546 GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); 6547@end example 6548 6549This pragma is standard in Ada 2005, but is available in all earlier 6550versions of Ada as an implementation-defined pragma. This is a 6551configuration pragma that establishes a set of configuration pragmas 6552that depend on the argument. @code{Ravenscar} is standard in Ada 2005. 6553@code{Jorvik} is standard in Ada 202x. 6554The other possibilities (@code{Restricted}, @code{Rational}, 6555@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) 6556are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}. 6557 6558The set of configuration pragmas is defined in the following sections. 6559 6560 6561@itemize * 6562 6563@item 6564Pragma Profile (Ravenscar) 6565 6566The @code{Ravenscar} profile is standard in Ada 2005, 6567but is available in all earlier 6568versions of Ada as an implementation-defined pragma. This profile 6569establishes the following set of configuration pragmas: 6570 6571 6572@itemize * 6573 6574@item 6575@code{Task_Dispatching_Policy (FIFO_Within_Priorities)} 6576 6577[RM D.2.2] Tasks are dispatched following a preemptive 6578priority-ordered scheduling policy. 6579 6580@item 6581@code{Locking_Policy (Ceiling_Locking)} 6582 6583[RM D.3] While tasks and interrupts execute a protected action, they inherit 6584the ceiling priority of the corresponding protected object. 6585 6586@item 6587@code{Detect_Blocking} 6588 6589This pragma forces the detection of potentially blocking operations within a 6590protected operation, and to raise Program_Error if that happens. 6591@end itemize 6592 6593plus the following set of restrictions: 6594 6595 6596@itemize * 6597 6598@item 6599@code{Max_Entry_Queue_Length => 1} 6600 6601No task can be queued on a protected entry. 6602 6603@item 6604@code{Max_Protected_Entries => 1} 6605 6606@item 6607@code{Max_Task_Entries => 0} 6608 6609No rendezvous statements are allowed. 6610 6611@item 6612@code{No_Abort_Statements} 6613 6614@item 6615@code{No_Dynamic_Attachment} 6616 6617@item 6618@code{No_Dynamic_Priorities} 6619 6620@item 6621@code{No_Implicit_Heap_Allocations} 6622 6623@item 6624@code{No_Local_Protected_Objects} 6625 6626@item 6627@code{No_Local_Timing_Events} 6628 6629@item 6630@code{No_Protected_Type_Allocators} 6631 6632@item 6633@code{No_Relative_Delay} 6634 6635@item 6636@code{No_Requeue_Statements} 6637 6638@item 6639@code{No_Select_Statements} 6640 6641@item 6642@code{No_Specific_Termination_Handlers} 6643 6644@item 6645@code{No_Task_Allocators} 6646 6647@item 6648@code{No_Task_Hierarchy} 6649 6650@item 6651@code{No_Task_Termination} 6652 6653@item 6654@code{Simple_Barriers} 6655@end itemize 6656 6657The Ravenscar profile also includes the following restrictions that specify 6658that there are no semantic dependencies on the corresponding predefined 6659packages: 6660 6661 6662@itemize * 6663 6664@item 6665@code{No_Dependence => Ada.Asynchronous_Task_Control} 6666 6667@item 6668@code{No_Dependence => Ada.Calendar} 6669 6670@item 6671@code{No_Dependence => Ada.Execution_Time.Group_Budget} 6672 6673@item 6674@code{No_Dependence => Ada.Execution_Time.Timers} 6675 6676@item 6677@code{No_Dependence => Ada.Task_Attributes} 6678 6679@item 6680@code{No_Dependence => System.Multiprocessors.Dispatching_Domains} 6681@end itemize 6682 6683This set of configuration pragmas and restrictions correspond to the 6684definition of the 'Ravenscar Profile' for limited tasking, devised and 6685published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. 6686A description is also available at 6687@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. 6688 6689The original definition of the profile was revised at subsequent IRTAW 6690meetings. It has been included in the ISO 6691@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, 6692and was made part of the Ada 2005 standard. 6693The formal definition given by 6694the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 6695AI-305) available at 6696@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and 6697@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. 6698 6699The above set is a superset of the restrictions provided by pragma 6700@code{Profile (Restricted)}, it includes six additional restrictions 6701(@code{Simple_Barriers}, @code{No_Select_Statements}, 6702@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, 6703@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 6704that pragma @code{Profile (Ravenscar)}, like the pragma 6705@code{Profile (Restricted)}, 6706automatically causes the use of a simplified, 6707more efficient version of the tasking run-time library. 6708 6709@item 6710Pragma Profile (Jorvik) 6711 6712@code{Jorvik} is the new profile added to the Ada 202x draft standard, 6713previously implemented under the name @code{GNAT_Extended_Ravenscar}. 6714 6715The @code{No_Implicit_Heap_Allocations} restriction has been replaced 6716by @code{No_Implicit_Task_Allocations} and 6717@code{No_Implicit_Protected_Object_Allocations}. 6718 6719The @code{Simple_Barriers} restriction has been replaced by 6720@code{Pure_Barriers}. 6721 6722The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and 6723@code{No_Relative_Delay} restrictions have been removed. 6724 6725Details on the rationale for @code{Jorvik} and implications for use may be 6726found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz, 6727T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies -- Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science, 6728Number 10300. 6729 6730@item 6731Pragma Profile (GNAT_Ravenscar_EDF) 6732 6733This profile corresponds to the Ravenscar profile but using 6734EDF_Across_Priority as the Task_Scheduling_Policy. 6735 6736@item 6737Pragma Profile (Restricted) 6738 6739This profile corresponds to the GNAT restricted run time. It 6740establishes the following set of restrictions: 6741 6742 6743@itemize * 6744 6745@item 6746@code{No_Abort_Statements} 6747 6748@item 6749@code{No_Entry_Queue} 6750 6751@item 6752@code{No_Task_Hierarchy} 6753 6754@item 6755@code{No_Task_Allocators} 6756 6757@item 6758@code{No_Dynamic_Priorities} 6759 6760@item 6761@code{No_Terminate_Alternatives} 6762 6763@item 6764@code{No_Dynamic_Attachment} 6765 6766@item 6767@code{No_Protected_Type_Allocators} 6768 6769@item 6770@code{No_Local_Protected_Objects} 6771 6772@item 6773@code{No_Requeue_Statements} 6774 6775@item 6776@code{No_Task_Attributes_Package} 6777 6778@item 6779@code{Max_Asynchronous_Select_Nesting = 0} 6780 6781@item 6782@code{Max_Task_Entries = 0} 6783 6784@item 6785@code{Max_Protected_Entries = 1} 6786 6787@item 6788@code{Max_Select_Alternatives = 0} 6789@end itemize 6790 6791This set of restrictions causes the automatic selection of a simplified 6792version of the run time that provides improved performance for the 6793limited set of tasking functionality permitted by this set of restrictions. 6794 6795@item 6796Pragma Profile (Rational) 6797 6798The Rational profile is intended to facilitate porting legacy code that 6799compiles with the Rational APEX compiler, even when the code includes non- 6800conforming Ada constructs. The profile enables the following three pragmas: 6801 6802 6803@itemize * 6804 6805@item 6806@code{pragma Implicit_Packing} 6807 6808@item 6809@code{pragma Overriding_Renamings} 6810 6811@item 6812@code{pragma Use_VADS_Size} 6813@end itemize 6814@end itemize 6815 6816@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas 6817@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c6} 6818@section Pragma Profile_Warnings 6819 6820 6821Syntax: 6822 6823@example 6824pragma Profile_Warnings (Ravenscar | Restricted | Rational); 6825@end example 6826 6827This is an implementation-defined pragma that is similar in 6828effect to @code{pragma Profile} except that instead of 6829generating @code{Restrictions} pragmas, it generates 6830@code{Restriction_Warnings} pragmas. The result is that 6831violations of the profile generate warning messages instead 6832of error messages. 6833 6834@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas 6835@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c7} 6836@section Pragma Propagate_Exceptions 6837 6838 6839@geindex Interfacing to C++ 6840 6841Syntax: 6842 6843@example 6844pragma Propagate_Exceptions; 6845@end example 6846 6847This pragma is now obsolete and, other than generating a warning if warnings 6848on obsolescent features are enabled, is ignored. 6849It is retained for compatibility 6850purposes. It used to be used in connection with optimization of 6851a now-obsolete mechanism for implementation of exceptions. 6852 6853@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas 6854@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c8} 6855@section Pragma Provide_Shift_Operators 6856 6857 6858@geindex Shift operators 6859 6860Syntax: 6861 6862@example 6863pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); 6864@end example 6865 6866This pragma can be applied to a first subtype local name that specifies 6867either an unsigned or signed type. It has the effect of providing the 6868five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, 6869Rotate_Left and Rotate_Right) for the given type. It is similar to 6870including the function declarations for these five operators, together 6871with the pragma Import (Intrinsic, ...) statements. 6872 6873@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas 6874@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c9} 6875@section Pragma Psect_Object 6876 6877 6878Syntax: 6879 6880@example 6881pragma Psect_Object ( 6882 [Internal =>] LOCAL_NAME, 6883 [, [External =>] EXTERNAL_SYMBOL] 6884 [, [Size =>] EXTERNAL_SYMBOL]); 6885 6886EXTERNAL_SYMBOL ::= 6887 IDENTIFIER 6888| static_string_EXPRESSION 6889@end example 6890 6891This pragma is identical in effect to pragma @code{Common_Object}. 6892 6893@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas 6894@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{ca}@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{cb} 6895@section Pragma Pure_Function 6896 6897 6898Syntax: 6899 6900@example 6901pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 6902@end example 6903 6904This pragma appears in the same declarative part as a function 6905declaration (or a set of function declarations if more than one 6906overloaded declaration exists, in which case the pragma applies 6907to all entities). It specifies that the function @code{Entity} is 6908to be considered pure for the purposes of code generation. This means 6909that the compiler can assume that there are no side effects, and 6910in particular that two calls with identical arguments produce the 6911same result. It also means that the function can be used in an 6912address clause. 6913 6914Note that, quite deliberately, there are no static checks to try 6915to ensure that this promise is met, so @code{Pure_Function} can be used 6916with functions that are conceptually pure, even if they do modify 6917global variables. For example, a square root function that is 6918instrumented to count the number of times it is called is still 6919conceptually pure, and can still be optimized, even though it 6920modifies a global variable (the count). Memo functions are another 6921example (where a table of previous calls is kept and consulted to 6922avoid re-computation). 6923 6924Note also that the normal rules excluding optimization of subprograms 6925in pure units (when parameter types are descended from System.Address, 6926or when the full view of a parameter type is limited), do not apply 6927for the Pure_Function case. If you explicitly specify Pure_Function, 6928the compiler may optimize away calls with identical arguments, and 6929if that results in unexpected behavior, the proper action is not to 6930use the pragma for subprograms that are not (conceptually) pure. 6931 6932Note: Most functions in a @code{Pure} package are automatically pure, and 6933there is no need to use pragma @code{Pure_Function} for such functions. One 6934exception is any function that has at least one formal of type 6935@code{System.Address} or a type derived from it. Such functions are not 6936considered pure by default, since the compiler assumes that the 6937@code{Address} parameter may be functioning as a pointer and that the 6938referenced data may change even if the address value does not. 6939Similarly, imported functions are not considered to be pure by default, 6940since there is no way of checking that they are in fact pure. The use 6941of pragma @code{Pure_Function} for such a function will override these default 6942assumption, and cause the compiler to treat a designated subprogram as pure 6943in these cases. 6944 6945Note: If pragma @code{Pure_Function} is applied to a renamed function, it 6946applies to the underlying renamed function. This can be used to 6947disambiguate cases of overloading where some but not all functions 6948in a set of overloaded functions are to be designated as pure. 6949 6950If pragma @code{Pure_Function} is applied to a library-level function, the 6951function is also considered pure from an optimization point of view, but the 6952unit is not a Pure unit in the categorization sense. So for example, a function 6953thus marked is free to @code{with} non-pure units. 6954 6955@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas 6956@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{cc} 6957@section Pragma Rational 6958 6959 6960Syntax: 6961 6962@example 6963pragma Rational; 6964@end example 6965 6966This pragma is considered obsolescent, but is retained for 6967compatibility purposes. It is equivalent to: 6968 6969@example 6970pragma Profile (Rational); 6971@end example 6972 6973@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas 6974@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cd} 6975@section Pragma Ravenscar 6976 6977 6978Syntax: 6979 6980@example 6981pragma Ravenscar; 6982@end example 6983 6984This pragma is considered obsolescent, but is retained for 6985compatibility purposes. It is equivalent to: 6986 6987@example 6988pragma Profile (Ravenscar); 6989@end example 6990 6991which is the preferred method of setting the @code{Ravenscar} profile. 6992 6993@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas 6994@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{ce}@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cf} 6995@section Pragma Refined_Depends 6996 6997 6998Syntax: 6999 7000@example 7001pragma Refined_Depends (DEPENDENCY_RELATION); 7002 7003DEPENDENCY_RELATION ::= 7004 null 7005 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) 7006 7007DEPENDENCY_CLAUSE ::= 7008 OUTPUT_LIST =>[+] INPUT_LIST 7009 | NULL_DEPENDENCY_CLAUSE 7010 7011NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST 7012 7013OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) 7014 7015INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) 7016 7017OUTPUT ::= NAME | FUNCTION_RESULT 7018INPUT ::= NAME 7019 7020where FUNCTION_RESULT is a function Result attribute_reference 7021@end example 7022 7023For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in 7024the SPARK 2014 Reference Manual, section 6.1.5. 7025 7026@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas 7027@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d0}@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{d1} 7028@section Pragma Refined_Global 7029 7030 7031Syntax: 7032 7033@example 7034pragma Refined_Global (GLOBAL_SPECIFICATION); 7035 7036GLOBAL_SPECIFICATION ::= 7037 null 7038 | (GLOBAL_LIST) 7039 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) 7040 7041MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST 7042 7043MODE_SELECTOR ::= In_Out | Input | Output | Proof_In 7044GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) 7045GLOBAL_ITEM ::= NAME 7046@end example 7047 7048For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in 7049the SPARK 2014 Reference Manual, section 6.1.4. 7050 7051@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas 7052@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d3} 7053@section Pragma Refined_Post 7054 7055 7056Syntax: 7057 7058@example 7059pragma Refined_Post (boolean_EXPRESSION); 7060@end example 7061 7062For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in 7063the SPARK 2014 Reference Manual, section 7.2.7. 7064 7065@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas 7066@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d4}@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d5} 7067@section Pragma Refined_State 7068 7069 7070Syntax: 7071 7072@example 7073pragma Refined_State (REFINEMENT_LIST); 7074 7075REFINEMENT_LIST ::= 7076 (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) 7077 7078REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST 7079 7080CONSTITUENT_LIST ::= 7081 null 7082 | CONSTITUENT 7083 | (CONSTITUENT @{, CONSTITUENT@}) 7084 7085CONSTITUENT ::= object_NAME | state_NAME 7086@end example 7087 7088For the semantics of this pragma, see the entry for aspect @code{Refined_State} in 7089the SPARK 2014 Reference Manual, section 7.2.2. 7090 7091@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas 7092@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d6} 7093@section Pragma Relative_Deadline 7094 7095 7096Syntax: 7097 7098@example 7099pragma Relative_Deadline (time_span_EXPRESSION); 7100@end example 7101 7102This pragma is standard in Ada 2005, but is available in all earlier 7103versions of Ada as an implementation-defined pragma. 7104See Ada 2012 Reference Manual for details. 7105 7106@node Pragma Remote_Access_Type,Pragma Restricted_Run_Time,Pragma Relative_Deadline,Implementation Defined Pragmas 7107@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d7}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d8} 7108@section Pragma Remote_Access_Type 7109 7110 7111Syntax: 7112 7113@example 7114pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 7115@end example 7116 7117This pragma appears in the formal part of a generic declaration. 7118It specifies an exception to the RM rule from E.2.2(17/2), which forbids 7119the use of a remote access to class-wide type as actual for a formal 7120access type. 7121 7122When this pragma applies to a formal access type @code{Entity}, that 7123type is treated as a remote access to class-wide type in the generic. 7124It must be a formal general access type, and its designated type must 7125be the class-wide type of a formal tagged limited private type from the 7126same generic declaration. 7127 7128In the generic unit, the formal type is subject to all restrictions 7129pertaining to remote access to class-wide types. At instantiation, the 7130actual type must be a remote access to class-wide type. 7131 7132@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Remote_Access_Type,Implementation Defined Pragmas 7133@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d9} 7134@section Pragma Restricted_Run_Time 7135 7136 7137Syntax: 7138 7139@example 7140pragma Restricted_Run_Time; 7141@end example 7142 7143This pragma is considered obsolescent, but is retained for 7144compatibility purposes. It is equivalent to: 7145 7146@example 7147pragma Profile (Restricted); 7148@end example 7149 7150which is the preferred method of setting the restricted run time 7151profile. 7152 7153@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas 7154@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{da} 7155@section Pragma Restriction_Warnings 7156 7157 7158Syntax: 7159 7160@example 7161pragma Restriction_Warnings 7162 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 7163@end example 7164 7165This pragma allows a series of restriction identifiers to be 7166specified (the list of allowed identifiers is the same as for 7167pragma @code{Restrictions}). For each of these identifiers 7168the compiler checks for violations of the restriction, but 7169generates a warning message rather than an error message 7170if the restriction is violated. 7171 7172One use of this is in situations where you want to know 7173about violations of a restriction, but you want to ignore some of 7174these violations. Consider this example, where you want to set 7175Ada_95 mode and enable style checks, but you want to know about 7176any other use of implementation pragmas: 7177 7178@example 7179pragma Restriction_Warnings (No_Implementation_Pragmas); 7180pragma Warnings (Off, "violation of No_Implementation_Pragmas"); 7181pragma Ada_95; 7182pragma Style_Checks ("2bfhkM160"); 7183pragma Warnings (On, "violation of No_Implementation_Pragmas"); 7184@end example 7185 7186By including the above lines in a configuration pragmas file, 7187the Ada_95 and Style_Checks pragmas are accepted without 7188generating a warning, but any other use of implementation 7189defined pragmas will cause a warning to be generated. 7190 7191@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas 7192@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{db} 7193@section Pragma Reviewable 7194 7195 7196Syntax: 7197 7198@example 7199pragma Reviewable; 7200@end example 7201 7202This pragma is an RM-defined standard pragma, but has no effect on the 7203program being compiled, or on the code generated for the program. 7204 7205To obtain the required output specified in RM H.3.1, the compiler must be 7206run with various special switches as follows: 7207 7208 7209@itemize * 7210 7211@item 7212@emph{Where compiler-generated run-time checks remain} 7213 7214The switch @emph{-gnatGL} 7215may be used to list the expanded code in pseudo-Ada form. 7216Runtime checks show up in the listing either as explicit 7217checks or operators marked with @{@} to indicate a check is present. 7218 7219@item 7220@emph{An identification of known exceptions at compile time} 7221 7222If the program is compiled with @emph{-gnatwa}, 7223the compiler warning messages will indicate all cases where the compiler 7224detects that an exception is certain to occur at run time. 7225 7226@item 7227@emph{Possible reads of uninitialized variables} 7228 7229The compiler warns of many such cases, but its output is incomplete. 7230@end itemize 7231 7232 7233A supplemental static analysis tool 7234may be used to obtain a comprehensive list of all 7235possible points at which uninitialized data may be read. 7236 7237 7238@itemize * 7239 7240@item 7241@emph{Where run-time support routines are implicitly invoked} 7242 7243In the output from @emph{-gnatGL}, 7244run-time calls are explicitly listed as calls to the relevant 7245run-time routine. 7246 7247@item 7248@emph{Object code listing} 7249 7250This may be obtained either by using the @emph{-S} switch, 7251or the objdump utility. 7252 7253@item 7254@emph{Constructs known to be erroneous at compile time} 7255 7256These are identified by warnings issued by the compiler (use @emph{-gnatwa}). 7257 7258@item 7259@emph{Stack usage information} 7260 7261Static stack usage data (maximum per-subprogram) can be obtained via the 7262@emph{-fstack-usage} switch to the compiler. 7263Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch 7264to gnatbind 7265@end itemize 7266 7267 7268 7269@itemize * 7270 7271@item 7272@emph{Object code listing of entire partition} 7273 7274This can be obtained by compiling the partition with @emph{-S}, 7275or by applying objdump 7276to all the object files that are part of the partition. 7277 7278@item 7279@emph{A description of the run-time model} 7280 7281The full sources of the run-time are available, and the documentation of 7282these routines describes how these run-time routines interface to the 7283underlying operating system facilities. 7284 7285@item 7286@emph{Control and data-flow information} 7287@end itemize 7288 7289 7290A supplemental static analysis tool 7291may be used to obtain complete control and data-flow information, as well as 7292comprehensive messages identifying possible problems based on this 7293information. 7294 7295@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas 7296@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{dc}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{dd} 7297@section Pragma Secondary_Stack_Size 7298 7299 7300Syntax: 7301 7302@example 7303pragma Secondary_Stack_Size (integer_EXPRESSION); 7304@end example 7305 7306This pragma appears within the task definition of a single task declaration 7307or a task type declaration (like pragma @code{Storage_Size}) and applies to all 7308task objects of that type. The argument specifies the size of the secondary 7309stack to be used by these task objects, and must be of an integer type. The 7310secondary stack is used to handle functions that return a variable-sized 7311result, for example a function returning an unconstrained String. 7312 7313Note this pragma only applies to targets using fixed secondary stacks, like 7314VxWorks 653 and bare board targets, where a fixed block for the 7315secondary stack is allocated from the primary stack of the task. By default, 7316these targets assign a percentage of the primary stack for the secondary stack, 7317as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, 7318an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. 7319 7320For most targets, the pragma does not apply as the secondary stack grows on 7321demand: allocated as a chain of blocks in the heap. The default size of these 7322blocks can be modified via the @code{-D} binder option as described in 7323@cite{GNAT User's Guide}. 7324 7325Note that no check is made to see if the secondary stack can fit inside the 7326primary stack. 7327 7328Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} 7329is in effect. 7330 7331@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas 7332@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{de} 7333@section Pragma Share_Generic 7334 7335 7336Syntax: 7337 7338@example 7339pragma Share_Generic (GNAME @{, GNAME@}); 7340 7341GNAME ::= generic_unit_NAME | generic_instance_NAME 7342@end example 7343 7344This pragma is provided for compatibility with Dec Ada 83. It has 7345no effect in GNAT (which does not implement shared generics), other 7346than to check that the given names are all names of generic units or 7347generic instances. 7348 7349@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas 7350@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{df}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e0} 7351@section Pragma Shared 7352 7353 7354This pragma is provided for compatibility with Ada 83. The syntax and 7355semantics are identical to pragma Atomic. 7356 7357@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas 7358@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e1} 7359@section Pragma Short_Circuit_And_Or 7360 7361 7362Syntax: 7363 7364@example 7365pragma Short_Circuit_And_Or; 7366@end example 7367 7368This configuration pragma causes any occurrence of the AND operator applied to 7369operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 7370is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 7371may be useful in the context of certification protocols requiring the use of 7372short-circuited logical operators. If this configuration pragma occurs locally 7373within the file being compiled, it applies only to the file being compiled. 7374There is no requirement that all units in a partition use this option. 7375 7376@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas 7377@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e2} 7378@section Pragma Short_Descriptors 7379 7380 7381Syntax: 7382 7383@example 7384pragma Short_Descriptors 7385@end example 7386 7387This pragma is provided for compatibility with other Ada implementations. It 7388is recognized but ignored by all current versions of GNAT. 7389 7390@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas 7391@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e3}@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e4} 7392@section Pragma Simple_Storage_Pool_Type 7393 7394 7395@geindex Storage pool 7396@geindex simple 7397 7398@geindex Simple storage pool 7399 7400Syntax: 7401 7402@example 7403pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 7404@end example 7405 7406A type can be established as a 'simple storage pool type' by applying 7407the representation pragma @code{Simple_Storage_Pool_Type} to the type. 7408A type named in the pragma must be a library-level immutably limited record 7409type or limited tagged type declared immediately within a package declaration. 7410The type can also be a limited private type whose full type is allowed as 7411a simple storage pool type. 7412 7413For a simple storage pool type @code{SSP}, nonabstract primitive subprograms 7414@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that 7415are subtype conformant with the following subprogram declarations: 7416 7417@example 7418procedure Allocate 7419 (Pool : in out SSP; 7420 Storage_Address : out System.Address; 7421 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7422 Alignment : System.Storage_Elements.Storage_Count); 7423 7424procedure Deallocate 7425 (Pool : in out SSP; 7426 Storage_Address : System.Address; 7427 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 7428 Alignment : System.Storage_Elements.Storage_Count); 7429 7430function Storage_Size (Pool : SSP) 7431 return System.Storage_Elements.Storage_Count; 7432@end example 7433 7434Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and 7435@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then 7436applying an unchecked deallocation has no effect other than to set its actual 7437parameter to null. If @code{Storage_Size} is not declared, then the 7438@code{Storage_Size} attribute applied to an access type associated with 7439a pool object of type SSP returns zero. Additional operations can be declared 7440for a simple storage pool type (such as for supporting a mark/release 7441storage-management discipline). 7442 7443An object of a simple storage pool type can be associated with an access 7444type by specifying the attribute 7445@ref{e5,,Simple_Storage_Pool}. For example: 7446 7447@example 7448My_Pool : My_Simple_Storage_Pool_Type; 7449 7450type Acc is access My_Data_Type; 7451 7452for Acc'Simple_Storage_Pool use My_Pool; 7453@end example 7454 7455See attribute @ref{e5,,Simple_Storage_Pool} 7456for further details. 7457 7458@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas 7459@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e6}@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e7} 7460@section Pragma Source_File_Name 7461 7462 7463Syntax: 7464 7465@example 7466pragma Source_File_Name ( 7467 [Unit_Name =>] unit_NAME, 7468 Spec_File_Name => STRING_LITERAL, 7469 [Index => INTEGER_LITERAL]); 7470 7471pragma Source_File_Name ( 7472 [Unit_Name =>] unit_NAME, 7473 Body_File_Name => STRING_LITERAL, 7474 [Index => INTEGER_LITERAL]); 7475@end example 7476 7477Use this to override the normal naming convention. It is a configuration 7478pragma, and so has the usual applicability of configuration pragmas 7479(i.e., it applies to either an entire partition, or to all units in a 7480compilation, or to a single unit, depending on how it is used. 7481@code{unit_name} is mapped to @code{file_name_literal}. The identifier for 7482the second argument is required, and indicates whether this is the file 7483name for the spec or for the body. 7484 7485The optional Index argument should be used when a file contains multiple 7486units, and when you do not want to use @code{gnatchop} to separate then 7487into multiple files (which is the recommended procedure to limit the 7488number of recompilations that are needed when some sources change). 7489For instance, if the source file @code{source.ada} contains 7490 7491@example 7492package B is 7493... 7494end B; 7495 7496with B; 7497procedure A is 7498begin 7499 .. 7500end A; 7501@end example 7502 7503you could use the following configuration pragmas: 7504 7505@example 7506pragma Source_File_Name 7507 (B, Spec_File_Name => "source.ada", Index => 1); 7508pragma Source_File_Name 7509 (A, Body_File_Name => "source.ada", Index => 2); 7510@end example 7511 7512Note that the @code{gnatname} utility can also be used to generate those 7513configuration pragmas. 7514 7515Another form of the @code{Source_File_Name} pragma allows 7516the specification of patterns defining alternative file naming schemes 7517to apply to all files. 7518 7519@example 7520pragma Source_File_Name 7521 ( [Spec_File_Name =>] STRING_LITERAL 7522 [,[Casing =>] CASING_SPEC] 7523 [,[Dot_Replacement =>] STRING_LITERAL]); 7524 7525pragma Source_File_Name 7526 ( [Body_File_Name =>] STRING_LITERAL 7527 [,[Casing =>] CASING_SPEC] 7528 [,[Dot_Replacement =>] STRING_LITERAL]); 7529 7530pragma Source_File_Name 7531 ( [Subunit_File_Name =>] STRING_LITERAL 7532 [,[Casing =>] CASING_SPEC] 7533 [,[Dot_Replacement =>] STRING_LITERAL]); 7534 7535CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 7536@end example 7537 7538The first argument is a pattern that contains a single asterisk indicating 7539the point at which the unit name is to be inserted in the pattern string 7540to form the file name. The second argument is optional. If present it 7541specifies the casing of the unit name in the resulting file name string. 7542The default is lower case. Finally the third argument allows for systematic 7543replacement of any dots in the unit name by the specified string literal. 7544 7545Note that Source_File_Name pragmas should not be used if you are using 7546project files. The reason for this rule is that the project manager is not 7547aware of these pragmas, and so other tools that use the projet file would not 7548be aware of the intended naming conventions. If you are using project files, 7549file naming is controlled by Source_File_Name_Project pragmas, which are 7550usually supplied automatically by the project manager. A pragma 7551Source_File_Name cannot appear after a @ref{e8,,Pragma Source_File_Name_Project}. 7552 7553For more details on the use of the @code{Source_File_Name} pragma, see the 7554sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} 7555in the @cite{GNAT User's Guide}. 7556 7557@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas 7558@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e8}@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e9} 7559@section Pragma Source_File_Name_Project 7560 7561 7562This pragma has the same syntax and semantics as pragma Source_File_Name. 7563It is only allowed as a stand-alone configuration pragma. 7564It cannot appear after a @ref{e6,,Pragma Source_File_Name}, and 7565most importantly, once pragma Source_File_Name_Project appears, 7566no further Source_File_Name pragmas are allowed. 7567 7568The intention is that Source_File_Name_Project pragmas are always 7569generated by the Project Manager in a manner consistent with the naming 7570specified in a project file, and when naming is controlled in this manner, 7571it is not permissible to attempt to modify this naming scheme using 7572Source_File_Name or Source_File_Name_Project pragmas (which would not be 7573known to the project manager). 7574 7575@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas 7576@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ea} 7577@section Pragma Source_Reference 7578 7579 7580Syntax: 7581 7582@example 7583pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 7584@end example 7585 7586This pragma must appear as the first line of a source file. 7587@code{integer_literal} is the logical line number of the line following 7588the pragma line (for use in error messages and debugging 7589information). @code{string_literal} is a static string constant that 7590specifies the file name to be used in error messages and debugging 7591information. This is most notably used for the output of @code{gnatchop} 7592with the @emph{-r} switch, to make sure that the original unchopped 7593source file is the one referred to. 7594 7595The second argument must be a string literal, it cannot be a static 7596string expression other than a string literal. This is because its value 7597is needed for error messages issued by all phases of the compiler. 7598 7599@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas 7600@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{eb}@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{ec} 7601@section Pragma SPARK_Mode 7602 7603 7604Syntax: 7605 7606@example 7607pragma SPARK_Mode [(On | Off)] ; 7608@end example 7609 7610In general a program can have some parts that are in SPARK 2014 (and 7611follow all the rules in the SPARK Reference Manual), and some parts 7612that are full Ada 2012. 7613 7614The SPARK_Mode pragma is used to identify which parts are in SPARK 76152014 (by default programs are in full Ada). The SPARK_Mode pragma can 7616be used in the following places: 7617 7618 7619@itemize * 7620 7621@item 7622As a configuration pragma, in which case it sets the default mode for 7623all units compiled with this pragma. 7624 7625@item 7626Immediately following a library-level subprogram spec 7627 7628@item 7629Immediately within a library-level package body 7630 7631@item 7632Immediately following the @code{private} keyword of a library-level 7633package spec 7634 7635@item 7636Immediately following the @code{begin} keyword of a library-level 7637package body 7638 7639@item 7640Immediately within a library-level subprogram body 7641@end itemize 7642 7643Normally a subprogram or package spec/body inherits the current mode 7644that is active at the point it is declared. But this can be overridden 7645by pragma within the spec or body as above. 7646 7647The basic consistency rule is that you can't turn SPARK_Mode back 7648@code{On}, once you have explicitly (with a pragma) turned if 7649@code{Off}. So the following rules apply: 7650 7651If a subprogram spec has SPARK_Mode @code{Off}, then the body must 7652also have SPARK_Mode @code{Off}. 7653 7654For a package, we have four parts: 7655 7656 7657@itemize * 7658 7659@item 7660the package public declarations 7661 7662@item 7663the package private part 7664 7665@item 7666the body of the package 7667 7668@item 7669the elaboration code after @code{begin} 7670@end itemize 7671 7672For a package, the rule is that if you explicitly turn SPARK_Mode 7673@code{Off} for any part, then all the following parts must have 7674SPARK_Mode @code{Off}. Note that this may require repeating a pragma 7675SPARK_Mode (@code{Off}) in the body. For example, if we have a 7676configuration pragma SPARK_Mode (@code{On}) that turns the mode on by 7677default everywhere, and one particular package spec has pragma 7678SPARK_Mode (@code{Off}), then that pragma will need to be repeated in 7679the package body. 7680 7681@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas 7682@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ed} 7683@section Pragma Static_Elaboration_Desired 7684 7685 7686Syntax: 7687 7688@example 7689pragma Static_Elaboration_Desired; 7690@end example 7691 7692This pragma is used to indicate that the compiler should attempt to initialize 7693statically the objects declared in the library unit to which the pragma applies, 7694when these objects are initialized (explicitly or implicitly) by an aggregate. 7695In the absence of this pragma, aggregates in object declarations are expanded 7696into assignments and loops, even when the aggregate components are static 7697constants. When the aggregate is present the compiler builds a static expression 7698that requires no run-time code, so that the initialized object can be placed in 7699read-only data space. If the components are not static, or the aggregate has 7700more that 100 components, the compiler emits a warning that the pragma cannot 7701be obeyed. (See also the restriction No_Implicit_Loops, which supports static 7702construction of larger aggregates with static components that include an others 7703choice.) 7704 7705@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas 7706@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ee} 7707@section Pragma Stream_Convert 7708 7709 7710Syntax: 7711 7712@example 7713pragma Stream_Convert ( 7714 [Entity =>] type_LOCAL_NAME, 7715 [Read =>] function_NAME, 7716 [Write =>] function_NAME); 7717@end example 7718 7719This pragma provides an efficient way of providing user-defined stream 7720attributes. Not only is it simpler to use than specifying the attributes 7721directly, but more importantly, it allows the specification to be made in such 7722a way that the predefined unit Ada.Streams is not loaded unless it is actually 7723needed (i.e. unless the stream attributes are actually used); the use of 7724the Stream_Convert pragma adds no overhead at all, unless the stream 7725attributes are actually used on the designated type. 7726 7727The first argument specifies the type for which stream functions are 7728provided. The second parameter provides a function used to read values 7729of this type. It must name a function whose argument type may be any 7730subtype, and whose returned type must be the type given as the first 7731argument to the pragma. 7732 7733The meaning of the @code{Read} parameter is that if a stream attribute directly 7734or indirectly specifies reading of the type given as the first parameter, 7735then a value of the type given as the argument to the Read function is 7736read from the stream, and then the Read function is used to convert this 7737to the required target type. 7738 7739Similarly the @code{Write} parameter specifies how to treat write attributes 7740that directly or indirectly apply to the type given as the first parameter. 7741It must have an input parameter of the type specified by the first parameter, 7742and the return type must be the same as the input type of the Read function. 7743The effect is to first call the Write function to convert to the given stream 7744type, and then write the result type to the stream. 7745 7746The Read and Write functions must not be overloaded subprograms. If necessary 7747renamings can be supplied to meet this requirement. 7748The usage of this attribute is best illustrated by a simple example, taken 7749from the GNAT implementation of package Ada.Strings.Unbounded: 7750 7751@example 7752function To_Unbounded (S : String) return Unbounded_String 7753 renames To_Unbounded_String; 7754 7755pragma Stream_Convert 7756 (Unbounded_String, To_Unbounded, To_String); 7757@end example 7758 7759The specifications of the referenced functions, as given in the Ada 7760Reference Manual are: 7761 7762@example 7763function To_Unbounded_String (Source : String) 7764 return Unbounded_String; 7765 7766function To_String (Source : Unbounded_String) 7767 return String; 7768@end example 7769 7770The effect is that if the value of an unbounded string is written to a stream, 7771then the representation of the item in the stream is in the same format that 7772would be used for @code{Standard.String'Output}, and this same representation 7773is expected when a value of this type is read from the stream. Note that the 7774value written always includes the bounds, even for Unbounded_String'Write, 7775since Unbounded_String is not an array type. 7776 7777Note that the @code{Stream_Convert} pragma is not effective in the case of 7778a derived type of a non-limited tagged type. If such a type is specified then 7779the pragma is silently ignored, and the default implementation of the stream 7780attributes is used instead. 7781 7782@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas 7783@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ef} 7784@section Pragma Style_Checks 7785 7786 7787Syntax: 7788 7789@example 7790pragma Style_Checks (string_LITERAL | ALL_CHECKS | 7791 On | Off [, LOCAL_NAME]); 7792@end example 7793 7794This pragma is used in conjunction with compiler switches to control the 7795built in style checking provided by GNAT. The compiler switches, if set, 7796provide an initial setting for the switches, and this pragma may be used 7797to modify these settings, or the settings may be provided entirely by 7798the use of the pragma. This pragma can be used anywhere that a pragma 7799is legal, including use as a configuration pragma (including use in 7800the @code{gnat.adc} file). 7801 7802The form with a string literal specifies which style options are to be 7803activated. These are additive, so they apply in addition to any previously 7804set style check options. The codes for the options are the same as those 7805used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}. 7806For example the following two methods can be used to enable 7807layout checking: 7808 7809 7810@itemize * 7811 7812@item 7813@example 7814pragma Style_Checks ("l"); 7815@end example 7816 7817@item 7818@example 7819gcc -c -gnatyl ... 7820@end example 7821@end itemize 7822 7823The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent 7824to the use of the @code{gnaty} switch with no options. 7825See the @cite{GNAT User's Guide} for details.) 7826 7827Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). 7828In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check 7829options (i.e. equivalent to @code{-gnatyg}). 7830 7831The forms with @code{Off} and @code{On} 7832can be used to temporarily disable style checks 7833as shown in the following example: 7834 7835@example 7836pragma Style_Checks ("k"); -- requires keywords in lower case 7837pragma Style_Checks (Off); -- turn off style checks 7838NULL; -- this will not generate an error message 7839pragma Style_Checks (On); -- turn style checks back on 7840NULL; -- this will generate an error message 7841@end example 7842 7843Finally the two argument form is allowed only if the first argument is 7844@code{On} or @code{Off}. The effect is to turn of semantic style checks 7845for the specified entity, as shown in the following example: 7846 7847@example 7848pragma Style_Checks ("r"); -- require consistency of identifier casing 7849Arg : Integer; 7850Rf1 : Integer := ARG; -- incorrect, wrong case 7851pragma Style_Checks (Off, Arg); 7852Rf2 : Integer := ARG; -- OK, no error 7853@end example 7854 7855@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas 7856@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f0} 7857@section Pragma Subtitle 7858 7859 7860Syntax: 7861 7862@example 7863pragma Subtitle ([Subtitle =>] STRING_LITERAL); 7864@end example 7865 7866This pragma is recognized for compatibility with other Ada compilers 7867but is ignored by GNAT. 7868 7869@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas 7870@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f1} 7871@section Pragma Suppress 7872 7873 7874Syntax: 7875 7876@example 7877pragma Suppress (Identifier [, [On =>] Name]); 7878@end example 7879 7880This is a standard pragma, and supports all the check names required in 7881the RM. It is included here because GNAT recognizes some additional check 7882names that are implementation defined (as permitted by the RM): 7883 7884 7885@itemize * 7886 7887@item 7888@code{Alignment_Check} can be used to suppress alignment checks 7889on addresses used in address clauses. Such checks can also be suppressed 7890by suppressing range checks, but the specific use of @code{Alignment_Check} 7891allows suppression of alignment checks without suppressing other range checks. 7892Note that @code{Alignment_Check} is suppressed by default on machines (such as 7893the x86) with non-strict alignment. 7894 7895@item 7896@code{Atomic_Synchronization} can be used to suppress the special memory 7897synchronization instructions that are normally generated for access to 7898@code{Atomic} variables to ensure correct synchronization between tasks 7899that use such variables for synchronization purposes. 7900 7901@item 7902@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated 7903for a duplicated tag value when a tagged type is declared. 7904 7905@item 7906@code{Container_Checks} Can be used to suppress all checks within Ada.Containers 7907and instances of its children, including Tampering_Check. 7908 7909@item 7910@code{Tampering_Check} Can be used to suppress tampering check in the containers. 7911 7912@item 7913@code{Predicate_Check} can be used to control whether predicate checks are 7914active. It is applicable only to predicates for which the policy is 7915@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given 7916predicate is ignored or checked for the whole program, the use of 7917@code{Suppress} and @code{Unsuppress} with this check name allows a given 7918predicate to be turned on and off at specific points in the program. 7919 7920@item 7921@code{Validity_Check} can be used specifically to control validity checks. 7922If @code{Suppress} is used to suppress validity checks, then no validity 7923checks are performed, including those specified by the appropriate compiler 7924switch or the @code{Validity_Checks} pragma. 7925 7926@item 7927Additional check names previously introduced by use of the @code{Check_Name} 7928pragma are also allowed. 7929@end itemize 7930 7931Note that pragma Suppress gives the compiler permission to omit 7932checks, but does not require the compiler to omit checks. The compiler 7933will generate checks if they are essentially free, even when they are 7934suppressed. In particular, if the compiler can prove that a certain 7935check will necessarily fail, it will generate code to do an 7936unconditional 'raise', even if checks are suppressed. The compiler 7937warns in this case. 7938 7939Of course, run-time checks are omitted whenever the compiler can prove 7940that they will not fail, whether or not checks are suppressed. 7941 7942@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas 7943@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f2} 7944@section Pragma Suppress_All 7945 7946 7947Syntax: 7948 7949@example 7950pragma Suppress_All; 7951@end example 7952 7953This pragma can appear anywhere within a unit. 7954The effect is to apply @code{Suppress (All_Checks)} to the unit 7955in which it appears. This pragma is implemented for compatibility with DEC 7956Ada 83 usage where it appears at the end of a unit, and for compatibility 7957with Rational Ada, where it appears as a program unit pragma. 7958The use of the standard Ada pragma @code{Suppress (All_Checks)} 7959as a normal configuration pragma is the preferred usage in GNAT. 7960 7961@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas 7962@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f3}@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f4} 7963@section Pragma Suppress_Debug_Info 7964 7965 7966Syntax: 7967 7968@example 7969pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); 7970@end example 7971 7972This pragma can be used to suppress generation of debug information 7973for the specified entity. It is intended primarily for use in debugging 7974the debugger, and navigating around debugger problems. 7975 7976@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas 7977@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f5} 7978@section Pragma Suppress_Exception_Locations 7979 7980 7981Syntax: 7982 7983@example 7984pragma Suppress_Exception_Locations; 7985@end example 7986 7987In normal mode, a raise statement for an exception by default generates 7988an exception message giving the file name and line number for the location 7989of the raise. This is useful for debugging and logging purposes, but this 7990entails extra space for the strings for the messages. The configuration 7991pragma @code{Suppress_Exception_Locations} can be used to suppress the 7992generation of these strings, with the result that space is saved, but the 7993exception message for such raises is null. This configuration pragma may 7994appear in a global configuration pragma file, or in a specific unit as 7995usual. It is not required that this pragma be used consistently within 7996a partition, so it is fine to have some units within a partition compiled 7997with this pragma and others compiled in normal mode without it. 7998 7999@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas 8000@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f6}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f7} 8001@section Pragma Suppress_Initialization 8002 8003 8004@geindex Suppressing initialization 8005 8006@geindex Initialization 8007@geindex suppression of 8008 8009Syntax: 8010 8011@example 8012pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); 8013@end example 8014 8015Here variable_or_subtype_Name is the name introduced by a type declaration 8016or subtype declaration or the name of a variable introduced by an 8017object declaration. 8018 8019In the case of a type or subtype 8020this pragma suppresses any implicit or explicit initialization 8021for all variables of the given type or subtype, 8022including initialization resulting from the use of pragmas 8023Normalize_Scalars or Initialize_Scalars. 8024 8025This is considered a representation item, so it cannot be given after 8026the type is frozen. It applies to all subsequent object declarations, 8027and also any allocator that creates objects of the type. 8028 8029If the pragma is given for the first subtype, then it is considered 8030to apply to the base type and all its subtypes. If the pragma is given 8031for other than a first subtype, then it applies only to the given subtype. 8032The pragma may not be given after the type is frozen. 8033 8034Note that this includes eliminating initialization of discriminants 8035for discriminated types, and tags for tagged types. In these cases, 8036you will have to use some non-portable mechanism (e.g. address 8037overlays or unchecked conversion) to achieve required initialization 8038of these fields before accessing any object of the corresponding type. 8039 8040For the variable case, implicit initialization for the named variable 8041is suppressed, just as though its subtype had been given in a pragma 8042Suppress_Initialization, as described above. 8043 8044@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas 8045@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f8} 8046@section Pragma Task_Name 8047 8048 8049Syntax 8050 8051@example 8052pragma Task_Name (string_EXPRESSION); 8053@end example 8054 8055This pragma appears within a task definition (like pragma 8056@code{Priority}) and applies to the task in which it appears. The 8057argument must be of type String, and provides a name to be used for 8058the task instance when the task is created. Note that this expression 8059is not required to be static, and in particular, it can contain 8060references to task discriminants. This facility can be used to 8061provide different names for different tasks as they are created, 8062as illustrated in the example below. 8063 8064The task name is recorded internally in the run-time structures 8065and is accessible to tools like the debugger. In addition the 8066routine @code{Ada.Task_Identification.Image} will return this 8067string, with a unique task address appended. 8068 8069@example 8070-- Example of the use of pragma Task_Name 8071 8072with Ada.Task_Identification; 8073use Ada.Task_Identification; 8074with Text_IO; use Text_IO; 8075procedure t3 is 8076 8077 type Astring is access String; 8078 8079 task type Task_Typ (Name : access String) is 8080 pragma Task_Name (Name.all); 8081 end Task_Typ; 8082 8083 task body Task_Typ is 8084 Nam : constant String := Image (Current_Task); 8085 begin 8086 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 8087 end Task_Typ; 8088 8089 type Ptr_Task is access Task_Typ; 8090 Task_Var : Ptr_Task; 8091 8092begin 8093 Task_Var := 8094 new Task_Typ (new String'("This is task 1")); 8095 Task_Var := 8096 new Task_Typ (new String'("This is task 2")); 8097end; 8098@end example 8099 8100@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas 8101@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f9} 8102@section Pragma Task_Storage 8103 8104 8105Syntax: 8106 8107@example 8108pragma Task_Storage ( 8109 [Task_Type =>] LOCAL_NAME, 8110 [Top_Guard =>] static_integer_EXPRESSION); 8111@end example 8112 8113This pragma specifies the length of the guard area for tasks. The guard 8114area is an additional storage area allocated to a task. A value of zero 8115means that either no guard area is created or a minimal guard area is 8116created, depending on the target. This pragma can appear anywhere a 8117@code{Storage_Size} attribute definition clause is allowed for a task 8118type. 8119 8120@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas 8121@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{fb} 8122@section Pragma Test_Case 8123 8124 8125@geindex Test cases 8126 8127Syntax: 8128 8129@example 8130pragma Test_Case ( 8131 [Name =>] static_string_Expression 8132 ,[Mode =>] (Nominal | Robustness) 8133 [, Requires => Boolean_Expression] 8134 [, Ensures => Boolean_Expression]); 8135@end example 8136 8137The @code{Test_Case} pragma allows defining fine-grain specifications 8138for use by testing tools. 8139The compiler checks the validity of the @code{Test_Case} pragma, but its 8140presence does not lead to any modification of the code generated by the 8141compiler. 8142 8143@code{Test_Case} pragmas may only appear immediately following the 8144(separate) declaration of a subprogram in a package declaration, inside 8145a package spec unit. Only other pragmas may intervene (that is appear 8146between the subprogram declaration and a test case). 8147 8148The compiler checks that boolean expressions given in @code{Requires} and 8149@code{Ensures} are valid, where the rules for @code{Requires} are the 8150same as the rule for an expression in @code{Precondition} and the rules 8151for @code{Ensures} are the same as the rule for an expression in 8152@code{Postcondition}. In particular, attributes @code{'Old} and 8153@code{'Result} can only be used within the @code{Ensures} 8154expression. The following is an example of use within a package spec: 8155 8156@example 8157package Math_Functions is 8158 ... 8159 function Sqrt (Arg : Float) return Float; 8160 pragma Test_Case (Name => "Test 1", 8161 Mode => Nominal, 8162 Requires => Arg < 10000.0, 8163 Ensures => Sqrt'Result < 10.0); 8164 ... 8165end Math_Functions; 8166@end example 8167 8168The meaning of a test case is that there is at least one context where 8169@code{Requires} holds such that, if the associated subprogram is executed in 8170that context, then @code{Ensures} holds when the subprogram returns. 8171Mode @code{Nominal} indicates that the input context should also satisfy the 8172precondition of the subprogram, and the output context should also satisfy its 8173postcondition. Mode @code{Robustness} indicates that the precondition and 8174postcondition of the subprogram should be ignored for this test case. 8175 8176@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas 8177@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fc}@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fd} 8178@section Pragma Thread_Local_Storage 8179 8180 8181@geindex Task specific storage 8182 8183@geindex TLS (Thread Local Storage) 8184 8185@geindex Task_Attributes 8186 8187Syntax: 8188 8189@example 8190pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 8191@end example 8192 8193This pragma specifies that the specified entity, which must be 8194a variable declared in a library-level package, is to be marked as 8195"Thread Local Storage" (@code{TLS}). On systems supporting this (which 8196include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each 8197thread (and hence each Ada task) to see a distinct copy of the variable. 8198 8199The variable must not have default initialization, and if there is 8200an explicit initialization, it must be either @code{null} for an 8201access variable, a static expression for a scalar variable, or a fully 8202static aggregate for a composite type, that is to say, an aggregate all 8203of whose components are static, and which does not include packed or 8204discriminated components. 8205 8206This provides a low-level mechanism similar to that provided by 8207the @code{Ada.Task_Attributes} package, but much more efficient 8208and is also useful in writing interface code that will interact 8209with foreign threads. 8210 8211If this pragma is used on a system where @code{TLS} is not supported, 8212then an error message will be generated and the program will be rejected. 8213 8214@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas 8215@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fe} 8216@section Pragma Time_Slice 8217 8218 8219Syntax: 8220 8221@example 8222pragma Time_Slice (static_duration_EXPRESSION); 8223@end example 8224 8225For implementations of GNAT on operating systems where it is possible 8226to supply a time slice value, this pragma may be used for this purpose. 8227It is ignored if it is used in a system that does not allow this control, 8228or if it appears in other than the main program unit. 8229 8230@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas 8231@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{ff} 8232@section Pragma Title 8233 8234 8235Syntax: 8236 8237@example 8238pragma Title (TITLING_OPTION [, TITLING OPTION]); 8239 8240TITLING_OPTION ::= 8241 [Title =>] STRING_LITERAL, 8242| [Subtitle =>] STRING_LITERAL 8243@end example 8244 8245Syntax checked but otherwise ignored by GNAT. This is a listing control 8246pragma used in DEC Ada 83 implementations to provide a title and/or 8247subtitle for the program listing. The program listing generated by GNAT 8248does not have titles or subtitles. 8249 8250Unlike other pragmas, the full flexibility of named notation is allowed 8251for this pragma, i.e., the parameters may be given in any order if named 8252notation is used, and named and positional notation can be mixed 8253following the normal rules for procedure calls in Ada. 8254 8255@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas 8256@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{100} 8257@section Pragma Type_Invariant 8258 8259 8260Syntax: 8261 8262@example 8263pragma Type_Invariant 8264 ([Entity =>] type_LOCAL_NAME, 8265 [Check =>] EXPRESSION); 8266@end example 8267 8268The @code{Type_Invariant} pragma is intended to be an exact 8269replacement for the language-defined @code{Type_Invariant} 8270aspect, and shares its restrictions and semantics. It differs 8271from the language defined @code{Invariant} pragma in that it 8272does not permit a string parameter, and it is 8273controlled by the assertion identifier @code{Type_Invariant} 8274rather than @code{Invariant}. 8275 8276@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas 8277@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{101}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{102} 8278@section Pragma Type_Invariant_Class 8279 8280 8281Syntax: 8282 8283@example 8284pragma Type_Invariant_Class 8285 ([Entity =>] type_LOCAL_NAME, 8286 [Check =>] EXPRESSION); 8287@end example 8288 8289The @code{Type_Invariant_Class} pragma is intended to be an exact 8290replacement for the language-defined @code{Type_Invariant'Class} 8291aspect, and shares its restrictions and semantics. 8292 8293Note: This pragma is called @code{Type_Invariant_Class} rather than 8294@code{Type_Invariant'Class} because the latter would not be strictly 8295conforming to the allowed syntax for pragmas. The motivation 8296for providing pragmas equivalent to the aspects is to allow a program 8297to be written using the pragmas, and then compiled if necessary 8298using an Ada compiler that does not recognize the pragmas or 8299aspects, but is prepared to ignore the pragmas. The assertion 8300policy that controls this pragma is @code{Type_Invariant'Class}, 8301not @code{Type_Invariant_Class}. 8302 8303@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas 8304@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{103} 8305@section Pragma Unchecked_Union 8306 8307 8308@geindex Unions in C 8309 8310Syntax: 8311 8312@example 8313pragma Unchecked_Union (first_subtype_LOCAL_NAME); 8314@end example 8315 8316This pragma is used to specify a representation of a record type that is 8317equivalent to a C union. It was introduced as a GNAT implementation defined 8318pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 8319pragma, making it language defined, and GNAT fully implements this extended 8320version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 8321details, consult the Ada 2012 Reference Manual, section B.3.3. 8322 8323@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas 8324@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{104} 8325@section Pragma Unevaluated_Use_Of_Old 8326 8327 8328@geindex Attribute Old 8329 8330@geindex Attribute Loop_Entry 8331 8332@geindex Unevaluated_Use_Of_Old 8333 8334Syntax: 8335 8336@example 8337pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); 8338@end example 8339 8340This pragma controls the processing of attributes Old and Loop_Entry. 8341If either of these attributes is used in a potentially unevaluated 8342expression (e.g. the then or else parts of an if expression), then 8343normally this usage is considered illegal if the prefix of the attribute 8344is other than an entity name. The language requires this 8345behavior for Old, and GNAT copies the same rule for Loop_Entry. 8346 8347The reason for this rule is that otherwise, we can have a situation 8348where we save the Old value, and this results in an exception, even 8349though we might not evaluate the attribute. Consider this example: 8350 8351@example 8352package UnevalOld is 8353 K : Character; 8354 procedure U (A : String; C : Boolean) -- ERROR 8355 with Post => (if C then A(1)'Old = K else True); 8356end; 8357@end example 8358 8359If procedure U is called with a string with a lower bound of 2, and 8360C false, then an exception would be raised trying to evaluate A(1) 8361on entry even though the value would not be actually used. 8362 8363Although the rule guarantees against this possibility, it is sometimes 8364too restrictive. For example if we know that the string has a lower 8365bound of 1, then we will never raise an exception. 8366The pragma @code{Unevaluated_Use_Of_Old} can be 8367used to modify this behavior. If the argument is @code{Error} then an 8368error is given (this is the default RM behavior). If the argument is 8369@code{Warn} then the usage is allowed as legal but with a warning 8370that an exception might be raised. If the argument is @code{Allow} 8371then the usage is allowed as legal without generating a warning. 8372 8373This pragma may appear as a configuration pragma, or in a declarative 8374part or package specification. In the latter case it applies to 8375uses up to the end of the corresponding statement sequence or 8376sequence of package declarations. 8377 8378@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas 8379@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{105} 8380@section Pragma Unimplemented_Unit 8381 8382 8383Syntax: 8384 8385@example 8386pragma Unimplemented_Unit; 8387@end example 8388 8389If this pragma occurs in a unit that is processed by the compiler, GNAT 8390aborts with the message @code{xxx not implemented}, where 8391@code{xxx} is the name of the current compilation unit. This pragma is 8392intended to allow the compiler to handle unimplemented library units in 8393a clean manner. 8394 8395The abort only happens if code is being generated. Thus you can use 8396specs of unimplemented packages in syntax or semantic checking mode. 8397 8398@node Pragma Universal_Aliasing,Pragma Universal_Data,Pragma Unimplemented_Unit,Implementation Defined Pragmas 8399@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{106}@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{107} 8400@section Pragma Universal_Aliasing 8401 8402 8403Syntax: 8404 8405@example 8406pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 8407@end example 8408 8409@code{type_LOCAL_NAME} must refer to a type declaration in the current 8410declarative part. The effect is to inhibit strict type-based aliasing 8411optimization for the given type. In other words, the effect is as though 8412access types designating this type were subject to pragma No_Strict_Aliasing. 8413For a detailed description of the strict aliasing optimization, and the 8414situations in which it must be suppressed, see the section on 8415@code{Optimization and Strict Aliasing} in the @cite{GNAT User's Guide}. 8416 8417@node Pragma Universal_Data,Pragma Unmodified,Pragma Universal_Aliasing,Implementation Defined Pragmas 8418@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-data}@anchor{108}@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{109} 8419@section Pragma Universal_Data 8420 8421 8422Syntax: 8423 8424@example 8425pragma Universal_Data [(library_unit_Name)]; 8426@end example 8427 8428This pragma is supported only for the AAMP target and is ignored for 8429other targets. The pragma specifies that all library-level objects 8430(Counter 0 data) associated with the library unit are to be accessed 8431and updated using universal addressing (24-bit addresses for AAMP5) 8432rather than the default of 16-bit Data Environment (DENV) addressing. 8433Use of this pragma will generally result in less efficient code for 8434references to global data associated with the library unit, but 8435allows such data to be located anywhere in memory. This pragma is 8436a library unit pragma, but can also be used as a configuration pragma 8437(including use in the @code{gnat.adc} file). The functionality 8438of this pragma is also available by applying the -univ switch on the 8439compilations of units where universal addressing of the data is desired. 8440 8441@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Data,Implementation Defined Pragmas 8442@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{10b} 8443@section Pragma Unmodified 8444 8445 8446@geindex Warnings 8447@geindex unmodified 8448 8449Syntax: 8450 8451@example 8452pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); 8453@end example 8454 8455This pragma signals that the assignable entities (variables, 8456@code{out} parameters, @code{in out} parameters) whose names are listed are 8457deliberately not assigned in the current source unit. This 8458suppresses warnings about the 8459entities being referenced but not assigned, and in addition a warning will be 8460generated if one of these entities is in fact assigned in the 8461same unit as the pragma (or in the corresponding body, or one 8462of its subunits). 8463 8464This is particularly useful for clearly signaling that a particular 8465parameter is not modified, even though the spec suggests that it might 8466be. 8467 8468For the variable case, warnings are never given for unreferenced variables 8469whose name contains one of the substrings 8470@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8471are typically to be used in cases where such warnings are expected. 8472Thus it is never necessary to use @code{pragma Unmodified} for such 8473variables, though it is harmless to do so. 8474 8475@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas 8476@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10d} 8477@section Pragma Unreferenced 8478 8479 8480@geindex Warnings 8481@geindex unreferenced 8482 8483Syntax: 8484 8485@example 8486pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); 8487pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); 8488@end example 8489 8490This pragma signals that the entities whose names are listed are 8491deliberately not referenced in the current source unit after the 8492occurrence of the pragma. This 8493suppresses warnings about the 8494entities being unreferenced, and in addition a warning will be 8495generated if one of these entities is in fact subsequently referenced in the 8496same unit as the pragma (or in the corresponding body, or one 8497of its subunits). 8498 8499This is particularly useful for clearly signaling that a particular 8500parameter is not referenced in some particular subprogram implementation 8501and that this is deliberate. It can also be useful in the case of 8502objects declared only for their initialization or finalization side 8503effects. 8504 8505If @code{LOCAL_NAME} identifies more than one matching homonym in the 8506current scope, then the entity most recently declared is the one to which 8507the pragma applies. Note that in the case of accept formals, the pragma 8508Unreferenced may appear immediately after the keyword @code{do} which 8509allows the indication of whether or not accept formals are referenced 8510or not to be given individually for each accept statement. 8511 8512The left hand side of an assignment does not count as a reference for the 8513purpose of this pragma. Thus it is fine to assign to an entity for which 8514pragma Unreferenced is given. 8515 8516Note that if a warning is desired for all calls to a given subprogram, 8517regardless of whether they occur in the same unit as the subprogram 8518declaration, then this pragma should not be used (calls from another 8519unit would not be flagged); pragma Obsolescent can be used instead 8520for this purpose, see @ref{ac,,Pragma Obsolescent}. 8521 8522The second form of pragma @code{Unreferenced} is used within a context 8523clause. In this case the arguments must be unit names of units previously 8524mentioned in @code{with} clauses (similar to the usage of pragma 8525@code{Elaborate_All}. The effect is to suppress warnings about unreferenced 8526units and unreferenced entities within these units. 8527 8528For the variable case, warnings are never given for unreferenced variables 8529whose name contains one of the substrings 8530@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8531are typically to be used in cases where such warnings are expected. 8532Thus it is never necessary to use @code{pragma Unreferenced} for such 8533variables, though it is harmless to do so. 8534 8535@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas 8536@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10e}@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{10f} 8537@section Pragma Unreferenced_Objects 8538 8539 8540@geindex Warnings 8541@geindex unreferenced 8542 8543Syntax: 8544 8545@example 8546pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); 8547@end example 8548 8549This pragma signals that for the types or subtypes whose names are 8550listed, objects which are declared with one of these types or subtypes may 8551not be referenced, and if no references appear, no warnings are given. 8552 8553This is particularly useful for objects which are declared solely for their 8554initialization and finalization effect. Such variables are sometimes referred 8555to as RAII variables (Resource Acquisition Is Initialization). Using this 8556pragma on the relevant type (most typically a limited controlled type), the 8557compiler will automatically suppress unwanted warnings about these variables 8558not being referenced. 8559 8560@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas 8561@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{110} 8562@section Pragma Unreserve_All_Interrupts 8563 8564 8565Syntax: 8566 8567@example 8568pragma Unreserve_All_Interrupts; 8569@end example 8570 8571Normally certain interrupts are reserved to the implementation. Any attempt 8572to attach an interrupt causes Program_Error to be raised, as described in 8573RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 8574many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is 8575reserved to the implementation, so that @code{Ctrl-C} can be used to 8576interrupt execution. 8577 8578If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in 8579a program, then all such interrupts are unreserved. This allows the 8580program to handle these interrupts, but disables their standard 8581functions. For example, if this pragma is used, then pressing 8582@code{Ctrl-C} will not automatically interrupt execution. However, 8583a program can then handle the @code{SIGINT} interrupt as it chooses. 8584 8585For a full list of the interrupts handled in a specific implementation, 8586see the source code for the spec of @code{Ada.Interrupts.Names} in 8587file @code{a-intnam.ads}. This is a target dependent file that contains the 8588list of interrupts recognized for a given target. The documentation in 8589this file also specifies what interrupts are affected by the use of 8590the @code{Unreserve_All_Interrupts} pragma. 8591 8592For a more general facility for controlling what interrupts can be 8593handled, see pragma @code{Interrupt_State}, which subsumes the functionality 8594of the @code{Unreserve_All_Interrupts} pragma. 8595 8596@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas 8597@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{111} 8598@section Pragma Unsuppress 8599 8600 8601Syntax: 8602 8603@example 8604pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 8605@end example 8606 8607This pragma undoes the effect of a previous pragma @code{Suppress}. If 8608there is no corresponding pragma @code{Suppress} in effect, it has no 8609effect. The range of the effect is the same as for pragma 8610@code{Suppress}. The meaning of the arguments is identical to that used 8611in pragma @code{Suppress}. 8612 8613One important application is to ensure that checks are on in cases where 8614code depends on the checks for its correct functioning, so that the code 8615will compile correctly even if the compiler switches are set to suppress 8616checks. For example, in a program that depends on external names of tagged 8617types and wants to ensure that the duplicated tag check occurs even if all 8618run-time checks are suppressed by a compiler switch, the following 8619configuration pragma will ensure this test is not suppressed: 8620 8621@example 8622pragma Unsuppress (Duplicated_Tag_Check); 8623@end example 8624 8625This pragma is standard in Ada 2005. It is available in all earlier versions 8626of Ada as an implementation-defined pragma. 8627 8628Note that in addition to the checks defined in the Ada RM, GNAT recogizes a 8629number of implementation-defined check names. See the description of pragma 8630@code{Suppress} for full details. 8631 8632@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas 8633@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{112} 8634@section Pragma Use_VADS_Size 8635 8636 8637@geindex Size 8638@geindex VADS compatibility 8639 8640@geindex Rational profile 8641 8642Syntax: 8643 8644@example 8645pragma Use_VADS_Size; 8646@end example 8647 8648This is a configuration pragma. In a unit to which it applies, any use 8649of the 'Size attribute is automatically interpreted as a use of the 8650'VADS_Size attribute. Note that this may result in incorrect semantic 8651processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 8652the handling of existing code which depends on the interpretation of Size 8653as implemented in the VADS compiler. See description of the VADS_Size 8654attribute for further details. 8655 8656@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas 8657@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{113}@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{114} 8658@section Pragma Unused 8659 8660 8661@geindex Warnings 8662@geindex unused 8663 8664Syntax: 8665 8666@example 8667pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); 8668@end example 8669 8670This pragma signals that the assignable entities (variables, 8671@code{out} parameters, and @code{in out} parameters) whose names are listed 8672deliberately do not get assigned or referenced in the current source unit 8673after the occurrence of the pragma in the current source unit. This 8674suppresses warnings about the entities that are unreferenced and/or not 8675assigned, and, in addition, a warning will be generated if one of these 8676entities gets assigned or subsequently referenced in the same unit as the 8677pragma (in the corresponding body or one of its subunits). 8678 8679This is particularly useful for clearly signaling that a particular 8680parameter is not modified or referenced, even though the spec suggests 8681that it might be. 8682 8683For the variable case, warnings are never given for unreferenced 8684variables whose name contains one of the substrings 8685@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 8686are typically to be used in cases where such warnings are expected. 8687Thus it is never necessary to use @code{pragma Unmodified} for such 8688variables, though it is harmless to do so. 8689 8690@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas 8691@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{115} 8692@section Pragma Validity_Checks 8693 8694 8695Syntax: 8696 8697@example 8698pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 8699@end example 8700 8701This pragma is used in conjunction with compiler switches to control the 8702built-in validity checking provided by GNAT. The compiler switches, if set 8703provide an initial setting for the switches, and this pragma may be used 8704to modify these settings, or the settings may be provided entirely by 8705the use of the pragma. This pragma can be used anywhere that a pragma 8706is legal, including use as a configuration pragma (including use in 8707the @code{gnat.adc} file). 8708 8709The form with a string literal specifies which validity options are to be 8710activated. The validity checks are first set to include only the default 8711reference manual settings, and then a string of letters in the string 8712specifies the exact set of options required. The form of this string 8713is exactly as described for the @emph{-gnatVx} compiler switch (see the 8714GNAT User's Guide for details). For example the following two 8715methods can be used to enable validity checking for mode @code{in} and 8716@code{in out} subprogram parameters: 8717 8718 8719@itemize * 8720 8721@item 8722@example 8723pragma Validity_Checks ("im"); 8724@end example 8725 8726@item 8727@example 8728$ gcc -c -gnatVim ... 8729@end example 8730@end itemize 8731 8732The form ALL_CHECKS activates all standard checks (its use is equivalent 8733to the use of the @code{gnatVa} switch). 8734 8735The forms with @code{Off} and @code{On} can be used to temporarily disable 8736validity checks as shown in the following example: 8737 8738@example 8739pragma Validity_Checks ("c"); -- validity checks for copies 8740pragma Validity_Checks (Off); -- turn off validity checks 8741A := B; -- B will not be validity checked 8742pragma Validity_Checks (On); -- turn validity checks back on 8743A := C; -- C will be validity checked 8744@end example 8745 8746@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas 8747@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{116}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{117} 8748@section Pragma Volatile 8749 8750 8751Syntax: 8752 8753@example 8754pragma Volatile (LOCAL_NAME); 8755@end example 8756 8757This pragma is defined by the Ada Reference Manual, and the GNAT 8758implementation is fully conformant with this definition. The reason it 8759is mentioned in this section is that a pragma of the same name was supplied 8760in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 8761implementation of pragma Volatile is upwards compatible with the 8762implementation in DEC Ada 83. 8763 8764@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas 8765@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{118}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{119} 8766@section Pragma Volatile_Full_Access 8767 8768 8769Syntax: 8770 8771@example 8772pragma Volatile_Full_Access (LOCAL_NAME); 8773@end example 8774 8775This is similar in effect to pragma Volatile, except that any reference to the 8776object is guaranteed to be done only with instructions that read or write all 8777the bits of the object. Furthermore, if the object is of a composite type, 8778then any reference to a subcomponent of the object is guaranteed to read 8779and/or write all the bits of the object. 8780 8781The intention is that this be suitable for use with memory-mapped I/O devices 8782on some machines. Note that there are two important respects in which this is 8783different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} 8784object is not a sequential action in the RM 9.10 sense and, therefore, does 8785not create a synchronization point. Second, in the case of @code{pragma Atomic}, 8786there is no guarantee that all the bits will be accessed if the reference 8787is not to the whole object; the compiler is allowed (and generally will) 8788access only part of the object in this case. 8789 8790@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas 8791@anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11a}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{11b} 8792@section Pragma Volatile_Function 8793 8794 8795Syntax: 8796 8797@example 8798pragma Volatile_Function [ (boolean_EXPRESSION) ]; 8799@end example 8800 8801For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} 8802in the SPARK 2014 Reference Manual, section 7.1.2. 8803 8804@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas 8805@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{11c} 8806@section Pragma Warning_As_Error 8807 8808 8809Syntax: 8810 8811@example 8812pragma Warning_As_Error (static_string_EXPRESSION); 8813@end example 8814 8815This configuration pragma allows the programmer to specify a set 8816of warnings that will be treated as errors. Any warning that 8817matches the pattern given by the pragma argument will be treated 8818as an error. This gives more precise control than -gnatwe, 8819which treats warnings as errors. 8820 8821This pragma can apply to regular warnings (messages enabled by -gnatw) 8822and to style warnings (messages that start with "(style)", 8823enabled by -gnaty). 8824 8825The pattern may contain asterisks, which match zero or more characters 8826in the message. For example, you can use @code{pragma Warning_As_Error 8827("bits of*unused")} to treat the warning message @code{warning: 960 bits of 8828"a" unused} as an error. All characters other than asterisk are treated 8829as literal characters in the match. The match is case insensitive; for 8830example XYZ matches xyz. 8831 8832Note that the pattern matches if it occurs anywhere within the warning 8833message string (it is not necessary to put an asterisk at the start and 8834the end of the message, since this is implied). 8835 8836Another possibility for the static_string_EXPRESSION which works whether 8837or not error tags are enabled (@emph{-gnatw.d}) is to use a single 8838@emph{-gnatw} tag string, enclosed in brackets, 8839as shown in the example below, to treat one category of warnings as errors. 8840Note that if you want to treat multiple categories of warnings as errors, 8841you can use multiple pragma Warning_As_Error. 8842 8843The above use of patterns to match the message applies only to warning 8844messages generated by the front end. This pragma can also be applied to 8845warnings provided by the back end and mentioned in @ref{11d,,Pragma Warnings}. 8846By using a single full @emph{-Wxxx} switch in the pragma, such warnings 8847can also be treated as errors. 8848 8849The pragma can appear either in a global configuration pragma file 8850(e.g. @code{gnat.adc}), or at the start of a file. Given a global 8851configuration pragma file containing: 8852 8853@example 8854pragma Warning_As_Error ("[-gnatwj]"); 8855@end example 8856 8857which will treat all obsolescent feature warnings as errors, the 8858following program compiles as shown (compile options here are 8859@emph{-gnatwa.d -gnatl -gnatj55}). 8860 8861@example 8862 1. pragma Warning_As_Error ("*never assigned*"); 8863 2. function Warnerr return String is 8864 3. X : Integer; 8865 | 8866 >>> error: variable "X" is never read and 8867 never assigned [-gnatwv] [warning-as-error] 8868 8869 4. Y : Integer; 8870 | 8871 >>> warning: variable "Y" is assigned but 8872 never read [-gnatwu] 8873 8874 5. begin 8875 6. Y := 0; 8876 7. return %ABC%; 8877 | 8878 >>> error: use of "%" is an obsolescent 8879 feature (RM J.2(4)), use """ instead 8880 [-gnatwj] [warning-as-error] 8881 8882 8. end; 8883 88848 lines: No errors, 3 warnings (2 treated as errors) 8885@end example 8886 8887Note that this pragma does not affect the set of warnings issued in 8888any way, it merely changes the effect of a matching warning if one 8889is produced as a result of other warnings options. As shown in this 8890example, if the pragma results in a warning being treated as an error, 8891the tag is changed from "warning:" to "error:" and the string 8892"[warning-as-error]" is appended to the end of the message. 8893 8894@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas 8895@anchor{gnat_rm/implementation_defined_pragmas id57}@anchor{11e}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11d} 8896@section Pragma Warnings 8897 8898 8899Syntax: 8900 8901@example 8902pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); 8903 8904DETAILS ::= On | Off 8905DETAILS ::= On | Off, local_NAME 8906DETAILS ::= static_string_EXPRESSION 8907DETAILS ::= On | Off, static_string_EXPRESSION 8908 8909TOOL_NAME ::= GNAT | GNATprove 8910 8911REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} 8912@end example 8913 8914Note: in Ada 83 mode, a string literal may be used in place of a static string 8915expression (which does not exist in Ada 83). 8916 8917Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the 8918second form is always understood. If the intention is to use 8919the fourth form, then you can write @code{NAME & ""} to force the 8920intepretation as a @emph{static_string_EXPRESSION}. 8921 8922Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted 8923that way. The use of the @code{TOOL_NAME} argument is relevant only to users 8924of SPARK and GNATprove, see last part of this section for details. 8925 8926Normally warnings are enabled, with the output being controlled by 8927the command line switch. Warnings (@code{Off}) turns off generation of 8928warnings until a Warnings (@code{On}) is encountered or the end of the 8929current unit. If generation of warnings is turned off using this 8930pragma, then some or all of the warning messages are suppressed, 8931regardless of the setting of the command line switches. 8932 8933The @code{Reason} parameter may optionally appear as the last argument 8934in any of the forms of this pragma. It is intended purely for the 8935purposes of documenting the reason for the @code{Warnings} pragma. 8936The compiler will check that the argument is a static string but 8937otherwise ignore this argument. Other tools may provide specialized 8938processing for this string. 8939 8940The form with a single argument (or two arguments if Reason present), 8941where the first argument is @code{ON} or @code{OFF} 8942may be used as a configuration pragma. 8943 8944If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for 8945the specified entity. This suppression is effective from the point where 8946it occurs till the end of the extended scope of the variable (similar to 8947the scope of @code{Suppress}). This form cannot be used as a configuration 8948pragma. 8949 8950In the case where the first argument is other than @code{ON} or 8951@code{OFF}, 8952the third form with a single static_string_EXPRESSION argument (and possible 8953reason) provides more precise 8954control over which warnings are active. The string is a list of letters 8955specifying which warnings are to be activated and which deactivated. The 8956code for these letters is the same as the string used in the command 8957line switch controlling warnings. For a brief summary, use the gnatmake 8958command with no arguments, which will generate usage information containing 8959the list of warnings switches supported. For 8960full details see the section on @code{Warning Message Control} in the 8961@cite{GNAT User's Guide}. 8962This form can also be used as a configuration pragma. 8963 8964The warnings controlled by the @code{-gnatw} switch are generated by the 8965front end of the compiler. The GCC back end can provide additional warnings 8966and they are controlled by the @code{-W} switch. Such warnings can be 8967identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the 8968message which designates the @code{-W@emph{xxx}} switch that controls the message. 8969The form with a single @emph{static_string_EXPRESSION} argument also works for these 8970warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this 8971case. The above reference lists a few examples of these additional warnings. 8972 8973The specified warnings will be in effect until the end of the program 8974or another pragma @code{Warnings} is encountered. The effect of the pragma is 8975cumulative. Initially the set of warnings is the standard default set 8976as possibly modified by compiler switches. Then each pragma Warning 8977modifies this set of warnings as specified. This form of the pragma may 8978also be used as a configuration pragma. 8979 8980The fourth form, with an @code{On|Off} parameter and a string, is used to 8981control individual messages, based on their text. The string argument 8982is a pattern that is used to match against the text of individual 8983warning messages (not including the initial "warning: " tag). 8984 8985The pattern may contain asterisks, which match zero or more characters in 8986the message. For example, you can use 8987@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning 8988message @code{warning: 960 bits of "a" unused}. No other regular 8989expression notations are permitted. All characters other than asterisk in 8990these three specific cases are treated as literal characters in the match. 8991The match is case insensitive, for example XYZ matches xyz. 8992 8993Note that the pattern matches if it occurs anywhere within the warning 8994message string (it is not necessary to put an asterisk at the start and 8995the end of the message, since this is implied). 8996 8997The above use of patterns to match the message applies only to warning 8998messages generated by the front end. This form of the pragma with a string 8999argument can also be used to control warnings provided by the back end and 9000mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma, 9001such warnings can be turned on and off. 9002 9003There are two ways to use the pragma in this form. The OFF form can be used 9004as a configuration pragma. The effect is to suppress all warnings (if any) 9005that match the pattern string throughout the compilation (or match the 9006-W switch in the back end case). 9007 9008The second usage is to suppress a warning locally, and in this case, two 9009pragmas must appear in sequence: 9010 9011@example 9012pragma Warnings (Off, Pattern); 9013... code where given warning is to be suppressed 9014pragma Warnings (On, Pattern); 9015@end example 9016 9017In this usage, the pattern string must match in the Off and On 9018pragmas, and (if @emph{-gnatw.w} is given) at least one matching 9019warning must be suppressed. 9020 9021Note: if the ON form is not found, then the effect of the OFF form extends 9022until the end of the file (pragma Warnings is purely textual, so its effect 9023does not stop at the end of the enclosing scope). 9024 9025Note: to write a string that will match any warning, use the string 9026@code{"***"}. It will not work to use a single asterisk or two 9027asterisks since this looks like an operator name. This form with three 9028asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching 9029@code{pragma Warnings (On, "***")} will be required. This can be 9030helpful in avoiding forgetting to turn warnings back on. 9031 9032Note: the debug flag @code{-gnatd.i} can be 9033used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 9034be useful in checking whether obsolete pragmas in existing programs are hiding 9035real problems. 9036 9037Note: pragma Warnings does not affect the processing of style messages. See 9038separate entry for pragma Style_Checks for control of style messages. 9039 9040Users of the formal verification tool GNATprove for the SPARK subset of Ada may 9041use the version of the pragma with a @code{TOOL_NAME} parameter. 9042 9043If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the 9044compiler or @code{GNATprove} for the formal verification tool. A given tool only 9045takes into account pragma Warnings that do not specify a tool name, or that 9046specify the matching tool name. This makes it possible to disable warnings 9047selectively for each tool, and as a consequence to detect useless pragma 9048Warnings with switch @code{-gnatw.w}. 9049 9050@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas 9051@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11f} 9052@section Pragma Weak_External 9053 9054 9055Syntax: 9056 9057@example 9058pragma Weak_External ([Entity =>] LOCAL_NAME); 9059@end example 9060 9061@code{LOCAL_NAME} must refer to an object that is declared at the library 9062level. This pragma specifies that the given entity should be marked as a 9063weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} 9064in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead 9065of a regular symbol, that is to say a symbol that does not have to be 9066resolved by the linker if used in conjunction with a pragma Import. 9067 9068When a weak symbol is not resolved by the linker, its address is set to 9069zero. This is useful in writing interfaces to external modules that may 9070or may not be linked in the final executable, for example depending on 9071configuration settings. 9072 9073If a program references at run time an entity to which this pragma has been 9074applied, and the corresponding symbol was not resolved at link time, then 9075the execution of the program is erroneous. It is not erroneous to take the 9076Address of such an entity, for example to guard potential references, 9077as shown in the example below. 9078 9079Some file formats do not support weak symbols so not all target machines 9080support this pragma. 9081 9082@example 9083-- Example of the use of pragma Weak_External 9084 9085package External_Module is 9086 key : Integer; 9087 pragma Import (C, key); 9088 pragma Weak_External (key); 9089 function Present return boolean; 9090end External_Module; 9091 9092with System; use System; 9093package body External_Module is 9094 function Present return boolean is 9095 begin 9096 return key'Address /= System.Null_Address; 9097 end Present; 9098end External_Module; 9099@end example 9100 9101@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas 9102@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{120} 9103@section Pragma Wide_Character_Encoding 9104 9105 9106Syntax: 9107 9108@example 9109pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 9110@end example 9111 9112This pragma specifies the wide character encoding to be used in program 9113source text appearing subsequently. It is a configuration pragma, but may 9114also be used at any point that a pragma is allowed, and it is permissible 9115to have more than one such pragma in a file, allowing multiple encodings 9116to appear within the same file. 9117 9118However, note that the pragma cannot immediately precede the relevant 9119wide character, because then the previous encoding will still be in 9120effect, causing "illegal character" errors. 9121 9122The argument can be an identifier or a character literal. In the identifier 9123case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, 9124@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal 9125case it is correspondingly one of the characters @code{h}, @code{u}, 9126@code{s}, @code{e}, @code{8}, or @code{b}. 9127 9128Note that when the pragma is used within a file, it affects only the 9129encoding within that file, and does not affect withed units, specs, 9130or subunits. 9131 9132@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top 9133@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{121}@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{122}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{123} 9134@chapter Implementation Defined Aspects 9135 9136 9137Ada defines (throughout the Ada 2012 reference manual, summarized 9138in Annex K) a set of aspects that can be specified for certain entities. 9139These language defined aspects are implemented in GNAT in Ada 2012 mode 9140and work as described in the Ada 2012 Reference Manual. 9141 9142In addition, Ada 2012 allows implementations to define additional aspects 9143whose meaning is defined by the implementation. GNAT provides 9144a number of these implementation-defined aspects which can be used 9145to extend and enhance the functionality of the compiler. This section of 9146the GNAT reference manual describes these additional aspects. 9147 9148Note that any program using these aspects may not be portable to 9149other compilers (although GNAT implements this set of aspects on all 9150platforms). Therefore if portability to other compilers is an important 9151consideration, you should minimize the use of these aspects. 9152 9153Note that for many of these aspects, the effect is essentially similar 9154to the use of a pragma or attribute specification with the same name 9155applied to the entity. For example, if we write: 9156 9157@example 9158type R is range 1 .. 100 9159 with Value_Size => 10; 9160@end example 9161 9162then the effect is the same as: 9163 9164@example 9165type R is range 1 .. 100; 9166for R'Value_Size use 10; 9167@end example 9168 9169and if we write: 9170 9171@example 9172type R is new Integer 9173 with Shared => True; 9174@end example 9175 9176then the effect is the same as: 9177 9178@example 9179type R is new Integer; 9180pragma Shared (R); 9181@end example 9182 9183In the documentation below, such cases are simply marked 9184as being boolean aspects equivalent to the corresponding pragma 9185or attribute definition clause. 9186 9187@menu 9188* Aspect Abstract_State:: 9189* Aspect Annotate:: 9190* Aspect Async_Readers:: 9191* Aspect Async_Writers:: 9192* Aspect Constant_After_Elaboration:: 9193* Aspect Contract_Cases:: 9194* Aspect Depends:: 9195* Aspect Default_Initial_Condition:: 9196* Aspect Dimension:: 9197* Aspect Dimension_System:: 9198* Aspect Disable_Controlled:: 9199* Aspect Effective_Reads:: 9200* Aspect Effective_Writes:: 9201* Aspect Extensions_Visible:: 9202* Aspect Favor_Top_Level:: 9203* Aspect Ghost:: 9204* Aspect Global:: 9205* Aspect Initial_Condition:: 9206* Aspect Initializes:: 9207* Aspect Inline_Always:: 9208* Aspect Invariant:: 9209* Aspect Invariant'Class:: 9210* Aspect Iterable:: 9211* Aspect Linker_Section:: 9212* Aspect Lock_Free:: 9213* Aspect Max_Queue_Length:: 9214* Aspect No_Caching:: 9215* Aspect No_Elaboration_Code_All:: 9216* Aspect No_Inline:: 9217* Aspect No_Tagged_Streams:: 9218* Aspect Object_Size:: 9219* Aspect Obsolescent:: 9220* Aspect Part_Of:: 9221* Aspect Persistent_BSS:: 9222* Aspect Predicate:: 9223* Aspect Pure_Function:: 9224* Aspect Refined_Depends:: 9225* Aspect Refined_Global:: 9226* Aspect Refined_Post:: 9227* Aspect Refined_State:: 9228* Aspect Relaxed_Initialization:: 9229* Aspect Remote_Access_Type:: 9230* Aspect Secondary_Stack_Size:: 9231* Aspect Scalar_Storage_Order:: 9232* Aspect Shared:: 9233* Aspect Simple_Storage_Pool:: 9234* Aspect Simple_Storage_Pool_Type:: 9235* Aspect SPARK_Mode:: 9236* Aspect Suppress_Debug_Info:: 9237* Aspect Suppress_Initialization:: 9238* Aspect Test_Case:: 9239* Aspect Thread_Local_Storage:: 9240* Aspect Universal_Aliasing:: 9241* Aspect Universal_Data:: 9242* Aspect Unmodified:: 9243* Aspect Unreferenced:: 9244* Aspect Unreferenced_Objects:: 9245* Aspect Value_Size:: 9246* Aspect Volatile_Full_Access:: 9247* Aspect Volatile_Function:: 9248* Aspect Warnings:: 9249 9250@end menu 9251 9252@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects 9253@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{124} 9254@section Aspect Abstract_State 9255 9256 9257@geindex Abstract_State 9258 9259This aspect is equivalent to @ref{1c,,pragma Abstract_State}. 9260 9261@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects 9262@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{125} 9263@section Aspect Annotate 9264 9265 9266@geindex Annotate 9267 9268There are three forms of this aspect (where ID is an identifier, 9269and ARG is a general expression), 9270corresponding to @ref{26,,pragma Annotate}. 9271 9272 9273@table @asis 9274 9275@item @emph{Annotate => ID} 9276 9277Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9278 9279@item @emph{Annotate => (ID)} 9280 9281Equivalent to @code{pragma Annotate (ID, Entity => Name);} 9282 9283@item @emph{Annotate => (ID ,ID @{, ARG@})} 9284 9285Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} 9286@end table 9287 9288@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects 9289@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{126} 9290@section Aspect Async_Readers 9291 9292 9293@geindex Async_Readers 9294 9295This boolean aspect is equivalent to @ref{2d,,pragma Async_Readers}. 9296 9297@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects 9298@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{127} 9299@section Aspect Async_Writers 9300 9301 9302@geindex Async_Writers 9303 9304This boolean aspect is equivalent to @ref{30,,pragma Async_Writers}. 9305 9306@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects 9307@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{128} 9308@section Aspect Constant_After_Elaboration 9309 9310 9311@geindex Constant_After_Elaboration 9312 9313This aspect is equivalent to @ref{42,,pragma Constant_After_Elaboration}. 9314 9315@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects 9316@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{129} 9317@section Aspect Contract_Cases 9318 9319 9320@geindex Contract_Cases 9321 9322This aspect is equivalent to @ref{44,,pragma Contract_Cases}, the sequence 9323of clauses being enclosed in parentheses so that syntactically it is an 9324aggregate. 9325 9326@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects 9327@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{12a} 9328@section Aspect Depends 9329 9330 9331@geindex Depends 9332 9333This aspect is equivalent to @ref{53,,pragma Depends}. 9334 9335@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects 9336@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{12b} 9337@section Aspect Default_Initial_Condition 9338 9339 9340@geindex Default_Initial_Condition 9341 9342This aspect is equivalent to @ref{4e,,pragma Default_Initial_Condition}. 9343 9344@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects 9345@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{12c} 9346@section Aspect Dimension 9347 9348 9349@geindex Dimension 9350 9351The @code{Dimension} aspect is used to specify the dimensions of a given 9352subtype of a dimensioned numeric type. The aspect also specifies a symbol 9353used when doing formatted output of dimensioned quantities. The syntax is: 9354 9355@example 9356with Dimension => 9357 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) 9358 9359SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL 9360 9361DIMENSION_VALUE ::= 9362 RATIONAL 9363| others => RATIONAL 9364| DISCRETE_CHOICE_LIST => RATIONAL 9365 9366RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] 9367@end example 9368 9369This aspect can only be applied to a subtype whose parent type has 9370a @code{Dimension_System} aspect. The aspect must specify values for 9371all dimensions of the system. The rational values are the powers of the 9372corresponding dimensions that are used by the compiler to verify that 9373physical (numeric) computations are dimensionally consistent. For example, 9374the computation of a force must result in dimensions (L => 1, M => 1, T => -2). 9375For further examples of the usage 9376of this aspect, see package @code{System.Dim.Mks}. 9377Note that when the dimensioned type is an integer type, then any 9378dimension value must be an integer literal. 9379 9380@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects 9381@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12d} 9382@section Aspect Dimension_System 9383 9384 9385@geindex Dimension_System 9386 9387The @code{Dimension_System} aspect is used to define a system of 9388dimensions that will be used in subsequent subtype declarations with 9389@code{Dimension} aspects that reference this system. The syntax is: 9390 9391@example 9392with Dimension_System => (DIMENSION @{, DIMENSION@}); 9393 9394DIMENSION ::= ([Unit_Name =>] IDENTIFIER, 9395 [Unit_Symbol =>] SYMBOL, 9396 [Dim_Symbol =>] SYMBOL) 9397 9398SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL 9399@end example 9400 9401This aspect is applied to a type, which must be a numeric derived type 9402(typically a floating-point type), that 9403will represent values within the dimension system. Each @code{DIMENSION} 9404corresponds to one particular dimension. A maximum of 7 dimensions may 9405be specified. @code{Unit_Name} is the name of the dimension (for example 9406@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities 9407of this dimension (for example @code{m} for @code{Meter}). 9408@code{Dim_Symbol} gives 9409the identification within the dimension system (typically this is a 9410single letter, e.g. @code{L} standing for length for unit name @code{Meter}). 9411The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. 9412The @code{Dim_Symbol} is used in error messages when numeric operations have 9413inconsistent dimensions. 9414 9415GNAT provides the standard definition of the International MKS system in 9416the run-time package @code{System.Dim.Mks}. You can easily define 9417similar packages for cgs units or British units, and define conversion factors 9418between values in different systems. The MKS system is characterized by the 9419following aspect: 9420 9421@example 9422type Mks_Type is new Long_Long_Float with 9423 Dimension_System => ( 9424 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 9425 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 9426 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 9427 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 9428 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), 9429 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 9430 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 9431@end example 9432 9433Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to 9434represent a theta character (avoiding the use of extended Latin-1 9435characters in this context). 9436 9437See section 'Performing Dimensionality Analysis in GNAT' in the GNAT Users 9438Guide for detailed examples of use of the dimension system. 9439 9440@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects 9441@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12e} 9442@section Aspect Disable_Controlled 9443 9444 9445@geindex Disable_Controlled 9446 9447The aspect @code{Disable_Controlled} is defined for controlled record types. If 9448active, this aspect causes suppression of all related calls to @code{Initialize}, 9449@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, 9450where for example you might want a record to be controlled or not depending on 9451whether some run-time check is enabled or suppressed. 9452 9453@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects 9454@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12f} 9455@section Aspect Effective_Reads 9456 9457 9458@geindex Effective_Reads 9459 9460This aspect is equivalent to @ref{59,,pragma Effective_Reads}. 9461 9462@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects 9463@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{130} 9464@section Aspect Effective_Writes 9465 9466 9467@geindex Effective_Writes 9468 9469This aspect is equivalent to @ref{5b,,pragma Effective_Writes}. 9470 9471@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects 9472@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{131} 9473@section Aspect Extensions_Visible 9474 9475 9476@geindex Extensions_Visible 9477 9478This aspect is equivalent to @ref{67,,pragma Extensions_Visible}. 9479 9480@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects 9481@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{132} 9482@section Aspect Favor_Top_Level 9483 9484 9485@geindex Favor_Top_Level 9486 9487This boolean aspect is equivalent to @ref{6c,,pragma Favor_Top_Level}. 9488 9489@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects 9490@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{133} 9491@section Aspect Ghost 9492 9493 9494@geindex Ghost 9495 9496This aspect is equivalent to @ref{6f,,pragma Ghost}. 9497 9498@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects 9499@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{134} 9500@section Aspect Global 9501 9502 9503@geindex Global 9504 9505This aspect is equivalent to @ref{71,,pragma Global}. 9506 9507@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects 9508@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{135} 9509@section Aspect Initial_Condition 9510 9511 9512@geindex Initial_Condition 9513 9514This aspect is equivalent to @ref{7f,,pragma Initial_Condition}. 9515 9516@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects 9517@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{136} 9518@section Aspect Initializes 9519 9520 9521@geindex Initializes 9522 9523This aspect is equivalent to @ref{81,,pragma Initializes}. 9524 9525@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects 9526@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{137} 9527@section Aspect Inline_Always 9528 9529 9530@geindex Inline_Always 9531 9532This boolean aspect is equivalent to @ref{84,,pragma Inline_Always}. 9533 9534@node Aspect Invariant,Aspect Invariant'Class,Aspect Inline_Always,Implementation Defined Aspects 9535@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{138} 9536@section Aspect Invariant 9537 9538 9539@geindex Invariant 9540 9541This aspect is equivalent to @ref{8b,,pragma Invariant}. It is a 9542synonym for the language defined aspect @code{Type_Invariant} except 9543that it is separately controllable using pragma @code{Assertion_Policy}. 9544 9545@node Aspect Invariant'Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects 9546@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{139} 9547@section Aspect Invariant'Class 9548 9549 9550@geindex Invariant'Class 9551 9552This aspect is equivalent to @ref{102,,pragma Type_Invariant_Class}. It is a 9553synonym for the language defined aspect @code{Type_Invariant'Class} except 9554that it is separately controllable using pragma @code{Assertion_Policy}. 9555 9556@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant'Class,Implementation Defined Aspects 9557@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{13a} 9558@section Aspect Iterable 9559 9560 9561@geindex Iterable 9562 9563This aspect provides a light-weight mechanism for loops and quantified 9564expressions over container types, without the overhead imposed by the tampering 9565checks of standard Ada 2012 iterators. The value of the aspect is an aggregate 9566with six named components, of which the last three are optional: @code{First}, 9567@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. 9568When only the first three components are specified, only the 9569@code{for .. in} form of iteration over cursors is available. When @code{Element} 9570is specified, both this form and the @code{for .. of} form of iteration over 9571elements are available. If the last two components are specified, reverse 9572iterations over the container can be specified (analogous to what can be done 9573over predefined containers that support the @code{Reverse_Iterator} interface). 9574The following is a typical example of use: 9575 9576@example 9577type List is private with 9578 Iterable => (First => First_Cursor, 9579 Next => Advance, 9580 Has_Element => Cursor_Has_Element, 9581 [Element => Get_Element]); 9582@end example 9583 9584 9585@itemize * 9586 9587@item 9588The value denoted by @code{First} must denote a primitive operation of the 9589container type that returns a @code{Cursor}, which must a be a type declared in 9590the container package or visible from it. For example: 9591@end itemize 9592 9593@example 9594function First_Cursor (Cont : Container) return Cursor; 9595@end example 9596 9597 9598@itemize * 9599 9600@item 9601The value of @code{Next} is a primitive operation of the container type that takes 9602both a container and a cursor and yields a cursor. For example: 9603@end itemize 9604 9605@example 9606function Advance (Cont : Container; Position : Cursor) return Cursor; 9607@end example 9608 9609 9610@itemize * 9611 9612@item 9613The value of @code{Has_Element} is a primitive operation of the container type 9614that takes both a container and a cursor and yields a boolean. For example: 9615@end itemize 9616 9617@example 9618function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; 9619@end example 9620 9621 9622@itemize * 9623 9624@item 9625The value of @code{Element} is a primitive operation of the container type that 9626takes both a container and a cursor and yields an @code{Element_Type}, which must 9627be a type declared in the container package or visible from it. For example: 9628@end itemize 9629 9630@example 9631function Get_Element (Cont : Container; Position : Cursor) return Element_Type; 9632@end example 9633 9634This aspect is used in the GNAT-defined formal container packages. 9635 9636@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects 9637@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{13b} 9638@section Aspect Linker_Section 9639 9640 9641@geindex Linker_Section 9642 9643This aspect is equivalent to @ref{93,,pragma Linker_Section}. 9644 9645@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects 9646@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{13c} 9647@section Aspect Lock_Free 9648 9649 9650@geindex Lock_Free 9651 9652This boolean aspect is equivalent to @ref{95,,pragma Lock_Free}. 9653 9654@node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects 9655@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13d} 9656@section Aspect Max_Queue_Length 9657 9658 9659@geindex Max_Queue_Length 9660 9661This aspect is equivalent to @ref{9d,,pragma Max_Queue_Length}. 9662 9663@node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects 9664@anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13e} 9665@section Aspect No_Caching 9666 9667 9668@geindex No_Caching 9669 9670This boolean aspect is equivalent to @ref{9f,,pragma No_Caching}. 9671 9672@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects 9673@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13f} 9674@section Aspect No_Elaboration_Code_All 9675 9676 9677@geindex No_Elaboration_Code_All 9678 9679This aspect is equivalent to @ref{a3,,pragma No_Elaboration_Code_All} 9680for a program unit. 9681 9682@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects 9683@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{140} 9684@section Aspect No_Inline 9685 9686 9687@geindex No_Inline 9688 9689This boolean aspect is equivalent to @ref{a6,,pragma No_Inline}. 9690 9691@node Aspect No_Tagged_Streams,Aspect Object_Size,Aspect No_Inline,Implementation Defined Aspects 9692@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{141} 9693@section Aspect No_Tagged_Streams 9694 9695 9696@geindex No_Tagged_Streams 9697 9698This aspect is equivalent to @ref{a9,,pragma No_Tagged_Streams} with an 9699argument specifying a root tagged type (thus this aspect can only be 9700applied to such a type). 9701 9702@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Tagged_Streams,Implementation Defined Aspects 9703@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{142} 9704@section Aspect Object_Size 9705 9706 9707@geindex Object_Size 9708 9709This aspect is equivalent to @ref{143,,attribute Object_Size}. 9710 9711@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects 9712@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{144} 9713@section Aspect Obsolescent 9714 9715 9716@geindex Obsolsecent 9717 9718This aspect is equivalent to @ref{ac,,pragma Obsolescent}. Note that the 9719evaluation of this aspect happens at the point of occurrence, it is not 9720delayed until the freeze point. 9721 9722@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects 9723@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{145} 9724@section Aspect Part_Of 9725 9726 9727@geindex Part_Of 9728 9729This aspect is equivalent to @ref{b4,,pragma Part_Of}. 9730 9731@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects 9732@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{146} 9733@section Aspect Persistent_BSS 9734 9735 9736@geindex Persistent_BSS 9737 9738This boolean aspect is equivalent to @ref{b7,,pragma Persistent_BSS}. 9739 9740@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects 9741@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{147} 9742@section Aspect Predicate 9743 9744 9745@geindex Predicate 9746 9747This aspect is equivalent to @ref{be,,pragma Predicate}. It is thus 9748similar to the language defined aspects @code{Dynamic_Predicate} 9749and @code{Static_Predicate} except that whether the resulting 9750predicate is static or dynamic is controlled by the form of the 9751expression. It is also separately controllable using pragma 9752@code{Assertion_Policy}. 9753 9754@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects 9755@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{148} 9756@section Aspect Pure_Function 9757 9758 9759@geindex Pure_Function 9760 9761This boolean aspect is equivalent to @ref{ca,,pragma Pure_Function}. 9762 9763@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects 9764@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{149} 9765@section Aspect Refined_Depends 9766 9767 9768@geindex Refined_Depends 9769 9770This aspect is equivalent to @ref{ce,,pragma Refined_Depends}. 9771 9772@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects 9773@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{14a} 9774@section Aspect Refined_Global 9775 9776 9777@geindex Refined_Global 9778 9779This aspect is equivalent to @ref{d0,,pragma Refined_Global}. 9780 9781@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects 9782@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{14b} 9783@section Aspect Refined_Post 9784 9785 9786@geindex Refined_Post 9787 9788This aspect is equivalent to @ref{d2,,pragma Refined_Post}. 9789 9790@node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects 9791@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14c} 9792@section Aspect Refined_State 9793 9794 9795@geindex Refined_State 9796 9797This aspect is equivalent to @ref{d4,,pragma Refined_State}. 9798 9799@node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects 9800@anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14d} 9801@section Aspect Relaxed_Initialization 9802 9803 9804@geindex Refined_Initialization 9805 9806For the syntax and semantics of this aspect, see the SPARK 2014 Reference 9807Manual, section 6.10. 9808 9809@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects 9810@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14e} 9811@section Aspect Remote_Access_Type 9812 9813 9814@geindex Remote_Access_Type 9815 9816This aspect is equivalent to @ref{d8,,pragma Remote_Access_Type}. 9817 9818@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects 9819@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14f} 9820@section Aspect Secondary_Stack_Size 9821 9822 9823@geindex Secondary_Stack_Size 9824 9825This aspect is equivalent to @ref{dd,,pragma Secondary_Stack_Size}. 9826 9827@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects 9828@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{150} 9829@section Aspect Scalar_Storage_Order 9830 9831 9832@geindex Scalar_Storage_Order 9833 9834This aspect is equivalent to a @ref{151,,attribute Scalar_Storage_Order}. 9835 9836@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects 9837@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{152} 9838@section Aspect Shared 9839 9840 9841@geindex Shared 9842 9843This boolean aspect is equivalent to @ref{e0,,pragma Shared} 9844and is thus a synonym for aspect @code{Atomic}. 9845 9846@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects 9847@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{153} 9848@section Aspect Simple_Storage_Pool 9849 9850 9851@geindex Simple_Storage_Pool 9852 9853This aspect is equivalent to @ref{e5,,attribute Simple_Storage_Pool}. 9854 9855@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects 9856@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{154} 9857@section Aspect Simple_Storage_Pool_Type 9858 9859 9860@geindex Simple_Storage_Pool_Type 9861 9862This boolean aspect is equivalent to @ref{e3,,pragma Simple_Storage_Pool_Type}. 9863 9864@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects 9865@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{155} 9866@section Aspect SPARK_Mode 9867 9868 9869@geindex SPARK_Mode 9870 9871This aspect is equivalent to @ref{eb,,pragma SPARK_Mode} and 9872may be specified for either or both of the specification and body 9873of a subprogram or package. 9874 9875@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects 9876@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{156} 9877@section Aspect Suppress_Debug_Info 9878 9879 9880@geindex Suppress_Debug_Info 9881 9882This boolean aspect is equivalent to @ref{f3,,pragma Suppress_Debug_Info}. 9883 9884@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects 9885@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{157} 9886@section Aspect Suppress_Initialization 9887 9888 9889@geindex Suppress_Initialization 9890 9891This boolean aspect is equivalent to @ref{f7,,pragma Suppress_Initialization}. 9892 9893@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects 9894@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{158} 9895@section Aspect Test_Case 9896 9897 9898@geindex Test_Case 9899 9900This aspect is equivalent to @ref{fa,,pragma Test_Case}. 9901 9902@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects 9903@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{159} 9904@section Aspect Thread_Local_Storage 9905 9906 9907@geindex Thread_Local_Storage 9908 9909This boolean aspect is equivalent to @ref{fc,,pragma Thread_Local_Storage}. 9910 9911@node Aspect Universal_Aliasing,Aspect Universal_Data,Aspect Thread_Local_Storage,Implementation Defined Aspects 9912@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{15a} 9913@section Aspect Universal_Aliasing 9914 9915 9916@geindex Universal_Aliasing 9917 9918This boolean aspect is equivalent to @ref{106,,pragma Universal_Aliasing}. 9919 9920@node Aspect Universal_Data,Aspect Unmodified,Aspect Universal_Aliasing,Implementation Defined Aspects 9921@anchor{gnat_rm/implementation_defined_aspects aspect-universal-data}@anchor{15b} 9922@section Aspect Universal_Data 9923 9924 9925@geindex Universal_Data 9926 9927This aspect is equivalent to @ref{108,,pragma Universal_Data}. 9928 9929@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Data,Implementation Defined Aspects 9930@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{15c} 9931@section Aspect Unmodified 9932 9933 9934@geindex Unmodified 9935 9936This boolean aspect is equivalent to @ref{10b,,pragma Unmodified}. 9937 9938@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects 9939@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15d} 9940@section Aspect Unreferenced 9941 9942 9943@geindex Unreferenced 9944 9945This boolean aspect is equivalent to @ref{10c,,pragma Unreferenced}. 9946 9947When using the @code{-gnat2020} switch, this aspect is also supported on formal 9948parameters, which is in particular the only form possible for expression 9949functions. 9950 9951@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects 9952@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15e} 9953@section Aspect Unreferenced_Objects 9954 9955 9956@geindex Unreferenced_Objects 9957 9958This boolean aspect is equivalent to @ref{10e,,pragma Unreferenced_Objects}. 9959 9960@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects 9961@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15f} 9962@section Aspect Value_Size 9963 9964 9965@geindex Value_Size 9966 9967This aspect is equivalent to @ref{160,,attribute Value_Size}. 9968 9969@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects 9970@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{161} 9971@section Aspect Volatile_Full_Access 9972 9973 9974@geindex Volatile_Full_Access 9975 9976This boolean aspect is equivalent to @ref{119,,pragma Volatile_Full_Access}. 9977 9978@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects 9979@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{162} 9980@section Aspect Volatile_Function 9981 9982 9983@geindex Volatile_Function 9984 9985This boolean aspect is equivalent to @ref{11b,,pragma Volatile_Function}. 9986 9987@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects 9988@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{163} 9989@section Aspect Warnings 9990 9991 9992@geindex Warnings 9993 9994This aspect is equivalent to the two argument form of @ref{11d,,pragma Warnings}, 9995where the first argument is @code{ON} or @code{OFF} and the second argument 9996is the entity. 9997 9998@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top 9999@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{164}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{165} 10000@chapter Implementation Defined Attributes 10001 10002 10003Ada defines (throughout the Ada reference manual, 10004summarized in Annex K), 10005a set of attributes that provide useful additional functionality in all 10006areas of the language. These language defined attributes are implemented 10007in GNAT and work as described in the Ada Reference Manual. 10008 10009In addition, Ada allows implementations to define additional 10010attributes whose meaning is defined by the implementation. GNAT provides 10011a number of these implementation-dependent attributes which can be used 10012to extend and enhance the functionality of the compiler. This section of 10013the GNAT reference manual describes these additional attributes. It also 10014describes additional implementation-dependent features of standard 10015language-defined attributes. 10016 10017Note that any program using these attributes may not be portable to 10018other compilers (although GNAT implements this set of attributes on all 10019platforms). Therefore if portability to other compilers is an important 10020consideration, you should minimize the use of these attributes. 10021 10022@menu 10023* Attribute Abort_Signal:: 10024* Attribute Address_Size:: 10025* Attribute Asm_Input:: 10026* Attribute Asm_Output:: 10027* Attribute Atomic_Always_Lock_Free:: 10028* Attribute Bit:: 10029* Attribute Bit_Position:: 10030* Attribute Code_Address:: 10031* Attribute Compiler_Version:: 10032* Attribute Constrained:: 10033* Attribute Default_Bit_Order:: 10034* Attribute Default_Scalar_Storage_Order:: 10035* Attribute Deref:: 10036* Attribute Descriptor_Size:: 10037* Attribute Elaborated:: 10038* Attribute Elab_Body:: 10039* Attribute Elab_Spec:: 10040* Attribute Elab_Subp_Body:: 10041* Attribute Emax:: 10042* Attribute Enabled:: 10043* Attribute Enum_Rep:: 10044* Attribute Enum_Val:: 10045* Attribute Epsilon:: 10046* Attribute Fast_Math:: 10047* Attribute Finalization_Size:: 10048* Attribute Fixed_Value:: 10049* Attribute From_Any:: 10050* Attribute Has_Access_Values:: 10051* Attribute Has_Discriminants:: 10052* Attribute Has_Tagged_Values:: 10053* Attribute Img:: 10054* Attribute Initialized:: 10055* Attribute Integer_Value:: 10056* Attribute Invalid_Value:: 10057* Attribute Iterable:: 10058* Attribute Large:: 10059* Attribute Library_Level:: 10060* Attribute Lock_Free:: 10061* Attribute Loop_Entry:: 10062* Attribute Machine_Size:: 10063* Attribute Mantissa:: 10064* Attribute Maximum_Alignment:: 10065* Attribute Max_Integer_Size:: 10066* Attribute Mechanism_Code:: 10067* Attribute Null_Parameter:: 10068* Attribute Object_Size:: 10069* Attribute Old:: 10070* Attribute Passed_By_Reference:: 10071* Attribute Pool_Address:: 10072* Attribute Range_Length:: 10073* Attribute Restriction_Set:: 10074* Attribute Result:: 10075* Attribute Safe_Emax:: 10076* Attribute Safe_Large:: 10077* Attribute Safe_Small:: 10078* Attribute Scalar_Storage_Order:: 10079* Attribute Simple_Storage_Pool:: 10080* Attribute Small:: 10081* Attribute Small_Denominator:: 10082* Attribute Small_Numerator:: 10083* Attribute Storage_Unit:: 10084* Attribute Stub_Type:: 10085* Attribute System_Allocator_Alignment:: 10086* Attribute Target_Name:: 10087* Attribute To_Address:: 10088* Attribute To_Any:: 10089* Attribute Type_Class:: 10090* Attribute Type_Key:: 10091* Attribute TypeCode:: 10092* Attribute Unconstrained_Array:: 10093* Attribute Universal_Literal_String:: 10094* Attribute Unrestricted_Access:: 10095* Attribute Update:: 10096* Attribute Valid_Scalars:: 10097* Attribute VADS_Size:: 10098* Attribute Value_Size:: 10099* Attribute Wchar_T_Size:: 10100* Attribute Word_Size:: 10101 10102@end menu 10103 10104@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes 10105@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{166} 10106@section Attribute Abort_Signal 10107 10108 10109@geindex Abort_Signal 10110 10111@code{Standard'Abort_Signal} (@code{Standard} is the only allowed 10112prefix) provides the entity for the special exception used to signal 10113task abort or asynchronous transfer of control. Normally this attribute 10114should only be used in the tasking runtime (it is highly peculiar, and 10115completely outside the normal semantics of Ada, for a user program to 10116intercept the abort exception). 10117 10118@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes 10119@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{167} 10120@section Attribute Address_Size 10121 10122 10123@geindex Size of `@w{`}Address`@w{`} 10124 10125@geindex Address_Size 10126 10127@code{Standard'Address_Size} (@code{Standard} is the only allowed 10128prefix) is a static constant giving the number of bits in an 10129@code{Address}. It is the same value as System.Address'Size, 10130but has the advantage of being static, while a direct 10131reference to System.Address'Size is nonstatic because Address 10132is a private type. 10133 10134@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes 10135@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{168} 10136@section Attribute Asm_Input 10137 10138 10139@geindex Asm_Input 10140 10141The @code{Asm_Input} attribute denotes a function that takes two 10142parameters. The first is a string, the second is an expression of the 10143type designated by the prefix. The first (string) argument is required 10144to be a static expression, and is the constraint for the parameter, 10145(e.g., what kind of register is required). The second argument is the 10146value to be used as the input argument. The possible values for the 10147constant are the same as those used in the RTL, and are dependent on 10148the configuration file used to built the GCC back end. 10149@ref{169,,Machine Code Insertions} 10150 10151@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes 10152@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{16a} 10153@section Attribute Asm_Output 10154 10155 10156@geindex Asm_Output 10157 10158The @code{Asm_Output} attribute denotes a function that takes two 10159parameters. The first is a string, the second is the name of a variable 10160of the type designated by the attribute prefix. The first (string) 10161argument is required to be a static expression and designates the 10162constraint for the parameter (e.g., what kind of register is 10163required). The second argument is the variable to be updated with the 10164result. The possible values for constraint are the same as those used in 10165the RTL, and are dependent on the configuration file used to build the 10166GCC back end. If there are no output operands, then this argument may 10167either be omitted, or explicitly given as @code{No_Output_Operands}. 10168@ref{169,,Machine Code Insertions} 10169 10170@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes 10171@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{16b} 10172@section Attribute Atomic_Always_Lock_Free 10173 10174 10175@geindex Atomic_Always_Lock_Free 10176 10177The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. 10178The result is a Boolean value which is True if the type has discriminants, 10179and False otherwise. The result indicate whether atomic operations are 10180supported by the target for the given type. 10181 10182@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes 10183@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{16c} 10184@section Attribute Bit 10185 10186 10187@geindex Bit 10188 10189@code{obj'Bit}, where @code{obj} is any object, yields the bit 10190offset within the storage unit (byte) that contains the first bit of 10191storage allocated for the object. The value of this attribute is of the 10192type @emph{universal_integer} and is always a nonnegative number smaller 10193than @code{System.Storage_Unit}. 10194 10195For an object that is a variable or a constant allocated in a register, 10196the value is zero. (The use of this attribute does not force the 10197allocation of a variable to memory). 10198 10199For an object that is a formal parameter, this attribute applies 10200to either the matching actual parameter or to a copy of the 10201matching actual parameter. 10202 10203For an access object the value is zero. Note that 10204@code{obj.all'Bit} is subject to an @code{Access_Check} for the 10205designated object. Similarly for a record component 10206@code{X.C'Bit} is subject to a discriminant check and 10207@code{X(I).Bit} and @code{X(I1..I2)'Bit} 10208are subject to index checks. 10209 10210This attribute is designed to be compatible with the DEC Ada 83 definition 10211and implementation of the @code{Bit} attribute. 10212 10213@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes 10214@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16d} 10215@section Attribute Bit_Position 10216 10217 10218@geindex Bit_Position 10219 10220@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one 10221of the fields of the record type, yields the bit 10222offset within the record contains the first bit of 10223storage allocated for the object. The value of this attribute is of the 10224type @emph{universal_integer}. The value depends only on the field 10225@code{C} and is independent of the alignment of 10226the containing record @code{R}. 10227 10228@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes 10229@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16e} 10230@section Attribute Code_Address 10231 10232 10233@geindex Code_Address 10234 10235@geindex Subprogram address 10236 10237@geindex Address of subprogram code 10238 10239The @code{'Address} 10240attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 10241intended effect seems to be to provide 10242an address value which can be used to call the subprogram by means of 10243an address clause as in the following example: 10244 10245@example 10246procedure K is ... 10247 10248procedure L; 10249for L'Address use K'Address; 10250pragma Import (Ada, L); 10251@end example 10252 10253A call to @code{L} is then expected to result in a call to @code{K}. 10254In Ada 83, where there were no access-to-subprogram values, this was 10255a common work-around for getting the effect of an indirect call. 10256GNAT implements the above use of @code{Address} and the technique 10257illustrated by the example code works correctly. 10258 10259However, for some purposes, it is useful to have the address of the start 10260of the generated code for the subprogram. On some architectures, this is 10261not necessarily the same as the @code{Address} value described above. 10262For example, the @code{Address} value may reference a subprogram 10263descriptor rather than the subprogram itself. 10264 10265The @code{'Code_Address} attribute, which can only be applied to 10266subprogram entities, always returns the address of the start of the 10267generated code of the specified subprogram, which may or may not be 10268the same value as is returned by the corresponding @code{'Address} 10269attribute. 10270 10271@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes 10272@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16f} 10273@section Attribute Compiler_Version 10274 10275 10276@geindex Compiler_Version 10277 10278@code{Standard'Compiler_Version} (@code{Standard} is the only allowed 10279prefix) yields a static string identifying the version of the compiler 10280being used to compile the unit containing the attribute reference. 10281 10282@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes 10283@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{170} 10284@section Attribute Constrained 10285 10286 10287@geindex Constrained 10288 10289In addition to the usage of this attribute in the Ada RM, GNAT 10290also permits the use of the @code{'Constrained} attribute 10291in a generic template 10292for any type, including types without discriminants. The value of this 10293attribute in the generic instance when applied to a scalar type or a 10294record type without discriminants is always @code{True}. This usage is 10295compatible with older Ada compilers, including notably DEC Ada. 10296 10297@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes 10298@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{171} 10299@section Attribute Default_Bit_Order 10300 10301 10302@geindex Big endian 10303 10304@geindex Little endian 10305 10306@geindex Default_Bit_Order 10307 10308@code{Standard'Default_Bit_Order} (@code{Standard} is the only 10309permissible prefix), provides the value @code{System.Default_Bit_Order} 10310as a @code{Pos} value (0 for @code{High_Order_First}, 1 for 10311@code{Low_Order_First}). This is used to construct the definition of 10312@code{Default_Bit_Order} in package @code{System}. 10313 10314@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes 10315@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{172} 10316@section Attribute Default_Scalar_Storage_Order 10317 10318 10319@geindex Big endian 10320 10321@geindex Little endian 10322 10323@geindex Default_Scalar_Storage_Order 10324 10325@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only 10326permissible prefix), provides the current value of the default scalar storage 10327order (as specified using pragma @code{Default_Scalar_Storage_Order}, or 10328equal to @code{Default_Bit_Order} if unspecified) as a 10329@code{System.Bit_Order} value. This is a static attribute. 10330 10331@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes 10332@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{173} 10333@section Attribute Deref 10334 10335 10336@geindex Deref 10337 10338The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields 10339the variable of type @code{typ} that is located at the given address. It is similar 10340to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to 10341a named access-to-@cite{typ} type, except that it yields a variable, so it can be 10342used on the left side of an assignment. 10343 10344@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes 10345@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{174} 10346@section Attribute Descriptor_Size 10347 10348 10349@geindex Descriptor 10350 10351@geindex Dope vector 10352 10353@geindex Descriptor_Size 10354 10355Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the 10356descriptor allocated for a type. The result is non-zero only for unconstrained 10357array types and the returned value is of type universal integer. In GNAT, an 10358array descriptor contains bounds information and is located immediately before 10359the first element of the array. 10360 10361@example 10362type Unconstr_Array is array (Short_Short_Integer range <>) of Positive; 10363Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 10364@end example 10365 10366The attribute takes into account any padding due to the alignment of the 10367component type. In the example above, the descriptor contains two values 10368of type @code{Short_Short_Integer} representing the low and high bound. But, 10369since @code{Positive} has an alignment of 4, the size of the descriptor is 10370@code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32, 10371which yields a size of 32 bits, i.e. including 16 bits of padding. 10372 10373@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes 10374@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{175} 10375@section Attribute Elaborated 10376 10377 10378@geindex Elaborated 10379 10380The prefix of the @code{'Elaborated} attribute must be a unit name. The 10381value is a Boolean which indicates whether or not the given unit has been 10382elaborated. This attribute is primarily intended for internal use by the 10383generated code for dynamic elaboration checking, but it can also be used 10384in user programs. The value will always be True once elaboration of all 10385units has been completed. An exception is for units which need no 10386elaboration, the value is always False for such units. 10387 10388@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes 10389@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{176} 10390@section Attribute Elab_Body 10391 10392 10393@geindex Elab_Body 10394 10395This attribute can only be applied to a program unit name. It returns 10396the entity for the corresponding elaboration procedure for elaborating 10397the body of the referenced unit. This is used in the main generated 10398elaboration procedure by the binder and is not normally used in any 10399other context. However, there may be specialized situations in which it 10400is useful to be able to call this elaboration procedure from Ada code, 10401e.g., if it is necessary to do selective re-elaboration to fix some 10402error. 10403 10404@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes 10405@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{177} 10406@section Attribute Elab_Spec 10407 10408 10409@geindex Elab_Spec 10410 10411This attribute can only be applied to a program unit name. It returns 10412the entity for the corresponding elaboration procedure for elaborating 10413the spec of the referenced unit. This is used in the main 10414generated elaboration procedure by the binder and is not normally used 10415in any other context. However, there may be specialized situations in 10416which it is useful to be able to call this elaboration procedure from 10417Ada code, e.g., if it is necessary to do selective re-elaboration to fix 10418some error. 10419 10420@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes 10421@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{178} 10422@section Attribute Elab_Subp_Body 10423 10424 10425@geindex Elab_Subp_Body 10426 10427This attribute can only be applied to a library level subprogram 10428name and is only allowed in CodePeer mode. It returns the entity 10429for the corresponding elaboration procedure for elaborating the body 10430of the referenced subprogram unit. This is used in the main generated 10431elaboration procedure by the binder in CodePeer mode only and is unrecognized 10432otherwise. 10433 10434@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes 10435@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{179} 10436@section Attribute Emax 10437 10438 10439@geindex Ada 83 attributes 10440 10441@geindex Emax 10442 10443The @code{Emax} attribute is provided for compatibility with Ada 83. See 10444the Ada 83 reference manual for an exact description of the semantics of 10445this attribute. 10446 10447@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes 10448@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{17a} 10449@section Attribute Enabled 10450 10451 10452@geindex Enabled 10453 10454The @code{Enabled} attribute allows an application program to check at compile 10455time to see if the designated check is currently enabled. The prefix is a 10456simple identifier, referencing any predefined check name (other than 10457@code{All_Checks}) or a check name introduced by pragma Check_Name. If 10458no argument is given for the attribute, the check is for the general state 10459of the check, if an argument is given, then it is an entity name, and the 10460check indicates whether an @code{Suppress} or @code{Unsuppress} has been 10461given naming the entity (if not, then the argument is ignored). 10462 10463Note that instantiations inherit the check status at the point of the 10464instantiation, so a useful idiom is to have a library package that 10465introduces a check name with @code{pragma Check_Name}, and then contains 10466generic packages or subprograms which use the @code{Enabled} attribute 10467to see if the check is enabled. A user of this package can then issue 10468a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating 10469the package or subprogram, controlling whether the check will be present. 10470 10471@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes 10472@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{17b} 10473@section Attribute Enum_Rep 10474 10475 10476@geindex Representation of enums 10477 10478@geindex Enum_Rep 10479 10480Note that this attribute is now standard in Ada 202x and is available 10481as an implementation defined attribute for earlier Ada versions. 10482 10483For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a 10484function with the following spec: 10485 10486@example 10487function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; 10488@end example 10489 10490It is also allowable to apply @code{Enum_Rep} directly to an object of an 10491enumeration type or to a non-overloaded enumeration 10492literal. In this case @code{S'Enum_Rep} is equivalent to 10493@code{typ'Enum_Rep(S)} where @code{typ} is the type of the 10494enumeration literal or object. 10495 10496The function returns the representation value for the given enumeration 10497value. This will be equal to value of the @code{Pos} attribute in the 10498absence of an enumeration representation clause. This is a static 10499attribute (i.e., the result is static if the argument is static). 10500 10501@code{S'Enum_Rep} can also be used with integer types and objects, 10502in which case it simply returns the integer value. The reason for this 10503is to allow it to be used for @code{(<>)} discrete formal arguments in 10504a generic unit that can be instantiated with either enumeration types 10505or integer types. Note that if @code{Enum_Rep} is used on a modular 10506type whose upper bound exceeds the upper bound of the largest signed 10507integer type, and the argument is a variable, so that the universal 10508integer calculation is done at run time, then the call to @code{Enum_Rep} 10509may raise @code{Constraint_Error}. 10510 10511@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes 10512@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{17c} 10513@section Attribute Enum_Val 10514 10515 10516@geindex Representation of enums 10517 10518@geindex Enum_Val 10519 10520Note that this attribute is now standard in Ada 202x and is available 10521as an implementation defined attribute for earlier Ada versions. 10522 10523For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a 10524function with the following spec: 10525 10526@example 10527function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; 10528@end example 10529 10530The function returns the enumeration value whose representation matches the 10531argument, or raises Constraint_Error if no enumeration literal of the type 10532has the matching value. 10533This will be equal to value of the @code{Val} attribute in the 10534absence of an enumeration representation clause. This is a static 10535attribute (i.e., the result is static if the argument is static). 10536 10537@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes 10538@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17d} 10539@section Attribute Epsilon 10540 10541 10542@geindex Ada 83 attributes 10543 10544@geindex Epsilon 10545 10546The @code{Epsilon} attribute is provided for compatibility with Ada 83. See 10547the Ada 83 reference manual for an exact description of the semantics of 10548this attribute. 10549 10550@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes 10551@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17e} 10552@section Attribute Fast_Math 10553 10554 10555@geindex Fast_Math 10556 10557@code{Standard'Fast_Math} (@code{Standard} is the only allowed 10558prefix) yields a static Boolean value that is True if pragma 10559@code{Fast_Math} is active, and False otherwise. 10560 10561@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes 10562@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17f} 10563@section Attribute Finalization_Size 10564 10565 10566@geindex Finalization_Size 10567 10568The prefix of attribute @code{Finalization_Size} must be an object or 10569a non-class-wide type. This attribute returns the size of any hidden data 10570reserved by the compiler to handle finalization-related actions. The type of 10571the attribute is @emph{universal_integer}. 10572 10573@code{Finalization_Size} yields a value of zero for a type with no controlled 10574parts, an object whose type has no controlled parts, or an object of a 10575class-wide type whose tag denotes a type with no controlled parts. 10576 10577Note that only heap-allocated objects contain finalization data. 10578 10579@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes 10580@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{180} 10581@section Attribute Fixed_Value 10582 10583 10584@geindex Fixed_Value 10585 10586For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a 10587function with the following specification: 10588 10589@example 10590function S'Fixed_Value (Arg : <Universal_Integer>) return S; 10591@end example 10592 10593The value returned is the fixed-point value @code{V} such that: 10594 10595@example 10596V = Arg * S'Small 10597@end example 10598 10599The effect is thus similar to first converting the argument to the 10600integer type used to represent @code{S}, and then doing an unchecked 10601conversion to the fixed-point type. The difference is 10602that there are full range checks, to ensure that the result is in range. 10603This attribute is primarily intended for use in implementation of the 10604input-output functions for fixed-point values. 10605 10606@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes 10607@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{181} 10608@section Attribute From_Any 10609 10610 10611@geindex From_Any 10612 10613This internal attribute is used for the generation of remote subprogram 10614stubs in the context of the Distributed Systems Annex. 10615 10616@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes 10617@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{182} 10618@section Attribute Has_Access_Values 10619 10620 10621@geindex Access values 10622@geindex testing for 10623 10624@geindex Has_Access_Values 10625 10626The prefix of the @code{Has_Access_Values} attribute is a type. The result 10627is a Boolean value which is True if the is an access type, or is a composite 10628type with a component (at any nesting depth) that is an access type, and is 10629False otherwise. 10630The intended use of this attribute is in conjunction with generic 10631definitions. If the attribute is applied to a generic private type, it 10632indicates whether or not the corresponding actual type has access values. 10633 10634@node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes 10635@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{183} 10636@section Attribute Has_Discriminants 10637 10638 10639@geindex Discriminants 10640@geindex testing for 10641 10642@geindex Has_Discriminants 10643 10644The prefix of the @code{Has_Discriminants} attribute is a type. The result 10645is a Boolean value which is True if the type has discriminants, and False 10646otherwise. The intended use of this attribute is in conjunction with generic 10647definitions. If the attribute is applied to a generic private type, it 10648indicates whether or not the corresponding actual type has discriminants. 10649 10650@node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes 10651@anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{184} 10652@section Attribute Has_Tagged_Values 10653 10654 10655@geindex Tagged values 10656@geindex testing for 10657 10658@geindex Has_Tagged_Values 10659 10660The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a 10661Boolean value which is True if the type is a composite type (array or record) 10662that is either a tagged type or has a subcomponent that is tagged, and is False 10663otherwise. The intended use of this attribute is in conjunction with generic 10664definitions. If the attribute is applied to a generic private type, it 10665indicates whether or not the corresponding actual type has access values. 10666 10667@node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes 10668@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{185} 10669@section Attribute Img 10670 10671 10672@geindex Img 10673 10674The @code{Img} attribute differs from @code{Image} in that, while both can be 10675applied directly to an object, @code{Img} cannot be applied to types. 10676 10677Example usage of the attribute: 10678 10679@example 10680Put_Line ("X = " & X'Img); 10681@end example 10682 10683which has the same meaning as the more verbose: 10684 10685@example 10686Put_Line ("X = " & T'Image (X)); 10687@end example 10688 10689where @code{T} is the (sub)type of the object @code{X}. 10690 10691Note that technically, in analogy to @code{Image}, 10692@code{X'Img} returns a parameterless function 10693that returns the appropriate string when called. This means that 10694@code{X'Img} can be renamed as a function-returning-string, or used 10695in an instantiation as a function parameter. 10696 10697@node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes 10698@anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{186} 10699@section Attribute Initialized 10700 10701 10702@geindex Initialized 10703 10704For the syntax and semantics of this attribute, see the SPARK 2014 Reference 10705Manual, section 6.10. 10706 10707@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes 10708@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{187} 10709@section Attribute Integer_Value 10710 10711 10712@geindex Integer_Value 10713 10714For every integer type @code{S}, @code{S'Integer_Value} denotes a 10715function with the following spec: 10716 10717@example 10718function S'Integer_Value (Arg : <Universal_Fixed>) return S; 10719@end example 10720 10721The value returned is the integer value @code{V}, such that: 10722 10723@example 10724Arg = V * T'Small 10725@end example 10726 10727where @code{T} is the type of @code{Arg}. 10728The effect is thus similar to first doing an unchecked conversion from 10729the fixed-point type to its corresponding implementation type, and then 10730converting the result to the target integer type. The difference is 10731that there are full range checks, to ensure that the result is in range. 10732This attribute is primarily intended for use in implementation of the 10733standard input-output functions for fixed-point values. 10734 10735@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes 10736@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{188} 10737@section Attribute Invalid_Value 10738 10739 10740@geindex Invalid_Value 10741 10742For every scalar type S, S'Invalid_Value returns an undefined value of the 10743type. If possible this value is an invalid representation for the type. The 10744value returned is identical to the value used to initialize an otherwise 10745uninitialized value of the type if pragma Initialize_Scalars is used, 10746including the ability to modify the value with the binder -Sxx flag and 10747relevant environment variables at run time. 10748 10749@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes 10750@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{189} 10751@section Attribute Iterable 10752 10753 10754@geindex Iterable 10755 10756Equivalent to Aspect Iterable. 10757 10758@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes 10759@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{18a} 10760@section Attribute Large 10761 10762 10763@geindex Ada 83 attributes 10764 10765@geindex Large 10766 10767The @code{Large} attribute is provided for compatibility with Ada 83. See 10768the Ada 83 reference manual for an exact description of the semantics of 10769this attribute. 10770 10771@node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes 10772@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{18b} 10773@section Attribute Library_Level 10774 10775 10776@geindex Library_Level 10777 10778@code{P'Library_Level}, where P is an entity name, 10779returns a Boolean value which is True if the entity is declared 10780at the library level, and False otherwise. Note that within a 10781generic instantition, the name of the generic unit denotes the 10782instance, which means that this attribute can be used to test 10783if a generic is instantiated at the library level, as shown 10784in this example: 10785 10786@example 10787generic 10788 ... 10789package Gen is 10790 pragma Compile_Time_Error 10791 (not Gen'Library_Level, 10792 "Gen can only be instantiated at library level"); 10793 ... 10794end Gen; 10795@end example 10796 10797@node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes 10798@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{18c} 10799@section Attribute Lock_Free 10800 10801 10802@geindex Lock_Free 10803 10804@code{P'Lock_Free}, where P is a protected object, returns True if a 10805pragma @code{Lock_Free} applies to P. 10806 10807@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes 10808@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{18d} 10809@section Attribute Loop_Entry 10810 10811 10812@geindex Loop_Entry 10813 10814Syntax: 10815 10816@example 10817X'Loop_Entry [(loop_name)] 10818@end example 10819 10820The @code{Loop_Entry} attribute is used to refer to the value that an 10821expression had upon entry to a given loop in much the same way that the 10822@code{Old} attribute in a subprogram postcondition can be used to refer 10823to the value an expression had upon entry to the subprogram. The 10824relevant loop is either identified by the given loop name, or it is the 10825innermost enclosing loop when no loop name is given. 10826 10827A @code{Loop_Entry} attribute can only occur within a 10828@code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of 10829@code{Loop_Entry} is to compare the current value of objects with their 10830initial value at loop entry, in a @code{Loop_Invariant} pragma. 10831 10832The effect of using @code{X'Loop_Entry} is the same as declaring 10833a constant initialized with the initial value of @code{X} at loop 10834entry. This copy is not performed if the loop is not entered, or if the 10835corresponding pragmas are ignored or disabled. 10836 10837@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes 10838@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18e} 10839@section Attribute Machine_Size 10840 10841 10842@geindex Machine_Size 10843 10844This attribute is identical to the @code{Object_Size} attribute. It is 10845provided for compatibility with the DEC Ada 83 attribute of this name. 10846 10847@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes 10848@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18f} 10849@section Attribute Mantissa 10850 10851 10852@geindex Ada 83 attributes 10853 10854@geindex Mantissa 10855 10856The @code{Mantissa} attribute is provided for compatibility with Ada 83. See 10857the Ada 83 reference manual for an exact description of the semantics of 10858this attribute. 10859 10860@node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes 10861@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{190}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{191} 10862@section Attribute Maximum_Alignment 10863 10864 10865@geindex Alignment 10866@geindex maximum 10867 10868@geindex Maximum_Alignment 10869 10870@code{Standard'Maximum_Alignment} (@code{Standard} is the only 10871permissible prefix) provides the maximum useful alignment value for the 10872target. This is a static value that can be used to specify the alignment 10873for an object, guaranteeing that it is properly aligned in all 10874cases. 10875 10876@node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes 10877@anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{192} 10878@section Attribute Max_Integer_Size 10879 10880 10881@geindex Max_Integer_Size 10882 10883@code{Standard'Max_Integer_Size} (@code{Standard} is the only permissible 10884prefix) provides the size of the largest supported integer type for 10885the target. The result is a static constant. 10886 10887@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes 10888@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{193} 10889@section Attribute Mechanism_Code 10890 10891 10892@geindex Return values 10893@geindex passing mechanism 10894 10895@geindex Parameters 10896@geindex passing mechanism 10897 10898@geindex Mechanism_Code 10899 10900@code{func'Mechanism_Code} yields an integer code for the 10901mechanism used for the result of function @code{func}, and 10902@code{subprog'Mechanism_Code (n)} yields the mechanism 10903used for formal parameter number @emph{n} (a static integer value, with 1 10904meaning the first parameter) of subprogram @code{subprog}. The code returned is: 10905 10906 10907@table @asis 10908 10909@item @emph{1} 10910 10911by copy (value) 10912 10913@item @emph{2} 10914 10915by reference 10916@end table 10917 10918@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes 10919@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{194} 10920@section Attribute Null_Parameter 10921 10922 10923@geindex Zero address 10924@geindex passing 10925 10926@geindex Null_Parameter 10927 10928A reference @code{T'Null_Parameter} denotes an imaginary object of 10929type or subtype @code{T} allocated at machine address zero. The attribute 10930is allowed only as the default expression of a formal parameter, or as 10931an actual expression of a subprogram call. In either case, the 10932subprogram must be imported. 10933 10934The identity of the object is represented by the address zero in the 10935argument list, independent of the passing mechanism (explicit or 10936default). 10937 10938This capability is needed to specify that a zero address should be 10939passed for a record or other composite object passed by reference. 10940There is no way of indicating this without the @code{Null_Parameter} 10941attribute. 10942 10943@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes 10944@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{143}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{195} 10945@section Attribute Object_Size 10946 10947 10948@geindex Size 10949@geindex used for objects 10950 10951@geindex Object_Size 10952 10953The size of an object is not necessarily the same as the size of the type 10954of an object. This is because by default object sizes are increased to be 10955a multiple of the alignment of the object. For example, 10956@code{Natural'Size} is 1095731, but by default objects of type @code{Natural} will have a size of 32 bits. 10958Similarly, a record containing an integer and a character: 10959 10960@example 10961type Rec is record 10962 I : Integer; 10963 C : Character; 10964end record; 10965@end example 10966 10967will have a size of 40 (that is @code{Rec'Size} will be 40). The 10968alignment will be 4, because of the 10969integer field, and so the default size of record objects for this type 10970will be 64 (8 bytes). 10971 10972If the alignment of the above record is specified to be 1, then the 10973object size will be 40 (5 bytes). This is true by default, and also 10974an object size of 40 can be explicitly specified in this case. 10975 10976A consequence of this capability is that different object sizes can be 10977given to subtypes that would otherwise be considered in Ada to be 10978statically matching. But it makes no sense to consider such subtypes 10979as statically matching. Consequently, GNAT adds a rule 10980to the static matching rules that requires object sizes to match. 10981Consider this example: 10982 10983@example 10984 1. procedure BadAVConvert is 10985 2. type R is new Integer; 10986 3. subtype R1 is R range 1 .. 10; 10987 4. subtype R2 is R range 1 .. 10; 10988 5. for R1'Object_Size use 8; 10989 6. for R2'Object_Size use 16; 10990 7. type R1P is access all R1; 10991 8. type R2P is access all R2; 10992 9. R1PV : R1P := new R1'(4); 1099310. R2PV : R2P; 1099411. begin 1099512. R2PV := R2P (R1PV); 10996 | 10997 >>> target designated subtype not compatible with 10998 type "R1" defined at line 3 10999 1100013. end; 11001@end example 11002 11003In the absence of lines 5 and 6, 11004types @code{R1} and @code{R2} statically match and 11005hence the conversion on line 12 is legal. But since lines 5 and 6 11006cause the object sizes to differ, GNAT considers that types 11007@code{R1} and @code{R2} are not statically matching, and line 12 11008generates the diagnostic shown above. 11009 11010Similar additional checks are performed in other contexts requiring 11011statically matching subtypes. 11012 11013@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes 11014@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{196} 11015@section Attribute Old 11016 11017 11018@geindex Old 11019 11020In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage 11021within @code{Post} aspect), GNAT also permits the use of this attribute 11022in implementation defined pragmas @code{Postcondition}, 11023@code{Contract_Cases} and @code{Test_Case}. Also usages of 11024@code{Old} which would be illegal according to the Ada 2012 RM 11025definition are allowed under control of 11026implementation defined pragma @code{Unevaluated_Use_Of_Old}. 11027 11028@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes 11029@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{197} 11030@section Attribute Passed_By_Reference 11031 11032 11033@geindex Parameters 11034@geindex when passed by reference 11035 11036@geindex Passed_By_Reference 11037 11038@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns 11039a value of type @code{Boolean} value that is @code{True} if the type is 11040normally passed by reference and @code{False} if the type is normally 11041passed by copy in calls. For scalar types, the result is always @code{False} 11042and is static. For non-scalar types, the result is nonstatic. 11043 11044@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes 11045@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{198} 11046@section Attribute Pool_Address 11047 11048 11049@geindex Pool_Address 11050 11051@code{X'Pool_Address} for any object @code{X} returns the address 11052of X within its storage pool. This is the same as 11053@code{X'Address}, except that for an unconstrained array whose 11054bounds are allocated just before the first component, 11055@code{X'Pool_Address} returns the address of those bounds, 11056whereas @code{X'Address} returns the address of the first 11057component. 11058 11059Here, we are interpreting 'storage pool' broadly to mean 11060@code{wherever the object is allocated}, which could be a 11061user-defined storage pool, 11062the global heap, on the stack, or in a static memory area. 11063For an object created by @code{new}, @code{Ptr.all'Pool_Address} is 11064what is passed to @code{Allocate} and returned from @code{Deallocate}. 11065 11066@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes 11067@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{199} 11068@section Attribute Range_Length 11069 11070 11071@geindex Range_Length 11072 11073@code{typ'Range_Length} for any discrete type @cite{typ} yields 11074the number of values represented by the subtype (zero for a null 11075range). The result is static for static subtypes. @code{Range_Length} 11076applied to the index subtype of a one dimensional array always gives the 11077same result as @code{Length} applied to the array itself. 11078 11079@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes 11080@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{19a} 11081@section Attribute Restriction_Set 11082 11083 11084@geindex Restriction_Set 11085 11086@geindex Restrictions 11087 11088This attribute allows compile time testing of restrictions that 11089are currently in effect. It is primarily intended for specializing 11090code in the run-time based on restrictions that are active (e.g. 11091don't need to save fpt registers if restriction No_Floating_Point 11092is known to be in effect), but can be used anywhere. 11093 11094There are two forms: 11095 11096@example 11097System'Restriction_Set (partition_boolean_restriction_NAME) 11098System'Restriction_Set (No_Dependence => library_unit_NAME); 11099@end example 11100 11101In the case of the first form, the only restriction names 11102allowed are parameterless restrictions that are checked 11103for consistency at bind time. For a complete list see the 11104subtype @code{System.Rident.Partition_Boolean_Restrictions}. 11105 11106The result returned is True if the restriction is known to 11107be in effect, and False if the restriction is known not to 11108be in effect. An important guarantee is that the value of 11109a Restriction_Set attribute is known to be consistent throughout 11110all the code of a partition. 11111 11112This is trivially achieved if the entire partition is compiled 11113with a consistent set of restriction pragmas. However, the 11114compilation model does not require this. It is possible to 11115compile one set of units with one set of pragmas, and another 11116set of units with another set of pragmas. It is even possible 11117to compile a spec with one set of pragmas, and then WITH the 11118same spec with a different set of pragmas. Inconsistencies 11119in the actual use of the restriction are checked at bind time. 11120 11121In order to achieve the guarantee of consistency for the 11122Restriction_Set pragma, we consider that a use of the pragma 11123that yields False is equivalent to a violation of the 11124restriction. 11125 11126So for example if you write 11127 11128@example 11129if System'Restriction_Set (No_Floating_Point) then 11130 ... 11131else 11132 ... 11133end if; 11134@end example 11135 11136And the result is False, so that the else branch is executed, 11137you can assume that this restriction is not set for any unit 11138in the partition. This is checked by considering this use of 11139the restriction pragma to be a violation of the restriction 11140No_Floating_Point. This means that no other unit can attempt 11141to set this restriction (if some unit does attempt to set it, 11142the binder will refuse to bind the partition). 11143 11144Technical note: The restriction name and the unit name are 11145intepreted entirely syntactically, as in the corresponding 11146Restrictions pragma, they are not analyzed semantically, 11147so they do not have a type. 11148 11149@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes 11150@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{19b} 11151@section Attribute Result 11152 11153 11154@geindex Result 11155 11156@code{function'Result} can only be used with in a Postcondition pragma 11157for a function. The prefix must be the name of the corresponding function. This 11158is used to refer to the result of the function in the postcondition expression. 11159For a further discussion of the use of this attribute and examples of its use, 11160see the description of pragma Postcondition. 11161 11162@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes 11163@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{19c} 11164@section Attribute Safe_Emax 11165 11166 11167@geindex Ada 83 attributes 11168 11169@geindex Safe_Emax 11170 11171The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See 11172the Ada 83 reference manual for an exact description of the semantics of 11173this attribute. 11174 11175@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes 11176@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{19d} 11177@section Attribute Safe_Large 11178 11179 11180@geindex Ada 83 attributes 11181 11182@geindex Safe_Large 11183 11184The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See 11185the Ada 83 reference manual for an exact description of the semantics of 11186this attribute. 11187 11188@node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes 11189@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19e} 11190@section Attribute Safe_Small 11191 11192 11193@geindex Ada 83 attributes 11194 11195@geindex Safe_Small 11196 11197The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See 11198the Ada 83 reference manual for an exact description of the semantics of 11199this attribute. 11200 11201@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes 11202@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19f}@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{151} 11203@section Attribute Scalar_Storage_Order 11204 11205 11206@geindex Endianness 11207 11208@geindex Scalar storage order 11209 11210@geindex Scalar_Storage_Order 11211 11212For every array or record type @code{S}, the representation attribute 11213@code{Scalar_Storage_Order} denotes the order in which storage elements 11214that make up scalar components are ordered within S. The value given must 11215be a static expression of type System.Bit_Order. The following is an example 11216of the use of this feature: 11217 11218@example 11219-- Component type definitions 11220 11221subtype Yr_Type is Natural range 0 .. 127; 11222subtype Mo_Type is Natural range 1 .. 12; 11223subtype Da_Type is Natural range 1 .. 31; 11224 11225-- Record declaration 11226 11227type Date is record 11228 Years_Since_1980 : Yr_Type; 11229 Month : Mo_Type; 11230 Day_Of_Month : Da_Type; 11231end record; 11232 11233-- Record representation clause 11234 11235for Date use record 11236 Years_Since_1980 at 0 range 0 .. 6; 11237 Month at 0 range 7 .. 10; 11238 Day_Of_Month at 0 range 11 .. 15; 11239end record; 11240 11241-- Attribute definition clauses 11242 11243for Date'Bit_Order use System.High_Order_First; 11244for Date'Scalar_Storage_Order use System.High_Order_First; 11245-- If Scalar_Storage_Order is specified, it must be consistent with 11246-- Bit_Order, so it's best to always define the latter explicitly if 11247-- the former is used. 11248@end example 11249 11250Other properties are as for the standard representation attribute @code{Bit_Order} 11251defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. 11252 11253For a record type @code{T}, if @code{T'Scalar_Storage_Order} is 11254specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: 11255this means that if a @code{Scalar_Storage_Order} attribute definition 11256clause is not confirming, then the type's @code{Bit_Order} shall be 11257specified explicitly and set to the same value. 11258 11259Derived types inherit an explicitly set scalar storage order from their parent 11260types. This may be overridden for the derived type by giving an explicit scalar 11261storage order for it. However, for a record extension, the derived type must 11262have the same scalar storage order as the parent type. 11263 11264A component of a record type that is itself a record or an array and that does 11265not start and end on a byte boundary must have have the same scalar storage 11266order as the record type. A component of a bit-packed array type that is itself 11267a record or an array must have the same scalar storage order as the array type. 11268 11269No component of a type that has an explicit @code{Scalar_Storage_Order} 11270attribute definition may be aliased. 11271 11272A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. 11273with a value equal to @code{System.Default_Bit_Order}) has no effect. 11274 11275If the opposite storage order is specified, then whenever the value of 11276a scalar component of an object of type @code{S} is read, the storage 11277elements of the enclosing machine scalar are first reversed (before 11278retrieving the component value, possibly applying some shift and mask 11279operatings on the enclosing machine scalar), and the opposite operation 11280is done for writes. 11281 11282In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 11283are relaxed. Instead, the following rules apply: 11284 11285 11286@itemize * 11287 11288@item 11289the underlying storage elements are those at positions 11290@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} 11291 11292@item 11293the sequence of underlying storage elements shall have 11294a size no greater than the largest machine scalar 11295 11296@item 11297the enclosing machine scalar is defined as the smallest machine 11298scalar starting at a position no greater than 11299@code{position + first_bit / storage_element_size} and covering 11300storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`} 11301 11302@item 11303the position of the component is interpreted relative to that machine 11304scalar. 11305@end itemize 11306 11307If no scalar storage order is specified for a type (either directly, or by 11308inheritance in the case of a derived type), then the default is normally 11309the native ordering of the target, but this default can be overridden using 11310pragma @code{Default_Scalar_Storage_Order}. 11311 11312If a component of @code{T} is itself of a record or array type, the specfied 11313@code{Scalar_Storage_Order} does @emph{not} apply to that nested type: an explicit 11314attribute definition clause must be provided for the component type as well 11315if desired. 11316 11317Note that the scalar storage order only affects the in-memory data 11318representation. It has no effect on the representation used by stream 11319attributes. 11320 11321Note that debuggers may be unable to display the correct value of scalar 11322components of a type for which the opposite storage order is specified. 11323 11324@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes 11325@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e5}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{1a0} 11326@section Attribute Simple_Storage_Pool 11327 11328 11329@geindex Storage pool 11330@geindex simple 11331 11332@geindex Simple storage pool 11333 11334@geindex Simple_Storage_Pool 11335 11336For every nonformal, nonderived access-to-object type @code{Acc}, the 11337representation attribute @code{Simple_Storage_Pool} may be specified 11338via an attribute_definition_clause (or by specifying the equivalent aspect): 11339 11340@example 11341My_Pool : My_Simple_Storage_Pool_Type; 11342 11343type Acc is access My_Data_Type; 11344 11345for Acc'Simple_Storage_Pool use My_Pool; 11346@end example 11347 11348The name given in an attribute_definition_clause for the 11349@code{Simple_Storage_Pool} attribute shall denote a variable of 11350a 'simple storage pool type' (see pragma @cite{Simple_Storage_Pool_Type}). 11351 11352The use of this attribute is only allowed for a prefix denoting a type 11353for which it has been specified. The type of the attribute is the type 11354of the variable specified as the simple storage pool of the access type, 11355and the attribute denotes that variable. 11356 11357It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} 11358for the same access type. 11359 11360If the @code{Simple_Storage_Pool} attribute has been specified for an access 11361type, then applying the @code{Storage_Pool} attribute to the type is flagged 11362with a warning and its evaluation raises the exception @code{Program_Error}. 11363 11364If the Simple_Storage_Pool attribute has been specified for an access 11365type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} 11366returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, 11367which is intended to indicate the number of storage elements reserved for 11368the simple storage pool. If the Storage_Size function has not been defined 11369for the simple storage pool type, then this attribute returns zero. 11370 11371If an access type @code{S} has a specified simple storage pool of type 11372@code{SSP}, then the evaluation of an allocator for that access type calls 11373the primitive @code{Allocate} procedure for type @code{SSP}, passing 11374@code{S'Simple_Storage_Pool} as the pool parameter. The detailed 11375semantics of such allocators is the same as those defined for allocators 11376in section 13.11 of the @cite{Ada Reference Manual}, with the term 11377@emph{simple storage pool} substituted for @emph{storage pool}. 11378 11379If an access type @code{S} has a specified simple storage pool of type 11380@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} 11381for that access type invokes the primitive @code{Deallocate} procedure 11382for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool 11383parameter. The detailed semantics of such unchecked deallocations is the same 11384as defined in section 13.11.2 of the Ada Reference Manual, except that the 11385term @emph{simple storage pool} is substituted for @emph{storage pool}. 11386 11387@node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes 11388@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{1a1} 11389@section Attribute Small 11390 11391 11392@geindex Ada 83 attributes 11393 11394@geindex Small 11395 11396The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for 11397fixed-point types. 11398GNAT also allows this attribute to be applied to floating-point types 11399for compatibility with Ada 83. See 11400the Ada 83 reference manual for an exact description of the semantics of 11401this attribute when applied to floating-point types. 11402 11403@node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes 11404@anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{1a2} 11405@section Attribute Small_Denominator 11406 11407 11408@geindex Small 11409 11410@geindex Small_Denominator 11411 11412@code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the 11413denominator in the representation of @code{typ'Small} as a rational number 11414with coprime factors (i.e. as an irreducible fraction). 11415 11416@node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes 11417@anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{1a3} 11418@section Attribute Small_Numerator 11419 11420 11421@geindex Small 11422 11423@geindex Small_Numerator 11424 11425@code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the 11426numerator in the representation of @code{typ'Small} as a rational number 11427with coprime factors (i.e. as an irreducible fraction). 11428 11429@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes 11430@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a4} 11431@section Attribute Storage_Unit 11432 11433 11434@geindex Storage_Unit 11435 11436@code{Standard'Storage_Unit} (@code{Standard} is the only permissible 11437prefix) provides the same value as @code{System.Storage_Unit}. 11438 11439@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes 11440@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a5} 11441@section Attribute Stub_Type 11442 11443 11444@geindex Stub_Type 11445 11446The GNAT implementation of remote access-to-classwide types is 11447organized as described in AARM section E.4 (20.t): a value of an RACW type 11448(designating a remote object) is represented as a normal access 11449value, pointing to a "stub" object which in turn contains the 11450necessary information to contact the designated remote object. A 11451call on any dispatching operation of such a stub object does the 11452remote call, if necessary, using the information in the stub object 11453to locate the target partition, etc. 11454 11455For a prefix @code{T} that denotes a remote access-to-classwide type, 11456@code{T'Stub_Type} denotes the type of the corresponding stub objects. 11457 11458By construction, the layout of @code{T'Stub_Type} is identical to that of 11459type @code{RACW_Stub_Type} declared in the internal implementation-defined 11460unit @code{System.Partition_Interface}. Use of this attribute will create 11461an implicit dependency on this unit. 11462 11463@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes 11464@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a6} 11465@section Attribute System_Allocator_Alignment 11466 11467 11468@geindex Alignment 11469@geindex allocator 11470 11471@geindex System_Allocator_Alignment 11472 11473@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only 11474permissible prefix) provides the observable guaranted to be honored by 11475the system allocator (malloc). This is a static value that can be used 11476in user storage pools based on malloc either to reject allocation 11477with alignment too large or to enable a realignment circuitry if the 11478alignment request is larger than this value. 11479 11480@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes 11481@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a7} 11482@section Attribute Target_Name 11483 11484 11485@geindex Target_Name 11486 11487@code{Standard'Target_Name} (@code{Standard} is the only permissible 11488prefix) provides a static string value that identifies the target 11489for the current compilation. For GCC implementations, this is the 11490standard gcc target name without the terminating slash (for 11491example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 11492 11493@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes 11494@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a8} 11495@section Attribute To_Address 11496 11497 11498@geindex To_Address 11499 11500The @code{System'To_Address} 11501(@code{System} is the only permissible prefix) 11502denotes a function identical to 11503@code{System.Storage_Elements.To_Address} except that 11504it is a static attribute. This means that if its argument is 11505a static expression, then the result of the attribute is a 11506static expression. This means that such an expression can be 11507used in contexts (e.g., preelaborable packages) which require a 11508static expression and where the function call could not be used 11509(since the function call is always nonstatic, even if its 11510argument is static). The argument must be in the range 11511-(2**(m-1)) .. 2**m-1, where m is the memory size 11512(typically 32 or 64). Negative values are intepreted in a 11513modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on 11514a 32 bits machine). 11515 11516@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes 11517@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a9} 11518@section Attribute To_Any 11519 11520 11521@geindex To_Any 11522 11523This internal attribute is used for the generation of remote subprogram 11524stubs in the context of the Distributed Systems Annex. 11525 11526@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes 11527@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1aa} 11528@section Attribute Type_Class 11529 11530 11531@geindex Type_Class 11532 11533@code{typ'Type_Class} for any type or subtype @cite{typ} yields 11534the value of the type class for the full type of @cite{typ}. If 11535@cite{typ} is a generic formal type, the value is the value for the 11536corresponding actual subtype. The value of this attribute is of type 11537@code{System.Aux_DEC.Type_Class}, which has the following definition: 11538 11539@example 11540type Type_Class is 11541 (Type_Class_Enumeration, 11542 Type_Class_Integer, 11543 Type_Class_Fixed_Point, 11544 Type_Class_Floating_Point, 11545 Type_Class_Array, 11546 Type_Class_Record, 11547 Type_Class_Access, 11548 Type_Class_Task, 11549 Type_Class_Address); 11550@end example 11551 11552Protected types yield the value @code{Type_Class_Task}, which thus 11553applies to all concurrent types. This attribute is designed to 11554be compatible with the DEC Ada 83 attribute of the same name. 11555 11556@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes 11557@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1ab} 11558@section Attribute Type_Key 11559 11560 11561@geindex Type_Key 11562 11563The @code{Type_Key} attribute is applicable to a type or subtype and 11564yields a value of type Standard.String containing encoded information 11565about the type or subtype. This provides improved compatibility with 11566other implementations that support this attribute. 11567 11568@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes 11569@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1ac} 11570@section Attribute TypeCode 11571 11572 11573@geindex TypeCode 11574 11575This internal attribute is used for the generation of remote subprogram 11576stubs in the context of the Distributed Systems Annex. 11577 11578@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes 11579@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1ad} 11580@section Attribute Unconstrained_Array 11581 11582 11583@geindex Unconstrained_Array 11584 11585The @code{Unconstrained_Array} attribute can be used with a prefix that 11586denotes any type or subtype. It is a static attribute that yields 11587@code{True} if the prefix designates an unconstrained array, 11588and @code{False} otherwise. In a generic instance, the result is 11589still static, and yields the result of applying this test to the 11590generic actual. 11591 11592@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes 11593@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1ae} 11594@section Attribute Universal_Literal_String 11595 11596 11597@geindex Named numbers 11598@geindex representation of 11599 11600@geindex Universal_Literal_String 11601 11602The prefix of @code{Universal_Literal_String} must be a named 11603number. The static result is the string consisting of the characters of 11604the number as defined in the original source. This allows the user 11605program to access the actual text of named numbers without intermediate 11606conversions and without the need to enclose the strings in quotes (which 11607would preclude their use as numbers). 11608 11609For example, the following program prints the first 50 digits of pi: 11610 11611@example 11612with Text_IO; use Text_IO; 11613with Ada.Numerics; 11614procedure Pi is 11615begin 11616 Put (Ada.Numerics.Pi'Universal_Literal_String); 11617end; 11618@end example 11619 11620@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes 11621@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1af} 11622@section Attribute Unrestricted_Access 11623 11624 11625@geindex Access 11626@geindex unrestricted 11627 11628@geindex Unrestricted_Access 11629 11630The @code{Unrestricted_Access} attribute is similar to @code{Access} 11631except that all accessibility and aliased view checks are omitted. This 11632is a user-beware attribute. 11633 11634For objects, it is similar to @code{Address}, for which it is a 11635desirable replacement where the value desired is an access type. 11636In other words, its effect is similar to first applying the 11637@code{Address} attribute and then doing an unchecked conversion to a 11638desired access type. 11639 11640For subprograms, @code{P'Unrestricted_Access} may be used where 11641@code{P'Access} would be illegal, to construct a value of a 11642less-nested named access type that designates a more-nested 11643subprogram. This value may be used in indirect calls, so long as the 11644more-nested subprogram still exists; once the subprogram containing it 11645has returned, such calls are erroneous. For example: 11646 11647@example 11648package body P is 11649 11650 type Less_Nested is not null access procedure; 11651 Global : Less_Nested; 11652 11653 procedure P1 is 11654 begin 11655 Global.all; 11656 end P1; 11657 11658 procedure P2 is 11659 Local_Var : Integer; 11660 11661 procedure More_Nested is 11662 begin 11663 ... Local_Var ... 11664 end More_Nested; 11665 begin 11666 Global := More_Nested'Unrestricted_Access; 11667 P1; 11668 end P2; 11669 11670end P; 11671@end example 11672 11673When P1 is called from P2, the call via Global is OK, but if P1 were 11674called after P2 returns, it would be an erroneous use of a dangling 11675pointer. 11676 11677For objects, it is possible to use @code{Unrestricted_Access} for any 11678type. However, if the result is of an access-to-unconstrained array 11679subtype, then the resulting pointer has the same scope as the context 11680of the attribute, and must not be returned to some enclosing scope. 11681For instance, if a function uses @code{Unrestricted_Access} to create 11682an access-to-unconstrained-array and returns that value to the caller, 11683the result will involve dangling pointers. In addition, it is only 11684valid to create pointers to unconstrained arrays using this attribute 11685if the pointer has the normal default 'fat' representation where a 11686pointer has two components, one points to the array and one points to 11687the bounds. If a size clause is used to force 'thin' representation 11688for a pointer to unconstrained where there is only space for a single 11689pointer, then the resulting pointer is not usable. 11690 11691In the simple case where a direct use of Unrestricted_Access attempts 11692to make a thin pointer for a non-aliased object, the compiler will 11693reject the use as illegal, as shown in the following example: 11694 11695@example 11696with System; use System; 11697procedure SliceUA2 is 11698 type A is access all String; 11699 for A'Size use Standard'Address_Size; 11700 11701 procedure P (Arg : A) is 11702 begin 11703 null; 11704 end P; 11705 11706 X : String := "hello world!"; 11707 X2 : aliased String := "hello world!"; 11708 11709 AV : A := X'Unrestricted_Access; -- ERROR 11710 | 11711>>> illegal use of Unrestricted_Access attribute 11712>>> attempt to generate thin pointer to unaliased object 11713 11714begin 11715 P (X'Unrestricted_Access); -- ERROR 11716 | 11717>>> illegal use of Unrestricted_Access attribute 11718>>> attempt to generate thin pointer to unaliased object 11719 11720 P (X(7 .. 12)'Unrestricted_Access); -- ERROR 11721 | 11722>>> illegal use of Unrestricted_Access attribute 11723>>> attempt to generate thin pointer to unaliased object 11724 11725 P (X2'Unrestricted_Access); -- OK 11726end; 11727@end example 11728 11729but other cases cannot be detected by the compiler, and are 11730considered to be erroneous. Consider the following example: 11731 11732@example 11733with System; use System; 11734with System; use System; 11735procedure SliceUA is 11736 type AF is access all String; 11737 11738 type A is access all String; 11739 for A'Size use Standard'Address_Size; 11740 11741 procedure P (Arg : A) is 11742 begin 11743 if Arg'Length /= 6 then 11744 raise Program_Error; 11745 end if; 11746 end P; 11747 11748 X : String := "hello world!"; 11749 Y : AF := X (7 .. 12)'Unrestricted_Access; 11750 11751begin 11752 P (A (Y)); 11753end; 11754@end example 11755 11756A normal unconstrained array value 11757or a constrained array object marked as aliased has the bounds in memory 11758just before the array, so a thin pointer can retrieve both the data and 11759the bounds. But in this case, the non-aliased object @code{X} does not have the 11760bounds before the string. If the size clause for type @code{A} 11761were not present, then the pointer 11762would be a fat pointer, where one component is a pointer to the bounds, 11763and all would be well. But with the size clause present, the conversion from 11764fat pointer to thin pointer in the call loses the bounds, and so this 11765is erroneous, and the program likely raises a @code{Program_Error} exception. 11766 11767In general, it is advisable to completely 11768avoid mixing the use of thin pointers and the use of 11769@code{Unrestricted_Access} where the designated type is an 11770unconstrained array. The use of thin pointers should be restricted to 11771cases of porting legacy code that implicitly assumes the size of pointers, 11772and such code should not in any case be using this attribute. 11773 11774Another erroneous situation arises if the attribute is 11775applied to a constant. The resulting pointer can be used to access the 11776constant, but the effect of trying to modify a constant in this manner 11777is not well-defined. Consider this example: 11778 11779@example 11780P : constant Integer := 4; 11781type R is access all Integer; 11782RV : R := P'Unrestricted_Access; 11783.. 11784RV.all := 3; 11785@end example 11786 11787Here we attempt to modify the constant P from 4 to 3, but the compiler may 11788or may not notice this attempt, and subsequent references to P may yield 11789either the value 3 or the value 4 or the assignment may blow up if the 11790compiler decides to put P in read-only memory. One particular case where 11791@code{Unrestricted_Access} can be used in this way is to modify the 11792value of an @code{in} parameter: 11793 11794@example 11795procedure K (S : in String) is 11796 type R is access all Character; 11797 RV : R := S (3)'Unrestricted_Access; 11798begin 11799 RV.all := 'a'; 11800end; 11801@end example 11802 11803In general this is a risky approach. It may appear to "work" but such uses of 11804@code{Unrestricted_Access} are potentially non-portable, even from one version 11805of GNAT to another, so are best avoided if possible. 11806 11807@node Attribute Update,Attribute Valid_Scalars,Attribute Unrestricted_Access,Implementation Defined Attributes 11808@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1b0} 11809@section Attribute Update 11810 11811 11812@geindex Update 11813 11814The @code{Update} attribute creates a copy of an array or record value 11815with one or more modified components. The syntax is: 11816 11817@example 11818PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) 11819PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) 11820PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION 11821 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) 11822 11823MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION 11824INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} 11825INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) 11826@end example 11827 11828where @code{PREFIX} is the name of an array or record object, the 11829association list in parentheses does not contain an @code{others} 11830choice and the box symbol @code{<>} may not appear in any 11831expression. The effect is to yield a copy of the array or record value 11832which is unchanged apart from the components mentioned in the 11833association list, which are changed to the indicated value. The 11834original value of the array or record value is not affected. For 11835example: 11836 11837@example 11838type Arr is Array (1 .. 5) of Integer; 11839... 11840Avar1 : Arr := (1,2,3,4,5); 11841Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); 11842@end example 11843 11844yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} 11845begin unmodified. Similarly: 11846 11847@example 11848type Rec is A, B, C : Integer; 11849... 11850Rvar1 : Rec := (A => 1, B => 2, C => 3); 11851Rvar2 : Rec := Rvar1'Update (B => 20); 11852@end example 11853 11854yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), 11855with @code{Rvar1} being unmodifed. 11856Note that the value of the attribute reference is computed 11857completely before it is used. This means that if you write: 11858 11859@example 11860Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); 11861@end example 11862 11863then the value of @code{Avar1} is not modified if @code{Function_Call} 11864raises an exception, unlike the effect of a series of direct assignments 11865to elements of @code{Avar1}. In general this requires that 11866two extra complete copies of the object are required, which should be 11867kept in mind when considering efficiency. 11868 11869The @code{Update} attribute cannot be applied to prefixes of a limited 11870type, and cannot reference discriminants in the case of a record type. 11871The accessibility level of an Update attribute result object is defined 11872as for an aggregate. 11873 11874In the record case, no component can be mentioned more than once. In 11875the array case, two overlapping ranges can appear in the association list, 11876in which case the modifications are processed left to right. 11877 11878Multi-dimensional arrays can be modified, as shown by this example: 11879 11880@example 11881A : array (1 .. 10, 1 .. 10) of Integer; 11882.. 11883A := A'Update ((1, 2) => 20, (3, 4) => 30); 11884@end example 11885 11886which changes element (1,2) to 20 and (3,4) to 30. 11887 11888@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Update,Implementation Defined Attributes 11889@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1b1} 11890@section Attribute Valid_Scalars 11891 11892 11893@geindex Valid_Scalars 11894 11895The @code{'Valid_Scalars} attribute is intended to make it easier to check the 11896validity of scalar subcomponents of composite objects. The attribute is defined 11897for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type 11898except for tagged private or @code{Unchecked_Union} types. The value of the 11899attribute is of type @code{Boolean}. 11900 11901@code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of 11902@code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if 11903@code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent 11904to attribute @code{'Valid} for scalar types. 11905 11906It is not specified in what order the subcomponents are checked, nor whether 11907any more are checked after any one of them is determined to be invalid. If the 11908prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated 11909specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then 11910only the subcomponents of @code{T} are checked; in other words, components of 11911extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. 11912 11913The compiler will issue a warning if it can be determined at compile time that 11914the prefix of the attribute has no scalar subcomponents. 11915 11916Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of 11917a large variant record. If the attribute is called in many places in the same 11918program applied to objects of the same type, it can reduce program size to 11919write a function with a single use of the attribute, and then call that 11920function from multiple places. 11921 11922@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes 11923@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b2} 11924@section Attribute VADS_Size 11925 11926 11927@geindex Size 11928@geindex VADS compatibility 11929 11930@geindex VADS_Size 11931 11932The @code{'VADS_Size} attribute is intended to make it easier to port 11933legacy code which relies on the semantics of @code{'Size} as implemented 11934by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 11935same semantic interpretation. In particular, @code{'VADS_Size} applied 11936to a predefined or other primitive type with no Size clause yields the 11937Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on 11938typical machines). In addition @code{'VADS_Size} applied to an object 11939gives the result that would be obtained by applying the attribute to 11940the corresponding type. 11941 11942@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes 11943@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b3}@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{160} 11944@section Attribute Value_Size 11945 11946 11947@geindex Size 11948@geindex setting for not-first subtype 11949 11950@geindex Value_Size 11951 11952@code{type'Value_Size} is the number of bits required to represent 11953a value of the given subtype. It is the same as @code{type'Size}, 11954but, unlike @code{Size}, may be set for non-first subtypes. 11955 11956@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes 11957@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b4} 11958@section Attribute Wchar_T_Size 11959 11960 11961@geindex Wchar_T_Size 11962 11963@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible 11964prefix) provides the size in bits of the C @code{wchar_t} type 11965primarily for constructing the definition of this type in 11966package @code{Interfaces.C}. The result is a static constant. 11967 11968@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes 11969@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b5} 11970@section Attribute Word_Size 11971 11972 11973@geindex Word_Size 11974 11975@code{Standard'Word_Size} (@code{Standard} is the only permissible 11976prefix) provides the value @code{System.Word_Size}. The result is 11977a static constant. 11978 11979@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top 11980@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{1b6}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b7} 11981@chapter Standard and Implementation Defined Restrictions 11982 11983 11984All Ada Reference Manual-defined Restriction identifiers are implemented: 11985 11986 11987@itemize * 11988 11989@item 11990language-defined restrictions (see 13.12.1) 11991 11992@item 11993tasking restrictions (see D.7) 11994 11995@item 11996high integrity restrictions (see H.4) 11997@end itemize 11998 11999GNAT implements additional restriction identifiers. All restrictions, whether 12000language defined or GNAT-specific, are listed in the following. 12001 12002@menu 12003* Partition-Wide Restrictions:: 12004* Program Unit Level Restrictions:: 12005 12006@end menu 12007 12008@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions 12009@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b8}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b9} 12010@section Partition-Wide Restrictions 12011 12012 12013There are two separate lists of restriction identifiers. The first 12014set requires consistency throughout a partition (in other words, if the 12015restriction identifier is used for any compilation unit in the partition, 12016then all compilation units in the partition must obey the restriction). 12017 12018@menu 12019* Immediate_Reclamation:: 12020* Max_Asynchronous_Select_Nesting:: 12021* Max_Entry_Queue_Length:: 12022* Max_Protected_Entries:: 12023* Max_Select_Alternatives:: 12024* Max_Storage_At_Blocking:: 12025* Max_Task_Entries:: 12026* Max_Tasks:: 12027* No_Abort_Statements:: 12028* No_Access_Parameter_Allocators:: 12029* No_Access_Subprograms:: 12030* No_Allocators:: 12031* No_Anonymous_Allocators:: 12032* No_Asynchronous_Control:: 12033* No_Calendar:: 12034* No_Coextensions:: 12035* No_Default_Initialization:: 12036* No_Delay:: 12037* No_Dependence:: 12038* No_Direct_Boolean_Operators:: 12039* No_Dispatch:: 12040* No_Dispatching_Calls:: 12041* No_Dynamic_Attachment:: 12042* No_Dynamic_Priorities:: 12043* No_Entry_Calls_In_Elaboration_Code:: 12044* No_Enumeration_Maps:: 12045* No_Exception_Handlers:: 12046* No_Exception_Propagation:: 12047* No_Exception_Registration:: 12048* No_Exceptions:: 12049* No_Finalization:: 12050* No_Fixed_Point:: 12051* No_Floating_Point:: 12052* No_Implicit_Conditionals:: 12053* No_Implicit_Dynamic_Code:: 12054* No_Implicit_Heap_Allocations:: 12055* No_Implicit_Protected_Object_Allocations:: 12056* No_Implicit_Task_Allocations:: 12057* No_Initialize_Scalars:: 12058* No_IO:: 12059* No_Local_Allocators:: 12060* No_Local_Protected_Objects:: 12061* No_Local_Timing_Events:: 12062* No_Long_Long_Integers:: 12063* No_Multiple_Elaboration:: 12064* No_Nested_Finalization:: 12065* No_Protected_Type_Allocators:: 12066* No_Protected_Types:: 12067* No_Recursion:: 12068* No_Reentrancy:: 12069* No_Relative_Delay:: 12070* No_Requeue_Statements:: 12071* No_Secondary_Stack:: 12072* No_Select_Statements:: 12073* No_Specific_Termination_Handlers:: 12074* No_Specification_of_Aspect:: 12075* No_Standard_Allocators_After_Elaboration:: 12076* No_Standard_Storage_Pools:: 12077* No_Stream_Optimizations:: 12078* No_Streams:: 12079* No_Task_Allocators:: 12080* No_Task_At_Interrupt_Priority:: 12081* No_Task_Attributes_Package:: 12082* No_Task_Hierarchy:: 12083* No_Task_Termination:: 12084* No_Tasking:: 12085* No_Terminate_Alternatives:: 12086* No_Unchecked_Access:: 12087* No_Unchecked_Conversion:: 12088* No_Unchecked_Deallocation:: 12089* No_Use_Of_Entity:: 12090* Pure_Barriers:: 12091* Simple_Barriers:: 12092* Static_Priorities:: 12093* Static_Storage_Size:: 12094 12095@end menu 12096 12097@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions 12098@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1ba} 12099@subsection Immediate_Reclamation 12100 12101 12102@geindex Immediate_Reclamation 12103 12104[RM H.4] This restriction ensures that, except for storage occupied by 12105objects created by allocators and not deallocated via unchecked 12106deallocation, any storage reserved at run time for an object is 12107immediately reclaimed when the object no longer exists. 12108 12109@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions 12110@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1bb} 12111@subsection Max_Asynchronous_Select_Nesting 12112 12113 12114@geindex Max_Asynchronous_Select_Nesting 12115 12116[RM D.7] Specifies the maximum dynamic nesting level of asynchronous 12117selects. Violations of this restriction with a value of zero are 12118detected at compile time. Violations of this restriction with values 12119other than zero cause Storage_Error to be raised. 12120 12121@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions 12122@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1bc} 12123@subsection Max_Entry_Queue_Length 12124 12125 12126@geindex Max_Entry_Queue_Length 12127 12128[RM D.7] This restriction is a declaration that any protected entry compiled in 12129the scope of the restriction has at most the specified number of 12130tasks waiting on the entry at any one time, and so no queue is required. 12131Note that this restriction is checked at run time. Violation of this 12132restriction results in the raising of Program_Error exception at the point of 12133the call. 12134 12135@geindex Max_Entry_Queue_Depth 12136 12137The restriction @code{Max_Entry_Queue_Depth} is recognized as a 12138synonym for @code{Max_Entry_Queue_Length}. This is retained for historical 12139compatibility purposes (and a warning will be generated for its use if 12140warnings on obsolescent features are activated). 12141 12142@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions 12143@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1bd} 12144@subsection Max_Protected_Entries 12145 12146 12147@geindex Max_Protected_Entries 12148 12149[RM D.7] Specifies the maximum number of entries per protected type. The 12150bounds of every entry family of a protected unit shall be static, or shall be 12151defined by a discriminant of a subtype whose corresponding bound is static. 12152 12153@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions 12154@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1be} 12155@subsection Max_Select_Alternatives 12156 12157 12158@geindex Max_Select_Alternatives 12159 12160[RM D.7] Specifies the maximum number of alternatives in a selective accept. 12161 12162@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions 12163@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1bf} 12164@subsection Max_Storage_At_Blocking 12165 12166 12167@geindex Max_Storage_At_Blocking 12168 12169[RM D.7] Specifies the maximum portion (in storage elements) of a task's 12170Storage_Size that can be retained by a blocked task. A violation of this 12171restriction causes Storage_Error to be raised. 12172 12173@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions 12174@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1c0} 12175@subsection Max_Task_Entries 12176 12177 12178@geindex Max_Task_Entries 12179 12180[RM D.7] Specifies the maximum number of entries 12181per task. The bounds of every entry family 12182of a task unit shall be static, or shall be 12183defined by a discriminant of a subtype whose 12184corresponding bound is static. 12185 12186@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions 12187@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1c1} 12188@subsection Max_Tasks 12189 12190 12191@geindex Max_Tasks 12192 12193[RM D.7] Specifies the maximum number of task that may be created, not 12194counting the creation of the environment task. Violations of this 12195restriction with a value of zero are detected at compile 12196time. Violations of this restriction with values other than zero cause 12197Storage_Error to be raised. 12198 12199@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions 12200@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c2} 12201@subsection No_Abort_Statements 12202 12203 12204@geindex No_Abort_Statements 12205 12206[RM D.7] There are no abort_statements, and there are 12207no calls to Task_Identification.Abort_Task. 12208 12209@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions 12210@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c3} 12211@subsection No_Access_Parameter_Allocators 12212 12213 12214@geindex No_Access_Parameter_Allocators 12215 12216[RM H.4] This restriction ensures at compile time that there are no 12217occurrences of an allocator as the actual parameter to an access 12218parameter. 12219 12220@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions 12221@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c4} 12222@subsection No_Access_Subprograms 12223 12224 12225@geindex No_Access_Subprograms 12226 12227[RM H.4] This restriction ensures at compile time that there are no 12228declarations of access-to-subprogram types. 12229 12230@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions 12231@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c5} 12232@subsection No_Allocators 12233 12234 12235@geindex No_Allocators 12236 12237[RM H.4] This restriction ensures at compile time that there are no 12238occurrences of an allocator. 12239 12240@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions 12241@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c6} 12242@subsection No_Anonymous_Allocators 12243 12244 12245@geindex No_Anonymous_Allocators 12246 12247[RM H.4] This restriction ensures at compile time that there are no 12248occurrences of an allocator of anonymous access type. 12249 12250@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions 12251@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c7} 12252@subsection No_Asynchronous_Control 12253 12254 12255@geindex No_Asynchronous_Control 12256 12257[RM J.13] This restriction ensures at compile time that there are no semantic 12258dependences on the predefined package Asynchronous_Task_Control. 12259 12260@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions 12261@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c8} 12262@subsection No_Calendar 12263 12264 12265@geindex No_Calendar 12266 12267[GNAT] This restriction ensures at compile time that there are no semantic 12268dependences on package Calendar. 12269 12270@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions 12271@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c9} 12272@subsection No_Coextensions 12273 12274 12275@geindex No_Coextensions 12276 12277[RM H.4] This restriction ensures at compile time that there are no 12278coextensions. See 3.10.2. 12279 12280@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions 12281@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1ca} 12282@subsection No_Default_Initialization 12283 12284 12285@geindex No_Default_Initialization 12286 12287[GNAT] This restriction prohibits any instance of default initialization 12288of variables. The binder implements a consistency rule which prevents 12289any unit compiled without the restriction from with'ing a unit with the 12290restriction (this allows the generation of initialization procedures to 12291be skipped, since you can be sure that no call is ever generated to an 12292initialization procedure in a unit with the restriction active). If used 12293in conjunction with Initialize_Scalars or Normalize_Scalars, the effect 12294is to prohibit all cases of variables declared without a specific 12295initializer (including the case of OUT scalar parameters). 12296 12297@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions 12298@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1cb} 12299@subsection No_Delay 12300 12301 12302@geindex No_Delay 12303 12304[RM H.4] This restriction ensures at compile time that there are no 12305delay statements and no semantic dependences on package Calendar. 12306 12307@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions 12308@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1cc} 12309@subsection No_Dependence 12310 12311 12312@geindex No_Dependence 12313 12314[RM 13.12.1] This restriction ensures at compile time that there are no 12315dependences on a library unit. 12316 12317@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions 12318@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1cd} 12319@subsection No_Direct_Boolean_Operators 12320 12321 12322@geindex No_Direct_Boolean_Operators 12323 12324[GNAT] This restriction ensures that no logical operators (and/or/xor) 12325are used on operands of type Boolean (or any type derived from Boolean). 12326This is intended for use in safety critical programs where the certification 12327protocol requires the use of short-circuit (and then, or else) forms for all 12328composite boolean operations. 12329 12330@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions 12331@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1ce} 12332@subsection No_Dispatch 12333 12334 12335@geindex No_Dispatch 12336 12337[RM H.4] This restriction ensures at compile time that there are no 12338occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. 12339 12340@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions 12341@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1cf} 12342@subsection No_Dispatching_Calls 12343 12344 12345@geindex No_Dispatching_Calls 12346 12347[GNAT] This restriction ensures at compile time that the code generated by the 12348compiler involves no dispatching calls. The use of this restriction allows the 12349safe use of record extensions, classwide membership tests and other classwide 12350features not involving implicit dispatching. This restriction ensures that 12351the code contains no indirect calls through a dispatching mechanism. Note that 12352this includes internally-generated calls created by the compiler, for example 12353in the implementation of class-wide objects assignments. The 12354membership test is allowed in the presence of this restriction, because its 12355implementation requires no dispatching. 12356This restriction is comparable to the official Ada restriction 12357@code{No_Dispatch} except that it is a bit less restrictive in that it allows 12358all classwide constructs that do not imply dispatching. 12359The following example indicates constructs that violate this restriction. 12360 12361@example 12362package Pkg is 12363 type T is tagged record 12364 Data : Natural; 12365 end record; 12366 procedure P (X : T); 12367 12368 type DT is new T with record 12369 More_Data : Natural; 12370 end record; 12371 procedure Q (X : DT); 12372end Pkg; 12373 12374with Pkg; use Pkg; 12375procedure Example is 12376 procedure Test (O : T'Class) is 12377 N : Natural := O'Size;-- Error: Dispatching call 12378 C : T'Class := O; -- Error: implicit Dispatching Call 12379 begin 12380 if O in DT'Class then -- OK : Membership test 12381 Q (DT (O)); -- OK : Type conversion plus direct call 12382 else 12383 P (O); -- Error: Dispatching call 12384 end if; 12385 end Test; 12386 12387 Obj : DT; 12388begin 12389 P (Obj); -- OK : Direct call 12390 P (T (Obj)); -- OK : Type conversion plus direct call 12391 P (T'Class (Obj)); -- Error: Dispatching call 12392 12393 Test (Obj); -- OK : Type conversion 12394 12395 if Obj in T'Class then -- OK : Membership test 12396 null; 12397 end if; 12398end Example; 12399@end example 12400 12401@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions 12402@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1d0} 12403@subsection No_Dynamic_Attachment 12404 12405 12406@geindex No_Dynamic_Attachment 12407 12408[RM D.7] This restriction ensures that there is no call to any of the 12409operations defined in package Ada.Interrupts 12410(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, 12411Detach_Handler, and Reference). 12412 12413@geindex No_Dynamic_Interrupts 12414 12415The restriction @code{No_Dynamic_Interrupts} is recognized as a 12416synonym for @code{No_Dynamic_Attachment}. This is retained for historical 12417compatibility purposes (and a warning will be generated for its use if 12418warnings on obsolescent features are activated). 12419 12420@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions 12421@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1d1} 12422@subsection No_Dynamic_Priorities 12423 12424 12425@geindex No_Dynamic_Priorities 12426 12427[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 12428 12429@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions 12430@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d2} 12431@subsection No_Entry_Calls_In_Elaboration_Code 12432 12433 12434@geindex No_Entry_Calls_In_Elaboration_Code 12435 12436[GNAT] This restriction ensures at compile time that no task or protected entry 12437calls are made during elaboration code. As a result of the use of this 12438restriction, the compiler can assume that no code past an accept statement 12439in a task can be executed at elaboration time. 12440 12441@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions 12442@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d3} 12443@subsection No_Enumeration_Maps 12444 12445 12446@geindex No_Enumeration_Maps 12447 12448[GNAT] This restriction ensures at compile time that no operations requiring 12449enumeration maps are used (that is Image and Value attributes applied 12450to enumeration types). 12451 12452@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions 12453@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d4} 12454@subsection No_Exception_Handlers 12455 12456 12457@geindex No_Exception_Handlers 12458 12459[GNAT] This restriction ensures at compile time that there are no explicit 12460exception handlers. It also indicates that no exception propagation will 12461be provided. In this mode, exceptions may be raised but will result in 12462an immediate call to the last chance handler, a routine that the user 12463must define with the following profile: 12464 12465@example 12466procedure Last_Chance_Handler 12467 (Source_Location : System.Address; Line : Integer); 12468pragma Export (C, Last_Chance_Handler, 12469 "__gnat_last_chance_handler"); 12470@end example 12471 12472The parameter is a C null-terminated string representing a message to be 12473associated with the exception (typically the source location of the raise 12474statement generated by the compiler). The Line parameter when nonzero 12475represents the line number in the source program where the raise occurs. 12476 12477@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions 12478@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d5} 12479@subsection No_Exception_Propagation 12480 12481 12482@geindex No_Exception_Propagation 12483 12484[GNAT] This restriction guarantees that exceptions are never propagated 12485to an outer subprogram scope. The only case in which an exception may 12486be raised is when the handler is statically in the same subprogram, so 12487that the effect of a raise is essentially like a goto statement. Any 12488other raise statement (implicit or explicit) will be considered 12489unhandled. Exception handlers are allowed, but may not contain an 12490exception occurrence identifier (exception choice). In addition, use of 12491the package GNAT.Current_Exception is not permitted, and reraise 12492statements (raise with no operand) are not permitted. 12493 12494@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions 12495@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d6} 12496@subsection No_Exception_Registration 12497 12498 12499@geindex No_Exception_Registration 12500 12501[GNAT] This restriction ensures at compile time that no stream operations for 12502types Exception_Id or Exception_Occurrence are used. This also makes it 12503impossible to pass exceptions to or from a partition with this restriction 12504in a distributed environment. If this restriction is active, the generated 12505code is simplified by omitting the otherwise-required global registration 12506of exceptions when they are declared. 12507 12508@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions 12509@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d7} 12510@subsection No_Exceptions 12511 12512 12513@geindex No_Exceptions 12514 12515[RM H.4] This restriction ensures at compile time that there are no 12516raise statements and no exception handlers and also suppresses the 12517generation of language-defined run-time checks. 12518 12519@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions 12520@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d8} 12521@subsection No_Finalization 12522 12523 12524@geindex No_Finalization 12525 12526[GNAT] This restriction disables the language features described in 12527chapter 7.6 of the Ada 2005 RM as well as all form of code generation 12528performed by the compiler to support these features. The following types 12529are no longer considered controlled when this restriction is in effect: 12530 12531 12532@itemize * 12533 12534@item 12535@code{Ada.Finalization.Controlled} 12536 12537@item 12538@code{Ada.Finalization.Limited_Controlled} 12539 12540@item 12541Derivations from @code{Controlled} or @code{Limited_Controlled} 12542 12543@item 12544Class-wide types 12545 12546@item 12547Protected types 12548 12549@item 12550Task types 12551 12552@item 12553Array and record types with controlled components 12554@end itemize 12555 12556The compiler no longer generates code to initialize, finalize or adjust an 12557object or a nested component, either declared on the stack or on the heap. The 12558deallocation of a controlled object no longer finalizes its contents. 12559 12560@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions 12561@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d9} 12562@subsection No_Fixed_Point 12563 12564 12565@geindex No_Fixed_Point 12566 12567[RM H.4] This restriction ensures at compile time that there are no 12568occurrences of fixed point types and operations. 12569 12570@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions 12571@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1da} 12572@subsection No_Floating_Point 12573 12574 12575@geindex No_Floating_Point 12576 12577[RM H.4] This restriction ensures at compile time that there are no 12578occurrences of floating point types and operations. 12579 12580@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions 12581@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1db} 12582@subsection No_Implicit_Conditionals 12583 12584 12585@geindex No_Implicit_Conditionals 12586 12587[GNAT] This restriction ensures that the generated code does not contain any 12588implicit conditionals, either by modifying the generated code where possible, 12589or by rejecting any construct that would otherwise generate an implicit 12590conditional. Note that this check does not include run time constraint 12591checks, which on some targets may generate implicit conditionals as 12592well. To control the latter, constraint checks can be suppressed in the 12593normal manner. Constructs generating implicit conditionals include comparisons 12594of composite objects and the Max/Min attributes. 12595 12596@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions 12597@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1dc} 12598@subsection No_Implicit_Dynamic_Code 12599 12600 12601@geindex No_Implicit_Dynamic_Code 12602 12603@geindex trampoline 12604 12605[GNAT] This restriction prevents the compiler from building 'trampolines'. 12606This is a structure that is built on the stack and contains dynamic 12607code to be executed at run time. On some targets, a trampoline is 12608built for the following features: @code{Access}, 12609@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; 12610nested task bodies; primitive operations of nested tagged types. 12611Trampolines do not work on machines that prevent execution of stack 12612data. For example, on windows systems, enabling DEP (data execution 12613protection) will cause trampolines to raise an exception. 12614Trampolines are also quite slow at run time. 12615 12616On many targets, trampolines have been largely eliminated. Look at the 12617version of system.ads for your target --- if it has 12618Always_Compatible_Rep equal to False, then trampolines are largely 12619eliminated. In particular, a trampoline is built for the following 12620features: @code{Address} of a nested subprogram; 12621@code{Access} or @code{Unrestricted_Access} of a nested subprogram, 12622but only if pragma Favor_Top_Level applies, or the access type has a 12623foreign-language convention; primitive operations of nested tagged 12624types. 12625 12626@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions 12627@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1dd} 12628@subsection No_Implicit_Heap_Allocations 12629 12630 12631@geindex No_Implicit_Heap_Allocations 12632 12633[RM D.7] No constructs are allowed to cause implicit heap allocation. 12634 12635@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions 12636@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1de} 12637@subsection No_Implicit_Protected_Object_Allocations 12638 12639 12640@geindex No_Implicit_Protected_Object_Allocations 12641 12642[GNAT] No constructs are allowed to cause implicit heap allocation of a 12643protected object. 12644 12645@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions 12646@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1df} 12647@subsection No_Implicit_Task_Allocations 12648 12649 12650@geindex No_Implicit_Task_Allocations 12651 12652[GNAT] No constructs are allowed to cause implicit heap allocation of a task. 12653 12654@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions 12655@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1e0} 12656@subsection No_Initialize_Scalars 12657 12658 12659@geindex No_Initialize_Scalars 12660 12661[GNAT] This restriction ensures that no unit in the partition is compiled with 12662pragma Initialize_Scalars. This allows the generation of more efficient 12663code, and in particular eliminates dummy null initialization routines that 12664are otherwise generated for some record and array types. 12665 12666@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions 12667@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1e1} 12668@subsection No_IO 12669 12670 12671@geindex No_IO 12672 12673[RM H.4] This restriction ensures at compile time that there are no 12674dependences on any of the library units Sequential_IO, Direct_IO, 12675Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. 12676 12677@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions 12678@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e2} 12679@subsection No_Local_Allocators 12680 12681 12682@geindex No_Local_Allocators 12683 12684[RM H.4] This restriction ensures at compile time that there are no 12685occurrences of an allocator in subprograms, generic subprograms, tasks, 12686and entry bodies. 12687 12688@node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions 12689@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e3} 12690@subsection No_Local_Protected_Objects 12691 12692 12693@geindex No_Local_Protected_Objects 12694 12695[RM D.7] This restriction ensures at compile time that protected objects are 12696only declared at the library level. 12697 12698@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions 12699@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e4} 12700@subsection No_Local_Timing_Events 12701 12702 12703@geindex No_Local_Timing_Events 12704 12705[RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are 12706declared at the library level. 12707 12708@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions 12709@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e5} 12710@subsection No_Long_Long_Integers 12711 12712 12713@geindex No_Long_Long_Integers 12714 12715[GNAT] This partition-wide restriction forbids any explicit reference to 12716type Standard.Long_Long_Integer, and also forbids declaring range types whose 12717implicit base type is Long_Long_Integer, and modular types whose size exceeds 12718Long_Integer'Size. 12719 12720@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions 12721@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e6} 12722@subsection No_Multiple_Elaboration 12723 12724 12725@geindex No_Multiple_Elaboration 12726 12727[GNAT] When this restriction is active and the static elaboration model is 12728used, and -fpreserve-control-flow is not used, the compiler is allowed to 12729suppress the elaboration counter normally associated with the unit, even if 12730the unit has elaboration code. This counter is typically used to check for 12731access before elaboration and to control multiple elaboration attempts. If the 12732restriction is used, then the situations in which multiple elaboration is 12733possible, including non-Ada main programs and Stand Alone libraries, are not 12734permitted and will be diagnosed by the binder. 12735 12736@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions 12737@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e7} 12738@subsection No_Nested_Finalization 12739 12740 12741@geindex No_Nested_Finalization 12742 12743[RM D.7] All objects requiring finalization are declared at the library level. 12744 12745@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions 12746@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e8} 12747@subsection No_Protected_Type_Allocators 12748 12749 12750@geindex No_Protected_Type_Allocators 12751 12752[RM D.7] This restriction ensures at compile time that there are no allocator 12753expressions that attempt to allocate protected objects. 12754 12755@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions 12756@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e9} 12757@subsection No_Protected_Types 12758 12759 12760@geindex No_Protected_Types 12761 12762[RM H.4] This restriction ensures at compile time that there are no 12763declarations of protected types or protected objects. 12764 12765@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions 12766@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1ea} 12767@subsection No_Recursion 12768 12769 12770@geindex No_Recursion 12771 12772[RM H.4] A program execution is erroneous if a subprogram is invoked as 12773part of its execution. 12774 12775@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions 12776@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1eb} 12777@subsection No_Reentrancy 12778 12779 12780@geindex No_Reentrancy 12781 12782[RM H.4] A program execution is erroneous if a subprogram is executed by 12783two tasks at the same time. 12784 12785@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions 12786@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1ec} 12787@subsection No_Relative_Delay 12788 12789 12790@geindex No_Relative_Delay 12791 12792[RM D.7] This restriction ensures at compile time that there are no delay 12793relative statements and prevents expressions such as @code{delay 1.23;} from 12794appearing in source code. 12795 12796@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions 12797@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1ed} 12798@subsection No_Requeue_Statements 12799 12800 12801@geindex No_Requeue_Statements 12802 12803[RM D.7] This restriction ensures at compile time that no requeue statements 12804are permitted and prevents keyword @code{requeue} from being used in source 12805code. 12806 12807@geindex No_Requeue 12808 12809The restriction @code{No_Requeue} is recognized as a 12810synonym for @code{No_Requeue_Statements}. This is retained for historical 12811compatibility purposes (and a warning will be generated for its use if 12812warnings on oNobsolescent features are activated). 12813 12814@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions 12815@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1ee} 12816@subsection No_Secondary_Stack 12817 12818 12819@geindex No_Secondary_Stack 12820 12821[GNAT] This restriction ensures at compile time that the generated code 12822does not contain any reference to the secondary stack. The secondary 12823stack is used to implement functions returning unconstrained objects 12824(arrays or records) on some targets. Suppresses the allocation of 12825secondary stacks for tasks (excluding the environment task) at run time. 12826 12827@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions 12828@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1ef} 12829@subsection No_Select_Statements 12830 12831 12832@geindex No_Select_Statements 12833 12834[RM D.7] This restriction ensures at compile time no select statements of any 12835kind are permitted, that is the keyword @code{select} may not appear. 12836 12837@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions 12838@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1f0} 12839@subsection No_Specific_Termination_Handlers 12840 12841 12842@geindex No_Specific_Termination_Handlers 12843 12844[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler 12845or to Ada.Task_Termination.Specific_Handler. 12846 12847@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions 12848@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1f1} 12849@subsection No_Specification_of_Aspect 12850 12851 12852@geindex No_Specification_of_Aspect 12853 12854[RM 13.12.1] This restriction checks at compile time that no aspect 12855specification, attribute definition clause, or pragma is given for a 12856given aspect. 12857 12858@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions 12859@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f2} 12860@subsection No_Standard_Allocators_After_Elaboration 12861 12862 12863@geindex No_Standard_Allocators_After_Elaboration 12864 12865[RM D.7] Specifies that an allocator using a standard storage pool 12866should never be evaluated at run time after the elaboration of the 12867library items of the partition has completed. Otherwise, Storage_Error 12868is raised. 12869 12870@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions 12871@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f3} 12872@subsection No_Standard_Storage_Pools 12873 12874 12875@geindex No_Standard_Storage_Pools 12876 12877[GNAT] This restriction ensures at compile time that no access types 12878use the standard default storage pool. Any access type declared must 12879have an explicit Storage_Pool attribute defined specifying a 12880user-defined storage pool. 12881 12882@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions 12883@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f4} 12884@subsection No_Stream_Optimizations 12885 12886 12887@geindex No_Stream_Optimizations 12888 12889[GNAT] This restriction affects the performance of stream operations on types 12890@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the 12891compiler uses block reads and writes when manipulating @code{String} objects 12892due to their superior performance. When this restriction is in effect, the 12893compiler performs all IO operations on a per-character basis. 12894 12895@node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions 12896@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f5} 12897@subsection No_Streams 12898 12899 12900@geindex No_Streams 12901 12902[GNAT] This restriction ensures at compile/bind time that there are no 12903stream objects created and no use of stream attributes. 12904This restriction does not forbid dependences on the package 12905@code{Ada.Streams}. So it is permissible to with 12906@code{Ada.Streams} (or another package that does so itself) 12907as long as no actual stream objects are created and no 12908stream attributes are used. 12909 12910Note that the use of restriction allows optimization of tagged types, 12911since they do not need to worry about dispatching stream operations. 12912To take maximum advantage of this space-saving optimization, any 12913unit declaring a tagged type should be compiled with the restriction, 12914though this is not required. 12915 12916@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions 12917@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f6} 12918@subsection No_Task_Allocators 12919 12920 12921@geindex No_Task_Allocators 12922 12923[RM D.7] There are no allocators for task types 12924or types containing task subcomponents. 12925 12926@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions 12927@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f7} 12928@subsection No_Task_At_Interrupt_Priority 12929 12930 12931@geindex No_Task_At_Interrupt_Priority 12932 12933[GNAT] This restriction ensures at compile time that there is no 12934Interrupt_Priority aspect or pragma for a task or a task type. As 12935a consequence, the tasks are always created with a priority below 12936that an interrupt priority. 12937 12938@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions 12939@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f8} 12940@subsection No_Task_Attributes_Package 12941 12942 12943@geindex No_Task_Attributes_Package 12944 12945[GNAT] This restriction ensures at compile time that there are no implicit or 12946explicit dependencies on the package @code{Ada.Task_Attributes}. 12947 12948@geindex No_Task_Attributes 12949 12950The restriction @code{No_Task_Attributes} is recognized as a synonym 12951for @code{No_Task_Attributes_Package}. This is retained for historical 12952compatibility purposes (and a warning will be generated for its use if 12953warnings on obsolescent features are activated). 12954 12955@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions 12956@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f9} 12957@subsection No_Task_Hierarchy 12958 12959 12960@geindex No_Task_Hierarchy 12961 12962[RM D.7] All (non-environment) tasks depend 12963directly on the environment task of the partition. 12964 12965@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions 12966@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1fa} 12967@subsection No_Task_Termination 12968 12969 12970@geindex No_Task_Termination 12971 12972[RM D.7] Tasks that terminate are erroneous. 12973 12974@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions 12975@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1fb} 12976@subsection No_Tasking 12977 12978 12979@geindex No_Tasking 12980 12981[GNAT] This restriction prevents the declaration of tasks or task types 12982throughout the partition. It is similar in effect to the use of 12983@code{Max_Tasks => 0} except that violations are caught at compile time 12984and cause an error message to be output either by the compiler or 12985binder. 12986 12987@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions 12988@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1fc} 12989@subsection No_Terminate_Alternatives 12990 12991 12992@geindex No_Terminate_Alternatives 12993 12994[RM D.7] There are no selective accepts with terminate alternatives. 12995 12996@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions 12997@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1fd} 12998@subsection No_Unchecked_Access 12999 13000 13001@geindex No_Unchecked_Access 13002 13003[RM H.4] This restriction ensures at compile time that there are no 13004occurrences of the Unchecked_Access attribute. 13005 13006@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions 13007@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1fe} 13008@subsection No_Unchecked_Conversion 13009 13010 13011@geindex No_Unchecked_Conversion 13012 13013[RM J.13] This restriction ensures at compile time that there are no semantic 13014dependences on the predefined generic function Unchecked_Conversion. 13015 13016@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions 13017@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1ff} 13018@subsection No_Unchecked_Deallocation 13019 13020 13021@geindex No_Unchecked_Deallocation 13022 13023[RM J.13] This restriction ensures at compile time that there are no semantic 13024dependences on the predefined generic procedure Unchecked_Deallocation. 13025 13026@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions 13027@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{200} 13028@subsection No_Use_Of_Entity 13029 13030 13031@geindex No_Use_Of_Entity 13032 13033[GNAT] This restriction ensures at compile time that there are no references 13034to the entity given in the form 13035 13036@example 13037No_Use_Of_Entity => Name 13038@end example 13039 13040where @code{Name} is the fully qualified entity, for example 13041 13042@example 13043No_Use_Of_Entity => Ada.Text_IO.Put_Line 13044@end example 13045 13046@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions 13047@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{201} 13048@subsection Pure_Barriers 13049 13050 13051@geindex Pure_Barriers 13052 13053[GNAT] This restriction ensures at compile time that protected entry 13054barriers are restricted to: 13055 13056 13057@itemize * 13058 13059@item 13060components of the protected object (excluding selection from dereferences), 13061 13062@item 13063constant declarations, 13064 13065@item 13066named numbers, 13067 13068@item 13069enumeration literals, 13070 13071@item 13072integer literals, 13073 13074@item 13075real literals, 13076 13077@item 13078character literals, 13079 13080@item 13081implicitly defined comparison operators, 13082 13083@item 13084uses of the Standard."not" operator, 13085 13086@item 13087short-circuit operator, 13088 13089@item 13090the Count attribute 13091@end itemize 13092 13093This restriction is a relaxation of the Simple_Barriers restriction, 13094but still ensures absence of side effects, exceptions, and recursion 13095during the evaluation of the barriers. 13096 13097@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions 13098@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{202} 13099@subsection Simple_Barriers 13100 13101 13102@geindex Simple_Barriers 13103 13104[RM D.7] This restriction ensures at compile time that barriers in entry 13105declarations for protected types are restricted to either static boolean 13106expressions or references to simple boolean variables defined in the private 13107part of the protected type. No other form of entry barriers is permitted. 13108 13109@geindex Boolean_Entry_Barriers 13110 13111The restriction @code{Boolean_Entry_Barriers} is recognized as a 13112synonym for @code{Simple_Barriers}. This is retained for historical 13113compatibility purposes (and a warning will be generated for its use if 13114warnings on obsolescent features are activated). 13115 13116@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions 13117@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{203} 13118@subsection Static_Priorities 13119 13120 13121@geindex Static_Priorities 13122 13123[GNAT] This restriction ensures at compile time that all priority expressions 13124are static, and that there are no dependences on the package 13125@code{Ada.Dynamic_Priorities}. 13126 13127@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions 13128@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{204} 13129@subsection Static_Storage_Size 13130 13131 13132@geindex Static_Storage_Size 13133 13134[GNAT] This restriction ensures at compile time that any expression appearing 13135in a Storage_Size pragma or attribute definition clause is static. 13136 13137@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions 13138@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{205}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{206} 13139@section Program Unit Level Restrictions 13140 13141 13142The second set of restriction identifiers 13143does not require partition-wide consistency. 13144The restriction may be enforced for a single 13145compilation unit without any effect on any of the 13146other compilation units in the partition. 13147 13148@menu 13149* No_Elaboration_Code:: 13150* No_Dynamic_Sized_Objects:: 13151* No_Entry_Queue:: 13152* No_Implementation_Aspect_Specifications:: 13153* No_Implementation_Attributes:: 13154* No_Implementation_Identifiers:: 13155* No_Implementation_Pragmas:: 13156* No_Implementation_Restrictions:: 13157* No_Implementation_Units:: 13158* No_Implicit_Aliasing:: 13159* No_Implicit_Loops:: 13160* No_Obsolescent_Features:: 13161* No_Wide_Characters:: 13162* Static_Dispatch_Tables:: 13163* SPARK_05:: 13164 13165@end menu 13166 13167@node No_Elaboration_Code,No_Dynamic_Sized_Objects,,Program Unit Level Restrictions 13168@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{207} 13169@subsection No_Elaboration_Code 13170 13171 13172@geindex No_Elaboration_Code 13173 13174[GNAT] This restriction ensures at compile time that no elaboration code is 13175generated. Note that this is not the same condition as is enforced 13176by pragma @code{Preelaborate}. There are cases in which pragma 13177@code{Preelaborate} still permits code to be generated (e.g., code 13178to initialize a large array to all zeroes), and there are cases of units 13179which do not meet the requirements for pragma @code{Preelaborate}, 13180but for which no elaboration code is generated. Generally, it is 13181the case that preelaborable units will meet the restrictions, with 13182the exception of large aggregates initialized with an others_clause, 13183and exception declarations (which generate calls to a run-time 13184registry procedure). This restriction is enforced on 13185a unit by unit basis, it need not be obeyed consistently 13186throughout a partition. 13187 13188In the case of aggregates with others, if the aggregate has a dynamic 13189size, there is no way to eliminate the elaboration code (such dynamic 13190bounds would be incompatible with @code{Preelaborate} in any case). If 13191the bounds are static, then use of this restriction actually modifies 13192the code choice of the compiler to avoid generating a loop, and instead 13193generate the aggregate statically if possible, no matter how many times 13194the data for the others clause must be repeatedly generated. 13195 13196It is not possible to precisely document 13197the constructs which are compatible with this restriction, since, 13198unlike most other restrictions, this is not a restriction on the 13199source code, but a restriction on the generated object code. For 13200example, if the source contains a declaration: 13201 13202@example 13203Val : constant Integer := X; 13204@end example 13205 13206where X is not a static constant, it may be possible, depending 13207on complex optimization circuitry, for the compiler to figure 13208out the value of X at compile time, in which case this initialization 13209can be done by the loader, and requires no initialization code. It 13210is not possible to document the precise conditions under which the 13211optimizer can figure this out. 13212 13213Note that this the implementation of this restriction requires full 13214code generation. If it is used in conjunction with "semantics only" 13215checking, then some cases of violations may be missed. 13216 13217When this restriction is active, we are not requesting control-flow 13218preservation with -fpreserve-control-flow, and the static elaboration model is 13219used, the compiler is allowed to suppress the elaboration counter normally 13220associated with the unit. This counter is typically used to check for access 13221before elaboration and to control multiple elaboration attempts. 13222 13223@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Elaboration_Code,Program Unit Level Restrictions 13224@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{208} 13225@subsection No_Dynamic_Sized_Objects 13226 13227 13228@geindex No_Dynamic_Sized_Objects 13229 13230[GNAT] This restriction disallows certain constructs that might lead to the 13231creation of dynamic-sized composite objects (or array or discriminated type). 13232An array subtype indication is illegal if the bounds are not static 13233or references to discriminants of an enclosing type. 13234A discriminated subtype indication is illegal if the type has 13235discriminant-dependent array components or a variant part, and the 13236discriminants are not static. In addition, array and record aggregates are 13237illegal in corresponding cases. Note that this restriction does not forbid 13238access discriminants. It is often a good idea to combine this restriction 13239with No_Secondary_Stack. 13240 13241@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions 13242@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{209} 13243@subsection No_Entry_Queue 13244 13245 13246@geindex No_Entry_Queue 13247 13248[GNAT] This restriction is a declaration that any protected entry compiled in 13249the scope of the restriction has at most one task waiting on the entry 13250at any one time, and so no queue is required. This restriction is not 13251checked at compile time. A program execution is erroneous if an attempt 13252is made to queue a second task on such an entry. 13253 13254@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions 13255@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{20a} 13256@subsection No_Implementation_Aspect_Specifications 13257 13258 13259@geindex No_Implementation_Aspect_Specifications 13260 13261[RM 13.12.1] This restriction checks at compile time that no 13262GNAT-defined aspects are present. With this restriction, the only 13263aspects that can be used are those defined in the Ada Reference Manual. 13264 13265@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions 13266@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{20b} 13267@subsection No_Implementation_Attributes 13268 13269 13270@geindex No_Implementation_Attributes 13271 13272[RM 13.12.1] This restriction checks at compile time that no 13273GNAT-defined attributes are present. With this restriction, the only 13274attributes that can be used are those defined in the Ada Reference 13275Manual. 13276 13277@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions 13278@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{20c} 13279@subsection No_Implementation_Identifiers 13280 13281 13282@geindex No_Implementation_Identifiers 13283 13284[RM 13.12.1] This restriction checks at compile time that no 13285implementation-defined identifiers (marked with pragma Implementation_Defined) 13286occur within language-defined packages. 13287 13288@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions 13289@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{20d} 13290@subsection No_Implementation_Pragmas 13291 13292 13293@geindex No_Implementation_Pragmas 13294 13295[RM 13.12.1] This restriction checks at compile time that no 13296GNAT-defined pragmas are present. With this restriction, the only 13297pragmas that can be used are those defined in the Ada Reference Manual. 13298 13299@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions 13300@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{20e} 13301@subsection No_Implementation_Restrictions 13302 13303 13304@geindex No_Implementation_Restrictions 13305 13306[GNAT] This restriction checks at compile time that no GNAT-defined restriction 13307identifiers (other than @code{No_Implementation_Restrictions} itself) 13308are present. With this restriction, the only other restriction identifiers 13309that can be used are those defined in the Ada Reference Manual. 13310 13311@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions 13312@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{20f} 13313@subsection No_Implementation_Units 13314 13315 13316@geindex No_Implementation_Units 13317 13318[RM 13.12.1] This restriction checks at compile time that there is no 13319mention in the context clause of any implementation-defined descendants 13320of packages Ada, Interfaces, or System. 13321 13322@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions 13323@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{210} 13324@subsection No_Implicit_Aliasing 13325 13326 13327@geindex No_Implicit_Aliasing 13328 13329[GNAT] This restriction, which is not required to be partition-wide consistent, 13330requires an explicit aliased keyword for an object to which 'Access, 13331'Unchecked_Access, or 'Address is applied, and forbids entirely the use of 13332the 'Unrestricted_Access attribute for objects. Note: the reason that 13333Unrestricted_Access is forbidden is that it would require the prefix 13334to be aliased, and in such cases, it can always be replaced by 13335the standard attribute Unchecked_Access which is preferable. 13336 13337@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions 13338@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{211} 13339@subsection No_Implicit_Loops 13340 13341 13342@geindex No_Implicit_Loops 13343 13344[GNAT] This restriction ensures that the generated code of the unit marked 13345with this restriction does not contain any implicit @code{for} loops, either by 13346modifying the generated code where possible, or by rejecting any construct 13347that would otherwise generate an implicit @code{for} loop. If this restriction is 13348active, it is possible to build large array aggregates with all static 13349components without generating an intermediate temporary, and without generating 13350a loop to initialize individual components. Otherwise, a loop is created for 13351arrays larger than about 5000 scalar components. Note that if this restriction 13352is set in the spec of a package, it will not apply to its body. 13353 13354@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions 13355@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{212} 13356@subsection No_Obsolescent_Features 13357 13358 13359@geindex No_Obsolescent_Features 13360 13361[RM 13.12.1] This restriction checks at compile time that no obsolescent 13362features are used, as defined in Annex J of the Ada Reference Manual. 13363 13364@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions 13365@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{213} 13366@subsection No_Wide_Characters 13367 13368 13369@geindex No_Wide_Characters 13370 13371[GNAT] This restriction ensures at compile time that no uses of the types 13372@code{Wide_Character} or @code{Wide_String} or corresponding wide 13373wide types 13374appear, and that no wide or wide wide string or character literals 13375appear in the program (that is literals representing characters not in 13376type @code{Character}). 13377 13378@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions 13379@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{214} 13380@subsection Static_Dispatch_Tables 13381 13382 13383@geindex Static_Dispatch_Tables 13384 13385[GNAT] This restriction checks at compile time that all the artifacts 13386associated with dispatch tables can be placed in read-only memory. 13387 13388@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions 13389@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{215} 13390@subsection SPARK_05 13391 13392 13393@geindex SPARK_05 13394 13395[GNAT] This restriction no longer has any effect and is superseded by 13396SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that 13397a codebase respects SPARK 2014 restrictions, mark the code with pragma or 13398aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as 13399follows: 13400 13401@example 13402gnatprove -P project.gpr --mode=stone 13403@end example 13404 13405or equivalently: 13406 13407@example 13408gnatprove -P project.gpr --mode=check_all 13409@end example 13410 13411@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top 13412@anchor{gnat_rm/implementation_advice doc}@anchor{216}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}@anchor{gnat_rm/implementation_advice id1}@anchor{217} 13413@chapter Implementation Advice 13414 13415 13416The main text of the Ada Reference Manual describes the required 13417behavior of all Ada compilers, and the GNAT compiler conforms to 13418these requirements. 13419 13420In addition, there are sections throughout the Ada Reference Manual headed 13421by the phrase 'Implementation advice'. These sections are not normative, 13422i.e., they do not specify requirements that all compilers must 13423follow. Rather they provide advice on generally desirable behavior. 13424They are not requirements, because they describe behavior that cannot 13425be provided on all systems, or may be undesirable on some systems. 13426 13427As far as practical, GNAT follows the implementation advice in 13428the Ada Reference Manual. Each such RM section corresponds to a section 13429in this chapter whose title specifies the 13430RM section number and paragraph number and the subject of 13431the advice. The contents of each section consists of the RM text within 13432quotation marks, 13433followed by the GNAT interpretation of the advice. Most often, this simply says 13434'followed', which means that GNAT follows the advice. However, in a 13435number of cases, GNAT deliberately deviates from this advice, in which 13436case the text describes what GNAT does and why. 13437 13438@geindex Error detection 13439 13440@menu 13441* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. 13442* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. 13443* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. 13444* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. 13445* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. 13446* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. 13447* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. 13448* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. 13449* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. 13450* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. 13451* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. 13452* RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small. 13453* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. 13454* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. 13455* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. 13456* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. 13457* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. 13458* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. 13459* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. 13460* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. 13461* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. 13462* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. 13463* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. 13464* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. 13465* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. 13466* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. 13467* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. 13468* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. 13469* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. 13470* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. 13471* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. 13472* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. 13473* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. 13474* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. 13475* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. 13476* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. 13477* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. 13478* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. 13479* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. 13480* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. 13481* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. 13482* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. 13483* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. 13484* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. 13485* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. 13486* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. 13487* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. 13488* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. 13489* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. 13490* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. 13491* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. 13492* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. 13493* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. 13494* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. 13495* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. 13496* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. 13497* RM F(7); COBOL Support: RM F 7 COBOL Support. 13498* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. 13499* RM G; Numerics: RM G Numerics. 13500* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. 13501* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. 13502* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. 13503* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. 13504* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. 13505 13506@end menu 13507 13508@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice 13509@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{218} 13510@section RM 1.1.3(20): Error Detection 13511 13512 13513@quotation 13514 13515"If an implementation detects the use of an unsupported Specialized Needs 13516Annex feature at run time, it should raise @code{Program_Error} if 13517feasible." 13518@end quotation 13519 13520Not relevant. All specialized needs annex features are either supported, 13521or diagnosed at compile time. 13522 13523@geindex Child Units 13524 13525@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice 13526@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{219} 13527@section RM 1.1.3(31): Child Units 13528 13529 13530@quotation 13531 13532"If an implementation wishes to provide implementation-defined 13533extensions to the functionality of a language-defined library unit, it 13534should normally do so by adding children to the library unit." 13535@end quotation 13536 13537Followed. 13538 13539@geindex Bounded errors 13540 13541@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice 13542@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{21a} 13543@section RM 1.1.5(12): Bounded Errors 13544 13545 13546@quotation 13547 13548"If an implementation detects a bounded error or erroneous 13549execution, it should raise @code{Program_Error}." 13550@end quotation 13551 13552Followed in all cases in which the implementation detects a bounded 13553error or erroneous execution. Not all such situations are detected at 13554runtime. 13555 13556@geindex Pragmas 13557 13558@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice 13559@anchor{gnat_rm/implementation_advice id2}@anchor{21b}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21c} 13560@section RM 2.8(16): Pragmas 13561 13562 13563@quotation 13564 13565"Normally, implementation-defined pragmas should have no semantic effect 13566for error-free programs; that is, if the implementation-defined pragmas 13567are removed from a working program, the program should still be legal, 13568and should still have the same semantics." 13569@end quotation 13570 13571The following implementation defined pragmas are exceptions to this 13572rule: 13573 13574 13575@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} 13576@headitem 13577 13578Pragma 13579 13580@tab 13581 13582Explanation 13583 13584@item 13585 13586@emph{Abort_Defer} 13587 13588@tab 13589 13590Affects semantics 13591 13592@item 13593 13594@emph{Ada_83} 13595 13596@tab 13597 13598Affects legality 13599 13600@item 13601 13602@emph{Assert} 13603 13604@tab 13605 13606Affects semantics 13607 13608@item 13609 13610@emph{CPP_Class} 13611 13612@tab 13613 13614Affects semantics 13615 13616@item 13617 13618@emph{CPP_Constructor} 13619 13620@tab 13621 13622Affects semantics 13623 13624@item 13625 13626@emph{Debug} 13627 13628@tab 13629 13630Affects semantics 13631 13632@item 13633 13634@emph{Interface_Name} 13635 13636@tab 13637 13638Affects semantics 13639 13640@item 13641 13642@emph{Machine_Attribute} 13643 13644@tab 13645 13646Affects semantics 13647 13648@item 13649 13650@emph{Unimplemented_Unit} 13651 13652@tab 13653 13654Affects legality 13655 13656@item 13657 13658@emph{Unchecked_Union} 13659 13660@tab 13661 13662Affects semantics 13663 13664@end multitable 13665 13666 13667In each of the above cases, it is essential to the purpose of the pragma 13668that this advice not be followed. For details see 13669@ref{7,,Implementation Defined Pragmas}. 13670 13671@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice 13672@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{21d} 13673@section RM 2.8(17-19): Pragmas 13674 13675 13676@quotation 13677 13678"Normally, an implementation should not define pragmas that can 13679make an illegal program legal, except as follows: 13680 13681 13682@itemize * 13683 13684@item 13685A pragma used to complete a declaration, such as a pragma @code{Import}; 13686 13687@item 13688A pragma used to configure the environment by adding, removing, or 13689replacing @code{library_items}." 13690@end itemize 13691@end quotation 13692 13693See @ref{21c,,RM 2.8(16); Pragmas}. 13694 13695@geindex Character Sets 13696 13697@geindex Alternative Character Sets 13698 13699@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice 13700@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{21e} 13701@section RM 3.5.2(5): Alternative Character Sets 13702 13703 13704@quotation 13705 13706"If an implementation supports a mode with alternative interpretations 13707for @code{Character} and @code{Wide_Character}, the set of graphic 13708characters of @code{Character} should nevertheless remain a proper 13709subset of the set of graphic characters of @code{Wide_Character}. Any 13710character set 'localizations' should be reflected in the results of 13711the subprograms defined in the language-defined package 13712@code{Characters.Handling} (see A.3) available in such a mode. In a mode with 13713an alternative interpretation of @code{Character}, the implementation should 13714also support a corresponding change in what is a legal 13715@code{identifier_letter}." 13716@end quotation 13717 13718Not all wide character modes follow this advice, in particular the JIS 13719and IEC modes reflect standard usage in Japan, and in these encoding, 13720the upper half of the Latin-1 set is not part of the wide-character 13721subset, since the most significant bit is used for wide character 13722encoding. However, this only applies to the external forms. Internally 13723there is no such restriction. 13724 13725@geindex Integer types 13726 13727@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 13728@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{21f} 13729@section RM 3.5.4(28): Integer Types 13730 13731 13732@quotation 13733 13734"An implementation should support @code{Long_Integer} in addition to 13735@code{Integer} if the target machine supports 32-bit (or longer) 13736arithmetic. No other named integer subtypes are recommended for package 13737@code{Standard}. Instead, appropriate named integer subtypes should be 13738provided in the library package @code{Interfaces} (see B.2)." 13739@end quotation 13740 13741@code{Long_Integer} is supported. Other standard integer types are supported 13742so this advice is not fully followed. These types 13743are supported for convenient interface to C, and so that all hardware 13744types of the machine are easily available. 13745 13746@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice 13747@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{220} 13748@section RM 3.5.4(29): Integer Types 13749 13750 13751@quotation 13752 13753"An implementation for a two's complement machine should support 13754modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 13755implementation should support a non-binary modules up to @code{Integer'Last}." 13756@end quotation 13757 13758Followed. 13759 13760@geindex Enumeration values 13761 13762@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice 13763@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{221} 13764@section RM 3.5.5(8): Enumeration Values 13765 13766 13767@quotation 13768 13769"For the evaluation of a call on @code{S'Pos} for an enumeration 13770subtype, if the value of the operand does not correspond to the internal 13771code for any enumeration literal of its type (perhaps due to an 13772un-initialized variable), then the implementation should raise 13773@code{Program_Error}. This is particularly important for enumeration 13774types with noncontiguous internal codes specified by an 13775enumeration_representation_clause." 13776@end quotation 13777 13778Followed. 13779 13780@geindex Float types 13781 13782@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice 13783@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{222} 13784@section RM 3.5.7(17): Float Types 13785 13786 13787@quotation 13788 13789"An implementation should support @code{Long_Float} in addition to 13790@code{Float} if the target machine supports 11 or more digits of 13791precision. No other named floating point subtypes are recommended for 13792package @code{Standard}. Instead, appropriate named floating point subtypes 13793should be provided in the library package @code{Interfaces} (see B.2)." 13794@end quotation 13795 13796@code{Short_Float} and @code{Long_Long_Float} are also provided. The 13797former provides improved compatibility with other implementations 13798supporting this type. The latter corresponds to the highest precision 13799floating-point type supported by the hardware. On most machines, this 13800will be the same as @code{Long_Float}, but on some machines, it will 13801correspond to the IEEE extended form. The notable case is all x86 13802implementations, where @code{Long_Long_Float} corresponds to the 80-bit 13803extended precision format supported in hardware on this processor. 13804Note that the 128-bit format on SPARC is not supported, since this 13805is a software rather than a hardware format. 13806 13807@geindex Multidimensional arrays 13808 13809@geindex Arrays 13810@geindex multidimensional 13811 13812@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration'Small,RM 3 5 7 17 Float Types,Implementation Advice 13813@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{223} 13814@section RM 3.6.2(11): Multidimensional Arrays 13815 13816 13817@quotation 13818 13819"An implementation should normally represent multidimensional arrays in 13820row-major order, consistent with the notation used for multidimensional 13821array aggregates (see 4.3.3). However, if a pragma @code{Convention} 13822(@code{Fortran}, ...) applies to a multidimensional array type, then 13823column-major order should be used instead (see B.5, @emph{Interfacing with Fortran})." 13824@end quotation 13825 13826Followed. 13827 13828@geindex Duration'Small 13829 13830@node RM 9 6 30-31 Duration'Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice 13831@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{224} 13832@section RM 9.6(30-31): Duration'Small 13833 13834 13835@quotation 13836 13837"Whenever possible in an implementation, the value of @code{Duration'Small} 13838should be no greater than 100 microseconds." 13839@end quotation 13840 13841Followed. (@code{Duration'Small} = 10**(-9)). 13842 13843@quotation 13844 13845"The time base for @code{delay_relative_statements} should be monotonic; 13846it need not be the same time base as used for @code{Calendar.Clock}." 13847@end quotation 13848 13849Followed. 13850 13851@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration'Small,Implementation Advice 13852@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{225} 13853@section RM 10.2.1(12): Consistent Representation 13854 13855 13856@quotation 13857 13858"In an implementation, a type declared in a pre-elaborated package should 13859have the same representation in every elaboration of a given version of 13860the package, whether the elaborations occur in distinct executions of 13861the same program, or in executions of distinct programs or partitions 13862that include the given version." 13863@end quotation 13864 13865Followed, except in the case of tagged types. Tagged types involve 13866implicit pointers to a local copy of a dispatch table, and these pointers 13867have representations which thus depend on a particular elaboration of the 13868package. It is not easy to see how it would be possible to follow this 13869advice without severely impacting efficiency of execution. 13870 13871@geindex Exception information 13872 13873@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice 13874@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{226} 13875@section RM 11.4.1(19): Exception Information 13876 13877 13878@quotation 13879 13880"@code{Exception_Message} by default and @code{Exception_Information} 13881should produce information useful for 13882debugging. @code{Exception_Message} should be short, about one 13883line. @code{Exception_Information} can be long. @code{Exception_Message} 13884should not include the 13885@code{Exception_Name}. @code{Exception_Information} should include both 13886the @code{Exception_Name} and the @code{Exception_Message}." 13887@end quotation 13888 13889Followed. For each exception that doesn't have a specified 13890@code{Exception_Message}, the compiler generates one containing the location 13891of the raise statement. This location has the form 'file_name:line', where 13892file_name is the short file name (without path information) and line is the line 13893number in the file. Note that in the case of the Zero Cost Exception 13894mechanism, these messages become redundant with the Exception_Information that 13895contains a full backtrace of the calling sequence, so they are disabled. 13896To disable explicitly the generation of the source location message, use the 13897Pragma @code{Discard_Names}. 13898 13899@geindex Suppression of checks 13900 13901@geindex Checks 13902@geindex suppression of 13903 13904@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice 13905@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{227} 13906@section RM 11.5(28): Suppression of Checks 13907 13908 13909@quotation 13910 13911"The implementation should minimize the code executed for checks that 13912have been suppressed." 13913@end quotation 13914 13915Followed. 13916 13917@geindex Representation clauses 13918 13919@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice 13920@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{228} 13921@section RM 13.1 (21-24): Representation Clauses 13922 13923 13924@quotation 13925 13926"The recommended level of support for all representation items is 13927qualified as follows: 13928 13929An implementation need not support representation items containing 13930nonstatic expressions, except that an implementation should support a 13931representation item for a given entity if each nonstatic expression in 13932the representation item is a name that statically denotes a constant 13933declared before the entity." 13934@end quotation 13935 13936Followed. In fact, GNAT goes beyond the recommended level of support 13937by allowing nonstatic expressions in some representation clauses even 13938without the need to declare constants initialized with the values of 13939such expressions. 13940For example: 13941 13942@example 13943 X : Integer; 13944 Y : Float; 13945 for Y'Address use X'Address;>> 13946 13947 13948"An implementation need not support a specification for the `@w{`}Size`@w{`} 13949for a given composite subtype, nor the size or storage place for an 13950object (including a component) of a given composite subtype, unless the 13951constraints on the subtype and its composite subcomponents (if any) are 13952all static constraints." 13953@end example 13954 13955Followed. Size Clauses are not permitted on nonstatic components, as 13956described above. 13957 13958@quotation 13959 13960"An aliased component, or a component whose type is by-reference, should 13961always be allocated at an addressable location." 13962@end quotation 13963 13964Followed. 13965 13966@geindex Packed types 13967 13968@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice 13969@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{229} 13970@section RM 13.2(6-8): Packed Types 13971 13972 13973@quotation 13974 13975"If a type is packed, then the implementation should try to minimize 13976storage allocated to objects of the type, possibly at the expense of 13977speed of accessing components, subject to reasonable complexity in 13978addressing calculations. 13979 13980The recommended level of support pragma @code{Pack} is: 13981 13982For a packed record type, the components should be packed as tightly as 13983possible subject to the Sizes of the component subtypes, and subject to 13984any @emph{record_representation_clause} that applies to the type; the 13985implementation may, but need not, reorder components or cross aligned 13986word boundaries to improve the packing. A component whose @code{Size} is 13987greater than the word size may be allocated an integral number of words." 13988@end quotation 13989 13990Followed. Tight packing of arrays is supported for all component sizes 13991up to 64-bits. If the array component size is 1 (that is to say, if 13992the component is a boolean type or an enumeration type with two values) 13993then values of the type are implicitly initialized to zero. This 13994happens both for objects of the packed type, and for objects that have a 13995subcomponent of the packed type. 13996 13997@quotation 13998 13999"An implementation should support Address clauses for imported 14000subprograms." 14001@end quotation 14002 14003Followed. 14004 14005@geindex Address clauses 14006 14007@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice 14008@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{22a} 14009@section RM 13.3(14-19): Address Clauses 14010 14011 14012@quotation 14013 14014"For an array @code{X}, @code{X'Address} should point at the first 14015component of the array, and not at the array bounds." 14016@end quotation 14017 14018Followed. 14019 14020@quotation 14021 14022"The recommended level of support for the @code{Address} attribute is: 14023 14024@code{X'Address} should produce a useful result if @code{X} is an 14025object that is aliased or of a by-reference type, or is an entity whose 14026@code{Address} has been specified." 14027@end quotation 14028 14029Followed. A valid address will be produced even if none of those 14030conditions have been met. If necessary, the object is forced into 14031memory to ensure the address is valid. 14032 14033@quotation 14034 14035"An implementation should support @code{Address} clauses for imported 14036subprograms." 14037@end quotation 14038 14039Followed. 14040 14041@quotation 14042 14043"Objects (including subcomponents) that are aliased or of a by-reference 14044type should be allocated on storage element boundaries." 14045@end quotation 14046 14047Followed. 14048 14049@quotation 14050 14051"If the @code{Address} of an object is specified, or it is imported or exported, 14052then the implementation should not perform optimizations based on 14053assumptions of no aliases." 14054@end quotation 14055 14056Followed. 14057 14058@geindex Alignment clauses 14059 14060@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice 14061@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{22b} 14062@section RM 13.3(29-35): Alignment Clauses 14063 14064 14065@quotation 14066 14067"The recommended level of support for the @code{Alignment} attribute for 14068subtypes is: 14069 14070An implementation should support specified Alignments that are factors 14071and multiples of the number of storage elements per word, subject to the 14072following:" 14073@end quotation 14074 14075Followed. 14076 14077@quotation 14078 14079"An implementation need not support specified Alignments for 14080combinations of Sizes and Alignments that cannot be easily 14081loaded and stored by available machine instructions." 14082@end quotation 14083 14084Followed. 14085 14086@quotation 14087 14088"An implementation need not support specified Alignments that are 14089greater than the maximum @code{Alignment} the implementation ever returns by 14090default." 14091@end quotation 14092 14093Followed. 14094 14095@quotation 14096 14097"The recommended level of support for the @code{Alignment} attribute for 14098objects is: 14099 14100Same as above, for subtypes, but in addition:" 14101@end quotation 14102 14103Followed. 14104 14105@quotation 14106 14107"For stand-alone library-level objects of statically constrained 14108subtypes, the implementation should support all alignments 14109supported by the target linker. For example, page alignment is likely to 14110be supported for such objects, but not for subtypes." 14111@end quotation 14112 14113Followed. 14114 14115@geindex Size clauses 14116 14117@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice 14118@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{22c} 14119@section RM 13.3(42-43): Size Clauses 14120 14121 14122@quotation 14123 14124"The recommended level of support for the @code{Size} attribute of 14125objects is: 14126 14127A @code{Size} clause should be supported for an object if the specified 14128@code{Size} is at least as large as its subtype's @code{Size}, and 14129corresponds to a size in storage elements that is a multiple of the 14130object's @code{Alignment} (if the @code{Alignment} is nonzero)." 14131@end quotation 14132 14133Followed. 14134 14135@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 14136@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{22d} 14137@section RM 13.3(50-56): Size Clauses 14138 14139 14140@quotation 14141 14142"If the @code{Size} of a subtype is specified, and allows for efficient 14143independent addressability (see 9.10) on the target architecture, then 14144the @code{Size} of the following objects of the subtype should equal the 14145@code{Size} of the subtype: 14146 14147Aliased objects (including components)." 14148@end quotation 14149 14150Followed. 14151 14152@quotation 14153 14154"@cite{Size} clause on a composite subtype should not affect the 14155internal layout of components." 14156@end quotation 14157 14158Followed. But note that this can be overridden by use of the implementation 14159pragma Implicit_Packing in the case of packed arrays. 14160 14161@quotation 14162 14163"The recommended level of support for the @code{Size} attribute of subtypes is: 14164 14165The @code{Size} (if not specified) of a static discrete or fixed point 14166subtype should be the number of bits needed to represent each value 14167belonging to the subtype using an unbiased representation, leaving space 14168for a sign bit only if the subtype contains negative values. If such a 14169subtype is a first subtype, then an implementation should support a 14170specified @code{Size} for it that reflects this representation." 14171@end quotation 14172 14173Followed. 14174 14175@quotation 14176 14177"For a subtype implemented with levels of indirection, the @code{Size} 14178should include the size of the pointers, but not the size of what they 14179point at." 14180@end quotation 14181 14182Followed. 14183 14184@geindex Component_Size clauses 14185 14186@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 14187@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{22e} 14188@section RM 13.3(71-73): Component Size Clauses 14189 14190 14191@quotation 14192 14193"The recommended level of support for the @code{Component_Size} 14194attribute is: 14195 14196An implementation need not support specified @code{Component_Sizes} that are 14197less than the @code{Size} of the component subtype." 14198@end quotation 14199 14200Followed. 14201 14202@quotation 14203 14204"An implementation should support specified Component_Sizes that 14205are factors and multiples of the word size. For such 14206Component_Sizes, the array should contain no gaps between 14207components. For other Component_Sizes (if supported), the array 14208should contain no gaps between components when packing is also 14209specified; the implementation should forbid this combination in cases 14210where it cannot support a no-gaps representation." 14211@end quotation 14212 14213Followed. 14214 14215@geindex Enumeration representation clauses 14216 14217@geindex Representation clauses 14218@geindex enumeration 14219 14220@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 14221@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{22f} 14222@section RM 13.4(9-10): Enumeration Representation Clauses 14223 14224 14225@quotation 14226 14227"The recommended level of support for enumeration representation clauses 14228is: 14229 14230An implementation need not support enumeration representation clauses 14231for boolean types, but should at minimum support the internal codes in 14232the range @code{System.Min_Int .. System.Max_Int}." 14233@end quotation 14234 14235Followed. 14236 14237@geindex Record representation clauses 14238 14239@geindex Representation clauses 14240@geindex records 14241 14242@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 14243@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{230} 14244@section RM 13.5.1(17-22): Record Representation Clauses 14245 14246 14247@quotation 14248 14249"The recommended level of support for 14250@emph{record_representation_clause}s is: 14251 14252An implementation should support storage places that can be extracted 14253with a load, mask, shift sequence of machine code, and set with a load, 14254shift, mask, store sequence, given the available machine instructions 14255and run-time model." 14256@end quotation 14257 14258Followed. 14259 14260@quotation 14261 14262"A storage place should be supported if its size is equal to the 14263@code{Size} of the component subtype, and it starts and ends on a 14264boundary that obeys the @code{Alignment} of the component subtype." 14265@end quotation 14266 14267Followed. 14268 14269@quotation 14270 14271"If the default bit ordering applies to the declaration of a given type, 14272then for a component whose subtype's @code{Size} is less than the word 14273size, any storage place that does not cross an aligned word boundary 14274should be supported." 14275@end quotation 14276 14277Followed. 14278 14279@quotation 14280 14281"An implementation may reserve a storage place for the tag field of a 14282tagged type, and disallow other components from overlapping that place." 14283@end quotation 14284 14285Followed. The storage place for the tag field is the beginning of the tagged 14286record, and its size is Address'Size. GNAT will reject an explicit component 14287clause for the tag field. 14288 14289@quotation 14290 14291"An implementation need not support a @emph{component_clause} for a 14292component of an extension part if the storage place is not after the 14293storage places of all components of the parent type, whether or not 14294those storage places had been specified." 14295@end quotation 14296 14297Followed. The above advice on record representation clauses is followed, 14298and all mentioned features are implemented. 14299 14300@geindex Storage place attributes 14301 14302@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 14303@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{231} 14304@section RM 13.5.2(5): Storage Place Attributes 14305 14306 14307@quotation 14308 14309"If a component is represented using some form of pointer (such as an 14310offset) to the actual data of the component, and this data is contiguous 14311with the rest of the object, then the storage place attributes should 14312reflect the place of the actual data, not the pointer. If a component is 14313allocated discontinuously from the rest of the object, then a warning 14314should be generated upon reference to one of its storage place 14315attributes." 14316@end quotation 14317 14318Followed. There are no such components in GNAT. 14319 14320@geindex Bit ordering 14321 14322@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 14323@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{232} 14324@section RM 13.5.3(7-8): Bit Ordering 14325 14326 14327@quotation 14328 14329"The recommended level of support for the non-default bit ordering is: 14330 14331If @code{Word_Size} = @code{Storage_Unit}, then the implementation 14332should support the non-default bit ordering in addition to the default 14333bit ordering." 14334@end quotation 14335 14336Followed. Word size does not equal storage size in this implementation. 14337Thus non-default bit ordering is not supported. 14338 14339@geindex Address 14340@geindex as private type 14341 14342@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 14343@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{233} 14344@section RM 13.7(37): Address as Private 14345 14346 14347@quotation 14348 14349"@cite{Address} should be of a private type." 14350@end quotation 14351 14352Followed. 14353 14354@geindex Operations 14355@geindex on `@w{`}Address`@w{`} 14356 14357@geindex Address 14358@geindex operations of 14359 14360@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice 14361@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{234} 14362@section RM 13.7.1(16): Address Operations 14363 14364 14365@quotation 14366 14367"Operations in @code{System} and its children should reflect the target 14368environment semantics as closely as is reasonable. For example, on most 14369machines, it makes sense for address arithmetic to 'wrap around'. 14370Operations that do not make sense should raise @code{Program_Error}." 14371@end quotation 14372 14373Followed. Address arithmetic is modular arithmetic that wraps around. No 14374operation raises @code{Program_Error}, since all operations make sense. 14375 14376@geindex Unchecked conversion 14377 14378@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 14379@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{235} 14380@section RM 13.9(14-17): Unchecked Conversion 14381 14382 14383@quotation 14384 14385"The @code{Size} of an array object should not include its bounds; hence, 14386the bounds should not be part of the converted data." 14387@end quotation 14388 14389Followed. 14390 14391@quotation 14392 14393"The implementation should not generate unnecessary run-time checks to 14394ensure that the representation of @code{S} is a representation of the 14395target type. It should take advantage of the permission to return by 14396reference when possible. Restrictions on unchecked conversions should be 14397avoided unless required by the target environment." 14398@end quotation 14399 14400Followed. There are no restrictions on unchecked conversion. A warning is 14401generated if the source and target types do not have the same size since 14402the semantics in this case may be target dependent. 14403 14404@quotation 14405 14406"The recommended level of support for unchecked conversions is: 14407 14408Unchecked conversions should be supported and should be reversible in 14409the cases where this clause defines the result. To enable meaningful use 14410of unchecked conversion, a contiguous representation should be used for 14411elementary subtypes, for statically constrained array subtypes whose 14412component subtype is one of the subtypes described in this paragraph, 14413and for record subtypes without discriminants whose component subtypes 14414are described in this paragraph." 14415@end quotation 14416 14417Followed. 14418 14419@geindex Heap usage 14420@geindex implicit 14421 14422@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 14423@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{236} 14424@section RM 13.11(23-25): Implicit Heap Usage 14425 14426 14427@quotation 14428 14429"An implementation should document any cases in which it dynamically 14430allocates heap storage for a purpose other than the evaluation of an 14431allocator." 14432@end quotation 14433 14434Followed, the only other points at which heap storage is dynamically 14435allocated are as follows: 14436 14437 14438@itemize * 14439 14440@item 14441At initial elaboration time, to allocate dynamically sized global 14442objects. 14443 14444@item 14445To allocate space for a task when a task is created. 14446 14447@item 14448To extend the secondary stack dynamically when needed. The secondary 14449stack is used for returning variable length results. 14450@end itemize 14451 14452 14453@quotation 14454 14455"A default (implementation-provided) storage pool for an 14456access-to-constant type should not have overhead to support deallocation of 14457individual objects." 14458@end quotation 14459 14460Followed. 14461 14462@quotation 14463 14464"A storage pool for an anonymous access type should be created at the 14465point of an allocator for the type, and be reclaimed when the designated 14466object becomes inaccessible." 14467@end quotation 14468 14469Followed. 14470 14471@geindex Unchecked deallocation 14472 14473@node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 1 6 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice 14474@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{237} 14475@section RM 13.11.2(17): Unchecked Deallocation 14476 14477 14478@quotation 14479 14480"For a standard storage pool, @code{Free} should actually reclaim the 14481storage." 14482@end quotation 14483 14484Followed. 14485 14486@geindex Stream oriented attributes 14487 14488@node RM 13 13 2 1 6 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice 14489@anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{238} 14490@section RM 13.13.2(1.6): Stream Oriented Attributes 14491 14492 14493@quotation 14494 14495"If not specified, the value of Stream_Size for an elementary type 14496should be the number of bits that corresponds to the minimum number of 14497stream elements required by the first subtype of the type, rounded up 14498to the nearest factor or multiple of the word size that is also a 14499multiple of the stream element size." 14500@end quotation 14501 14502Followed, except that the number of stream elements is 1, 2, 3, 4 or 8. 14503The Stream_Size may be used to override the default choice. 14504 14505The default implementation is based on direct binary representations and is 14506therefore target- and endianness-dependent. To address this issue, GNAT also 14507supplies an alternate implementation of the stream attributes @code{Read} and 14508@code{Write}, which uses the target-independent XDR standard representation for 14509scalar types. This XDR alternative can be enabled via the binder switch -xdr. 14510 14511@geindex XDR representation 14512 14513@geindex Read attribute 14514 14515@geindex Write attribute 14516 14517@geindex Stream oriented attributes 14518 14519@node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 1 6 Stream Oriented Attributes,Implementation Advice 14520@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{239} 14521@section RM A.1(52): Names of Predefined Numeric Types 14522 14523 14524@quotation 14525 14526"If an implementation provides additional named predefined integer types, 14527then the names should end with @code{Integer} as in 14528@code{Long_Integer}. If an implementation provides additional named 14529predefined floating point types, then the names should end with 14530@code{Float} as in @code{Long_Float}." 14531@end quotation 14532 14533Followed. 14534 14535@geindex Ada.Characters.Handling 14536 14537@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 14538@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{23a} 14539@section RM A.3.2(49): @code{Ada.Characters.Handling} 14540 14541 14542@quotation 14543 14544"If an implementation provides a localized definition of @code{Character} 14545or @code{Wide_Character}, then the effects of the subprograms in 14546@code{Characters.Handling} should reflect the localizations. 14547See also 3.5.2." 14548@end quotation 14549 14550Followed. GNAT provides no such localized definitions. 14551 14552@geindex Bounded-length strings 14553 14554@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 14555@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{23b} 14556@section RM A.4.4(106): Bounded-Length String Handling 14557 14558 14559@quotation 14560 14561"Bounded string objects should not be implemented by implicit pointers 14562and dynamic allocation." 14563@end quotation 14564 14565Followed. No implicit pointers or dynamic allocation are used. 14566 14567@geindex Random number generation 14568 14569@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 14570@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{23c} 14571@section RM A.5.2(46-47): Random Number Generation 14572 14573 14574@quotation 14575 14576"Any storage associated with an object of type @code{Generator} should be 14577reclaimed on exit from the scope of the object." 14578@end quotation 14579 14580Followed. 14581 14582@quotation 14583 14584"If the generator period is sufficiently long in relation to the number 14585of distinct initiator values, then each possible value of 14586@code{Initiator} passed to @code{Reset} should initiate a sequence of 14587random numbers that does not, in a practical sense, overlap the sequence 14588initiated by any other value. If this is not possible, then the mapping 14589between initiator values and generator states should be a rapidly 14590varying function of the initiator value." 14591@end quotation 14592 14593Followed. The generator period is sufficiently long for the first 14594condition here to hold true. 14595 14596@geindex Get_Immediate 14597 14598@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 14599@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23d} 14600@section RM A.10.7(23): @code{Get_Immediate} 14601 14602 14603@quotation 14604 14605"The @code{Get_Immediate} procedures should be implemented with 14606unbuffered input. For a device such as a keyboard, input should be 14607available if a key has already been typed, whereas for a disk 14608file, input should always be available except at end of file. For a file 14609associated with a keyboard-like device, any line-editing features of the 14610underlying operating system should be disabled during the execution of 14611@code{Get_Immediate}." 14612@end quotation 14613 14614Followed on all targets except VxWorks. For VxWorks, there is no way to 14615provide this functionality that does not result in the input buffer being 14616flushed before the @code{Get_Immediate} call. A special unit 14617@code{Interfaces.Vxworks.IO} is provided that contains routines to enable 14618this functionality. 14619 14620@geindex Export 14621 14622@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 10 7 23 Get_Immediate,Implementation Advice 14623@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23e} 14624@section RM B.1(39-41): Pragma @code{Export} 14625 14626 14627@quotation 14628 14629"If an implementation supports pragma @code{Export} to a given language, 14630then it should also allow the main subprogram to be written in that 14631language. It should support some mechanism for invoking the elaboration 14632of the Ada library units included in the system, and for invoking the 14633finalization of the environment task. On typical systems, the 14634recommended mechanism is to provide two subprograms whose link names are 14635@code{adainit} and @code{adafinal}. @code{adainit} should contain the 14636elaboration code for library units. @code{adafinal} should contain the 14637finalization code. These subprograms should have no effect the second 14638and subsequent time they are called." 14639@end quotation 14640 14641Followed. 14642 14643@quotation 14644 14645"Automatic elaboration of pre-elaborated packages should be 14646provided when pragma @code{Export} is supported." 14647@end quotation 14648 14649Followed when the main program is in Ada. If the main program is in a 14650foreign language, then 14651@code{adainit} must be called to elaborate pre-elaborated 14652packages. 14653 14654@quotation 14655 14656"For each supported convention @emph{L} other than @code{Intrinsic}, an 14657implementation should support @code{Import} and @code{Export} pragmas 14658for objects of @emph{L}-compatible types and for subprograms, and pragma 14659@cite{Convention} for @emph{L}-eligible types and for subprograms, 14660presuming the other language has corresponding features. Pragma 14661@code{Convention} need not be supported for scalar types." 14662@end quotation 14663 14664Followed. 14665 14666@geindex Package Interfaces 14667 14668@geindex Interfaces 14669 14670@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 14671@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{23f} 14672@section RM B.2(12-13): Package @code{Interfaces} 14673 14674 14675@quotation 14676 14677"For each implementation-defined convention identifier, there should be a 14678child package of package Interfaces with the corresponding name. This 14679package should contain any declarations that would be useful for 14680interfacing to the language (implementation) represented by the 14681convention. Any declarations useful for interfacing to any language on 14682the given hardware architecture should be provided directly in 14683@code{Interfaces}." 14684@end quotation 14685 14686Followed. 14687 14688@quotation 14689 14690"An implementation supporting an interface to C, COBOL, or Fortran should 14691provide the corresponding package or packages described in the following 14692clauses." 14693@end quotation 14694 14695Followed. GNAT provides all the packages described in this section. 14696 14697@geindex C 14698@geindex interfacing with 14699 14700@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 14701@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{240} 14702@section RM B.3(63-71): Interfacing with C 14703 14704 14705@quotation 14706 14707"An implementation should support the following interface correspondences 14708between Ada and C." 14709@end quotation 14710 14711Followed. 14712 14713@quotation 14714 14715"An Ada procedure corresponds to a void-returning C function." 14716@end quotation 14717 14718Followed. 14719 14720@quotation 14721 14722"An Ada function corresponds to a non-void C function." 14723@end quotation 14724 14725Followed. 14726 14727@quotation 14728 14729"An Ada @code{in} scalar parameter is passed as a scalar argument to a C 14730function." 14731@end quotation 14732 14733Followed. 14734 14735@quotation 14736 14737"An Ada @code{in} parameter of an access-to-object type with designated 14738type @code{T} is passed as a @code{t*} argument to a C function, 14739where @code{t} is the C type corresponding to the Ada type @code{T}." 14740@end quotation 14741 14742Followed. 14743 14744@quotation 14745 14746"An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} 14747parameter of an elementary type @code{T}, is passed as a @code{t*} 14748argument to a C function, where @code{t} is the C type corresponding to 14749the Ada type @code{T}. In the case of an elementary @code{out} or 14750@code{in out} parameter, a pointer to a temporary copy is used to 14751preserve by-copy semantics." 14752@end quotation 14753 14754Followed. 14755 14756@quotation 14757 14758"An Ada parameter of a record type @code{T}, of any mode, is passed as a 14759@code{t*} argument to a C function, where @code{t} is the C 14760structure corresponding to the Ada type @code{T}." 14761@end quotation 14762 14763Followed. This convention may be overridden by the use of the C_Pass_By_Copy 14764pragma, or Convention, or by explicitly specifying the mechanism for a given 14765call using an extended import or export pragma. 14766 14767@quotation 14768 14769"An Ada parameter of an array type with component type @code{T}, of any 14770mode, is passed as a @code{t*} argument to a C function, where 14771@code{t} is the C type corresponding to the Ada type @code{T}." 14772@end quotation 14773 14774Followed. 14775 14776@quotation 14777 14778"An Ada parameter of an access-to-subprogram type is passed as a pointer 14779to a C function whose prototype corresponds to the designated 14780subprogram's specification." 14781@end quotation 14782 14783Followed. 14784 14785@geindex COBOL 14786@geindex interfacing with 14787 14788@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 14789@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{241} 14790@section RM B.4(95-98): Interfacing with COBOL 14791 14792 14793@quotation 14794 14795"An Ada implementation should support the following interface 14796correspondences between Ada and COBOL." 14797@end quotation 14798 14799Followed. 14800 14801@quotation 14802 14803"An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of 14804the COBOL type corresponding to @code{T}." 14805@end quotation 14806 14807Followed. 14808 14809@quotation 14810 14811"An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of 14812the corresponding COBOL type." 14813@end quotation 14814 14815Followed. 14816 14817@quotation 14818 14819"Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the 14820COBOL type corresponding to the Ada parameter type; for scalars, a local 14821copy is used if necessary to ensure by-copy semantics." 14822@end quotation 14823 14824Followed. 14825 14826@geindex Fortran 14827@geindex interfacing with 14828 14829@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 14830@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{242} 14831@section RM B.5(22-26): Interfacing with Fortran 14832 14833 14834@quotation 14835 14836"An Ada implementation should support the following interface 14837correspondences between Ada and Fortran:" 14838@end quotation 14839 14840Followed. 14841 14842@quotation 14843 14844"An Ada procedure corresponds to a Fortran subroutine." 14845@end quotation 14846 14847Followed. 14848 14849@quotation 14850 14851"An Ada function corresponds to a Fortran function." 14852@end quotation 14853 14854Followed. 14855 14856@quotation 14857 14858"An Ada parameter of an elementary, array, or record type @code{T} is 14859passed as a @code{T} argument to a Fortran procedure, where @code{T} is 14860the Fortran type corresponding to the Ada type @code{T}, and where the 14861INTENT attribute of the corresponding dummy argument matches the Ada 14862formal parameter mode; the Fortran implementation's parameter passing 14863conventions are used. For elementary types, a local copy is used if 14864necessary to ensure by-copy semantics." 14865@end quotation 14866 14867Followed. 14868 14869@quotation 14870 14871"An Ada parameter of an access-to-subprogram type is passed as a 14872reference to a Fortran procedure whose interface corresponds to the 14873designated subprogram's specification." 14874@end quotation 14875 14876Followed. 14877 14878@geindex Machine operations 14879 14880@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 14881@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{243} 14882@section RM C.1(3-5): Access to Machine Operations 14883 14884 14885@quotation 14886 14887"The machine code or intrinsic support should allow access to all 14888operations normally available to assembly language programmers for the 14889target environment, including privileged instructions, if any." 14890@end quotation 14891 14892Followed. 14893 14894@quotation 14895 14896"The interfacing pragmas (see Annex B) should support interface to 14897assembler; the default assembler should be associated with the 14898convention identifier @code{Assembler}." 14899@end quotation 14900 14901Followed. 14902 14903@quotation 14904 14905"If an entity is exported to assembly language, then the implementation 14906should allocate it at an addressable location, and should ensure that it 14907is retained by the linking process, even if not otherwise referenced 14908from the Ada code. The implementation should assume that any call to a 14909machine code or assembler subprogram is allowed to read or update every 14910object that is specified as exported." 14911@end quotation 14912 14913Followed. 14914 14915@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 14916@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{244} 14917@section RM C.1(10-16): Access to Machine Operations 14918 14919 14920@quotation 14921 14922"The implementation should ensure that little or no overhead is 14923associated with calling intrinsic and machine-code subprograms." 14924@end quotation 14925 14926Followed for both intrinsics and machine-code subprograms. 14927 14928@quotation 14929 14930"It is recommended that intrinsic subprograms be provided for convenient 14931access to any machine operations that provide special capabilities or 14932efficiency and that are not otherwise available through the language 14933constructs." 14934@end quotation 14935 14936Followed. A full set of machine operation intrinsic subprograms is provided. 14937 14938@quotation 14939 14940"Atomic read-modify-write operations---e.g., test and set, compare and 14941swap, decrement and test, enqueue/dequeue." 14942@end quotation 14943 14944Followed on any target supporting such operations. 14945 14946@quotation 14947 14948"Standard numeric functions---e.g.:, sin, log." 14949@end quotation 14950 14951Followed on any target supporting such operations. 14952 14953@quotation 14954 14955"String manipulation operations---e.g.:, translate and test." 14956@end quotation 14957 14958Followed on any target supporting such operations. 14959 14960@quotation 14961 14962"Vector operations---e.g.:, compare vector against thresholds." 14963@end quotation 14964 14965Followed on any target supporting such operations. 14966 14967@quotation 14968 14969"Direct operations on I/O ports." 14970@end quotation 14971 14972Followed on any target supporting such operations. 14973 14974@geindex Interrupt support 14975 14976@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 14977@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{245} 14978@section RM C.3(28): Interrupt Support 14979 14980 14981@quotation 14982 14983"If the @code{Ceiling_Locking} policy is not in effect, the 14984implementation should provide means for the application to specify which 14985interrupts are to be blocked during protected actions, if the underlying 14986system allows for a finer-grain control of interrupt blocking." 14987@end quotation 14988 14989Followed. The underlying system does not allow for finer-grain control 14990of interrupt blocking. 14991 14992@geindex Protected procedure handlers 14993 14994@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 14995@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{246} 14996@section RM C.3.1(20-21): Protected Procedure Handlers 14997 14998 14999@quotation 15000 15001"Whenever possible, the implementation should allow interrupt handlers to 15002be called directly by the hardware." 15003@end quotation 15004 15005Followed on any target where the underlying operating system permits 15006such direct calls. 15007 15008@quotation 15009 15010"Whenever practical, violations of any 15011implementation-defined restrictions should be detected before run time." 15012@end quotation 15013 15014Followed. Compile time warnings are given when possible. 15015 15016@geindex Package `@w{`}Interrupts`@w{`} 15017 15018@geindex Interrupts 15019 15020@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 15021@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{247} 15022@section RM C.3.2(25): Package @code{Interrupts} 15023 15024 15025@quotation 15026 15027"If implementation-defined forms of interrupt handler procedures are 15028supported, such as protected procedures with parameters, then for each 15029such form of a handler, a type analogous to @code{Parameterless_Handler} 15030should be specified in a child package of @code{Interrupts}, with the 15031same operations as in the predefined package Interrupts." 15032@end quotation 15033 15034Followed. 15035 15036@geindex Pre-elaboration requirements 15037 15038@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice 15039@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{248} 15040@section RM C.4(14): Pre-elaboration Requirements 15041 15042 15043@quotation 15044 15045"It is recommended that pre-elaborated packages be implemented in such a 15046way that there should be little or no code executed at run time for the 15047elaboration of entities not already covered by the Implementation 15048Requirements." 15049@end quotation 15050 15051Followed. Executable code is generated in some cases, e.g., loops 15052to initialize large arrays. 15053 15054@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 15055@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{249} 15056@section RM C.5(8): Pragma @code{Discard_Names} 15057 15058 15059@quotation 15060 15061"If the pragma applies to an entity, then the implementation should 15062reduce the amount of storage used for storing names associated with that 15063entity." 15064@end quotation 15065 15066Followed. 15067 15068@geindex Package Task_Attributes 15069 15070@geindex Task_Attributes 15071 15072@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 15073@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{24a} 15074@section RM C.7.2(30): The Package Task_Attributes 15075 15076 15077@quotation 15078 15079"Some implementations are targeted to domains in which memory use at run 15080time must be completely deterministic. For such implementations, it is 15081recommended that the storage for task attributes will be pre-allocated 15082statically and not from the heap. This can be accomplished by either 15083placing restrictions on the number and the size of the task's 15084attributes, or by using the pre-allocated storage for the first @code{N} 15085attribute objects, and the heap for the others. In the latter case, 15086@code{N} should be documented." 15087@end quotation 15088 15089Not followed. This implementation is not targeted to such a domain. 15090 15091@geindex Locking Policies 15092 15093@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 15094@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{24b} 15095@section RM D.3(17): Locking Policies 15096 15097 15098@quotation 15099 15100"The implementation should use names that end with @code{_Locking} for 15101locking policies defined by the implementation." 15102@end quotation 15103 15104Followed. Two implementation-defined locking policies are defined, 15105whose names (@code{Inheritance_Locking} and 15106@code{Concurrent_Readers_Locking}) follow this suggestion. 15107 15108@geindex Entry queuing policies 15109 15110@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice 15111@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{24c} 15112@section RM D.4(16): Entry Queuing Policies 15113 15114 15115@quotation 15116 15117"Names that end with @code{_Queuing} should be used 15118for all implementation-defined queuing policies." 15119@end quotation 15120 15121Followed. No such implementation-defined queuing policies exist. 15122 15123@geindex Preemptive abort 15124 15125@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice 15126@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{24d} 15127@section RM D.6(9-10): Preemptive Abort 15128 15129 15130@quotation 15131 15132"Even though the @emph{abort_statement} is included in the list of 15133potentially blocking operations (see 9.5.1), it is recommended that this 15134statement be implemented in a way that never requires the task executing 15135the @emph{abort_statement} to block." 15136@end quotation 15137 15138Followed. 15139 15140@quotation 15141 15142"On a multi-processor, the delay associated with aborting a task on 15143another processor should be bounded; the implementation should use 15144periodic polling, if necessary, to achieve this." 15145@end quotation 15146 15147Followed. 15148 15149@geindex Tasking restrictions 15150 15151@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice 15152@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{24e} 15153@section RM D.7(21): Tasking Restrictions 15154 15155 15156@quotation 15157 15158"When feasible, the implementation should take advantage of the specified 15159restrictions to produce a more efficient implementation." 15160@end quotation 15161 15162GNAT currently takes advantage of these restrictions by providing an optimized 15163run time when the Ravenscar profile and the GNAT restricted run time set 15164of restrictions are specified. See pragma @code{Profile (Ravenscar)} and 15165pragma @code{Profile (Restricted)} for more details. 15166 15167@geindex Time 15168@geindex monotonic 15169 15170@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice 15171@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{24f} 15172@section RM D.8(47-49): Monotonic Time 15173 15174 15175@quotation 15176 15177"When appropriate, implementations should provide configuration 15178mechanisms to change the value of @code{Tick}." 15179@end quotation 15180 15181Such configuration mechanisms are not appropriate to this implementation 15182and are thus not supported. 15183 15184@quotation 15185 15186"It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} 15187be implemented as transformations of the same time base." 15188@end quotation 15189 15190Followed. 15191 15192@quotation 15193 15194"It is recommended that the best time base which exists in 15195the underlying system be available to the application through 15196@code{Clock}. @cite{Best} may mean highest accuracy or largest range." 15197@end quotation 15198 15199Followed. 15200 15201@geindex Partition communication subsystem 15202 15203@geindex PCS 15204 15205@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice 15206@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{250} 15207@section RM E.5(28-29): Partition Communication Subsystem 15208 15209 15210@quotation 15211 15212"Whenever possible, the PCS on the called partition should allow for 15213multiple tasks to call the RPC-receiver with different messages and 15214should allow them to block until the corresponding subprogram body 15215returns." 15216@end quotation 15217 15218Followed by GLADE, a separately supplied PCS that can be used with 15219GNAT. 15220 15221@quotation 15222 15223"The @code{Write} operation on a stream of type @code{Params_Stream_Type} 15224should raise @code{Storage_Error} if it runs out of space trying to 15225write the @code{Item} into the stream." 15226@end quotation 15227 15228Followed by GLADE, a separately supplied PCS that can be used with 15229GNAT. 15230 15231@geindex COBOL support 15232 15233@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice 15234@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{251} 15235@section RM F(7): COBOL Support 15236 15237 15238@quotation 15239 15240"If COBOL (respectively, C) is widely supported in the target 15241environment, implementations supporting the Information Systems Annex 15242should provide the child package @code{Interfaces.COBOL} (respectively, 15243@code{Interfaces.C}) specified in Annex B and should support a 15244@code{convention_identifier} of COBOL (respectively, C) in the interfacing 15245pragmas (see Annex B), thus allowing Ada programs to interface with 15246programs written in that language." 15247@end quotation 15248 15249Followed. 15250 15251@geindex Decimal radix support 15252 15253@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice 15254@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{252} 15255@section RM F.1(2): Decimal Radix Support 15256 15257 15258@quotation 15259 15260"Packed decimal should be used as the internal representation for objects 15261of subtype @code{S} when @code{S}'Machine_Radix = 10." 15262@end quotation 15263 15264Not followed. GNAT ignores @code{S}'Machine_Radix and always uses binary 15265representations. 15266 15267@geindex Numerics 15268 15269@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice 15270@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{253} 15271@section RM G: Numerics 15272 15273 15274@quotation 15275 15276"If Fortran (respectively, C) is widely supported in the target 15277environment, implementations supporting the Numerics Annex 15278should provide the child package @code{Interfaces.Fortran} (respectively, 15279@code{Interfaces.C}) specified in Annex B and should support a 15280@code{convention_identifier} of Fortran (respectively, C) in the interfacing 15281pragmas (see Annex B), thus allowing Ada programs to interface with 15282programs written in that language." 15283@end quotation 15284 15285Followed. 15286 15287@geindex Complex types 15288 15289@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice 15290@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{254} 15291@section RM G.1.1(56-58): Complex Types 15292 15293 15294@quotation 15295 15296"Because the usual mathematical meaning of multiplication of a complex 15297operand and a real operand is that of the scaling of both components of 15298the former by the latter, an implementation should not perform this 15299operation by first promoting the real operand to complex type and then 15300performing a full complex multiplication. In systems that, in the 15301future, support an Ada binding to IEC 559:1989, the latter technique 15302will not generate the required result when one of the components of the 15303complex operand is infinite. (Explicit multiplication of the infinite 15304component by the zero component obtained during promotion yields a NaN 15305that propagates into the final result.) Analogous advice applies in the 15306case of multiplication of a complex operand and a pure-imaginary 15307operand, and in the case of division of a complex operand by a real or 15308pure-imaginary operand." 15309@end quotation 15310 15311Not followed. 15312 15313@quotation 15314 15315"Similarly, because the usual mathematical meaning of addition of a 15316complex operand and a real operand is that the imaginary operand remains 15317unchanged, an implementation should not perform this operation by first 15318promoting the real operand to complex type and then performing a full 15319complex addition. In implementations in which the @code{Signed_Zeros} 15320attribute of the component type is @code{True} (and which therefore 15321conform to IEC 559:1989 in regard to the handling of the sign of zero in 15322predefined arithmetic operations), the latter technique will not 15323generate the required result when the imaginary component of the complex 15324operand is a negatively signed zero. (Explicit addition of the negative 15325zero to the zero obtained during promotion yields a positive zero.) 15326Analogous advice applies in the case of addition of a complex operand 15327and a pure-imaginary operand, and in the case of subtraction of a 15328complex operand and a real or pure-imaginary operand." 15329@end quotation 15330 15331Not followed. 15332 15333@quotation 15334 15335"Implementations in which @code{Real'Signed_Zeros} is @code{True} should 15336attempt to provide a rational treatment of the signs of zero results and 15337result components. As one example, the result of the @code{Argument} 15338function should have the sign of the imaginary component of the 15339parameter @code{X} when the point represented by that parameter lies on 15340the positive real axis; as another, the sign of the imaginary component 15341of the @code{Compose_From_Polar} function should be the same as 15342(respectively, the opposite of) that of the @code{Argument} parameter when that 15343parameter has a value of zero and the @code{Modulus} parameter has a 15344nonnegative (respectively, negative) value." 15345@end quotation 15346 15347Followed. 15348 15349@geindex Complex elementary functions 15350 15351@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 15352@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{255} 15353@section RM G.1.2(49): Complex Elementary Functions 15354 15355 15356@quotation 15357 15358"Implementations in which @code{Complex_Types.Real'Signed_Zeros} is 15359@code{True} should attempt to provide a rational treatment of the signs 15360of zero results and result components. For example, many of the complex 15361elementary functions have components that are odd functions of one of 15362the parameter components; in these cases, the result component should 15363have the sign of the parameter component at the origin. Other complex 15364elementary functions have zero components whose sign is opposite that of 15365a parameter component at the origin, or is always positive or always 15366negative." 15367@end quotation 15368 15369Followed. 15370 15371@geindex Accuracy requirements 15372 15373@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 15374@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{256} 15375@section RM G.2.4(19): Accuracy Requirements 15376 15377 15378@quotation 15379 15380"The versions of the forward trigonometric functions without a 15381@code{Cycle} parameter should not be implemented by calling the 15382corresponding version with a @code{Cycle} parameter of 15383@code{2.0*Numerics.Pi}, since this will not provide the required 15384accuracy in some portions of the domain. For the same reason, the 15385version of @code{Log} without a @code{Base} parameter should not be 15386implemented by calling the corresponding version with a @code{Base} 15387parameter of @code{Numerics.e}." 15388@end quotation 15389 15390Followed. 15391 15392@geindex Complex arithmetic accuracy 15393 15394@geindex Accuracy 15395@geindex complex arithmetic 15396 15397@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 15398@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{257} 15399@section RM G.2.6(15): Complex Arithmetic Accuracy 15400 15401 15402@quotation 15403 15404"The version of the @code{Compose_From_Polar} function without a 15405@code{Cycle} parameter should not be implemented by calling the 15406corresponding version with a @code{Cycle} parameter of 15407@code{2.0*Numerics.Pi}, since this will not provide the required 15408accuracy in some portions of the domain." 15409@end quotation 15410 15411Followed. 15412 15413@geindex Sequential elaboration policy 15414 15415@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice 15416@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{258} 15417@section RM H.6(15/2): Pragma Partition_Elaboration_Policy 15418 15419 15420@quotation 15421 15422"If the partition elaboration policy is @code{Sequential} and the 15423Environment task becomes permanently blocked during elaboration then the 15424partition is deadlocked and it is recommended that the partition be 15425immediately terminated." 15426@end quotation 15427 15428Not followed. 15429 15430@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top 15431@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{259}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{25a} 15432@chapter Implementation Defined Characteristics 15433 15434 15435In addition to the implementation dependent pragmas and attributes, and the 15436implementation advice, there are a number of other Ada features that are 15437potentially implementation dependent and are designated as 15438implementation-defined. These are mentioned throughout the Ada Reference 15439Manual, and are summarized in Annex M. 15440 15441A requirement for conforming Ada compilers is that they provide 15442documentation describing how the implementation deals with each of these 15443issues. In this chapter you will find each point in Annex M listed, 15444followed by a description of how GNAT handles the implementation dependence. 15445 15446You can use this chapter as a guide to minimizing implementation 15447dependent features in your programs if portability to other compilers 15448and other operating systems is an important consideration. The numbers 15449in each entry below correspond to the paragraph numbers in the Ada 15450Reference Manual. 15451 15452 15453@itemize * 15454 15455@item 15456"Whether or not each recommendation given in Implementation 15457Advice is followed. See 1.1.2(37)." 15458@end itemize 15459 15460See @ref{a,,Implementation Advice}. 15461 15462 15463@itemize * 15464 15465@item 15466"Capacity limitations of the implementation. See 1.1.3(3)." 15467@end itemize 15468 15469The complexity of programs that can be processed is limited only by the 15470total amount of available virtual memory, and disk space for the 15471generated object files. 15472 15473 15474@itemize * 15475 15476@item 15477"Variations from the standard that are impractical to avoid 15478given the implementation's execution environment. See 1.1.3(6)." 15479@end itemize 15480 15481There are no variations from the standard. 15482 15483 15484@itemize * 15485 15486@item 15487"Which code_statements cause external 15488interactions. See 1.1.3(10)." 15489@end itemize 15490 15491Any @emph{code_statement} can potentially cause external interactions. 15492 15493 15494@itemize * 15495 15496@item 15497"The coded representation for the text of an Ada 15498program. See 2.1(4)." 15499@end itemize 15500 15501See separate section on source representation. 15502 15503 15504@itemize * 15505 15506@item 15507"The control functions allowed in comments. See 2.1(14)." 15508@end itemize 15509 15510See separate section on source representation. 15511 15512 15513@itemize * 15514 15515@item 15516"The representation for an end of line. See 2.2(2)." 15517@end itemize 15518 15519See separate section on source representation. 15520 15521 15522@itemize * 15523 15524@item 15525"Maximum supported line length and lexical element 15526length. See 2.2(15)." 15527@end itemize 15528 15529The maximum line length is 255 characters and the maximum length of 15530a lexical element is also 255 characters. This is the default setting 15531if not overridden by the use of compiler switch @emph{-gnaty} (which 15532sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum 15533line length to be specified to be any value up to 32767. The maximum 15534length of a lexical element is the same as the maximum line length. 15535 15536 15537@itemize * 15538 15539@item 15540"Implementation defined pragmas. See 2.8(14)." 15541@end itemize 15542 15543See @ref{7,,Implementation Defined Pragmas}. 15544 15545 15546@itemize * 15547 15548@item 15549"Effect of pragma @code{Optimize}. See 2.8(27)." 15550@end itemize 15551 15552Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} 15553parameter, checks that the optimization flag is set, and aborts if it is 15554not. 15555 15556 15557@itemize * 15558 15559@item 15560"The sequence of characters of the value returned by 15561@code{S'Image} when some of the graphic characters of 15562@code{S'Wide_Image} are not defined in @code{Character}. See 155633.5(37)." 15564@end itemize 15565 15566The sequence of characters is as defined by the wide character encoding 15567method used for the source. See section on source representation for 15568further details. 15569 15570 15571@itemize * 15572 15573@item 15574"The predefined integer types declared in 15575@code{Standard}. See 3.5.4(25)." 15576@end itemize 15577 15578 15579@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15580@headitem 15581 15582Type 15583 15584@tab 15585 15586Representation 15587 15588@item 15589 15590@emph{Short_Short_Integer} 15591 15592@tab 15593 155948-bit signed 15595 15596@item 15597 15598@emph{Short_Integer} 15599 15600@tab 15601 1560216-bit signed 15603 15604@item 15605 15606@emph{Integer} 15607 15608@tab 15609 1561032-bit signed 15611 15612@item 15613 15614@emph{Long_Integer} 15615 15616@tab 15617 1561864-bit signed (on most 64-bit targets, 15619depending on the C definition of long) 1562032-bit signed (on all other targets) 15621 15622@item 15623 15624@emph{Long_Long_Integer} 15625 15626@tab 15627 1562864-bit signed 15629 15630@item 15631 15632@emph{Long_Long_Long_Integer} 15633 15634@tab 15635 15636128-bit signed (on 64-bit targets) 1563764-bit signed (on 32-bit targets) 15638 15639@end multitable 15640 15641 15642 15643@itemize * 15644 15645@item 15646"Any nonstandard integer types and the operators defined 15647for them. See 3.5.4(26)." 15648@end itemize 15649 15650There are no nonstandard integer types. 15651 15652 15653@itemize * 15654 15655@item 15656"Any nonstandard real types and the operators defined for 15657them. See 3.5.6(8)." 15658@end itemize 15659 15660There are no nonstandard real types. 15661 15662 15663@itemize * 15664 15665@item 15666"What combinations of requested decimal precision and range 15667are supported for floating point types. See 3.5.7(7)." 15668@end itemize 15669 15670The precision and range is as defined by the IEEE standard. 15671 15672 15673@itemize * 15674 15675@item 15676"The predefined floating point types declared in 15677@code{Standard}. See 3.5.7(16)." 15678@end itemize 15679 15680 15681@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 15682@headitem 15683 15684Type 15685 15686@tab 15687 15688Representation 15689 15690@item 15691 15692@emph{Short_Float} 15693 15694@tab 15695 1569632 bit IEEE short 15697 15698@item 15699 15700@emph{Float} 15701 15702@tab 15703 15704(Short) 32 bit IEEE short 15705 15706@item 15707 15708@emph{Long_Float} 15709 15710@tab 15711 1571264 bit IEEE long 15713 15714@item 15715 15716@emph{Long_Long_Float} 15717 15718@tab 15719 1572064 bit IEEE long (80 bit IEEE long on x86 processors) 15721 15722@end multitable 15723 15724 15725 15726@itemize * 15727 15728@item 15729"The small of an ordinary fixed point type. See 3.5.9(8)." 15730@end itemize 15731 15732The small is the largest power of two that does not exceed the delta. 15733 15734 15735@itemize * 15736 15737@item 15738"What combinations of small, range, and digits are 15739supported for fixed point types. See 3.5.9(10)." 15740@end itemize 15741 15742For an ordinary fixed point type, on 32-bit platforms, the small must lie in 157432.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination 15744is permitted that does not result in a mantissa larger than 63 bits. 15745 15746On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the 15747range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not 15748result in a mantissa larger than 63 bits, and any combination is permitted 15749that results in a mantissa between 64 and 127 bits if the small is the 15750ratio of two integers that lie in 1 .. 2.0**127. 15751 15752If the small is the ratio of two integers with 64-bit magnitude on 32-bit 15753platforms and 128-bit magnitude on 64-bit platforms, which is the case if 15754no @code{small} clause is provided, then the operations of the fixed point 15755type are entirely implemented by means of integer instructions. In the 15756other cases, some operations, in particular input and output, may be 15757implemented by means of floating-point instructions and may be affected 15758by accuracy issues on architectures other than x86. 15759 15760For a decimal fixed point type, on 32-bit platforms, the small must lie in 157611.0E-18 .. 1.0E+18 and the digits in 1 .. 18. On 64-bit platforms, the 15762small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38. 15763 15764 15765@itemize * 15766 15767@item 15768"The result of @code{Tags.Expanded_Name} for types declared 15769within an unnamed @emph{block_statement}. See 3.9(10)." 15770@end itemize 15771 15772Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a 15773decimal integer are allocated. 15774 15775 15776@itemize * 15777 15778@item 15779"Implementation-defined attributes. See 4.1.4(12)." 15780@end itemize 15781 15782See @ref{8,,Implementation Defined Attributes}. 15783 15784 15785@itemize * 15786 15787@item 15788"Any implementation-defined time types. See 9.6(6)." 15789@end itemize 15790 15791There are no implementation-defined time types. 15792 15793 15794@itemize * 15795 15796@item 15797"The time base associated with relative delays." 15798@end itemize 15799 15800See 9.6(20). The time base used is that provided by the C library 15801function @code{gettimeofday}. 15802 15803 15804@itemize * 15805 15806@item 15807"The time base of the type @code{Calendar.Time}. See 158089.6(23)." 15809@end itemize 15810 15811The time base used is that provided by the C library function 15812@code{gettimeofday}. 15813 15814 15815@itemize * 15816 15817@item 15818"The time zone used for package @code{Calendar} 15819operations. See 9.6(24)." 15820@end itemize 15821 15822The time zone used by package @code{Calendar} is the current system time zone 15823setting for local time, as accessed by the C library function 15824@code{localtime}. 15825 15826 15827@itemize * 15828 15829@item 15830"Any limit on @emph{delay_until_statements} of 15831@emph{select_statements}. See 9.6(29)." 15832@end itemize 15833 15834There are no such limits. 15835 15836 15837@itemize * 15838 15839@item 15840"Whether or not two non-overlapping parts of a composite 15841object are independently addressable, in the case where packing, record 15842layout, or @code{Component_Size} is specified for the object. See 158439.10(1)." 15844@end itemize 15845 15846Separate components are independently addressable if they do not share 15847overlapping storage units. 15848 15849 15850@itemize * 15851 15852@item 15853"The representation for a compilation. See 10.1(2)." 15854@end itemize 15855 15856A compilation is represented by a sequence of files presented to the 15857compiler in a single invocation of the @emph{gcc} command. 15858 15859 15860@itemize * 15861 15862@item 15863"Any restrictions on compilations that contain multiple 15864compilation_units. See 10.1(4)." 15865@end itemize 15866 15867No single file can contain more than one compilation unit, but any 15868sequence of files can be presented to the compiler as a single 15869compilation. 15870 15871 15872@itemize * 15873 15874@item 15875"The mechanisms for creating an environment and for adding 15876and replacing compilation units. See 10.1.4(3)." 15877@end itemize 15878 15879See separate section on compilation model. 15880 15881 15882@itemize * 15883 15884@item 15885"The manner of explicitly assigning library units to a 15886partition. See 10.2(2)." 15887@end itemize 15888 15889If a unit contains an Ada main program, then the Ada units for the partition 15890are determined by recursive application of the rules in the Ada Reference 15891Manual section 10.2(2-6). In other words, the Ada units will be those that 15892are needed by the main program, and then this definition of need is applied 15893recursively to those units, and the partition contains the transitive 15894closure determined by this relationship. In short, all the necessary units 15895are included, with no need to explicitly specify the list. If additional 15896units are required, e.g., by foreign language units, then all units must be 15897mentioned in the context clause of one of the needed Ada units. 15898 15899If the partition contains no main program, or if the main program is in 15900a language other than Ada, then GNAT 15901provides the binder options @emph{-z} and @emph{-n} respectively, and in 15902this case a list of units can be explicitly supplied to the binder for 15903inclusion in the partition (all units needed by these units will also 15904be included automatically). For full details on the use of these 15905options, refer to @emph{GNAT Make Program gnatmake} in the 15906@cite{GNAT User's Guide}. 15907 15908 15909@itemize * 15910 15911@item 15912"The implementation-defined means, if any, of specifying 15913which compilation units are needed by a given compilation unit. See 1591410.2(2)." 15915@end itemize 15916 15917The units needed by a given compilation unit are as defined in 15918the Ada Reference Manual section 10.2(2-6). There are no 15919implementation-defined pragmas or other implementation-defined 15920means for specifying needed units. 15921 15922 15923@itemize * 15924 15925@item 15926"The manner of designating the main subprogram of a 15927partition. See 10.2(7)." 15928@end itemize 15929 15930The main program is designated by providing the name of the 15931corresponding @code{ALI} file as the input parameter to the binder. 15932 15933 15934@itemize * 15935 15936@item 15937"The order of elaboration of @emph{library_items}. See 1593810.2(18)." 15939@end itemize 15940 15941The first constraint on ordering is that it meets the requirements of 15942Chapter 10 of the Ada Reference Manual. This still leaves some 15943implementation dependent choices, which are resolved by first 15944elaborating bodies as early as possible (i.e., in preference to specs 15945where there is a choice), and second by evaluating the immediate with 15946clauses of a unit to determine the probably best choice, and 15947third by elaborating in alphabetical order of unit names 15948where a choice still remains. 15949 15950 15951@itemize * 15952 15953@item 15954"Parameter passing and function return for the main 15955subprogram. See 10.2(21)." 15956@end itemize 15957 15958The main program has no parameters. It may be a procedure, or a function 15959returning an integer type. In the latter case, the returned integer 15960value is the return code of the program (overriding any value that 15961may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). 15962 15963 15964@itemize * 15965 15966@item 15967"The mechanisms for building and running partitions. See 1596810.2(24)." 15969@end itemize 15970 15971GNAT itself supports programs with only a single partition. The GNATDIST 15972tool provided with the GLADE package (which also includes an implementation 15973of the PCS) provides a completely flexible method for building and running 15974programs consisting of multiple partitions. See the separate GLADE manual 15975for details. 15976 15977 15978@itemize * 15979 15980@item 15981"The details of program execution, including program 15982termination. See 10.2(25)." 15983@end itemize 15984 15985See separate section on compilation model. 15986 15987 15988@itemize * 15989 15990@item 15991"The semantics of any non-active partitions supported by the 15992implementation. See 10.2(28)." 15993@end itemize 15994 15995Passive partitions are supported on targets where shared memory is 15996provided by the operating system. See the GLADE reference manual for 15997further details. 15998 15999 16000@itemize * 16001 16002@item 16003"The information returned by @code{Exception_Message}. See 1600411.4.1(10)." 16005@end itemize 16006 16007Exception message returns the null string unless a specific message has 16008been passed by the program. 16009 16010 16011@itemize * 16012 16013@item 16014"The result of @code{Exceptions.Exception_Name} for types 16015declared within an unnamed @emph{block_statement}. See 11.4.1(12)." 16016@end itemize 16017 16018Blocks have implementation defined names of the form @code{B@emph{nnn}} 16019where @emph{nnn} is an integer. 16020 16021 16022@itemize * 16023 16024@item 16025"The information returned by 16026@code{Exception_Information}. See 11.4.1(13)." 16027@end itemize 16028 16029@code{Exception_Information} returns a string in the following format: 16030 16031@example 16032*Exception_Name:* nnnnn 16033*Message:* mmmmm 16034*PID:* ppp 16035*Load address:* 0xhhhh 16036*Call stack traceback locations:* 160370xhhhh 0xhhhh 0xhhhh ... 0xhhh 16038@end example 16039 16040where 16041 16042@quotation 16043 16044 16045@itemize * 16046 16047@item 16048@code{nnnn} is the fully qualified name of the exception in all upper 16049case letters. This line is always present. 16050 16051@item 16052@code{mmmm} is the message (this line present only if message is non-null) 16053 16054@item 16055@code{ppp} is the Process Id value as a decimal integer (this line is 16056present only if the Process Id is nonzero). Currently we are 16057not making use of this field. 16058 16059@item 16060The Load address line, the Call stack traceback locations line and the 16061following values are present only if at least one traceback location was 16062recorded. The Load address indicates the address at which the main executable 16063was loaded; this line may not be present if operating system hasn't relocated 16064the main executable. The values are given in C style format, with lower case 16065letters for a-f, and only as many digits present as are necessary. 16066The line terminator sequence at the end of each line, including 16067the last line is a single @code{LF} character (@code{16#0A#}). 16068@end itemize 16069@end quotation 16070 16071 16072@itemize * 16073 16074@item 16075"Implementation-defined check names. See 11.5(27)." 16076@end itemize 16077 16078The implementation defined check names include Alignment_Check, 16079Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, 16080Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user 16081program can add implementation-defined check names by means of the pragma 16082Check_Name. See the description of pragma @code{Suppress} for full details. 16083 16084 16085@itemize * 16086 16087@item 16088"The interpretation of each aspect of representation. See 1608913.1(20)." 16090@end itemize 16091 16092See separate section on data representations. 16093 16094 16095@itemize * 16096 16097@item 16098"Any restrictions placed upon representation items. See 1609913.1(20)." 16100@end itemize 16101 16102See separate section on data representations. 16103 16104 16105@itemize * 16106 16107@item 16108"The meaning of @code{Size} for indefinite subtypes. See 1610913.3(48)." 16110@end itemize 16111 16112Size for an indefinite subtype is the maximum possible size, except that 16113for the case of a subprogram parameter, the size of the parameter object 16114is the actual size. 16115 16116 16117@itemize * 16118 16119@item 16120"The default external representation for a type tag. See 1612113.3(75)." 16122@end itemize 16123 16124The default external representation for a type tag is the fully expanded 16125name of the type in upper case letters. 16126 16127 16128@itemize * 16129 16130@item 16131"What determines whether a compilation unit is the same in 16132two different partitions. See 13.3(76)." 16133@end itemize 16134 16135A compilation unit is the same in two different partitions if and only 16136if it derives from the same source file. 16137 16138 16139@itemize * 16140 16141@item 16142"Implementation-defined components. See 13.5.1(15)." 16143@end itemize 16144 16145The only implementation defined component is the tag for a tagged type, 16146which contains a pointer to the dispatching table. 16147 16148 16149@itemize * 16150 16151@item 16152"If @code{Word_Size} = @code{Storage_Unit}, the default bit 16153ordering. See 13.5.3(5)." 16154@end itemize 16155 16156@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this 16157implementation, so no non-default bit ordering is supported. The default 16158bit ordering corresponds to the natural endianness of the target architecture. 16159 16160 16161@itemize * 16162 16163@item 16164"The contents of the visible part of package @code{System} 16165and its language-defined children. See 13.7(2)." 16166@end itemize 16167 16168See the definition of these packages in files @code{system.ads} and 16169@code{s-stoele.ads}. Note that two declarations are added to package 16170System. 16171 16172@example 16173Max_Priority : constant Positive := Priority'Last; 16174Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; 16175@end example 16176 16177 16178@itemize * 16179 16180@item 16181"The contents of the visible part of package 16182@code{System.Machine_Code}, and the meaning of 16183@emph{code_statements}. See 13.8(7)." 16184@end itemize 16185 16186See the definition and documentation in file @code{s-maccod.ads}. 16187 16188 16189@itemize * 16190 16191@item 16192"The effect of unchecked conversion. See 13.9(11)." 16193@end itemize 16194 16195Unchecked conversion between types of the same size 16196results in an uninterpreted transmission of the bits from one type 16197to the other. If the types are of unequal sizes, then in the case of 16198discrete types, a shorter source is first zero or sign extended as 16199necessary, and a shorter target is simply truncated on the left. 16200For all non-discrete types, the source is first copied if necessary 16201to ensure that the alignment requirements of the target are met, then 16202a pointer is constructed to the source value, and the result is obtained 16203by dereferencing this pointer after converting it to be a pointer to the 16204target type. Unchecked conversions where the target subtype is an 16205unconstrained array are not permitted. If the target alignment is 16206greater than the source alignment, then a copy of the result is 16207made with appropriate alignment 16208 16209 16210@itemize * 16211 16212@item 16213"The semantics of operations on invalid representations. 16214See 13.9.2(10-11)." 16215@end itemize 16216 16217For assignments and other operations where the use of invalid values cannot 16218result in erroneous behavior, the compiler ignores the possibility of invalid 16219values. An exception is raised at the point where an invalid value would 16220result in erroneous behavior. For example executing: 16221 16222@example 16223procedure invalidvals is 16224 X : Integer := -1; 16225 Y : Natural range 1 .. 10; 16226 for Y'Address use X'Address; 16227 Z : Natural range 1 .. 10; 16228 A : array (Natural range 1 .. 10) of Integer; 16229begin 16230 Z := Y; -- no exception 16231 A (Z) := 3; -- exception raised; 16232end; 16233@end example 16234 16235As indicated, an exception is raised on the array assignment, but not 16236on the simple assignment of the invalid negative value from Y to Z. 16237 16238 16239@itemize * 16240 16241@item 16242"The manner of choosing a storage pool for an access type 16243when @code{Storage_Pool} is not specified for the type. See 13.11(17)." 16244@end itemize 16245 16246There are 3 different standard pools used by the compiler when 16247@code{Storage_Pool} is not specified depending whether the type is local 16248to a subprogram or defined at the library level and whether 16249@code{Storage_Size`@w{`}is specified or not. See documentation in the runtime 16250library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and 16251@code{System.Pool_Local} in files @code{s-poosiz.ads}, 16252@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the 16253default pools used. 16254 16255 16256@itemize * 16257 16258@item 16259"Whether or not the implementation provides user-accessible 16260names for the standard pool type(s). See 13.11(17)." 16261@end itemize 16262 16263See documentation in the sources of the run time mentioned in the previous 16264paragraph. All these pools are accessible by means of @cite{with}ing 16265these units. 16266 16267 16268@itemize * 16269 16270@item 16271"The meaning of @code{Storage_Size}. See 13.11(18)." 16272@end itemize 16273 16274@code{Storage_Size} is measured in storage units, and refers to the 16275total space available for an access type collection, or to the primary 16276stack space for a task. 16277 16278 16279@itemize * 16280 16281@item 16282"Implementation-defined aspects of storage pools. See 1628313.11(22)." 16284@end itemize 16285 16286See documentation in the sources of the run time mentioned in the 16287paragraph about standard storage pools above 16288for details on GNAT-defined aspects of storage pools. 16289 16290 16291@itemize * 16292 16293@item 16294"The set of restrictions allowed in a pragma 16295@code{Restrictions}. See 13.12(7)." 16296@end itemize 16297 16298See @ref{9,,Standard and Implementation Defined Restrictions}. 16299 16300 16301@itemize * 16302 16303@item 16304"The consequences of violating limitations on 16305@code{Restrictions} pragmas. See 13.12(9)." 16306@end itemize 16307 16308Restrictions that can be checked at compile time result in illegalities 16309if violated. Currently there are no other consequences of violating 16310restrictions. 16311 16312 16313@itemize * 16314 16315@item 16316"The representation used by the @code{Read} and 16317@code{Write} attributes of elementary types in terms of stream 16318elements. See 13.13.2(9)." 16319@end itemize 16320 16321The representation is the in-memory representation of the base type of 16322the type, using the number of bits corresponding to the 16323@code{type'Size} value, and the natural ordering of the machine. 16324 16325 16326@itemize * 16327 16328@item 16329"The names and characteristics of the numeric subtypes 16330declared in the visible part of package @code{Standard}. See A.1(3)." 16331@end itemize 16332 16333See items describing the integer and floating-point types supported. 16334 16335 16336@itemize * 16337 16338@item 16339"The string returned by @code{Character_Set_Version}. 16340See A.3.5(3)." 16341@end itemize 16342 16343@code{Ada.Wide_Characters.Handling.Character_Set_Version} returns 16344the string "Unicode 4.0", referring to version 4.0 of the 16345Unicode specification. 16346 16347 16348@itemize * 16349 16350@item 16351"The accuracy actually achieved by the elementary 16352functions. See A.5.1(1)." 16353@end itemize 16354 16355The elementary functions correspond to the functions available in the C 16356library. Only fast math mode is implemented. 16357 16358 16359@itemize * 16360 16361@item 16362"The sign of a zero result from some of the operators or 16363functions in @code{Numerics.Generic_Elementary_Functions}, when 16364@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46)." 16365@end itemize 16366 16367The sign of zeroes follows the requirements of the IEEE 754 standard on 16368floating-point. 16369 16370 16371@itemize * 16372 16373@item 16374"The value of 16375@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27)." 16376@end itemize 16377 16378Maximum image width is 6864, see library file @code{s-rannum.ads}. 16379 16380 16381@itemize * 16382 16383@item 16384"The value of 16385@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27)." 16386@end itemize 16387 16388Maximum image width is 6864, see library file @code{s-rannum.ads}. 16389 16390 16391@itemize * 16392 16393@item 16394"The algorithms for random number generation. See 16395A.5.2(32)." 16396@end itemize 16397 16398The algorithm is the Mersenne Twister, as documented in the source file 16399@code{s-rannum.adb}. This version of the algorithm has a period of 164002**19937-1. 16401 16402 16403@itemize * 16404 16405@item 16406"The string representation of a random number generator's 16407state. See A.5.2(38)." 16408@end itemize 16409 16410The value returned by the Image function is the concatenation of 16411the fixed-width decimal representations of the 624 32-bit integers 16412of the state vector. 16413 16414 16415@itemize * 16416 16417@item 16418"The minimum time interval between calls to the 16419time-dependent Reset procedure that are guaranteed to initiate different 16420random number sequences. See A.5.2(45)." 16421@end itemize 16422 16423The minimum period between reset calls to guarantee distinct series of 16424random numbers is one microsecond. 16425 16426 16427@itemize * 16428 16429@item 16430"The values of the @code{Model_Mantissa}, 16431@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, 16432@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics 16433Annex is not supported. See A.5.3(72)." 16434@end itemize 16435 16436Run the compiler with @emph{-gnatS} to produce a listing of package 16437@code{Standard}, has the values of all numeric attributes. 16438 16439 16440@itemize * 16441 16442@item 16443"Any implementation-defined characteristics of the 16444input-output packages. See A.7(14)." 16445@end itemize 16446 16447There are no special implementation defined characteristics for these 16448packages. 16449 16450 16451@itemize * 16452 16453@item 16454"The value of @code{Buffer_Size} in @code{Storage_IO}. See 16455A.9(10)." 16456@end itemize 16457 16458All type representations are contiguous, and the @code{Buffer_Size} is 16459the value of @code{type'Size} rounded up to the next storage unit 16460boundary. 16461 16462 16463@itemize * 16464 16465@item 16466"External files for standard input, standard output, and 16467standard error See A.10(5)." 16468@end itemize 16469 16470These files are mapped onto the files provided by the C streams 16471libraries. See source file @code{i-cstrea.ads} for further details. 16472 16473 16474@itemize * 16475 16476@item 16477"The accuracy of the value produced by @code{Put}. See 16478A.10.9(36)." 16479@end itemize 16480 16481If more digits are requested in the output than are represented by the 16482precision of the value, zeroes are output in the corresponding least 16483significant digit positions. 16484 16485 16486@itemize * 16487 16488@item 16489"The meaning of @code{Argument_Count}, @code{Argument}, and 16490@code{Command_Name}. See A.15(1)." 16491@end itemize 16492 16493These are mapped onto the @code{argv} and @code{argc} parameters of the 16494main program in the natural manner. 16495 16496 16497@itemize * 16498 16499@item 16500"The interpretation of the @code{Form} parameter in procedure 16501@code{Create_Directory}. See A.16(56)." 16502@end itemize 16503 16504The @code{Form} parameter is not used. 16505 16506 16507@itemize * 16508 16509@item 16510"The interpretation of the @code{Form} parameter in procedure 16511@code{Create_Path}. See A.16(60)." 16512@end itemize 16513 16514The @code{Form} parameter is not used. 16515 16516 16517@itemize * 16518 16519@item 16520"The interpretation of the @code{Form} parameter in procedure 16521@code{Copy_File}. See A.16(68)." 16522@end itemize 16523 16524The @code{Form} parameter is case-insensitive. 16525Two fields are recognized in the @code{Form} parameter: 16526 16527@example 16528*preserve=<value>* 16529*mode=<value>* 16530@end example 16531 16532<value> starts immediately after the character '=' and ends with the 16533character immediately preceding the next comma (',') or with the last 16534character of the parameter. 16535 16536The only possible values for preserve= are: 16537 16538 16539@multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16540@headitem 16541 16542Value 16543 16544@tab 16545 16546Meaning 16547 16548@item 16549 16550@emph{no_attributes} 16551 16552@tab 16553 16554Do not try to preserve any file attributes. This is the 16555default if no preserve= is found in Form. 16556 16557@item 16558 16559@emph{all_attributes} 16560 16561@tab 16562 16563Try to preserve all file attributes (timestamps, access rights). 16564 16565@item 16566 16567@emph{timestamps} 16568 16569@tab 16570 16571Preserve the timestamp of the copied file, but not the other 16572file attributes. 16573 16574@end multitable 16575 16576 16577The only possible values for mode= are: 16578 16579 16580@multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16581@headitem 16582 16583Value 16584 16585@tab 16586 16587Meaning 16588 16589@item 16590 16591@emph{copy} 16592 16593@tab 16594 16595Only do the copy if the destination file does not already exist. 16596If it already exists, Copy_File fails. 16597 16598@item 16599 16600@emph{overwrite} 16601 16602@tab 16603 16604Copy the file in all cases. Overwrite an already existing destination file. 16605 16606@item 16607 16608@emph{append} 16609 16610@tab 16611 16612Append the original file to the destination file. If the destination file 16613does not exist, the destination file is a copy of the source file. 16614When mode=append, the field preserve=, if it exists, is not taken into account. 16615 16616@end multitable 16617 16618 16619If the Form parameter includes one or both of the fields and the value or 16620values are incorrect, Copy_file fails with Use_Error. 16621 16622Examples of correct Forms: 16623 16624@example 16625Form => "preserve=no_attributes,mode=overwrite" (the default) 16626Form => "mode=append" 16627Form => "mode=copy, preserve=all_attributes" 16628@end example 16629 16630Examples of incorrect Forms: 16631 16632@example 16633Form => "preserve=junk" 16634Form => "mode=internal, preserve=timestamps" 16635@end example 16636 16637 16638@itemize * 16639 16640@item 16641"The interpretation of the @code{Pattern} parameter, when not the null string, 16642in the @code{Start_Search} and @code{Search} procedures. 16643See A.16(104) and A.16(112)." 16644@end itemize 16645 16646When the @code{Pattern} parameter is not the null string, it is interpreted 16647according to the syntax of regular expressions as defined in the 16648@code{GNAT.Regexp} package. 16649 16650See @ref{25b,,GNAT.Regexp (g-regexp.ads)}. 16651 16652 16653@itemize * 16654 16655@item 16656"Implementation-defined convention names. See B.1(11)." 16657@end itemize 16658 16659The following convention names are supported 16660 16661 16662@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16663@headitem 16664 16665Convention Name 16666 16667@tab 16668 16669Interpretation 16670 16671@item 16672 16673@emph{Ada} 16674 16675@tab 16676 16677Ada 16678 16679@item 16680 16681@emph{Ada_Pass_By_Copy} 16682 16683@tab 16684 16685Allowed for any types except by-reference types such as limited 16686records. Compatible with convention Ada, but causes any parameters 16687with this convention to be passed by copy. 16688 16689@item 16690 16691@emph{Ada_Pass_By_Reference} 16692 16693@tab 16694 16695Allowed for any types except by-copy types such as scalars. 16696Compatible with convention Ada, but causes any parameters 16697with this convention to be passed by reference. 16698 16699@item 16700 16701@emph{Assembler} 16702 16703@tab 16704 16705Assembly language 16706 16707@item 16708 16709@emph{Asm} 16710 16711@tab 16712 16713Synonym for Assembler 16714 16715@item 16716 16717@emph{Assembly} 16718 16719@tab 16720 16721Synonym for Assembler 16722 16723@item 16724 16725@emph{C} 16726 16727@tab 16728 16729C 16730 16731@item 16732 16733@emph{C_Pass_By_Copy} 16734 16735@tab 16736 16737Allowed only for record types, like C, but also notes that record 16738is to be passed by copy rather than reference. 16739 16740@item 16741 16742@emph{COBOL} 16743 16744@tab 16745 16746COBOL 16747 16748@item 16749 16750@emph{C_Plus_Plus (or CPP)} 16751 16752@tab 16753 16754C++ 16755 16756@item 16757 16758@emph{Default} 16759 16760@tab 16761 16762Treated the same as C 16763 16764@item 16765 16766@emph{External} 16767 16768@tab 16769 16770Treated the same as C 16771 16772@item 16773 16774@emph{Fortran} 16775 16776@tab 16777 16778Fortran 16779 16780@item 16781 16782@emph{Intrinsic} 16783 16784@tab 16785 16786For support of pragma @code{Import} with convention Intrinsic, see 16787separate section on Intrinsic Subprograms. 16788 16789@item 16790 16791@emph{Stdcall} 16792 16793@tab 16794 16795Stdcall (used for Windows implementations only). This convention correspond 16796to the WINAPI (previously called Pascal convention) C/C++ convention under 16797Windows. A routine with this convention cleans the stack before 16798exit. This pragma cannot be applied to a dispatching call. 16799 16800@item 16801 16802@emph{DLL} 16803 16804@tab 16805 16806Synonym for Stdcall 16807 16808@item 16809 16810@emph{Win32} 16811 16812@tab 16813 16814Synonym for Stdcall 16815 16816@item 16817 16818@emph{Stubbed} 16819 16820@tab 16821 16822Stubbed is a special convention used to indicate that the body of the 16823subprogram will be entirely ignored. Any call to the subprogram 16824is converted into a raise of the @code{Program_Error} exception. If a 16825pragma @code{Import} specifies convention @code{stubbed} then no body need 16826be present at all. This convention is useful during development for the 16827inclusion of subprograms whose body has not yet been written. 16828In addition, all otherwise unrecognized convention names are also 16829treated as being synonymous with convention C. In all implementations, 16830use of such other names results in a warning. 16831 16832@end multitable 16833 16834 16835 16836@itemize * 16837 16838@item 16839"The meaning of link names. See B.1(36)." 16840@end itemize 16841 16842Link names are the actual names used by the linker. 16843 16844 16845@itemize * 16846 16847@item 16848"The manner of choosing link names when neither the link 16849name nor the address of an imported or exported entity is specified. See 16850B.1(36)." 16851@end itemize 16852 16853The default linker name is that which would be assigned by the relevant 16854external language, interpreting the Ada name as being in all lower case 16855letters. 16856 16857 16858@itemize * 16859 16860@item 16861"The effect of pragma @code{Linker_Options}. See B.1(37)." 16862@end itemize 16863 16864The string passed to @code{Linker_Options} is presented uninterpreted as 16865an argument to the link command, unless it contains ASCII.NUL characters. 16866NUL characters if they appear act as argument separators, so for example 16867 16868@example 16869pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); 16870@end example 16871 16872causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the 16873linker. The order of linker options is preserved for a given unit. The final 16874list of options passed to the linker is in reverse order of the elaboration 16875order. For example, linker options for a body always appear before the options 16876from the corresponding package spec. 16877 16878 16879@itemize * 16880 16881@item 16882"The contents of the visible part of package 16883@code{Interfaces} and its language-defined descendants. See B.2(1)." 16884@end itemize 16885 16886See files with prefix @code{i-} in the distributed library. 16887 16888 16889@itemize * 16890 16891@item 16892"Implementation-defined children of package 16893@code{Interfaces}. The contents of the visible part of package 16894@code{Interfaces}. See B.2(11)." 16895@end itemize 16896 16897See files with prefix @code{i-} in the distributed library. 16898 16899 16900@itemize * 16901 16902@item 16903"The types @code{Floating}, @code{Long_Floating}, 16904@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and 16905@code{COBOL_Character}; and the initialization of the variables 16906@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in 16907@code{Interfaces.COBOL}. See B.4(50)." 16908@end itemize 16909 16910 16911@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 16912@headitem 16913 16914COBOL 16915 16916@tab 16917 16918Ada 16919 16920@item 16921 16922@emph{Floating} 16923 16924@tab 16925 16926Float 16927 16928@item 16929 16930@emph{Long_Floating} 16931 16932@tab 16933 16934(Floating) Long_Float 16935 16936@item 16937 16938@emph{Binary} 16939 16940@tab 16941 16942Integer 16943 16944@item 16945 16946@emph{Long_Binary} 16947 16948@tab 16949 16950Long_Long_Integer 16951 16952@item 16953 16954@emph{Decimal_Element} 16955 16956@tab 16957 16958Character 16959 16960@item 16961 16962@emph{COBOL_Character} 16963 16964@tab 16965 16966Character 16967 16968@end multitable 16969 16970 16971For initialization, see the file @code{i-cobol.ads} in the distributed library. 16972 16973 16974@itemize * 16975 16976@item 16977"Support for access to machine instructions. See C.1(1)." 16978@end itemize 16979 16980See documentation in file @code{s-maccod.ads} in the distributed library. 16981 16982 16983@itemize * 16984 16985@item 16986"Implementation-defined aspects of access to machine 16987operations. See C.1(9)." 16988@end itemize 16989 16990See documentation in file @code{s-maccod.ads} in the distributed library. 16991 16992 16993@itemize * 16994 16995@item 16996"Implementation-defined aspects of interrupts. See C.3(2)." 16997@end itemize 16998 16999Interrupts are mapped to signals or conditions as appropriate. See 17000definition of unit 17001@code{Ada.Interrupt_Names} in source file @code{a-intnam.ads} for details 17002on the interrupts supported on a particular target. 17003 17004 17005@itemize * 17006 17007@item 17008"Implementation-defined aspects of pre-elaboration. See 17009C.4(13)." 17010@end itemize 17011 17012GNAT does not permit a partition to be restarted without reloading, 17013except under control of the debugger. 17014 17015 17016@itemize * 17017 17018@item 17019"The semantics of pragma @code{Discard_Names}. See C.5(7)." 17020@end itemize 17021 17022Pragma @code{Discard_Names} causes names of enumeration literals to 17023be suppressed. In the presence of this pragma, the Image attribute 17024provides the image of the Pos of the literal, and Value accepts 17025Pos values. 17026 17027For tagged types, when pragmas @code{Discard_Names} and @code{No_Tagged_Streams} 17028simultaneously apply, their Expanded_Name and External_Tag are initialized 17029with empty strings. This is useful to avoid exposing entity names at binary 17030level. 17031 17032 17033@itemize * 17034 17035@item 17036"The result of the @code{Task_Identification.Image} 17037attribute. See C.7.1(7)." 17038@end itemize 17039 17040The result of this attribute is a string that identifies 17041the object or component that denotes a given task. If a variable @code{Var} 17042has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}}, 17043where the suffix @emph{XXXXXXXX} 17044is the hexadecimal representation of the virtual address of the corresponding 17045task control block. If the variable is an array of tasks, the image of each 17046task will have the form of an indexed component indicating the position of a 17047given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a 17048component of a record, the image of the task will have the form of a selected 17049component. These rules are fully recursive, so that the image of a task that 17050is a subcomponent of a composite object corresponds to the expression that 17051designates this task. 17052 17053If a task is created by an allocator, its image depends on the context. If the 17054allocator is part of an object declaration, the rules described above are used 17055to construct its image, and this image is not affected by subsequent 17056assignments. If the allocator appears within an expression, the image 17057includes only the name of the task type. 17058 17059If the configuration pragma Discard_Names is present, or if the restriction 17060No_Implicit_Heap_Allocation is in effect, the image reduces to 17061the numeric suffix, that is to say the hexadecimal representation of the 17062virtual address of the control block of the task. 17063 17064 17065@itemize * 17066 17067@item 17068"The value of @code{Current_Task} when in a protected entry 17069or interrupt handler. See C.7.1(17)." 17070@end itemize 17071 17072Protected entries or interrupt handlers can be executed by any 17073convenient thread, so the value of @code{Current_Task} is undefined. 17074 17075 17076@itemize * 17077 17078@item 17079"The effect of calling @code{Current_Task} from an entry 17080body or interrupt handler. See C.7.1(19)." 17081@end itemize 17082 17083When GNAT can determine statically that @code{Current_Task} is called directly in 17084the body of an entry (or barrier) then a warning is emitted and @code{Program_Error} 17085is raised at run time. Otherwise, the effect of calling @code{Current_Task} from an 17086entry body or interrupt handler is to return the identification of the task 17087currently executing the code. 17088 17089 17090@itemize * 17091 17092@item 17093"Implementation-defined aspects of 17094@code{Task_Attributes}. See C.7.2(19)." 17095@end itemize 17096 17097There are no implementation-defined aspects of @code{Task_Attributes}. 17098 17099 17100@itemize * 17101 17102@item 17103"Values of all @code{Metrics}. See D(2)." 17104@end itemize 17105 17106The metrics information for GNAT depends on the performance of the 17107underlying operating system. The sources of the run-time for tasking 17108implementation, together with the output from @emph{-gnatG} can be 17109used to determine the exact sequence of operating systems calls made 17110to implement various tasking constructs. Together with appropriate 17111information on the performance of the underlying operating system, 17112on the exact target in use, this information can be used to determine 17113the required metrics. 17114 17115 17116@itemize * 17117 17118@item 17119"The declarations of @code{Any_Priority} and 17120@code{Priority}. See D.1(11)." 17121@end itemize 17122 17123See declarations in file @code{system.ads}. 17124 17125 17126@itemize * 17127 17128@item 17129"Implementation-defined execution resources. See D.1(15)." 17130@end itemize 17131 17132There are no implementation-defined execution resources. 17133 17134 17135@itemize * 17136 17137@item 17138"Whether, on a multiprocessor, a task that is waiting for 17139access to a protected object keeps its processor busy. See D.2.1(3)." 17140@end itemize 17141 17142On a multi-processor, a task that is waiting for access to a protected 17143object does not keep its processor busy. 17144 17145 17146@itemize * 17147 17148@item 17149"The affect of implementation defined execution resources 17150on task dispatching. See D.2.1(9)." 17151@end itemize 17152 17153Tasks map to threads in the threads package used by GNAT. Where possible 17154and appropriate, these threads correspond to native threads of the 17155underlying operating system. 17156 17157 17158@itemize * 17159 17160@item 17161"Implementation-defined @emph{policy_identifiers} allowed 17162in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3)." 17163@end itemize 17164 17165There are no implementation-defined policy-identifiers allowed in this 17166pragma. 17167 17168 17169@itemize * 17170 17171@item 17172"Implementation-defined aspects of priority inversion. See 17173D.2.2(16)." 17174@end itemize 17175 17176Execution of a task cannot be preempted by the implementation processing 17177of delay expirations for lower priority tasks. 17178 17179 17180@itemize * 17181 17182@item 17183"Implementation-defined task dispatching. See D.2.2(18)." 17184@end itemize 17185 17186The policy is the same as that of the underlying threads implementation. 17187 17188 17189@itemize * 17190 17191@item 17192"Implementation-defined @emph{policy_identifiers} allowed 17193in a pragma @code{Locking_Policy}. See D.3(4)." 17194@end itemize 17195 17196The two implementation defined policies permitted in GNAT are 17197@code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On 17198targets that support the @code{Inheritance_Locking} policy, locking is 17199implemented by inheritance, i.e., the task owning the lock operates 17200at a priority equal to the highest priority of any task currently 17201requesting the lock. On targets that support the 17202@code{Concurrent_Readers_Locking} policy, locking is implemented with a 17203read/write lock allowing multiple protected object functions to enter 17204concurrently. 17205 17206 17207@itemize * 17208 17209@item 17210"Default ceiling priorities. See D.3(10)." 17211@end itemize 17212 17213The ceiling priority of protected objects of the type 17214@code{System.Interrupt_Priority'Last} as described in the Ada 17215Reference Manual D.3(10), 17216 17217 17218@itemize * 17219 17220@item 17221"The ceiling of any protected object used internally by 17222the implementation. See D.3(16)." 17223@end itemize 17224 17225The ceiling priority of internal protected objects is 17226@code{System.Priority'Last}. 17227 17228 17229@itemize * 17230 17231@item 17232"Implementation-defined queuing policies. See D.4(1)." 17233@end itemize 17234 17235There are no implementation-defined queuing policies. 17236 17237 17238@itemize * 17239 17240@item 17241"On a multiprocessor, any conditions that cause the 17242completion of an aborted construct to be delayed later than what is 17243specified for a single processor. See D.6(3)." 17244@end itemize 17245 17246The semantics for abort on a multi-processor is the same as on a single 17247processor, there are no further delays. 17248 17249 17250@itemize * 17251 17252@item 17253"Any operations that implicitly require heap storage 17254allocation. See D.7(8)." 17255@end itemize 17256 17257The only operation that implicitly requires heap storage allocation is 17258task creation. 17259 17260 17261@itemize * 17262 17263@item 17264"What happens when a task terminates in the presence of 17265pragma @code{No_Task_Termination}. See D.7(15)." 17266@end itemize 17267 17268Execution is erroneous in that case. 17269 17270 17271@itemize * 17272 17273@item 17274"Implementation-defined aspects of pragma 17275@code{Restrictions}. See D.7(20)." 17276@end itemize 17277 17278There are no such implementation-defined aspects. 17279 17280 17281@itemize * 17282 17283@item 17284"Implementation-defined aspects of package 17285@code{Real_Time}. See D.8(17)." 17286@end itemize 17287 17288There are no implementation defined aspects of package @code{Real_Time}. 17289 17290 17291@itemize * 17292 17293@item 17294"Implementation-defined aspects of 17295@emph{delay_statements}. See D.9(8)." 17296@end itemize 17297 17298Any difference greater than one microsecond will cause the task to be 17299delayed (see D.9(7)). 17300 17301 17302@itemize * 17303 17304@item 17305"The upper bound on the duration of interrupt blocking 17306caused by the implementation. See D.12(5)." 17307@end itemize 17308 17309The upper bound is determined by the underlying operating system. In 17310no cases is it more than 10 milliseconds. 17311 17312 17313@itemize * 17314 17315@item 17316"The means for creating and executing distributed 17317programs. See E(5)." 17318@end itemize 17319 17320The GLADE package provides a utility GNATDIST for creating and executing 17321distributed programs. See the GLADE reference manual for further details. 17322 17323 17324@itemize * 17325 17326@item 17327"Any events that can result in a partition becoming 17328inaccessible. See E.1(7)." 17329@end itemize 17330 17331See the GLADE reference manual for full details on such events. 17332 17333 17334@itemize * 17335 17336@item 17337"The scheduling policies, treatment of priorities, and 17338management of shared resources between partitions in certain cases. See 17339E.1(11)." 17340@end itemize 17341 17342See the GLADE reference manual for full details on these aspects of 17343multi-partition execution. 17344 17345 17346@itemize * 17347 17348@item 17349"Events that cause the version of a compilation unit to 17350change. See E.3(5)." 17351@end itemize 17352 17353Editing the source file of a compilation unit, or the source files of 17354any units on which it is dependent in a significant way cause the version 17355to change. No other actions cause the version number to change. All changes 17356are significant except those which affect only layout, capitalization or 17357comments. 17358 17359 17360@itemize * 17361 17362@item 17363"Whether the execution of the remote subprogram is 17364immediately aborted as a result of cancellation. See E.4(13)." 17365@end itemize 17366 17367See the GLADE reference manual for details on the effect of abort in 17368a distributed application. 17369 17370 17371@itemize * 17372 17373@item 17374"Implementation-defined aspects of the PCS. See E.5(25)." 17375@end itemize 17376 17377See the GLADE reference manual for a full description of all implementation 17378defined aspects of the PCS. 17379 17380 17381@itemize * 17382 17383@item 17384"Implementation-defined interfaces in the PCS. See 17385E.5(26)." 17386@end itemize 17387 17388See the GLADE reference manual for a full description of all 17389implementation defined interfaces. 17390 17391 17392@itemize * 17393 17394@item 17395"The values of named numbers in the package 17396@code{Decimal}. See F.2(7)." 17397@end itemize 17398 17399 17400@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} 17401@headitem 17402 17403Named Number 17404 17405@tab 17406 17407Value 17408 17409@item 17410 17411@emph{Max_Scale} 17412 17413@tab 17414 17415+18 17416 17417@item 17418 17419@emph{Min_Scale} 17420 17421@tab 17422 17423-18 17424 17425@item 17426 17427@emph{Min_Delta} 17428 17429@tab 17430 174311.0E-18 17432 17433@item 17434 17435@emph{Max_Delta} 17436 17437@tab 17438 174391.0E+18 17440 17441@item 17442 17443@emph{Max_Decimal_Digits} 17444 17445@tab 17446 1744718 17448 17449@end multitable 17450 17451 17452 17453@itemize * 17454 17455@item 17456"The value of @code{Max_Picture_Length} in the package 17457@code{Text_IO.Editing}. See F.3.3(16)." 17458@end itemize 17459 1746064 17461 17462 17463@itemize * 17464 17465@item 17466"The value of @code{Max_Picture_Length} in the package 17467@code{Wide_Text_IO.Editing}. See F.3.4(5)." 17468@end itemize 17469 1747064 17471 17472 17473@itemize * 17474 17475@item 17476"The accuracy actually achieved by the complex elementary 17477functions and by other complex arithmetic operations. See G.1(1)." 17478@end itemize 17479 17480Standard library functions are used for the complex arithmetic 17481operations. Only fast math mode is currently supported. 17482 17483 17484@itemize * 17485 17486@item 17487"The sign of a zero result (or a component thereof) from 17488any operator or function in @code{Numerics.Generic_Complex_Types}, when 17489@code{Real'Signed_Zeros} is True. See G.1.1(53)." 17490@end itemize 17491 17492The signs of zero values are as recommended by the relevant 17493implementation advice. 17494 17495 17496@itemize * 17497 17498@item 17499"The sign of a zero result (or a component thereof) from 17500any operator or function in 17501@code{Numerics.Generic_Complex_Elementary_Functions}, when 17502@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45)." 17503@end itemize 17504 17505The signs of zero values are as recommended by the relevant 17506implementation advice. 17507 17508 17509@itemize * 17510 17511@item 17512"Whether the strict mode or the relaxed mode is the 17513default. See G.2(2)." 17514@end itemize 17515 17516The strict mode is the default. There is no separate relaxed mode. GNAT 17517provides a highly efficient implementation of strict mode. 17518 17519 17520@itemize * 17521 17522@item 17523"The result interval in certain cases of fixed-to-float 17524conversion. See G.2.1(10)." 17525@end itemize 17526 17527For cases where the result interval is implementation dependent, the 17528accuracy is that provided by performing all operations in 64-bit IEEE 17529floating-point format. 17530 17531 17532@itemize * 17533 17534@item 17535"The result of a floating point arithmetic operation in 17536overflow situations, when the @code{Machine_Overflows} attribute of the 17537result type is @code{False}. See G.2.1(13)." 17538@end itemize 17539 17540Infinite and NaN values are produced as dictated by the IEEE 17541floating-point standard. 17542Note that on machines that are not fully compliant with the IEEE 17543floating-point standard, such as Alpha, the @emph{-mieee} compiler flag 17544must be used for achieving IEEE conforming behavior (although at the cost 17545of a significant performance penalty), so infinite and NaN values are 17546properly generated. 17547 17548 17549@itemize * 17550 17551@item 17552"The result interval for division (or exponentiation by a 17553negative exponent), when the floating point hardware implements division 17554as multiplication by a reciprocal. See G.2.1(16)." 17555@end itemize 17556 17557Not relevant, division is IEEE exact. 17558 17559 17560@itemize * 17561 17562@item 17563"The definition of close result set, which determines the 17564accuracy of certain fixed point multiplications and divisions. See 17565G.2.3(5)." 17566@end itemize 17567 17568Operations in the close result set are performed using IEEE long format 17569floating-point arithmetic. The input operands are converted to 17570floating-point, the operation is done in floating-point, and the result 17571is converted to the target type. 17572 17573 17574@itemize * 17575 17576@item 17577"Conditions on a @emph{universal_real} operand of a fixed 17578point multiplication or division for which the result shall be in the 17579perfect result set. See G.2.3(22)." 17580@end itemize 17581 17582The result is only defined to be in the perfect result set if the result 17583can be computed by a single scaling operation involving a scale factor 17584representable in 64 bits. 17585 17586 17587@itemize * 17588 17589@item 17590"The result of a fixed point arithmetic operation in 17591overflow situations, when the @code{Machine_Overflows} attribute of the 17592result type is @code{False}. See G.2.3(27)." 17593@end itemize 17594 17595Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point 17596types. 17597 17598 17599@itemize * 17600 17601@item 17602"The result of an elementary function reference in 17603overflow situations, when the @code{Machine_Overflows} attribute of the 17604result type is @code{False}. See G.2.4(4)." 17605@end itemize 17606 17607IEEE infinite and Nan values are produced as appropriate. 17608 17609 17610@itemize * 17611 17612@item 17613"The value of the angle threshold, within which certain 17614elementary functions, complex arithmetic operations, and complex 17615elementary functions yield results conforming to a maximum relative 17616error bound. See G.2.4(10)." 17617@end itemize 17618 17619Information on this subject is not yet available. 17620 17621 17622@itemize * 17623 17624@item 17625"The accuracy of certain elementary functions for 17626parameters beyond the angle threshold. See G.2.4(10)." 17627@end itemize 17628 17629Information on this subject is not yet available. 17630 17631 17632@itemize * 17633 17634@item 17635"The result of a complex arithmetic operation or complex 17636elementary function reference in overflow situations, when the 17637@code{Machine_Overflows} attribute of the corresponding real type is 17638@code{False}. See G.2.6(5)." 17639@end itemize 17640 17641IEEE infinite and Nan values are produced as appropriate. 17642 17643 17644@itemize * 17645 17646@item 17647"The accuracy of certain complex arithmetic operations and 17648certain complex elementary functions for parameters (or components 17649thereof) beyond the angle threshold. See G.2.6(8)." 17650@end itemize 17651 17652Information on those subjects is not yet available. 17653 17654 17655@itemize * 17656 17657@item 17658"Information regarding bounded errors and erroneous 17659execution. See H.2(1)." 17660@end itemize 17661 17662Information on this subject is not yet available. 17663 17664 17665@itemize * 17666 17667@item 17668"Implementation-defined aspects of pragma 17669@code{Inspection_Point}. See H.3.2(8)." 17670@end itemize 17671 17672Pragma @code{Inspection_Point} ensures that the variable is live and can 17673be examined by the debugger at the inspection point. 17674 17675 17676@itemize * 17677 17678@item 17679"Implementation-defined aspects of pragma 17680@code{Restrictions}. See H.4(25)." 17681@end itemize 17682 17683There are no implementation-defined aspects of pragma @code{Restrictions}. The 17684use of pragma @code{Restrictions [No_Exceptions]} has no effect on the 17685generated code. Checks must suppressed by use of pragma @code{Suppress}. 17686 17687 17688@itemize * 17689 17690@item 17691"Any restrictions on pragma @code{Restrictions}. See 17692H.4(27)." 17693@end itemize 17694 17695There are no restrictions on pragma @code{Restrictions}. 17696 17697@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top 17698@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{25c}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{25d} 17699@chapter Intrinsic Subprograms 17700 17701 17702@geindex Intrinsic Subprograms 17703 17704GNAT allows a user application program to write the declaration: 17705 17706@example 17707pragma Import (Intrinsic, name); 17708@end example 17709 17710providing that the name corresponds to one of the implemented intrinsic 17711subprograms in GNAT, and that the parameter profile of the referenced 17712subprogram meets the requirements. This chapter describes the set of 17713implemented intrinsic subprograms, and the requirements on parameter profiles. 17714Note that no body is supplied; as with other uses of pragma Import, the 17715body is supplied elsewhere (in this case by the compiler itself). Note 17716that any use of this feature is potentially non-portable, since the 17717Ada standard does not require Ada compilers to implement this feature. 17718 17719@menu 17720* Intrinsic Operators:: 17721* Compilation_ISO_Date:: 17722* Compilation_Date:: 17723* Compilation_Time:: 17724* Enclosing_Entity:: 17725* Exception_Information:: 17726* Exception_Message:: 17727* Exception_Name:: 17728* File:: 17729* Line:: 17730* Shifts and Rotates:: 17731* Source_Location:: 17732 17733@end menu 17734 17735@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms 17736@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{25f} 17737@section Intrinsic Operators 17738 17739 17740@geindex Intrinsic operator 17741 17742All the predefined numeric operators in package Standard 17743in @code{pragma Import (Intrinsic,..)} 17744declarations. In the binary operator case, the operands must have the same 17745size. The operand or operands must also be appropriate for 17746the operator. For example, for addition, the operands must 17747both be floating-point or both be fixed-point, and the 17748right operand for @code{"**"} must have a root type of 17749@code{Standard.Integer'Base}. 17750You can use an intrinsic operator declaration as in the following example: 17751 17752@example 17753type Int1 is new Integer; 17754type Int2 is new Integer; 17755 17756function "+" (X1 : Int1; X2 : Int2) return Int1; 17757function "+" (X1 : Int1; X2 : Int2) return Int2; 17758pragma Import (Intrinsic, "+"); 17759@end example 17760 17761This declaration would permit 'mixed mode' arithmetic on items 17762of the differing types @code{Int1} and @code{Int2}. 17763It is also possible to specify such operators for private types, if the 17764full views are appropriate arithmetic types. 17765 17766@node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms 17767@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{260}@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{261} 17768@section Compilation_ISO_Date 17769 17770 17771@geindex Compilation_ISO_Date 17772 17773This intrinsic subprogram is used in the implementation of the 17774library package @code{GNAT.Source_Info}. The only useful use of the 17775intrinsic import in this case is the one in this unit, so an 17776application program should simply call the function 17777@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of 17778the current compilation (in local time format YYYY-MM-DD). 17779 17780@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms 17781@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{262}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{263} 17782@section Compilation_Date 17783 17784 17785@geindex Compilation_Date 17786 17787Same as Compilation_ISO_Date, except the string is in the form 17788MMM DD YYYY. 17789 17790@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms 17791@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{264}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{265} 17792@section Compilation_Time 17793 17794 17795@geindex Compilation_Time 17796 17797This intrinsic subprogram is used in the implementation of the 17798library package @code{GNAT.Source_Info}. The only useful use of the 17799intrinsic import in this case is the one in this unit, so an 17800application program should simply call the function 17801@code{GNAT.Source_Info.Compilation_Time} to obtain the time of 17802the current compilation (in local time format HH:MM:SS). 17803 17804@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms 17805@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{266}@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{267} 17806@section Enclosing_Entity 17807 17808 17809@geindex Enclosing_Entity 17810 17811This intrinsic subprogram is used in the implementation of the 17812library package @code{GNAT.Source_Info}. The only useful use of the 17813intrinsic import in this case is the one in this unit, so an 17814application program should simply call the function 17815@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 17816the current subprogram, package, task, entry, or protected subprogram. 17817 17818@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms 17819@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{268}@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{269} 17820@section Exception_Information 17821 17822 17823@geindex Exception_Information' 17824 17825This intrinsic subprogram is used in the implementation of the 17826library package @code{GNAT.Current_Exception}. The only useful 17827use of the intrinsic import in this case is the one in this unit, 17828so an application program should simply call the function 17829@code{GNAT.Current_Exception.Exception_Information} to obtain 17830the exception information associated with the current exception. 17831 17832@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms 17833@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{26a}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{26b} 17834@section Exception_Message 17835 17836 17837@geindex Exception_Message 17838 17839This intrinsic subprogram is used in the implementation of the 17840library package @code{GNAT.Current_Exception}. The only useful 17841use of the intrinsic import in this case is the one in this unit, 17842so an application program should simply call the function 17843@code{GNAT.Current_Exception.Exception_Message} to obtain 17844the message associated with the current exception. 17845 17846@node Exception_Name,File,Exception_Message,Intrinsic Subprograms 17847@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{26c}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26d} 17848@section Exception_Name 17849 17850 17851@geindex Exception_Name 17852 17853This intrinsic subprogram is used in the implementation of the 17854library package @code{GNAT.Current_Exception}. The only useful 17855use of the intrinsic import in this case is the one in this unit, 17856so an application program should simply call the function 17857@code{GNAT.Current_Exception.Exception_Name} to obtain 17858the name of the current exception. 17859 17860@node File,Line,Exception_Name,Intrinsic Subprograms 17861@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{26e}@anchor{gnat_rm/intrinsic_subprograms file}@anchor{26f} 17862@section File 17863 17864 17865@geindex File 17866 17867This intrinsic subprogram is used in the implementation of the 17868library package @code{GNAT.Source_Info}. The only useful use of the 17869intrinsic import in this case is the one in this unit, so an 17870application program should simply call the function 17871@code{GNAT.Source_Info.File} to obtain the name of the current 17872file. 17873 17874@node Line,Shifts and Rotates,File,Intrinsic Subprograms 17875@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{270}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{271} 17876@section Line 17877 17878 17879@geindex Line 17880 17881This intrinsic subprogram is used in the implementation of the 17882library package @code{GNAT.Source_Info}. The only useful use of the 17883intrinsic import in this case is the one in this unit, so an 17884application program should simply call the function 17885@code{GNAT.Source_Info.Line} to obtain the number of the current 17886source line. 17887 17888@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms 17889@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{272}@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{273} 17890@section Shifts and Rotates 17891 17892 17893@geindex Shift_Left 17894 17895@geindex Shift_Right 17896 17897@geindex Shift_Right_Arithmetic 17898 17899@geindex Rotate_Left 17900 17901@geindex Rotate_Right 17902 17903In standard Ada, the shift and rotate functions are available only 17904for the predefined modular types in package @code{Interfaces}. However, in 17905GNAT it is possible to define these functions for any integer 17906type (signed or modular), as in this example: 17907 17908@example 17909function Shift_Left 17910 (Value : T; 17911 Amount : Natural) return T; 17912@end example 17913 17914The function name must be one of 17915Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or 17916Rotate_Right. T must be an integer type. T'Size must be 179178, 16, 32 or 64 bits; if T is modular, the modulus 17918must be 2**8, 2**16, 2**32 or 2**64. 17919The result type must be the same as the type of @code{Value}. 17920The shift amount must be Natural. 17921The formal parameter names can be anything. 17922 17923A more convenient way of providing these shift operators is to use 17924the Provide_Shift_Operators pragma, which provides the function declarations 17925and corresponding pragma Import's for all five shift functions. Note that in 17926using these provided shift operations, shifts performed on negative numbers 17927will result in modification of the sign bit. 17928 17929@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms 17930@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{274}@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{275} 17931@section Source_Location 17932 17933 17934@geindex Source_Location 17935 17936This intrinsic subprogram is used in the implementation of the 17937library routine @code{GNAT.Source_Info}. The only useful use of the 17938intrinsic import in this case is the one in this unit, so an 17939application program should simply call the function 17940@code{GNAT.Source_Info.Source_Location} to obtain the current 17941source file location. 17942 17943@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top 17944@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{276}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{277} 17945@chapter Representation Clauses and Pragmas 17946 17947 17948@geindex Representation Clauses 17949 17950@geindex Representation Clause 17951 17952@geindex Representation Pragma 17953 17954@geindex Pragma 17955@geindex representation 17956 17957This section describes the representation clauses accepted by GNAT, and 17958their effect on the representation of corresponding data objects. 17959 17960GNAT fully implements Annex C (Systems Programming). This means that all 17961the implementation advice sections in chapter 13 are fully implemented. 17962However, these sections only require a minimal level of support for 17963representation clauses. GNAT provides much more extensive capabilities, 17964and this section describes the additional capabilities provided. 17965 17966@menu 17967* Alignment Clauses:: 17968* Size Clauses:: 17969* Storage_Size Clauses:: 17970* Size of Variant Record Objects:: 17971* Biased Representation:: 17972* Value_Size and Object_Size Clauses:: 17973* Component_Size Clauses:: 17974* Bit_Order Clauses:: 17975* Effect of Bit_Order on Byte Ordering:: 17976* Pragma Pack for Arrays:: 17977* Pragma Pack for Records:: 17978* Record Representation Clauses:: 17979* Handling of Records with Holes:: 17980* Enumeration Clauses:: 17981* Address Clauses:: 17982* Use of Address Clauses for Memory-Mapped I/O:: 17983* Effect of Convention on Representation:: 17984* Conventions and Anonymous Access Types:: 17985* Determining the Representations chosen by GNAT:: 17986 17987@end menu 17988 17989@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas 17990@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{279} 17991@section Alignment Clauses 17992 17993 17994@geindex Alignment Clause 17995 17996GNAT requires that all alignment clauses specify 0 or a power of 2, and 17997all default alignments are always a power of 2. Specifying 0 is the 17998same as specifying 1. 17999 18000The default alignment values are as follows: 18001 18002 18003@itemize * 18004 18005@item 18006@emph{Elementary Types}. 18007 18008For elementary types, the alignment is the minimum of the actual size of 18009objects of the type divided by @code{Storage_Unit}, 18010and the maximum alignment supported by the target. 18011(This maximum alignment is given by the GNAT-specific attribute 18012@code{Standard'Maximum_Alignment}; see @ref{190,,Attribute Maximum_Alignment}.) 18013 18014@geindex Maximum_Alignment attribute 18015 18016For example, for type @code{Long_Float}, the object size is 8 bytes, and the 18017default alignment will be 8 on any target that supports alignments 18018this large, but on some targets, the maximum alignment may be smaller 18019than 8, in which case objects of type @code{Long_Float} will be maximally 18020aligned. 18021 18022@item 18023@emph{Arrays}. 18024 18025For arrays, the alignment is equal to the alignment of the component type 18026for the normal case where no packing or component size is given. If the 18027array is packed, and the packing is effective (see separate section on 18028packed arrays), then the alignment will be either 4, 2, or 1 for long packed 18029arrays or arrays whose length is not known at compile time, depending on 18030whether the component size is divisible by 4, 2, or is odd. For short packed 18031arrays, which are handled internally as modular types, the alignment 18032will be as described for elementary types, e.g. a packed array of length 1803331 bits will have an object size of four bytes, and an alignment of 4. 18034 18035@item 18036@emph{Records}. 18037 18038For the normal unpacked case, the alignment of a record is equal to 18039the maximum alignment of any of its components. For tagged records, this 18040includes the implicit access type used for the tag. If a pragma @code{Pack} 18041is used and all components are packable (see separate section on pragma 18042@code{Pack}), then the resulting alignment is 1, unless the layout of the 18043record makes it profitable to increase it. 18044 18045A special case is when: 18046 18047 18048@itemize * 18049 18050@item 18051the size of the record is given explicitly, or a 18052full record representation clause is given, and 18053 18054@item 18055the size of the record is 2, 4, or 8 bytes. 18056@end itemize 18057 18058In this case, an alignment is chosen to match the 18059size of the record. For example, if we have: 18060 18061@example 18062type Small is record 18063 A, B : Character; 18064end record; 18065for Small'Size use 16; 18066@end example 18067 18068then the default alignment of the record type @code{Small} is 2, not 1. This 18069leads to more efficient code when the record is treated as a unit, and also 18070allows the type to specified as @code{Atomic} on architectures requiring 18071strict alignment. 18072@end itemize 18073 18074An alignment clause may specify a larger alignment than the default value 18075up to some maximum value dependent on the target (obtainable by using the 18076attribute reference @code{Standard'Maximum_Alignment}). It may also specify 18077a smaller alignment than the default value for enumeration, integer and 18078fixed point types, as well as for record types, for example 18079 18080@example 18081type V is record 18082 A : Integer; 18083end record; 18084 18085for V'alignment use 1; 18086@end example 18087 18088@geindex Alignment 18089@geindex default 18090 18091The default alignment for the type @code{V} is 4, as a result of the 18092Integer field in the record, but it is permissible, as shown, to 18093override the default alignment of the record with a smaller value. 18094 18095@geindex Alignment 18096@geindex subtypes 18097 18098Note that according to the Ada standard, an alignment clause applies only 18099to the first named subtype. If additional subtypes are declared, then the 18100compiler is allowed to choose any alignment it likes, and there is no way 18101to control this choice. Consider: 18102 18103@example 18104type R is range 1 .. 10_000; 18105for R'Alignment use 1; 18106subtype RS is R range 1 .. 1000; 18107@end example 18108 18109The alignment clause specifies an alignment of 1 for the first named subtype 18110@code{R} but this does not necessarily apply to @code{RS}. When writing 18111portable Ada code, you should avoid writing code that explicitly or 18112implicitly relies on the alignment of such subtypes. 18113 18114For the GNAT compiler, if an explicit alignment clause is given, this 18115value is also used for any subsequent subtypes. So for GNAT, in the 18116above example, you can count on the alignment of @code{RS} being 1. But this 18117assumption is non-portable, and other compilers may choose different 18118alignments for the subtype @code{RS}. 18119 18120@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas 18121@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{27a}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{27b} 18122@section Size Clauses 18123 18124 18125@geindex Size Clause 18126 18127The default size for a type @code{T} is obtainable through the 18128language-defined attribute @code{T'Size} and also through the 18129equivalent GNAT-defined attribute @code{T'Value_Size}. 18130For objects of type @code{T}, GNAT will generally increase the type size 18131so that the object size (obtainable through the GNAT-defined attribute 18132@code{T'Object_Size}) 18133is a multiple of @code{T'Alignment * Storage_Unit}. 18134 18135For example: 18136 18137@example 18138type Smallint is range 1 .. 6; 18139 18140type Rec is record 18141 Y1 : integer; 18142 Y2 : boolean; 18143end record; 18144@end example 18145 18146In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, 18147as specified by the RM rules, 18148but objects of this type will have a size of 8 18149(@code{Smallint'Object_Size} = 8), 18150since objects by default occupy an integral number 18151of storage units. On some targets, notably older 18152versions of the Digital Alpha, the size of stand 18153alone objects of this type may be 32, reflecting 18154the inability of the hardware to do byte load/stores. 18155 18156Similarly, the size of type @code{Rec} is 40 bits 18157(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but 18158the alignment is 4, so objects of this type will have 18159their size increased to 64 bits so that it is a multiple 18160of the alignment (in bits). This decision is 18161in accordance with the specific Implementation Advice in RM 13.3(43): 18162 18163@quotation 18164 18165"A @code{Size} clause should be supported for an object if the specified 18166@code{Size} is at least as large as its subtype's @code{Size}, and corresponds 18167to a size in storage elements that is a multiple of the object's 18168@code{Alignment} (if the @code{Alignment} is nonzero)." 18169@end quotation 18170 18171An explicit size clause may be used to override the default size by 18172increasing it. For example, if we have: 18173 18174@example 18175type My_Boolean is new Boolean; 18176for My_Boolean'Size use 32; 18177@end example 18178 18179then values of this type will always be 32-bit long. In the case of discrete 18180types, the size can be increased up to 64 bits on 32-bit targets and 128 bits 18181on 64-bit targets, with the effect that the entire specified field is used to 18182hold the value, sign- or zero-extended as appropriate. If more than 64 bits 18183or 128 bits resp. is specified, then padding space is allocated after the 18184value, and a warning is issued that there are unused bits. 18185 18186Similarly the size of records and arrays may be increased, and the effect 18187is to add padding bits after the value. This also causes a warning message 18188to be generated. 18189 18190The largest Size value permitted in GNAT is 2**31-1. Since this is a 18191Size in bits, this corresponds to an object of size 256 megabytes (minus 18192one). This limitation is true on all targets. The reason for this 18193limitation is that it improves the quality of the code in many cases 18194if it is known that a Size value can be accommodated in an object of 18195type Integer. 18196 18197@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas 18198@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27c}@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27d} 18199@section Storage_Size Clauses 18200 18201 18202@geindex Storage_Size Clause 18203 18204For tasks, the @code{Storage_Size} clause specifies the amount of space 18205to be allocated for the task stack. This cannot be extended, and if the 18206stack is exhausted, then @code{Storage_Error} will be raised (if stack 18207checking is enabled). Use a @code{Storage_Size} attribute definition clause, 18208or a @code{Storage_Size} pragma in the task definition to set the 18209appropriate required size. A useful technique is to include in every 18210task definition a pragma of the form: 18211 18212@example 18213pragma Storage_Size (Default_Stack_Size); 18214@end example 18215 18216Then @code{Default_Stack_Size} can be defined in a global package, and 18217modified as required. Any tasks requiring stack sizes different from the 18218default can have an appropriate alternative reference in the pragma. 18219 18220You can also use the @emph{-d} binder switch to modify the default stack 18221size. 18222 18223For access types, the @code{Storage_Size} clause specifies the maximum 18224space available for allocation of objects of the type. If this space is 18225exceeded then @code{Storage_Error} will be raised by an allocation attempt. 18226In the case where the access type is declared local to a subprogram, the 18227use of a @code{Storage_Size} clause triggers automatic use of a special 18228predefined storage pool (@code{System.Pool_Size}) that ensures that all 18229space for the pool is automatically reclaimed on exit from the scope in 18230which the type is declared. 18231 18232A special case recognized by the compiler is the specification of a 18233@code{Storage_Size} of zero for an access type. This means that no 18234items can be allocated from the pool, and this is recognized at compile 18235time, and all the overhead normally associated with maintaining a fixed 18236size storage pool is eliminated. Consider the following example: 18237 18238@example 18239procedure p is 18240 type R is array (Natural) of Character; 18241 type P is access all R; 18242 for P'Storage_Size use 0; 18243 -- Above access type intended only for interfacing purposes 18244 18245 y : P; 18246 18247 procedure g (m : P); 18248 pragma Import (C, g); 18249 18250 -- ... 18251 18252begin 18253 -- ... 18254 y := new R; 18255end; 18256@end example 18257 18258As indicated in this example, these dummy storage pools are often useful in 18259connection with interfacing where no object will ever be allocated. If you 18260compile the above example, you get the warning: 18261 18262@example 18263p.adb:16:09: warning: allocation from empty storage pool 18264p.adb:16:09: warning: Storage_Error will be raised at run time 18265@end example 18266 18267Of course in practice, there will not be any explicit allocators in the 18268case of such an access declaration. 18269 18270@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas 18271@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{27e}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{27f} 18272@section Size of Variant Record Objects 18273 18274 18275@geindex Size 18276@geindex variant record objects 18277 18278@geindex Variant record objects 18279@geindex size 18280 18281In the case of variant record objects, there is a question whether Size gives 18282information about a particular variant, or the maximum size required 18283for any variant. Consider the following program 18284 18285@example 18286with Text_IO; use Text_IO; 18287procedure q is 18288 type R1 (A : Boolean := False) is record 18289 case A is 18290 when True => X : Character; 18291 when False => null; 18292 end case; 18293 end record; 18294 18295 V1 : R1 (False); 18296 V2 : R1; 18297 18298begin 18299 Put_Line (Integer'Image (V1'Size)); 18300 Put_Line (Integer'Image (V2'Size)); 18301end q; 18302@end example 18303 18304Here we are dealing with a variant record, where the True variant 18305requires 16 bits, and the False variant requires 8 bits. 18306In the above example, both V1 and V2 contain the False variant, 18307which is only 8 bits long. However, the result of running the 18308program is: 18309 18310@example 183118 1831216 18313@end example 18314 18315The reason for the difference here is that the discriminant value of 18316V1 is fixed, and will always be False. It is not possible to assign 18317a True variant value to V1, therefore 8 bits is sufficient. On the 18318other hand, in the case of V2, the initial discriminant value is 18319False (from the default), but it is possible to assign a True 18320variant value to V2, therefore 16 bits must be allocated for V2 18321in the general case, even fewer bits may be needed at any particular 18322point during the program execution. 18323 18324As can be seen from the output of this program, the @code{'Size} 18325attribute applied to such an object in GNAT gives the actual allocated 18326size of the variable, which is the largest size of any of the variants. 18327The Ada Reference Manual is not completely clear on what choice should 18328be made here, but the GNAT behavior seems most consistent with the 18329language in the RM. 18330 18331In some cases, it may be desirable to obtain the size of the current 18332variant, rather than the size of the largest variant. This can be 18333achieved in GNAT by making use of the fact that in the case of a 18334subprogram parameter, GNAT does indeed return the size of the current 18335variant (because a subprogram has no way of knowing how much space 18336is actually allocated for the actual). 18337 18338Consider the following modified version of the above program: 18339 18340@example 18341with Text_IO; use Text_IO; 18342procedure q is 18343 type R1 (A : Boolean := False) is record 18344 case A is 18345 when True => X : Character; 18346 when False => null; 18347 end case; 18348 end record; 18349 18350 V2 : R1; 18351 18352 function Size (V : R1) return Integer is 18353 begin 18354 return V'Size; 18355 end Size; 18356 18357begin 18358 Put_Line (Integer'Image (V2'Size)); 18359 Put_Line (Integer'Image (Size (V2))); 18360 V2 := (True, 'x'); 18361 Put_Line (Integer'Image (V2'Size)); 18362 Put_Line (Integer'Image (Size (V2))); 18363end q; 18364@end example 18365 18366The output from this program is 18367 18368@example 1836916 183708 1837116 1837216 18373@end example 18374 18375Here we see that while the @code{'Size} attribute always returns 18376the maximum size, regardless of the current variant value, the 18377@code{Size} function does indeed return the size of the current 18378variant value. 18379 18380@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas 18381@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{280}@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{281} 18382@section Biased Representation 18383 18384 18385@geindex Size for biased representation 18386 18387@geindex Biased representation 18388 18389In the case of scalars with a range starting at other than zero, it is 18390possible in some cases to specify a size smaller than the default minimum 18391value, and in such cases, GNAT uses an unsigned biased representation, 18392in which zero is used to represent the lower bound, and successive values 18393represent successive values of the type. 18394 18395For example, suppose we have the declaration: 18396 18397@example 18398type Small is range -7 .. -4; 18399for Small'Size use 2; 18400@end example 18401 18402Although the default size of type @code{Small} is 4, the @code{Size} 18403clause is accepted by GNAT and results in the following representation 18404scheme: 18405 18406@example 18407-7 is represented as 2#00# 18408-6 is represented as 2#01# 18409-5 is represented as 2#10# 18410-4 is represented as 2#11# 18411@end example 18412 18413Biased representation is only used if the specified @code{Size} clause 18414cannot be accepted in any other manner. These reduced sizes that force 18415biased representation can be used for all discrete types except for 18416enumeration types for which a representation clause is given. 18417 18418@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas 18419@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{282}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{283} 18420@section Value_Size and Object_Size Clauses 18421 18422 18423@geindex Value_Size 18424 18425@geindex Object_Size 18426 18427@geindex Size 18428@geindex of objects 18429 18430In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum 18431number of bits required to hold values of type @code{T}. 18432Although this interpretation was allowed in Ada 83, it was not required, 18433and this requirement in practice can cause some significant difficulties. 18434For example, in most Ada 83 compilers, @code{Natural'Size} was 32. 18435However, in Ada 95 and Ada 2005, 18436@code{Natural'Size} is 18437typically 31. This means that code may change in behavior when moving 18438from Ada 83 to Ada 95 or Ada 2005. For example, consider: 18439 18440@example 18441type Rec is record; 18442 A : Natural; 18443 B : Natural; 18444end record; 18445 18446for Rec use record 18447 at 0 range 0 .. Natural'Size - 1; 18448 at 0 range Natural'Size .. 2 * Natural'Size - 1; 18449end record; 18450@end example 18451 18452In the above code, since the typical size of @code{Natural} objects 18453is 32 bits and @code{Natural'Size} is 31, the above code can cause 18454unexpected inefficient packing in Ada 95 and Ada 2005, and in general 18455there are cases where the fact that the object size can exceed the 18456size of the type causes surprises. 18457 18458To help get around this problem GNAT provides two implementation 18459defined attributes, @code{Value_Size} and @code{Object_Size}. When 18460applied to a type, these attributes yield the size of the type 18461(corresponding to the RM defined size attribute), and the size of 18462objects of the type respectively. 18463 18464The @code{Object_Size} is used for determining the default size of 18465objects and components. This size value can be referred to using the 18466@code{Object_Size} attribute. The phrase 'is used' here means that it is 18467the basis of the determination of the size. The backend is free to 18468pad this up if necessary for efficiency, e.g., an 8-bit stand-alone 18469character might be stored in 32 bits on a machine with no efficient 18470byte access instructions such as the Alpha. 18471 18472The default rules for the value of @code{Object_Size} for 18473discrete types are as follows: 18474 18475 18476@itemize * 18477 18478@item 18479The @code{Object_Size} for base subtypes reflect the natural hardware 18480size in bits (run the compiler with @emph{-gnatS} to find those values 18481for numeric types). Enumeration types and fixed-point base subtypes have 184828, 16, 32, or 64 bits for this size, depending on the range of values 18483to be stored. 18484 18485@item 18486The @code{Object_Size} of a subtype is the same as the 18487@code{Object_Size} of 18488the type from which it is obtained. 18489 18490@item 18491The @code{Object_Size} of a derived base type is copied from the parent 18492base type, and the @code{Object_Size} of a derived first subtype is copied 18493from the parent first subtype. 18494@end itemize 18495 18496The @code{Value_Size} attribute 18497is the (minimum) number of bits required to store a value 18498of the type. 18499This value is used to determine how tightly to pack 18500records or arrays with components of this type, and also affects 18501the semantics of unchecked conversion (unchecked conversions where 18502the @code{Value_Size} values differ generate a warning, and are potentially 18503target dependent). 18504 18505The default rules for the value of @code{Value_Size} are as follows: 18506 18507 18508@itemize * 18509 18510@item 18511The @code{Value_Size} for a base subtype is the minimum number of bits 18512required to store all values of the type (including the sign bit 18513only if negative values are possible). 18514 18515@item 18516If a subtype statically matches the first subtype of a given type, then it has 18517by default the same @code{Value_Size} as the first subtype. This is a 18518consequence of RM 13.1(14): "if two subtypes statically match, 18519then their subtype-specific aspects are the same".) 18520 18521@item 18522All other subtypes have a @code{Value_Size} corresponding to the minimum 18523number of bits required to store all values of the subtype. For 18524dynamic bounds, it is assumed that the value can range down or up 18525to the corresponding bound of the ancestor 18526@end itemize 18527 18528The RM defined attribute @code{Size} corresponds to the 18529@code{Value_Size} attribute. 18530 18531The @code{Size} attribute may be defined for a first-named subtype. This sets 18532the @code{Value_Size} of 18533the first-named subtype to the given value, and the 18534@code{Object_Size} of this first-named subtype to the given value padded up 18535to an appropriate boundary. It is a consequence of the default rules 18536above that this @code{Object_Size} will apply to all further subtypes. On the 18537other hand, @code{Value_Size} is affected only for the first subtype, any 18538dynamic subtypes obtained from it directly, and any statically matching 18539subtypes. The @code{Value_Size} of any other static subtypes is not affected. 18540 18541@code{Value_Size} and 18542@code{Object_Size} may be explicitly set for any subtype using 18543an attribute definition clause. Note that the use of these attributes 18544can cause the RM 13.1(14) rule to be violated. If two access types 18545reference aliased objects whose subtypes have differing @code{Object_Size} 18546values as a result of explicit attribute definition clauses, then it 18547is illegal to convert from one access subtype to the other. For a more 18548complete description of this additional legality rule, see the 18549description of the @code{Object_Size} attribute. 18550 18551To get a feel for the difference, consider the following examples (note 18552that in each case the base is @code{Short_Short_Integer} with a size of 8): 18553 18554 18555@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} 18556@headitem 18557 18558Type or subtype declaration 18559 18560@tab 18561 18562Object_Size 18563 18564@tab 18565 18566Value_Size 18567 18568@item 18569 18570@code{type x1 is range 0 .. 5;} 18571 18572@tab 18573 185748 18575 18576@tab 18577 185783 18579 18580@item 18581 18582@code{type x2 is range 0 .. 5;} 18583@code{for x2'size use 12;} 18584 18585@tab 18586 1858716 18588 18589@tab 18590 1859112 18592 18593@item 18594 18595@code{subtype x3 is x2 range 0 .. 3;} 18596 18597@tab 18598 1859916 18600 18601@tab 18602 186032 18604 18605@item 18606 18607@code{subtype x4 is x2'base range 0 .. 10;} 18608 18609@tab 18610 186118 18612 18613@tab 18614 186154 18616 18617@item 18618 18619@code{dynamic : x2'Base range -64 .. +63;} 18620 18621@tab 18622 18623@tab 18624 18625@item 18626 18627@code{subtype x5 is x2 range 0 .. dynamic;} 18628 18629@tab 18630 1863116 18632 18633@tab 18634 186353* 18636 18637@item 18638 18639@code{subtype x6 is x2'base range 0 .. dynamic;} 18640 18641@tab 18642 186438 18644 18645@tab 18646 186477* 18648 18649@end multitable 18650 18651 18652Note: the entries marked '*' are not actually specified by the Ada 18653Reference Manual, which has nothing to say about size in the dynamic 18654case. What GNAT does is to allocate sufficient bits to accommodate any 18655possible dynamic values for the bounds at run-time. 18656 18657So far, so good, but GNAT has to obey the RM rules, so the question is 18658under what conditions must the RM @code{Size} be used. 18659The following is a list 18660of the occasions on which the RM @code{Size} must be used: 18661 18662 18663@itemize * 18664 18665@item 18666Component size for packed arrays or records 18667 18668@item 18669Value of the attribute @code{Size} for a type 18670 18671@item 18672Warning about sizes not matching for unchecked conversion 18673@end itemize 18674 18675For record types, the @code{Object_Size} is always a multiple of the 18676alignment of the type (this is true for all types). In some cases the 18677@code{Value_Size} can be smaller. Consider: 18678 18679@example 18680type R is record 18681 X : Integer; 18682 Y : Character; 18683end record; 18684@end example 18685 18686On a typical 32-bit architecture, the X component will occupy four bytes 18687and the Y component will occupy one byte, for a total of 5 bytes. As a 18688result @code{R'Value_Size} will be 40 (bits) since this is the minimum size 18689required to store a value of this type. For example, it is permissible 18690to have a component of type R in an array whose component size is 18691specified to be 40 bits. 18692 18693However, @code{R'Object_Size} will be 64 (bits). The difference is due to 18694the alignment requirement for objects of the record type. The X 18695component will require four-byte alignment because that is what type 18696Integer requires, whereas the Y component, a Character, will only 18697require 1-byte alignment. Since the alignment required for X is the 18698greatest of all the components' alignments, that is the alignment 18699required for the enclosing record type, i.e., 4 bytes or 32 bits. As 18700indicated above, the actual object size must be rounded up so that it is 18701a multiple of the alignment value. Therefore, 40 bits rounded up to the 18702next multiple of 32 yields 64 bits. 18703 18704For all other types, the @code{Object_Size} 18705and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). 18706Only @code{Size} may be specified for such types. 18707 18708Note that @code{Value_Size} can be used to force biased representation 18709for a particular subtype. Consider this example: 18710 18711@example 18712type R is (A, B, C, D, E, F); 18713subtype RAB is R range A .. B; 18714subtype REF is R range E .. F; 18715@end example 18716 18717By default, @code{RAB} 18718has a size of 1 (sufficient to accommodate the representation 18719of @code{A} and @code{B}, 0 and 1), and @code{REF} 18720has a size of 3 (sufficient to accommodate the representation 18721of @code{E} and @code{F}, 4 and 5). But if we add the 18722following @code{Value_Size} attribute definition clause: 18723 18724@example 18725for REF'Value_Size use 1; 18726@end example 18727 18728then biased representation is forced for @code{REF}, 18729and 0 will represent @code{E} and 1 will represent @code{F}. 18730A warning is issued when a @code{Value_Size} attribute 18731definition clause forces biased representation. This 18732warning can be turned off using @code{-gnatw.B}. 18733 18734@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas 18735@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{284}@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{285} 18736@section Component_Size Clauses 18737 18738 18739@geindex Component_Size Clause 18740 18741Normally, the value specified in a component size clause must be consistent 18742with the subtype of the array component with regard to size and alignment. 18743In other words, the value specified must be at least equal to the size 18744of this subtype, and must be a multiple of the alignment value. 18745 18746In addition, component size clauses are allowed which cause the array 18747to be packed, by specifying a smaller value. A first case is for 18748component size values in the range 1 through 63 on 32-bit targets, 18749and 1 through 127 on 64-bit targets. The value specified may not 18750be smaller than the Size of the subtype. GNAT will accurately 18751honor all packing requests in this range. For example, if we have: 18752 18753@example 18754type r is array (1 .. 8) of Natural; 18755for r'Component_Size use 31; 18756@end example 18757 18758then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 18759Of course access to the components of such an array is considerably 18760less efficient than if the natural component size of 32 is used. 18761A second case is when the subtype of the component is a record type 18762padded because of its default alignment. For example, if we have: 18763 18764@example 18765type r is record 18766 i : Integer; 18767 j : Integer; 18768 b : Boolean; 18769end record; 18770 18771type a is array (1 .. 8) of r; 18772for a'Component_Size use 72; 18773@end example 18774 18775then the resulting array has a length of 72 bytes, instead of 96 bytes 18776if the alignment of the record (4) was obeyed. 18777 18778Note that there is no point in giving both a component size clause 18779and a pragma Pack for the same array type. if such duplicate 18780clauses are given, the pragma Pack will be ignored. 18781 18782@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas 18783@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{286}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{287} 18784@section Bit_Order Clauses 18785 18786 18787@geindex Bit_Order Clause 18788 18789@geindex bit ordering 18790 18791@geindex ordering 18792@geindex of bits 18793 18794For record subtypes, GNAT permits the specification of the @code{Bit_Order} 18795attribute. The specification may either correspond to the default bit 18796order for the target, in which case the specification has no effect and 18797places no additional restrictions, or it may be for the non-standard 18798setting (that is the opposite of the default). 18799 18800In the case where the non-standard value is specified, the effect is 18801to renumber bits within each byte, but the ordering of bytes is not 18802affected. There are certain 18803restrictions placed on component clauses as follows: 18804 18805 18806@itemize * 18807 18808@item 18809Components fitting within a single storage unit. 18810 18811These are unrestricted, and the effect is merely to renumber bits. For 18812example if we are on a little-endian machine with @code{Low_Order_First} 18813being the default, then the following two declarations have exactly 18814the same effect: 18815 18816@example 18817type R1 is record 18818 A : Boolean; 18819 B : Integer range 1 .. 120; 18820end record; 18821 18822for R1 use record 18823 A at 0 range 0 .. 0; 18824 B at 0 range 1 .. 7; 18825end record; 18826 18827type R2 is record 18828 A : Boolean; 18829 B : Integer range 1 .. 120; 18830end record; 18831 18832for R2'Bit_Order use High_Order_First; 18833 18834for R2 use record 18835 A at 0 range 7 .. 7; 18836 B at 0 range 0 .. 6; 18837end record; 18838@end example 18839 18840The useful application here is to write the second declaration with the 18841@code{Bit_Order} attribute definition clause, and know that it will be treated 18842the same, regardless of whether the target is little-endian or big-endian. 18843 18844@item 18845Components occupying an integral number of bytes. 18846 18847These are components that exactly fit in two or more bytes. Such component 18848declarations are allowed, but have no effect, since it is important to realize 18849that the @code{Bit_Order} specification does not affect the ordering of bytes. 18850In particular, the following attempt at getting an endian-independent integer 18851does not work: 18852 18853@example 18854type R2 is record 18855 A : Integer; 18856end record; 18857 18858for R2'Bit_Order use High_Order_First; 18859 18860for R2 use record 18861 A at 0 range 0 .. 31; 18862end record; 18863@end example 18864 18865This declaration will result in a little-endian integer on a 18866little-endian machine, and a big-endian integer on a big-endian machine. 18867If byte flipping is required for interoperability between big- and 18868little-endian machines, this must be explicitly programmed. This capability 18869is not provided by @code{Bit_Order}. 18870 18871@item 18872Components that are positioned across byte boundaries. 18873 18874but do not occupy an integral number of bytes. Given that bytes are not 18875reordered, such fields would occupy a non-contiguous sequence of bits 18876in memory, requiring non-trivial code to reassemble. They are for this 18877reason not permitted, and any component clause specifying such a layout 18878will be flagged as illegal by GNAT. 18879@end itemize 18880 18881Since the misconception that Bit_Order automatically deals with all 18882endian-related incompatibilities is a common one, the specification of 18883a component field that is an integral number of bytes will always 18884generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} 18885if desired. The following section contains additional 18886details regarding the issue of byte ordering. 18887 18888@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas 18889@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{288}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{289} 18890@section Effect of Bit_Order on Byte Ordering 18891 18892 18893@geindex byte ordering 18894 18895@geindex ordering 18896@geindex of bytes 18897 18898In this section we will review the effect of the @code{Bit_Order} attribute 18899definition clause on byte ordering. Briefly, it has no effect at all, but 18900a detailed example will be helpful. Before giving this 18901example, let us review the precise 18902definition of the effect of defining @code{Bit_Order}. The effect of a 18903non-standard bit order is described in section 13.5.3 of the Ada 18904Reference Manual: 18905 18906@quotation 18907 18908"2 A bit ordering is a method of interpreting the meaning of 18909the storage place attributes." 18910@end quotation 18911 18912To understand the precise definition of storage place attributes in 18913this context, we visit section 13.5.1 of the manual: 18914 18915@quotation 18916 18917"13 A record_representation_clause (without the mod_clause) 18918specifies the layout. The storage place attributes (see 13.5.2) 18919are taken from the values of the position, first_bit, and last_bit 18920expressions after normalizing those values so that first_bit is 18921less than Storage_Unit." 18922@end quotation 18923 18924The critical point here is that storage places are taken from 18925the values after normalization, not before. So the @code{Bit_Order} 18926interpretation applies to normalized values. The interpretation 18927is described in the later part of the 13.5.3 paragraph: 18928 18929@quotation 18930 18931"2 A bit ordering is a method of interpreting the meaning of 18932the storage place attributes. High_Order_First (known in the 18933vernacular as 'big endian') means that the first bit of a 18934storage element (bit 0) is the most significant bit (interpreting 18935the sequence of bits that represent a component as an unsigned 18936integer value). Low_Order_First (known in the vernacular as 18937'little endian') means the opposite: the first bit is the 18938least significant." 18939@end quotation 18940 18941Note that the numbering is with respect to the bits of a storage 18942unit. In other words, the specification affects only the numbering 18943of bits within a single storage unit. 18944 18945We can make the effect clearer by giving an example. 18946 18947Suppose that we have an external device which presents two bytes, the first 18948byte presented, which is the first (low addressed byte) of the two byte 18949record is called Master, and the second byte is called Slave. 18950 18951The left most (most significant bit is called Control for each byte, and 18952the remaining 7 bits are called V1, V2, ... V7, where V7 is the rightmost 18953(least significant) bit. 18954 18955On a big-endian machine, we can write the following representation clause 18956 18957@example 18958type Data is record 18959 Master_Control : Bit; 18960 Master_V1 : Bit; 18961 Master_V2 : Bit; 18962 Master_V3 : Bit; 18963 Master_V4 : Bit; 18964 Master_V5 : Bit; 18965 Master_V6 : Bit; 18966 Master_V7 : Bit; 18967 Slave_Control : Bit; 18968 Slave_V1 : Bit; 18969 Slave_V2 : Bit; 18970 Slave_V3 : Bit; 18971 Slave_V4 : Bit; 18972 Slave_V5 : Bit; 18973 Slave_V6 : Bit; 18974 Slave_V7 : Bit; 18975end record; 18976 18977for Data use record 18978 Master_Control at 0 range 0 .. 0; 18979 Master_V1 at 0 range 1 .. 1; 18980 Master_V2 at 0 range 2 .. 2; 18981 Master_V3 at 0 range 3 .. 3; 18982 Master_V4 at 0 range 4 .. 4; 18983 Master_V5 at 0 range 5 .. 5; 18984 Master_V6 at 0 range 6 .. 6; 18985 Master_V7 at 0 range 7 .. 7; 18986 Slave_Control at 1 range 0 .. 0; 18987 Slave_V1 at 1 range 1 .. 1; 18988 Slave_V2 at 1 range 2 .. 2; 18989 Slave_V3 at 1 range 3 .. 3; 18990 Slave_V4 at 1 range 4 .. 4; 18991 Slave_V5 at 1 range 5 .. 5; 18992 Slave_V6 at 1 range 6 .. 6; 18993 Slave_V7 at 1 range 7 .. 7; 18994end record; 18995@end example 18996 18997Now if we move this to a little endian machine, then the bit ordering within 18998the byte is backwards, so we have to rewrite the record rep clause as: 18999 19000@example 19001for Data use record 19002 Master_Control at 0 range 7 .. 7; 19003 Master_V1 at 0 range 6 .. 6; 19004 Master_V2 at 0 range 5 .. 5; 19005 Master_V3 at 0 range 4 .. 4; 19006 Master_V4 at 0 range 3 .. 3; 19007 Master_V5 at 0 range 2 .. 2; 19008 Master_V6 at 0 range 1 .. 1; 19009 Master_V7 at 0 range 0 .. 0; 19010 Slave_Control at 1 range 7 .. 7; 19011 Slave_V1 at 1 range 6 .. 6; 19012 Slave_V2 at 1 range 5 .. 5; 19013 Slave_V3 at 1 range 4 .. 4; 19014 Slave_V4 at 1 range 3 .. 3; 19015 Slave_V5 at 1 range 2 .. 2; 19016 Slave_V6 at 1 range 1 .. 1; 19017 Slave_V7 at 1 range 0 .. 0; 19018end record; 19019@end example 19020 19021It is a nuisance to have to rewrite the clause, especially if 19022the code has to be maintained on both machines. However, 19023this is a case that we can handle with the 19024@code{Bit_Order} attribute if it is implemented. 19025Note that the implementation is not required on byte addressed 19026machines, but it is indeed implemented in GNAT. 19027This means that we can simply use the 19028first record clause, together with the declaration 19029 19030@example 19031for Data'Bit_Order use High_Order_First; 19032@end example 19033 19034and the effect is what is desired, namely the layout is exactly the same, 19035independent of whether the code is compiled on a big-endian or little-endian 19036machine. 19037 19038The important point to understand is that byte ordering is not affected. 19039A @code{Bit_Order} attribute definition never affects which byte a field 19040ends up in, only where it ends up in that byte. 19041To make this clear, let us rewrite the record rep clause of the previous 19042example as: 19043 19044@example 19045for Data'Bit_Order use High_Order_First; 19046for Data use record 19047 Master_Control at 0 range 0 .. 0; 19048 Master_V1 at 0 range 1 .. 1; 19049 Master_V2 at 0 range 2 .. 2; 19050 Master_V3 at 0 range 3 .. 3; 19051 Master_V4 at 0 range 4 .. 4; 19052 Master_V5 at 0 range 5 .. 5; 19053 Master_V6 at 0 range 6 .. 6; 19054 Master_V7 at 0 range 7 .. 7; 19055 Slave_Control at 0 range 8 .. 8; 19056 Slave_V1 at 0 range 9 .. 9; 19057 Slave_V2 at 0 range 10 .. 10; 19058 Slave_V3 at 0 range 11 .. 11; 19059 Slave_V4 at 0 range 12 .. 12; 19060 Slave_V5 at 0 range 13 .. 13; 19061 Slave_V6 at 0 range 14 .. 14; 19062 Slave_V7 at 0 range 15 .. 15; 19063end record; 19064@end example 19065 19066This is exactly equivalent to saying (a repeat of the first example): 19067 19068@example 19069for Data'Bit_Order use High_Order_First; 19070for Data use record 19071 Master_Control at 0 range 0 .. 0; 19072 Master_V1 at 0 range 1 .. 1; 19073 Master_V2 at 0 range 2 .. 2; 19074 Master_V3 at 0 range 3 .. 3; 19075 Master_V4 at 0 range 4 .. 4; 19076 Master_V5 at 0 range 5 .. 5; 19077 Master_V6 at 0 range 6 .. 6; 19078 Master_V7 at 0 range 7 .. 7; 19079 Slave_Control at 1 range 0 .. 0; 19080 Slave_V1 at 1 range 1 .. 1; 19081 Slave_V2 at 1 range 2 .. 2; 19082 Slave_V3 at 1 range 3 .. 3; 19083 Slave_V4 at 1 range 4 .. 4; 19084 Slave_V5 at 1 range 5 .. 5; 19085 Slave_V6 at 1 range 6 .. 6; 19086 Slave_V7 at 1 range 7 .. 7; 19087end record; 19088@end example 19089 19090Why are they equivalent? Well take a specific field, the @code{Slave_V2} 19091field. The storage place attributes are obtained by normalizing the 19092values given so that the @code{First_Bit} value is less than 8. After 19093normalizing the values (0,10,10) we get (1,2,2) which is exactly what 19094we specified in the other case. 19095 19096Now one might expect that the @code{Bit_Order} attribute might affect 19097bit numbering within the entire record component (two bytes in this 19098case, thus affecting which byte fields end up in), but that is not 19099the way this feature is defined, it only affects numbering of bits, 19100not which byte they end up in. 19101 19102Consequently it never makes sense to specify a starting bit number 19103greater than 7 (for a byte addressable field) if an attribute 19104definition for @code{Bit_Order} has been given, and indeed it 19105may be actively confusing to specify such a value, so the compiler 19106generates a warning for such usage. 19107 19108If you do need to control byte ordering then appropriate conditional 19109values must be used. If in our example, the slave byte came first on 19110some machines we might write: 19111 19112@example 19113Master_Byte_First constant Boolean := ...; 19114 19115Master_Byte : constant Natural := 19116 1 - Boolean'Pos (Master_Byte_First); 19117Slave_Byte : constant Natural := 19118 Boolean'Pos (Master_Byte_First); 19119 19120for Data'Bit_Order use High_Order_First; 19121for Data use record 19122 Master_Control at Master_Byte range 0 .. 0; 19123 Master_V1 at Master_Byte range 1 .. 1; 19124 Master_V2 at Master_Byte range 2 .. 2; 19125 Master_V3 at Master_Byte range 3 .. 3; 19126 Master_V4 at Master_Byte range 4 .. 4; 19127 Master_V5 at Master_Byte range 5 .. 5; 19128 Master_V6 at Master_Byte range 6 .. 6; 19129 Master_V7 at Master_Byte range 7 .. 7; 19130 Slave_Control at Slave_Byte range 0 .. 0; 19131 Slave_V1 at Slave_Byte range 1 .. 1; 19132 Slave_V2 at Slave_Byte range 2 .. 2; 19133 Slave_V3 at Slave_Byte range 3 .. 3; 19134 Slave_V4 at Slave_Byte range 4 .. 4; 19135 Slave_V5 at Slave_Byte range 5 .. 5; 19136 Slave_V6 at Slave_Byte range 6 .. 6; 19137 Slave_V7 at Slave_Byte range 7 .. 7; 19138end record; 19139@end example 19140 19141Now to switch between machines, all that is necessary is 19142to set the boolean constant @code{Master_Byte_First} in 19143an appropriate manner. 19144 19145@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas 19146@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{28a}@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{28b} 19147@section Pragma Pack for Arrays 19148 19149 19150@geindex Pragma Pack (for arrays) 19151 19152Pragma @code{Pack} applied to an array has an effect that depends upon whether the 19153component type is @emph{packable}. For a component type to be @emph{packable}, it must 19154be one of the following cases: 19155 19156 19157@itemize * 19158 19159@item 19160Any elementary type. 19161 19162@item 19163Any small packed array type with a static size. 19164 19165@item 19166Any small simple record type with a static size. 19167@end itemize 19168 19169For all these cases, if the component subtype size is in the range 191701 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets, 19171then the effect of the pragma @code{Pack} is exactly as though a 19172component size were specified giving the component subtype size. 19173 19174All other types are non-packable, they occupy an integral number of storage 19175units and the only effect of pragma Pack is to remove alignment gaps. 19176 19177For example if we have: 19178 19179@example 19180type r is range 0 .. 17; 19181 19182type ar is array (1 .. 8) of r; 19183pragma Pack (ar); 19184@end example 19185 19186Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, 19187and the size of the array @code{ar} will be exactly 40 bits). 19188 19189Note that in some cases this rather fierce approach to packing can produce 19190unexpected effects. For example, in Ada 95 and Ada 2005, 19191subtype @code{Natural} typically has a size of 31, meaning that if you 19192pack an array of @code{Natural}, you get 31-bit 19193close packing, which saves a few bits, but results in far less efficient 19194access. Since many other Ada compilers will ignore such a packing request, 19195GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses 19196might not be what is intended. You can easily remove this warning by 19197using an explicit @code{Component_Size} setting instead, which never generates 19198a warning, since the intention of the programmer is clear in this case. 19199 19200GNAT treats packed arrays in one of two ways. If the size of the array is 19201known at compile time and is at most 64 bits on 32-bit targets, and at most 19202128 bits on 64-bit targets, then internally the array is represented as a 19203single modular type, of exactly the appropriate number of bits. If the 19204length is greater than 64 bits on 32-bit targets, and greater than 128 19205bits on 64-bit targets, or is not known at compile time, then the packed 19206array is represented as an array of bytes, and its length is always a 19207multiple of 8 bits. 19208 19209Note that to represent a packed array as a modular type, the alignment must 19210be suitable for the modular type involved. For example, on typical machines 19211a 32-bit packed array will be represented by a 32-bit modular integer with 19212an alignment of four bytes. If you explicitly override the default alignment 19213with an alignment clause that is too small, the modular representation 19214cannot be used. For example, consider the following set of declarations: 19215 19216@example 19217type R is range 1 .. 3; 19218type S is array (1 .. 31) of R; 19219for S'Component_Size use 2; 19220for S'Size use 62; 19221for S'Alignment use 1; 19222@end example 19223 19224If the alignment clause were not present, then a 62-bit modular 19225representation would be chosen (typically with an alignment of 4 or 8 19226bytes depending on the target). But the default alignment is overridden 19227with the explicit alignment clause. This means that the modular 19228representation cannot be used, and instead the array of bytes 19229representation must be used, meaning that the length must be a multiple 19230of 8. Thus the above set of declarations will result in a diagnostic 19231rejecting the size clause and noting that the minimum size allowed is 64. 19232 19233@geindex Pragma Pack (for type Natural) 19234 19235@geindex Pragma Pack warning 19236 19237One special case that is worth noting occurs when the base type of the 19238component size is 8/16/32 and the subtype is one bit less. Notably this 19239occurs with subtype @code{Natural}. Consider: 19240 19241@example 19242type Arr is array (1 .. 32) of Natural; 19243pragma Pack (Arr); 19244@end example 19245 19246In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 19247since typically @code{Natural'Size} is 32 in Ada 83, and in any case most 19248Ada 83 compilers did not attempt 31 bit packing. 19249 19250In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, 19251GNAT really does pack 31-bit subtype to 31 bits. This may result in a 19252substantial unintended performance penalty when porting legacy Ada 83 code. 19253To help prevent this, GNAT generates a warning in such cases. If you really 19254want 31 bit packing in a case like this, you can set the component size 19255explicitly: 19256 19257@example 19258type Arr is array (1 .. 32) of Natural; 19259for Arr'Component_Size use 31; 19260@end example 19261 19262Here 31-bit packing is achieved as required, and no warning is generated, 19263since in this case the programmer intention is clear. 19264 19265@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas 19266@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28c}@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{28d} 19267@section Pragma Pack for Records 19268 19269 19270@geindex Pragma Pack (for records) 19271 19272Pragma @code{Pack} applied to a record will pack the components to reduce 19273wasted space from alignment gaps and by reducing the amount of space 19274taken by components. We distinguish between @emph{packable} components and 19275@emph{non-packable} components. 19276Components of the following types are considered packable: 19277 19278 19279@itemize * 19280 19281@item 19282Components of an elementary type are packable unless they are aliased, 19283independent or atomic. 19284 19285@item 19286Small packed arrays, where the size is statically known, are represented 19287internally as modular integers, and so they are also packable. 19288 19289@item 19290Small simple records, where the size is statically known, are also packable. 19291@end itemize 19292 19293For all these cases, if the @code{'Size} value is in the range 1 through 64 on 1929432-bit targets, and 1 through 128 on 64-bit targets, the components occupy 19295the exact number of bits corresponding to this value and are packed with no 19296padding bits, i.e. they can start on an arbitrary bit boundary. 19297 19298All other types are non-packable, they occupy an integral number of storage 19299units and the only effect of pragma @code{Pack} is to remove alignment gaps. 19300 19301For example, consider the record 19302 19303@example 19304type Rb1 is array (1 .. 13) of Boolean; 19305pragma Pack (Rb1); 19306 19307type Rb2 is array (1 .. 65) of Boolean; 19308pragma Pack (Rb2); 19309 19310type AF is new Float with Atomic; 19311 19312type X2 is record 19313 L1 : Boolean; 19314 L2 : Duration; 19315 L3 : AF; 19316 L4 : Boolean; 19317 L5 : Rb1; 19318 L6 : Rb2; 19319end record; 19320pragma Pack (X2); 19321@end example 19322 19323The representation for the record @code{X2} is as follows on 32-bit targets: 19324 19325@example 19326for X2'Size use 224; 19327for X2 use record 19328 L1 at 0 range 0 .. 0; 19329 L2 at 0 range 1 .. 64; 19330 L3 at 12 range 0 .. 31; 19331 L4 at 16 range 0 .. 0; 19332 L5 at 16 range 1 .. 13; 19333 L6 at 18 range 0 .. 71; 19334end record; 19335@end example 19336 19337Studying this example, we see that the packable fields @code{L1} 19338and @code{L2} are of length equal to their sizes, and placed at 19339specific bit boundaries (and not byte boundaries) to eliminate 19340padding. But @code{L3} is of a non-packable float type (because 19341it is aliased), so it is on the next appropriate alignment boundary. 19342 19343The next two fields are fully packable, so @code{L4} and @code{L5} are 19344minimally packed with no gaps. However, type @code{Rb2} is a packed 19345array that is longer than 64 bits, so it is itself non-packable on 1934632-bit targets. Thus the @code{L6} field is aligned to the next byte 19347boundary, and takes an integral number of bytes, i.e., 72 bits. 19348 19349@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas 19350@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{28e}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{28f} 19351@section Record Representation Clauses 19352 19353 19354@geindex Record Representation Clause 19355 19356Record representation clauses may be given for all record types, including 19357types obtained by record extension. Component clauses are allowed for any 19358static component. The restrictions on component clauses depend on the type 19359of the component. 19360 19361@geindex Component Clause 19362 19363For all components of an elementary type, the only restriction on component 19364clauses is that the size must be at least the @code{'Size} value of the type 19365(actually the Value_Size). There are no restrictions due to alignment, 19366and such components may freely cross storage boundaries. 19367 19368Packed arrays with a size up to and including 64 bits on 32-bit targets, 19369and up to and including 128 bits on 64-bit targets, are represented 19370internally using a modular type with the appropriate number of bits, and 19371thus the same lack of restriction applies. For example, if you declare: 19372 19373@example 19374type R is array (1 .. 49) of Boolean; 19375pragma Pack (R); 19376for R'Size use 49; 19377@end example 19378 19379then a component clause for a component of type @code{R} may start on any 19380specified bit boundary, and may specify a value of 49 bits or greater. 19381 19382For packed bit arrays that are longer than 64 bits on 32-bit targets, 19383and longer than 128 bits on 64-bit targets, there are two cases. If the 19384component size is a power of 2 (1,2,4,8,16,32,64 bits), including the 19385important case of single bits or boolean values, then there are no 19386limitations on placement of such components, and they may start and 19387end at arbitrary bit boundaries. 19388 19389If the component size is not a power of 2 (e.g., 3 or 5), then an array 19390of this type must always be placed on on a storage unit (byte) boundary 19391and occupy an integral number of storage units (bytes). Any component 19392clause that does not meet this requirement will be rejected. 19393 19394Any aliased component, or component of an aliased type, must have its 19395normal alignment and size. A component clause that does not meet this 19396requirement will be rejected. 19397 19398The tag field of a tagged type always occupies an address sized field at 19399the start of the record. No component clause may attempt to overlay this 19400tag. When a tagged type appears as a component, the tag field must have 19401proper alignment 19402 19403In the case of a record extension @code{T1}, of a type @code{T}, no component 19404clause applied to the type @code{T1} can specify a storage location that 19405would overlap the first @code{T'Object_Size} bits of the record. 19406 19407For all other component types, including non-bit-packed arrays, 19408the component can be placed at an arbitrary bit boundary, 19409so for example, the following is permitted: 19410 19411@example 19412type R is array (1 .. 10) of Boolean; 19413for R'Size use 80; 19414 19415type Q is record 19416 G, H : Boolean; 19417 L, M : R; 19418end record; 19419 19420for Q use record 19421 G at 0 range 0 .. 0; 19422 H at 0 range 1 .. 1; 19423 L at 0 range 2 .. 81; 19424 R at 0 range 82 .. 161; 19425end record; 19426@end example 19427 19428@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas 19429@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{290}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{291} 19430@section Handling of Records with Holes 19431 19432 19433@geindex Handling of Records with Holes 19434 19435As a result of alignment considerations, records may contain "holes" 19436or gaps which do not correspond to the data bits of any of the components. 19437Record representation clauses can also result in holes in records. 19438 19439GNAT does not attempt to clear these holes, so in record objects, 19440they should be considered to hold undefined rubbish. The generated 19441equality routine just tests components so does not access these 19442undefined bits, and assignment and copy operations may or may not 19443preserve the contents of these holes (for assignments, the holes 19444in the target will in practice contain either the bits that are 19445present in the holes in the source, or the bits that were present 19446in the target before the assignment). 19447 19448If it is necessary to ensure that holes in records have all zero 19449bits, then record objects for which this initialization is desired 19450should be explicitly set to all zero values using Unchecked_Conversion 19451or address overlays. For example 19452 19453@example 19454type HRec is record 19455 C : Character; 19456 I : Integer; 19457end record; 19458@end example 19459 19460On typical machines, integers need to be aligned on a four-byte 19461boundary, resulting in three bytes of undefined rubbish following 19462the 8-bit field for C. To ensure that the hole in a variable of 19463type HRec is set to all zero bits, 19464you could for example do: 19465 19466@example 19467type Base is record 19468 Dummy1, Dummy2 : Integer := 0; 19469end record; 19470 19471BaseVar : Base; 19472RealVar : Hrec; 19473for RealVar'Address use BaseVar'Address; 19474@end example 19475 19476Now the 8-bytes of the value of RealVar start out containing all zero 19477bits. A safer approach is to just define dummy fields, avoiding the 19478holes, as in: 19479 19480@example 19481type HRec is record 19482 C : Character; 19483 Dummy1 : Short_Short_Integer := 0; 19484 Dummy2 : Short_Short_Integer := 0; 19485 Dummy3 : Short_Short_Integer := 0; 19486 I : Integer; 19487end record; 19488@end example 19489 19490And to make absolutely sure that the intent of this is followed, you 19491can use representation clauses: 19492 19493@example 19494for Hrec use record 19495 C at 0 range 0 .. 7; 19496 Dummy1 at 1 range 0 .. 7; 19497 Dummy2 at 2 range 0 .. 7; 19498 Dummy3 at 3 range 0 .. 7; 19499 I at 4 range 0 .. 31; 19500end record; 19501for Hrec'Size use 64; 19502@end example 19503 19504@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas 19505@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{292}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{293} 19506@section Enumeration Clauses 19507 19508 19509The only restriction on enumeration clauses is that the range of values 19510must be representable. For the signed case, if one or more of the 19511representation values are negative, all values must be in the range: 19512 19513@example 19514System.Min_Int .. System.Max_Int 19515@end example 19516 19517For the unsigned case, where all values are nonnegative, the values must 19518be in the range: 19519 19520@example 195210 .. System.Max_Binary_Modulus; 19522@end example 19523 19524A @emph{confirming} representation clause is one in which the values range 19525from 0 in sequence, i.e., a clause that confirms the default representation 19526for an enumeration type. 19527Such a confirming representation 19528is permitted by these rules, and is specially recognized by the compiler so 19529that no extra overhead results from the use of such a clause. 19530 19531If an array has an index type which is an enumeration type to which an 19532enumeration clause has been applied, then the array is stored in a compact 19533manner. Consider the declarations: 19534 19535@example 19536type r is (A, B, C); 19537for r use (A => 1, B => 5, C => 10); 19538type t is array (r) of Character; 19539@end example 19540 19541The array type t corresponds to a vector with exactly three elements and 19542has a default size equal to @code{3*Character'Size}. This ensures efficient 19543use of space, but means that accesses to elements of the array will incur 19544the overhead of converting representation values to the corresponding 19545positional values, (i.e., the value delivered by the @code{Pos} attribute). 19546 19547@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas 19548@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{294}@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{295} 19549@section Address Clauses 19550 19551 19552@geindex Address Clause 19553 19554The reference manual allows a general restriction on representation clauses, 19555as found in RM 13.1(22): 19556 19557@quotation 19558 19559"An implementation need not support representation 19560items containing nonstatic expressions, except that 19561an implementation should support a representation item 19562for a given entity if each nonstatic expression in the 19563representation item is a name that statically denotes 19564a constant declared before the entity." 19565@end quotation 19566 19567In practice this is applicable only to address clauses, since this is the 19568only case in which a nonstatic expression is permitted by the syntax. As 19569the AARM notes in sections 13.1 (22.a-22.h): 19570 19571@quotation 19572 1957322.a Reason: This is to avoid the following sort of thing: 19574 1957522.b X : Integer := F(...); 19576Y : Address := G(...); 19577for X'Address use Y; 19578 1957922.c In the above, we have to evaluate the 19580initialization expression for X before we 19581know where to put the result. This seems 19582like an unreasonable implementation burden. 19583 1958422.d The above code should instead be written 19585like this: 19586 1958722.e Y : constant Address := G(...); 19588X : Integer := F(...); 19589for X'Address use Y; 19590 1959122.f This allows the expression 'Y' to be safely 19592evaluated before X is created. 19593 1959422.g The constant could be a formal parameter of mode in. 19595 1959622.h An implementation can support other nonstatic 19597expressions if it wants to. Expressions of type 19598Address are hardly ever static, but their value 19599might be known at compile time anyway in many 19600cases. 19601@end quotation 19602 19603GNAT does indeed permit many additional cases of nonstatic expressions. In 19604particular, if the type involved is elementary there are no restrictions 19605(since in this case, holding a temporary copy of the initialization value, 19606if one is present, is inexpensive). In addition, if there is no implicit or 19607explicit initialization, then there are no restrictions. GNAT will reject 19608only the case where all three of these conditions hold: 19609 19610 19611@itemize * 19612 19613@item 19614The type of the item is non-elementary (e.g., a record or array). 19615 19616@item 19617There is explicit or implicit initialization required for the object. 19618Note that access values are always implicitly initialized. 19619 19620@item 19621The address value is nonstatic. Here GNAT is more permissive than the 19622RM, and allows the address value to be the address of a previously declared 19623stand-alone variable, as long as it does not itself have an address clause. 19624 19625@example 19626Anchor : Some_Initialized_Type; 19627Overlay : Some_Initialized_Type; 19628for Overlay'Address use Anchor'Address; 19629@end example 19630 19631However, the prefix of the address clause cannot be an array component, or 19632a component of a discriminated record. 19633@end itemize 19634 19635As noted above in section 22.h, address values are typically nonstatic. In 19636particular the To_Address function, even if applied to a literal value, is 19637a nonstatic function call. To avoid this minor annoyance, GNAT provides 19638the implementation defined attribute 'To_Address. The following two 19639expressions have identical values: 19640 19641@geindex Attribute 19642 19643@geindex To_Address 19644 19645@example 19646To_Address (16#1234_0000#) 19647System'To_Address (16#1234_0000#); 19648@end example 19649 19650except that the second form is considered to be a static expression, and 19651thus when used as an address clause value is always permitted. 19652 19653Additionally, GNAT treats as static an address clause that is an 19654unchecked_conversion of a static integer value. This simplifies the porting 19655of legacy code, and provides a portable equivalent to the GNAT attribute 19656@code{To_Address}. 19657 19658Another issue with address clauses is the interaction with alignment 19659requirements. When an address clause is given for an object, the address 19660value must be consistent with the alignment of the object (which is usually 19661the same as the alignment of the type of the object). If an address clause 19662is given that specifies an inappropriately aligned address value, then the 19663program execution is erroneous. 19664 19665Since this source of erroneous behavior can have unfortunate effects on 19666machines with strict alignment requirements, GNAT 19667checks (at compile time if possible, generating a warning, or at execution 19668time with a run-time check) that the alignment is appropriate. If the 19669run-time check fails, then @code{Program_Error} is raised. This run-time 19670check is suppressed if range checks are suppressed, or if the special GNAT 19671check Alignment_Check is suppressed, or if 19672@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also 19673suppressed by default on non-strict alignment machines (such as the x86). 19674 19675Finally, GNAT does not permit overlaying of objects of class-wide types. In 19676most cases, the compiler can detect an attempt at such overlays and will 19677generate a warning at compile time and a Program_Error exception at run time. 19678 19679@geindex Export 19680 19681An address clause cannot be given for an exported object. More 19682understandably the real restriction is that objects with an address 19683clause cannot be exported. This is because such variables are not 19684defined by the Ada program, so there is no external object to export. 19685 19686@geindex Import 19687 19688It is permissible to give an address clause and a pragma Import for the 19689same object. In this case, the variable is not really defined by the 19690Ada program, so there is no external symbol to be linked. The link name 19691and the external name are ignored in this case. The reason that we allow this 19692combination is that it provides a useful idiom to avoid unwanted 19693initializations on objects with address clauses. 19694 19695When an address clause is given for an object that has implicit or 19696explicit initialization, then by default initialization takes place. This 19697means that the effect of the object declaration is to overwrite the 19698memory at the specified address. This is almost always not what the 19699programmer wants, so GNAT will output a warning: 19700 19701@example 19702with System; 19703package G is 19704 type R is record 19705 M : Integer := 0; 19706 end record; 19707 19708 Ext : R; 19709 for Ext'Address use System'To_Address (16#1234_1234#); 19710 | 19711>>> warning: implicit initialization of "Ext" may 19712 modify overlaid storage 19713>>> warning: use pragma Import for "Ext" to suppress 19714 initialization (RM B(24)) 19715 19716end G; 19717@end example 19718 19719As indicated by the warning message, the solution is to use a (dummy) pragma 19720Import to suppress this initialization. The pragma tell the compiler that the 19721object is declared and initialized elsewhere. The following package compiles 19722without warnings (and the initialization is suppressed): 19723 19724@example 19725with System; 19726package G is 19727 type R is record 19728 M : Integer := 0; 19729 end record; 19730 19731 Ext : R; 19732 for Ext'Address use System'To_Address (16#1234_1234#); 19733 pragma Import (Ada, Ext); 19734end G; 19735@end example 19736 19737A final issue with address clauses involves their use for overlaying 19738variables, as in the following example: 19739 19740@geindex Overlaying of objects 19741 19742@example 19743A : Integer; 19744B : Integer; 19745for B'Address use A'Address; 19746@end example 19747 19748or alternatively, using the form recommended by the RM: 19749 19750@example 19751A : Integer; 19752Addr : constant Address := A'Address; 19753B : Integer; 19754for B'Address use Addr; 19755@end example 19756 19757In both of these cases, @code{A} and @code{B} become aliased to one another 19758via the address clause. This use of address clauses to overlay 19759variables, achieving an effect similar to unchecked conversion 19760was erroneous in Ada 83, but in Ada 95 and Ada 2005 19761the effect is implementation defined. Furthermore, the 19762Ada RM specifically recommends that in a situation 19763like this, @code{B} should be subject to the following 19764implementation advice (RM 13.3(19)): 19765 19766@quotation 19767 19768"19 If the Address of an object is specified, or it is imported 19769or exported, then the implementation should not perform 19770optimizations based on assumptions of no aliases." 19771@end quotation 19772 19773GNAT follows this recommendation, and goes further by also applying 19774this recommendation to the overlaid variable (@code{A} in the above example) 19775in this case. This means that the overlay works "as expected", in that 19776a modification to one of the variables will affect the value of the other. 19777 19778More generally, GNAT interprets this recommendation conservatively for 19779address clauses: in the cases other than overlays, it considers that the 19780object is effectively subject to pragma @code{Volatile} and implements the 19781associated semantics. 19782 19783Note that when address clause overlays are used in this way, there is an 19784issue of unintentional initialization, as shown by this example: 19785 19786@example 19787package Overwrite_Record is 19788 type R is record 19789 A : Character := 'C'; 19790 B : Character := 'A'; 19791 end record; 19792 X : Short_Integer := 3; 19793 Y : R; 19794 for Y'Address use X'Address; 19795 | 19796>>> warning: default initialization of "Y" may 19797 modify "X", use pragma Import for "Y" to 19798 suppress initialization (RM B.1(24)) 19799 19800end Overwrite_Record; 19801@end example 19802 19803Here the default initialization of @code{Y} will clobber the value 19804of @code{X}, which justifies the warning. The warning notes that 19805this effect can be eliminated by adding a @code{pragma Import} 19806which suppresses the initialization: 19807 19808@example 19809package Overwrite_Record is 19810 type R is record 19811 A : Character := 'C'; 19812 B : Character := 'A'; 19813 end record; 19814 X : Short_Integer := 3; 19815 Y : R; 19816 for Y'Address use X'Address; 19817 pragma Import (Ada, Y); 19818end Overwrite_Record; 19819@end example 19820 19821Note that the use of @code{pragma Initialize_Scalars} may cause variables to 19822be initialized when they would not otherwise have been in the absence 19823of the use of this pragma. This may cause an overlay to have this 19824unintended clobbering effect. The compiler avoids this for scalar 19825types, but not for composite objects (where in general the effect 19826of @code{Initialize_Scalars} is part of the initialization routine 19827for the composite object: 19828 19829@example 19830pragma Initialize_Scalars; 19831with Ada.Text_IO; use Ada.Text_IO; 19832procedure Overwrite_Array is 19833 type Arr is array (1 .. 5) of Integer; 19834 X : Arr := (others => 1); 19835 A : Arr; 19836 for A'Address use X'Address; 19837 | 19838>>> warning: default initialization of "A" may 19839 modify "X", use pragma Import for "A" to 19840 suppress initialization (RM B.1(24)) 19841 19842begin 19843 if X /= Arr'(others => 1) then 19844 Put_Line ("X was clobbered"); 19845 else 19846 Put_Line ("X was not clobbered"); 19847 end if; 19848end Overwrite_Array; 19849@end example 19850 19851The above program generates the warning as shown, and at execution 19852time, prints @code{X was clobbered}. If the @code{pragma Import} is 19853added as suggested: 19854 19855@example 19856pragma Initialize_Scalars; 19857with Ada.Text_IO; use Ada.Text_IO; 19858procedure Overwrite_Array is 19859 type Arr is array (1 .. 5) of Integer; 19860 X : Arr := (others => 1); 19861 A : Arr; 19862 for A'Address use X'Address; 19863 pragma Import (Ada, A); 19864begin 19865 if X /= Arr'(others => 1) then 19866 Put_Line ("X was clobbered"); 19867 else 19868 Put_Line ("X was not clobbered"); 19869 end if; 19870end Overwrite_Array; 19871@end example 19872 19873then the program compiles without the warning and when run will generate 19874the output @code{X was not clobbered}. 19875 19876@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas 19877@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{296}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{297} 19878@section Use of Address Clauses for Memory-Mapped I/O 19879 19880 19881@geindex Memory-mapped I/O 19882 19883A common pattern is to use an address clause to map an atomic variable to 19884a location in memory that corresponds to a memory-mapped I/O operation or 19885operations, for example: 19886 19887@example 19888type Mem_Word is record 19889 A,B,C,D : Byte; 19890end record; 19891pragma Atomic (Mem_Word); 19892for Mem_Word_Size use 32; 19893 19894Mem : Mem_Word; 19895for Mem'Address use some-address; 19896... 19897Temp := Mem; 19898Temp.A := 32; 19899Mem := Temp; 19900@end example 19901 19902For a full access (reference or modification) of the variable (Mem) in this 19903case, as in the above examples, GNAT guarantees that the entire atomic word 19904will be accessed, in accordance with the RM C.6(15) clause. 19905 19906A problem arises with a component access such as: 19907 19908@example 19909Mem.A := 32; 19910@end example 19911 19912Note that the component A is not declared as atomic. This means that it is 19913not clear what this assignment means. It could correspond to full word read 19914and write as given in the first example, or on architectures that supported 19915such an operation it might be a single byte store instruction. The RM does 19916not have anything to say in this situation, and GNAT does not make any 19917guarantee. The code generated may vary from target to target. GNAT will issue 19918a warning in such a case: 19919 19920@example 19921Mem.A := 32; 19922| 19923>>> warning: access to non-atomic component of atomic array, 19924 may cause unexpected accesses to atomic object 19925@end example 19926 19927It is best to be explicit in this situation, by either declaring the 19928components to be atomic if you want the byte store, or explicitly writing 19929the full word access sequence if that is what the hardware requires. 19930Alternatively, if the full word access sequence is required, GNAT also 19931provides the pragma @code{Volatile_Full_Access} which can be used in lieu of 19932pragma @code{Atomic} and will give the additional guarantee. 19933 19934@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas 19935@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{298}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{299} 19936@section Effect of Convention on Representation 19937 19938 19939@geindex Convention 19940@geindex effect on representation 19941 19942Normally the specification of a foreign language convention for a type or 19943an object has no effect on the chosen representation. In particular, the 19944representation chosen for data in GNAT generally meets the standard system 19945conventions, and for example records are laid out in a manner that is 19946consistent with C. This means that specifying convention C (for example) 19947has no effect. 19948 19949There are four exceptions to this general rule: 19950 19951 19952@itemize * 19953 19954@item 19955@emph{Convention Fortran and array subtypes}. 19956 19957If pragma Convention Fortran is specified for an array subtype, then in 19958accordance with the implementation advice in section 3.6.2(11) of the 19959Ada Reference Manual, the array will be stored in a Fortran-compatible 19960column-major manner, instead of the normal default row-major order. 19961 19962@item 19963@emph{Convention C and enumeration types} 19964 19965GNAT normally stores enumeration types in 8, 16, or 32 bits as required 19966to accommodate all values of the type. For example, for the enumeration 19967type declared by: 19968 19969@example 19970type Color is (Red, Green, Blue); 19971@end example 19972 199738 bits is sufficient to store all values of the type, so by default, objects 19974of type @code{Color} will be represented using 8 bits. However, normal C 19975convention is to use 32 bits for all enum values in C, since enum values 19976are essentially of type int. If pragma @code{Convention C} is specified for an 19977Ada enumeration type, then the size is modified as necessary (usually to 1997832 bits) to be consistent with the C convention for enum values. 19979 19980Note that this treatment applies only to types. If Convention C is given for 19981an enumeration object, where the enumeration type is not Convention C, then 19982Object_Size bits are allocated. For example, for a normal enumeration type, 19983with less than 256 elements, only 8 bits will be allocated for the object. 19984Since this may be a surprise in terms of what C expects, GNAT will issue a 19985warning in this situation. The warning can be suppressed by giving an explicit 19986size clause specifying the desired size. 19987 19988@item 19989@emph{Convention C/Fortran and Boolean types} 19990 19991In C, the usual convention for boolean values, that is values used for 19992conditions, is that zero represents false, and nonzero values represent 19993true. In Ada, the normal convention is that two specific values, typically 199940/1, are used to represent false/true respectively. 19995 19996Fortran has a similar convention for @code{LOGICAL} values (any nonzero 19997value represents true). 19998 19999To accommodate the Fortran and C conventions, if a pragma Convention specifies 20000C or Fortran convention for a derived Boolean, as in the following example: 20001 20002@example 20003type C_Switch is new Boolean; 20004pragma Convention (C, C_Switch); 20005@end example 20006 20007then the GNAT generated code will treat any nonzero value as true. For truth 20008values generated by GNAT, the conventional value 1 will be used for True, but 20009when one of these values is read, any nonzero value is treated as True. 20010@end itemize 20011 20012@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas 20013@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{29a}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{29b} 20014@section Conventions and Anonymous Access Types 20015 20016 20017@geindex Anonymous access types 20018 20019@geindex Convention for anonymous access types 20020 20021The RM is not entirely clear on convention handling in a number of cases, 20022and in particular, it is not clear on the convention to be given to 20023anonymous access types in general, and in particular what is to be 20024done for the case of anonymous access-to-subprogram. 20025 20026In GNAT, we decide that if an explicit Convention is applied 20027to an object or component, and its type is such an anonymous type, 20028then the convention will apply to this anonymous type as well. This 20029seems to make sense since it is anomolous in any case to have a 20030different convention for an object and its type, and there is clearly 20031no way to explicitly specify a convention for an anonymous type, since 20032it doesn't have a name to specify! 20033 20034Furthermore, we decide that if a convention is applied to a record type, 20035then this convention is inherited by any of its components that are of an 20036anonymous access type which do not have an explicitly specified convention. 20037 20038The following program shows these conventions in action: 20039 20040@example 20041package ConvComp is 20042 type Foo is range 1 .. 10; 20043 type T1 is record 20044 A : access function (X : Foo) return Integer; 20045 B : Integer; 20046 end record; 20047 pragma Convention (C, T1); 20048 20049 type T2 is record 20050 A : access function (X : Foo) return Integer; 20051 pragma Convention (C, A); 20052 B : Integer; 20053 end record; 20054 pragma Convention (COBOL, T2); 20055 20056 type T3 is record 20057 A : access function (X : Foo) return Integer; 20058 pragma Convention (COBOL, A); 20059 B : Integer; 20060 end record; 20061 pragma Convention (C, T3); 20062 20063 type T4 is record 20064 A : access function (X : Foo) return Integer; 20065 B : Integer; 20066 end record; 20067 pragma Convention (COBOL, T4); 20068 20069 function F (X : Foo) return Integer; 20070 pragma Convention (C, F); 20071 20072 function F (X : Foo) return Integer is (13); 20073 20074 TV1 : T1 := (F'Access, 12); -- OK 20075 TV2 : T2 := (F'Access, 13); -- OK 20076 20077 TV3 : T3 := (F'Access, 13); -- ERROR 20078 | 20079>>> subprogram "F" has wrong convention 20080>>> does not match access to subprogram declared at line 17 20081 38. TV4 : T4 := (F'Access, 13); -- ERROR 20082 | 20083>>> subprogram "F" has wrong convention 20084>>> does not match access to subprogram declared at line 24 20085 39. end ConvComp; 20086@end example 20087 20088@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas 20089@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{29c}@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{29d} 20090@section Determining the Representations chosen by GNAT 20091 20092 20093@geindex Representation 20094@geindex determination of 20095 20096@geindex -gnatR (gcc) 20097 20098Although the descriptions in this section are intended to be complete, it is 20099often easier to simply experiment to see what GNAT accepts and what the 20100effect is on the layout of types and objects. 20101 20102As required by the Ada RM, if a representation clause is not accepted, then 20103it must be rejected as illegal by the compiler. However, when a 20104representation clause or pragma is accepted, there can still be questions 20105of what the compiler actually does. For example, if a partial record 20106representation clause specifies the location of some components and not 20107others, then where are the non-specified components placed? Or if pragma 20108@code{Pack} is used on a record, then exactly where are the resulting 20109fields placed? The section on pragma @code{Pack} in this chapter can be 20110used to answer the second question, but it is often easier to just see 20111what the compiler does. 20112 20113For this purpose, GNAT provides the option @emph{-gnatR}. If you compile 20114with this option, then the compiler will output information on the actual 20115representations chosen, in a format similar to source representation 20116clauses. For example, if we compile the package: 20117 20118@example 20119package q is 20120 type r (x : boolean) is tagged record 20121 case x is 20122 when True => S : String (1 .. 100); 20123 when False => null; 20124 end case; 20125 end record; 20126 20127 type r2 is new r (false) with record 20128 y2 : integer; 20129 end record; 20130 20131 for r2 use record 20132 y2 at 16 range 0 .. 31; 20133 end record; 20134 20135 type x is record 20136 y : character; 20137 end record; 20138 20139 type x1 is array (1 .. 10) of x; 20140 for x1'component_size use 11; 20141 20142 type ia is access integer; 20143 20144 type Rb1 is array (1 .. 13) of Boolean; 20145 pragma Pack (rb1); 20146 20147 type Rb2 is array (1 .. 65) of Boolean; 20148 pragma Pack (rb2); 20149 20150 type x2 is record 20151 l1 : Boolean; 20152 l2 : Duration; 20153 l3 : Float; 20154 l4 : Boolean; 20155 l5 : Rb1; 20156 l6 : Rb2; 20157 end record; 20158 pragma Pack (x2); 20159end q; 20160@end example 20161 20162using the switch @emph{-gnatR} we obtain the following output: 20163 20164@example 20165Representation information for unit q 20166------------------------------------- 20167 20168for r'Size use ??; 20169for r'Alignment use 4; 20170for r use record 20171 x at 4 range 0 .. 7; 20172 _tag at 0 range 0 .. 31; 20173 s at 5 range 0 .. 799; 20174end record; 20175 20176for r2'Size use 160; 20177for r2'Alignment use 4; 20178for r2 use record 20179 x at 4 range 0 .. 7; 20180 _tag at 0 range 0 .. 31; 20181 _parent at 0 range 0 .. 63; 20182 y2 at 16 range 0 .. 31; 20183end record; 20184 20185for x'Size use 8; 20186for x'Alignment use 1; 20187for x use record 20188 y at 0 range 0 .. 7; 20189end record; 20190 20191for x1'Size use 112; 20192for x1'Alignment use 1; 20193for x1'Component_Size use 11; 20194 20195for rb1'Size use 13; 20196for rb1'Alignment use 2; 20197for rb1'Component_Size use 1; 20198 20199for rb2'Size use 72; 20200for rb2'Alignment use 1; 20201for rb2'Component_Size use 1; 20202 20203for x2'Size use 224; 20204for x2'Alignment use 4; 20205for x2 use record 20206 l1 at 0 range 0 .. 0; 20207 l2 at 0 range 1 .. 64; 20208 l3 at 12 range 0 .. 31; 20209 l4 at 16 range 0 .. 0; 20210 l5 at 16 range 1 .. 13; 20211 l6 at 18 range 0 .. 71; 20212end record; 20213@end example 20214 20215The Size values are actually the Object_Size, i.e., the default size that 20216will be allocated for objects of the type. 20217The @code{??} size for type r indicates that we have a variant record, and the 20218actual size of objects will depend on the discriminant value. 20219 20220The Alignment values show the actual alignment chosen by the compiler 20221for each record or array type. 20222 20223The record representation clause for type r shows where all fields 20224are placed, including the compiler generated tag field (whose location 20225cannot be controlled by the programmer). 20226 20227The record representation clause for the type extension r2 shows all the 20228fields present, including the parent field, which is a copy of the fields 20229of the parent type of r2, i.e., r1. 20230 20231The component size and size clauses for types rb1 and rb2 show 20232the exact effect of pragma @code{Pack} on these arrays, and the record 20233representation clause for type x2 shows how pragma @cite{Pack} affects 20234this record type. 20235 20236In some cases, it may be useful to cut and paste the representation clauses 20237generated by the compiler into the original source to fix and guarantee 20238the actual representation to be used. 20239 20240@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top 20241@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}@anchor{gnat_rm/standard_library_routines doc}@anchor{29e}@anchor{gnat_rm/standard_library_routines id1}@anchor{29f} 20242@chapter Standard Library Routines 20243 20244 20245The Ada Reference Manual contains in Annex A a full description of an 20246extensive set of standard library routines that can be used in any Ada 20247program, and which must be provided by all Ada compilers. They are 20248analogous to the standard C library used by C programs. 20249 20250GNAT implements all of the facilities described in annex A, and for most 20251purposes the description in the Ada Reference Manual, or appropriate Ada 20252text book, will be sufficient for making use of these facilities. 20253 20254In the case of the input-output facilities, 20255@ref{f,,The Implementation of Standard I/O}, 20256gives details on exactly how GNAT interfaces to the 20257file system. For the remaining packages, the Ada Reference Manual 20258should be sufficient. The following is a list of the packages included, 20259together with a brief description of the functionality that is provided. 20260 20261For completeness, references are included to other predefined library 20262routines defined in other sections of the Ada Reference Manual (these are 20263cross-indexed from Annex A). For further details see the relevant 20264package declarations in the run-time library. In particular, a few units 20265are not implemented, as marked by the presence of pragma Unimplemented_Unit, 20266and in this case the package declaration contains comments explaining why 20267the unit is not implemented. 20268 20269 20270@table @asis 20271 20272@item @code{Ada} @emph{(A.2)} 20273 20274This is a parent package for all the standard library packages. It is 20275usually included implicitly in your program, and itself contains no 20276useful data or routines. 20277 20278@item @code{Ada.Assertions} @emph{(11.4.2)} 20279 20280@code{Assertions} provides the @code{Assert} subprograms, and also 20281the declaration of the @code{Assertion_Error} exception. 20282 20283@item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)} 20284 20285@code{Asynchronous_Task_Control} provides low level facilities for task 20286synchronization. It is typically not implemented. See package spec for details. 20287 20288@item @code{Ada.Calendar} @emph{(9.6)} 20289 20290@code{Calendar} provides time of day access, and routines for 20291manipulating times and durations. 20292 20293@item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)} 20294 20295This package provides additional arithmetic 20296operations for @code{Calendar}. 20297 20298@item @code{Ada.Calendar.Formatting} @emph{(9.6.1)} 20299 20300This package provides formatting operations for @code{Calendar}. 20301 20302@item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)} 20303 20304This package provides additional @code{Calendar} facilities 20305for handling time zones. 20306 20307@item @code{Ada.Characters} @emph{(A.3.1)} 20308 20309This is a dummy parent package that contains no useful entities 20310 20311@item @code{Ada.Characters.Conversions} @emph{(A.3.2)} 20312 20313This package provides character conversion functions. 20314 20315@item @code{Ada.Characters.Handling} @emph{(A.3.2)} 20316 20317This package provides some basic character handling capabilities, 20318including classification functions for classes of characters (e.g., test 20319for letters, or digits). 20320 20321@item @code{Ada.Characters.Latin_1} @emph{(A.3.3)} 20322 20323This package includes a complete set of definitions of the characters 20324that appear in type CHARACTER. It is useful for writing programs that 20325will run in international environments. For example, if you want an 20326upper case E with an acute accent in a string, it is often better to use 20327the definition of @code{UC_E_Acute} in this package. Then your program 20328will print in an understandable manner even if your environment does not 20329support these extended characters. 20330 20331@item @code{Ada.Command_Line} @emph{(A.15)} 20332 20333This package provides access to the command line parameters and the name 20334of the current program (analogous to the use of @code{argc} and @code{argv} 20335in C), and also allows the exit status for the program to be set in a 20336system-independent manner. 20337 20338@item @code{Ada.Complex_Text_IO} @emph{(G.1.3)} 20339 20340This package provides text input and output of complex numbers. 20341 20342@item @code{Ada.Containers} @emph{(A.18.1)} 20343 20344A top level package providing a few basic definitions used by all the 20345following specific child packages that provide specific kinds of 20346containers. 20347@end table 20348 20349@code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)} 20350 20351@code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)} 20352 20353@code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)} 20354 20355@code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)} 20356 20357@code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)} 20358 20359@code{Ada.Containers.Generic_Sort} @emph{(A.18.26)} 20360 20361@code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)} 20362 20363@code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)} 20364 20365@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)} 20366 20367@code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)} 20368 20369@code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)} 20370 20371@code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)} 20372 20373@code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)} 20374 20375@code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)} 20376 20377@code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)} 20378 20379@code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)} 20380 20381@code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)} 20382 20383@code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)} 20384 20385@code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)} 20386 20387@code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)} 20388 20389@code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)} 20390 20391@code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)} 20392 20393@code{Ada.Containers.Vectors} @emph{(A.18.2)} 20394 20395 20396@table @asis 20397 20398@item @code{Ada.Directories} @emph{(A.16)} 20399 20400This package provides operations on directories. 20401 20402@item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)} 20403 20404This package provides additional directory operations handling 20405hiearchical file names. 20406 20407@item @code{Ada.Directories.Information} @emph{(A.16)} 20408 20409This is an implementation defined package for additional directory 20410operations, which is not implemented in GNAT. 20411 20412@item @code{Ada.Decimal} @emph{(F.2)} 20413 20414This package provides constants describing the range of decimal numbers 20415implemented, and also a decimal divide routine (analogous to the COBOL 20416verb DIVIDE ... GIVING ... REMAINDER ...) 20417 20418@item @code{Ada.Direct_IO} @emph{(A.8.4)} 20419 20420This package provides input-output using a model of a set of records of 20421fixed-length, containing an arbitrary definite Ada type, indexed by an 20422integer record number. 20423 20424@item @code{Ada.Dispatching} @emph{(D.2.1)} 20425 20426A parent package containing definitions for task dispatching operations. 20427 20428@item @code{Ada.Dispatching.EDF} @emph{(D.2.6)} 20429 20430Not implemented in GNAT. 20431 20432@item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)} 20433 20434Not implemented in GNAT. 20435 20436@item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)} 20437 20438Not implemented in GNAT. 20439 20440@item @code{Ada.Dynamic_Priorities} @emph{(D.5)} 20441 20442This package allows the priorities of a task to be adjusted dynamically 20443as the task is running. 20444 20445@item @code{Ada.Environment_Variables} @emph{(A.17)} 20446 20447This package provides facilities for accessing environment variables. 20448 20449@item @code{Ada.Exceptions} @emph{(11.4.1)} 20450 20451This package provides additional information on exceptions, and also 20452contains facilities for treating exceptions as data objects, and raising 20453exceptions with associated messages. 20454 20455@item @code{Ada.Execution_Time} @emph{(D.14)} 20456 20457This package provides CPU clock functionalities. It is not implemented on 20458all targets (see package spec for details). 20459 20460@item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)} 20461 20462Not implemented in GNAT. 20463 20464@item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)'} 20465 20466Not implemented in GNAT. 20467 20468@item @code{Ada.Finalization} @emph{(7.6)} 20469 20470This package contains the declarations and subprograms to support the 20471use of controlled types, providing for automatic initialization and 20472finalization (analogous to the constructors and destructors of C++). 20473 20474@item @code{Ada.Float_Text_IO} @emph{(A.10.9)} 20475 20476A library level instantiation of Text_IO.Float_IO for type Float. 20477 20478@item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)} 20479 20480A library level instantiation of Wide_Text_IO.Float_IO for type Float. 20481 20482@item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)} 20483 20484A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. 20485 20486@item @code{Ada.Integer_Text_IO} @emph{(A.10.9)} 20487 20488A library level instantiation of Text_IO.Integer_IO for type Integer. 20489 20490@item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)} 20491 20492A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. 20493 20494@item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)} 20495 20496A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. 20497 20498@item @code{Ada.Interrupts} @emph{(C.3.2)} 20499 20500This package provides facilities for interfacing to interrupts, which 20501includes the set of signals or conditions that can be raised and 20502recognized as interrupts. 20503 20504@item @code{Ada.Interrupts.Names} @emph{(C.3.2)} 20505 20506This package provides the set of interrupt names (actually signal 20507or condition names) that can be handled by GNAT. 20508 20509@item @code{Ada.IO_Exceptions} @emph{(A.13)} 20510 20511This package defines the set of exceptions that can be raised by use of 20512the standard IO packages. 20513 20514@item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)} 20515 20516This package provides a generic interface to generalized iterators. 20517 20518@item @code{Ada.Locales} @emph{(A.19)} 20519 20520This package provides declarations providing information (Language 20521and Country) about the current locale. 20522 20523@item @code{Ada.Numerics} 20524 20525This package contains some standard constants and exceptions used 20526throughout the numerics packages. Note that the constants pi and e are 20527defined here, and it is better to use these definitions than rolling 20528your own. 20529 20530@item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)} 20531 20532Provides operations on arrays of complex numbers. 20533 20534@item @code{Ada.Numerics.Complex_Elementary_Functions} 20535 20536Provides the implementation of standard elementary functions (such as 20537log and trigonometric functions) operating on complex numbers using the 20538standard @code{Float} and the @code{Complex} and @code{Imaginary} types 20539created by the package @code{Numerics.Complex_Types}. 20540 20541@item @code{Ada.Numerics.Complex_Types} 20542 20543This is a predefined instantiation of 20544@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to 20545build the type @code{Complex} and @code{Imaginary}. 20546 20547@item @code{Ada.Numerics.Discrete_Random} 20548 20549This generic package provides a random number generator suitable for generating 20550uniformly distributed values of a specified discrete subtype. 20551 20552@item @code{Ada.Numerics.Float_Random} 20553 20554This package provides a random number generator suitable for generating 20555uniformly distributed floating point values in the unit interval. 20556 20557@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} 20558 20559This is a generic version of the package that provides the 20560implementation of standard elementary functions (such as log and 20561trigonometric functions) for an arbitrary complex type. 20562 20563The following predefined instantiations of this package are provided: 20564 20565 20566@itemize * 20567 20568@item 20569@code{Short_Float} 20570 20571@code{Ada.Numerics.Short_Complex_Elementary_Functions} 20572 20573@item 20574@code{Float} 20575 20576@code{Ada.Numerics.Complex_Elementary_Functions} 20577 20578@item 20579@code{Long_Float} 20580 20581@code{Ada.Numerics.Long_Complex_Elementary_Functions} 20582@end itemize 20583 20584@item @code{Ada.Numerics.Generic_Complex_Types} 20585 20586This is a generic package that allows the creation of complex types, 20587with associated complex arithmetic operations. 20588 20589The following predefined instantiations of this package exist 20590 20591 20592@itemize * 20593 20594@item 20595@code{Short_Float} 20596 20597@code{Ada.Numerics.Short_Complex_Complex_Types} 20598 20599@item 20600@code{Float} 20601 20602@code{Ada.Numerics.Complex_Complex_Types} 20603 20604@item 20605@code{Long_Float} 20606 20607@code{Ada.Numerics.Long_Complex_Complex_Types} 20608@end itemize 20609 20610@item @code{Ada.Numerics.Generic_Elementary_Functions} 20611 20612This is a generic package that provides the implementation of standard 20613elementary functions (such as log an trigonometric functions) for an 20614arbitrary float type. 20615 20616The following predefined instantiations of this package exist 20617 20618 20619@itemize * 20620 20621@item 20622@code{Short_Float} 20623 20624@code{Ada.Numerics.Short_Elementary_Functions} 20625 20626@item 20627@code{Float} 20628 20629@code{Ada.Numerics.Elementary_Functions} 20630 20631@item 20632@code{Long_Float} 20633 20634@code{Ada.Numerics.Long_Elementary_Functions} 20635@end itemize 20636 20637@item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)} 20638 20639Generic operations on arrays of reals 20640 20641@item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)} 20642 20643Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). 20644 20645@item @code{Ada.Real_Time} @emph{(D.8)} 20646 20647This package provides facilities similar to those of @code{Calendar}, but 20648operating with a finer clock suitable for real time control. Note that 20649annex D requires that there be no backward clock jumps, and GNAT generally 20650guarantees this behavior, but of course if the external clock on which 20651the GNAT runtime depends is deliberately reset by some external event, 20652then such a backward jump may occur. 20653 20654@item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)} 20655 20656Not implemented in GNAT. 20657 20658@item @code{Ada.Sequential_IO} @emph{(A.8.1)} 20659 20660This package provides input-output facilities for sequential files, 20661which can contain a sequence of values of a single type, which can be 20662any Ada type, including indefinite (unconstrained) types. 20663 20664@item @code{Ada.Storage_IO} @emph{(A.9)} 20665 20666This package provides a facility for mapping arbitrary Ada types to and 20667from a storage buffer. It is primarily intended for the creation of new 20668IO packages. 20669 20670@item @code{Ada.Streams} @emph{(13.13.1)} 20671 20672This is a generic package that provides the basic support for the 20673concept of streams as used by the stream attributes (@code{Input}, 20674@code{Output}, @code{Read} and @code{Write}). 20675 20676@item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)} 20677 20678This package is a specialization of the type @code{Streams} defined in 20679package @code{Streams} together with a set of operations providing 20680Stream_IO capability. The Stream_IO model permits both random and 20681sequential access to a file which can contain an arbitrary set of values 20682of one or more Ada types. 20683 20684@item @code{Ada.Strings} @emph{(A.4.1)} 20685 20686This package provides some basic constants used by the string handling 20687packages. 20688 20689@item @code{Ada.Strings.Bounded} @emph{(A.4.4)} 20690 20691This package provides facilities for handling variable length 20692strings. The bounded model requires a maximum length. It is thus 20693somewhat more limited than the unbounded model, but avoids the use of 20694dynamic allocation or finalization. 20695 20696@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)} 20697 20698Provides case-insensitive comparisons of bounded strings 20699 20700@item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)} 20701 20702This package provides a generic hash function for bounded strings 20703 20704@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)} 20705 20706This package provides a generic hash function for bounded strings that 20707converts the string to be hashed to lower case. 20708 20709@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)} 20710 20711This package provides a comparison function for bounded strings that works 20712in a case insensitive manner by converting to lower case before the comparison. 20713 20714@item @code{Ada.Strings.Fixed} @emph{(A.4.3)} 20715 20716This package provides facilities for handling fixed length strings. 20717 20718@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)} 20719 20720This package provides an equality function for fixed strings that compares 20721the strings after converting both to lower case. 20722 20723@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)} 20724 20725This package provides a case insensitive hash function for fixed strings that 20726converts the string to lower case before computing the hash. 20727 20728@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)} 20729 20730This package provides a comparison function for fixed strings that works 20731in a case insensitive manner by converting to lower case before the comparison. 20732 20733@item @code{Ada.Strings.Hash} @emph{(A.4.9)} 20734 20735This package provides a hash function for strings. 20736 20737@item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)} 20738 20739This package provides a hash function for strings that is case insensitive. 20740The string is converted to lower case before computing the hash. 20741 20742@item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)} 20743 20744This package provides a comparison function for\strings that works 20745in a case insensitive manner by converting to lower case before the comparison. 20746 20747@item @code{Ada.Strings.Maps} @emph{(A.4.2)} 20748 20749This package provides facilities for handling character mappings and 20750arbitrarily defined subsets of characters. For instance it is useful in 20751defining specialized translation tables. 20752 20753@item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)} 20754 20755This package provides a standard set of predefined mappings and 20756predefined character sets. For example, the standard upper to lower case 20757conversion table is found in this package. Note that upper to lower case 20758conversion is non-trivial if you want to take the entire set of 20759characters, including extended characters like E with an acute accent, 20760into account. You should use the mappings in this package (rather than 20761adding 32 yourself) to do case mappings. 20762 20763@item @code{Ada.Strings.Unbounded} @emph{(A.4.5)} 20764 20765This package provides facilities for handling variable length 20766strings. The unbounded model allows arbitrary length strings, but 20767requires the use of dynamic allocation and finalization. 20768 20769@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)} 20770 20771Provides case-insensitive comparisons of unbounded strings 20772 20773@item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)} 20774 20775This package provides a generic hash function for unbounded strings 20776 20777@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)} 20778 20779This package provides a generic hash function for unbounded strings that 20780converts the string to be hashed to lower case. 20781 20782@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)} 20783 20784This package provides a comparison function for unbounded strings that works 20785in a case insensitive manner by converting to lower case before the comparison. 20786 20787@item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)} 20788 20789This package provides basic definitions for dealing with UTF-encoded strings. 20790 20791@item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)} 20792 20793This package provides conversion functions for UTF-encoded strings. 20794@end table 20795 20796@code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)} 20797 20798@code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)} 20799 20800 20801@table @asis 20802 20803@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)} 20804 20805These packages provide facilities for handling UTF encodings for 20806Strings, Wide_Strings and Wide_Wide_Strings. 20807@end table 20808 20809@code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)} 20810 20811@code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)} 20812 20813@code{Ada.Strings.Wide_Maps} @emph{(A.4.7)} 20814 20815 20816@table @asis 20817 20818@item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)} 20819 20820These packages provide analogous capabilities to the corresponding 20821packages without @code{Wide_} in the name, but operate with the types 20822@code{Wide_String} and @code{Wide_Character} instead of @code{String} 20823and @code{Character}. Versions of all the child packages are available. 20824@end table 20825 20826@code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)} 20827 20828@code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)} 20829 20830@code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)} 20831 20832 20833@table @asis 20834 20835@item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)} 20836 20837These packages provide analogous capabilities to the corresponding 20838packages without @code{Wide_} in the name, but operate with the types 20839@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead 20840of @code{String} and @code{Character}. 20841 20842@item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)} 20843 20844This package provides facilities for synchronizing tasks at a low level 20845with barriers. 20846 20847@item @code{Ada.Synchronous_Task_Control} @emph{(D.10)} 20848 20849This package provides some standard facilities for controlling task 20850communication in a synchronous manner. 20851 20852@item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)} 20853 20854Not implemented in GNAT. 20855 20856@item @code{Ada.Tags} 20857 20858This package contains definitions for manipulation of the tags of tagged 20859values. 20860 20861@item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)} 20862 20863This package provides a way of constructing tagged class-wide values given 20864only the tag value. 20865 20866@item @code{Ada.Task_Attributes} @emph{(C.7.2)} 20867 20868This package provides the capability of associating arbitrary 20869task-specific data with separate tasks. 20870 20871@item @code{Ada.Task_Identifification} @emph{(C.7.1)} 20872 20873This package provides capabilities for task identification. 20874 20875@item @code{Ada.Task_Termination} @emph{(C.7.3)} 20876 20877This package provides control over task termination. 20878 20879@item @code{Ada.Text_IO} 20880 20881This package provides basic text input-output capabilities for 20882character, string and numeric data. The subpackages of this 20883package are listed next. Note that although these are defined 20884as subpackages in the RM, they are actually transparently 20885implemented as child packages in GNAT, meaning that they 20886are only loaded if needed. 20887 20888@item @code{Ada.Text_IO.Decimal_IO} 20889 20890Provides input-output facilities for decimal fixed-point types 20891 20892@item @code{Ada.Text_IO.Enumeration_IO} 20893 20894Provides input-output facilities for enumeration types. 20895 20896@item @code{Ada.Text_IO.Fixed_IO} 20897 20898Provides input-output facilities for ordinary fixed-point types. 20899 20900@item @code{Ada.Text_IO.Float_IO} 20901 20902Provides input-output facilities for float types. The following 20903predefined instantiations of this generic package are available: 20904 20905 20906@itemize * 20907 20908@item 20909@code{Short_Float} 20910 20911@code{Short_Float_Text_IO} 20912 20913@item 20914@code{Float} 20915 20916@code{Float_Text_IO} 20917 20918@item 20919@code{Long_Float} 20920 20921@code{Long_Float_Text_IO} 20922@end itemize 20923 20924@item @code{Ada.Text_IO.Integer_IO} 20925 20926Provides input-output facilities for integer types. The following 20927predefined instantiations of this generic package are available: 20928 20929 20930@itemize * 20931 20932@item 20933@code{Short_Short_Integer} 20934 20935@code{Ada.Short_Short_Integer_Text_IO} 20936 20937@item 20938@code{Short_Integer} 20939 20940@code{Ada.Short_Integer_Text_IO} 20941 20942@item 20943@code{Integer} 20944 20945@code{Ada.Integer_Text_IO} 20946 20947@item 20948@code{Long_Integer} 20949 20950@code{Ada.Long_Integer_Text_IO} 20951 20952@item 20953@code{Long_Long_Integer} 20954 20955@code{Ada.Long_Long_Integer_Text_IO} 20956@end itemize 20957 20958@item @code{Ada.Text_IO.Modular_IO} 20959 20960Provides input-output facilities for modular (unsigned) types. 20961 20962@item @code{Ada.Text_IO.Bounded_IO (A.10.11)} 20963 20964Provides input-output facilities for bounded strings. 20965 20966@item @code{Ada.Text_IO.Complex_IO (G.1.3)} 20967 20968This package provides basic text input-output capabilities for complex 20969data. 20970 20971@item @code{Ada.Text_IO.Editing (F.3.3)} 20972 20973This package contains routines for edited output, analogous to the use 20974of pictures in COBOL. The picture formats used by this package are a 20975close copy of the facility in COBOL. 20976 20977@item @code{Ada.Text_IO.Text_Streams (A.12.2)} 20978 20979This package provides a facility that allows Text_IO files to be treated 20980as streams, so that the stream attributes can be used for writing 20981arbitrary data, including binary data, to Text_IO files. 20982 20983@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} 20984 20985This package provides input-output facilities for unbounded strings. 20986 20987@item @code{Ada.Unchecked_Conversion (13.9)} 20988 20989This generic package allows arbitrary conversion from one type to 20990another of the same size, providing for breaking the type safety in 20991special circumstances. 20992 20993If the types have the same Size (more accurately the same Value_Size), 20994then the effect is simply to transfer the bits from the source to the 20995target type without any modification. This usage is well defined, and 20996for simple types whose representation is typically the same across 20997all implementations, gives a portable method of performing such 20998conversions. 20999 21000If the types do not have the same size, then the result is implementation 21001defined, and thus may be non-portable. The following describes how GNAT 21002handles such unchecked conversion cases. 21003 21004If the types are of different sizes, and are both discrete types, then 21005the effect is of a normal type conversion without any constraint checking. 21006In particular if the result type has a larger size, the result will be 21007zero or sign extended. If the result type has a smaller size, the result 21008will be truncated by ignoring high order bits. 21009 21010If the types are of different sizes, and are not both discrete types, 21011then the conversion works as though pointers were created to the source 21012and target, and the pointer value is converted. The effect is that bits 21013are copied from successive low order storage units and bits of the source 21014up to the length of the target type. 21015 21016A warning is issued if the lengths differ, since the effect in this 21017case is implementation dependent, and the above behavior may not match 21018that of some other compiler. 21019 21020A pointer to one type may be converted to a pointer to another type using 21021unchecked conversion. The only case in which the effect is undefined is 21022when one or both pointers are pointers to unconstrained array types. In 21023this case, the bounds information may get incorrectly transferred, and in 21024particular, GNAT uses double size pointers for such types, and it is 21025meaningless to convert between such pointer types. GNAT will issue a 21026warning if the alignment of the target designated type is more strict 21027than the alignment of the source designated type (since the result may 21028be unaligned in this case). 21029 21030A pointer other than a pointer to an unconstrained array type may be 21031converted to and from System.Address. Such usage is common in Ada 83 21032programs, but note that Ada.Address_To_Access_Conversions is the 21033preferred method of performing such conversions in Ada 95 and Ada 2005. 21034Neither 21035unchecked conversion nor Ada.Address_To_Access_Conversions should be 21036used in conjunction with pointers to unconstrained objects, since 21037the bounds information cannot be handled correctly in this case. 21038 21039@item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)} 21040 21041This generic package allows explicit freeing of storage previously 21042allocated by use of an allocator. 21043 21044@item @code{Ada.Wide_Text_IO} @emph{(A.11)} 21045 21046This package is similar to @code{Ada.Text_IO}, except that the external 21047file supports wide character representations, and the internal types are 21048@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21049and @code{String}. The corresponding set of nested packages and child 21050packages are defined. 21051 21052@item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)} 21053 21054This package is similar to @code{Ada.Text_IO}, except that the external 21055file supports wide character representations, and the internal types are 21056@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 21057and @code{String}. The corresponding set of nested packages and child 21058packages are defined. 21059@end table 21060 21061For packages in Interfaces and System, all the RM defined packages are 21062available in GNAT, see the Ada 2012 RM for full details. 21063 21064@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top 21065@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{2a0}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2a1} 21066@chapter The Implementation of Standard I/O 21067 21068 21069GNAT implements all the required input-output facilities described in 21070A.6 through A.14. These sections of the Ada Reference Manual describe the 21071required behavior of these packages from the Ada point of view, and if 21072you are writing a portable Ada program that does not need to know the 21073exact manner in which Ada maps to the outside world when it comes to 21074reading or writing external files, then you do not need to read this 21075chapter. As long as your files are all regular files (not pipes or 21076devices), and as long as you write and read the files only from Ada, the 21077description in the Ada Reference Manual is sufficient. 21078 21079However, if you want to do input-output to pipes or other devices, such 21080as the keyboard or screen, or if the files you are dealing with are 21081either generated by some other language, or to be read by some other 21082language, then you need to know more about the details of how the GNAT 21083implementation of these input-output facilities behaves. 21084 21085In this chapter we give a detailed description of exactly how GNAT 21086interfaces to the file system. As always, the sources of the system are 21087available to you for answering questions at an even more detailed level, 21088but for most purposes the information in this chapter will suffice. 21089 21090Another reason that you may need to know more about how input-output is 21091implemented arises when you have a program written in mixed languages 21092where, for example, files are shared between the C and Ada sections of 21093the same program. GNAT provides some additional facilities, in the form 21094of additional child library packages, that facilitate this sharing, and 21095these additional facilities are also described in this chapter. 21096 21097@menu 21098* Standard I/O Packages:: 21099* FORM Strings:: 21100* Direct_IO:: 21101* Sequential_IO:: 21102* Text_IO:: 21103* Wide_Text_IO:: 21104* Wide_Wide_Text_IO:: 21105* Stream_IO:: 21106* Text Translation:: 21107* Shared Files:: 21108* Filenames encoding:: 21109* File content encoding:: 21110* Open Modes:: 21111* Operations on C Streams:: 21112* Interfacing to C Streams:: 21113 21114@end menu 21115 21116@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O 21117@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a3} 21118@section Standard I/O Packages 21119 21120 21121The Standard I/O packages described in Annex A for 21122 21123 21124@itemize * 21125 21126@item 21127Ada.Text_IO 21128 21129@item 21130Ada.Text_IO.Complex_IO 21131 21132@item 21133Ada.Text_IO.Text_Streams 21134 21135@item 21136Ada.Wide_Text_IO 21137 21138@item 21139Ada.Wide_Text_IO.Complex_IO 21140 21141@item 21142Ada.Wide_Text_IO.Text_Streams 21143 21144@item 21145Ada.Wide_Wide_Text_IO 21146 21147@item 21148Ada.Wide_Wide_Text_IO.Complex_IO 21149 21150@item 21151Ada.Wide_Wide_Text_IO.Text_Streams 21152 21153@item 21154Ada.Stream_IO 21155 21156@item 21157Ada.Sequential_IO 21158 21159@item 21160Ada.Direct_IO 21161@end itemize 21162 21163are implemented using the C 21164library streams facility; where 21165 21166 21167@itemize * 21168 21169@item 21170All files are opened using @code{fopen}. 21171 21172@item 21173All input/output operations use @code{fread}/@cite{fwrite}. 21174@end itemize 21175 21176There is no internal buffering of any kind at the Ada library level. The only 21177buffering is that provided at the system level in the implementation of the 21178library routines that support streams. This facilitates shared use of these 21179streams by mixed language programs. Note though that system level buffering is 21180explicitly enabled at elaboration of the standard I/O packages and that can 21181have an impact on mixed language programs, in particular those using I/O before 21182calling the Ada elaboration routine (e.g., adainit). It is recommended to call 21183the Ada elaboration routine before performing any I/O or when impractical, 21184flush the common I/O streams and in particular Standard_Output before 21185elaborating the Ada code. 21186 21187@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O 21188@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2a4}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2a5} 21189@section FORM Strings 21190 21191 21192The format of a FORM string in GNAT is: 21193 21194@example 21195"keyword=value,keyword=value,...,keyword=value" 21196@end example 21197 21198where letters may be in upper or lower case, and there are no spaces 21199between values. The order of the entries is not important. Currently 21200the following keywords defined. 21201 21202@example 21203TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] 21204SHARED=[YES|NO] 21205WCEM=[n|h|u|s|e|8|b] 21206ENCODING=[UTF8|8BITS] 21207@end example 21208 21209The use of these parameters is described later in this section. If an 21210unrecognized keyword appears in a form string, it is silently ignored 21211and not considered invalid. 21212 21213@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O 21214@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2a6}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a7} 21215@section Direct_IO 21216 21217 21218Direct_IO can only be instantiated for definite types. This is a 21219restriction of the Ada language, which means that the records are fixed 21220length (the length being determined by @code{type'Size}, rounded 21221up to the next storage unit boundary if necessary). 21222 21223The records of a Direct_IO file are simply written to the file in index 21224sequence, with the first record starting at offset zero, and subsequent 21225records following. There is no control information of any kind. For 21226example, if 32-bit integers are being written, each record takes 212274-bytes, so the record at index @code{K} starts at offset 21228(@code{K}-1)*4. 21229 21230There is no limit on the size of Direct_IO files, they are expanded as 21231necessary to accommodate whatever records are written to the file. 21232 21233@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O 21234@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2a8}@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2a9} 21235@section Sequential_IO 21236 21237 21238Sequential_IO may be instantiated with either a definite (constrained) 21239or indefinite (unconstrained) type. 21240 21241For the definite type case, the elements written to the file are simply 21242the memory images of the data values with no control information of any 21243kind. The resulting file should be read using the same type, no validity 21244checking is performed on input. 21245 21246For the indefinite type case, the elements written consist of two 21247parts. First is the size of the data item, written as the memory image 21248of a @code{Interfaces.C.size_t} value, followed by the memory image of 21249the data value. The resulting file can only be read using the same 21250(unconstrained) type. Normal assignment checks are performed on these 21251read operations, and if these checks fail, @code{Data_Error} is 21252raised. In particular, in the array case, the lengths must match, and in 21253the variant record case, if the variable for a particular read operation 21254is constrained, the discriminants must match. 21255 21256Note that it is not possible to use Sequential_IO to write variable 21257length array items, and then read the data back into different length 21258arrays. For example, the following will raise @code{Data_Error}: 21259 21260@example 21261package IO is new Sequential_IO (String); 21262F : IO.File_Type; 21263S : String (1..4); 21264... 21265IO.Create (F) 21266IO.Write (F, "hello!") 21267IO.Reset (F, Mode=>In_File); 21268IO.Read (F, S); 21269Put_Line (S); 21270@end example 21271 21272On some Ada implementations, this will print @code{hell}, but the program is 21273clearly incorrect, since there is only one element in the file, and that 21274element is the string @code{hello!}. 21275 21276In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved 21277using Stream_IO, and this is the preferred mechanism. In particular, the 21278above program fragment rewritten to use Stream_IO will work correctly. 21279 21280@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O 21281@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2aa}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2ab} 21282@section Text_IO 21283 21284 21285Text_IO files consist of a stream of characters containing the following 21286special control characters: 21287 21288@example 21289LF (line feed, 16#0A#) Line Mark 21290FF (form feed, 16#0C#) Page Mark 21291@end example 21292 21293A canonical Text_IO file is defined as one in which the following 21294conditions are met: 21295 21296 21297@itemize * 21298 21299@item 21300The character @code{LF} is used only as a line mark, i.e., to mark the end 21301of the line. 21302 21303@item 21304The character @code{FF} is used only as a page mark, i.e., to mark the 21305end of a page and consequently can appear only immediately following a 21306@code{LF} (line mark) character. 21307 21308@item 21309The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} 21310(line mark, page mark). In the former case, the page mark is implicitly 21311assumed to be present. 21312@end itemize 21313 21314A file written using Text_IO will be in canonical form provided that no 21315explicit @code{LF} or @code{FF} characters are written using @code{Put} 21316or @code{Put_Line}. There will be no @code{FF} character at the end of 21317the file unless an explicit @code{New_Page} operation was performed 21318before closing the file. 21319 21320A canonical Text_IO file that is a regular file (i.e., not a device or a 21321pipe) can be read using any of the routines in Text_IO. The 21322semantics in this case will be exactly as defined in the Ada Reference 21323Manual, and all the routines in Text_IO are fully implemented. 21324 21325A text file that does not meet the requirements for a canonical Text_IO 21326file has one of the following: 21327 21328 21329@itemize * 21330 21331@item 21332The file contains @code{FF} characters not immediately following a 21333@code{LF} character. 21334 21335@item 21336The file contains @code{LF} or @code{FF} characters written by 21337@code{Put} or @code{Put_Line}, which are not logically considered to be 21338line marks or page marks. 21339 21340@item 21341The file ends in a character other than @code{LF} or @code{FF}, 21342i.e., there is no explicit line mark or page mark at the end of the file. 21343@end itemize 21344 21345Text_IO can be used to read such non-standard text files but subprograms 21346to do with line or page numbers do not have defined meanings. In 21347particular, a @code{FF} character that does not follow a @code{LF} 21348character may or may not be treated as a page mark from the point of 21349view of page and line numbering. Every @code{LF} character is considered 21350to end a line, and there is an implied @code{LF} character at the end of 21351the file. 21352 21353@menu 21354* Stream Pointer Positioning:: 21355* Reading and Writing Non-Regular Files:: 21356* Get_Immediate:: 21357* Treating Text_IO Files as Streams:: 21358* Text_IO Extensions:: 21359* Text_IO Facilities for Unbounded Strings:: 21360 21361@end menu 21362 21363@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO 21364@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2ac}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ad} 21365@subsection Stream Pointer Positioning 21366 21367 21368@code{Ada.Text_IO} has a definition of current position for a file that 21369is being read. No internal buffering occurs in Text_IO, and usually the 21370physical position in the stream used to implement the file corresponds 21371to this logical position defined by Text_IO. There are two exceptions: 21372 21373 21374@itemize * 21375 21376@item 21377After a call to @code{End_Of_Page} that returns @code{True}, the stream 21378is positioned past the @code{LF} (line mark) that precedes the page 21379mark. Text_IO maintains an internal flag so that subsequent read 21380operations properly handle the logical position which is unchanged by 21381the @code{End_Of_Page} call. 21382 21383@item 21384After a call to @code{End_Of_File} that returns @code{True}, if the 21385Text_IO file was positioned before the line mark at the end of file 21386before the call, then the logical position is unchanged, but the stream 21387is physically positioned right at the end of file (past the line mark, 21388and past a possible page mark following the line mark. Again Text_IO 21389maintains internal flags so that subsequent read operations properly 21390handle the logical position. 21391@end itemize 21392 21393These discrepancies have no effect on the observable behavior of 21394Text_IO, but if a single Ada stream is shared between a C program and 21395Ada program, or shared (using @code{shared=yes} in the form string) 21396between two Ada files, then the difference may be observable in some 21397situations. 21398 21399@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO 21400@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2ae}@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2af} 21401@subsection Reading and Writing Non-Regular Files 21402 21403 21404A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 21405can be used for reading and writing. Writing is not affected and the 21406sequence of characters output is identical to the normal file case, but 21407for reading, the behavior of Text_IO is modified to avoid undesirable 21408look-ahead as follows: 21409 21410An input file that is not a regular file is considered to have no page 21411marks. Any @code{Ascii.FF} characters (the character normally used for a 21412page mark) appearing in the file are considered to be data 21413characters. In particular: 21414 21415 21416@itemize * 21417 21418@item 21419@code{Get_Line} and @code{Skip_Line} do not test for a page mark 21420following a line mark. If a page mark appears, it will be treated as a 21421data character. 21422 21423@item 21424This avoids the need to wait for an extra character to be typed or 21425entered from the pipe to complete one of these operations. 21426 21427@item 21428@code{End_Of_Page} always returns @code{False} 21429 21430@item 21431@code{End_Of_File} will return @code{False} if there is a page mark at 21432the end of the file. 21433@end itemize 21434 21435Output to non-regular files is the same as for regular files. Page marks 21436may be written to non-regular files using @code{New_Page}, but as noted 21437above they will not be treated as page marks on input if the output is 21438piped to another Ada program. 21439 21440Another important discrepancy when reading non-regular files is that the end 21441of file indication is not 'sticky'. If an end of file is entered, e.g., by 21442pressing the @code{EOT} key, 21443then end of file 21444is signaled once (i.e., the test @code{End_Of_File} 21445will yield @code{True}, or a read will 21446raise @code{End_Error}), but then reading can resume 21447to read data past that end of 21448file indication, until another end of file indication is entered. 21449 21450@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO 21451@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2b0}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2b1} 21452@subsection Get_Immediate 21453 21454 21455@geindex Get_Immediate 21456 21457Get_Immediate returns the next character (including control characters) 21458from the input file. In particular, Get_Immediate will return LF or FF 21459characters used as line marks or page marks. Such operations leave the 21460file positioned past the control character, and it is thus not treated 21461as having its normal function. This means that page, line and column 21462counts after this kind of Get_Immediate call are set as though the mark 21463did not occur. In the case where a Get_Immediate leaves the file 21464positioned between the line mark and page mark (which is not normally 21465possible), it is undefined whether the FF character will be treated as a 21466page mark. 21467 21468@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO 21469@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2b2}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2b3} 21470@subsection Treating Text_IO Files as Streams 21471 21472 21473@geindex Stream files 21474 21475The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated 21476as a stream. Data written to a @code{Text_IO} file in this stream mode is 21477binary data. If this binary data contains bytes 16#0A# (@code{LF}) or 2147816#0C# (@code{FF}), the resulting file may have non-standard 21479format. Similarly if read operations are used to read from a Text_IO 21480file treated as a stream, then @code{LF} and @code{FF} characters may be 21481skipped and the effect is similar to that described above for 21482@code{Get_Immediate}. 21483 21484@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO 21485@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2b4}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2b5} 21486@subsection Text_IO Extensions 21487 21488 21489@geindex Text_IO extensions 21490 21491A package GNAT.IO_Aux in the GNAT library provides some useful extensions 21492to the standard @code{Text_IO} package: 21493 21494 21495@itemize * 21496 21497@item 21498function File_Exists (Name : String) return Boolean; 21499Determines if a file of the given name exists. 21500 21501@item 21502function Get_Line return String; 21503Reads a string from the standard input file. The value returned is exactly 21504the length of the line that was read. 21505 21506@item 21507function Get_Line (File : Ada.Text_IO.File_Type) return String; 21508Similar, except that the parameter File specifies the file from which 21509the string is to be read. 21510@end itemize 21511 21512@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO 21513@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b6}@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b7} 21514@subsection Text_IO Facilities for Unbounded Strings 21515 21516 21517@geindex Text_IO for unbounded strings 21518 21519@geindex Unbounded_String 21520@geindex Text_IO operations 21521 21522The package @code{Ada.Strings.Unbounded.Text_IO} 21523in library files @code{a-suteio.ads/adb} contains some GNAT-specific 21524subprograms useful for Text_IO operations on unbounded strings: 21525 21526 21527@itemize * 21528 21529@item 21530function Get_Line (File : File_Type) return Unbounded_String; 21531Reads a line from the specified file 21532and returns the result as an unbounded string. 21533 21534@item 21535procedure Put (File : File_Type; U : Unbounded_String); 21536Writes the value of the given unbounded string to the specified file 21537Similar to the effect of 21538@code{Put (To_String (U))} except that an extra copy is avoided. 21539 21540@item 21541procedure Put_Line (File : File_Type; U : Unbounded_String); 21542Writes the value of the given unbounded string to the specified file, 21543followed by a @code{New_Line}. 21544Similar to the effect of @code{Put_Line (To_String (U))} except 21545that an extra copy is avoided. 21546@end itemize 21547 21548In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} 21549and is optional. If the parameter is omitted, then the standard input or 21550output file is referenced as appropriate. 21551 21552The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 21553files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended 21554@code{Wide_Text_IO} functionality for unbounded wide strings. 21555 21556The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library 21557files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended 21558@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. 21559 21560@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O 21561@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2b8}@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2b9} 21562@section Wide_Text_IO 21563 21564 21565@code{Wide_Text_IO} is similar in most respects to Text_IO, except that 21566both input and output files may contain special sequences that represent 21567wide character values. The encoding scheme for a given file may be 21568specified using a FORM parameter: 21569 21570@example 21571WCEM=`x` 21572@end example 21573 21574as part of the FORM string (WCEM = wide character encoding method), 21575where @code{x} is one of the following characters 21576 21577 21578@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 21579@headitem 21580 21581Character 21582 21583@tab 21584 21585Encoding 21586 21587@item 21588 21589@emph{h} 21590 21591@tab 21592 21593Hex ESC encoding 21594 21595@item 21596 21597@emph{u} 21598 21599@tab 21600 21601Upper half encoding 21602 21603@item 21604 21605@emph{s} 21606 21607@tab 21608 21609Shift-JIS encoding 21610 21611@item 21612 21613@emph{e} 21614 21615@tab 21616 21617EUC Encoding 21618 21619@item 21620 21621@emph{8} 21622 21623@tab 21624 21625UTF-8 encoding 21626 21627@item 21628 21629@emph{b} 21630 21631@tab 21632 21633Brackets encoding 21634 21635@end multitable 21636 21637 21638The encoding methods match those that 21639can be used in a source 21640program, but there is no requirement that the encoding method used for 21641the source program be the same as the encoding method used for files, 21642and different files may use different encoding methods. 21643 21644The default encoding method for the standard files, and for opened files 21645for which no WCEM parameter is given in the FORM string matches the 21646wide character encoding specified for the main program (the default 21647being brackets encoding if no coding method was specified with -gnatW). 21648 21649 21650@table @asis 21651 21652@item @emph{Hex Coding} 21653 21654In this encoding, a wide character is represented by a five character 21655sequence: 21656@end table 21657 21658@example 21659ESC a b c d 21660@end example 21661 21662 21663@quotation 21664 21665where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 21666characters (using upper case letters) of the wide character code. For 21667example, ESC A345 is used to represent the wide character with code 2166816#A345#. This scheme is compatible with use of the full 21669@code{Wide_Character} set. 21670@end quotation 21671 21672 21673@table @asis 21674 21675@item @emph{Upper Half Coding} 21676 21677The wide character with encoding 16#abcd#, where the upper bit is on 21678(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and 2167916#cd#. The second byte may never be a format control character, but is 21680not required to be in the upper half. This method can be also used for 21681shift-JIS or EUC where the internal coding matches the external coding. 21682 21683@item @emph{Shift JIS Coding} 21684 21685A wide character is represented by a two character sequence 16#ab# and 2168616#cd#, with the restrictions described for upper half encoding as 21687described above. The internal character code is the corresponding JIS 21688character according to the standard algorithm for Shift-JIS 21689conversion. Only characters defined in the JIS code set table can be 21690used with this encoding method. 21691 21692@item @emph{EUC Coding} 21693 21694A wide character is represented by a two character sequence 16#ab# and 2169516#cd#, with both characters being in the upper half. The internal 21696character code is the corresponding JIS character according to the EUC 21697encoding algorithm. Only characters defined in the JIS code set table 21698can be used with this encoding method. 21699 21700@item @emph{UTF-8 Coding} 21701 21702A wide character is represented using 21703UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2170410646-1/Am.2. Depending on the character value, the representation 21705is a one, two, or three byte sequence: 21706@end table 21707 21708@example 2170916#0000#-16#007f#: 2#0xxxxxxx# 2171016#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 2171116#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 21712@end example 21713 21714 21715@quotation 21716 21717where the @code{xxx} bits correspond to the left-padded bits of the 2171816-bit character value. Note that all lower half ASCII characters 21719are represented as ASCII bytes and all upper half characters and 21720other wide characters are represented as sequences of upper-half 21721(The full UTF-8 scheme allows for encoding 31-bit characters as 217226-byte sequences, but in this implementation, all UTF-8 sequences 21723of four or more bytes length will raise a Constraint_Error, as 21724will all invalid UTF-8 sequences.) 21725@end quotation 21726 21727 21728@table @asis 21729 21730@item @emph{Brackets Coding} 21731 21732In this encoding, a wide character is represented by the following eight 21733character sequence: 21734@end table 21735 21736@example 21737[ " a b c d " ] 21738@end example 21739 21740 21741@quotation 21742 21743where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 21744characters (using uppercase letters) of the wide character code. For 21745example, @code{["A345"]} is used to represent the wide character with code 21746@code{16#A345#}. 21747This scheme is compatible with use of the full Wide_Character set. 21748On input, brackets coding can also be used for upper half characters, 21749e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 21750is only used for wide characters with a code greater than @code{16#FF#}. 21751 21752Note that brackets coding is not normally used in the context of 21753Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as 21754a portable way of encoding source files. In the context of Wide_Text_IO 21755or Wide_Wide_Text_IO, it can only be used if the file does not contain 21756any instance of the left bracket character other than to encode wide 21757character values using the brackets encoding method. In practice it is 21758expected that some standard wide character encoding method such 21759as UTF-8 will be used for text input output. 21760 21761If brackets notation is used, then any occurrence of a left bracket 21762in the input file which is not the start of a valid wide character 21763sequence will cause Constraint_Error to be raised. It is possible to 21764encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO 21765input will interpret this as a left bracket. 21766 21767However, when a left bracket is output, it will be output as a left bracket 21768and not as ["5B"]. We make this decision because for normal use of 21769Wide_Text_IO for outputting messages, it is unpleasant to clobber left 21770brackets. For example, if we write: 21771 21772@example 21773Put_Line ("Start of output [first run]"); 21774@end example 21775 21776we really do not want to have the left bracket in this message clobbered so 21777that the output reads: 21778@end quotation 21779 21780@example 21781Start of output ["5B"]first run] 21782@end example 21783 21784 21785@quotation 21786 21787In practice brackets encoding is reasonably useful for normal Put_Line use 21788since we won't get confused between left brackets and wide character 21789sequences in the output. But for input, or when files are written out 21790and read back in, it really makes better sense to use one of the standard 21791encoding methods such as UTF-8. 21792@end quotation 21793 21794For the coding schemes other than UTF-8, Hex, or Brackets encoding, 21795not all wide character 21796values can be represented. An attempt to output a character that cannot 21797be represented using the encoding scheme for the file causes 21798Constraint_Error to be raised. An invalid wide character sequence on 21799input also causes Constraint_Error to be raised. 21800 21801@menu 21802* Stream Pointer Positioning: Stream Pointer Positioning<2>. 21803* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. 21804 21805@end menu 21806 21807@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO 21808@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2ba}@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2bb} 21809@subsection Stream Pointer Positioning 21810 21811 21812@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 21813of stream pointer positioning (@ref{2ab,,Text_IO}). There is one additional 21814case: 21815 21816If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 21817normal lower ASCII set (i.e., a character in the range: 21818 21819@example 21820Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 21821@end example 21822 21823then although the logical position of the file pointer is unchanged by 21824the @code{Look_Ahead} call, the stream is physically positioned past the 21825wide character sequence. Again this is to avoid the need for buffering 21826or backup, and all @code{Wide_Text_IO} routines check the internal 21827indication that this situation has occurred so that this is not visible 21828to a normal program using @code{Wide_Text_IO}. However, this discrepancy 21829can be observed if the wide text file shares a stream with another file. 21830 21831@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO 21832@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2bc}@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2bd} 21833@subsection Reading and Writing Non-Regular Files 21834 21835 21836As in the case of Text_IO, when a non-regular file is read, it is 21837assumed that the file contains no page marks (any form characters are 21838treated as data characters), and @code{End_Of_Page} always returns 21839@code{False}. Similarly, the end of file indication is not sticky, so 21840it is possible to read beyond an end of file. 21841 21842@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O 21843@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2be}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2bf} 21844@section Wide_Wide_Text_IO 21845 21846 21847@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that 21848both input and output files may contain special sequences that represent 21849wide wide character values. The encoding scheme for a given file may be 21850specified using a FORM parameter: 21851 21852@example 21853WCEM=`x` 21854@end example 21855 21856as part of the FORM string (WCEM = wide character encoding method), 21857where @code{x} is one of the following characters 21858 21859 21860@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} 21861@headitem 21862 21863Character 21864 21865@tab 21866 21867Encoding 21868 21869@item 21870 21871@emph{h} 21872 21873@tab 21874 21875Hex ESC encoding 21876 21877@item 21878 21879@emph{u} 21880 21881@tab 21882 21883Upper half encoding 21884 21885@item 21886 21887@emph{s} 21888 21889@tab 21890 21891Shift-JIS encoding 21892 21893@item 21894 21895@emph{e} 21896 21897@tab 21898 21899EUC Encoding 21900 21901@item 21902 21903@emph{8} 21904 21905@tab 21906 21907UTF-8 encoding 21908 21909@item 21910 21911@emph{b} 21912 21913@tab 21914 21915Brackets encoding 21916 21917@end multitable 21918 21919 21920The encoding methods match those that 21921can be used in a source 21922program, but there is no requirement that the encoding method used for 21923the source program be the same as the encoding method used for files, 21924and different files may use different encoding methods. 21925 21926The default encoding method for the standard files, and for opened files 21927for which no WCEM parameter is given in the FORM string matches the 21928wide character encoding specified for the main program (the default 21929being brackets encoding if no coding method was specified with -gnatW). 21930 21931 21932@table @asis 21933 21934@item @emph{UTF-8 Coding} 21935 21936A wide character is represented using 21937UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 2193810646-1/Am.2. Depending on the character value, the representation 21939is a one, two, three, or four byte sequence: 21940@end table 21941 21942@example 2194316#000000#-16#00007f#: 2#0xxxxxxx# 2194416#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# 2194516#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 2194616#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# 21947@end example 21948 21949 21950@quotation 21951 21952where the @code{xxx} bits correspond to the left-padded bits of the 2195321-bit character value. Note that all lower half ASCII characters 21954are represented as ASCII bytes and all upper half characters and 21955other wide characters are represented as sequences of upper-half 21956characters. 21957@end quotation 21958 21959 21960@table @asis 21961 21962@item @emph{Brackets Coding} 21963 21964In this encoding, a wide wide character is represented by the following eight 21965character sequence if is in wide character range 21966@end table 21967 21968@example 21969[ " a b c d " ] 21970@end example 21971 21972 21973@quotation 21974 21975and by the following ten character sequence if not 21976@end quotation 21977 21978@example 21979[ " a b c d e f " ] 21980@end example 21981 21982 21983@quotation 21984 21985where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} 21986are the four or six hexadecimal 21987characters (using uppercase letters) of the wide wide character code. For 21988example, @code{["01A345"]} is used to represent the wide wide character 21989with code @code{16#01A345#}. 21990 21991This scheme is compatible with use of the full Wide_Wide_Character set. 21992On input, brackets coding can also be used for upper half characters, 21993e.g., @code{["C1"]} for lower case a. However, on output, brackets notation 21994is only used for wide characters with a code greater than @code{16#FF#}. 21995@end quotation 21996 21997If is also possible to use the other Wide_Character encoding methods, 21998such as Shift-JIS, but the other schemes cannot support the full range 21999of wide wide characters. 22000An attempt to output a character that cannot 22001be represented using the encoding scheme for the file causes 22002Constraint_Error to be raised. An invalid wide character sequence on 22003input also causes Constraint_Error to be raised. 22004 22005@menu 22006* Stream Pointer Positioning: Stream Pointer Positioning<3>. 22007* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. 22008 22009@end menu 22010 22011@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO 22012@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2c0}@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2c1} 22013@subsection Stream Pointer Positioning 22014 22015 22016@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 22017of stream pointer positioning (@ref{2ab,,Text_IO}). There is one additional 22018case: 22019 22020If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the 22021normal lower ASCII set (i.e., a character in the range: 22022 22023@example 22024Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) 22025@end example 22026 22027then although the logical position of the file pointer is unchanged by 22028the @code{Look_Ahead} call, the stream is physically positioned past the 22029wide character sequence. Again this is to avoid the need for buffering 22030or backup, and all @code{Wide_Wide_Text_IO} routines check the internal 22031indication that this situation has occurred so that this is not visible 22032to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy 22033can be observed if the wide text file shares a stream with another file. 22034 22035@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO 22036@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2c2}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2c3} 22037@subsection Reading and Writing Non-Regular Files 22038 22039 22040As in the case of Text_IO, when a non-regular file is read, it is 22041assumed that the file contains no page marks (any form characters are 22042treated as data characters), and @code{End_Of_Page} always returns 22043@code{False}. Similarly, the end of file indication is not sticky, so 22044it is possible to read beyond an end of file. 22045 22046@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O 22047@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2c4}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2c5} 22048@section Stream_IO 22049 22050 22051A stream file is a sequence of bytes, where individual elements are 22052written to the file as described in the Ada Reference Manual. The type 22053@code{Stream_Element} is simply a byte. There are two ways to read or 22054write a stream file. 22055 22056 22057@itemize * 22058 22059@item 22060The operations @code{Read} and @code{Write} directly read or write a 22061sequence of stream elements with no control information. 22062 22063@item 22064The stream attributes applied to a stream file transfer data in the 22065manner described for stream attributes. 22066@end itemize 22067 22068@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O 22069@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2c6}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c7} 22070@section Text Translation 22071 22072 22073@code{Text_Translation=xxx} may be used as the Form parameter 22074passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} 22075has no effect on Unix systems. Possible values are: 22076 22077 22078@itemize * 22079 22080@item 22081@code{Yes} or @code{Text} is the default, which means to 22082translate LF to/from CR/LF on Windows systems. 22083 22084@code{No} disables this translation; i.e. it 22085uses binary mode. For output files, @code{Text_Translation=No} 22086may be used to create Unix-style files on 22087Windows. 22088 22089@item 22090@code{wtext} translation enabled in Unicode mode. 22091(corresponds to _O_WTEXT). 22092 22093@item 22094@code{u8text} translation enabled in Unicode UTF-8 mode. 22095(corresponds to O_U8TEXT). 22096 22097@item 22098@code{u16text} translation enabled in Unicode UTF-16 22099mode. (corresponds to_O_U16TEXT). 22100@end itemize 22101 22102@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O 22103@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2c8}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2c9} 22104@section Shared Files 22105 22106 22107Section A.14 of the Ada Reference Manual allows implementations to 22108provide a wide variety of behavior if an attempt is made to access the 22109same external file with two or more internal files. 22110 22111To provide a full range of functionality, while at the same time 22112minimizing the problems of portability caused by this implementation 22113dependence, GNAT handles file sharing as follows: 22114 22115 22116@itemize * 22117 22118@item 22119In the absence of a @code{shared=xxx} form parameter, an attempt 22120to open two or more files with the same full name is considered an error 22121and is not supported. The exception @code{Use_Error} will be 22122raised. Note that a file that is not explicitly closed by the program 22123remains open until the program terminates. 22124 22125@item 22126If the form parameter @code{shared=no} appears in the form string, the 22127file can be opened or created with its own separate stream identifier, 22128regardless of whether other files sharing the same external file are 22129opened. The exact effect depends on how the C stream routines handle 22130multiple accesses to the same external files using separate streams. 22131 22132@item 22133If the form parameter @code{shared=yes} appears in the form string for 22134each of two or more files opened using the same full name, the same 22135stream is shared between these files, and the semantics are as described 22136in Ada Reference Manual, Section A.14. 22137@end itemize 22138 22139When a program that opens multiple files with the same name is ported 22140from another Ada compiler to GNAT, the effect will be that 22141@code{Use_Error} is raised. 22142 22143The documentation of the original compiler and the documentation of the 22144program should then be examined to determine if file sharing was 22145expected, and @code{shared=xxx} parameters added to @code{Open} 22146and @code{Create} calls as required. 22147 22148When a program is ported from GNAT to some other Ada compiler, no 22149special attention is required unless the @code{shared=xxx} form 22150parameter is used in the program. In this case, you must examine the 22151documentation of the new compiler to see if it supports the required 22152file sharing semantics, and form strings modified appropriately. Of 22153course it may be the case that the program cannot be ported if the 22154target compiler does not support the required functionality. The best 22155approach in writing portable code is to avoid file sharing (and hence 22156the use of the @code{shared=xxx} parameter in the form string) 22157completely. 22158 22159One common use of file sharing in Ada 83 is the use of instantiations of 22160Sequential_IO on the same file with different types, to achieve 22161heterogeneous input-output. Although this approach will work in GNAT if 22162@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO 22163for this purpose (using the stream attributes) 22164 22165@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O 22166@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2ca}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2cb} 22167@section Filenames encoding 22168 22169 22170An encoding form parameter can be used to specify the filename 22171encoding @code{encoding=xxx}. 22172 22173 22174@itemize * 22175 22176@item 22177If the form parameter @code{encoding=utf8} appears in the form string, the 22178filename must be encoded in UTF-8. 22179 22180@item 22181If the form parameter @code{encoding=8bits} appears in the form 22182string, the filename must be a standard 8bits string. 22183@end itemize 22184 22185In the absence of a @code{encoding=xxx} form parameter, the 22186encoding is controlled by the @code{GNAT_CODE_PAGE} environment 22187variable. And if not set @code{utf8} is assumed. 22188 22189 22190@table @asis 22191 22192@item @emph{CP_ACP} 22193 22194The current system Windows ANSI code page. 22195 22196@item @emph{CP_UTF8} 22197 22198UTF-8 encoding 22199@end table 22200 22201This encoding form parameter is only supported on the Windows 22202platform. On the other Operating Systems the run-time is supporting 22203UTF-8 natively. 22204 22205@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O 22206@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2cc}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2cd} 22207@section File content encoding 22208 22209 22210For text files it is possible to specify the encoding to use. This is 22211controlled by the by the @code{GNAT_CCS_ENCODING} environment 22212variable. And if not set @code{TEXT} is assumed. 22213 22214The possible values are those supported on Windows: 22215 22216 22217@table @asis 22218 22219@item @emph{TEXT} 22220 22221Translated text mode 22222 22223@item @emph{WTEXT} 22224 22225Translated unicode encoding 22226 22227@item @emph{U16TEXT} 22228 22229Unicode 16-bit encoding 22230 22231@item @emph{U8TEXT} 22232 22233Unicode 8-bit encoding 22234@end table 22235 22236This encoding is only supported on the Windows platform. 22237 22238@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O 22239@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2ce}@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2cf} 22240@section Open Modes 22241 22242 22243@code{Open} and @code{Create} calls result in a call to @code{fopen} 22244using the mode shown in the following table: 22245 22246 22247@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} 22248@headitem 22249 22250@code{Open} and @code{Create} Call Modes 22251 22252@tab 22253 22254@tab 22255 22256@item 22257 22258@tab 22259 22260@strong{OPEN} 22261 22262@tab 22263 22264@strong{CREATE} 22265 22266@item 22267 22268Append_File 22269 22270@tab 22271 22272"r+" 22273 22274@tab 22275 22276"w+" 22277 22278@item 22279 22280In_File 22281 22282@tab 22283 22284"r" 22285 22286@tab 22287 22288"w+" 22289 22290@item 22291 22292Out_File (Direct_IO) 22293 22294@tab 22295 22296"r+" 22297 22298@tab 22299 22300"w" 22301 22302@item 22303 22304Out_File (all other cases) 22305 22306@tab 22307 22308"w" 22309 22310@tab 22311 22312"w" 22313 22314@item 22315 22316Inout_File 22317 22318@tab 22319 22320"r+" 22321 22322@tab 22323 22324"w+" 22325 22326@end multitable 22327 22328 22329If text file translation is required, then either @code{b} or @code{t} 22330is added to the mode, depending on the setting of Text. Text file 22331translation refers to the mapping of CR/LF sequences in an external file 22332to LF characters internally. This mapping only occurs in DOS and 22333DOS-like systems, and is not relevant to other systems. 22334 22335A special case occurs with Stream_IO. As shown in the above table, the 22336file is initially opened in @code{r} or @code{w} mode for the 22337@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation 22338subsequently requires switching from reading to writing or vice-versa, 22339then the file is reopened in @code{r+} mode to permit the required operation. 22340 22341@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O 22342@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2d0}@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2d1} 22343@section Operations on C Streams 22344 22345 22346The package @code{Interfaces.C_Streams} provides an Ada program with direct 22347access to the C library functions for operations on C streams: 22348 22349@example 22350package Interfaces.C_Streams is 22351 -- Note: the reason we do not use the types that are in 22352 -- Interfaces.C is that we want to avoid dragging in the 22353 -- code in this unit if possible. 22354 subtype chars is System.Address; 22355 -- Pointer to null-terminated array of characters 22356 subtype FILEs is System.Address; 22357 -- Corresponds to the C type FILE* 22358 subtype voids is System.Address; 22359 -- Corresponds to the C type void* 22360 subtype int is Integer; 22361 subtype long is Long_Integer; 22362 -- Note: the above types are subtypes deliberately, and it 22363 -- is part of this spec that the above correspondences are 22364 -- guaranteed. This means that it is legitimate to, for 22365 -- example, use Integer instead of int. We provide these 22366 -- synonyms for clarity, but in some cases it may be 22367 -- convenient to use the underlying types (for example to 22368 -- avoid an unnecessary dependency of a spec on the spec 22369 -- of this unit). 22370 type size_t is mod 2 ** Standard'Address_Size; 22371 NULL_Stream : constant FILEs; 22372 -- Value returned (NULL in C) to indicate an 22373 -- fdopen/fopen/tmpfile error 22374 ---------------------------------- 22375 -- Constants Defined in stdio.h -- 22376 ---------------------------------- 22377 EOF : constant int; 22378 -- Used by a number of routines to indicate error or 22379 -- end of file 22380 IOFBF : constant int; 22381 IOLBF : constant int; 22382 IONBF : constant int; 22383 -- Used to indicate buffering mode for setvbuf call 22384 SEEK_CUR : constant int; 22385 SEEK_END : constant int; 22386 SEEK_SET : constant int; 22387 -- Used to indicate origin for fseek call 22388 function stdin return FILEs; 22389 function stdout return FILEs; 22390 function stderr return FILEs; 22391 -- Streams associated with standard files 22392 -------------------------- 22393 -- Standard C functions -- 22394 -------------------------- 22395 -- The functions selected below are ones that are 22396 -- available in UNIX (but not necessarily in ANSI C). 22397 -- These are very thin interfaces 22398 -- which copy exactly the C headers. For more 22399 -- documentation on these functions, see the Microsoft C 22400 -- "Run-Time Library Reference" (Microsoft Press, 1990, 22401 -- ISBN 1-55615-225-6), which includes useful information 22402 -- on system compatibility. 22403 procedure clearerr (stream : FILEs); 22404 function fclose (stream : FILEs) return int; 22405 function fdopen (handle : int; mode : chars) return FILEs; 22406 function feof (stream : FILEs) return int; 22407 function ferror (stream : FILEs) return int; 22408 function fflush (stream : FILEs) return int; 22409 function fgetc (stream : FILEs) return int; 22410 function fgets (strng : chars; n : int; stream : FILEs) 22411 return chars; 22412 function fileno (stream : FILEs) return int; 22413 function fopen (filename : chars; Mode : chars) 22414 return FILEs; 22415 -- Note: to maintain target independence, use 22416 -- text_translation_required, a boolean variable defined in 22417 -- a-sysdep.c to deal with the target dependent text 22418 -- translation requirement. If this variable is set, 22419 -- then b/t should be appended to the standard mode 22420 -- argument to set the text translation mode off or on 22421 -- as required. 22422 function fputc (C : int; stream : FILEs) return int; 22423 function fputs (Strng : chars; Stream : FILEs) return int; 22424 function fread 22425 (buffer : voids; 22426 size : size_t; 22427 count : size_t; 22428 stream : FILEs) 22429 return size_t; 22430 function freopen 22431 (filename : chars; 22432 mode : chars; 22433 stream : FILEs) 22434 return FILEs; 22435 function fseek 22436 (stream : FILEs; 22437 offset : long; 22438 origin : int) 22439 return int; 22440 function ftell (stream : FILEs) return long; 22441 function fwrite 22442 (buffer : voids; 22443 size : size_t; 22444 count : size_t; 22445 stream : FILEs) 22446 return size_t; 22447 function isatty (handle : int) return int; 22448 procedure mktemp (template : chars); 22449 -- The return value (which is just a pointer to template) 22450 -- is discarded 22451 procedure rewind (stream : FILEs); 22452 function rmtmp return int; 22453 function setvbuf 22454 (stream : FILEs; 22455 buffer : chars; 22456 mode : int; 22457 size : size_t) 22458 return int; 22459 22460 function tmpfile return FILEs; 22461 function ungetc (c : int; stream : FILEs) return int; 22462 function unlink (filename : chars) return int; 22463 --------------------- 22464 -- Extra functions -- 22465 --------------------- 22466 -- These functions supply slightly thicker bindings than 22467 -- those above. They are derived from functions in the 22468 -- C Run-Time Library, but may do a bit more work than 22469 -- just directly calling one of the Library functions. 22470 function is_regular_file (handle : int) return int; 22471 -- Tests if given handle is for a regular file (result 1) 22472 -- or for a non-regular file (pipe or device, result 0). 22473 --------------------------------- 22474 -- Control of Text/Binary Mode -- 22475 --------------------------------- 22476 -- If text_translation_required is true, then the following 22477 -- functions may be used to dynamically switch a file from 22478 -- binary to text mode or vice versa. These functions have 22479 -- no effect if text_translation_required is false (i.e., in 22480 -- normal UNIX mode). Use fileno to get a stream handle. 22481 procedure set_binary_mode (handle : int); 22482 procedure set_text_mode (handle : int); 22483 ---------------------------- 22484 -- Full Path Name support -- 22485 ---------------------------- 22486 procedure full_name (nam : chars; buffer : chars); 22487 -- Given a NUL terminated string representing a file 22488 -- name, returns in buffer a NUL terminated string 22489 -- representing the full path name for the file name. 22490 -- On systems where it is relevant the drive is also 22491 -- part of the full path name. It is the responsibility 22492 -- of the caller to pass an actual parameter for buffer 22493 -- that is big enough for any full path name. Use 22494 -- max_path_len given below as the size of buffer. 22495 max_path_len : integer; 22496 -- Maximum length of an allowable full path name on the 22497 -- system, including a terminating NUL character. 22498end Interfaces.C_Streams; 22499@end example 22500 22501@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O 22502@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2d2}@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2d3} 22503@section Interfacing to C Streams 22504 22505 22506The packages in this section permit interfacing Ada files to C Stream 22507operations. 22508 22509@example 22510with Interfaces.C_Streams; 22511package Ada.Sequential_IO.C_Streams is 22512 function C_Stream (F : File_Type) 22513 return Interfaces.C_Streams.FILEs; 22514 procedure Open 22515 (File : in out File_Type; 22516 Mode : in File_Mode; 22517 C_Stream : in Interfaces.C_Streams.FILEs; 22518 Form : in String := ""); 22519end Ada.Sequential_IO.C_Streams; 22520 22521 with Interfaces.C_Streams; 22522 package Ada.Direct_IO.C_Streams is 22523 function C_Stream (F : File_Type) 22524 return Interfaces.C_Streams.FILEs; 22525 procedure Open 22526 (File : in out File_Type; 22527 Mode : in File_Mode; 22528 C_Stream : in Interfaces.C_Streams.FILEs; 22529 Form : in String := ""); 22530 end Ada.Direct_IO.C_Streams; 22531 22532 with Interfaces.C_Streams; 22533 package Ada.Text_IO.C_Streams is 22534 function C_Stream (F : File_Type) 22535 return Interfaces.C_Streams.FILEs; 22536 procedure Open 22537 (File : in out File_Type; 22538 Mode : in File_Mode; 22539 C_Stream : in Interfaces.C_Streams.FILEs; 22540 Form : in String := ""); 22541 end Ada.Text_IO.C_Streams; 22542 22543 with Interfaces.C_Streams; 22544 package Ada.Wide_Text_IO.C_Streams is 22545 function C_Stream (F : File_Type) 22546 return Interfaces.C_Streams.FILEs; 22547 procedure Open 22548 (File : in out File_Type; 22549 Mode : in File_Mode; 22550 C_Stream : in Interfaces.C_Streams.FILEs; 22551 Form : in String := ""); 22552end Ada.Wide_Text_IO.C_Streams; 22553 22554 with Interfaces.C_Streams; 22555 package Ada.Wide_Wide_Text_IO.C_Streams is 22556 function C_Stream (F : File_Type) 22557 return Interfaces.C_Streams.FILEs; 22558 procedure Open 22559 (File : in out File_Type; 22560 Mode : in File_Mode; 22561 C_Stream : in Interfaces.C_Streams.FILEs; 22562 Form : in String := ""); 22563end Ada.Wide_Wide_Text_IO.C_Streams; 22564 22565with Interfaces.C_Streams; 22566package Ada.Stream_IO.C_Streams is 22567 function C_Stream (F : File_Type) 22568 return Interfaces.C_Streams.FILEs; 22569 procedure Open 22570 (File : in out File_Type; 22571 Mode : in File_Mode; 22572 C_Stream : in Interfaces.C_Streams.FILEs; 22573 Form : in String := ""); 22574end Ada.Stream_IO.C_Streams; 22575@end example 22576 22577In each of these six packages, the @code{C_Stream} function obtains the 22578@code{FILE} pointer from a currently opened Ada file. It is then 22579possible to use the @code{Interfaces.C_Streams} package to operate on 22580this stream, or the stream can be passed to a C program which can 22581operate on it directly. Of course the program is responsible for 22582ensuring that only appropriate sequences of operations are executed. 22583 22584One particular use of relevance to an Ada program is that the 22585@code{setvbuf} function can be used to control the buffering of the 22586stream used by an Ada file. In the absence of such a call the standard 22587default buffering is used. 22588 22589The @code{Open} procedures in these packages open a file giving an 22590existing C Stream instead of a file name. Typically this stream is 22591imported from a C program, allowing an Ada file to operate on an 22592existing C file. 22593 22594@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top 22595@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}@anchor{gnat_rm/the_gnat_library doc}@anchor{2d4}@anchor{gnat_rm/the_gnat_library id1}@anchor{2d5} 22596@chapter The GNAT Library 22597 22598 22599The GNAT library contains a number of general and special purpose packages. 22600It represents functionality that the GNAT developers have found useful, and 22601which is made available to GNAT users. The packages described here are fully 22602supported, and upwards compatibility will be maintained in future releases, 22603so you can use these facilities with the confidence that the same functionality 22604will be available in future releases. 22605 22606The chapter here simply gives a brief summary of the facilities available. 22607The full documentation is found in the spec file for the package. The full 22608sources of these library packages, including both spec and body, are provided 22609with all GNAT releases. For example, to find out the full specifications of 22610the SPITBOL pattern matching capability, including a full tutorial and 22611extensive examples, look in the @code{g-spipat.ads} file in the library. 22612 22613For each entry here, the package name (as it would appear in a @code{with} 22614clause) is given, followed by the name of the corresponding spec file in 22615parentheses. The packages are children in four hierarchies, @code{Ada}, 22616@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a 22617GNAT-specific hierarchy. 22618 22619Note that an application program should only use packages in one of these 22620four hierarchies if the package is defined in the Ada Reference Manual, 22621or is listed in this section of the GNAT Programmers Reference Manual. 22622All other units should be considered internal implementation units and 22623should not be directly @code{with}ed by application code. The use of 22624a @code{with} clause that references one of these internal implementation 22625units makes an application potentially dependent on changes in versions 22626of GNAT, and will generate a warning message. 22627 22628@menu 22629* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. 22630* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. 22631* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads. 22632* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. 22633* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. 22634* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads. 22635* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads. 22636* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads. 22637* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads. 22638* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads. 22639* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads. 22640* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads. 22641* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads. 22642* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads. 22643* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads. 22644* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. 22645* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. 22646* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. 22647* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. 22648* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. 22649* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. 22650* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. 22651* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. 22652* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. 22653* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. 22654* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. 22655* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. 22656* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. 22657* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. 22658* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. 22659* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. 22660* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. 22661* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. 22662* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. 22663* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. 22664* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. 22665* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. 22666* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. 22667* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. 22668* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. 22669* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. 22670* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. 22671* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. 22672* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. 22673* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. 22674* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. 22675* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. 22676* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. 22677* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. 22678* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. 22679* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. 22680* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. 22681* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. 22682* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. 22683* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. 22684* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. 22685* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. 22686* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. 22687* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. 22688* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. 22689* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. 22690* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. 22691* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. 22692* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. 22693* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. 22694* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. 22695* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. 22696* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. 22697* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. 22698* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. 22699* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. 22700* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. 22701* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. 22702* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. 22703* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. 22704* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. 22705* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. 22706* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. 22707* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. 22708* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. 22709* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. 22710* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. 22711* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. 22712* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. 22713* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. 22714* GNAT.IO (g-io.ads): GNAT IO g-io ads. 22715* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. 22716* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. 22717* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. 22718* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. 22719* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. 22720* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. 22721* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. 22722* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. 22723* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. 22724* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. 22725* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. 22726* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. 22727* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. 22728* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. 22729* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. 22730* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. 22731* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. 22732* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. 22733* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. 22734* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. 22735* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. 22736* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. 22737* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. 22738* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. 22739* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. 22740* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. 22741* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. 22742* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. 22743* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. 22744* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. 22745* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. 22746* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. 22747* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. 22748* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. 22749* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. 22750* GNAT.Strings (g-string.ads): GNAT Strings g-string ads. 22751* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. 22752* GNAT.Table (g-table.ads): GNAT Table g-table ads. 22753* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. 22754* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. 22755* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. 22756* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. 22757* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. 22758* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads. 22759* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads. 22760* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. 22761* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. 22762* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. 22763* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. 22764* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. 22765* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. 22766* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. 22767* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. 22768* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. 22769* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. 22770* System.Address_Image (s-addima.ads): System Address_Image s-addima ads. 22771* System.Assertions (s-assert.ads): System Assertions s-assert ads. 22772* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. 22773* System.Memory (s-memory.ads): System Memory s-memory ads. 22774* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. 22775* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. 22776* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. 22777* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. 22778* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. 22779* System.Restrictions (s-restri.ads): System Restrictions s-restri ads. 22780* System.Rident (s-rident.ads): System Rident s-rident ads. 22781* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. 22782* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. 22783* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. 22784* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. 22785 22786@end menu 22787 22788@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library 22789@anchor{gnat_rm/the_gnat_library id2}@anchor{2d6}@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d7} 22790@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) 22791 22792 22793@geindex Ada.Characters.Latin_9 (a-chlat9.ads) 22794 22795@geindex Latin_9 constants for Character 22796 22797This child of @code{Ada.Characters} 22798provides a set of definitions corresponding to those in the 22799RM-defined package @code{Ada.Characters.Latin_1} but with the 22800few modifications required for @code{Latin-9} 22801The provision of such a package 22802is specifically authorized by the Ada Reference Manual 22803(RM A.3.3(27)). 22804 22805@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 22806@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2d8}@anchor{gnat_rm/the_gnat_library id3}@anchor{2d9} 22807@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) 22808 22809 22810@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 22811 22812@geindex Latin_1 constants for Wide_Character 22813 22814This child of @code{Ada.Characters} 22815provides a set of definitions corresponding to those in the 22816RM-defined package @code{Ada.Characters.Latin_1} but with the 22817types of the constants being @code{Wide_Character} 22818instead of @code{Character}. The provision of such a package 22819is specifically authorized by the Ada Reference Manual 22820(RM A.3.3(27)). 22821 22822@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 22823@anchor{gnat_rm/the_gnat_library id4}@anchor{2da}@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2db} 22824@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads}) 22825 22826 22827@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads) 22828 22829@geindex Latin_9 constants for Wide_Character 22830 22831This child of @code{Ada.Characters} 22832provides a set of definitions corresponding to those in the 22833GNAT defined package @code{Ada.Characters.Latin_9} but with the 22834types of the constants being @code{Wide_Character} 22835instead of @code{Character}. The provision of such a package 22836is specifically authorized by the Ada Reference Manual 22837(RM A.3.3(27)). 22838 22839@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 22840@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2dc}@anchor{gnat_rm/the_gnat_library id5}@anchor{2dd} 22841@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) 22842 22843 22844@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) 22845 22846@geindex Latin_1 constants for Wide_Wide_Character 22847 22848This child of @code{Ada.Characters} 22849provides a set of definitions corresponding to those in the 22850RM-defined package @code{Ada.Characters.Latin_1} but with the 22851types of the constants being @code{Wide_Wide_Character} 22852instead of @code{Character}. The provision of such a package 22853is specifically authorized by the Ada Reference Manual 22854(RM A.3.3(27)). 22855 22856@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 22857@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2de}@anchor{gnat_rm/the_gnat_library id6}@anchor{2df} 22858@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) 22859 22860 22861@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) 22862 22863@geindex Latin_9 constants for Wide_Wide_Character 22864 22865This child of @code{Ada.Characters} 22866provides a set of definitions corresponding to those in the 22867GNAT defined package @code{Ada.Characters.Latin_9} but with the 22868types of the constants being @code{Wide_Wide_Character} 22869instead of @code{Character}. The provision of such a package 22870is specifically authorized by the Ada Reference Manual 22871(RM A.3.3(27)). 22872 22873@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 22874@anchor{gnat_rm/the_gnat_library id7}@anchor{2e0}@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2e1} 22875@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads}) 22876 22877 22878@geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) 22879 22880@geindex Formal container for doubly linked lists 22881 22882This child of @code{Ada.Containers} defines a modified version of the 22883Ada 2005 container for doubly linked lists, meant to facilitate formal 22884verification of code using such containers. The specification of this 22885unit is compatible with SPARK 2014. 22886 22887Note that although this container was designed with formal verification 22888in mind, it may well be generally useful in that it is a simplified more 22889efficient version than the one defined in the standard. In particular it 22890does not have the complex overhead required to detect cursor tampering. 22891 22892@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 22893@anchor{gnat_rm/the_gnat_library id8}@anchor{2e2}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2e3} 22894@section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads}) 22895 22896 22897@geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) 22898 22899@geindex Formal container for hashed maps 22900 22901This child of @code{Ada.Containers} defines a modified version of the 22902Ada 2005 container for hashed maps, meant to facilitate formal 22903verification of code using such containers. The specification of this 22904unit is compatible with SPARK 2014. 22905 22906Note that although this container was designed with formal verification 22907in mind, it may well be generally useful in that it is a simplified more 22908efficient version than the one defined in the standard. In particular it 22909does not have the complex overhead required to detect cursor tampering. 22910 22911@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 22912@anchor{gnat_rm/the_gnat_library id9}@anchor{2e4}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2e5} 22913@section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads}) 22914 22915 22916@geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) 22917 22918@geindex Formal container for hashed sets 22919 22920This child of @code{Ada.Containers} defines a modified version of the 22921Ada 2005 container for hashed sets, meant to facilitate formal 22922verification of code using such containers. The specification of this 22923unit is compatible with SPARK 2014. 22924 22925Note that although this container was designed with formal verification 22926in mind, it may well be generally useful in that it is a simplified more 22927efficient version than the one defined in the standard. In particular it 22928does not have the complex overhead required to detect cursor tampering. 22929 22930@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 22931@anchor{gnat_rm/the_gnat_library id10}@anchor{2e6}@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2e7} 22932@section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads}) 22933 22934 22935@geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) 22936 22937@geindex Formal container for ordered maps 22938 22939This child of @code{Ada.Containers} defines a modified version of the 22940Ada 2005 container for ordered maps, meant to facilitate formal 22941verification of code using such containers. The specification of this 22942unit is compatible with SPARK 2014. 22943 22944Note that although this container was designed with formal verification 22945in mind, it may well be generally useful in that it is a simplified more 22946efficient version than the one defined in the standard. In particular it 22947does not have the complex overhead required to detect cursor tampering. 22948 22949@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 22950@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2e8}@anchor{gnat_rm/the_gnat_library id11}@anchor{2e9} 22951@section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads}) 22952 22953 22954@geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) 22955 22956@geindex Formal container for ordered sets 22957 22958This child of @code{Ada.Containers} defines a modified version of the 22959Ada 2005 container for ordered sets, meant to facilitate formal 22960verification of code using such containers. The specification of this 22961unit is compatible with SPARK 2014. 22962 22963Note that although this container was designed with formal verification 22964in mind, it may well be generally useful in that it is a simplified more 22965efficient version than the one defined in the standard. In particular it 22966does not have the complex overhead required to detect cursor tampering. 22967 22968@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 22969@anchor{gnat_rm/the_gnat_library id12}@anchor{2ea}@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2eb} 22970@section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads}) 22971 22972 22973@geindex Ada.Containers.Formal_Vectors (a-cofove.ads) 22974 22975@geindex Formal container for vectors 22976 22977This child of @code{Ada.Containers} defines a modified version of the 22978Ada 2005 container for vectors, meant to facilitate formal 22979verification of code using such containers. The specification of this 22980unit is compatible with SPARK 2014. 22981 22982Note that although this container was designed with formal verification 22983in mind, it may well be generally useful in that it is a simplified more 22984efficient version than the one defined in the standard. In particular it 22985does not have the complex overhead required to detect cursor tampering. 22986 22987@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 22988@anchor{gnat_rm/the_gnat_library id13}@anchor{2ec}@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2ed} 22989@section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads}) 22990 22991 22992@geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads) 22993 22994@geindex Formal container for vectors 22995 22996This child of @code{Ada.Containers} defines a modified version of the 22997Ada 2005 container for vectors of indefinite elements, meant to 22998facilitate formal verification of code using such containers. The 22999specification of this unit is compatible with SPARK 2014. 23000 23001Note that although this container was designed with formal verification 23002in mind, it may well be generally useful in that it is a simplified more 23003efficient version than the one defined in the standard. In particular it 23004does not have the complex overhead required to detect cursor tampering. 23005 23006@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 23007@anchor{gnat_rm/the_gnat_library id14}@anchor{2ee}@anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2ef} 23008@section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads}) 23009 23010 23011@geindex Ada.Containers.Functional_Vectors (a-cofuve.ads) 23012 23013@geindex Functional vectors 23014 23015This child of @code{Ada.Containers} defines immutable vectors. These 23016containers are unbounded and may contain indefinite elements. Furthermore, to 23017be usable in every context, they are neither controlled nor limited. As they 23018are functional, that is, no primitives are provided which would allow modifying 23019an existing container, these containers can still be used safely. 23020 23021Their API features functions creating new containers from existing ones. 23022As a consequence, these containers are highly inefficient. They are also 23023memory consuming, as the allocated memory is not reclaimed when the container 23024is no longer referenced. Thus, they should in general be used in ghost code 23025and annotations, so that they can be removed from the final executable. The 23026specification of this unit is compatible with SPARK 2014. 23027 23028@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 23029@anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2f0}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f1} 23030@section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads}) 23031 23032 23033@geindex Ada.Containers.Functional_Sets (a-cofuse.ads) 23034 23035@geindex Functional sets 23036 23037This child of @code{Ada.Containers} defines immutable sets. These containers are 23038unbounded and may contain indefinite elements. Furthermore, to be usable in 23039every context, they are neither controlled nor limited. As they are functional, 23040that is, no primitives are provided which would allow modifying an existing 23041container, these containers can still be used safely. 23042 23043Their API features functions creating new containers from existing ones. 23044As a consequence, these containers are highly inefficient. They are also 23045memory consuming, as the allocated memory is not reclaimed when the container 23046is no longer referenced. Thus, they should in general be used in ghost code 23047and annotations, so that they can be removed from the final executable. The 23048specification of this unit is compatible with SPARK 2014. 23049 23050@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 23051@anchor{gnat_rm/the_gnat_library id16}@anchor{2f2}@anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2f3} 23052@section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads}) 23053 23054 23055@geindex Ada.Containers.Functional_Maps (a-cofuma.ads) 23056 23057@geindex Functional maps 23058 23059This child of @code{Ada.Containers} defines immutable maps. These containers are 23060unbounded and may contain indefinite elements. Furthermore, to be usable in 23061every context, they are neither controlled nor limited. As they are functional, 23062that is, no primitives are provided which would allow modifying an existing 23063container, these containers can still be used safely. 23064 23065Their API features functions creating new containers from existing ones. 23066As a consequence, these containers are highly inefficient. They are also 23067memory consuming, as the allocated memory is not reclaimed when the container 23068is no longer referenced. Thus, they should in general be used in ghost code 23069and annotations, so that they can be removed from the final executable. The 23070specification of this unit is compatible with SPARK 2014. 23071 23072@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 23073@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2f4}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f5} 23074@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) 23075 23076 23077@geindex Ada.Containers.Bounded_Holders (a-coboho.ads) 23078 23079@geindex Formal container for vectors 23080 23081This child of @code{Ada.Containers} defines a modified version of 23082Indefinite_Holders that avoids heap allocation. 23083 23084@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 23085@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2f6}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f7} 23086@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) 23087 23088 23089@geindex Ada.Command_Line.Environment (a-colien.ads) 23090 23091@geindex Environment entries 23092 23093This child of @code{Ada.Command_Line} 23094provides a mechanism for obtaining environment values on systems 23095where this concept makes sense. 23096 23097@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 23098@anchor{gnat_rm/the_gnat_library id19}@anchor{2f8}@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2f9} 23099@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) 23100 23101 23102@geindex Ada.Command_Line.Remove (a-colire.ads) 23103 23104@geindex Removing command line arguments 23105 23106@geindex Command line 23107@geindex argument removal 23108 23109This child of @code{Ada.Command_Line} 23110provides a mechanism for logically removing 23111arguments from the argument list. Once removed, an argument is not visible 23112to further calls on the subprograms in @code{Ada.Command_Line} will not 23113see the removed argument. 23114 23115@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 23116@anchor{gnat_rm/the_gnat_library id20}@anchor{2fa}@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2fb} 23117@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) 23118 23119 23120@geindex Ada.Command_Line.Response_File (a-clrefi.ads) 23121 23122@geindex Response file for command line 23123 23124@geindex Command line 23125@geindex response file 23126 23127@geindex Command line 23128@geindex handling long command lines 23129 23130This child of @code{Ada.Command_Line} provides a mechanism facilities for 23131getting command line arguments from a text file, called a "response file". 23132Using a response file allow passing a set of arguments to an executable longer 23133than the maximum allowed by the system on the command line. 23134 23135@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 23136@anchor{gnat_rm/the_gnat_library id21}@anchor{2fc}@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2fd} 23137@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) 23138 23139 23140@geindex Ada.Direct_IO.C_Streams (a-diocst.ads) 23141 23142@geindex C Streams 23143@geindex Interfacing with Direct_IO 23144 23145This package provides subprograms that allow interfacing between 23146C streams and @code{Direct_IO}. The stream identifier can be 23147extracted from a file opened on the Ada side, and an Ada file 23148can be constructed from a stream opened on the C side. 23149 23150@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 23151@anchor{gnat_rm/the_gnat_library id22}@anchor{2fe}@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2ff} 23152@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) 23153 23154 23155@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 23156 23157@geindex Null_Occurrence 23158@geindex testing for 23159 23160This child subprogram provides a way of testing for the null 23161exception occurrence (@code{Null_Occurrence}) without raising 23162an exception. 23163 23164@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 23165@anchor{gnat_rm/the_gnat_library id23}@anchor{300}@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{301} 23166@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) 23167 23168 23169@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) 23170 23171@geindex Null_Occurrence 23172@geindex testing for 23173 23174This child subprogram is used for handling otherwise unhandled 23175exceptions (hence the name last chance), and perform clean ups before 23176terminating the program. Note that this subprogram never returns. 23177 23178@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 23179@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{302}@anchor{gnat_rm/the_gnat_library id24}@anchor{303} 23180@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) 23181 23182 23183@geindex Ada.Exceptions.Traceback (a-exctra.ads) 23184 23185@geindex Traceback for Exception Occurrence 23186 23187This child package provides the subprogram (@code{Tracebacks}) to 23188give a traceback array of addresses based on an exception 23189occurrence. 23190 23191@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 23192@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{304}@anchor{gnat_rm/the_gnat_library id25}@anchor{305} 23193@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) 23194 23195 23196@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) 23197 23198@geindex C Streams 23199@geindex Interfacing with Sequential_IO 23200 23201This package provides subprograms that allow interfacing between 23202C streams and @code{Sequential_IO}. The stream identifier can be 23203extracted from a file opened on the Ada side, and an Ada file 23204can be constructed from a stream opened on the C side. 23205 23206@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 23207@anchor{gnat_rm/the_gnat_library id26}@anchor{306}@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{307} 23208@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) 23209 23210 23211@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 23212 23213@geindex C Streams 23214@geindex Interfacing with Stream_IO 23215 23216This package provides subprograms that allow interfacing between 23217C streams and @code{Stream_IO}. The stream identifier can be 23218extracted from a file opened on the Ada side, and an Ada file 23219can be constructed from a stream opened on the C side. 23220 23221@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 23222@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{308}@anchor{gnat_rm/the_gnat_library id27}@anchor{309} 23223@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) 23224 23225 23226@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 23227 23228@geindex Unbounded_String 23229@geindex IO support 23230 23231@geindex Text_IO 23232@geindex extensions for unbounded strings 23233 23234This package provides subprograms for Text_IO for unbounded 23235strings, avoiding the necessity for an intermediate operation 23236with ordinary strings. 23237 23238@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 23239@anchor{gnat_rm/the_gnat_library id28}@anchor{30a}@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{30b} 23240@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) 23241 23242 23243@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 23244 23245@geindex Unbounded_Wide_String 23246@geindex IO support 23247 23248@geindex Text_IO 23249@geindex extensions for unbounded wide strings 23250 23251This package provides subprograms for Text_IO for unbounded 23252wide strings, avoiding the necessity for an intermediate operation 23253with ordinary wide strings. 23254 23255@node Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Task_Initialization a-tasini ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,The GNAT Library 23256@anchor{gnat_rm/the_gnat_library id29}@anchor{30c}@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{30d} 23257@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) 23258 23259 23260@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) 23261 23262@geindex Unbounded_Wide_Wide_String 23263@geindex IO support 23264 23265@geindex Text_IO 23266@geindex extensions for unbounded wide wide strings 23267 23268This package provides subprograms for Text_IO for unbounded 23269wide wide strings, avoiding the necessity for an intermediate operation 23270with ordinary wide wide strings. 23271 23272@node Ada Task_Initialization a-tasini ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library 23273@anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{30e}@anchor{gnat_rm/the_gnat_library id30}@anchor{30f} 23274@section @code{Ada.Task_Initialization} (@code{a-tasini.ads}) 23275 23276 23277@geindex Ada.Task_Initialization (a-tasini.ads) 23278 23279This package provides a way to set a global initialization handler that 23280is automatically invoked whenever a task is activated. Handlers are 23281parameterless procedures. Note that such a handler is only invoked for 23282those tasks activated after the handler is set. 23283 23284@node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Task_Initialization a-tasini ads,The GNAT Library 23285@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{310}@anchor{gnat_rm/the_gnat_library id31}@anchor{311} 23286@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) 23287 23288 23289@geindex Ada.Text_IO.C_Streams (a-tiocst.ads) 23290 23291@geindex C Streams 23292@geindex Interfacing with `@w{`}Text_IO`@w{`} 23293 23294This package provides subprograms that allow interfacing between 23295C streams and @code{Text_IO}. The stream identifier can be 23296extracted from a file opened on the Ada side, and an Ada file 23297can be constructed from a stream opened on the C side. 23298 23299@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 23300@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{312}@anchor{gnat_rm/the_gnat_library id32}@anchor{313} 23301@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) 23302 23303 23304@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) 23305 23306@geindex Text_IO resetting standard files 23307 23308This procedure is used to reset the status of the standard files used 23309by Ada.Text_IO. This is useful in a situation (such as a restart in an 23310embedded application) where the status of the files may change during 23311execution (for example a standard input file may be redefined to be 23312interactive). 23313 23314@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 23315@anchor{gnat_rm/the_gnat_library id33}@anchor{314}@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{315} 23316@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) 23317 23318 23319@geindex Ada.Wide_Characters.Unicode (a-wichun.ads) 23320 23321@geindex Unicode categorization 23322@geindex Wide_Character 23323 23324This package provides subprograms that allow categorization of 23325Wide_Character values according to Unicode categories. 23326 23327@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 23328@anchor{gnat_rm/the_gnat_library id34}@anchor{316}@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{317} 23329@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) 23330 23331 23332@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 23333 23334@geindex C Streams 23335@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} 23336 23337This package provides subprograms that allow interfacing between 23338C streams and @code{Wide_Text_IO}. The stream identifier can be 23339extracted from a file opened on the Ada side, and an Ada file 23340can be constructed from a stream opened on the C side. 23341 23342@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 23343@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{318}@anchor{gnat_rm/the_gnat_library id35}@anchor{319} 23344@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) 23345 23346 23347@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) 23348 23349@geindex Wide_Text_IO resetting standard files 23350 23351This procedure is used to reset the status of the standard files used 23352by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an 23353embedded application) where the status of the files may change during 23354execution (for example a standard input file may be redefined to be 23355interactive). 23356 23357@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 23358@anchor{gnat_rm/the_gnat_library id36}@anchor{31a}@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{31b} 23359@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) 23360 23361 23362@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) 23363 23364@geindex Unicode categorization 23365@geindex Wide_Wide_Character 23366 23367This package provides subprograms that allow categorization of 23368Wide_Wide_Character values according to Unicode categories. 23369 23370@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 23371@anchor{gnat_rm/the_gnat_library id37}@anchor{31c}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{31d} 23372@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) 23373 23374 23375@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) 23376 23377@geindex C Streams 23378@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} 23379 23380This package provides subprograms that allow interfacing between 23381C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be 23382extracted from a file opened on the Ada side, and an Ada file 23383can be constructed from a stream opened on the C side. 23384 23385@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 23386@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{31e}@anchor{gnat_rm/the_gnat_library id38}@anchor{31f} 23387@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) 23388 23389 23390@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) 23391 23392@geindex Wide_Wide_Text_IO resetting standard files 23393 23394This procedure is used to reset the status of the standard files used 23395by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a 23396restart in an embedded application) where the status of the files may 23397change during execution (for example a standard input file may be 23398redefined to be interactive). 23399 23400@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 23401@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{320}@anchor{gnat_rm/the_gnat_library id39}@anchor{321} 23402@section @code{GNAT.Altivec} (@code{g-altive.ads}) 23403 23404 23405@geindex GNAT.Altivec (g-altive.ads) 23406 23407@geindex AltiVec 23408 23409This is the root package of the GNAT AltiVec binding. It provides 23410definitions of constants and types common to all the versions of the 23411binding. 23412 23413@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library 23414@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{322}@anchor{gnat_rm/the_gnat_library id40}@anchor{323} 23415@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) 23416 23417 23418@geindex GNAT.Altivec.Conversions (g-altcon.ads) 23419 23420@geindex AltiVec 23421 23422This package provides the Vector/View conversion routines. 23423 23424@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library 23425@anchor{gnat_rm/the_gnat_library id41}@anchor{324}@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{325} 23426@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) 23427 23428 23429@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) 23430 23431@geindex AltiVec 23432 23433This package exposes the Ada interface to the AltiVec operations on 23434vector objects. A soft emulation is included by default in the GNAT 23435library. The hard binding is provided as a separate package. This unit 23436is common to both bindings. 23437 23438@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 23439@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{326}@anchor{gnat_rm/the_gnat_library id42}@anchor{327} 23440@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) 23441 23442 23443@geindex GNAT.Altivec.Vector_Types (g-alvety.ads) 23444 23445@geindex AltiVec 23446 23447This package exposes the various vector types part of the Ada binding 23448to AltiVec facilities. 23449 23450@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library 23451@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{328}@anchor{gnat_rm/the_gnat_library id43}@anchor{329} 23452@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) 23453 23454 23455@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) 23456 23457@geindex AltiVec 23458 23459This package provides public 'View' data types from/to which private 23460vector representations can be converted via 23461GNAT.Altivec.Conversions. This allows convenient access to individual 23462vector elements and provides a simple way to initialize vector 23463objects. 23464 23465@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library 23466@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{32a}@anchor{gnat_rm/the_gnat_library id44}@anchor{32b} 23467@section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) 23468 23469 23470@geindex GNAT.Array_Split (g-arrspl.ads) 23471 23472@geindex Array splitter 23473 23474Useful array-manipulation routines: given a set of separators, split 23475an array wherever the separators appear, and provide direct access 23476to the resulting slices. 23477 23478@node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library 23479@anchor{gnat_rm/the_gnat_library id45}@anchor{32c}@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{32d} 23480@section @code{GNAT.AWK} (@code{g-awk.ads}) 23481 23482 23483@geindex GNAT.AWK (g-awk.ads) 23484 23485@geindex Parsing 23486 23487@geindex AWK 23488 23489Provides AWK-like parsing functions, with an easy interface for parsing one 23490or more files containing formatted data. The file is viewed as a database 23491where each record is a line and a field is a data element in this line. 23492 23493@node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT AWK g-awk ads,The GNAT Library 23494@anchor{gnat_rm/the_gnat_library id46}@anchor{32e}@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{32f} 23495@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) 23496 23497 23498@geindex GNAT.Bind_Environment (g-binenv.ads) 23499 23500@geindex Bind environment 23501 23502Provides access to key=value associations captured at bind time. 23503These associations can be specified using the @code{-V} binder command 23504line switch. 23505 23506@node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library 23507@anchor{gnat_rm/the_gnat_library id47}@anchor{330}@anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{331} 23508@section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads}) 23509 23510 23511@geindex GNAT.Branch_Prediction (g-brapre.ads) 23512 23513@geindex Branch Prediction 23514 23515Provides routines giving hints to the branch predictor of the code generator. 23516 23517@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library 23518@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{332}@anchor{gnat_rm/the_gnat_library id48}@anchor{333} 23519@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) 23520 23521 23522@geindex GNAT.Bounded_Buffers (g-boubuf.ads) 23523 23524@geindex Parsing 23525 23526@geindex Bounded Buffers 23527 23528Provides a concurrent generic bounded buffer abstraction. Instances are 23529useful directly or as parts of the implementations of other abstractions, 23530such as mailboxes. 23531 23532@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library 23533@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{334}@anchor{gnat_rm/the_gnat_library id49}@anchor{335} 23534@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) 23535 23536 23537@geindex GNAT.Bounded_Mailboxes (g-boumai.ads) 23538 23539@geindex Parsing 23540 23541@geindex Mailboxes 23542 23543Provides a thread-safe asynchronous intertask mailbox communication facility. 23544 23545@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library 23546@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{336}@anchor{gnat_rm/the_gnat_library id50}@anchor{337} 23547@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) 23548 23549 23550@geindex GNAT.Bubble_Sort (g-bubsor.ads) 23551 23552@geindex Sorting 23553 23554@geindex Bubble sort 23555 23556Provides a general implementation of bubble sort usable for sorting arbitrary 23557data items. Exchange and comparison procedures are provided by passing 23558access-to-procedure values. 23559 23560@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library 23561@anchor{gnat_rm/the_gnat_library id51}@anchor{338}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{339} 23562@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) 23563 23564 23565@geindex GNAT.Bubble_Sort_A (g-busora.ads) 23566 23567@geindex Sorting 23568 23569@geindex Bubble sort 23570 23571Provides a general implementation of bubble sort usable for sorting arbitrary 23572data items. Move and comparison procedures are provided by passing 23573access-to-procedure values. This is an older version, retained for 23574compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. 23575 23576@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 23577@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{33a}@anchor{gnat_rm/the_gnat_library id52}@anchor{33b} 23578@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) 23579 23580 23581@geindex GNAT.Bubble_Sort_G (g-busorg.ads) 23582 23583@geindex Sorting 23584 23585@geindex Bubble sort 23586 23587Similar to @code{Bubble_Sort_A} except that the move and sorting procedures 23588are provided as generic parameters, this improves efficiency, especially 23589if the procedures can be inlined, at the expense of duplicating code for 23590multiple instantiations. 23591 23592@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library 23593@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{33c}@anchor{gnat_rm/the_gnat_library id53}@anchor{33d} 23594@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) 23595 23596 23597@geindex GNAT.Byte_Order_Mark (g-byorma.ads) 23598 23599@geindex UTF-8 representation 23600 23601@geindex Wide characte representations 23602 23603Provides a routine which given a string, reads the start of the string to 23604see whether it is one of the standard byte order marks (BOM's) which signal 23605the encoding of the string. The routine includes detection of special XML 23606sequences for various UCS input formats. 23607 23608@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library 23609@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{33e}@anchor{gnat_rm/the_gnat_library id54}@anchor{33f} 23610@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) 23611 23612 23613@geindex GNAT.Byte_Swapping (g-bytswa.ads) 23614 23615@geindex Byte swapping 23616 23617@geindex Endianness 23618 23619General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. 23620Machine-specific implementations are available in some cases. 23621 23622@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library 23623@anchor{gnat_rm/the_gnat_library id55}@anchor{340}@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{341} 23624@section @code{GNAT.Calendar} (@code{g-calend.ads}) 23625 23626 23627@geindex GNAT.Calendar (g-calend.ads) 23628 23629@geindex Calendar 23630 23631Extends the facilities provided by @code{Ada.Calendar} to include handling 23632of days of the week, an extended @code{Split} and @code{Time_Of} capability. 23633Also provides conversion of @code{Ada.Calendar.Time} values to and from the 23634C @code{timeval} format. 23635 23636@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library 23637@anchor{gnat_rm/the_gnat_library id56}@anchor{342}@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{343} 23638@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) 23639 23640 23641@geindex Calendar 23642 23643@geindex Time 23644 23645@geindex GNAT.Calendar.Time_IO (g-catiio.ads) 23646 23647@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library 23648@anchor{gnat_rm/the_gnat_library id57}@anchor{344}@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{345} 23649@section @code{GNAT.CRC32} (@code{g-crc32.ads}) 23650 23651 23652@geindex GNAT.CRC32 (g-crc32.ads) 23653 23654@geindex CRC32 23655 23656@geindex Cyclic Redundancy Check 23657 23658This package implements the CRC-32 algorithm. For a full description 23659of this algorithm see 23660@emph{Computation of Cyclic Redundancy Checks via Table Look-Up}, 23661@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, 23662Aug. 1988. Sarwate, D.V. 23663 23664@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library 23665@anchor{gnat_rm/the_gnat_library id58}@anchor{346}@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{347} 23666@section @code{GNAT.Case_Util} (@code{g-casuti.ads}) 23667 23668 23669@geindex GNAT.Case_Util (g-casuti.ads) 23670 23671@geindex Casing utilities 23672 23673@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) 23674 23675A set of simple routines for handling upper and lower casing of strings 23676without the overhead of the full casing tables 23677in @code{Ada.Characters.Handling}. 23678 23679@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library 23680@anchor{gnat_rm/the_gnat_library id59}@anchor{348}@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{349} 23681@section @code{GNAT.CGI} (@code{g-cgi.ads}) 23682 23683 23684@geindex GNAT.CGI (g-cgi.ads) 23685 23686@geindex CGI (Common Gateway Interface) 23687 23688This is a package for interfacing a GNAT program with a Web server via the 23689Common Gateway Interface (CGI). Basically this package parses the CGI 23690parameters, which are a set of key/value pairs sent by the Web server. It 23691builds a table whose index is the key and provides some services to deal 23692with this table. 23693 23694@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library 23695@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{34a}@anchor{gnat_rm/the_gnat_library id60}@anchor{34b} 23696@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) 23697 23698 23699@geindex GNAT.CGI.Cookie (g-cgicoo.ads) 23700 23701@geindex CGI (Common Gateway Interface) cookie support 23702 23703@geindex Cookie support in CGI 23704 23705This is a package to interface a GNAT program with a Web server via the 23706Common Gateway Interface (CGI). It exports services to deal with Web 23707cookies (piece of information kept in the Web client software). 23708 23709@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library 23710@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{34c}@anchor{gnat_rm/the_gnat_library id61}@anchor{34d} 23711@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) 23712 23713 23714@geindex GNAT.CGI.Debug (g-cgideb.ads) 23715 23716@geindex CGI (Common Gateway Interface) debugging 23717 23718This is a package to help debugging CGI (Common Gateway Interface) 23719programs written in Ada. 23720 23721@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library 23722@anchor{gnat_rm/the_gnat_library id62}@anchor{34e}@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{34f} 23723@section @code{GNAT.Command_Line} (@code{g-comlin.ads}) 23724 23725 23726@geindex GNAT.Command_Line (g-comlin.ads) 23727 23728@geindex Command line 23729 23730Provides a high level interface to @code{Ada.Command_Line} facilities, 23731including the ability to scan for named switches with optional parameters 23732and expand file names using wildcard notations. 23733 23734@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library 23735@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{350}@anchor{gnat_rm/the_gnat_library id63}@anchor{351} 23736@section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) 23737 23738 23739@geindex GNAT.Compiler_Version (g-comver.ads) 23740 23741@geindex Compiler Version 23742 23743@geindex Version 23744@geindex of compiler 23745 23746Provides a routine for obtaining the version of the compiler used to 23747compile the program. More accurately this is the version of the binder 23748used to bind the program (this will normally be the same as the version 23749of the compiler if a consistent tool set is used to compile all units 23750of a partition). 23751 23752@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library 23753@anchor{gnat_rm/the_gnat_library id64}@anchor{352}@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{353} 23754@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) 23755 23756 23757@geindex GNAT.Ctrl_C (g-ctrl_c.ads) 23758 23759@geindex Interrupt 23760 23761Provides a simple interface to handle Ctrl-C keyboard events. 23762 23763@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library 23764@anchor{gnat_rm/the_gnat_library id65}@anchor{354}@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{355} 23765@section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) 23766 23767 23768@geindex GNAT.Current_Exception (g-curexc.ads) 23769 23770@geindex Current exception 23771 23772@geindex Exception retrieval 23773 23774Provides access to information on the current exception that has been raised 23775without the need for using the Ada 95 / Ada 2005 exception choice parameter 23776specification syntax. 23777This is particularly useful in simulating typical facilities for 23778obtaining information about exceptions provided by Ada 83 compilers. 23779 23780@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library 23781@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{356}@anchor{gnat_rm/the_gnat_library id66}@anchor{357} 23782@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) 23783 23784 23785@geindex GNAT.Debug_Pools (g-debpoo.ads) 23786 23787@geindex Debugging 23788 23789@geindex Debug pools 23790 23791@geindex Memory corruption debugging 23792 23793Provide a debugging storage pools that helps tracking memory corruption 23794problems. 23795See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User's Guide}. 23796 23797@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library 23798@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{358}@anchor{gnat_rm/the_gnat_library id67}@anchor{359} 23799@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) 23800 23801 23802@geindex GNAT.Debug_Utilities (g-debuti.ads) 23803 23804@geindex Debugging 23805 23806Provides a few useful utilities for debugging purposes, including conversion 23807to and from string images of address values. Supports both C and Ada formats 23808for hexadecimal literals. 23809 23810@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library 23811@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{35a}@anchor{gnat_rm/the_gnat_library id68}@anchor{35b} 23812@section @code{GNAT.Decode_String} (@code{g-decstr.ads}) 23813 23814 23815@geindex GNAT.Decode_String (g-decstr.ads) 23816 23817@geindex Decoding strings 23818 23819@geindex String decoding 23820 23821@geindex Wide character encoding 23822 23823@geindex UTF-8 23824 23825@geindex Unicode 23826 23827A generic package providing routines for decoding wide character and wide wide 23828character strings encoded as sequences of 8-bit characters using a specified 23829encoding method. Includes validation routines, and also routines for stepping 23830to next or previous encoded character in an encoded string. 23831Useful in conjunction with Unicode character coding. Note there is a 23832preinstantiation for UTF-8. See next entry. 23833 23834@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library 23835@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{35c}@anchor{gnat_rm/the_gnat_library id69}@anchor{35d} 23836@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) 23837 23838 23839@geindex GNAT.Decode_UTF8_String (g-deutst.ads) 23840 23841@geindex Decoding strings 23842 23843@geindex Decoding UTF-8 strings 23844 23845@geindex UTF-8 string decoding 23846 23847@geindex Wide character decoding 23848 23849@geindex UTF-8 23850 23851@geindex Unicode 23852 23853A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. 23854 23855@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library 23856@anchor{gnat_rm/the_gnat_library id70}@anchor{35e}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{35f} 23857@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) 23858 23859 23860@geindex GNAT.Directory_Operations (g-dirope.ads) 23861 23862@geindex Directory operations 23863 23864Provides a set of routines for manipulating directories, including changing 23865the current directory, making new directories, and scanning the files in a 23866directory. 23867 23868@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library 23869@anchor{gnat_rm/the_gnat_library id71}@anchor{360}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{361} 23870@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) 23871 23872 23873@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) 23874 23875@geindex Directory operations iteration 23876 23877A child unit of GNAT.Directory_Operations providing additional operations 23878for iterating through directories. 23879 23880@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library 23881@anchor{gnat_rm/the_gnat_library id72}@anchor{362}@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{363} 23882@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) 23883 23884 23885@geindex GNAT.Dynamic_HTables (g-dynhta.ads) 23886 23887@geindex Hash tables 23888 23889A generic implementation of hash tables that can be used to hash arbitrary 23890data. Provided in two forms, a simple form with built in hash functions, 23891and a more complex form in which the hash function is supplied. 23892 23893This package provides a facility similar to that of @code{GNAT.HTable}, 23894except that this package declares a type that can be used to define 23895dynamic instances of the hash table, while an instantiation of 23896@code{GNAT.HTable} creates a single instance of the hash table. 23897 23898@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library 23899@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{364}@anchor{gnat_rm/the_gnat_library id73}@anchor{365} 23900@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) 23901 23902 23903@geindex GNAT.Dynamic_Tables (g-dyntab.ads) 23904 23905@geindex Table implementation 23906 23907@geindex Arrays 23908@geindex extendable 23909 23910A generic package providing a single dimension array abstraction where the 23911length of the array can be dynamically modified. 23912 23913This package provides a facility similar to that of @code{GNAT.Table}, 23914except that this package declares a type that can be used to define 23915dynamic instances of the table, while an instantiation of 23916@code{GNAT.Table} creates a single instance of the table type. 23917 23918@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library 23919@anchor{gnat_rm/the_gnat_library id74}@anchor{366}@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{367} 23920@section @code{GNAT.Encode_String} (@code{g-encstr.ads}) 23921 23922 23923@geindex GNAT.Encode_String (g-encstr.ads) 23924 23925@geindex Encoding strings 23926 23927@geindex String encoding 23928 23929@geindex Wide character encoding 23930 23931@geindex UTF-8 23932 23933@geindex Unicode 23934 23935A generic package providing routines for encoding wide character and wide 23936wide character strings as sequences of 8-bit characters using a specified 23937encoding method. Useful in conjunction with Unicode character coding. 23938Note there is a preinstantiation for UTF-8. See next entry. 23939 23940@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library 23941@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{368}@anchor{gnat_rm/the_gnat_library id75}@anchor{369} 23942@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) 23943 23944 23945@geindex GNAT.Encode_UTF8_String (g-enutst.ads) 23946 23947@geindex Encoding strings 23948 23949@geindex Encoding UTF-8 strings 23950 23951@geindex UTF-8 string encoding 23952 23953@geindex Wide character encoding 23954 23955@geindex UTF-8 23956 23957@geindex Unicode 23958 23959A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. 23960 23961@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library 23962@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{36a}@anchor{gnat_rm/the_gnat_library id76}@anchor{36b} 23963@section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) 23964 23965 23966@geindex GNAT.Exception_Actions (g-excact.ads) 23967 23968@geindex Exception actions 23969 23970Provides callbacks when an exception is raised. Callbacks can be registered 23971for specific exceptions, or when any exception is raised. This 23972can be used for instance to force a core dump to ease debugging. 23973 23974@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library 23975@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{36c}@anchor{gnat_rm/the_gnat_library id77}@anchor{36d} 23976@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) 23977 23978 23979@geindex GNAT.Exception_Traces (g-exctra.ads) 23980 23981@geindex Exception traces 23982 23983@geindex Debugging 23984 23985Provides an interface allowing to control automatic output upon exception 23986occurrences. 23987 23988@node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library 23989@anchor{gnat_rm/the_gnat_library id78}@anchor{36e}@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{36f} 23990@section @code{GNAT.Exceptions} (@code{g-except.ads}) 23991 23992 23993@geindex GNAT.Exceptions (g-except.ads) 23994 23995@geindex Exceptions 23996@geindex Pure 23997 23998@geindex Pure packages 23999@geindex exceptions 24000 24001Normally it is not possible to raise an exception with 24002a message from a subprogram in a pure package, since the 24003necessary types and subprograms are in @code{Ada.Exceptions} 24004which is not a pure unit. @code{GNAT.Exceptions} provides a 24005facility for getting around this limitation for a few 24006predefined exceptions, and for example allow raising 24007@code{Constraint_Error} with a message from a pure subprogram. 24008 24009@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library 24010@anchor{gnat_rm/the_gnat_library id79}@anchor{370}@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{371} 24011@section @code{GNAT.Expect} (@code{g-expect.ads}) 24012 24013 24014@geindex GNAT.Expect (g-expect.ads) 24015 24016Provides a set of subprograms similar to what is available 24017with the standard Tcl Expect tool. 24018It allows you to easily spawn and communicate with an external process. 24019You can send commands or inputs to the process, and compare the output 24020with some expected regular expression. Currently @code{GNAT.Expect} 24021is implemented on all native GNAT ports. 24022It is not implemented for cross ports, and in particular is not 24023implemented for VxWorks or LynxOS. 24024 24025@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library 24026@anchor{gnat_rm/the_gnat_library id80}@anchor{372}@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{373} 24027@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) 24028 24029 24030@geindex GNAT.Expect.TTY (g-exptty.ads) 24031 24032As GNAT.Expect but using pseudo-terminal. 24033Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT 24034ports. It is not implemented for cross ports, and 24035in particular is not implemented for VxWorks or LynxOS. 24036 24037@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library 24038@anchor{gnat_rm/the_gnat_library id81}@anchor{374}@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{375} 24039@section @code{GNAT.Float_Control} (@code{g-flocon.ads}) 24040 24041 24042@geindex GNAT.Float_Control (g-flocon.ads) 24043 24044@geindex Floating-Point Processor 24045 24046Provides an interface for resetting the floating-point processor into the 24047mode required for correct semantic operation in Ada. Some third party 24048library calls may cause this mode to be modified, and the Reset procedure 24049in this package can be used to reestablish the required mode. 24050 24051@node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library 24052@anchor{gnat_rm/the_gnat_library id82}@anchor{376}@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{377} 24053@section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) 24054 24055 24056@geindex GNAT.Formatted_String (g-forstr.ads) 24057 24058@geindex Formatted String 24059 24060Provides support for C/C++ printf() formatted strings. The format is 24061copied from the printf() routine and should therefore gives identical 24062output. Some generic routines are provided to be able to use types 24063derived from Integer, Float or enumerations as values for the 24064formatted string. 24065 24066@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library 24067@anchor{gnat_rm/the_gnat_library id83}@anchor{378}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{379} 24068@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) 24069 24070 24071@geindex GNAT.Heap_Sort (g-heasor.ads) 24072 24073@geindex Sorting 24074 24075Provides a general implementation of heap sort usable for sorting arbitrary 24076data items. Exchange and comparison procedures are provided by passing 24077access-to-procedure values. The algorithm used is a modified heap sort 24078that performs approximately N*log(N) comparisons in the worst case. 24079 24080@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library 24081@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{37a}@anchor{gnat_rm/the_gnat_library id84}@anchor{37b} 24082@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) 24083 24084 24085@geindex GNAT.Heap_Sort_A (g-hesora.ads) 24086 24087@geindex Sorting 24088 24089Provides a general implementation of heap sort usable for sorting arbitrary 24090data items. Move and comparison procedures are provided by passing 24091access-to-procedure values. The algorithm used is a modified heap sort 24092that performs approximately N*log(N) comparisons in the worst case. 24093This differs from @code{GNAT.Heap_Sort} in having a less convenient 24094interface, but may be slightly more efficient. 24095 24096@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library 24097@anchor{gnat_rm/the_gnat_library id85}@anchor{37c}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{37d} 24098@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) 24099 24100 24101@geindex GNAT.Heap_Sort_G (g-hesorg.ads) 24102 24103@geindex Sorting 24104 24105Similar to @code{Heap_Sort_A} except that the move and sorting procedures 24106are provided as generic parameters, this improves efficiency, especially 24107if the procedures can be inlined, at the expense of duplicating code for 24108multiple instantiations. 24109 24110@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library 24111@anchor{gnat_rm/the_gnat_library id86}@anchor{37e}@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{37f} 24112@section @code{GNAT.HTable} (@code{g-htable.ads}) 24113 24114 24115@geindex GNAT.HTable (g-htable.ads) 24116 24117@geindex Hash tables 24118 24119A generic implementation of hash tables that can be used to hash arbitrary 24120data. Provides two approaches, one a simple static approach, and the other 24121allowing arbitrary dynamic hash tables. 24122 24123@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library 24124@anchor{gnat_rm/the_gnat_library id87}@anchor{380}@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{381} 24125@section @code{GNAT.IO} (@code{g-io.ads}) 24126 24127 24128@geindex GNAT.IO (g-io.ads) 24129 24130@geindex Simple I/O 24131 24132@geindex Input/Output facilities 24133 24134A simple preelaborable input-output package that provides a subset of 24135simple Text_IO functions for reading characters and strings from 24136Standard_Input, and writing characters, strings and integers to either 24137Standard_Output or Standard_Error. 24138 24139@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library 24140@anchor{gnat_rm/the_gnat_library id88}@anchor{382}@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{383} 24141@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) 24142 24143 24144@geindex GNAT.IO_Aux (g-io_aux.ads) 24145 24146@geindex Text_IO 24147 24148@geindex Input/Output facilities 24149 24150Provides some auxiliary functions for use with Text_IO, including a test 24151for whether a file exists, and functions for reading a line of text. 24152 24153@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library 24154@anchor{gnat_rm/the_gnat_library id89}@anchor{384}@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{385} 24155@section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) 24156 24157 24158@geindex GNAT.Lock_Files (g-locfil.ads) 24159 24160@geindex File locking 24161 24162@geindex Locking using files 24163 24164Provides a general interface for using files as locks. Can be used for 24165providing program level synchronization. 24166 24167@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library 24168@anchor{gnat_rm/the_gnat_library id90}@anchor{386}@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{387} 24169@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) 24170 24171 24172@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) 24173 24174@geindex Random number generation 24175 24176The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses 24177a modified version of the Blum-Blum-Shub generator. 24178 24179@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library 24180@anchor{gnat_rm/the_gnat_library id91}@anchor{388}@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{389} 24181@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) 24182 24183 24184@geindex GNAT.MBBS_Float_Random (g-mbflra.ads) 24185 24186@geindex Random number generation 24187 24188The original implementation of @code{Ada.Numerics.Float_Random}. Uses 24189a modified version of the Blum-Blum-Shub generator. 24190 24191@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library 24192@anchor{gnat_rm/the_gnat_library id92}@anchor{38a}@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{38b} 24193@section @code{GNAT.MD5} (@code{g-md5.ads}) 24194 24195 24196@geindex GNAT.MD5 (g-md5.ads) 24197 24198@geindex Message Digest MD5 24199 24200Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and 24201the HMAC-MD5 message authentication function as described in RFC 2104 and 24202FIPS PUB 198. 24203 24204@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library 24205@anchor{gnat_rm/the_gnat_library id93}@anchor{38c}@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{38d} 24206@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) 24207 24208 24209@geindex GNAT.Memory_Dump (g-memdum.ads) 24210 24211@geindex Dump Memory 24212 24213Provides a convenient routine for dumping raw memory to either the 24214standard output or standard error files. Uses GNAT.IO for actual 24215output. 24216 24217@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library 24218@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{38e}@anchor{gnat_rm/the_gnat_library id94}@anchor{38f} 24219@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) 24220 24221 24222@geindex GNAT.Most_Recent_Exception (g-moreex.ads) 24223 24224@geindex Exception 24225@geindex obtaining most recent 24226 24227Provides access to the most recently raised exception. Can be used for 24228various logging purposes, including duplicating functionality of some 24229Ada 83 implementation dependent extensions. 24230 24231@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 24232@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{390}@anchor{gnat_rm/the_gnat_library id95}@anchor{391} 24233@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) 24234 24235 24236@geindex GNAT.OS_Lib (g-os_lib.ads) 24237 24238@geindex Operating System interface 24239 24240@geindex Spawn capability 24241 24242Provides a range of target independent operating system interface functions, 24243including time/date management, file operations, subprocess management, 24244including a portable spawn procedure, and access to environment variables 24245and error return codes. 24246 24247@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library 24248@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{392}@anchor{gnat_rm/the_gnat_library id96}@anchor{393} 24249@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) 24250 24251 24252@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) 24253 24254@geindex Hash functions 24255 24256Provides a generator of static minimal perfect hash functions. No 24257collisions occur and each item can be retrieved from the table in one 24258probe (perfect property). The hash table size corresponds to the exact 24259size of the key set and no larger (minimal property). The key set has to 24260be know in advance (static property). The hash functions are also order 24261preserving. If w2 is inserted after w1 in the generator, their 24262hashcode are in the same order. These hashing functions are very 24263convenient for use with realtime applications. 24264 24265@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library 24266@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{394}@anchor{gnat_rm/the_gnat_library id97}@anchor{395} 24267@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) 24268 24269 24270@geindex GNAT.Random_Numbers (g-rannum.ads) 24271 24272@geindex Random number generation 24273 24274Provides random number capabilities which extend those available in the 24275standard Ada library and are more convenient to use. 24276 24277@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library 24278@anchor{gnat_rm/the_gnat_library id98}@anchor{396}@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{25b} 24279@section @code{GNAT.Regexp} (@code{g-regexp.ads}) 24280 24281 24282@geindex GNAT.Regexp (g-regexp.ads) 24283 24284@geindex Regular expressions 24285 24286@geindex Pattern matching 24287 24288A simple implementation of regular expressions, using a subset of regular 24289expression syntax copied from familiar Unix style utilities. This is the 24290simplest of the three pattern matching packages provided, and is particularly 24291suitable for 'file globbing' applications. 24292 24293@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library 24294@anchor{gnat_rm/the_gnat_library id99}@anchor{397}@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{398} 24295@section @code{GNAT.Registry} (@code{g-regist.ads}) 24296 24297 24298@geindex GNAT.Registry (g-regist.ads) 24299 24300@geindex Windows Registry 24301 24302This is a high level binding to the Windows registry. It is possible to 24303do simple things like reading a key value, creating a new key. For full 24304registry API, but at a lower level of abstraction, refer to the Win32.Winreg 24305package provided with the Win32Ada binding 24306 24307@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library 24308@anchor{gnat_rm/the_gnat_library id100}@anchor{399}@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{39a} 24309@section @code{GNAT.Regpat} (@code{g-regpat.ads}) 24310 24311 24312@geindex GNAT.Regpat (g-regpat.ads) 24313 24314@geindex Regular expressions 24315 24316@geindex Pattern matching 24317 24318A complete implementation of Unix-style regular expression matching, copied 24319from the original V7 style regular expression library written in C by 24320Henry Spencer (and binary compatible with this C library). 24321 24322@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library 24323@anchor{gnat_rm/the_gnat_library id101}@anchor{39b}@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{39c} 24324@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) 24325 24326 24327@geindex GNAT.Rewrite_Data (g-rewdat.ads) 24328 24329@geindex Rewrite data 24330 24331A unit to rewrite on-the-fly string occurrences in a stream of 24332data. The implementation has a very minimal memory footprint as the 24333full content to be processed is not loaded into memory all at once. This makes 24334this interface usable for large files or socket streams. 24335 24336@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library 24337@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{39d}@anchor{gnat_rm/the_gnat_library id102}@anchor{39e} 24338@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) 24339 24340 24341@geindex GNAT.Secondary_Stack_Info (g-sestin.ads) 24342 24343@geindex Secondary Stack Info 24344 24345Provide the capability to query the high water mark of the current task's 24346secondary stack. 24347 24348@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library 24349@anchor{gnat_rm/the_gnat_library id103}@anchor{39f}@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{3a0} 24350@section @code{GNAT.Semaphores} (@code{g-semaph.ads}) 24351 24352 24353@geindex GNAT.Semaphores (g-semaph.ads) 24354 24355@geindex Semaphores 24356 24357Provides classic counting and binary semaphores using protected types. 24358 24359@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library 24360@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{3a1}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a2} 24361@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) 24362 24363 24364@geindex GNAT.Serial_Communications (g-sercom.ads) 24365 24366@geindex Serial_Communications 24367 24368Provides a simple interface to send and receive data over a serial 24369port. This is only supported on GNU/Linux and Windows. 24370 24371@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library 24372@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{3a3}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a4} 24373@section @code{GNAT.SHA1} (@code{g-sha1.ads}) 24374 24375 24376@geindex GNAT.SHA1 (g-sha1.ads) 24377 24378@geindex Secure Hash Algorithm SHA-1 24379 24380Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 24381and RFC 3174, and the HMAC-SHA1 message authentication function as described 24382in RFC 2104 and FIPS PUB 198. 24383 24384@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library 24385@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{3a5}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a6} 24386@section @code{GNAT.SHA224} (@code{g-sha224.ads}) 24387 24388 24389@geindex GNAT.SHA224 (g-sha224.ads) 24390 24391@geindex Secure Hash Algorithm SHA-224 24392 24393Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, 24394and the HMAC-SHA224 message authentication function as described 24395in RFC 2104 and FIPS PUB 198. 24396 24397@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library 24398@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{3a7}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a8} 24399@section @code{GNAT.SHA256} (@code{g-sha256.ads}) 24400 24401 24402@geindex GNAT.SHA256 (g-sha256.ads) 24403 24404@geindex Secure Hash Algorithm SHA-256 24405 24406Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, 24407and the HMAC-SHA256 message authentication function as described 24408in RFC 2104 and FIPS PUB 198. 24409 24410@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library 24411@anchor{gnat_rm/the_gnat_library id108}@anchor{3a9}@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3aa} 24412@section @code{GNAT.SHA384} (@code{g-sha384.ads}) 24413 24414 24415@geindex GNAT.SHA384 (g-sha384.ads) 24416 24417@geindex Secure Hash Algorithm SHA-384 24418 24419Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, 24420and the HMAC-SHA384 message authentication function as described 24421in RFC 2104 and FIPS PUB 198. 24422 24423@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library 24424@anchor{gnat_rm/the_gnat_library id109}@anchor{3ab}@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3ac} 24425@section @code{GNAT.SHA512} (@code{g-sha512.ads}) 24426 24427 24428@geindex GNAT.SHA512 (g-sha512.ads) 24429 24430@geindex Secure Hash Algorithm SHA-512 24431 24432Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, 24433and the HMAC-SHA512 message authentication function as described 24434in RFC 2104 and FIPS PUB 198. 24435 24436@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library 24437@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3ad}@anchor{gnat_rm/the_gnat_library id110}@anchor{3ae} 24438@section @code{GNAT.Signals} (@code{g-signal.ads}) 24439 24440 24441@geindex GNAT.Signals (g-signal.ads) 24442 24443@geindex Signals 24444 24445Provides the ability to manipulate the blocked status of signals on supported 24446targets. 24447 24448@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library 24449@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3af}@anchor{gnat_rm/the_gnat_library id111}@anchor{3b0} 24450@section @code{GNAT.Sockets} (@code{g-socket.ads}) 24451 24452 24453@geindex GNAT.Sockets (g-socket.ads) 24454 24455@geindex Sockets 24456 24457A high level and portable interface to develop sockets based applications. 24458This package is based on the sockets thin binding found in 24459@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented 24460on all native GNAT ports and on VxWorks cross prots. It is not implemented for 24461the LynxOS cross port. 24462 24463@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library 24464@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3b1}@anchor{gnat_rm/the_gnat_library id112}@anchor{3b2} 24465@section @code{GNAT.Source_Info} (@code{g-souinf.ads}) 24466 24467 24468@geindex GNAT.Source_Info (g-souinf.ads) 24469 24470@geindex Source Information 24471 24472Provides subprograms that give access to source code information known at 24473compile time, such as the current file name and line number. Also provides 24474subprograms yielding the date and time of the current compilation (like the 24475C macros @code{__DATE__} and @code{__TIME__}) 24476 24477@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library 24478@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3b3}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b4} 24479@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) 24480 24481 24482@geindex GNAT.Spelling_Checker (g-speche.ads) 24483 24484@geindex Spell checking 24485 24486Provides a function for determining whether one string is a plausible 24487near misspelling of another string. 24488 24489@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library 24490@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3b5}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b6} 24491@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) 24492 24493 24494@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) 24495 24496@geindex Spell checking 24497 24498Provides a generic function that can be instantiated with a string type for 24499determining whether one string is a plausible near misspelling of another 24500string. 24501 24502@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library 24503@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3b7}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b8} 24504@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) 24505 24506 24507@geindex GNAT.Spitbol.Patterns (g-spipat.ads) 24508 24509@geindex SPITBOL pattern matching 24510 24511@geindex Pattern matching 24512 24513A complete implementation of SNOBOL4 style pattern matching. This is the 24514most elaborate of the pattern matching packages provided. It fully duplicates 24515the SNOBOL4 dynamic pattern construction and matching capabilities, using the 24516efficient algorithm developed by Robert Dewar for the SPITBOL system. 24517 24518@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library 24519@anchor{gnat_rm/the_gnat_library id116}@anchor{3b9}@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3ba} 24520@section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) 24521 24522 24523@geindex GNAT.Spitbol (g-spitbo.ads) 24524 24525@geindex SPITBOL interface 24526 24527The top level package of the collection of SPITBOL-style functionality, this 24528package provides basic SNOBOL4 string manipulation functions, such as 24529Pad, Reverse, Trim, Substr capability, as well as a generic table function 24530useful for constructing arbitrary mappings from strings in the style of 24531the SNOBOL4 TABLE function. 24532 24533@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library 24534@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3bb}@anchor{gnat_rm/the_gnat_library id117}@anchor{3bc} 24535@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) 24536 24537 24538@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 24539 24540@geindex Sets of strings 24541 24542@geindex SPITBOL Tables 24543 24544A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 24545for type @code{Standard.Boolean}, giving an implementation of sets of 24546string values. 24547 24548@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 24549@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3bd}@anchor{gnat_rm/the_gnat_library id118}@anchor{3be} 24550@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) 24551 24552 24553@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) 24554 24555@geindex Integer maps 24556 24557@geindex Maps 24558 24559@geindex SPITBOL Tables 24560 24561A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 24562for type @code{Standard.Integer}, giving an implementation of maps 24563from string to integer values. 24564 24565@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library 24566@anchor{gnat_rm/the_gnat_library id119}@anchor{3bf}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3c0} 24567@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) 24568 24569 24570@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) 24571 24572@geindex String maps 24573 24574@geindex Maps 24575 24576@geindex SPITBOL Tables 24577 24578A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for 24579a variable length string type, giving an implementation of general 24580maps from strings to strings. 24581 24582@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library 24583@anchor{gnat_rm/the_gnat_library id120}@anchor{3c1}@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3c2} 24584@section @code{GNAT.SSE} (@code{g-sse.ads}) 24585 24586 24587@geindex GNAT.SSE (g-sse.ads) 24588 24589Root of a set of units aimed at offering Ada bindings to a subset of 24590the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of 24591targets. It exposes vector component types together with a general 24592introduction to the binding contents and use. 24593 24594@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library 24595@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3c3}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c4} 24596@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) 24597 24598 24599@geindex GNAT.SSE.Vector_Types (g-ssvety.ads) 24600 24601SSE vector types for use with SSE related intrinsics. 24602 24603@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library 24604@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3c5}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c6} 24605@section @code{GNAT.String_Hash} (@code{g-strhas.ads}) 24606 24607 24608@geindex GNAT.String_Hash (g-strhas.ads) 24609 24610@geindex Hash functions 24611 24612Provides a generic hash function working on arrays of scalars. Both the scalar 24613type and the hash result type are parameters. 24614 24615@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library 24616@anchor{gnat_rm/the_gnat_library id123}@anchor{3c7}@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3c8} 24617@section @code{GNAT.Strings} (@code{g-string.ads}) 24618 24619 24620@geindex GNAT.Strings (g-string.ads) 24621 24622Common String access types and related subprograms. Basically it 24623defines a string access and an array of string access types. 24624 24625@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library 24626@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3c9}@anchor{gnat_rm/the_gnat_library id124}@anchor{3ca} 24627@section @code{GNAT.String_Split} (@code{g-strspl.ads}) 24628 24629 24630@geindex GNAT.String_Split (g-strspl.ads) 24631 24632@geindex String splitter 24633 24634Useful string manipulation routines: given a set of separators, split 24635a string wherever the separators appear, and provide direct access 24636to the resulting slices. This package is instantiated from 24637@code{GNAT.Array_Split}. 24638 24639@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library 24640@anchor{gnat_rm/the_gnat_library id125}@anchor{3cb}@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3cc} 24641@section @code{GNAT.Table} (@code{g-table.ads}) 24642 24643 24644@geindex GNAT.Table (g-table.ads) 24645 24646@geindex Table implementation 24647 24648@geindex Arrays 24649@geindex extendable 24650 24651A generic package providing a single dimension array abstraction where the 24652length of the array can be dynamically modified. 24653 24654This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, 24655except that this package declares a single instance of the table type, 24656while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be 24657used to define dynamic instances of the table. 24658 24659@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library 24660@anchor{gnat_rm/the_gnat_library id126}@anchor{3cd}@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3ce} 24661@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) 24662 24663 24664@geindex GNAT.Task_Lock (g-tasloc.ads) 24665 24666@geindex Task synchronization 24667 24668@geindex Task locking 24669 24670@geindex Locking 24671 24672A very simple facility for locking and unlocking sections of code using a 24673single global task lock. Appropriate for use in situations where contention 24674between tasks is very rarely expected. 24675 24676@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library 24677@anchor{gnat_rm/the_gnat_library id127}@anchor{3cf}@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3d0} 24678@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) 24679 24680 24681@geindex GNAT.Time_Stamp (g-timsta.ads) 24682 24683@geindex Time stamp 24684 24685@geindex Current time 24686 24687Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that 24688represents the current date and time in ISO 8601 format. This is a very simple 24689routine with minimal code and there are no dependencies on any other unit. 24690 24691@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library 24692@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3d1}@anchor{gnat_rm/the_gnat_library id128}@anchor{3d2} 24693@section @code{GNAT.Threads} (@code{g-thread.ads}) 24694 24695 24696@geindex GNAT.Threads (g-thread.ads) 24697 24698@geindex Foreign threads 24699 24700@geindex Threads 24701@geindex foreign 24702 24703Provides facilities for dealing with foreign threads which need to be known 24704by the GNAT run-time system. Consult the documentation of this package for 24705further details if your program has threads that are created by a non-Ada 24706environment which then accesses Ada code. 24707 24708@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library 24709@anchor{gnat_rm/the_gnat_library id129}@anchor{3d3}@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3d4} 24710@section @code{GNAT.Traceback} (@code{g-traceb.ads}) 24711 24712 24713@geindex GNAT.Traceback (g-traceb.ads) 24714 24715@geindex Trace back facilities 24716 24717Provides a facility for obtaining non-symbolic traceback information, useful 24718in various debugging situations. 24719 24720@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library 24721@anchor{gnat_rm/the_gnat_library id130}@anchor{3d5}@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3d6} 24722@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) 24723 24724 24725@geindex GNAT.Traceback.Symbolic (g-trasym.ads) 24726 24727@geindex Trace back facilities 24728 24729@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library 24730@anchor{gnat_rm/the_gnat_library id131}@anchor{3d7}@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3d8} 24731@section @code{GNAT.UTF_32} (@code{g-table.ads}) 24732 24733 24734@geindex GNAT.UTF_32 (g-table.ads) 24735 24736@geindex Wide character codes 24737 24738This is a package intended to be used in conjunction with the 24739@code{Wide_Character} type in Ada 95 and the 24740@code{Wide_Wide_Character} type in Ada 2005 (available 24741in @code{GNAT} in Ada 2005 mode). This package contains 24742Unicode categorization routines, as well as lexical 24743categorization routines corresponding to the Ada 2005 24744lexical rules for identifiers and strings, and also a 24745lower case to upper case fold routine corresponding to 24746the Ada 2005 rules for identifier equivalence. 24747 24748@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library 24749@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3d9}@anchor{gnat_rm/the_gnat_library id132}@anchor{3da} 24750@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads}) 24751 24752 24753@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads) 24754 24755@geindex Spell checking 24756 24757Provides a function for determining whether one wide wide string is a plausible 24758near misspelling of another wide wide string, where the strings are represented 24759using the UTF_32_String type defined in System.Wch_Cnv. 24760 24761@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 24762@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3db}@anchor{gnat_rm/the_gnat_library id133}@anchor{3dc} 24763@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) 24764 24765 24766@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) 24767 24768@geindex Spell checking 24769 24770Provides a function for determining whether one wide string is a plausible 24771near misspelling of another wide string. 24772 24773@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 24774@anchor{gnat_rm/the_gnat_library id134}@anchor{3dd}@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3de} 24775@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) 24776 24777 24778@geindex GNAT.Wide_String_Split (g-wistsp.ads) 24779 24780@geindex Wide_String splitter 24781 24782Useful wide string manipulation routines: given a set of separators, split 24783a wide string wherever the separators appear, and provide direct access 24784to the resulting slices. This package is instantiated from 24785@code{GNAT.Array_Split}. 24786 24787@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 24788@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3df}@anchor{gnat_rm/the_gnat_library id135}@anchor{3e0} 24789@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) 24790 24791 24792@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) 24793 24794@geindex Spell checking 24795 24796Provides a function for determining whether one wide wide string is a plausible 24797near misspelling of another wide wide string. 24798 24799@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 24800@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3e1}@anchor{gnat_rm/the_gnat_library id136}@anchor{3e2} 24801@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) 24802 24803 24804@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) 24805 24806@geindex Wide_Wide_String splitter 24807 24808Useful wide wide string manipulation routines: given a set of separators, split 24809a wide wide string wherever the separators appear, and provide direct access 24810to the resulting slices. This package is instantiated from 24811@code{GNAT.Array_Split}. 24812 24813@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library 24814@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3e3}@anchor{gnat_rm/the_gnat_library id137}@anchor{3e4} 24815@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) 24816 24817 24818@geindex Interfaces.C.Extensions (i-cexten.ads) 24819 24820This package contains additional C-related definitions, intended 24821for use with either manually or automatically generated bindings 24822to C libraries. 24823 24824@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library 24825@anchor{gnat_rm/the_gnat_library id138}@anchor{3e5}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3e6} 24826@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) 24827 24828 24829@geindex Interfaces.C.Streams (i-cstrea.ads) 24830 24831@geindex C streams 24832@geindex interfacing 24833 24834This package is a binding for the most commonly used operations 24835on C streams. 24836 24837@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library 24838@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3e7}@anchor{gnat_rm/the_gnat_library id139}@anchor{3e8} 24839@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) 24840 24841 24842@geindex Interfaces.Packed_Decimal (i-pacdec.ads) 24843 24844@geindex IBM Packed Format 24845 24846@geindex Packed Decimal 24847 24848This package provides a set of routines for conversions to and 24849from a packed decimal format compatible with that used on IBM 24850mainframes. 24851 24852@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library 24853@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3e9}@anchor{gnat_rm/the_gnat_library id140}@anchor{3ea} 24854@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) 24855 24856 24857@geindex Interfaces.VxWorks (i-vxwork.ads) 24858 24859@geindex Interfacing to VxWorks 24860 24861@geindex VxWorks 24862@geindex interfacing 24863 24864This package provides a limited binding to the VxWorks API. 24865In particular, it interfaces with the 24866VxWorks hardware interrupt facilities. 24867 24868@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library 24869@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3eb}@anchor{gnat_rm/the_gnat_library id141}@anchor{3ec} 24870@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) 24871 24872 24873@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) 24874 24875@geindex Interfacing to VxWorks 24876 24877@geindex VxWorks 24878@geindex interfacing 24879 24880This package provides a way for users to replace the use of 24881intConnect() with a custom routine for installing interrupt 24882handlers. 24883 24884@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library 24885@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3ed}@anchor{gnat_rm/the_gnat_library id142}@anchor{3ee} 24886@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) 24887 24888 24889@geindex Interfaces.VxWorks.IO (i-vxwoio.ads) 24890 24891@geindex Interfacing to VxWorks' I/O 24892 24893@geindex VxWorks 24894@geindex I/O interfacing 24895 24896@geindex VxWorks 24897@geindex Get_Immediate 24898 24899@geindex Get_Immediate 24900@geindex VxWorks 24901 24902This package provides a binding to the ioctl (IO/Control) 24903function of VxWorks, defining a set of option values and 24904function codes. A particular use of this package is 24905to enable the use of Get_Immediate under VxWorks. 24906 24907@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library 24908@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3ef}@anchor{gnat_rm/the_gnat_library id143}@anchor{3f0} 24909@section @code{System.Address_Image} (@code{s-addima.ads}) 24910 24911 24912@geindex System.Address_Image (s-addima.ads) 24913 24914@geindex Address image 24915 24916@geindex Image 24917@geindex of an address 24918 24919This function provides a useful debugging 24920function that gives an (implementation dependent) 24921string which identifies an address. 24922 24923@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library 24924@anchor{gnat_rm/the_gnat_library id144}@anchor{3f1}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3f2} 24925@section @code{System.Assertions} (@code{s-assert.ads}) 24926 24927 24928@geindex System.Assertions (s-assert.ads) 24929 24930@geindex Assertions 24931 24932@geindex Assert_Failure 24933@geindex exception 24934 24935This package provides the declaration of the exception raised 24936by an run-time assertion failure, as well as the routine that 24937is used internally to raise this assertion. 24938 24939@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library 24940@anchor{gnat_rm/the_gnat_library id145}@anchor{3f3}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3f4} 24941@section @code{System.Atomic_Counters} (@code{s-atocou.ads}) 24942 24943 24944@geindex System.Atomic_Counters (s-atocou.ads) 24945 24946This package provides the declaration of an atomic counter type, 24947together with efficient routines (using hardware 24948synchronization primitives) for incrementing, decrementing, 24949and testing of these counters. This package is implemented 24950on most targets, including all Alpha, ia64, PowerPC, SPARC V9, 24951x86, and x86_64 platforms. 24952 24953@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library 24954@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3f5}@anchor{gnat_rm/the_gnat_library id146}@anchor{3f6} 24955@section @code{System.Memory} (@code{s-memory.ads}) 24956 24957 24958@geindex System.Memory (s-memory.ads) 24959 24960@geindex Memory allocation 24961 24962This package provides the interface to the low level routines used 24963by the generated code for allocation and freeing storage for the 24964default storage pool (analogous to the C routines malloc and free. 24965It also provides a reallocation interface analogous to the C routine 24966realloc. The body of this unit may be modified to provide alternative 24967allocation mechanisms for the default pool, and in addition, direct 24968calls to this unit may be made for low level allocation uses (for 24969example see the body of @code{GNAT.Tables}). 24970 24971@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library 24972@anchor{gnat_rm/the_gnat_library id147}@anchor{3f7}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3f8} 24973@section @code{System.Multiprocessors} (@code{s-multip.ads}) 24974 24975 24976@geindex System.Multiprocessors (s-multip.ads) 24977 24978@geindex Multiprocessor interface 24979 24980This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 24981in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 24982technically an implementation-defined addition). 24983 24984@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library 24985@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3f9}@anchor{gnat_rm/the_gnat_library id148}@anchor{3fa} 24986@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) 24987 24988 24989@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) 24990 24991@geindex Multiprocessor interface 24992 24993This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 24994in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 24995technically an implementation-defined addition). 24996 24997@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library 24998@anchor{gnat_rm/the_gnat_library id149}@anchor{3fb}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3fc} 24999@section @code{System.Partition_Interface} (@code{s-parint.ads}) 25000 25001 25002@geindex System.Partition_Interface (s-parint.ads) 25003 25004@geindex Partition interfacing functions 25005 25006This package provides facilities for partition interfacing. It 25007is used primarily in a distribution context when using Annex E 25008with @code{GLADE}. 25009 25010@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library 25011@anchor{gnat_rm/the_gnat_library id150}@anchor{3fd}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3fe} 25012@section @code{System.Pool_Global} (@code{s-pooglo.ads}) 25013 25014 25015@geindex System.Pool_Global (s-pooglo.ads) 25016 25017@geindex Storage pool 25018@geindex global 25019 25020@geindex Global storage pool 25021 25022This package provides a storage pool that is equivalent to the default 25023storage pool used for access types for which no pool is specifically 25024declared. It uses malloc/free to allocate/free and does not attempt to 25025do any automatic reclamation. 25026 25027@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library 25028@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3ff}@anchor{gnat_rm/the_gnat_library id151}@anchor{400} 25029@section @code{System.Pool_Local} (@code{s-pooloc.ads}) 25030 25031 25032@geindex System.Pool_Local (s-pooloc.ads) 25033 25034@geindex Storage pool 25035@geindex local 25036 25037@geindex Local storage pool 25038 25039This package provides a storage pool that is intended for use with locally 25040defined access types. It uses malloc/free for allocate/free, and maintains 25041a list of allocated blocks, so that all storage allocated for the pool can 25042be freed automatically when the pool is finalized. 25043 25044@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library 25045@anchor{gnat_rm/the_gnat_library id152}@anchor{401}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{402} 25046@section @code{System.Restrictions} (@code{s-restri.ads}) 25047 25048 25049@geindex System.Restrictions (s-restri.ads) 25050 25051@geindex Run-time restrictions access 25052 25053This package provides facilities for accessing at run time 25054the status of restrictions specified at compile time for 25055the partition. Information is available both with regard 25056to actual restrictions specified, and with regard to 25057compiler determined information on which restrictions 25058are violated by one or more packages in the partition. 25059 25060@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library 25061@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{403}@anchor{gnat_rm/the_gnat_library id153}@anchor{404} 25062@section @code{System.Rident} (@code{s-rident.ads}) 25063 25064 25065@geindex System.Rident (s-rident.ads) 25066 25067@geindex Restrictions definitions 25068 25069This package provides definitions of the restrictions 25070identifiers supported by GNAT, and also the format of 25071the restrictions provided in package System.Restrictions. 25072It is not normally necessary to @code{with} this generic package 25073since the necessary instantiation is included in 25074package System.Restrictions. 25075 25076@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library 25077@anchor{gnat_rm/the_gnat_library id154}@anchor{405}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{406} 25078@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) 25079 25080 25081@geindex System.Strings.Stream_Ops (s-ststop.ads) 25082 25083@geindex Stream operations 25084 25085@geindex String stream operations 25086 25087This package provides a set of stream subprograms for standard string types. 25088It is intended primarily to support implicit use of such subprograms when 25089stream attributes are applied to string types, but the subprograms in this 25090package can be used directly by application programs. 25091 25092@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library 25093@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{407}@anchor{gnat_rm/the_gnat_library id155}@anchor{408} 25094@section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) 25095 25096 25097@geindex System.Unsigned_Types (s-unstyp.ads) 25098 25099This package contains definitions of standard unsigned types that 25100correspond in size to the standard signed types declared in Standard, 25101and (unlike the types in Interfaces) have corresponding names. It 25102also contains some related definitions for other specialized types 25103used by the compiler in connection with packed array types. 25104 25105@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library 25106@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{409}@anchor{gnat_rm/the_gnat_library id156}@anchor{40a} 25107@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) 25108 25109 25110@geindex System.Wch_Cnv (s-wchcnv.ads) 25111 25112@geindex Wide Character 25113@geindex Representation 25114 25115@geindex Wide String 25116@geindex Conversion 25117 25118@geindex Representation of wide characters 25119 25120This package provides routines for converting between 25121wide and wide wide characters and a representation as a value of type 25122@code{Standard.String}, using a specified wide character 25123encoding method. It uses definitions in 25124package @code{System.Wch_Con}. 25125 25126@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library 25127@anchor{gnat_rm/the_gnat_library id157}@anchor{40b}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{40c} 25128@section @code{System.Wch_Con} (@code{s-wchcon.ads}) 25129 25130 25131@geindex System.Wch_Con (s-wchcon.ads) 25132 25133This package provides definitions and descriptions of 25134the various methods used for encoding wide characters 25135in ordinary strings. These definitions are used by 25136the package @code{System.Wch_Cnv}. 25137 25138@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top 25139@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{40d}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{40e} 25140@chapter Interfacing to Other Languages 25141 25142 25143The facilities in Annex B of the Ada Reference Manual are fully 25144implemented in GNAT, and in addition, a full interface to C++ is 25145provided. 25146 25147@menu 25148* Interfacing to C:: 25149* Interfacing to C++:: 25150* Interfacing to COBOL:: 25151* Interfacing to Fortran:: 25152* Interfacing to non-GNAT Ada code:: 25153 25154@end menu 25155 25156@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages 25157@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{40f}@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{410} 25158@section Interfacing to C 25159 25160 25161Interfacing to C with GNAT can use one of two approaches: 25162 25163 25164@itemize * 25165 25166@item 25167The types in the package @code{Interfaces.C} may be used. 25168 25169@item 25170Standard Ada types may be used directly. This may be less portable to 25171other compilers, but will work on all GNAT compilers, which guarantee 25172correspondence between the C and Ada types. 25173@end itemize 25174 25175Pragma @code{Convention C} may be applied to Ada types, but mostly has no 25176effect, since this is the default. The following table shows the 25177correspondence between Ada scalar types and the corresponding C types. 25178 25179 25180@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} 25181@headitem 25182 25183Ada Type 25184 25185@tab 25186 25187C Type 25188 25189@item 25190 25191@code{Integer} 25192 25193@tab 25194 25195@code{int} 25196 25197@item 25198 25199@code{Short_Integer} 25200 25201@tab 25202 25203@code{short} 25204 25205@item 25206 25207@code{Short_Short_Integer} 25208 25209@tab 25210 25211@code{signed char} 25212 25213@item 25214 25215@code{Long_Integer} 25216 25217@tab 25218 25219@code{long} 25220 25221@item 25222 25223@code{Long_Long_Integer} 25224 25225@tab 25226 25227@code{long long} 25228 25229@item 25230 25231@code{Short_Float} 25232 25233@tab 25234 25235@code{float} 25236 25237@item 25238 25239@code{Float} 25240 25241@tab 25242 25243@code{float} 25244 25245@item 25246 25247@code{Long_Float} 25248 25249@tab 25250 25251@code{double} 25252 25253@item 25254 25255@code{Long_Long_Float} 25256 25257@tab 25258 25259This is the longest floating-point type supported by the hardware. 25260 25261@end multitable 25262 25263 25264Additionally, there are the following general correspondences between Ada 25265and C types: 25266 25267 25268@itemize * 25269 25270@item 25271Ada enumeration types map to C enumeration types directly if pragma 25272@code{Convention C} is specified, which causes them to have a length of 2527332 bits, except for boolean types which map to C99 @code{bool} and for 25274which the length is 8 bits. 25275Without pragma @code{Convention C}, Ada enumeration types map to 252768, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, 25277@code{int}, respectively) depending on the number of values passed. 25278This is the only case in which pragma @code{Convention C} affects the 25279representation of an Ada type. 25280 25281@item 25282Ada access types map to C pointers, except for the case of pointers to 25283unconstrained types in Ada, which have no direct C equivalent. 25284 25285@item 25286Ada arrays map directly to C arrays. 25287 25288@item 25289Ada records map directly to C structures. 25290 25291@item 25292Packed Ada records map to C structures where all members are bit fields 25293of the length corresponding to the @code{type'Size} value in Ada. 25294@end itemize 25295 25296@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages 25297@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{411}@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{47} 25298@section Interfacing to C++ 25299 25300 25301The interface to C++ makes use of the following pragmas, which are 25302primarily intended to be constructed automatically using a binding generator 25303tool, although it is possible to construct them by hand. 25304 25305Using these pragmas it is possible to achieve complete 25306inter-operability between Ada tagged types and C++ class definitions. 25307See @ref{7,,Implementation Defined Pragmas}, for more details. 25308 25309 25310@table @asis 25311 25312@item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})} 25313 25314The argument denotes an entity in the current declarative region that is 25315declared as a tagged or untagged record type. It indicates that the type 25316corresponds to an externally declared C++ class type, and is to be laid 25317out the same way that C++ would lay out the type. 25318 25319Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 25320for backward compatibility but its functionality is available 25321using pragma @code{Import} with @code{Convention} = @code{CPP}. 25322 25323@item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})} 25324 25325This pragma identifies an imported function (imported in the usual way 25326with pragma @code{Import}) as corresponding to a C++ constructor. 25327@end table 25328 25329A few restrictions are placed on the use of the @code{Access} attribute 25330in conjunction with subprograms subject to convention @code{CPP}: the 25331attribute may be used neither on primitive operations of a tagged 25332record type with convention @code{CPP}, imported or not, nor on 25333subprograms imported with pragma @code{CPP_Constructor}. 25334 25335In addition, C++ exceptions are propagated and can be handled in an 25336@code{others} choice of an exception handler. The corresponding Ada 25337occurrence has no message, and the simple name of the exception identity 25338contains @code{Foreign_Exception}. Finalization and awaiting dependent 25339tasks works properly when such foreign exceptions are propagated. 25340 25341It is also possible to import a C++ exception using the following syntax: 25342 25343@example 25344LOCAL_NAME : exception; 25345pragma Import (Cpp, 25346 [Entity =>] LOCAL_NAME, 25347 [External_Name =>] static_string_EXPRESSION); 25348@end example 25349 25350The @code{External_Name} is the name of the C++ RTTI symbol. You can then 25351cover a specific C++ exception in an exception handler. 25352 25353@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages 25354@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{412}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{413} 25355@section Interfacing to COBOL 25356 25357 25358Interfacing to COBOL is achieved as described in section B.4 of 25359the Ada Reference Manual. 25360 25361@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages 25362@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{414}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{415} 25363@section Interfacing to Fortran 25364 25365 25366Interfacing to Fortran is achieved as described in section B.5 of the 25367Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a 25368multi-dimensional array causes the array to be stored in column-major 25369order as required for convenient interface to Fortran. 25370 25371@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages 25372@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{416}@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{417} 25373@section Interfacing to non-GNAT Ada code 25374 25375 25376It is possible to specify the convention @code{Ada} in a pragma 25377@code{Import} or pragma @code{Export}. However this refers to 25378the calling conventions used by GNAT, which may or may not be 25379similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 25380compiler to allow interoperation. 25381 25382If arguments types are kept simple, and if the foreign compiler generally 25383follows system calling conventions, then it may be possible to integrate 25384files compiled by other Ada compilers, provided that the elaboration 25385issues are adequately addressed (for example by eliminating the 25386need for any load time elaboration). 25387 25388In particular, GNAT running on VMS is designed to 25389be highly compatible with the DEC Ada 83 compiler, so this is one 25390case in which it is possible to import foreign units of this type, 25391provided that the data items passed are restricted to simple scalar 25392values or simple record types without variants, or simple array 25393types with fixed bounds. 25394 25395@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top 25396@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{418}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{419} 25397@chapter Specialized Needs Annexes 25398 25399 25400Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not 25401required in all implementations. However, as described in this chapter, 25402GNAT implements all of these annexes: 25403 25404 25405@table @asis 25406 25407@item @emph{Systems Programming (Annex C)} 25408 25409The Systems Programming Annex is fully implemented. 25410 25411@item @emph{Real-Time Systems (Annex D)} 25412 25413The Real-Time Systems Annex is fully implemented. 25414 25415@item @emph{Distributed Systems (Annex E)} 25416 25417Stub generation is fully implemented in the GNAT compiler. In addition, 25418a complete compatible PCS is available as part of the GLADE system, 25419a separate product. When the two 25420products are used in conjunction, this annex is fully implemented. 25421 25422@item @emph{Information Systems (Annex F)} 25423 25424The Information Systems annex is fully implemented. 25425 25426@item @emph{Numerics (Annex G)} 25427 25428The Numerics Annex is fully implemented. 25429 25430@item @emph{Safety and Security / High-Integrity Systems (Annex H)} 25431 25432The Safety and Security Annex (termed the High-Integrity Systems Annex 25433in Ada 2005) is fully implemented. 25434@end table 25435 25436@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top 25437@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{41a}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{41b} 25438@chapter Implementation of Specific Ada Features 25439 25440 25441This chapter describes the GNAT implementation of several Ada language 25442facilities. 25443 25444@menu 25445* Machine Code Insertions:: 25446* GNAT Implementation of Tasking:: 25447* GNAT Implementation of Shared Passive Packages:: 25448* Code Generation for Array Aggregates:: 25449* The Size of Discriminated Records with Default Discriminants:: 25450* Strict Conformance to the Ada Reference Manual:: 25451 25452@end menu 25453 25454@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features 25455@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{169}@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{41c} 25456@section Machine Code Insertions 25457 25458 25459@geindex Machine Code insertions 25460 25461Package @code{Machine_Code} provides machine code support as described 25462in the Ada Reference Manual in two separate forms: 25463 25464 25465@itemize * 25466 25467@item 25468Machine code statements, consisting of qualified expressions that 25469fit the requirements of RM section 13.8. 25470 25471@item 25472An intrinsic callable procedure, providing an alternative mechanism of 25473including machine instructions in a subprogram. 25474@end itemize 25475 25476The two features are similar, and both are closely related to the mechanism 25477provided by the asm instruction in the GNU C compiler. Full understanding 25478and use of the facilities in this package requires understanding the asm 25479instruction, see the section on Extended Asm in 25480@cite{Using_the_GNU_Compiler_Collection_(GCC)}. 25481 25482Calls to the function @code{Asm} and the procedure @code{Asm} have identical 25483semantic restrictions and effects as described below. Both are provided so 25484that the procedure call can be used as a statement, and the function call 25485can be used to form a code_statement. 25486 25487Consider this C @code{asm} instruction: 25488 25489@example 25490asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 25491@end example 25492 25493The equivalent can be written for GNAT as: 25494 25495@example 25496Asm ("fsinx %1 %0", 25497 My_Float'Asm_Output ("=f", result), 25498 My_Float'Asm_Input ("f", angle)); 25499@end example 25500 25501The first argument to @code{Asm} is the assembler template, and is 25502identical to what is used in GNU C. This string must be a static 25503expression. The second argument is the output operand list. It is 25504either a single @code{Asm_Output} attribute reference, or a list of such 25505references enclosed in parentheses (technically an array aggregate of 25506such references). 25507 25508The @code{Asm_Output} attribute denotes a function that takes two 25509parameters. The first is a string, the second is the name of a variable 25510of the type designated by the attribute prefix. The first (string) 25511argument is required to be a static expression and designates the 25512constraint (see the section on Constraints in 25513@cite{Using_the_GNU_Compiler_Collection_(GCC)}) 25514for the parameter; e.g., what kind of register is required. The second 25515argument is the variable to be written or updated with the 25516result. The possible values for constraint are the same as those used in 25517the RTL, and are dependent on the configuration file used to build the 25518GCC back end. If there are no output operands, then this argument may 25519either be omitted, or explicitly given as @code{No_Output_Operands}. 25520No support is provided for GNU C's symbolic names for output parameters. 25521 25522The second argument of @code{my_float'Asm_Output} functions as 25523though it were an @code{out} parameter, which is a little curious, but 25524all names have the form of expressions, so there is no syntactic 25525irregularity, even though normally functions would not be permitted 25526@code{out} parameters. The third argument is the list of input 25527operands. It is either a single @code{Asm_Input} attribute reference, or 25528a list of such references enclosed in parentheses (technically an array 25529aggregate of such references). 25530 25531The @code{Asm_Input} attribute denotes a function that takes two 25532parameters. The first is a string, the second is an expression of the 25533type designated by the prefix. The first (string) argument is required 25534to be a static expression, and is the constraint for the parameter, 25535(e.g., what kind of register is required). The second argument is the 25536value to be used as the input argument. The possible values for the 25537constraint are the same as those used in the RTL, and are dependent on 25538the configuration file used to built the GCC back end. 25539No support is provided for GNU C's symbolic names for input parameters. 25540 25541If there are no input operands, this argument may either be omitted, or 25542explicitly given as @code{No_Input_Operands}. The fourth argument, not 25543present in the above example, is a list of register names, called the 25544@emph{clobber} argument. This argument, if given, must be a static string 25545expression, and is a space or comma separated list of names of registers 25546that must be considered destroyed as a result of the @code{Asm} call. If 25547this argument is the null string (the default value), then the code 25548generator assumes that no additional registers are destroyed. 25549In addition to registers, the special clobbers @code{memory} and 25550@code{cc} as described in the GNU C docs are both supported. 25551 25552The fifth argument, not present in the above example, called the 25553@emph{volatile} argument, is by default @code{False}. It can be set to 25554the literal value @code{True} to indicate to the code generator that all 25555optimizations with respect to the instruction specified should be 25556suppressed, and in particular an instruction that has outputs 25557will still be generated, even if none of the outputs are 25558used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} 25559for the full description. 25560Generally it is strongly advisable to use Volatile for any ASM statement 25561that is missing either input or output operands or to avoid unwanted 25562optimizations. A warning is generated if this advice is not followed. 25563 25564No support is provided for GNU C's @code{asm goto} feature. 25565 25566The @code{Asm} subprograms may be used in two ways. First the procedure 25567forms can be used anywhere a procedure call would be valid, and 25568correspond to what the RM calls 'intrinsic' routines. Such calls can 25569be used to intersperse machine instructions with other Ada statements. 25570Second, the function forms, which return a dummy value of the limited 25571private type @code{Asm_Insn}, can be used in code statements, and indeed 25572this is the only context where such calls are allowed. Code statements 25573appear as aggregates of the form: 25574 25575@example 25576Asm_Insn'(Asm (...)); 25577Asm_Insn'(Asm_Volatile (...)); 25578@end example 25579 25580In accordance with RM rules, such code statements are allowed only 25581within subprograms whose entire body consists of such statements. It is 25582not permissible to intermix such statements with other Ada statements. 25583 25584Typically the form using intrinsic procedure calls is more convenient 25585and more flexible. The code statement form is provided to meet the RM 25586suggestion that such a facility should be made available. The following 25587is the exact syntax of the call to @code{Asm}. As usual, if named notation 25588is used, the arguments may be given in arbitrary order, following the 25589normal rules for use of positional and named arguments: 25590 25591@example 25592ASM_CALL ::= Asm ( 25593 [Template =>] static_string_EXPRESSION 25594 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 25595 [,[Inputs =>] INPUT_OPERAND_LIST ] 25596 [,[Clobber =>] static_string_EXPRESSION ] 25597 [,[Volatile =>] static_boolean_EXPRESSION] ) 25598 25599OUTPUT_OPERAND_LIST ::= 25600 [PREFIX.]No_Output_Operands 25601| OUTPUT_OPERAND_ATTRIBUTE 25602| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 25603 25604OUTPUT_OPERAND_ATTRIBUTE ::= 25605 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 25606 25607INPUT_OPERAND_LIST ::= 25608 [PREFIX.]No_Input_Operands 25609| INPUT_OPERAND_ATTRIBUTE 25610| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 25611 25612INPUT_OPERAND_ATTRIBUTE ::= 25613 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 25614@end example 25615 25616The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} 25617are declared in the package @code{Machine_Code} and must be referenced 25618according to normal visibility rules. In particular if there is no 25619@code{use} clause for this package, then appropriate package name 25620qualification is required. 25621 25622@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features 25623@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{41e} 25624@section GNAT Implementation of Tasking 25625 25626 25627This chapter outlines the basic GNAT approach to tasking (in particular, 25628a multi-layered library for portability) and discusses issues related 25629to compliance with the Real-Time Systems Annex. 25630 25631@menu 25632* Mapping Ada Tasks onto the Underlying Kernel Threads:: 25633* Ensuring Compliance with the Real-Time Annex:: 25634* Support for Locking Policies:: 25635 25636@end menu 25637 25638@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking 25639@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{41f}@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{420} 25640@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 25641 25642 25643GNAT's run-time support comprises two layers: 25644 25645 25646@itemize * 25647 25648@item 25649GNARL (GNAT Run-time Layer) 25650 25651@item 25652GNULL (GNAT Low-level Library) 25653@end itemize 25654 25655In GNAT, Ada's tasking services rely on a platform and OS independent 25656layer known as GNARL. This code is responsible for implementing the 25657correct semantics of Ada's task creation, rendezvous, protected 25658operations etc. 25659 25660GNARL decomposes Ada's tasking semantics into simpler lower level 25661operations such as create a thread, set the priority of a thread, 25662yield, create a lock, lock/unlock, etc. The spec for these low-level 25663operations constitutes GNULLI, the GNULL Interface. This interface is 25664directly inspired from the POSIX real-time API. 25665 25666If the underlying executive or OS implements the POSIX standard 25667faithfully, the GNULL Interface maps as is to the services offered by 25668the underlying kernel. Otherwise, some target dependent glue code maps 25669the services offered by the underlying kernel to the semantics expected 25670by GNARL. 25671 25672Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the 25673key point is that each Ada task is mapped on a thread in the underlying 25674kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 25675 25676In addition Ada task priorities map onto the underlying thread priorities. 25677Mapping Ada tasks onto the underlying kernel threads has several advantages: 25678 25679 25680@itemize * 25681 25682@item 25683The underlying scheduler is used to schedule the Ada tasks. This 25684makes Ada tasks as efficient as kernel threads from a scheduling 25685standpoint. 25686 25687@item 25688Interaction with code written in C containing threads is eased 25689since at the lowest level Ada tasks and C threads map onto the same 25690underlying kernel concept. 25691 25692@item 25693When an Ada task is blocked during I/O the remaining Ada tasks are 25694able to proceed. 25695 25696@item 25697On multiprocessor systems Ada tasks can execute in parallel. 25698@end itemize 25699 25700Some threads libraries offer a mechanism to fork a new process, with the 25701child process duplicating the threads from the parent. 25702GNAT does not 25703support this functionality when the parent contains more than one task. 25704 25705@geindex Forking a new process 25706 25707@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking 25708@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{421}@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{422} 25709@subsection Ensuring Compliance with the Real-Time Annex 25710 25711 25712@geindex Real-Time Systems Annex compliance 25713 25714Although mapping Ada tasks onto 25715the underlying threads has significant advantages, it does create some 25716complications when it comes to respecting the scheduling semantics 25717specified in the real-time annex (Annex D). 25718 25719For instance the Annex D requirement for the @code{FIFO_Within_Priorities} 25720scheduling policy states: 25721 25722@quotation 25723 25724@emph{When the active priority of a ready task that is not running 25725changes, or the setting of its base priority takes effect, the 25726task is removed from the ready queue for its old active priority 25727and is added at the tail of the ready queue for its new active 25728priority, except in the case where the active priority is lowered 25729due to the loss of inherited priority, in which case the task is 25730added at the head of the ready queue for its new active priority.} 25731@end quotation 25732 25733While most kernels do put tasks at the end of the priority queue when 25734a task changes its priority, (which respects the main 25735FIFO_Within_Priorities requirement), almost none keep a thread at the 25736beginning of its priority queue when its priority drops from the loss 25737of inherited priority. 25738 25739As a result most vendors have provided incomplete Annex D implementations. 25740 25741The GNAT run-time, has a nice cooperative solution to this problem 25742which ensures that accurate FIFO_Within_Priorities semantics are 25743respected. 25744 25745The principle is as follows. When an Ada task T is about to start 25746running, it checks whether some other Ada task R with the same 25747priority as T has been suspended due to the loss of priority 25748inheritance. If this is the case, T yields and is placed at the end of 25749its priority queue. When R arrives at the front of the queue it 25750executes. 25751 25752Note that this simple scheme preserves the relative order of the tasks 25753that were ready to execute in the priority queue where R has been 25754placed at the end. 25755 25756@c Support_for_Locking_Policies 25757 25758@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking 25759@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{423} 25760@subsection Support for Locking Policies 25761 25762 25763This section specifies which policies specified by pragma Locking_Policy 25764are supported on which platforms. 25765 25766GNAT supports the standard @code{Ceiling_Locking} policy, and the 25767implementation defined @code{Inheritance_Locking} and 25768@code{Concurrent_Readers_Locking} policies. 25769 25770@code{Ceiling_Locking} is supported on all platforms if the operating system 25771supports it. In particular, @code{Ceiling_Locking} is not supported on 25772VxWorks. 25773@code{Inheritance_Locking} is supported on 25774Linux, 25775Darwin (Mac OS X), 25776LynxOS 178, 25777and VxWorks. 25778@code{Concurrent_Readers_Locking} is supported on Linux. 25779 25780Notes about @code{Ceiling_Locking} on Linux: 25781If the process is running as 'root', ceiling locking is used. 25782If the capabilities facility is installed 25783("sudo apt-get --assume-yes install libcap-dev" on Ubuntu, 25784for example), 25785and the program is linked against that library 25786("-largs -lcap"), 25787and the executable file has the cap_sys_nice capability 25788("sudo /sbin/setcap cap_sys_nice=ep executable_file_name"), 25789then ceiling locking is used. 25790Otherwise, the @code{Ceiling_Locking} policy is ignored. 25791 25792@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features 25793@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{424}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{425} 25794@section GNAT Implementation of Shared Passive Packages 25795 25796 25797@geindex Shared passive packages 25798 25799GNAT fully implements the 25800@geindex pragma Shared_Passive 25801pragma 25802@code{Shared_Passive} for 25803the purpose of designating shared passive packages. 25804This allows the use of passive partitions in the 25805context described in the Ada Reference Manual; i.e., for communication 25806between separate partitions of a distributed application using the 25807features in Annex E. 25808 25809@geindex Annex E 25810 25811@geindex Distribution Systems Annex 25812 25813However, the implementation approach used by GNAT provides for more 25814extensive usage as follows: 25815 25816 25817@table @asis 25818 25819@item @emph{Communication between separate programs} 25820 25821This allows separate programs to access the data in passive 25822partitions, using protected objects for synchronization where 25823needed. The only requirement is that the two programs have a 25824common shared file system. It is even possible for programs 25825running on different machines with different architectures 25826(e.g., different endianness) to communicate via the data in 25827a passive partition. 25828 25829@item @emph{Persistence between program runs} 25830 25831The data in a passive package can persist from one run of a 25832program to another, so that a later program sees the final 25833values stored by a previous run of the same program. 25834@end table 25835 25836The implementation approach used is to store the data in files. A 25837separate stream file is created for each object in the package, and 25838an access to an object causes the corresponding file to be read or 25839written. 25840 25841@geindex SHARED_MEMORY_DIRECTORY environment variable 25842 25843The environment variable @code{SHARED_MEMORY_DIRECTORY} should be 25844set to the directory to be used for these files. 25845The files in this directory 25846have names that correspond to their fully qualified names. For 25847example, if we have the package 25848 25849@example 25850package X is 25851 pragma Shared_Passive (X); 25852 Y : Integer; 25853 Z : Float; 25854end X; 25855@end example 25856 25857and the environment variable is set to @code{/stemp/}, then the files created 25858will have the names: 25859 25860@example 25861/stemp/x.y 25862/stemp/x.z 25863@end example 25864 25865These files are created when a value is initially written to the object, and 25866the files are retained until manually deleted. This provides the persistence 25867semantics. If no file exists, it means that no partition has assigned a value 25868to the variable; in this case the initial value declared in the package 25869will be used. This model ensures that there are no issues in synchronizing 25870the elaboration process, since elaboration of passive packages elaborates the 25871initial values, but does not create the files. 25872 25873The files are written using normal @code{Stream_IO} access. 25874If you want to be able 25875to communicate between programs or partitions running on different 25876architectures, then you should use the XDR versions of the stream attribute 25877routines, since these are architecture independent. 25878 25879If active synchronization is required for access to the variables in the 25880shared passive package, then as described in the Ada Reference Manual, the 25881package may contain protected objects used for this purpose. In this case 25882a lock file (whose name is @code{___lock} (three underscores) 25883is created in the shared memory directory. 25884 25885@geindex ___lock file (for shared passive packages) 25886 25887This is used to provide the required locking 25888semantics for proper protected object synchronization. 25889 25890@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 25891@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{426}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{427} 25892@section Code Generation for Array Aggregates 25893 25894 25895Aggregates have a rich syntax and allow the user to specify the values of 25896complex data structures by means of a single construct. As a result, the 25897code generated for aggregates can be quite complex and involve loops, case 25898statements and multiple assignments. In the simplest cases, however, the 25899compiler will recognize aggregates whose components and constraints are 25900fully static, and in those cases the compiler will generate little or no 25901executable code. The following is an outline of the code that GNAT generates 25902for various aggregate constructs. For further details, you will find it 25903useful to examine the output produced by the -gnatG flag to see the expanded 25904source that is input to the code generator. You may also want to examine 25905the assembly code generated at various levels of optimization. 25906 25907The code generated for aggregates depends on the context, the component values, 25908and the type. In the context of an object declaration the code generated is 25909generally simpler than in the case of an assignment. As a general rule, static 25910component values and static subtypes also lead to simpler code. 25911 25912@menu 25913* Static constant aggregates with static bounds:: 25914* Constant aggregates with unconstrained nominal types:: 25915* Aggregates with static bounds:: 25916* Aggregates with nonstatic bounds:: 25917* Aggregates in assignment statements:: 25918 25919@end menu 25920 25921@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates 25922@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{428}@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{429} 25923@subsection Static constant aggregates with static bounds 25924 25925 25926For the declarations: 25927 25928@example 25929type One_Dim is array (1..10) of integer; 25930ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 25931@end example 25932 25933GNAT generates no executable code: the constant ar0 is placed in static memory. 25934The same is true for constant aggregates with named associations: 25935 25936@example 25937Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); 25938Cr3 : constant One_Dim := (others => 7777); 25939@end example 25940 25941The same is true for multidimensional constant arrays such as: 25942 25943@example 25944type two_dim is array (1..3, 1..3) of integer; 25945Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 25946@end example 25947 25948The same is true for arrays of one-dimensional arrays: the following are 25949static: 25950 25951@example 25952type ar1b is array (1..3) of boolean; 25953type ar_ar is array (1..3) of ar1b; 25954None : constant ar1b := (others => false); -- fully static 25955None2 : constant ar_ar := (1..3 => None); -- fully static 25956@end example 25957 25958However, for multidimensional aggregates with named associations, GNAT will 25959generate assignments and loops, even if all associations are static. The 25960following two declarations generate a loop for the first dimension, and 25961individual component assignments for the second dimension: 25962 25963@example 25964Zero1: constant two_dim := (1..3 => (1..3 => 0)); 25965Zero2: constant two_dim := (others => (others => 0)); 25966@end example 25967 25968@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates 25969@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{42a}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{42b} 25970@subsection Constant aggregates with unconstrained nominal types 25971 25972 25973In such cases the aggregate itself establishes the subtype, so that 25974associations with @code{others} cannot be used. GNAT determines the 25975bounds for the actual subtype of the aggregate, and allocates the 25976aggregate statically as well. No code is generated for the following: 25977 25978@example 25979type One_Unc is array (natural range <>) of integer; 25980Cr_Unc : constant One_Unc := (12,24,36); 25981@end example 25982 25983@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates 25984@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{42c}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{42d} 25985@subsection Aggregates with static bounds 25986 25987 25988In all previous examples the aggregate was the initial (and immutable) value 25989of a constant. If the aggregate initializes a variable, then code is generated 25990for it as a combination of individual assignments and loops over the target 25991object. The declarations 25992 25993@example 25994Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); 25995Cr_Var2 : One_Dim := (others > -1); 25996@end example 25997 25998generate the equivalent of 25999 26000@example 26001Cr_Var1 (1) := 2; 26002Cr_Var1 (2) := 3; 26003Cr_Var1 (3) := 5; 26004Cr_Var1 (4) := 11; 26005 26006for I in Cr_Var2'range loop 26007 Cr_Var2 (I) := -1; 26008end loop; 26009@end example 26010 26011@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates 26012@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{42e}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{42f} 26013@subsection Aggregates with nonstatic bounds 26014 26015 26016If the bounds of the aggregate are not statically compatible with the bounds 26017of the nominal subtype of the target, then constraint checks have to be 26018generated on the bounds. For a multidimensional array, constraint checks may 26019have to be applied to sub-arrays individually, if they do not have statically 26020compatible subtypes. 26021 26022@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates 26023@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{430}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{431} 26024@subsection Aggregates in assignment statements 26025 26026 26027In general, aggregate assignment requires the construction of a temporary, 26028and a copy from the temporary to the target of the assignment. This is because 26029it is not always possible to convert the assignment into a series of individual 26030component assignments. For example, consider the simple case: 26031 26032@example 26033A := (A(2), A(1)); 26034@end example 26035 26036This cannot be converted into: 26037 26038@example 26039A(1) := A(2); 26040A(2) := A(1); 26041@end example 26042 26043So the aggregate has to be built first in a separate location, and then 26044copied into the target. GNAT recognizes simple cases where this intermediate 26045step is not required, and the assignments can be performed in place, directly 26046into the target. The following sufficient criteria are applied: 26047 26048 26049@itemize * 26050 26051@item 26052The bounds of the aggregate are static, and the associations are static. 26053 26054@item 26055The components of the aggregate are static constants, names of 26056simple variables that are not renamings, or expressions not involving 26057indexed components whose operands obey these rules. 26058@end itemize 26059 26060If any of these conditions are violated, the aggregate will be built in 26061a temporary (created either by the front-end or the code generator) and then 26062that temporary will be copied onto the target. 26063 26064@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 26065@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{432}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{433} 26066@section The Size of Discriminated Records with Default Discriminants 26067 26068 26069If a discriminated type @code{T} has discriminants with default values, it is 26070possible to declare an object of this type without providing an explicit 26071constraint: 26072 26073@example 26074type Size is range 1..100; 26075 26076type Rec (D : Size := 15) is record 26077 Name : String (1..D); 26078end T; 26079 26080Word : Rec; 26081@end example 26082 26083Such an object is said to be @emph{unconstrained}. 26084The discriminant of the object 26085can be modified by a full assignment to the object, as long as it preserves the 26086relation between the value of the discriminant, and the value of the components 26087that depend on it: 26088 26089@example 26090Word := (3, "yes"); 26091 26092Word := (5, "maybe"); 26093 26094Word := (5, "no"); -- raises Constraint_Error 26095@end example 26096 26097In order to support this behavior efficiently, an unconstrained object is 26098given the maximum size that any value of the type requires. In the case 26099above, @code{Word} has storage for the discriminant and for 26100a @code{String} of length 100. 26101It is important to note that unconstrained objects do not require dynamic 26102allocation. It would be an improper implementation to place on the heap those 26103components whose size depends on discriminants. (This improper implementation 26104was used by some Ada83 compilers, where the @code{Name} component above 26105would have 26106been stored as a pointer to a dynamic string). Following the principle that 26107dynamic storage management should never be introduced implicitly, 26108an Ada compiler should reserve the full size for an unconstrained declared 26109object, and place it on the stack. 26110 26111This maximum size approach 26112has been a source of surprise to some users, who expect the default 26113values of the discriminants to determine the size reserved for an 26114unconstrained object: "If the default is 15, why should the object occupy 26115a larger size?" 26116The answer, of course, is that the discriminant may be later modified, 26117and its full range of values must be taken into account. This is why the 26118declaration: 26119 26120@example 26121type Rec (D : Positive := 15) is record 26122 Name : String (1..D); 26123end record; 26124 26125Too_Large : Rec; 26126@end example 26127 26128is flagged by the compiler with a warning: 26129an attempt to create @code{Too_Large} will raise @code{Storage_Error}, 26130because the required size includes @code{Positive'Last} 26131bytes. As the first example indicates, the proper approach is to declare an 26132index type of 'reasonable' range so that unconstrained objects are not too 26133large. 26134 26135One final wrinkle: if the object is declared to be @code{aliased}, or if it is 26136created in the heap by means of an allocator, then it is @emph{not} 26137unconstrained: 26138it is constrained by the default values of the discriminants, and those values 26139cannot be modified by full assignment. This is because in the presence of 26140aliasing all views of the object (which may be manipulated by different tasks, 26141say) must be consistent, so it is imperative that the object, once created, 26142remain invariant. 26143 26144@node Strict Conformance to the Ada Reference Manual,,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features 26145@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{434}@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{435} 26146@section Strict Conformance to the Ada Reference Manual 26147 26148 26149The dynamic semantics defined by the Ada Reference Manual impose a set of 26150run-time checks to be generated. By default, the GNAT compiler will insert many 26151run-time checks into the compiled code, including most of those required by the 26152Ada Reference Manual. However, there are two checks that are not enabled in 26153the default mode for efficiency reasons: checks for access before elaboration 26154on subprogram calls, and stack overflow checking (most operating systems do not 26155perform this check by default). 26156 26157Strict conformance to the Ada Reference Manual can be achieved by adding two 26158compiler options for dynamic checks for access-before-elaboration on subprogram 26159calls and generic instantiations (@emph{-gnatE}), and stack overflow checking 26160(@emph{-fstack-check}). 26161 26162Note that the result of a floating point arithmetic operation in overflow and 26163invalid situations, when the @code{Machine_Overflows} attribute of the result 26164type is @code{False}, is to generate IEEE NaN and infinite values. This is the 26165case for machines compliant with the IEEE floating-point standard, but on 26166machines that are not fully compliant with this standard, such as Alpha, the 26167@emph{-mieee} compiler flag must be used for achieving IEEE confirming 26168behavior (although at the cost of a significant performance penalty), so 26169infinite and NaN values are properly generated. 26170 26171@node Implementation of Ada 2012 Features,Obsolescent Features,Implementation of Specific Ada Features,Top 26172@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{436}@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{437} 26173@chapter Implementation of Ada 2012 Features 26174 26175 26176@geindex Ada 2012 implementation status 26177 26178@geindex -gnat12 option (gcc) 26179 26180@geindex pragma Ada_2012 26181 26182@geindex configuration pragma Ada_2012 26183 26184@geindex Ada_2012 configuration pragma 26185 26186This chapter contains a complete list of Ada 2012 features that have been 26187implemented. 26188Generally, these features are only 26189available if the @emph{-gnat12} (Ada 2012 features enabled) option is set, 26190which is the default behavior, 26191or if the configuration pragma @code{Ada_2012} is used. 26192 26193However, new pragmas, attributes, and restrictions are 26194unconditionally available, since the Ada 95 standard allows the addition of 26195new pragmas, attributes, and restrictions (there are exceptions, which are 26196documented in the individual descriptions), and also certain packages 26197were made available in earlier versions of Ada. 26198 26199An ISO date (YYYY-MM-DD) appears in parentheses on the description line. 26200This date shows the implementation date of the feature. Any wavefront 26201subsequent to this date will contain the indicated feature, as will any 26202subsequent releases. A date of 0000-00-00 means that GNAT has always 26203implemented the feature, or implemented it as soon as it appeared as a 26204binding interpretation. 26205 26206Each feature corresponds to an Ada Issue ('AI') approved by the Ada 26207standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. 26208The features are ordered based on the relevant sections of the Ada 26209Reference Manual ("RM"). When a given AI relates to multiple points 26210in the RM, the earliest is used. 26211 26212A complete description of the AIs may be found in 26213@indicateurl{http://www.ada-auth.org/ai05-summary.html}. 26214 26215@geindex AI-0176 (Ada 2012 feature) 26216 26217 26218@itemize * 26219 26220@item 26221@emph{AI-0176 Quantified expressions (2010-09-29)} 26222 26223Both universally and existentially quantified expressions are implemented. 26224They use the new syntax for iterators proposed in AI05-139-2, as well as 26225the standard Ada loop syntax. 26226 26227RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) 26228@end itemize 26229 26230@geindex AI-0079 (Ada 2012 feature) 26231 26232 26233@itemize * 26234 26235@item 26236@emph{AI-0079 Allow other_format characters in source (2010-07-10)} 26237 26238Wide characters in the unicode category @emph{other_format} are now allowed in 26239source programs between tokens, but not within a token such as an identifier. 26240 26241RM References: 2.01 (4/2) 2.02 (7) 26242@end itemize 26243 26244@geindex AI-0091 (Ada 2012 feature) 26245 26246 26247@itemize * 26248 26249@item 26250@emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)} 26251 26252Wide characters in the unicode category @emph{other_format} are not permitted 26253within an identifier, since this can be a security problem. The error 26254message for this case has been improved to be more specific, but GNAT has 26255never allowed such characters to appear in identifiers. 26256 26257RM 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) 26258@end itemize 26259 26260@geindex AI-0100 (Ada 2012 feature) 26261 26262 26263@itemize * 26264 26265@item 26266@emph{AI-0100 Placement of pragmas (2010-07-01)} 26267 26268This AI is an earlier version of AI-163. It simplifies the rules 26269for legal placement of pragmas. In the case of lists that allow pragmas, if 26270the list may have no elements, then the list may consist solely of pragmas. 26271 26272RM References: 2.08 (7) 26273@end itemize 26274 26275@geindex AI-0163 (Ada 2012 feature) 26276 26277 26278@itemize * 26279 26280@item 26281@emph{AI-0163 Pragmas in place of null (2010-07-01)} 26282 26283A statement sequence may be composed entirely of pragmas. It is no longer 26284necessary to add a dummy @code{null} statement to make the sequence legal. 26285 26286RM References: 2.08 (7) 2.08 (16) 26287@end itemize 26288 26289@geindex AI-0080 (Ada 2012 feature) 26290 26291 26292@itemize * 26293 26294@item 26295@emph{AI-0080 'View of' not needed if clear from context (0000-00-00)} 26296 26297This is an editorial change only, described as non-testable in the AI. 26298 26299RM References: 3.01 (7) 26300@end itemize 26301 26302@geindex AI-0183 (Ada 2012 feature) 26303 26304 26305@itemize * 26306 26307@item 26308@emph{AI-0183 Aspect specifications (2010-08-16)} 26309 26310Aspect specifications have been fully implemented except for pre and post- 26311conditions, and type invariants, which have their own separate AI's. All 26312forms of declarations listed in the AI are supported. The following is a 26313list of the aspects supported (with GNAT implementation aspects marked) 26314@end itemize 26315 26316 26317@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} 26318@headitem 26319 26320Supported Aspect 26321 26322@tab 26323 26324Source 26325 26326@item 26327 26328@code{Ada_2005} 26329 26330@tab 26331 26332-- GNAT 26333 26334@item 26335 26336@code{Ada_2012} 26337 26338@tab 26339 26340-- GNAT 26341 26342@item 26343 26344@code{Address} 26345 26346@tab 26347 26348@item 26349 26350@code{Alignment} 26351 26352@tab 26353 26354@item 26355 26356@code{Atomic} 26357 26358@tab 26359 26360@item 26361 26362@code{Atomic_Components} 26363 26364@tab 26365 26366@item 26367 26368@code{Bit_Order} 26369 26370@tab 26371 26372@item 26373 26374@code{Component_Size} 26375 26376@tab 26377 26378@item 26379 26380@code{Contract_Cases} 26381 26382@tab 26383 26384-- GNAT 26385 26386@item 26387 26388@code{Discard_Names} 26389 26390@tab 26391 26392@item 26393 26394@code{External_Tag} 26395 26396@tab 26397 26398@item 26399 26400@code{Favor_Top_Level} 26401 26402@tab 26403 26404-- GNAT 26405 26406@item 26407 26408@code{Inline} 26409 26410@tab 26411 26412@item 26413 26414@code{Inline_Always} 26415 26416@tab 26417 26418-- GNAT 26419 26420@item 26421 26422@code{Invariant} 26423 26424@tab 26425 26426-- GNAT 26427 26428@item 26429 26430@code{Machine_Radix} 26431 26432@tab 26433 26434@item 26435 26436@code{No_Return} 26437 26438@tab 26439 26440@item 26441 26442@code{Object_Size} 26443 26444@tab 26445 26446-- GNAT 26447 26448@item 26449 26450@code{Pack} 26451 26452@tab 26453 26454@item 26455 26456@code{Persistent_BSS} 26457 26458@tab 26459 26460-- GNAT 26461 26462@item 26463 26464@code{Post} 26465 26466@tab 26467 26468@item 26469 26470@code{Pre} 26471 26472@tab 26473 26474@item 26475 26476@code{Predicate} 26477 26478@tab 26479 26480@item 26481 26482@code{Preelaborable_Initialization} 26483 26484@tab 26485 26486@item 26487 26488@code{Pure_Function} 26489 26490@tab 26491 26492-- GNAT 26493 26494@item 26495 26496@code{Remote_Access_Type} 26497 26498@tab 26499 26500-- GNAT 26501 26502@item 26503 26504@code{Shared} 26505 26506@tab 26507 26508-- GNAT 26509 26510@item 26511 26512@code{Size} 26513 26514@tab 26515 26516@item 26517 26518@code{Storage_Pool} 26519 26520@tab 26521 26522@item 26523 26524@code{Storage_Size} 26525 26526@tab 26527 26528@item 26529 26530@code{Stream_Size} 26531 26532@tab 26533 26534@item 26535 26536@code{Suppress} 26537 26538@tab 26539 26540@item 26541 26542@code{Suppress_Debug_Info} 26543 26544@tab 26545 26546-- GNAT 26547 26548@item 26549 26550@code{Test_Case} 26551 26552@tab 26553 26554-- GNAT 26555 26556@item 26557 26558@code{Thread_Local_Storage} 26559 26560@tab 26561 26562-- GNAT 26563 26564@item 26565 26566@code{Type_Invariant} 26567 26568@tab 26569 26570@item 26571 26572@code{Unchecked_Union} 26573 26574@tab 26575 26576@item 26577 26578@code{Universal_Aliasing} 26579 26580@tab 26581 26582-- GNAT 26583 26584@item 26585 26586@code{Unmodified} 26587 26588@tab 26589 26590-- GNAT 26591 26592@item 26593 26594@code{Unreferenced} 26595 26596@tab 26597 26598-- GNAT 26599 26600@item 26601 26602@code{Unreferenced_Objects} 26603 26604@tab 26605 26606-- GNAT 26607 26608@item 26609 26610@code{Unsuppress} 26611 26612@tab 26613 26614@item 26615 26616@code{Value_Size} 26617 26618@tab 26619 26620-- GNAT 26621 26622@item 26623 26624@code{Volatile} 26625 26626@tab 26627 26628@item 26629 26630@code{Volatile_Components} 26631 26632@tab 26633 26634@item 26635 26636@code{Warnings} 26637 26638@tab 26639 26640-- GNAT 26641 26642@end multitable 26643 26644 26645@quotation 26646 26647Note that for aspects with an expression, e.g. @code{Size}, the expression is 26648treated like a default expression (visibility is analyzed at the point of 26649occurrence of the aspect, but evaluation of the expression occurs at the 26650freeze point of the entity involved). 26651 26652RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) 266533.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 26654(2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) 266559.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) 2665612.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) 2665713.03.01 (0) 26658@end quotation 26659 26660@geindex AI-0128 (Ada 2012 feature) 26661 26662 26663@itemize * 26664 26665@item 26666@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} 26667 26668If an equality operator ("=") is declared for a type, then the implicitly 26669declared inequality operator ("/=") is a primitive operation of the type. 26670This is the only reasonable interpretation, and is the one always implemented 26671by GNAT, but the RM was not entirely clear in making this point. 26672 26673RM References: 3.02.03 (6) 6.06 (6) 26674@end itemize 26675 26676@geindex AI-0003 (Ada 2012 feature) 26677 26678 26679@itemize * 26680 26681@item 26682@emph{AI-0003 Qualified expressions as names (2010-07-11)} 26683 26684In Ada 2012, a qualified expression is considered to be syntactically a name, 26685meaning that constructs such as @code{A'(F(X)).B} are now legal. This is 26686useful in disambiguating some cases of overloading. 26687 26688RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) 266895.04 (7) 26690@end itemize 26691 26692@geindex AI-0120 (Ada 2012 feature) 26693 26694 26695@itemize * 26696 26697@item 26698@emph{AI-0120 Constant instance of protected object (0000-00-00)} 26699 26700This is an RM editorial change only. The section that lists objects that are 26701constant failed to include the current instance of a protected object 26702within a protected function. This has always been treated as a constant 26703in GNAT. 26704 26705RM References: 3.03 (21) 26706@end itemize 26707 26708@geindex AI-0008 (Ada 2012 feature) 26709 26710 26711@itemize * 26712 26713@item 26714@emph{AI-0008 General access to constrained objects (0000-00-00)} 26715 26716The wording in the RM implied that if you have a general access to a 26717constrained object, it could be used to modify the discriminants. This was 26718obviously not intended. @code{Constraint_Error} should be raised, and GNAT 26719has always done so in this situation. 26720 26721RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) 26722@end itemize 26723 26724@geindex AI-0093 (Ada 2012 feature) 26725 26726 26727@itemize * 26728 26729@item 26730@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} 26731 26732This is an editorial change only, to make more widespread use of the Ada 2012 26733'immutably limited'. 26734 26735RM References: 3.03 (23.4/3) 26736@end itemize 26737 26738@geindex AI-0096 (Ada 2012 feature) 26739 26740 26741@itemize * 26742 26743@item 26744@emph{AI-0096 Deriving from formal private types (2010-07-20)} 26745 26746In general it is illegal for a type derived from a formal limited type to be 26747nonlimited. This AI makes an exception to this rule: derivation is legal 26748if it appears in the private part of the generic, and the formal type is not 26749tagged. If the type is tagged, the legality check must be applied to the 26750private part of the package. 26751 26752RM References: 3.04 (5.1/2) 6.02 (7) 26753@end itemize 26754 26755@geindex AI-0181 (Ada 2012 feature) 26756 26757 26758@itemize * 26759 26760@item 26761@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} 26762 26763From Ada 2005 on, soft hyphen is considered a non-graphic character, which 26764means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the 26765@code{Image} and @code{Value} attributes for the character types. Strictly 26766speaking this is an inconsistency with Ada 95, but in practice the use of 26767these attributes is so obscure that it will not cause problems. 26768 26769RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) 26770@end itemize 26771 26772@geindex AI-0182 (Ada 2012 feature) 26773 26774 26775@itemize * 26776 26777@item 26778@emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)} 26779 26780This AI allows @code{Character'Value} to accept the string @code{'?'} where 26781@code{?} is any character including non-graphic control characters. GNAT has 26782always accepted such strings. It also allows strings such as 26783@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this 26784permission and raises @code{Constraint_Error}, as is certainly still 26785permitted. 26786 26787RM References: 3.05 (56/2) 26788@end itemize 26789 26790@geindex AI-0214 (Ada 2012 feature) 26791 26792 26793@itemize * 26794 26795@item 26796@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} 26797 26798Ada 2012 relaxes the restriction that forbids discriminants of tagged types 26799to have default expressions by allowing them when the type is limited. It 26800is often useful to define a default value for a discriminant even though 26801it can't be changed by assignment. 26802 26803RM References: 3.07 (9.1/2) 3.07.02 (3) 26804@end itemize 26805 26806@geindex AI-0102 (Ada 2012 feature) 26807 26808 26809@itemize * 26810 26811@item 26812@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} 26813 26814It is illegal to assign an anonymous access constant to an anonymous access 26815variable. The RM did not have a clear rule to prevent this, but GNAT has 26816always generated an error for this usage. 26817 26818RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) 26819@end itemize 26820 26821@geindex AI-0158 (Ada 2012 feature) 26822 26823 26824@itemize * 26825 26826@item 26827@emph{AI-0158 Generalizing membership tests (2010-09-16)} 26828 26829This AI extends the syntax of membership tests to simplify complex conditions 26830that can be expressed as membership in a subset of values of any type. It 26831introduces syntax for a list of expressions that may be used in loop contexts 26832as well. 26833 26834RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) 26835@end itemize 26836 26837@geindex AI-0173 (Ada 2012 feature) 26838 26839 26840@itemize * 26841 26842@item 26843@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} 26844 26845The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked 26846with the tag of an abstract type, and @code{False} otherwise. 26847 26848RM References: 3.09 (7.4/2) 3.09 (12.4/2) 26849@end itemize 26850 26851@geindex AI-0076 (Ada 2012 feature) 26852 26853 26854@itemize * 26855 26856@item 26857@emph{AI-0076 function with controlling result (0000-00-00)} 26858 26859This is an editorial change only. The RM defines calls with controlling 26860results, but uses the term 'function with controlling result' without an 26861explicit definition. 26862 26863RM References: 3.09.02 (2/2) 26864@end itemize 26865 26866@geindex AI-0126 (Ada 2012 feature) 26867 26868 26869@itemize * 26870 26871@item 26872@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} 26873 26874This AI clarifies dispatching rules, and simply confirms that dispatching 26875executes the operation of the parent type when there is no explicitly or 26876implicitly declared operation for the descendant type. This has always been 26877the case in all versions of GNAT. 26878 26879RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) 26880@end itemize 26881 26882@geindex AI-0097 (Ada 2012 feature) 26883 26884 26885@itemize * 26886 26887@item 26888@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} 26889 26890The RM as written implied that in some cases it was possible to create an 26891object of an abstract type, by having an abstract extension inherit a non- 26892abstract constructor from its parent type. This mistake has been corrected 26893in GNAT and in the RM, and this construct is now illegal. 26894 26895RM References: 3.09.03 (4/2) 26896@end itemize 26897 26898@geindex AI-0203 (Ada 2012 feature) 26899 26900 26901@itemize * 26902 26903@item 26904@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} 26905 26906A return_subtype_indication cannot denote an abstract subtype. GNAT has never 26907permitted such usage. 26908 26909RM References: 3.09.03 (8/3) 26910@end itemize 26911 26912@geindex AI-0198 (Ada 2012 feature) 26913 26914 26915@itemize * 26916 26917@item 26918@emph{AI-0198 Inheriting abstract operators (0000-00-00)} 26919 26920This AI resolves a conflict between two rules involving inherited abstract 26921operations and predefined operators. If a derived numeric type inherits 26922an abstract operator, it overrides the predefined one. This interpretation 26923was always the one implemented in GNAT. 26924 26925RM References: 3.09.03 (4/3) 26926@end itemize 26927 26928@geindex AI-0073 (Ada 2012 feature) 26929 26930 26931@itemize * 26932 26933@item 26934@emph{AI-0073 Functions returning abstract types (2010-07-10)} 26935 26936This AI covers a number of issues regarding returning abstract types. In 26937particular generic functions cannot have abstract result types or access 26938result types designated an abstract type. There are some other cases which 26939are detailed in the AI. Note that this binding interpretation has not been 26940retrofitted to operate before Ada 2012 mode, since it caused a significant 26941number of regressions. 26942 26943RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) 26944@end itemize 26945 26946@geindex AI-0070 (Ada 2012 feature) 26947 26948 26949@itemize * 26950 26951@item 26952@emph{AI-0070 Elaboration of interface types (0000-00-00)} 26953 26954This is an editorial change only, there are no testable consequences short of 26955checking for the absence of generated code for an interface declaration. 26956 26957RM References: 3.09.04 (18/2) 26958@end itemize 26959 26960@geindex AI-0208 (Ada 2012 feature) 26961 26962 26963@itemize * 26964 26965@item 26966@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} 26967 26968The wording in the Ada 2005 RM concerning characteristics of incomplete views 26969was incorrect and implied that some programs intended to be legal were now 26970illegal. GNAT had never considered such programs illegal, so it has always 26971implemented the intent of this AI. 26972 26973RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) 26974@end itemize 26975 26976@geindex AI-0162 (Ada 2012 feature) 26977 26978 26979@itemize * 26980 26981@item 26982@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} 26983 26984Incomplete types are made more useful by allowing them to be completed by 26985private types and private extensions. 26986 26987RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) 26988@end itemize 26989 26990@geindex AI-0098 (Ada 2012 feature) 26991 26992 26993@itemize * 26994 26995@item 26996@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} 26997 26998An unintentional omission in the RM implied some inconsistent restrictions on 26999the use of anonymous access to subprogram values. These restrictions were not 27000intentional, and have never been enforced by GNAT. 27001 27002RM References: 3.10.01 (6) 3.10.01 (9.2/2) 27003@end itemize 27004 27005@geindex AI-0199 (Ada 2012 feature) 27006 27007 27008@itemize * 27009 27010@item 27011@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} 27012 27013A choice list in a record aggregate can include several components of 27014(distinct) anonymous access types as long as they have matching designated 27015subtypes. 27016 27017RM References: 4.03.01 (16) 27018@end itemize 27019 27020@geindex AI-0220 (Ada 2012 feature) 27021 27022 27023@itemize * 27024 27025@item 27026@emph{AI-0220 Needed components for aggregates (0000-00-00)} 27027 27028This AI addresses a wording problem in the RM that appears to permit some 27029complex cases of aggregates with nonstatic discriminants. GNAT has always 27030implemented the intended semantics. 27031 27032RM References: 4.03.01 (17) 27033@end itemize 27034 27035@geindex AI-0147 (Ada 2012 feature) 27036 27037 27038@itemize * 27039 27040@item 27041@emph{AI-0147 Conditional expressions (2009-03-29)} 27042 27043Conditional expressions are permitted. The form of such an expression is: 27044 27045@example 27046(if expr then expr @{elsif expr then expr@} [else expr]) 27047@end example 27048 27049The parentheses can be omitted in contexts where parentheses are present 27050anyway, such as subprogram arguments and pragma arguments. If the @strong{else} 27051clause is omitted, @strong{else} @emph{True} is assumed; 27052thus @code{(if A then B)} is a way to conveniently represent 27053@emph{(A implies B)} in standard logic. 27054 27055RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) 270564.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) 27057@end itemize 27058 27059@geindex AI-0037 (Ada 2012 feature) 27060 27061 27062@itemize * 27063 27064@item 27065@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} 27066 27067This AI confirms that an association of the form @code{Indx => <>} in an 27068array aggregate must raise @code{Constraint_Error} if @code{Indx} 27069is out of range. The RM specified a range check on other associations, but 27070not when the value of the association was defaulted. GNAT has always inserted 27071a constraint check on the index value. 27072 27073RM References: 4.03.03 (29) 27074@end itemize 27075 27076@geindex AI-0123 (Ada 2012 feature) 27077 27078 27079@itemize * 27080 27081@item 27082@emph{AI-0123 Composability of equality (2010-04-13)} 27083 27084Equality of untagged record composes, so that the predefined equality for a 27085composite type that includes a component of some untagged record type 27086@code{R} uses the equality operation of @code{R} (which may be user-defined 27087or predefined). This makes the behavior of untagged records identical to that 27088of tagged types in this respect. 27089 27090This change is an incompatibility with previous versions of Ada, but it 27091corrects a non-uniformity that was often a source of confusion. Analysis of 27092a large number of industrial programs indicates that in those rare cases 27093where a composite type had an untagged record component with a user-defined 27094equality, either there was no use of the composite equality, or else the code 27095expected the same composability as for tagged types, and thus had a bug that 27096would be fixed by this change. 27097 27098RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) 270998.05.04 (8) 27100@end itemize 27101 27102@geindex AI-0088 (Ada 2012 feature) 27103 27104 27105@itemize * 27106 27107@item 27108@emph{AI-0088 The value of exponentiation (0000-00-00)} 27109 27110This AI clarifies the equivalence rule given for the dynamic semantics of 27111exponentiation: the value of the operation can be obtained by repeated 27112multiplication, but the operation can be implemented otherwise (for example 27113using the familiar divide-by-two-and-square algorithm, even if this is less 27114accurate), and does not imply repeated reads of a volatile base. 27115 27116RM References: 4.05.06 (11) 27117@end itemize 27118 27119@geindex AI-0188 (Ada 2012 feature) 27120 27121 27122@itemize * 27123 27124@item 27125@emph{AI-0188 Case expressions (2010-01-09)} 27126 27127Case expressions are permitted. This allows use of constructs such as: 27128 27129@example 27130X := (case Y is when 1 => 2, when 2 => 3, when others => 31) 27131@end example 27132 27133RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) 27134@end itemize 27135 27136@geindex AI-0104 (Ada 2012 feature) 27137 27138 27139@itemize * 27140 27141@item 27142@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} 27143 27144The assignment @code{Ptr := new not null Some_Ptr;} will raise 27145@code{Constraint_Error} because the default value of the allocated object is 27146@strong{null}. This useless construct is illegal in Ada 2012. 27147 27148RM References: 4.08 (2) 27149@end itemize 27150 27151@geindex AI-0157 (Ada 2012 feature) 27152 27153 27154@itemize * 27155 27156@item 27157@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} 27158 27159Allocation and Deallocation from an empty storage pool (i.e. allocation or 27160deallocation of a pointer for which a static storage size clause of zero 27161has been given) is now illegal and is detected as such. GNAT 27162previously gave a warning but not an error. 27163 27164RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) 27165@end itemize 27166 27167@geindex AI-0179 (Ada 2012 feature) 27168 27169 27170@itemize * 27171 27172@item 27173@emph{AI-0179 Statement not required after label (2010-04-10)} 27174 27175It is not necessary to have a statement following a label, so a label 27176can appear at the end of a statement sequence without the need for putting a 27177null statement afterwards, but it is not allowable to have only labels and 27178no real statements in a statement sequence. 27179 27180RM References: 5.01 (2) 27181@end itemize 27182 27183@geindex AI-0139-2 (Ada 2012 feature) 27184 27185 27186@itemize * 27187 27188@item 27189@emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)} 27190 27191The new syntax for iterating over arrays and containers is now implemented. 27192Iteration over containers is for now limited to read-only iterators. Only 27193default iterators are supported, with the syntax: @code{for Elem of C}. 27194 27195RM References: 5.05 27196@end itemize 27197 27198@geindex AI-0134 (Ada 2012 feature) 27199 27200 27201@itemize * 27202 27203@item 27204@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} 27205 27206For full conformance, the profiles of anonymous-access-to-subprogram 27207parameters must match. GNAT has always enforced this rule. 27208 27209RM References: 6.03.01 (18) 27210@end itemize 27211 27212@geindex AI-0207 (Ada 2012 feature) 27213 27214 27215@itemize * 27216 27217@item 27218@emph{AI-0207 Mode conformance and access constant (0000-00-00)} 27219 27220This AI confirms that access_to_constant indication must match for mode 27221conformance. This was implemented in GNAT when the qualifier was originally 27222introduced in Ada 2005. 27223 27224RM References: 6.03.01 (16/2) 27225@end itemize 27226 27227@geindex AI-0046 (Ada 2012 feature) 27228 27229 27230@itemize * 27231 27232@item 27233@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} 27234 27235For full conformance, in the case of access parameters, the null exclusion 27236must match (either both or neither must have @code{not null}). 27237 27238RM References: 6.03.02 (18) 27239@end itemize 27240 27241@geindex AI-0118 (Ada 2012 feature) 27242 27243 27244@itemize * 27245 27246@item 27247@emph{AI-0118 The association of parameter associations (0000-00-00)} 27248 27249This AI clarifies the rules for named associations in subprogram calls and 27250generic instantiations. The rules have been in place since Ada 83. 27251 27252RM References: 6.04.01 (2) 12.03 (9) 27253@end itemize 27254 27255@geindex AI-0196 (Ada 2012 feature) 27256 27257 27258@itemize * 27259 27260@item 27261@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} 27262 27263Null exclusion checks are not made for @code{out} parameters when 27264evaluating the actual parameters. GNAT has never generated these checks. 27265 27266RM References: 6.04.01 (13) 27267@end itemize 27268 27269@geindex AI-0015 (Ada 2012 feature) 27270 27271 27272@itemize * 27273 27274@item 27275@emph{AI-0015 Constant return objects (0000-00-00)} 27276 27277The return object declared in an @emph{extended_return_statement} may be 27278declared constant. This was always intended, and GNAT has always allowed it. 27279 27280RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) 272816.05 (5.7/2) 27282@end itemize 27283 27284@geindex AI-0032 (Ada 2012 feature) 27285 27286 27287@itemize * 27288 27289@item 27290@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} 27291 27292If a function returns a class-wide type, the object of an extended return 27293statement can be declared with a specific type that is covered by the class- 27294wide type. This has been implemented in GNAT since the introduction of 27295extended returns. Note AI-0103 complements this AI by imposing matching 27296rules for constrained return types. 27297 27298RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) 272996.05 (8/2) 27300@end itemize 27301 27302@geindex AI-0103 (Ada 2012 feature) 27303 27304 27305@itemize * 27306 27307@item 27308@emph{AI-0103 Static matching for extended return (2010-07-23)} 27309 27310If the return subtype of a function is an elementary type or a constrained 27311type, the subtype indication in an extended return statement must match 27312statically this return subtype. 27313 27314RM References: 6.05 (5.2/2) 27315@end itemize 27316 27317@geindex AI-0058 (Ada 2012 feature) 27318 27319 27320@itemize * 27321 27322@item 27323@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} 27324 27325The RM had some incorrect wording implying wrong treatment of abnormal 27326completion in an extended return. GNAT has always implemented the intended 27327correct semantics as described by this AI. 27328 27329RM References: 6.05 (22/2) 27330@end itemize 27331 27332@geindex AI-0050 (Ada 2012 feature) 27333 27334 27335@itemize * 27336 27337@item 27338@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} 27339 27340The implementation permissions for raising @code{Constraint_Error} early on a function call 27341when it was clear an exception would be raised were over-permissive and allowed 27342mishandling of discriminants in some cases. GNAT did 27343not take advantage of these incorrect permissions in any case. 27344 27345RM References: 6.05 (24/2) 27346@end itemize 27347 27348@geindex AI-0125 (Ada 2012 feature) 27349 27350 27351@itemize * 27352 27353@item 27354@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} 27355 27356In Ada 2012, the declaration of a primitive operation of a type extension 27357or private extension can also override an inherited primitive that is not 27358visible at the point of this declaration. 27359 27360RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) 27361@end itemize 27362 27363@geindex AI-0062 (Ada 2012 feature) 27364 27365 27366@itemize * 27367 27368@item 27369@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} 27370 27371A full constant may have a null exclusion even if its associated deferred 27372constant does not. GNAT has always allowed this. 27373 27374RM References: 7.04 (6/2) 7.04 (7.1/2) 27375@end itemize 27376 27377@geindex AI-0178 (Ada 2012 feature) 27378 27379 27380@itemize * 27381 27382@item 27383@emph{AI-0178 Incomplete views are limited (0000-00-00)} 27384 27385This AI clarifies the role of incomplete views and plugs an omission in the 27386RM. GNAT always correctly restricted the use of incomplete views and types. 27387 27388RM References: 7.05 (3/2) 7.05 (6/2) 27389@end itemize 27390 27391@geindex AI-0087 (Ada 2012 feature) 27392 27393 27394@itemize * 27395 27396@item 27397@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} 27398 27399The actual for a formal nonlimited derived type cannot be limited. In 27400particular, a formal derived type that extends a limited interface but which 27401is not explicitly limited cannot be instantiated with a limited type. 27402 27403RM References: 7.05 (5/2) 12.05.01 (5.1/2) 27404@end itemize 27405 27406@geindex AI-0099 (Ada 2012 feature) 27407 27408 27409@itemize * 27410 27411@item 27412@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} 27413 27414This AI clarifies that 'needs finalization' is part of dynamic semantics, 27415and therefore depends on the run-time characteristics of an object (i.e. its 27416tag) and not on its nominal type. As the AI indicates: "we do not expect 27417this to affect any implementation'@w{'}. 27418 27419RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) 27420@end itemize 27421 27422@geindex AI-0064 (Ada 2012 feature) 27423 27424 27425@itemize * 27426 27427@item 27428@emph{AI-0064 Redundant finalization rule (0000-00-00)} 27429 27430This is an editorial change only. The intended behavior is already checked 27431by an existing ACATS test, which GNAT has always executed correctly. 27432 27433RM References: 7.06.01 (17.1/1) 27434@end itemize 27435 27436@geindex AI-0026 (Ada 2012 feature) 27437 27438 27439@itemize * 27440 27441@item 27442@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} 27443 27444Record representation clauses concerning Unchecked_Union types cannot mention 27445the discriminant of the type. The type of a component declared in the variant 27446part of an Unchecked_Union cannot be controlled, have controlled components, 27447nor have protected or task parts. If an Unchecked_Union type is declared 27448within the body of a generic unit or its descendants, then the type of a 27449component declared in the variant part cannot be a formal private type or a 27450formal private extension declared within the same generic unit. 27451 27452RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) 27453@end itemize 27454 27455@geindex AI-0205 (Ada 2012 feature) 27456 27457 27458@itemize * 27459 27460@item 27461@emph{AI-0205 Extended return declares visible name (0000-00-00)} 27462 27463This AI corrects a simple omission in the RM. Return objects have always 27464been visible within an extended return statement. 27465 27466RM References: 8.03 (17) 27467@end itemize 27468 27469@geindex AI-0042 (Ada 2012 feature) 27470 27471 27472@itemize * 27473 27474@item 27475@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} 27476 27477This AI fixes a wording gap in the RM. An operation of a synchronized 27478interface can be implemented by a protected or task entry, but the abstract 27479operation is not being overridden in the usual sense, and it must be stated 27480separately that this implementation is legal. This has always been the case 27481in GNAT. 27482 27483RM References: 9.01 (9.2/2) 9.04 (11.1/2) 27484@end itemize 27485 27486@geindex AI-0030 (Ada 2012 feature) 27487 27488 27489@itemize * 27490 27491@item 27492@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} 27493 27494Requeue is permitted to a protected, synchronized or task interface primitive 27495providing it is known that the overriding operation is an entry. Otherwise 27496the requeue statement has the same effect as a procedure call. Use of pragma 27497@code{Implemented} provides a way to impose a static requirement on the 27498overriding operation by adhering to one of the implementation kinds: entry, 27499protected procedure or any of the above. 27500 27501RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) 275029.05.04 (6) 9.05.04 (7) 9.05.04 (12) 27503@end itemize 27504 27505@geindex AI-0201 (Ada 2012 feature) 27506 27507 27508@itemize * 27509 27510@item 27511@emph{AI-0201 Independence of atomic object components (2010-07-22)} 27512 27513If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} 27514attribute, then individual components may not be addressable by independent 27515tasks. However, if the representation clause has no effect (is confirming), 27516then independence is not compromised. Furthermore, in GNAT, specification of 27517other appropriately addressable component sizes (e.g. 16 for 8-bit 27518characters) also preserves independence. GNAT now gives very clear warnings 27519both for the declaration of such a type, and for any assignment to its components. 27520 27521RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) 27522@end itemize 27523 27524@geindex AI-0009 (Ada 2012 feature) 27525 27526 27527@itemize * 27528 27529@item 27530@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} 27531 27532This AI introduces the new pragmas @code{Independent} and 27533@code{Independent_Components}, 27534which control guaranteeing independence of access to objects and components. 27535The AI also requires independence not unaffected by confirming rep clauses. 27536 27537RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) 27538C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) 27539@end itemize 27540 27541@geindex AI-0072 (Ada 2012 feature) 27542 27543 27544@itemize * 27545 27546@item 27547@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)} 27548 27549This AI clarifies that task signalling for reading @code{'Terminated} only 27550occurs if the result is True. GNAT semantics has always been consistent with 27551this notion of task signalling. 27552 27553RM References: 9.10 (6.1/1) 27554@end itemize 27555 27556@geindex AI-0108 (Ada 2012 feature) 27557 27558 27559@itemize * 27560 27561@item 27562@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} 27563 27564This AI confirms that an incomplete type from a limited view does not have 27565discriminants. This has always been the case in GNAT. 27566 27567RM References: 10.01.01 (12.3/2) 27568@end itemize 27569 27570@geindex AI-0129 (Ada 2012 feature) 27571 27572 27573@itemize * 27574 27575@item 27576@emph{AI-0129 Limited views and incomplete types (0000-00-00)} 27577 27578This AI clarifies the description of limited views: a limited view of a 27579package includes only one view of a type that has an incomplete declaration 27580and a full declaration (there is no possible ambiguity in a client package). 27581This AI also fixes an omission: a nested package in the private part has no 27582limited view. GNAT always implemented this correctly. 27583 27584RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) 27585@end itemize 27586 27587@geindex AI-0077 (Ada 2012 feature) 27588 27589 27590@itemize * 27591 27592@item 27593@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} 27594 27595This AI clarifies that a declaration does not include a context clause, 27596and confirms that it is illegal to have a context in which both a limited 27597and a nonlimited view of a package are accessible. Such double visibility 27598was always rejected by GNAT. 27599 27600RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) 27601@end itemize 27602 27603@geindex AI-0122 (Ada 2012 feature) 27604 27605 27606@itemize * 27607 27608@item 27609@emph{AI-0122 Private with and children of generics (0000-00-00)} 27610 27611This AI clarifies the visibility of private children of generic units within 27612instantiations of a parent. GNAT has always handled this correctly. 27613 27614RM References: 10.01.02 (12/2) 27615@end itemize 27616 27617@geindex AI-0040 (Ada 2012 feature) 27618 27619 27620@itemize * 27621 27622@item 27623@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} 27624 27625This AI confirms that a limited with clause in a child unit cannot name 27626an ancestor of the unit. This has always been checked in GNAT. 27627 27628RM References: 10.01.02 (20/2) 27629@end itemize 27630 27631@geindex AI-0132 (Ada 2012 feature) 27632 27633 27634@itemize * 27635 27636@item 27637@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} 27638 27639This AI fills a gap in the description of library unit pragmas. The pragma 27640clearly must apply to a library unit, even if it does not carry the name 27641of the enclosing unit. GNAT has always enforced the required check. 27642 27643RM References: 10.01.05 (7) 27644@end itemize 27645 27646@geindex AI-0034 (Ada 2012 feature) 27647 27648 27649@itemize * 27650 27651@item 27652@emph{AI-0034 Categorization of limited views (0000-00-00)} 27653 27654The RM makes certain limited with clauses illegal because of categorization 27655considerations, when the corresponding normal with would be legal. This is 27656not intended, and GNAT has always implemented the recommended behavior. 27657 27658RM References: 10.02.01 (11/1) 10.02.01 (17/2) 27659@end itemize 27660 27661@geindex AI-0035 (Ada 2012 feature) 27662 27663 27664@itemize * 27665 27666@item 27667@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} 27668 27669This AI remedies some inconsistencies in the legality rules for Pure units. 27670Derived access types are legal in a pure unit (on the assumption that the 27671rule for a zero storage pool size has been enforced on the ancestor type). 27672The rules are enforced in generic instances and in subunits. GNAT has always 27673implemented the recommended behavior. 27674 27675RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) 27676@end itemize 27677 27678@geindex AI-0219 (Ada 2012 feature) 27679 27680 27681@itemize * 27682 27683@item 27684@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} 27685 27686This AI refines the rules for the cases with limited parameters which do not 27687allow the implementations to omit 'redundant'. GNAT now properly conforms 27688to the requirements of this binding interpretation. 27689 27690RM References: 10.02.01 (18/2) 27691@end itemize 27692 27693@geindex AI-0043 (Ada 2012 feature) 27694 27695 27696@itemize * 27697 27698@item 27699@emph{AI-0043 Rules about raising exceptions (0000-00-00)} 27700 27701This AI covers various omissions in the RM regarding the raising of 27702exceptions. GNAT has always implemented the intended semantics. 27703 27704RM References: 11.04.01 (10.1/2) 11 (2) 27705@end itemize 27706 27707@geindex AI-0200 (Ada 2012 feature) 27708 27709 27710@itemize * 27711 27712@item 27713@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} 27714 27715This AI plugs a gap in the RM which appeared to allow some obviously intended 27716illegal instantiations. GNAT has never allowed these instantiations. 27717 27718RM References: 12.07 (16) 27719@end itemize 27720 27721@geindex AI-0112 (Ada 2012 feature) 27722 27723 27724@itemize * 27725 27726@item 27727@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} 27728 27729This AI concerns giving names to various representation aspects, but the 27730practical effect is simply to make the use of duplicate 27731@code{Atomic[_Components]}, 27732@code{Volatile[_Components]}, and 27733@code{Independent[_Components]} pragmas illegal, and GNAT 27734now performs this required check. 27735 27736RM References: 13.01 (8) 27737@end itemize 27738 27739@geindex AI-0106 (Ada 2012 feature) 27740 27741 27742@itemize * 27743 27744@item 27745@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} 27746 27747The RM appeared to allow representation pragmas on generic formal parameters, 27748but this was not intended, and GNAT has never permitted this usage. 27749 27750RM References: 13.01 (9.1/1) 27751@end itemize 27752 27753@geindex AI-0012 (Ada 2012 feature) 27754 27755 27756@itemize * 27757 27758@item 27759@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} 27760 27761It is now illegal to give an inappropriate component size or a pragma 27762@code{Pack} that attempts to change the component size in the case of atomic 27763or aliased components. Previously GNAT ignored such an attempt with a 27764warning. 27765 27766RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) 27767@end itemize 27768 27769@geindex AI-0039 (Ada 2012 feature) 27770 27771 27772@itemize * 27773 27774@item 27775@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} 27776 27777The RM permitted the use of dynamic expressions (such as @code{ptr.all})` 27778for stream attributes, but these were never useful and are now illegal. GNAT 27779has always regarded such expressions as illegal. 27780 27781RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) 27782@end itemize 27783 27784@geindex AI-0095 (Ada 2012 feature) 27785 27786 27787@itemize * 27788 27789@item 27790@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} 27791 27792The prefix of @code{'Address} cannot statically denote a subprogram with 27793convention @code{Intrinsic}. The use of the @code{Address} attribute raises 27794@code{Program_Error} if the prefix denotes a subprogram with convention 27795@code{Intrinsic}. 27796 27797RM References: 13.03 (11/1) 27798@end itemize 27799 27800@geindex AI-0116 (Ada 2012 feature) 27801 27802 27803@itemize * 27804 27805@item 27806@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} 27807 27808This AI requires that the alignment of a class-wide object be no greater 27809than the alignment of any type in the class. GNAT has always followed this 27810recommendation. 27811 27812RM References: 13.03 (29) 13.11 (16) 27813@end itemize 27814 27815@geindex AI-0146 (Ada 2012 feature) 27816 27817 27818@itemize * 27819 27820@item 27821@emph{AI-0146 Type invariants (2009-09-21)} 27822 27823Type invariants may be specified for private types using the aspect notation. 27824Aspect @code{Type_Invariant} may be specified for any private type, 27825@code{Type_Invariant'Class} can 27826only be specified for tagged types, and is inherited by any descendent of the 27827tagged types. The invariant is a boolean expression that is tested for being 27828true in the following situations: conversions to the private type, object 27829declarations for the private type that are default initialized, and 27830[@strong{in}] @strong{out} 27831parameters and returned result on return from any primitive operation for 27832the type that is visible to a client. 27833GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and 27834@code{Invariant'Class} for @code{Type_Invariant'Class}. 27835 27836RM References: 13.03.03 (00) 27837@end itemize 27838 27839@geindex AI-0078 (Ada 2012 feature) 27840 27841 27842@itemize * 27843 27844@item 27845@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} 27846 27847In Ada 2012, compilers are required to support unchecked conversion where the 27848target alignment is a multiple of the source alignment. GNAT always supported 27849this case (and indeed all cases of differing alignments, doing copies where 27850required if the alignment was reduced). 27851 27852RM References: 13.09 (7) 27853@end itemize 27854 27855@geindex AI-0195 (Ada 2012 feature) 27856 27857 27858@itemize * 27859 27860@item 27861@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} 27862 27863The handling of invalid values is now designated to be implementation 27864defined. This is a documentation change only, requiring Annex M in the GNAT 27865Reference Manual to document this handling. 27866In GNAT, checks for invalid values are made 27867only when necessary to avoid erroneous behavior. Operations like assignments 27868which cannot cause erroneous behavior ignore the possibility of invalid 27869values and do not do a check. The date given above applies only to the 27870documentation change, this behavior has always been implemented by GNAT. 27871 27872RM References: 13.09.01 (10) 27873@end itemize 27874 27875@geindex AI-0193 (Ada 2012 feature) 27876 27877 27878@itemize * 27879 27880@item 27881@emph{AI-0193 Alignment of allocators (2010-09-16)} 27882 27883This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, 27884analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead 27885of size. 27886 27887RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) 2788813.11.01 (2) 13.11.01 (3) 27889@end itemize 27890 27891@geindex AI-0177 (Ada 2012 feature) 27892 27893 27894@itemize * 27895 27896@item 27897@emph{AI-0177 Parameterized expressions (2010-07-10)} 27898 27899The new Ada 2012 notion of parameterized expressions is implemented. The form 27900is: 27901 27902@example 27903function-specification is (expression) 27904@end example 27905 27906This is exactly equivalent to the 27907corresponding function body that returns the expression, but it can appear 27908in a package spec. Note that the expression must be parenthesized. 27909 27910RM References: 13.11.01 (3/2) 27911@end itemize 27912 27913@geindex AI-0033 (Ada 2012 feature) 27914 27915 27916@itemize * 27917 27918@item 27919@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} 27920 27921Neither of these two pragmas may appear within a generic template, because 27922the generic might be instantiated at other than the library level. 27923 27924RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) 27925@end itemize 27926 27927@geindex AI-0161 (Ada 2012 feature) 27928 27929 27930@itemize * 27931 27932@item 27933@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} 27934 27935A new restriction @code{No_Default_Stream_Attributes} prevents the use of any 27936of the default stream attributes for elementary types. If this restriction is 27937in force, then it is necessary to provide explicit subprograms for any 27938stream attributes used. 27939 27940RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) 27941@end itemize 27942 27943@geindex AI-0194 (Ada 2012 feature) 27944 27945 27946@itemize * 27947 27948@item 27949@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} 27950 27951The @code{Stream_Size} attribute returns the default number of bits in the 27952stream representation of the given type. 27953This value is not affected by the presence 27954of stream subprogram attributes for the type. GNAT has always implemented 27955this interpretation. 27956 27957RM References: 13.13.02 (1.2/2) 27958@end itemize 27959 27960@geindex AI-0109 (Ada 2012 feature) 27961 27962 27963@itemize * 27964 27965@item 27966@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)} 27967 27968This AI is an editorial change only. It removes the need for a tag check 27969that can never fail. 27970 27971RM References: 13.13.02 (34/2) 27972@end itemize 27973 27974@geindex AI-0007 (Ada 2012 feature) 27975 27976 27977@itemize * 27978 27979@item 27980@emph{AI-0007 Stream read and private scalar types (0000-00-00)} 27981 27982The RM as written appeared to limit the possibilities of declaring read 27983attribute procedures for private scalar types. This limitation was not 27984intended, and has never been enforced by GNAT. 27985 27986RM References: 13.13.02 (50/2) 13.13.02 (51/2) 27987@end itemize 27988 27989@geindex AI-0065 (Ada 2012 feature) 27990 27991 27992@itemize * 27993 27994@item 27995@emph{AI-0065 Remote access types and external streaming (0000-00-00)} 27996 27997This AI clarifies the fact that all remote access types support external 27998streaming. This fixes an obvious oversight in the definition of the 27999language, and GNAT always implemented the intended correct rules. 28000 28001RM References: 13.13.02 (52/2) 28002@end itemize 28003 28004@geindex AI-0019 (Ada 2012 feature) 28005 28006 28007@itemize * 28008 28009@item 28010@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} 28011 28012The RM suggests that primitive subprograms of a specific tagged type are 28013frozen when the tagged type is frozen. This would be an incompatible change 28014and is not intended. GNAT has never attempted this kind of freezing and its 28015behavior is consistent with the recommendation of this AI. 28016 28017RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) 28018@end itemize 28019 28020@geindex AI-0017 (Ada 2012 feature) 28021 28022 28023@itemize * 28024 28025@item 28026@emph{AI-0017 Freezing and incomplete types (0000-00-00)} 28027 28028So-called 'Taft-amendment types' (i.e., types that are completed in package 28029bodies) are not frozen by the occurrence of bodies in the 28030enclosing declarative part. GNAT always implemented this properly. 28031 28032RM References: 13.14 (3/1) 28033@end itemize 28034 28035@geindex AI-0060 (Ada 2012 feature) 28036 28037 28038@itemize * 28039 28040@item 28041@emph{AI-0060 Extended definition of remote access types (0000-00-00)} 28042 28043This AI extends the definition of remote access types to include access 28044to limited, synchronized, protected or task class-wide interface types. 28045GNAT already implemented this extension. 28046 28047RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) 28048@end itemize 28049 28050@geindex AI-0114 (Ada 2012 feature) 28051 28052 28053@itemize * 28054 28055@item 28056@emph{AI-0114 Classification of letters (0000-00-00)} 28057 28058The code points 170 (@code{FEMININE ORDINAL INDICATOR}), 28059181 (@code{MICRO SIGN}), and 28060186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered 28061lower case letters by Unicode. 28062However, they are not allowed in identifiers, and they 28063return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. 28064This behavior is consistent with that defined in Ada 95. 28065 28066RM References: A.03.02 (59) A.04.06 (7) 28067@end itemize 28068 28069@geindex AI-0185 (Ada 2012 feature) 28070 28071 28072@itemize * 28073 28074@item 28075@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} 28076 28077Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide 28078classification functions for @code{Wide_Character} and 28079@code{Wide_Wide_Character}, as well as providing 28080case folding routines for @code{Wide_[Wide_]Character} and 28081@code{Wide_[Wide_]String}. 28082 28083RM References: A.03.05 (0) A.03.06 (0) 28084@end itemize 28085 28086@geindex AI-0031 (Ada 2012 feature) 28087 28088 28089@itemize * 28090 28091@item 28092@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} 28093 28094A new version of @code{Find_Token} is added to all relevant string packages, 28095with an extra parameter @code{From}. Instead of starting at the first 28096character of the string, the search for a matching Token starts at the 28097character indexed by the value of @code{From}. 28098These procedures are available in all versions of Ada 28099but if used in versions earlier than Ada 2012 they will generate a warning 28100that an Ada 2012 subprogram is being used. 28101 28102RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) 28103A.04.05 (46) 28104@end itemize 28105 28106@geindex AI-0056 (Ada 2012 feature) 28107 28108 28109@itemize * 28110 28111@item 28112@emph{AI-0056 Index on null string returns zero (0000-00-00)} 28113 28114The wording in the Ada 2005 RM implied an incompatible handling of the 28115@code{Index} functions, resulting in raising an exception instead of 28116returning zero in some situations. 28117This was not intended and has been corrected. 28118GNAT always returned zero, and is thus consistent with this AI. 28119 28120RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) 28121@end itemize 28122 28123@geindex AI-0137 (Ada 2012 feature) 28124 28125 28126@itemize * 28127 28128@item 28129@emph{AI-0137 String encoding package (2010-03-25)} 28130 28131The packages @code{Ada.Strings.UTF_Encoding}, together with its child 28132packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, 28133and @code{Wide_Wide_Strings} have been 28134implemented. These packages (whose documentation can be found in the spec 28135files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, 28136@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of 28137@code{String}, @code{Wide_String}, and @code{Wide_Wide_String} 28138values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and 28139UTF-16), as well as conversions between the different UTF encodings. With 28140the exception of @code{Wide_Wide_Strings}, these packages are available in 28141Ada 95 and Ada 2005 mode as well as Ada 2012 mode. 28142The @code{Wide_Wide_Strings} package 28143is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 28144mode since it uses @code{Wide_Wide_Character}). 28145 28146RM References: A.04.11 28147@end itemize 28148 28149@geindex AI-0038 (Ada 2012 feature) 28150 28151 28152@itemize * 28153 28154@item 28155@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} 28156 28157These are minor errors in the description on three points. The intent on 28158all these points has always been clear, and GNAT has always implemented the 28159correct intended semantics. 28160 28161RM 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) 28162@end itemize 28163 28164@geindex AI-0044 (Ada 2012 feature) 28165 28166 28167@itemize * 28168 28169@item 28170@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} 28171 28172This AI places restrictions on allowed instantiations of generic containers. 28173These restrictions are not checked by the compiler, so there is nothing to 28174change in the implementation. This affects only the RM documentation. 28175 28176RM 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) 28177@end itemize 28178 28179@geindex AI-0127 (Ada 2012 feature) 28180 28181 28182@itemize * 28183 28184@item 28185@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} 28186 28187This package provides an interface for identifying the current locale. 28188 28189RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 28190A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 28191@end itemize 28192 28193@geindex AI-0002 (Ada 2012 feature) 28194 28195 28196@itemize * 28197 28198@item 28199@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} 28200 28201The compiler is not required to support exporting an Ada subprogram with 28202convention C if there are parameters or a return type of an unconstrained 28203array type (such as @code{String}). GNAT allows such declarations but 28204generates warnings. It is possible, but complicated, to write the 28205corresponding C code and certainly such code would be specific to GNAT and 28206non-portable. 28207 28208RM References: B.01 (17) B.03 (62) B.03 (71.1/2) 28209@end itemize 28210 28211@geindex AI05-0216 (Ada 2012 feature) 28212 28213 28214@itemize * 28215 28216@item 28217@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} 28218 28219It is clearly the intention that @code{No_Task_Hierarchy} is intended to 28220forbid tasks declared locally within subprograms, or functions returning task 28221objects, and that is the implementation that GNAT has always provided. 28222However the language in the RM was not sufficiently clear on this point. 28223Thus this is a documentation change in the RM only. 28224 28225RM References: D.07 (3/3) 28226@end itemize 28227 28228@geindex AI-0211 (Ada 2012 feature) 28229 28230 28231@itemize * 28232 28233@item 28234@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} 28235 28236The restriction @code{No_Relative_Delays} forbids any calls to the subprogram 28237@code{Ada.Real_Time.Timing_Events.Set_Handler}. 28238 28239RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) 28240@end itemize 28241 28242@geindex AI-0190 (Ada 2012 feature) 28243 28244 28245@itemize * 28246 28247@item 28248@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} 28249 28250This AI introduces a new pragma @code{Default_Storage_Pool}, which can be 28251used to control storage pools globally. 28252In particular, you can force every access 28253type that is used for allocation (@strong{new}) to have an explicit storage pool, 28254or you can declare a pool globally to be used for all access types that lack 28255an explicit one. 28256 28257RM References: D.07 (8) 28258@end itemize 28259 28260@geindex AI-0189 (Ada 2012 feature) 28261 28262 28263@itemize * 28264 28265@item 28266@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} 28267 28268This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, 28269which says that no dynamic allocation will occur once elaboration is 28270completed. 28271In general this requires a run-time check, which is not required, and which 28272GNAT does not attempt. But the static cases of allocators in a task body or 28273in the body of the main program are detected and flagged at compile or bind 28274time. 28275 28276RM References: D.07 (19.1/2) H.04 (23.3/2) 28277@end itemize 28278 28279@geindex AI-0171 (Ada 2012 feature) 28280 28281 28282@itemize * 28283 28284@item 28285@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} 28286 28287A new package @code{System.Multiprocessors} is added, together with the 28288definition of pragma @code{CPU} for controlling task affinity. A new no 28289dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, 28290is added to the Ravenscar profile. 28291 28292RM References: D.13.01 (4/2) D.16 28293@end itemize 28294 28295@geindex AI-0210 (Ada 2012 feature) 28296 28297 28298@itemize * 28299 28300@item 28301@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} 28302 28303This is a documentation only issue regarding wording of metric requirements, 28304that does not affect the implementation of the compiler. 28305 28306RM References: D.15 (24/2) 28307@end itemize 28308 28309@geindex AI-0206 (Ada 2012 feature) 28310 28311 28312@itemize * 28313 28314@item 28315@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} 28316 28317Remote types packages are now allowed to depend on preelaborated packages. 28318This was formerly considered illegal. 28319 28320RM References: E.02.02 (6) 28321@end itemize 28322 28323@geindex AI-0152 (Ada 2012 feature) 28324 28325 28326@itemize * 28327 28328@item 28329@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} 28330 28331Restriction @code{No_Anonymous_Allocators} prevents the use of allocators 28332where the type of the returned value is an anonymous access type. 28333 28334RM References: H.04 (8/1) 28335@end itemize 28336 28337@node Obsolescent Features,Compatibility and Porting Guide,Implementation of Ada 2012 Features,Top 28338@anchor{gnat_rm/obsolescent_features id1}@anchor{438}@anchor{gnat_rm/obsolescent_features doc}@anchor{439}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{15} 28339@chapter Obsolescent Features 28340 28341 28342This chapter describes features that are provided by GNAT, but are 28343considered obsolescent since there are preferred ways of achieving 28344the same effect. These features are provided solely for historical 28345compatibility purposes. 28346 28347@menu 28348* pragma No_Run_Time:: 28349* pragma Ravenscar:: 28350* pragma Restricted_Run_Time:: 28351* pragma Task_Info:: 28352* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. 28353 28354@end menu 28355 28356@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features 28357@anchor{gnat_rm/obsolescent_features id2}@anchor{43a}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{43b} 28358@section pragma No_Run_Time 28359 28360 28361The pragma @code{No_Run_Time} is used to achieve an affect similar 28362to the use of the "Zero Foot Print" configurable run time, but without 28363requiring a specially configured run time. The result of using this 28364pragma, which must be used for all units in a partition, is to restrict 28365the use of any language features requiring run-time support code. The 28366preferred usage is to use an appropriately configured run-time that 28367includes just those features that are to be made accessible. 28368 28369@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features 28370@anchor{gnat_rm/obsolescent_features id3}@anchor{43c}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{43d} 28371@section pragma Ravenscar 28372 28373 28374The pragma @code{Ravenscar} has exactly the same effect as pragma 28375@code{Profile (Ravenscar)}. The latter usage is preferred since it 28376is part of the new Ada 2005 standard. 28377 28378@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features 28379@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{43e}@anchor{gnat_rm/obsolescent_features id4}@anchor{43f} 28380@section pragma Restricted_Run_Time 28381 28382 28383The pragma @code{Restricted_Run_Time} has exactly the same effect as 28384pragma @code{Profile (Restricted)}. The latter usage is 28385preferred since the Ada 2005 pragma @code{Profile} is intended for 28386this kind of implementation dependent addition. 28387 28388@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features 28389@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{440}@anchor{gnat_rm/obsolescent_features id5}@anchor{441} 28390@section pragma Task_Info 28391 28392 28393The functionality provided by pragma @code{Task_Info} is now part of the 28394Ada language. The @code{CPU} aspect and the package 28395@code{System.Multiprocessors} offer a less system-dependent way to specify 28396task affinity or to query the number of processors. 28397 28398Syntax 28399 28400@example 28401pragma Task_Info (EXPRESSION); 28402@end example 28403 28404This pragma appears within a task definition (like pragma 28405@code{Priority}) and applies to the task in which it appears. The 28406argument must be of type @code{System.Task_Info.Task_Info_Type}. 28407The @code{Task_Info} pragma provides system dependent control over 28408aspects of tasking implementation, for example, the ability to map 28409tasks to specific processors. For details on the facilities available 28410for the version of GNAT that you are using, see the documentation 28411in the spec of package System.Task_Info in the runtime 28412library. 28413 28414@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features 28415@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{442}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{443} 28416@section package System.Task_Info (@code{s-tasinf.ads}) 28417 28418 28419This package provides target dependent functionality that is used 28420to support the @code{Task_Info} pragma. The predefined Ada package 28421@code{System.Multiprocessors} and the @code{CPU} aspect now provide a 28422standard replacement for GNAT's @code{Task_Info} functionality. 28423 28424@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top 28425@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{16}@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{444}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{445} 28426@chapter Compatibility and Porting Guide 28427 28428 28429This chapter presents some guidelines for developing portable Ada code, 28430describes the compatibility issues that may arise between 28431GNAT and other Ada compilation systems (including those for Ada 83), 28432and shows how GNAT can expedite porting 28433applications developed in other Ada environments. 28434 28435@menu 28436* Writing Portable Fixed-Point Declarations:: 28437* Compatibility with Ada 83:: 28438* Compatibility between Ada 95 and Ada 2005:: 28439* Implementation-dependent characteristics:: 28440* Compatibility with Other Ada Systems:: 28441* Representation Clauses:: 28442* Compatibility with HP Ada 83:: 28443 28444@end menu 28445 28446@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide 28447@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{446}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{447} 28448@section Writing Portable Fixed-Point Declarations 28449 28450 28451The Ada Reference Manual gives an implementation freedom to choose bounds 28452that are narrower by @code{Small} from the given bounds. 28453For example, if we write 28454 28455@example 28456type F1 is delta 1.0 range -128.0 .. +128.0; 28457@end example 28458 28459then the implementation is allowed to choose -128.0 .. +127.0 if it 28460likes, but is not required to do so. 28461 28462This leads to possible portability problems, so let's have a closer 28463look at this, and figure out how to avoid these problems. 28464 28465First, why does this freedom exist, and why would an implementation 28466take advantage of it? To answer this, take a closer look at the type 28467declaration for @code{F1} above. If the compiler uses the given bounds, 28468it would need 9 bits to hold the largest positive value (and typically 28469that means 16 bits on all machines). But if the implementation chooses 28470the +127.0 bound then it can fit values of the type in 8 bits. 28471 28472Why not make the user write +127.0 if that's what is wanted? 28473The rationale is that if you are thinking of fixed point 28474as a kind of 'poor man's floating-point', then you don't want 28475to be thinking about the scaled integers that are used in its 28476representation. Let's take another example: 28477 28478@example 28479type F2 is delta 2.0**(-15) range -1.0 .. +1.0; 28480@end example 28481 28482Looking at this declaration, it seems casually as though 28483it should fit in 16 bits, but again that extra positive value 28484+1.0 has the scaled integer equivalent of 2**15 which is one too 28485big for signed 16 bits. The implementation can treat this as: 28486 28487@example 28488type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); 28489@end example 28490 28491and the Ada language design team felt that this was too annoying 28492to require. We don't need to debate this decision at this point, 28493since it is well established (the rule about narrowing the ranges 28494dates to Ada 83). 28495 28496But the important point is that an implementation is not required 28497to do this narrowing, so we have a potential portability problem. 28498We could imagine three types of implementation: 28499 28500 28501@enumerate a 28502 28503@item 28504those that narrow the range automatically if they can figure 28505out that the narrower range will allow storage in a smaller machine unit, 28506 28507@item 28508those that will narrow only if forced to by a @code{'Size} clause, and 28509 28510@item 28511those that will never narrow. 28512@end enumerate 28513 28514Now if we are language theoreticians, we can imagine a fourth 28515approach: to narrow all the time, e.g. to treat 28516 28517@example 28518type F3 is delta 1.0 range -10.0 .. +23.0; 28519@end example 28520 28521as though it had been written: 28522 28523@example 28524type F3 is delta 1.0 range -9.0 .. +22.0; 28525@end example 28526 28527But although technically allowed, such a behavior would be hostile and silly, 28528and no real compiler would do this. All real compilers will fall into one of 28529the categories (a), (b) or (c) above. 28530 28531So, how do you get the compiler to do what you want? The answer is give the 28532actual bounds you want, and then use a @code{'Small} clause and a 28533@code{'Size} clause to absolutely pin down what the compiler does. 28534E.g., for @code{F2} above, we will write: 28535 28536@example 28537My_Small : constant := 2.0**(-15); 28538My_First : constant := -1.0; 28539My_Last : constant := +1.0 - My_Small; 28540 28541type F2 is delta My_Small range My_First .. My_Last; 28542@end example 28543 28544and then add 28545 28546@example 28547for F2'Small use my_Small; 28548for F2'Size use 16; 28549@end example 28550 28551In practice all compilers will do the same thing here and will give you 28552what you want, so the above declarations are fully portable. If you really 28553want to play language lawyer and guard against ludicrous behavior by the 28554compiler you could add 28555 28556@example 28557Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); 28558Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); 28559@end example 28560 28561One or other or both are allowed to be illegal if the compiler is 28562behaving in a silly manner, but at least the silly compiler will not 28563get away with silently messing with your (very clear) intentions. 28564 28565If you follow this scheme you will be guaranteed that your fixed-point 28566types will be portable. 28567 28568@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide 28569@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{448}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{449} 28570@section Compatibility with Ada 83 28571 28572 28573@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) 28574 28575Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 28576are highly upwards compatible with Ada 83. In 28577particular, the design intention was that the difficulties associated 28578with moving from Ada 83 to later versions of the standard should be no greater 28579than those that occur when moving from one Ada 83 system to another. 28580 28581However, there are a number of points at which there are minor 28582incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains 28583full details of these issues as they relate to Ada 95, 28584and should be consulted for a complete treatment. 28585In practice the 28586following subsections treat the most likely issues to be encountered. 28587 28588@menu 28589* Legal Ada 83 programs that are illegal in Ada 95:: 28590* More deterministic semantics:: 28591* Changed semantics:: 28592* Other language compatibility issues:: 28593 28594@end menu 28595 28596@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 28597@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{44a}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{44b} 28598@subsection Legal Ada 83 programs that are illegal in Ada 95 28599 28600 28601Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in 28602Ada 95 and later versions of the standard: 28603 28604 28605@itemize * 28606 28607@item 28608@emph{Character literals} 28609 28610Some uses of character literals are ambiguous. Since Ada 95 has introduced 28611@code{Wide_Character} as a new predefined character type, some uses of 28612character literals that were legal in Ada 83 are illegal in Ada 95. 28613For example: 28614 28615@example 28616for Char in 'A' .. 'Z' loop ... end loop; 28617@end example 28618 28619The problem is that 'A' and 'Z' could be from either 28620@code{Character} or @code{Wide_Character}. The simplest correction 28621is to make the type explicit; e.g.: 28622 28623@example 28624for Char in Character range 'A' .. 'Z' loop ... end loop; 28625@end example 28626 28627@item 28628@emph{New reserved words} 28629 28630The identifiers @code{abstract}, @code{aliased}, @code{protected}, 28631@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. 28632Existing Ada 83 code using any of these identifiers must be edited to 28633use some alternative name. 28634 28635@item 28636@emph{Freezing rules} 28637 28638The rules in Ada 95 are slightly different with regard to the point at 28639which entities are frozen, and representation pragmas and clauses are 28640not permitted past the freeze point. This shows up most typically in 28641the form of an error message complaining that a representation item 28642appears too late, and the appropriate corrective action is to move 28643the item nearer to the declaration of the entity to which it refers. 28644 28645A particular case is that representation pragmas 28646cannot be applied to a subprogram body. If necessary, a separate subprogram 28647declaration must be introduced to which the pragma can be applied. 28648 28649@item 28650@emph{Optional bodies for library packages} 28651 28652In Ada 83, a package that did not require a package body was nevertheless 28653allowed to have one. This lead to certain surprises in compiling large 28654systems (situations in which the body could be unexpectedly ignored by the 28655binder). In Ada 95, if a package does not require a body then it is not 28656permitted to have a body. To fix this problem, simply remove a redundant 28657body if it is empty, or, if it is non-empty, introduce a dummy declaration 28658into the spec that makes the body required. One approach is to add a private 28659part to the package declaration (if necessary), and define a parameterless 28660procedure called @code{Requires_Body}, which must then be given a dummy 28661procedure body in the package body, which then becomes required. 28662Another approach (assuming that this does not introduce elaboration 28663circularities) is to add an @code{Elaborate_Body} pragma to the package spec, 28664since one effect of this pragma is to require the presence of a package body. 28665 28666@item 28667@emph{Numeric_Error is the same exception as Constraint_Error} 28668 28669In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. 28670This means that it is illegal to have separate exception handlers for 28671the two exceptions. The fix is simply to remove the handler for the 28672@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise 28673@code{Constraint_Error} in place of @code{Numeric_Error} in all cases). 28674 28675@item 28676@emph{Indefinite subtypes in generics} 28677 28678In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) 28679as the actual for a generic formal private type, but then the instantiation 28680would be illegal if there were any instances of declarations of variables 28681of this type in the generic body. In Ada 95, to avoid this clear violation 28682of the methodological principle known as the 'contract model', 28683the generic declaration explicitly indicates whether 28684or not such instantiations are permitted. If a generic formal parameter 28685has explicit unknown discriminants, indicated by using @code{(<>)} after the 28686subtype name, then it can be instantiated with indefinite types, but no 28687stand-alone variables can be declared of this type. Any attempt to declare 28688such a variable will result in an illegality at the time the generic is 28689declared. If the @code{(<>)} notation is not used, then it is illegal 28690to instantiate the generic with an indefinite type. 28691This is the potential incompatibility issue when porting Ada 83 code to Ada 95. 28692It will show up as a compile time error, and 28693the fix is usually simply to add the @code{(<>)} to the generic declaration. 28694@end itemize 28695 28696@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 28697@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{44c}@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{44d} 28698@subsection More deterministic semantics 28699 28700 28701 28702@itemize * 28703 28704@item 28705@emph{Conversions} 28706 28707Conversions from real types to integer types round away from 0. In Ada 83 28708the conversion Integer(2.5) could deliver either 2 or 3 as its value. This 28709implementation freedom was intended to support unbiased rounding in 28710statistical applications, but in practice it interfered with portability. 28711In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 28712is required. Numeric code may be affected by this change in semantics. 28713Note, though, that this issue is no worse than already existed in Ada 83 28714when porting code from one vendor to another. 28715 28716@item 28717@emph{Tasking} 28718 28719The Real-Time Annex introduces a set of policies that define the behavior of 28720features that were implementation dependent in Ada 83, such as the order in 28721which open select branches are executed. 28722@end itemize 28723 28724@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 28725@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{44f} 28726@subsection Changed semantics 28727 28728 28729The worst kind of incompatibility is one where a program that is legal in 28730Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not 28731possible in Ada 83. Fortunately this is extremely rare, but the one 28732situation that you should be alert to is the change in the predefined type 28733@code{Character} from 7-bit ASCII to 8-bit Latin-1. 28734 28735@quotation 28736 28737@geindex Latin-1 28738@end quotation 28739 28740 28741@itemize * 28742 28743@item 28744@emph{Range of type `@w{`}Character`@w{`}} 28745 28746The range of @code{Standard.Character} is now the full 256 characters 28747of Latin-1, whereas in most Ada 83 implementations it was restricted 28748to 128 characters. Although some of the effects of 28749this change will be manifest in compile-time rejection of legal 28750Ada 83 programs it is possible for a working Ada 83 program to have 28751a different effect in Ada 95, one that was not permitted in Ada 83. 28752As an example, the expression 28753@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now 28754delivers @code{255} as its value. 28755In general, you should look at the logic of any 28756character-processing Ada 83 program and see whether it needs to be adapted 28757to work correctly with Latin-1. Note that the predefined Ada 95 API has a 28758character handling package that may be relevant if code needs to be adapted 28759to account for the additional Latin-1 elements. 28760The desirable fix is to 28761modify the program to accommodate the full character set, but in some cases 28762it may be convenient to define a subtype or derived type of Character that 28763covers only the restricted range. 28764@end itemize 28765 28766@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 28767@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{451} 28768@subsection Other language compatibility issues 28769 28770 28771 28772@itemize * 28773 28774@item 28775@emph{-gnat83} switch 28776 28777All implementations of GNAT provide a switch that causes GNAT to operate 28778in Ada 83 mode. In this mode, some but not all compatibility problems 28779of the type described above are handled automatically. For example, the 28780new reserved words introduced in Ada 95 and Ada 2005 are treated simply 28781as identifiers as in Ada 83. However, 28782in practice, it is usually advisable to make the necessary modifications 28783to the program to remove the need for using this switch. 28784See the @code{Compiling Different Versions of Ada} section in 28785the @cite{GNAT User's Guide}. 28786 28787@item 28788Support for removed Ada 83 pragmas and attributes 28789 28790A number of pragmas and attributes from Ada 83 were removed from Ada 95, 28791generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 28792compilers are allowed, but not required, to implement these missing 28793elements. In contrast with some other compilers, GNAT implements all 28794such pragmas and attributes, eliminating this compatibility concern. These 28795include @code{pragma Interface} and the floating point type attributes 28796(@code{Emax}, @code{Mantissa}, etc.), among other items. 28797@end itemize 28798 28799@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide 28800@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{452}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{453} 28801@section Compatibility between Ada 95 and Ada 2005 28802 28803 28804@geindex Compatibility between Ada 95 and Ada 2005 28805 28806Although Ada 2005 was designed to be upwards compatible with Ada 95, there are 28807a number of incompatibilities. Several are enumerated below; 28808for a complete description please see the 28809@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in 28810@cite{Rationale for Ada 2005}. 28811 28812 28813@itemize * 28814 28815@item 28816@emph{New reserved words.} 28817 28818The words @code{interface}, @code{overriding} and @code{synchronized} are 28819reserved in Ada 2005. 28820A pre-Ada 2005 program that uses any of these as an identifier will be 28821illegal. 28822 28823@item 28824@emph{New declarations in predefined packages.} 28825 28826A number of packages in the predefined environment contain new declarations: 28827@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, 28828@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, 28829@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, 28830@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, 28831@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. 28832If an Ada 95 program does a @code{with} and @code{use} of any of these 28833packages, the new declarations may cause name clashes. 28834 28835@item 28836@emph{Access parameters.} 28837 28838A nondispatching subprogram with an access parameter cannot be renamed 28839as a dispatching operation. This was permitted in Ada 95. 28840 28841@item 28842@emph{Access types, discriminants, and constraints.} 28843 28844Rule changes in this area have led to some incompatibilities; for example, 28845constrained subtypes of some access types are not permitted in Ada 2005. 28846 28847@item 28848@emph{Aggregates for limited types.} 28849 28850The allowance of aggregates for limited types in Ada 2005 raises the 28851possibility of ambiguities in legal Ada 95 programs, since additional types 28852now need to be considered in expression resolution. 28853 28854@item 28855@emph{Fixed-point multiplication and division.} 28856 28857Certain expressions involving '*' or '/' for a fixed-point type, which 28858were legal in Ada 95 and invoked the predefined versions of these operations, 28859are now ambiguous. 28860The ambiguity may be resolved either by applying a type conversion to the 28861expression, or by explicitly invoking the operation from package 28862@code{Standard}. 28863 28864@item 28865@emph{Return-by-reference types.} 28866 28867The Ada 95 return-by-reference mechanism has been removed. Instead, the user 28868can declare a function returning a value from an anonymous access type. 28869@end itemize 28870 28871@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide 28872@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{455} 28873@section Implementation-dependent characteristics 28874 28875 28876Although the Ada language defines the semantics of each construct as 28877precisely as practical, in some situations (for example for reasons of 28878efficiency, or where the effect is heavily dependent on the host or target 28879platform) the implementation is allowed some freedom. In porting Ada 83 28880code to GNAT, you need to be aware of whether / how the existing code 28881exercised such implementation dependencies. Such characteristics fall into 28882several categories, and GNAT offers specific support in assisting the 28883transition from certain Ada 83 compilers. 28884 28885@menu 28886* Implementation-defined pragmas:: 28887* Implementation-defined attributes:: 28888* Libraries:: 28889* Elaboration order:: 28890* Target-specific aspects:: 28891 28892@end menu 28893 28894@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics 28895@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{457} 28896@subsection Implementation-defined pragmas 28897 28898 28899Ada compilers are allowed to supplement the language-defined pragmas, and 28900these are a potential source of non-portability. All GNAT-defined pragmas 28901are described in @ref{7,,Implementation Defined Pragmas}, 28902and these include several that are specifically 28903intended to correspond to other vendors' Ada 83 pragmas. 28904For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. 28905For compatibility with HP Ada 83, GNAT supplies the pragmas 28906@code{Extend_System}, @code{Ident}, @code{Inline_Generic}, 28907@code{Interface_Name}, @code{Passive}, @code{Suppress_All}, 28908and @code{Volatile}. 28909Other relevant pragmas include @code{External} and @code{Link_With}. 28910Some vendor-specific 28911Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are 28912recognized, thus 28913avoiding compiler rejection of units that contain such pragmas; they are not 28914relevant in a GNAT context and hence are not otherwise implemented. 28915 28916@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics 28917@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{459} 28918@subsection Implementation-defined attributes 28919 28920 28921Analogous to pragmas, the set of attributes may be extended by an 28922implementation. All GNAT-defined attributes are described in 28923@ref{8,,Implementation Defined Attributes}, 28924and these include several that are specifically intended 28925to correspond to other vendors' Ada 83 attributes. For migrating from VADS, 28926the attribute @code{VADS_Size} may be useful. For compatibility with HP 28927Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and 28928@code{Type_Class}. 28929 28930@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics 28931@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{45a}@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{45b} 28932@subsection Libraries 28933 28934 28935Vendors may supply libraries to supplement the standard Ada API. If Ada 83 28936code uses vendor-specific libraries then there are several ways to manage 28937this in Ada 95 and later versions of the standard: 28938 28939 28940@itemize * 28941 28942@item 28943If the source code for the libraries (specs and bodies) are 28944available, then the libraries can be migrated in the same way as the 28945application. 28946 28947@item 28948If the source code for the specs but not the bodies are 28949available, then you can reimplement the bodies. 28950 28951@item 28952Some features introduced by Ada 95 obviate the need for library support. For 28953example most Ada 83 vendors supplied a package for unsigned integers. The 28954Ada 95 modular type feature is the preferred way to handle this need, so 28955instead of migrating or reimplementing the unsigned integer package it may 28956be preferable to retrofit the application using modular types. 28957@end itemize 28958 28959@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics 28960@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{45c}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{45d} 28961@subsection Elaboration order 28962 28963 28964The implementation can choose any elaboration order consistent with the unit 28965dependency relationship. This freedom means that some orders can result in 28966Program_Error being raised due to an 'Access Before Elaboration': an attempt 28967to invoke a subprogram before its body has been elaborated, or to instantiate 28968a generic before the generic body has been elaborated. By default GNAT 28969attempts to choose a safe order (one that will not encounter access before 28970elaboration problems) by implicitly inserting @code{Elaborate} or 28971@code{Elaborate_All} pragmas where 28972needed. However, this can lead to the creation of elaboration circularities 28973and a resulting rejection of the program by gnatbind. This issue is 28974thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix 28975in the @cite{GNAT User's Guide}. 28976In brief, there are several 28977ways to deal with this situation: 28978 28979 28980@itemize * 28981 28982@item 28983Modify the program to eliminate the circularities, e.g., by moving 28984elaboration-time code into explicitly-invoked procedures 28985 28986@item 28987Constrain the elaboration order by including explicit @code{Elaborate_Body} or 28988@code{Elaborate} pragmas, and then inhibit the generation of implicit 28989@code{Elaborate_All} 28990pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally 28991(by selectively suppressing elaboration checks via pragma 28992@code{Suppress(Elaboration_Check)} when it is safe to do so). 28993@end itemize 28994 28995@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics 28996@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{45e}@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{45f} 28997@subsection Target-specific aspects 28998 28999 29000Low-level applications need to deal with machine addresses, data 29001representations, interfacing with assembler code, and similar issues. If 29002such an Ada 83 application is being ported to different target hardware (for 29003example where the byte endianness has changed) then you will need to 29004carefully examine the program logic; the porting effort will heavily depend 29005on the robustness of the original design. Moreover, Ada 95 (and thus 29006Ada 2005 and Ada 2012) are sometimes 29007incompatible with typical Ada 83 compiler practices regarding implicit 29008packing, the meaning of the Size attribute, and the size of access values. 29009GNAT's approach to these issues is described in @ref{460,,Representation Clauses}. 29010 29011@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide 29012@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{461}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{462} 29013@section Compatibility with Other Ada Systems 29014 29015 29016If programs avoid the use of implementation dependent and 29017implementation defined features, as documented in the 29018@cite{Ada Reference Manual}, there should be a high degree of portability between 29019GNAT and other Ada systems. The following are specific items which 29020have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 29021compilers, but do not affect porting code to GNAT. 29022(As of January 2007, GNAT is the only compiler available for Ada 2005; 29023the following issues may or may not arise for Ada 2005 programs 29024when other compilers appear.) 29025 29026 29027@itemize * 29028 29029@item 29030@emph{Ada 83 Pragmas and Attributes} 29031 29032Ada 95 compilers are allowed, but not required, to implement the missing 29033Ada 83 pragmas and attributes that are no longer defined in Ada 95. 29034GNAT implements all such pragmas and attributes, eliminating this as 29035a compatibility concern, but some other Ada 95 compilers reject these 29036pragmas and attributes. 29037 29038@item 29039@emph{Specialized Needs Annexes} 29040 29041GNAT implements the full set of special needs annexes. At the 29042current time, it is the only Ada 95 compiler to do so. This means that 29043programs making use of these features may not be portable to other Ada 2904495 compilation systems. 29045 29046@item 29047@emph{Representation Clauses} 29048 29049Some other Ada 95 compilers implement only the minimal set of 29050representation clauses required by the Ada 95 reference manual. GNAT goes 29051far beyond this minimal set, as described in the next section. 29052@end itemize 29053 29054@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide 29055@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{460}@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{463} 29056@section Representation Clauses 29057 29058 29059The Ada 83 reference manual was quite vague in describing both the minimal 29060required implementation of representation clauses, and also their precise 29061effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the 29062minimal set of capabilities required is still quite limited. 29063 29064GNAT implements the full required set of capabilities in 29065Ada 95 and Ada 2005, but also goes much further, and in particular 29066an effort has been made to be compatible with existing Ada 83 usage to the 29067greatest extent possible. 29068 29069A few cases exist in which Ada 83 compiler behavior is incompatible with 29070the requirements in Ada 95 (and thus also Ada 2005). These are instances of 29071intentional or accidental dependence on specific implementation dependent 29072characteristics of these Ada 83 compilers. The following is a list of 29073the cases most likely to arise in existing Ada 83 code. 29074 29075 29076@itemize * 29077 29078@item 29079@emph{Implicit Packing} 29080 29081Some Ada 83 compilers allowed a Size specification to cause implicit 29082packing of an array or record. This could cause expensive implicit 29083conversions for change of representation in the presence of derived 29084types, and the Ada design intends to avoid this possibility. 29085Subsequent AI's were issued to make it clear that such implicit 29086change of representation in response to a Size clause is inadvisable, 29087and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) 29088Reference Manuals as implementation advice that is followed by GNAT. 29089The problem will show up as an error 29090message rejecting the size clause. The fix is simply to provide 29091the explicit pragma @code{Pack}, or for more fine tuned control, provide 29092a Component_Size clause. 29093 29094@item 29095@emph{Meaning of Size Attribute} 29096 29097The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as 29098the minimal number of bits required to hold values of the type. For example, 29099on a 32-bit machine, the size of @code{Natural} will typically be 31 and not 2910032 (since no sign bit is required). Some Ada 83 compilers gave 31, and 29101some 32 in this situation. This problem will usually show up as a compile 29102time error, but not always. It is a good idea to check all uses of the 29103'Size attribute when porting Ada 83 code. The GNAT specific attribute 29104Object_Size can provide a useful way of duplicating the behavior of 29105some Ada 83 compiler systems. 29106 29107@item 29108@emph{Size of Access Types} 29109 29110A common assumption in Ada 83 code is that an access type is in fact a pointer, 29111and that therefore it will be the same size as a System.Address value. This 29112assumption is true for GNAT in most cases with one exception. For the case of 29113a pointer to an unconstrained array type (where the bounds may vary from one 29114value of the access type to another), the default is to use a 'fat pointer', 29115which is represented as two separate pointers, one to the bounds, and one to 29116the array. This representation has a number of advantages, including improved 29117efficiency. However, it may cause some difficulties in porting existing Ada 83 29118code which makes the assumption that, for example, pointers fit in 32 bits on 29119a machine with 32-bit addressing. 29120 29121To get around this problem, GNAT also permits the use of 'thin pointers' for 29122access types in this case (where the designated type is an unconstrained array 29123type). These thin pointers are indeed the same size as a System.Address value. 29124To specify a thin pointer, use a size clause for the type, for example: 29125 29126@example 29127type X is access all String; 29128for X'Size use Standard'Address_Size; 29129@end example 29130 29131which will cause the type X to be represented using a single pointer. 29132When using this representation, the bounds are right behind the array. 29133This representation is slightly less efficient, and does not allow quite 29134such flexibility in the use of foreign pointers or in using the 29135Unrestricted_Access attribute to create pointers to non-aliased objects. 29136But for any standard portable use of the access type it will work in 29137a functionally correct manner and allow porting of existing code. 29138Note that another way of forcing a thin pointer representation 29139is to use a component size clause for the element size in an array, 29140or a record representation clause for an access field in a record. 29141 29142See the documentation of Unrestricted_Access in the GNAT RM for a 29143full discussion of possible problems using this attribute in conjunction 29144with thin pointers. 29145@end itemize 29146 29147@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide 29148@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{464}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{465} 29149@section Compatibility with HP Ada 83 29150 29151 29152All the HP Ada 83 pragmas and attributes are recognized, although only a subset 29153of them can sensibly be implemented. The description of pragmas in 29154@ref{7,,Implementation Defined Pragmas} indicates whether or not they are 29155applicable to GNAT. 29156 29157 29158@itemize * 29159 29160@item 29161@emph{Default floating-point representation} 29162 29163In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, 29164it is VMS format. 29165 29166@item 29167@emph{System} 29168 29169the package System in GNAT exactly corresponds to the definition in the 29170Ada 95 reference manual, which means that it excludes many of the 29171HP Ada 83 extensions. However, a separate package Aux_DEC is provided 29172that contains the additional definitions, and a special pragma, 29173Extend_System allows this package to be treated transparently as an 29174extension of package System. 29175@end itemize 29176 29177@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top 29178@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{466}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{467} 29179@chapter GNU Free Documentation License 29180 29181 29182Version 1.3, 3 November 2008 29183 29184Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc 29185@indicateurl{http://fsf.org/} 29186 29187Everyone is permitted to copy and distribute verbatim copies of this 29188license document, but changing it is not allowed. 29189 29190@strong{Preamble} 29191 29192The purpose of this License is to make a manual, textbook, or other 29193functional and useful document "free" in the sense of freedom: to 29194assure everyone the effective freedom to copy and redistribute it, 29195with or without modifying it, either commercially or noncommercially. 29196Secondarily, this License preserves for the author and publisher a way 29197to get credit for their work, while not being considered responsible 29198for modifications made by others. 29199 29200This License is a kind of "copyleft", which means that derivative 29201works of the document must themselves be free in the same sense. It 29202complements the GNU General Public License, which is a copyleft 29203license designed for free software. 29204 29205We have designed this License in order to use it for manuals for free 29206software, because free software needs free documentation: a free 29207program should come with manuals providing the same freedoms that the 29208software does. But this License is not limited to software manuals; 29209it can be used for any textual work, regardless of subject matter or 29210whether it is published as a printed book. We recommend this License 29211principally for works whose purpose is instruction or reference. 29212 29213@strong{1. APPLICABILITY AND DEFINITIONS} 29214 29215This License applies to any manual or other work, in any medium, that 29216contains a notice placed by the copyright holder saying it can be 29217distributed under the terms of this License. Such a notice grants a 29218world-wide, royalty-free license, unlimited in duration, to use that 29219work under the conditions stated herein. The @strong{Document}, below, 29220refers to any such manual or work. Any member of the public is a 29221licensee, and is addressed as "@strong{you}". You accept the license if you 29222copy, modify or distribute the work in a way requiring permission 29223under copyright law. 29224 29225A "@strong{Modified Version}" of the Document means any work containing the 29226Document or a portion of it, either copied verbatim, or with 29227modifications and/or translated into another language. 29228 29229A "@strong{Secondary Section}" is a named appendix or a front-matter section of 29230the Document that deals exclusively with the relationship of the 29231publishers or authors of the Document to the Document's overall subject 29232(or to related matters) and contains nothing that could fall directly 29233within that overall subject. (Thus, if the Document is in part a 29234textbook of mathematics, a Secondary Section may not explain any 29235mathematics.) The relationship could be a matter of historical 29236connection with the subject or with related matters, or of legal, 29237commercial, philosophical, ethical or political position regarding 29238them. 29239 29240The "@strong{Invariant Sections}" are certain Secondary Sections whose titles 29241are designated, as being those of Invariant Sections, in the notice 29242that says that the Document is released under this License. If a 29243section does not fit the above definition of Secondary then it is not 29244allowed to be designated as Invariant. The Document may contain zero 29245Invariant Sections. If the Document does not identify any Invariant 29246Sections then there are none. 29247 29248The "@strong{Cover Texts}" are certain short passages of text that are listed, 29249as Front-Cover Texts or Back-Cover Texts, in the notice that says that 29250the Document is released under this License. A Front-Cover Text may 29251be at most 5 words, and a Back-Cover Text may be at most 25 words. 29252 29253A "@strong{Transparent}" copy of the Document means a machine-readable copy, 29254represented in a format whose specification is available to the 29255general public, that is suitable for revising the document 29256straightforwardly with generic text editors or (for images composed of 29257pixels) generic paint programs or (for drawings) some widely available 29258drawing editor, and that is suitable for input to text formatters or 29259for automatic translation to a variety of formats suitable for input 29260to text formatters. A copy made in an otherwise Transparent file 29261format whose markup, or absence of markup, has been arranged to thwart 29262or discourage subsequent modification by readers is not Transparent. 29263An image format is not Transparent if used for any substantial amount 29264of text. A copy that is not "Transparent" is called @strong{Opaque}. 29265 29266Examples of suitable formats for Transparent copies include plain 29267ASCII without markup, Texinfo input format, LaTeX input format, SGML 29268or XML using a publicly available DTD, and standard-conforming simple 29269HTML, PostScript or PDF designed for human modification. Examples of 29270transparent image formats include PNG, XCF and JPG. Opaque formats 29271include proprietary formats that can be read and edited only by 29272proprietary word processors, SGML or XML for which the DTD and/or 29273processing tools are not generally available, and the 29274machine-generated HTML, PostScript or PDF produced by some word 29275processors for output purposes only. 29276 29277The "@strong{Title Page}" means, for a printed book, the title page itself, 29278plus such following pages as are needed to hold, legibly, the material 29279this License requires to appear in the title page. For works in 29280formats which do not have any title page as such, "Title Page" means 29281the text near the most prominent appearance of the work's title, 29282preceding the beginning of the body of the text. 29283 29284The "@strong{publisher}" means any person or entity that distributes 29285copies of the Document to the public. 29286 29287A section "@strong{Entitled XYZ}" means a named subunit of the Document whose 29288title either is precisely XYZ or contains XYZ in parentheses following 29289text that translates XYZ in another language. (Here XYZ stands for a 29290specific section name mentioned below, such as "@strong{Acknowledgements}", 29291"@strong{Dedications}", "@strong{Endorsements}", or "@strong{History}".) 29292To "@strong{Preserve the Title}" 29293of such a section when you modify the Document means that it remains a 29294section "Entitled XYZ" according to this definition. 29295 29296The Document may include Warranty Disclaimers next to the notice which 29297states that this License applies to the Document. These Warranty 29298Disclaimers are considered to be included by reference in this 29299License, but only as regards disclaiming warranties: any other 29300implication that these Warranty Disclaimers may have is void and has 29301no effect on the meaning of this License. 29302 29303@strong{2. VERBATIM COPYING} 29304 29305You may copy and distribute the Document in any medium, either 29306commercially or noncommercially, provided that this License, the 29307copyright notices, and the license notice saying this License applies 29308to the Document are reproduced in all copies, and that you add no other 29309conditions whatsoever to those of this License. You may not use 29310technical measures to obstruct or control the reading or further 29311copying of the copies you make or distribute. However, you may accept 29312compensation in exchange for copies. If you distribute a large enough 29313number of copies you must also follow the conditions in section 3. 29314 29315You may also lend copies, under the same conditions stated above, and 29316you may publicly display copies. 29317 29318@strong{3. COPYING IN QUANTITY} 29319 29320If you publish printed copies (or copies in media that commonly have 29321printed covers) of the Document, numbering more than 100, and the 29322Document's license notice requires Cover Texts, you must enclose the 29323copies in covers that carry, clearly and legibly, all these Cover 29324Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on 29325the back cover. Both covers must also clearly and legibly identify 29326you as the publisher of these copies. The front cover must present 29327the full title with all words of the title equally prominent and 29328visible. You may add other material on the covers in addition. 29329Copying with changes limited to the covers, as long as they preserve 29330the title of the Document and satisfy these conditions, can be treated 29331as verbatim copying in other respects. 29332 29333If the required texts for either cover are too voluminous to fit 29334legibly, you should put the first ones listed (as many as fit 29335reasonably) on the actual cover, and continue the rest onto adjacent 29336pages. 29337 29338If you publish or distribute Opaque copies of the Document numbering 29339more than 100, you must either include a machine-readable Transparent 29340copy along with each Opaque copy, or state in or with each Opaque copy 29341a computer-network location from which the general network-using 29342public has access to download using public-standard network protocols 29343a complete Transparent copy of the Document, free of added material. 29344If you use the latter option, you must take reasonably prudent steps, 29345when you begin distribution of Opaque copies in quantity, to ensure 29346that this Transparent copy will remain thus accessible at the stated 29347location until at least one year after the last time you distribute an 29348Opaque copy (directly or through your agents or retailers) of that 29349edition to the public. 29350 29351It is requested, but not required, that you contact the authors of the 29352Document well before redistributing any large number of copies, to give 29353them a chance to provide you with an updated version of the Document. 29354 29355@strong{4. MODIFICATIONS} 29356 29357You may copy and distribute a Modified Version of the Document under 29358the conditions of sections 2 and 3 above, provided that you release 29359the Modified Version under precisely this License, with the Modified 29360Version filling the role of the Document, thus licensing distribution 29361and modification of the Modified Version to whoever possesses a copy 29362of it. In addition, you must do these things in the Modified Version: 29363 29364 29365@enumerate A 29366 29367@item 29368Use in the Title Page (and on the covers, if any) a title distinct 29369from that of the Document, and from those of previous versions 29370(which should, if there were any, be listed in the History section 29371of the Document). You may use the same title as a previous version 29372if the original publisher of that version gives permission. 29373 29374@item 29375List on the Title Page, as authors, one or more persons or entities 29376responsible for authorship of the modifications in the Modified 29377Version, together with at least five of the principal authors of the 29378Document (all of its principal authors, if it has fewer than five), 29379unless they release you from this requirement. 29380 29381@item 29382State on the Title page the name of the publisher of the 29383Modified Version, as the publisher. 29384 29385@item 29386Preserve all the copyright notices of the Document. 29387 29388@item 29389Add an appropriate copyright notice for your modifications 29390adjacent to the other copyright notices. 29391 29392@item 29393Include, immediately after the copyright notices, a license notice 29394giving the public permission to use the Modified Version under the 29395terms of this License, in the form shown in the Addendum below. 29396 29397@item 29398Preserve in that license notice the full lists of Invariant Sections 29399and required Cover Texts given in the Document's license notice. 29400 29401@item 29402Include an unaltered copy of this License. 29403 29404@item 29405Preserve the section Entitled "History", Preserve its Title, and add 29406to it an item stating at least the title, year, new authors, and 29407publisher of the Modified Version as given on the Title Page. If 29408there is no section Entitled "History" in the Document, create one 29409stating the title, year, authors, and publisher of the Document as 29410given on its Title Page, then add an item describing the Modified 29411Version as stated in the previous sentence. 29412 29413@item 29414Preserve the network location, if any, given in the Document for 29415public access to a Transparent copy of the Document, and likewise 29416the network locations given in the Document for previous versions 29417it was based on. These may be placed in the "History" section. 29418You may omit a network location for a work that was published at 29419least four years before the Document itself, or if the original 29420publisher of the version it refers to gives permission. 29421 29422@item 29423For any section Entitled "Acknowledgements" or "Dedications", 29424Preserve the Title of the section, and preserve in the section all 29425the substance and tone of each of the contributor acknowledgements 29426and/or dedications given therein. 29427 29428@item 29429Preserve all the Invariant Sections of the Document, 29430unaltered in their text and in their titles. Section numbers 29431or the equivalent are not considered part of the section titles. 29432 29433@item 29434Delete any section Entitled "Endorsements". Such a section 29435may not be included in the Modified Version. 29436 29437@item 29438Do not retitle any existing section to be Entitled "Endorsements" 29439or to conflict in title with any Invariant Section. 29440 29441@item 29442Preserve any Warranty Disclaimers. 29443@end enumerate 29444 29445If the Modified Version includes new front-matter sections or 29446appendices that qualify as Secondary Sections and contain no material 29447copied from the Document, you may at your option designate some or all 29448of these sections as invariant. To do this, add their titles to the 29449list of Invariant Sections in the Modified Version's license notice. 29450These titles must be distinct from any other section titles. 29451 29452You may add a section Entitled "Endorsements", provided it contains 29453nothing but endorsements of your Modified Version by various 29454parties---for example, statements of peer review or that the text has 29455been approved by an organization as the authoritative definition of a 29456standard. 29457 29458You may add a passage of up to five words as a Front-Cover Text, and a 29459passage of up to 25 words as a Back-Cover Text, to the end of the list 29460of Cover Texts in the Modified Version. Only one passage of 29461Front-Cover Text and one of Back-Cover Text may be added by (or 29462through arrangements made by) any one entity. If the Document already 29463includes a cover text for the same cover, previously added by you or 29464by arrangement made by the same entity you are acting on behalf of, 29465you may not add another; but you may replace the old one, on explicit 29466permission from the previous publisher that added the old one. 29467 29468The author(s) and publisher(s) of the Document do not by this License 29469give permission to use their names for publicity for or to assert or 29470imply endorsement of any Modified Version. 29471 29472@strong{5. COMBINING DOCUMENTS} 29473 29474You may combine the Document with other documents released under this 29475License, under the terms defined in section 4 above for modified 29476versions, provided that you include in the combination all of the 29477Invariant Sections of all of the original documents, unmodified, and 29478list them all as Invariant Sections of your combined work in its 29479license notice, and that you preserve all their Warranty Disclaimers. 29480 29481The combined work need only contain one copy of this License, and 29482multiple identical Invariant Sections may be replaced with a single 29483copy. If there are multiple Invariant Sections with the same name but 29484different contents, make the title of each such section unique by 29485adding at the end of it, in parentheses, the name of the original 29486author or publisher of that section if known, or else a unique number. 29487Make the same adjustment to the section titles in the list of 29488Invariant Sections in the license notice of the combined work. 29489 29490In the combination, you must combine any sections Entitled "History" 29491in the various original documents, forming one section Entitled 29492"History"; likewise combine any sections Entitled "Acknowledgements", 29493and any sections Entitled "Dedications". You must delete all sections 29494Entitled "Endorsements". 29495 29496@strong{6. COLLECTIONS OF DOCUMENTS} 29497 29498You may make a collection consisting of the Document and other documents 29499released under this License, and replace the individual copies of this 29500License in the various documents with a single copy that is included in 29501the collection, provided that you follow the rules of this License for 29502verbatim copying of each of the documents in all other respects. 29503 29504You may extract a single document from such a collection, and distribute 29505it individually under this License, provided you insert a copy of this 29506License into the extracted document, and follow this License in all 29507other respects regarding verbatim copying of that document. 29508 29509@strong{7. AGGREGATION WITH INDEPENDENT WORKS} 29510 29511A compilation of the Document or its derivatives with other separate 29512and independent documents or works, in or on a volume of a storage or 29513distribution medium, is called an "aggregate" if the copyright 29514resulting from the compilation is not used to limit the legal rights 29515of the compilation's users beyond what the individual works permit. 29516When the Document is included in an aggregate, this License does not 29517apply to the other works in the aggregate which are not themselves 29518derivative works of the Document. 29519 29520If the Cover Text requirement of section 3 is applicable to these 29521copies of the Document, then if the Document is less than one half of 29522the entire aggregate, the Document's Cover Texts may be placed on 29523covers that bracket the Document within the aggregate, or the 29524electronic equivalent of covers if the Document is in electronic form. 29525Otherwise they must appear on printed covers that bracket the whole 29526aggregate. 29527 29528@strong{8. TRANSLATION} 29529 29530Translation is considered a kind of modification, so you may 29531distribute translations of the Document under the terms of section 4. 29532Replacing Invariant Sections with translations requires special 29533permission from their copyright holders, but you may include 29534translations of some or all Invariant Sections in addition to the 29535original versions of these Invariant Sections. You may include a 29536translation of this License, and all the license notices in the 29537Document, and any Warranty Disclaimers, provided that you also include 29538the original English version of this License and the original versions 29539of those notices and disclaimers. In case of a disagreement between 29540the translation and the original version of this License or a notice 29541or disclaimer, the original version will prevail. 29542 29543If a section in the Document is Entitled "Acknowledgements", 29544"Dedications", or "History", the requirement (section 4) to Preserve 29545its Title (section 1) will typically require changing the actual 29546title. 29547 29548@strong{9. TERMINATION} 29549 29550You may not copy, modify, sublicense, or distribute the Document 29551except as expressly provided under this License. Any attempt 29552otherwise to copy, modify, sublicense, or distribute it is void, and 29553will automatically terminate your rights under this License. 29554 29555However, if you cease all violation of this License, then your license 29556from a particular copyright holder is reinstated (a) provisionally, 29557unless and until the copyright holder explicitly and finally 29558terminates your license, and (b) permanently, if the copyright holder 29559fails to notify you of the violation by some reasonable means prior to 2956060 days after the cessation. 29561 29562Moreover, your license from a particular copyright holder is 29563reinstated permanently if the copyright holder notifies you of the 29564violation by some reasonable means, this is the first time you have 29565received notice of violation of this License (for any work) from that 29566copyright holder, and you cure the violation prior to 30 days after 29567your receipt of the notice. 29568 29569Termination of your rights under this section does not terminate the 29570licenses of parties who have received copies or rights from you under 29571this License. If your rights have been terminated and not permanently 29572reinstated, receipt of a copy of some or all of the same material does 29573not give you any rights to use it. 29574 29575@strong{10. FUTURE REVISIONS OF THIS LICENSE} 29576 29577The Free Software Foundation may publish new, revised versions 29578of the GNU Free Documentation License from time to time. Such new 29579versions will be similar in spirit to the present version, but may 29580differ in detail to address new problems or concerns. See 29581@indicateurl{http://www.gnu.org/copyleft/}. 29582 29583Each version of the License is given a distinguishing version number. 29584If the Document specifies that a particular numbered version of this 29585License "or any later version" applies to it, you have the option of 29586following the terms and conditions either of that specified version or 29587of any later version that has been published (not as a draft) by the 29588Free Software Foundation. If the Document does not specify a version 29589number of this License, you may choose any version ever published (not 29590as a draft) by the Free Software Foundation. If the Document 29591specifies that a proxy can decide which future versions of this 29592License can be used, that proxy's public statement of acceptance of a 29593version permanently authorizes you to choose that version for the 29594Document. 29595 29596@strong{11. RELICENSING} 29597 29598"Massive Multiauthor Collaboration Site" (or "MMC Site") means any 29599World Wide Web server that publishes copyrightable works and also 29600provides prominent facilities for anybody to edit those works. A 29601public wiki that anybody can edit is an example of such a server. A 29602"Massive Multiauthor Collaboration" (or "MMC") contained in the 29603site means any set of copyrightable works thus published on the MMC 29604site. 29605 29606"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 29607license published by Creative Commons Corporation, a not-for-profit 29608corporation with a principal place of business in San Francisco, 29609California, as well as future copyleft versions of that license 29610published by that same organization. 29611 29612"Incorporate" means to publish or republish a Document, in whole or 29613in part, as part of another Document. 29614 29615An MMC is "eligible for relicensing" if it is licensed under this 29616License, and if all works that were first published under this License 29617somewhere other than this MMC, and subsequently incorporated in whole 29618or in part into the MMC, (1) had no cover texts or invariant sections, 29619and (2) were thus incorporated prior to November 1, 2008. 29620 29621The operator of an MMC Site may republish an MMC contained in the site 29622under CC-BY-SA on the same site at any time before August 1, 2009, 29623provided the MMC is eligible for relicensing. 29624 29625@strong{ADDENDUM: How to use this License for your documents} 29626 29627To use this License in a document you have written, include a copy of 29628the License in the document and put the following copyright and 29629license notices just after the title page: 29630 29631@quotation 29632 29633Copyright © YEAR YOUR NAME. 29634Permission is granted to copy, distribute and/or modify this document 29635under the terms of the GNU Free Documentation License, Version 1.3 29636or any later version published by the Free Software Foundation; 29637with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 29638A copy of the license is included in the section entitled "GNU 29639Free Documentation License". 29640@end quotation 29641 29642If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, 29643replace the "with ... Texts." line with this: 29644 29645@quotation 29646 29647with the Invariant Sections being LIST THEIR TITLES, with the 29648Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. 29649@end quotation 29650 29651If you have Invariant Sections without Cover Texts, or some other 29652combination of the three, merge those two alternatives to suit the 29653situation. 29654 29655If your document contains nontrivial examples of program code, we 29656recommend releasing these examples in parallel under your choice of 29657free software license, such as the GNU General Public License, 29658to permit their use in free software. 29659 29660@node Index,,GNU Free Documentation License,Top 29661@unnumbered Index 29662 29663 29664@printindex ge 29665 29666 29667@c %**end of body 29668@bye 29669