1\input texinfo @c -*-texinfo-*- 2 3@c %**start of header 4 5@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo 6@c o 7@c GNAT DOCUMENTATION o 8@c o 9@c G N A T _ RM o 10@c o 11@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o 12@c o 13@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo 14 15@setfilename gnat_rm.info 16 17@copying 18Copyright @copyright{} 1995-2012, Free Software Foundation, Inc. 19 20Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU Free Documentation License, Version 1.3 or 22any later version published by the Free Software Foundation; with no 23Invariant Sections, with the Front-Cover Texts being ``GNAT Reference 24Manual'', and with no Back-Cover Texts. A copy of the license is 25included in the section entitled ``GNU Free Documentation License''. 26@end copying 27 28@set EDITION GNAT 29 30@settitle GNAT Reference Manual 31 32@setchapternewpage odd 33@syncodeindex fn cp 34 35@include gcc-common.texi 36 37@dircategory GNU Ada tools 38@direntry 39* GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools. 40@end direntry 41 42@titlepage 43@title GNAT Reference Manual 44@subtitle GNAT, The GNU Ada Development Environment 45@versionsubtitle 46@author AdaCore 47@page 48@vskip 0pt plus 1filll 49 50@insertcopying 51 52@end titlepage 53 54@ifnottex 55@node Top, About This Guide, (dir), (dir) 56@top GNAT Reference Manual 57 58@noindent 59GNAT Reference Manual 60 61@noindent 62GNAT, The GNU Ada Development Environment@* 63GCC version @value{version-GCC}@* 64 65@noindent 66AdaCore 67 68@menu 69* About This Guide:: 70* Implementation Defined Pragmas:: 71* Implementation Defined Aspects:: 72* Implementation Defined Attributes:: 73* Standard and Implementation Defined Restrictions:: 74* Implementation Advice:: 75* Implementation Defined Characteristics:: 76* Intrinsic Subprograms:: 77* Representation Clauses and Pragmas:: 78* Standard Library Routines:: 79* The Implementation of Standard I/O:: 80* The GNAT Library:: 81* Interfacing to Other Languages:: 82* Specialized Needs Annexes:: 83* Implementation of Specific Ada Features:: 84* Implementation of Ada 2012 Features:: 85* Obsolescent Features:: 86* GNU Free Documentation License:: 87* Index:: 88 89 --- The Detailed Node Listing --- 90 91About This Guide 92 93* What This Reference Manual Contains:: 94* Related Information:: 95 96Implementation Defined Pragmas 97 98* Pragma Abort_Defer:: 99* Pragma Abstract_State:: 100* Pragma Ada_83:: 101* Pragma Ada_95:: 102* Pragma Ada_05:: 103* Pragma Ada_2005:: 104* Pragma Ada_12:: 105* Pragma Ada_2012:: 106* Pragma Allow_Integer_Address:: 107* Pragma Annotate:: 108* Pragma Assert:: 109* Pragma Assert_And_Cut:: 110* Pragma Assertion_Policy:: 111* Pragma Assume:: 112* Pragma Assume_No_Invalid_Values:: 113* Pragma Attribute_Definition:: 114* Pragma Ast_Entry:: 115* Pragma C_Pass_By_Copy:: 116* Pragma Check:: 117* Pragma Check_Float_Overflow:: 118* Pragma Check_Name:: 119* Pragma Check_Policy:: 120* Pragma CIL_Constructor:: 121* Pragma Comment:: 122* Pragma Common_Object:: 123* Pragma Compile_Time_Error:: 124* Pragma Compile_Time_Warning:: 125* Pragma Compiler_Unit:: 126* Pragma Compiler_Unit_Warning:: 127* Pragma Complete_Representation:: 128* Pragma Complex_Representation:: 129* Pragma Component_Alignment:: 130* Pragma Contract_Cases:: 131* Pragma Convention_Identifier:: 132* Pragma CPP_Class:: 133* Pragma CPP_Constructor:: 134* Pragma CPP_Virtual:: 135* Pragma CPP_Vtable:: 136* Pragma CPU:: 137* Pragma Debug:: 138* Pragma Debug_Policy:: 139* Pragma Default_Storage_Pool:: 140* Pragma Depends:: 141* Pragma Detect_Blocking:: 142* Pragma Disable_Atomic_Synchronization:: 143* Pragma Dispatching_Domain:: 144* Pragma Elaboration_Checks:: 145* Pragma Eliminate:: 146* Pragma Enable_Atomic_Synchronization:: 147* Pragma Export_Exception:: 148* Pragma Export_Function:: 149* Pragma Export_Object:: 150* Pragma Export_Procedure:: 151* Pragma Export_Value:: 152* Pragma Export_Valued_Procedure:: 153* Pragma Extend_System:: 154* Pragma Extensions_Allowed:: 155* Pragma External:: 156* Pragma External_Name_Casing:: 157* Pragma Fast_Math:: 158* Pragma Favor_Top_Level:: 159* Pragma Finalize_Storage_Only:: 160* Pragma Float_Representation:: 161* Pragma Global:: 162* Pragma Ident:: 163* Pragma Implementation_Defined:: 164* Pragma Implemented:: 165* Pragma Implicit_Packing:: 166* Pragma Import_Exception:: 167* Pragma Import_Function:: 168* Pragma Import_Object:: 169* Pragma Import_Procedure:: 170* Pragma Import_Valued_Procedure:: 171* Pragma Independent:: 172* Pragma Independent_Components:: 173* Pragma Initial_Condition:: 174* Pragma Initialize_Scalars:: 175* Pragma Initializes:: 176* Pragma Inline_Always:: 177* Pragma Inline_Generic:: 178* Pragma Interface:: 179* Pragma Interface_Name:: 180* Pragma Interrupt_Handler:: 181* Pragma Interrupt_State:: 182* Pragma Invariant:: 183* Pragma Java_Constructor:: 184* Pragma Java_Interface:: 185* Pragma Keep_Names:: 186* Pragma License:: 187* Pragma Link_With:: 188* Pragma Linker_Alias:: 189* Pragma Linker_Constructor:: 190* Pragma Linker_Destructor:: 191* Pragma Linker_Section:: 192* Pragma Long_Float:: 193* Pragma Loop_Invariant:: 194* Pragma Loop_Optimize:: 195* Pragma Loop_Variant:: 196* Pragma Machine_Attribute:: 197* Pragma Main:: 198* Pragma Main_Storage:: 199* Pragma No_Body:: 200* Pragma No_Inline:: 201* Pragma No_Return:: 202* Pragma No_Run_Time:: 203* Pragma No_Strict_Aliasing :: 204* Pragma Normalize_Scalars:: 205* Pragma Obsolescent:: 206* Pragma Optimize_Alignment:: 207* Pragma Ordered:: 208* Pragma Overflow_Mode:: 209* Pragma Overriding_Renamings:: 210* Pragma Partition_Elaboration_Policy:: 211* Pragma Passive:: 212* Pragma Persistent_BSS:: 213* Pragma Polling:: 214* Pragma Post:: 215* Pragma Postcondition:: 216* Pragma Post_Class:: 217* Pragma Pre:: 218* Pragma Precondition:: 219* Pragma Predicate:: 220* Pragma Preelaborable_Initialization:: 221* Pragma Preelaborate_05:: 222* Pragma Pre_Class:: 223* Pragma Priority_Specific_Dispatching:: 224* Pragma Profile:: 225* Pragma Profile_Warnings:: 226* Pragma Propagate_Exceptions:: 227* Pragma Provide_Shift_Operators:: 228* Pragma Psect_Object:: 229* Pragma Pure_05:: 230* Pragma Pure_12:: 231* Pragma Pure_Function:: 232* Pragma Ravenscar:: 233* Pragma Refined_State:: 234* Pragma Relative_Deadline:: 235* Pragma Remote_Access_Type:: 236* Pragma Restricted_Run_Time:: 237* Pragma Restriction_Warnings:: 238* Pragma Reviewable:: 239* Pragma Share_Generic:: 240* Pragma Shared:: 241* Pragma Short_Circuit_And_Or:: 242* Pragma Short_Descriptors:: 243* Pragma Simple_Storage_Pool_Type:: 244* Pragma Source_File_Name:: 245* Pragma Source_File_Name_Project:: 246* Pragma Source_Reference:: 247* Pragma SPARK_Mode:: 248* Pragma Static_Elaboration_Desired:: 249* Pragma Stream_Convert:: 250* Pragma Style_Checks:: 251* Pragma Subtitle:: 252* Pragma Suppress:: 253* Pragma Suppress_All:: 254* Pragma Suppress_Debug_Info:: 255* Pragma Suppress_Exception_Locations:: 256* Pragma Suppress_Initialization:: 257* Pragma Task_Info:: 258* Pragma Task_Name:: 259* Pragma Task_Storage:: 260* Pragma Test_Case:: 261* Pragma Thread_Local_Storage:: 262* Pragma Time_Slice:: 263* Pragma Title:: 264* Pragma Type_Invariant:: 265* Pragma Type_Invariant_Class:: 266* Pragma Unchecked_Union:: 267* Pragma Unimplemented_Unit:: 268* Pragma Universal_Aliasing :: 269* Pragma Universal_Data:: 270* Pragma Unmodified:: 271* Pragma Unreferenced:: 272* Pragma Unreferenced_Objects:: 273* Pragma Unreserve_All_Interrupts:: 274* Pragma Unsuppress:: 275* Pragma Use_VADS_Size:: 276* Pragma Validity_Checks:: 277* Pragma Volatile:: 278* Pragma Warning_As_Error:: 279* Pragma Warnings:: 280* Pragma Weak_External:: 281* Pragma Wide_Character_Encoding:: 282 283Implementation Defined Aspects 284 285* Aspect Abstract_State:: 286* Aspect Contract_Cases:: 287* Aspect Depends:: 288* Aspect Dimension:: 289* Aspect Dimension_System:: 290* Aspect Favor_Top_Level:: 291* Aspect Global:: 292* Aspect Initial_Condition:: 293* Aspect Initializes:: 294* Aspect Inline_Always:: 295* Aspect Invariant:: 296* Aspect Linker_Section:: 297* Aspect Object_Size:: 298* Aspect Persistent_BSS:: 299* Aspect Predicate:: 300* Aspect Preelaborate_05:: 301* Aspect Pure_05:: 302* Aspect Pure_12:: 303* Aspect Pure_Function:: 304* Aspect Refined_State:: 305* Aspect Remote_Access_Type:: 306* Aspect Scalar_Storage_Order:: 307* Aspect Shared:: 308* Aspect Simple_Storage_Pool:: 309* Aspect Simple_Storage_Pool_Type:: 310* Aspect SPARK_Mode:: 311* Aspect Suppress_Debug_Info:: 312* Aspect Test_Case:: 313* Aspect Universal_Aliasing:: 314* Aspect Universal_Data:: 315* Aspect Unmodified:: 316* Aspect Unreferenced:: 317* Aspect Unreferenced_Objects:: 318* Aspect Value_Size:: 319* Aspect Warnings:: 320 321Implementation Defined Attributes 322 323* Attribute Abort_Signal:: 324* Attribute Address_Size:: 325* Attribute Asm_Input:: 326* Attribute Asm_Output:: 327* Attribute AST_Entry:: 328* Attribute Bit:: 329* Attribute Bit_Position:: 330* Attribute Compiler_Version:: 331* Attribute Code_Address:: 332* Attribute Default_Bit_Order:: 333* Attribute Descriptor_Size:: 334* Attribute Elaborated:: 335* Attribute Elab_Body:: 336* Attribute Elab_Spec:: 337* Attribute Elab_Subp_Body:: 338* Attribute Emax:: 339* Attribute Enabled:: 340* Attribute Enum_Rep:: 341* Attribute Enum_Val:: 342* Attribute Epsilon:: 343* Attribute Fixed_Value:: 344* Attribute Has_Access_Values:: 345* Attribute Has_Discriminants:: 346* Attribute Img:: 347* Attribute Integer_Value:: 348* Attribute Invalid_Value:: 349* Attribute Large:: 350* Attribute Library_Level:: 351* Attribute Loop_Entry:: 352* Attribute Machine_Size:: 353* Attribute Mantissa:: 354* Attribute Max_Interrupt_Priority:: 355* Attribute Max_Priority:: 356* Attribute Maximum_Alignment:: 357* Attribute Mechanism_Code:: 358* Attribute Null_Parameter:: 359* Attribute Object_Size:: 360* Attribute Passed_By_Reference:: 361* Attribute Pool_Address:: 362* Attribute Range_Length:: 363* Attribute Ref:: 364* Attribute Restriction_Set:: 365* Attribute Result:: 366* Attribute Safe_Emax:: 367* Attribute Safe_Large:: 368* Attribute Scalar_Storage_Order:: 369* Attribute Simple_Storage_Pool:: 370* Attribute Small:: 371* Attribute Storage_Unit:: 372* Attribute Stub_Type:: 373* Attribute System_Allocator_Alignment:: 374* Attribute Target_Name:: 375* Attribute Tick:: 376* Attribute To_Address:: 377* Attribute Type_Class:: 378* Attribute UET_Address:: 379* Attribute Unconstrained_Array:: 380* Attribute Universal_Literal_String:: 381* Attribute Unrestricted_Access:: 382* Attribute Update:: 383* Attribute Valid_Scalars:: 384* Attribute VADS_Size:: 385* Attribute Value_Size:: 386* Attribute Wchar_T_Size:: 387* Attribute Word_Size:: 388 389Standard and Implementation Defined Restrictions 390 391* Partition-Wide Restrictions:: 392* Program Unit Level Restrictions:: 393 394Partition-Wide Restrictions 395 396* Immediate_Reclamation:: 397* Max_Asynchronous_Select_Nesting:: 398* Max_Entry_Queue_Length:: 399* Max_Protected_Entries:: 400* Max_Select_Alternatives:: 401* Max_Storage_At_Blocking:: 402* Max_Task_Entries:: 403* Max_Tasks:: 404* No_Abort_Statements:: 405* No_Access_Parameter_Allocators:: 406* No_Access_Subprograms:: 407* No_Allocators:: 408* No_Anonymous_Allocators:: 409* No_Calendar:: 410* No_Coextensions:: 411* No_Default_Initialization:: 412* No_Delay:: 413* No_Dependence:: 414* No_Direct_Boolean_Operators:: 415* No_Dispatch:: 416* No_Dispatching_Calls:: 417* No_Dynamic_Attachment:: 418* No_Dynamic_Priorities:: 419* No_Entry_Calls_In_Elaboration_Code:: 420* No_Enumeration_Maps:: 421* No_Exception_Handlers:: 422* No_Exception_Propagation:: 423* No_Exception_Registration:: 424* No_Exceptions:: 425* No_Finalization:: 426* No_Fixed_Point:: 427* No_Floating_Point:: 428* No_Implicit_Conditionals:: 429* No_Implicit_Dynamic_Code:: 430* No_Implicit_Heap_Allocations:: 431* No_Implicit_Loops:: 432* No_Initialize_Scalars:: 433* No_IO:: 434* No_Local_Allocators:: 435* No_Local_Protected_Objects:: 436* No_Local_Timing_Events:: 437* No_Nested_Finalization:: 438* No_Protected_Type_Allocators:: 439* No_Protected_Types:: 440* No_Recursion:: 441* No_Reentrancy:: 442* No_Relative_Delay:: 443* No_Requeue_Statements:: 444* No_Secondary_Stack:: 445* No_Select_Statements:: 446* No_Specific_Termination_Handlers:: 447* No_Specification_of_Aspect:: 448* No_Standard_Allocators_After_Elaboration:: 449* No_Standard_Storage_Pools:: 450* No_Stream_Optimizations:: 451* No_Streams:: 452* No_Task_Allocators:: 453* No_Task_Attributes_Package:: 454* No_Task_Hierarchy:: 455* No_Task_Termination:: 456* No_Tasking:: 457* No_Terminate_Alternatives:: 458* No_Unchecked_Access:: 459* Simple_Barriers:: 460* Static_Priorities:: 461* Static_Storage_Size:: 462 463Program Unit Level Restrictions 464 465* No_Elaboration_Code:: 466* No_Entry_Queue:: 467* No_Implementation_Aspect_Specifications:: 468* No_Implementation_Attributes:: 469* No_Implementation_Identifiers:: 470* No_Implementation_Pragmas:: 471* No_Implementation_Restrictions:: 472* No_Implementation_Units:: 473* No_Implicit_Aliasing:: 474* No_Obsolescent_Features:: 475* No_Wide_Characters:: 476* SPARK_05:: 477 478The Implementation of Standard I/O 479 480* Standard I/O Packages:: 481* FORM Strings:: 482* Direct_IO:: 483* Sequential_IO:: 484* Text_IO:: 485* Wide_Text_IO:: 486* Wide_Wide_Text_IO:: 487* Stream_IO:: 488* Text Translation:: 489* Shared Files:: 490* Filenames encoding:: 491* Open Modes:: 492* Operations on C Streams:: 493* Interfacing to C Streams:: 494 495The GNAT Library 496 497* Ada.Characters.Latin_9 (a-chlat9.ads):: 498* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: 499* Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: 500* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads):: 501* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads):: 502* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads):: 503* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads):: 504* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads):: 505* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads):: 506* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads):: 507* Ada.Containers.Formal_Vectors (a-cofove.ads):: 508* Ada.Command_Line.Environment (a-colien.ads):: 509* Ada.Command_Line.Remove (a-colire.ads):: 510* Ada.Command_Line.Response_File (a-clrefi.ads):: 511* Ada.Direct_IO.C_Streams (a-diocst.ads):: 512* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: 513* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads):: 514* Ada.Exceptions.Traceback (a-exctra.ads):: 515* Ada.Sequential_IO.C_Streams (a-siocst.ads):: 516* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: 517* Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: 518* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: 519* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads):: 520* Ada.Text_IO.C_Streams (a-tiocst.ads):: 521* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads):: 522* Ada.Wide_Characters.Unicode (a-wichun.ads):: 523* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: 524* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads):: 525* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads):: 526* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: 527* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads):: 528* GNAT.Altivec (g-altive.ads):: 529* GNAT.Altivec.Conversions (g-altcon.ads):: 530* GNAT.Altivec.Vector_Operations (g-alveop.ads):: 531* GNAT.Altivec.Vector_Types (g-alvety.ads):: 532* GNAT.Altivec.Vector_Views (g-alvevi.ads):: 533* GNAT.Array_Split (g-arrspl.ads):: 534* GNAT.AWK (g-awk.ads):: 535* GNAT.Bounded_Buffers (g-boubuf.ads):: 536* GNAT.Bounded_Mailboxes (g-boumai.ads):: 537* GNAT.Bubble_Sort (g-bubsor.ads):: 538* GNAT.Bubble_Sort_A (g-busora.ads):: 539* GNAT.Bubble_Sort_G (g-busorg.ads):: 540* GNAT.Byte_Order_Mark (g-byorma.ads):: 541* GNAT.Byte_Swapping (g-bytswa.ads):: 542* GNAT.Calendar (g-calend.ads):: 543* GNAT.Calendar.Time_IO (g-catiio.ads):: 544* GNAT.Case_Util (g-casuti.ads):: 545* GNAT.CGI (g-cgi.ads):: 546* GNAT.CGI.Cookie (g-cgicoo.ads):: 547* GNAT.CGI.Debug (g-cgideb.ads):: 548* GNAT.Command_Line (g-comlin.ads):: 549* GNAT.Compiler_Version (g-comver.ads):: 550* GNAT.Ctrl_C (g-ctrl_c.ads):: 551* GNAT.CRC32 (g-crc32.ads):: 552* GNAT.Current_Exception (g-curexc.ads):: 553* GNAT.Debug_Pools (g-debpoo.ads):: 554* GNAT.Debug_Utilities (g-debuti.ads):: 555* GNAT.Decode_String (g-decstr.ads):: 556* GNAT.Decode_UTF8_String (g-deutst.ads):: 557* GNAT.Directory_Operations (g-dirope.ads):: 558* GNAT.Directory_Operations.Iteration (g-diopit.ads):: 559* GNAT.Dynamic_HTables (g-dynhta.ads):: 560* GNAT.Dynamic_Tables (g-dyntab.ads):: 561* GNAT.Encode_String (g-encstr.ads):: 562* GNAT.Encode_UTF8_String (g-enutst.ads):: 563* GNAT.Exception_Actions (g-excact.ads):: 564* GNAT.Exception_Traces (g-exctra.ads):: 565* GNAT.Exceptions (g-except.ads):: 566* GNAT.Expect (g-expect.ads):: 567* GNAT.Expect.TTY (g-exptty.ads):: 568* GNAT.Float_Control (g-flocon.ads):: 569* GNAT.Heap_Sort (g-heasor.ads):: 570* GNAT.Heap_Sort_A (g-hesora.ads):: 571* GNAT.Heap_Sort_G (g-hesorg.ads):: 572* GNAT.HTable (g-htable.ads):: 573* GNAT.IO (g-io.ads):: 574* GNAT.IO_Aux (g-io_aux.ads):: 575* GNAT.Lock_Files (g-locfil.ads):: 576* GNAT.MBBS_Discrete_Random (g-mbdira.ads):: 577* GNAT.MBBS_Float_Random (g-mbflra.ads):: 578* GNAT.MD5 (g-md5.ads):: 579* GNAT.Memory_Dump (g-memdum.ads):: 580* GNAT.Most_Recent_Exception (g-moreex.ads):: 581* GNAT.OS_Lib (g-os_lib.ads):: 582* GNAT.Perfect_Hash_Generators (g-pehage.ads):: 583* GNAT.Random_Numbers (g-rannum.ads):: 584* GNAT.Regexp (g-regexp.ads):: 585* GNAT.Registry (g-regist.ads):: 586* GNAT.Regpat (g-regpat.ads):: 587* GNAT.Secondary_Stack_Info (g-sestin.ads):: 588* GNAT.Semaphores (g-semaph.ads):: 589* GNAT.Serial_Communications (g-sercom.ads):: 590* GNAT.SHA1 (g-sha1.ads):: 591* GNAT.SHA224 (g-sha224.ads):: 592* GNAT.SHA256 (g-sha256.ads):: 593* GNAT.SHA384 (g-sha384.ads):: 594* GNAT.SHA512 (g-sha512.ads):: 595* GNAT.Signals (g-signal.ads):: 596* GNAT.Sockets (g-socket.ads):: 597* GNAT.Source_Info (g-souinf.ads):: 598* GNAT.Spelling_Checker (g-speche.ads):: 599* GNAT.Spelling_Checker_Generic (g-spchge.ads):: 600* GNAT.Spitbol.Patterns (g-spipat.ads):: 601* GNAT.Spitbol (g-spitbo.ads):: 602* GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: 603* GNAT.Spitbol.Table_Integer (g-sptain.ads):: 604* GNAT.Spitbol.Table_VString (g-sptavs.ads):: 605* GNAT.SSE (g-sse.ads):: 606* GNAT.SSE.Vector_Types (g-ssvety.ads):: 607* GNAT.Strings (g-string.ads):: 608* GNAT.String_Split (g-strspl.ads):: 609* GNAT.Table (g-table.ads):: 610* GNAT.Task_Lock (g-tasloc.ads):: 611* GNAT.Threads (g-thread.ads):: 612* GNAT.Time_Stamp (g-timsta.ads):: 613* GNAT.Traceback (g-traceb.ads):: 614* GNAT.Traceback.Symbolic (g-trasym.ads):: 615* GNAT.UTF_32 (g-utf_32.ads):: 616* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads):: 617* GNAT.Wide_Spelling_Checker (g-wispch.ads):: 618* GNAT.Wide_String_Split (g-wistsp.ads):: 619* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads):: 620* GNAT.Wide_Wide_String_Split (g-zistsp.ads):: 621* Interfaces.C.Extensions (i-cexten.ads):: 622* Interfaces.C.Streams (i-cstrea.ads):: 623* Interfaces.CPP (i-cpp.ads):: 624* Interfaces.Packed_Decimal (i-pacdec.ads):: 625* Interfaces.VxWorks (i-vxwork.ads):: 626* Interfaces.VxWorks.IO (i-vxwoio.ads):: 627* System.Address_Image (s-addima.ads):: 628* System.Assertions (s-assert.ads):: 629* System.Memory (s-memory.ads):: 630* System.Multiprocessors (s-multip.ads):: 631* System.Multiprocessors.Dispatching_Domains (s-mudido.ads):: 632* System.Partition_Interface (s-parint.ads):: 633* System.Pool_Global (s-pooglo.ads):: 634* System.Pool_Local (s-pooloc.ads):: 635* System.Restrictions (s-restri.ads):: 636* System.Rident (s-rident.ads):: 637* System.Strings.Stream_Ops (s-ststop.ads):: 638* System.Task_Info (s-tasinf.ads):: 639* System.Wch_Cnv (s-wchcnv.ads):: 640* System.Wch_Con (s-wchcon.ads):: 641 642Text_IO 643 644* Text_IO Stream Pointer Positioning:: 645* Text_IO Reading and Writing Non-Regular Files:: 646* Get_Immediate:: 647* Treating Text_IO Files as Streams:: 648* Text_IO Extensions:: 649* Text_IO Facilities for Unbounded Strings:: 650 651Wide_Text_IO 652 653* Wide_Text_IO Stream Pointer Positioning:: 654* Wide_Text_IO Reading and Writing Non-Regular Files:: 655 656Wide_Wide_Text_IO 657 658* Wide_Wide_Text_IO Stream Pointer Positioning:: 659* Wide_Wide_Text_IO Reading and Writing Non-Regular Files:: 660 661Interfacing to Other Languages 662 663* Interfacing to C:: 664* Interfacing to C++:: 665* Interfacing to COBOL:: 666* Interfacing to Fortran:: 667* Interfacing to non-GNAT Ada code:: 668 669Specialized Needs Annexes 670 671Implementation of Specific Ada Features 672* Machine Code Insertions:: 673* GNAT Implementation of Tasking:: 674* GNAT Implementation of Shared Passive Packages:: 675* Code Generation for Array Aggregates:: 676* The Size of Discriminated Records with Default Discriminants:: 677* Strict Conformance to the Ada Reference Manual:: 678 679Implementation of Ada 2012 Features 680 681Obsolescent Features 682 683GNU Free Documentation License 684 685Index 686@end menu 687 688@end ifnottex 689 690@node About This Guide 691@unnumbered About This Guide 692 693@noindent 694This manual contains useful information in writing programs using the 695@value{EDITION} compiler. It includes information on implementation dependent 696characteristics of @value{EDITION}, including all the information required by 697Annex M of the Ada language standard. 698 699@value{EDITION} implements Ada 95, Ada 2005 and Ada 2012, and it may also be 700invoked in Ada 83 compatibility mode. 701By default, @value{EDITION} assumes Ada 2012, 702but you can override with a compiler switch 703to explicitly specify the language version. 704(Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn, 705@value{EDITION} User's Guide}, for details on these switches.) 706Throughout this manual, references to ``Ada'' without a year suffix 707apply to all the Ada versions of the language. 708 709Ada is designed to be highly portable. 710In general, a program will have the same effect even when compiled by 711different compilers on different platforms. 712However, since Ada is designed to be used in a 713wide variety of applications, it also contains a number of system 714dependent features to be used in interfacing to the external world. 715@cindex Implementation-dependent features 716@cindex Portability 717 718Note: Any program that makes use of implementation-dependent features 719may be non-portable. You should follow good programming practice and 720isolate and clearly document any sections of your program that make use 721of these features in a non-portable manner. 722 723@ifset PROEDITION 724For ease of exposition, ``@value{EDITION}'' will be referred to simply as 725``GNAT'' in the remainder of this document. 726@end ifset 727 728@menu 729* What This Reference Manual Contains:: 730* Conventions:: 731* Related Information:: 732@end menu 733 734@node What This Reference Manual Contains 735@unnumberedsec What This Reference Manual Contains 736 737@noindent 738This reference manual contains the following chapters: 739 740@itemize @bullet 741@item 742@ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent 743pragmas, which can be used to extend and enhance the functionality of the 744compiler. 745 746@item 747@ref{Implementation Defined Attributes}, lists GNAT 748implementation-dependent attributes, which can be used to extend and 749enhance the functionality of the compiler. 750 751@item 752@ref{Standard and Implementation Defined Restrictions}, lists GNAT 753implementation-dependent restrictions, which can be used to extend and 754enhance the functionality of the compiler. 755 756@item 757@ref{Implementation Advice}, provides information on generally 758desirable behavior which are not requirements that all compilers must 759follow since it cannot be provided on all systems, or which may be 760undesirable on some systems. 761 762@item 763@ref{Implementation Defined Characteristics}, provides a guide to 764minimizing implementation dependent features. 765 766@item 767@ref{Intrinsic Subprograms}, describes the intrinsic subprograms 768implemented by GNAT, and how they can be imported into user 769application programs. 770 771@item 772@ref{Representation Clauses and Pragmas}, describes in detail the 773way that GNAT represents data, and in particular the exact set 774of representation clauses and pragmas that is accepted. 775 776@item 777@ref{Standard Library Routines}, provides a listing of packages and a 778brief description of the functionality that is provided by Ada's 779extensive set of standard library routines as implemented by GNAT@. 780 781@item 782@ref{The Implementation of Standard I/O}, details how the GNAT 783implementation of the input-output facilities. 784 785@item 786@ref{The GNAT Library}, is a catalog of packages that complement 787the Ada predefined library. 788 789@item 790@ref{Interfacing to Other Languages}, describes how programs 791written in Ada using GNAT can be interfaced to other programming 792languages. 793 794@ref{Specialized Needs Annexes}, describes the GNAT implementation of all 795of the specialized needs annexes. 796 797@item 798@ref{Implementation of Specific Ada Features}, discusses issues related 799to GNAT's implementation of machine code insertions, tasking, and several 800other features. 801 802@item 803@ref{Implementation of Ada 2012 Features}, describes the status of the 804GNAT implementation of the Ada 2012 language standard. 805 806@item 807@ref{Obsolescent Features} documents implementation dependent features, 808including pragmas and attributes, which are considered obsolescent, since 809there are other preferred ways of achieving the same results. These 810obsolescent forms are retained for backwards compatibility. 811 812@end itemize 813 814@cindex Ada 95 Language Reference Manual 815@cindex Ada 2005 Language Reference Manual 816@noindent 817This reference manual assumes a basic familiarity with the Ada 95 language, as 818described in the International Standard ANSI/ISO/IEC-8652:1995, 819January 1995. 820It does not require knowledge of the new features introduced by Ada 2005, 821(officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1 822and Amendment 1). 823Both reference manuals are included in the GNAT documentation 824package. 825 826@node Conventions 827@unnumberedsec Conventions 828@cindex Conventions, typographical 829@cindex Typographical conventions 830 831@noindent 832Following are examples of the typographical and graphic conventions used 833in this guide: 834 835@itemize @bullet 836@item 837@code{Functions}, @code{utility program names}, @code{standard names}, 838and @code{classes}. 839 840@item 841@code{Option flags} 842 843@item 844@file{File names}, @samp{button names}, and @samp{field names}. 845 846@item 847@code{Variables}, @env{environment variables}, and @var{metasyntactic 848variables}. 849 850@item 851@emph{Emphasis}. 852 853@item 854[optional information or parameters] 855 856@item 857Examples are described by text 858@smallexample 859and then shown this way. 860@end smallexample 861@end itemize 862 863@noindent 864Commands that are entered by the user are preceded in this manual by the 865characters @samp{$ } (dollar sign followed by space). If your system uses this 866sequence as a prompt, then the commands will appear exactly as you see them 867in the manual. If your system uses some other prompt, then the command will 868appear with the @samp{$} replaced by whatever prompt character you are using. 869 870@node Related Information 871@unnumberedsec Related Information 872@noindent 873See the following documents for further information on GNAT: 874 875@itemize @bullet 876@item 877@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn, 878@value{EDITION} User's Guide}, which provides information on how to use the 879GNAT compiler system. 880 881@item 882@cite{Ada 95 Reference Manual}, which contains all reference 883material for the Ada 95 programming language. 884 885@item 886@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 887of the Ada 95 standard. The annotations describe 888detailed aspects of the design decision, and in particular contain useful 889sections on Ada 83 compatibility. 890 891@item 892@cite{Ada 2005 Reference Manual}, which contains all reference 893material for the Ada 2005 programming language. 894 895@item 896@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version 897of the Ada 2005 standard. The annotations describe 898detailed aspects of the design decision, and in particular contain useful 899sections on Ada 83 and Ada 95 compatibility. 900 901@item 902@cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms}, 903which contains specific information on compatibility between GNAT and 904DEC Ada 83 systems. 905 906@item 907@cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which 908describes in detail the pragmas and attributes provided by the DEC Ada 83 909compiler system. 910 911@end itemize 912 913@node Implementation Defined Pragmas 914@chapter Implementation Defined Pragmas 915 916@noindent 917Ada defines a set of pragmas that can be used to supply additional 918information to the compiler. These language defined pragmas are 919implemented in GNAT and work as described in the Ada Reference Manual. 920 921In addition, Ada allows implementations to define additional pragmas 922whose meaning is defined by the implementation. GNAT provides a number 923of these implementation-defined pragmas, which can be used to extend 924and enhance the functionality of the compiler. This section of the GNAT 925Reference Manual describes these additional pragmas. 926 927Note that any program using these pragmas might not be portable to other 928compilers (although GNAT implements this set of pragmas on all 929platforms). Therefore if portability to other compilers is an important 930consideration, the use of these pragmas should be minimized. 931 932@menu 933* Pragma Abort_Defer:: 934* Pragma Abstract_State:: 935* Pragma Ada_83:: 936* Pragma Ada_95:: 937* Pragma Ada_05:: 938* Pragma Ada_2005:: 939* Pragma Ada_12:: 940* Pragma Ada_2012:: 941* Pragma Allow_Integer_Address:: 942* Pragma Annotate:: 943* Pragma Assert:: 944* Pragma Assert_And_Cut:: 945* Pragma Assertion_Policy:: 946* Pragma Assume:: 947* Pragma Assume_No_Invalid_Values:: 948* Pragma Attribute_Definition:: 949* Pragma Ast_Entry:: 950* Pragma C_Pass_By_Copy:: 951* Pragma Check:: 952* Pragma Check_Float_Overflow:: 953* Pragma Check_Name:: 954* Pragma Check_Policy:: 955* Pragma CIL_Constructor:: 956* Pragma Comment:: 957* Pragma Common_Object:: 958* Pragma Compile_Time_Error:: 959* Pragma Compile_Time_Warning:: 960* Pragma Compiler_Unit:: 961* Pragma Compiler_Unit_Warning:: 962* Pragma Complete_Representation:: 963* Pragma Complex_Representation:: 964* Pragma Component_Alignment:: 965* Pragma Contract_Cases:: 966* Pragma Convention_Identifier:: 967* Pragma CPP_Class:: 968* Pragma CPP_Constructor:: 969* Pragma CPP_Virtual:: 970* Pragma CPP_Vtable:: 971* Pragma CPU:: 972* Pragma Debug:: 973* Pragma Debug_Policy:: 974* Pragma Default_Storage_Pool:: 975* Pragma Depends:: 976* Pragma Detect_Blocking:: 977* Pragma Disable_Atomic_Synchronization:: 978* Pragma Dispatching_Domain:: 979* Pragma Elaboration_Checks:: 980* Pragma Eliminate:: 981* Pragma Enable_Atomic_Synchronization:: 982* Pragma Export_Exception:: 983* Pragma Export_Function:: 984* Pragma Export_Object:: 985* Pragma Export_Procedure:: 986* Pragma Export_Value:: 987* Pragma Export_Valued_Procedure:: 988* Pragma Extend_System:: 989* Pragma Extensions_Allowed:: 990* Pragma External:: 991* Pragma External_Name_Casing:: 992* Pragma Fast_Math:: 993* Pragma Favor_Top_Level:: 994* Pragma Finalize_Storage_Only:: 995* Pragma Float_Representation:: 996* Pragma Global:: 997* Pragma Ident:: 998* Pragma Implementation_Defined:: 999* Pragma Implemented:: 1000* Pragma Implicit_Packing:: 1001* Pragma Import_Exception:: 1002* Pragma Import_Function:: 1003* Pragma Import_Object:: 1004* Pragma Import_Procedure:: 1005* Pragma Import_Valued_Procedure:: 1006* Pragma Independent:: 1007* Pragma Independent_Components:: 1008* Pragma Initial_Condition:: 1009* Pragma Initialize_Scalars:: 1010* Pragma Initializes:: 1011* Pragma Inline_Always:: 1012* Pragma Inline_Generic:: 1013* Pragma Interface:: 1014* Pragma Interface_Name:: 1015* Pragma Interrupt_Handler:: 1016* Pragma Interrupt_State:: 1017* Pragma Invariant:: 1018* Pragma Java_Constructor:: 1019* Pragma Java_Interface:: 1020* Pragma Keep_Names:: 1021* Pragma License:: 1022* Pragma Link_With:: 1023* Pragma Linker_Alias:: 1024* Pragma Linker_Constructor:: 1025* Pragma Linker_Destructor:: 1026* Pragma Linker_Section:: 1027* Pragma Long_Float:: 1028* Pragma Loop_Invariant:: 1029* Pragma Loop_Optimize:: 1030* Pragma Loop_Variant:: 1031* Pragma Machine_Attribute:: 1032* Pragma Main:: 1033* Pragma Main_Storage:: 1034* Pragma No_Body:: 1035* Pragma No_Inline:: 1036* Pragma No_Return:: 1037* Pragma No_Run_Time:: 1038* Pragma No_Strict_Aliasing:: 1039* Pragma Normalize_Scalars:: 1040* Pragma Obsolescent:: 1041* Pragma Optimize_Alignment:: 1042* Pragma Ordered:: 1043* Pragma Overflow_Mode:: 1044* Pragma Overriding_Renamings:: 1045* Pragma Partition_Elaboration_Policy:: 1046* Pragma Passive:: 1047* Pragma Persistent_BSS:: 1048* Pragma Polling:: 1049* Pragma Post:: 1050* Pragma Postcondition:: 1051* Pragma Post_Class:: 1052* Pragma Pre:: 1053* Pragma Precondition:: 1054* Pragma Predicate:: 1055* Pragma Preelaborable_Initialization:: 1056* Pragma Preelaborate_05:: 1057* Pragma Pre_Class:: 1058* Pragma Priority_Specific_Dispatching:: 1059* Pragma Profile:: 1060* Pragma Profile_Warnings:: 1061* Pragma Propagate_Exceptions:: 1062* Pragma Provide_Shift_Operators:: 1063* Pragma Psect_Object:: 1064* Pragma Pure_05:: 1065* Pragma Pure_12:: 1066* Pragma Pure_Function:: 1067* Pragma Ravenscar:: 1068* Pragma Refined_State:: 1069* Pragma Relative_Deadline:: 1070* Pragma Remote_Access_Type:: 1071* Pragma Restricted_Run_Time:: 1072* Pragma Restriction_Warnings:: 1073* Pragma Reviewable:: 1074* Pragma Share_Generic:: 1075* Pragma Shared:: 1076* Pragma Short_Circuit_And_Or:: 1077* Pragma Short_Descriptors:: 1078* Pragma Simple_Storage_Pool_Type:: 1079* Pragma Source_File_Name:: 1080* Pragma Source_File_Name_Project:: 1081* Pragma Source_Reference:: 1082* Pragma SPARK_Mode:: 1083* Pragma Static_Elaboration_Desired:: 1084* Pragma Stream_Convert:: 1085* Pragma Style_Checks:: 1086* Pragma Subtitle:: 1087* Pragma Suppress:: 1088* Pragma Suppress_All:: 1089* Pragma Suppress_Debug_Info:: 1090* Pragma Suppress_Exception_Locations:: 1091* Pragma Suppress_Initialization:: 1092* Pragma Task_Info:: 1093* Pragma Task_Name:: 1094* Pragma Task_Storage:: 1095* Pragma Test_Case:: 1096* Pragma Thread_Local_Storage:: 1097* Pragma Time_Slice:: 1098* Pragma Title:: 1099* Pragma Type_Invariant:: 1100* Pragma Type_Invariant_Class:: 1101* Pragma Unchecked_Union:: 1102* Pragma Unimplemented_Unit:: 1103* Pragma Universal_Aliasing :: 1104* Pragma Universal_Data:: 1105* Pragma Unmodified:: 1106* Pragma Unreferenced:: 1107* Pragma Unreferenced_Objects:: 1108* Pragma Unreserve_All_Interrupts:: 1109* Pragma Unsuppress:: 1110* Pragma Use_VADS_Size:: 1111* Pragma Validity_Checks:: 1112* Pragma Volatile:: 1113* Pragma Warning_As_Error:: 1114* Pragma Warnings:: 1115* Pragma Weak_External:: 1116* Pragma Wide_Character_Encoding:: 1117@end menu 1118 1119@node Pragma Abort_Defer 1120@unnumberedsec Pragma Abort_Defer 1121@findex Abort_Defer 1122@cindex Deferring aborts 1123@noindent 1124Syntax: 1125@smallexample 1126pragma Abort_Defer; 1127@end smallexample 1128 1129@noindent 1130This pragma must appear at the start of the statement sequence of a 1131handled sequence of statements (right after the @code{begin}). It has 1132the effect of deferring aborts for the sequence of statements (but not 1133for the declarations or handlers, if any, associated with this statement 1134sequence). 1135 1136@node Pragma Abstract_State 1137@unnumberedsec Pragma Abstract_State 1138@findex Abstract_State 1139@noindent 1140For the description of this pragma, see SPARK 2014 Reference Manual, 1141section 7.1.4. 1142 1143@node Pragma Ada_83 1144@unnumberedsec Pragma Ada_83 1145@findex Ada_83 1146@noindent 1147Syntax: 1148@smallexample @c ada 1149pragma Ada_83; 1150@end smallexample 1151 1152@noindent 1153A configuration pragma that establishes Ada 83 mode for the unit to 1154which it applies, regardless of the mode set by the command line 1155switches. In Ada 83 mode, GNAT attempts to be as compatible with 1156the syntax and semantics of Ada 83, as defined in the original Ada 115783 Reference Manual as possible. In particular, the keywords added by Ada 95 1158and Ada 2005 are not recognized, optional package bodies are allowed, 1159and generics may name types with unknown discriminants without using 1160the @code{(<>)} notation. In addition, some but not all of the additional 1161restrictions of Ada 83 are enforced. 1162 1163Ada 83 mode is intended for two purposes. Firstly, it allows existing 1164Ada 83 code to be compiled and adapted to GNAT with less effort. 1165Secondly, it aids in keeping code backwards compatible with Ada 83. 1166However, there is no guarantee that code that is processed correctly 1167by GNAT in Ada 83 mode will in fact compile and execute with an Ada 116883 compiler, since GNAT does not enforce all the additional checks 1169required by Ada 83. 1170 1171@node Pragma Ada_95 1172@unnumberedsec Pragma Ada_95 1173@findex Ada_95 1174@noindent 1175Syntax: 1176@smallexample @c ada 1177pragma Ada_95; 1178@end smallexample 1179 1180@noindent 1181A configuration pragma that establishes Ada 95 mode for the unit to which 1182it applies, regardless of the mode set by the command line switches. 1183This mode is set automatically for the @code{Ada} and @code{System} 1184packages and their children, so you need not specify it in these 1185contexts. This pragma is useful when writing a reusable component that 1186itself uses Ada 95 features, but which is intended to be usable from 1187either Ada 83 or Ada 95 programs. 1188 1189@node Pragma Ada_05 1190@unnumberedsec Pragma Ada_05 1191@findex Ada_05 1192@noindent 1193Syntax: 1194@smallexample @c ada 1195pragma Ada_05; 1196pragma Ada_05 (local_NAME); 1197@end smallexample 1198 1199@noindent 1200A configuration pragma that establishes Ada 2005 mode for the unit to which 1201it applies, regardless of the mode set by the command line switches. 1202This pragma is useful when writing a reusable component that 1203itself uses Ada 2005 features, but which is intended to be usable from 1204either Ada 83 or Ada 95 programs. 1205 1206The one argument form (which is not a configuration pragma) 1207is used for managing the transition from 1208Ada 95 to Ada 2005 in the run-time library. If an entity is marked 1209as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 1210mode will generate a warning. In addition, in Ada_83 or Ada_95 1211mode, a preference rule is established which does not choose 1212such an entity unless it is unambiguously specified. This avoids 1213extra subprograms marked this way from generating ambiguities in 1214otherwise legal pre-Ada_2005 programs. The one argument form is 1215intended for exclusive use in the GNAT run-time library. 1216 1217@node Pragma Ada_2005 1218@unnumberedsec Pragma Ada_2005 1219@findex Ada_2005 1220@noindent 1221Syntax: 1222@smallexample @c ada 1223pragma Ada_2005; 1224@end smallexample 1225 1226@noindent 1227This configuration pragma is a synonym for pragma Ada_05 and has the 1228same syntax and effect. 1229 1230@node Pragma Ada_12 1231@unnumberedsec Pragma Ada_12 1232@findex Ada_12 1233@noindent 1234Syntax: 1235@smallexample @c ada 1236pragma Ada_12; 1237pragma Ada_12 (local_NAME); 1238@end smallexample 1239 1240@noindent 1241A configuration pragma that establishes Ada 2012 mode for the unit to which 1242it applies, regardless of the mode set by the command line switches. 1243This mode is set automatically for the @code{Ada} and @code{System} 1244packages and their children, so you need not specify it in these 1245contexts. This pragma is useful when writing a reusable component that 1246itself uses Ada 2012 features, but which is intended to be usable from 1247Ada 83, Ada 95, or Ada 2005 programs. 1248 1249The one argument form, which is not a configuration pragma, 1250is used for managing the transition from Ada 12512005 to Ada 2012 in the run-time library. If an entity is marked 1252as Ada_201 only, then referencing the entity in any pre-Ada_2012 1253mode will generate a warning. In addition, in any pre-Ada_2012 1254mode, a preference rule is established which does not choose 1255such an entity unless it is unambiguously specified. This avoids 1256extra subprograms marked this way from generating ambiguities in 1257otherwise legal pre-Ada_2012 programs. The one argument form is 1258intended for exclusive use in the GNAT run-time library. 1259 1260@node Pragma Ada_2012 1261@unnumberedsec Pragma Ada_2012 1262@findex Ada_2005 1263@noindent 1264Syntax: 1265@smallexample @c ada 1266pragma Ada_2012; 1267@end smallexample 1268 1269@noindent 1270This configuration pragma is a synonym for pragma Ada_12 and has the 1271same syntax and effect. 1272 1273@node Pragma Allow_Integer_Address 1274@unnumberedsec Pragma Allow_Integer_Address 1275@findex Allow_Integer_Address 1276@noindent 1277Syntax: 1278@smallexample @c ada 1279pragma Allow_Integer_Address; 1280@end smallexample 1281 1282@noindent 1283In almost all versions of GNAT, @code{System.Address} is a private 1284type in accordance with the implementation advice in the RM. This 1285means that integer values, 1286in particular integer literals, are not allowed as address values. 1287If the configuration pragma 1288@code{Allow_Integer_Address} is given, then integer expressions may 1289be used anywhere a value of type @code{System.Address} is required. 1290The effect is to introduce an implicit unchecked conversion from the 1291integer value to type @code{System.Address}. The reverse case of using 1292an address where an integer type is required is handled analogously. 1293The following example compiles without errors: 1294 1295@smallexample @c ada 1296pragma Allow_Integer_Address; 1297with System; use System; 1298package AddrAsInt is 1299 X : Integer; 1300 Y : Integer; 1301 for X'Address use 16#1240#; 1302 for Y use at 16#3230#; 1303 m : Address := 16#4000#; 1304 n : constant Address := 4000; 1305 p : constant Address := Address (X + Y); 1306 v : Integer := y'Address; 1307 w : constant Integer := Integer (Y'Address); 1308 type R is new integer; 1309 RR : R := 1000; 1310 Z : Integer; 1311 for Z'Address use RR; 1312end AddrAsInt; 1313@end smallexample 1314 1315@noindent 1316Note that pragma @code{Allow_Integer_Address} is ignored if 1317@code{System.Address} 1318is not a private type. In implementations of @code{GNAT} where 1319System.Address is a visible integer type (notably the implementations 1320for @code{OpenVMS}), this pragma serves no purpose but is ignored 1321rather than rejected to allow common sets of sources to be used 1322in the two situations. 1323 1324@node Pragma Annotate 1325@unnumberedsec Pragma Annotate 1326@findex Annotate 1327@noindent 1328Syntax: 1329@smallexample @c ada 1330pragma Annotate (IDENTIFIER [,IDENTIFIER @{, ARG@}]); 1331 1332ARG ::= NAME | EXPRESSION 1333@end smallexample 1334 1335@noindent 1336This pragma is used to annotate programs. @var{identifier} identifies 1337the type of annotation. GNAT verifies that it is an identifier, but does 1338not otherwise analyze it. The second optional identifier is also left 1339unanalyzed, and by convention is used to control the action of the tool to 1340which the annotation is addressed. The remaining @var{arg} arguments 1341can be either string literals or more generally expressions. 1342String literals are assumed to be either of type 1343@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} 1344depending on the character literals they contain. 1345All other kinds of arguments are analyzed as expressions, and must be 1346unambiguous. 1347 1348The analyzed pragma is retained in the tree, but not otherwise processed 1349by any part of the GNAT compiler, except to generate corresponding note 1350lines in the generated ALI file. For the format of these note lines, see 1351the compiler source file lib-writ.ads. This pragma is intended for use by 1352external tools, including ASIS@. The use of pragma Annotate does not 1353affect the compilation process in any way. This pragma may be used as 1354a configuration pragma. 1355 1356@node Pragma Assert 1357@unnumberedsec Pragma Assert 1358@findex Assert 1359@noindent 1360Syntax: 1361@smallexample @c ada 1362pragma Assert ( 1363 boolean_EXPRESSION 1364 [, string_EXPRESSION]); 1365@end smallexample 1366 1367@noindent 1368The effect of this pragma depends on whether the corresponding command 1369line switch is set to activate assertions. The pragma expands into code 1370equivalent to the following: 1371 1372@smallexample @c ada 1373if assertions-enabled then 1374 if not boolean_EXPRESSION then 1375 System.Assertions.Raise_Assert_Failure 1376 (string_EXPRESSION); 1377 end if; 1378end if; 1379@end smallexample 1380 1381@noindent 1382The string argument, if given, is the message that will be associated 1383with the exception occurrence if the exception is raised. If no second 1384argument is given, the default message is @samp{@var{file}:@var{nnn}}, 1385where @var{file} is the name of the source file containing the assert, 1386and @var{nnn} is the line number of the assert. A pragma is not a 1387statement, so if a statement sequence contains nothing but a pragma 1388assert, then a null statement is required in addition, as in: 1389 1390@smallexample @c ada 1391@dots{} 1392if J > 3 then 1393 pragma Assert (K > 3, "Bad value for K"); 1394 null; 1395end if; 1396@end smallexample 1397 1398@noindent 1399Note that, as with the @code{if} statement to which it is equivalent, the 1400type of the expression is either @code{Standard.Boolean}, or any type derived 1401from this standard type. 1402 1403Assert checks can be either checked or ignored. By default they are ignored. 1404They will be checked if either the command line switch @option{-gnata} is 1405used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used 1406to enable @code{Assert_Checks}. 1407 1408If assertions are ignored, then there 1409is no run-time effect (and in particular, any side effects from the 1410expression will not occur at run time). (The expression is still 1411analyzed at compile time, and may cause types to be frozen if they are 1412mentioned here for the first time). 1413 1414If assertions are checked, then the given expression is tested, and if 1415it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called 1416which results in the raising of @code{Assert_Failure} with the given message. 1417 1418You should generally avoid side effects in the expression arguments of 1419this pragma, because these side effects will turn on and off with the 1420setting of the assertions mode, resulting in assertions that have an 1421effect on the program. However, the expressions are analyzed for 1422semantic correctness whether or not assertions are enabled, so turning 1423assertions on and off cannot affect the legality of a program. 1424 1425Note that the implementation defined policy @code{DISABLE}, given in a 1426pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. 1427 1428Note: this is a standard language-defined pragma in versions 1429of Ada from 2005 on. In GNAT, it is implemented in all versions 1430of Ada, and the DISABLE policy is an implementation-defined 1431addition. 1432 1433@node Pragma Assert_And_Cut 1434@unnumberedsec Pragma Assert_And_Cut 1435@findex Assert_And_Cut 1436@noindent 1437Syntax: 1438@smallexample @c ada 1439pragma Assert_And_Cut ( 1440 boolean_EXPRESSION 1441 [, string_EXPRESSION]); 1442@end smallexample 1443 1444@noindent 1445The effect of this pragma is identical to that of pragma @code{Assert}, 1446except that in an @code{Assertion_Policy} pragma, the identifier 1447@code{Assert_And_Cut} is used to control whether it is ignored or checked 1448(or disabled). 1449 1450The intention is that this be used within a subprogram when the 1451given test expresion sums up all the work done so far in the 1452subprogram, so that the rest of the subprogram can be verified 1453(informally or formally) using only the entry preconditions, 1454and the expression in this pragma. This allows dividing up 1455a subprogram into sections for the purposes of testing or 1456formal verification. The pragma also serves as useful 1457documentation. 1458 1459@node Pragma Assertion_Policy 1460@unnumberedsec Pragma Assertion_Policy 1461@findex Assertion_Policy 1462@noindent 1463Syntax: 1464@smallexample @c ada 1465pragma Assertion_Policy (CHECK | DISABLE | IGNORE); 1466 1467pragma Assertion_Policy ( 1468 ASSERTION_KIND => POLICY_IDENTIFIER 1469 @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); 1470 1471ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 1472 1473RM_ASSERTION_KIND ::= Assert | 1474 Static_Predicate | 1475 Dynamic_Predicate | 1476 Pre | 1477 Pre'Class | 1478 Post | 1479 Post'Class | 1480 Type_Invariant | 1481 Type_Invariant'Class 1482 1483ID_ASSERTION_KIND ::= Assertions | 1484 Assert_And_Cut | 1485 Assume | 1486 Contract_Cases | 1487 Debug | 1488 Invariant | 1489 Invariant'Class | 1490 Loop_Invariant | 1491 Loop_Variant | 1492 Postcondition | 1493 Precondition | 1494 Predicate | 1495 Refined_Post | 1496 Statement_Assertions 1497 1498POLICY_IDENTIFIER ::= Check | Disable | Ignore 1499@end smallexample 1500 1501@noindent 1502This is a standard Ada 2012 pragma that is available as an 1503implementation-defined pragma in earlier versions of Ada. 1504The assertion kinds @code{RM_ASSERTION_KIND} are those defined in 1505the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} 1506are implementation defined additions recognized by the GNAT compiler. 1507 1508The pragma applies in both cases to pragmas and aspects with matching 1509names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} 1510applies to both the @code{Precondition} pragma 1511and the aspect @code{Precondition}. Note that the identifiers for 1512pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not 1513Pre_Class and Post_Class), since these pragmas are intended to be 1514identical to the corresponding aspects). 1515 1516If the policy is @code{CHECK}, then assertions are enabled, i.e. 1517the corresponding pragma or aspect is activated. 1518If the policy is @code{IGNORE}, then assertions are ignored, i.e. 1519the corresponding pragma or aspect is deactivated. 1520This pragma overrides the effect of the @option{-gnata} switch on the 1521command line. 1522 1523The implementation defined policy @code{DISABLE} is like 1524@code{IGNORE} except that it completely disables semantic 1525checking of the corresponding pragma or aspect. This is 1526useful when the pragma or aspect argument references subprograms 1527in a with'ed package which is replaced by a dummy package 1528for the final build. 1529 1530The implementation defined policy @code{Assertions} applies to all 1531assertion kinds. The form with no assertion kind given implies this 1532choice, so it applies to all assertion kinds (RM defined, and 1533implementation defined). 1534 1535The implementation defined policy @code{Statement_Assertions} 1536applies to @code{Assert}, @code{Assert_And_Cut}, 1537@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. 1538 1539@node Pragma Assume 1540@unnumberedsec Pragma Assume 1541@findex Assume 1542@noindent 1543Syntax: 1544@smallexample @c ada 1545pragma Assume ( 1546 boolean_EXPRESSION 1547 [, string_EXPRESSION]); 1548@end smallexample 1549 1550@noindent 1551The effect of this pragma is identical to that of pragma @code{Assert}, 1552except that in an @code{Assertion_Policy} pragma, the identifier 1553@code{Assume} is used to control whether it is ignored or checked 1554(or disabled). 1555 1556The intention is that this be used for assumptions about the 1557external environment. So you cannot expect to verify formally 1558or informally that the condition is met, this must be 1559established by examining things outside the program itself. 1560For example, we may have code that depends on the size of 1561@code{Long_Long_Integer} being at least 64. So we could write: 1562 1563@smallexample @c ada 1564pragma Assume (Long_Long_Integer'Size >= 64); 1565@end smallexample 1566 1567@noindent 1568This assumption cannot be proved from the program itself, 1569but it acts as a useful run-time check that the assumption 1570is met, and documents the need to ensure that it is met by 1571reference to information outside the program. 1572 1573@node Pragma Assume_No_Invalid_Values 1574@unnumberedsec Pragma Assume_No_Invalid_Values 1575@findex Assume_No_Invalid_Values 1576@cindex Invalid representations 1577@cindex Invalid values 1578@noindent 1579Syntax: 1580@smallexample @c ada 1581pragma Assume_No_Invalid_Values (On | Off); 1582@end smallexample 1583 1584@noindent 1585This is a configuration pragma that controls the assumptions made by the 1586compiler about the occurrence of invalid representations (invalid values) 1587in the code. 1588 1589The default behavior (corresponding to an Off argument for this pragma), is 1590to assume that values may in general be invalid unless the compiler can 1591prove they are valid. Consider the following example: 1592 1593@smallexample @c ada 1594V1 : Integer range 1 .. 10; 1595V2 : Integer range 11 .. 20; 1596... 1597for J in V2 .. V1 loop 1598 ... 1599end loop; 1600@end smallexample 1601 1602@noindent 1603if V1 and V2 have valid values, then the loop is known at compile 1604time not to execute since the lower bound must be greater than the 1605upper bound. However in default mode, no such assumption is made, 1606and the loop may execute. If @code{Assume_No_Invalid_Values (On)} 1607is given, the compiler will assume that any occurrence of a variable 1608other than in an explicit @code{'Valid} test always has a valid 1609value, and the loop above will be optimized away. 1610 1611The use of @code{Assume_No_Invalid_Values (On)} is appropriate if 1612you know your code is free of uninitialized variables and other 1613possible sources of invalid representations, and may result in 1614more efficient code. A program that accesses an invalid representation 1615with this pragma in effect is erroneous, so no guarantees can be made 1616about its behavior. 1617 1618It is peculiar though permissible to use this pragma in conjunction 1619with validity checking (-gnatVa). In such cases, accessing invalid 1620values will generally give an exception, though formally the program 1621is erroneous so there are no guarantees that this will always be the 1622case, and it is recommended that these two options not be used together. 1623 1624@node Pragma Ast_Entry 1625@unnumberedsec Pragma Ast_Entry 1626@cindex OpenVMS 1627@findex Ast_Entry 1628@noindent 1629Syntax: 1630@smallexample @c ada 1631pragma AST_Entry (entry_IDENTIFIER); 1632@end smallexample 1633 1634@noindent 1635This pragma is implemented only in the OpenVMS implementation of GNAT@. The 1636argument is the simple name of a single entry; at most one @code{AST_Entry} 1637pragma is allowed for any given entry. This pragma must be used in 1638conjunction with the @code{AST_Entry} attribute, and is only allowed after 1639the entry declaration and in the same task type specification or single task 1640as the entry to which it applies. This pragma specifies that the given entry 1641may be used to handle an OpenVMS asynchronous system trap (@code{AST}) 1642resulting from an OpenVMS system service call. The pragma does not affect 1643normal use of the entry. For further details on this pragma, see the 1644DEC Ada Language Reference Manual, section 9.12a. 1645 1646@node Pragma Attribute_Definition 1647@unnumberedsec Pragma Attribute_Definition 1648@findex Attribute_Definition 1649@noindent 1650Syntax: 1651@smallexample @c ada 1652pragma Attribute_Definition 1653 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 1654 [Entity =>] LOCAL_NAME, 1655 [Expression =>] EXPRESSION | NAME); 1656@end smallexample 1657 1658@noindent 1659If @code{Attribute} is a known attribute name, this pragma is equivalent to 1660the attribute definition clause: 1661 1662@smallexample @c ada 1663 for Entity'Attribute use Expression; 1664@end smallexample 1665 1666If @code{Attribute} is not a recognized attribute name, the pragma is 1667ignored, and a warning is emitted. This allows source 1668code to be written that takes advantage of some new attribute, while remaining 1669compilable with earlier compilers. 1670 1671@node Pragma C_Pass_By_Copy 1672@unnumberedsec Pragma C_Pass_By_Copy 1673@cindex Passing by copy 1674@findex C_Pass_By_Copy 1675@noindent 1676Syntax: 1677@smallexample @c ada 1678pragma C_Pass_By_Copy 1679 ([Max_Size =>] static_integer_EXPRESSION); 1680@end smallexample 1681 1682@noindent 1683Normally the default mechanism for passing C convention records to C 1684convention subprograms is to pass them by reference, as suggested by RM 1685B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change 1686this default, by requiring that record formal parameters be passed by 1687copy if all of the following conditions are met: 1688 1689@itemize @bullet 1690@item 1691The size of the record type does not exceed the value specified for 1692@code{Max_Size}. 1693@item 1694The record type has @code{Convention C}. 1695@item 1696The formal parameter has this record type, and the subprogram has a 1697foreign (non-Ada) convention. 1698@end itemize 1699 1700@noindent 1701If these conditions are met the argument is passed by copy, i.e.@: in a 1702manner consistent with what C expects if the corresponding formal in the 1703C prototype is a struct (rather than a pointer to a struct). 1704 1705You can also pass records by copy by specifying the convention 1706@code{C_Pass_By_Copy} for the record type, or by using the extended 1707@code{Import} and @code{Export} pragmas, which allow specification of 1708passing mechanisms on a parameter by parameter basis. 1709 1710@node Pragma Check 1711@unnumberedsec Pragma Check 1712@cindex Assertions 1713@cindex Named assertions 1714@findex Check 1715@noindent 1716Syntax: 1717@smallexample @c ada 1718pragma Check ( 1719 [Name =>] CHECK_KIND, 1720 [Check =>] Boolean_EXPRESSION 1721 [, [Message =>] string_EXPRESSION] ); 1722 1723CHECK_KIND ::= IDENTIFIER | 1724 Pre'Class | 1725 Post'Class | 1726 Type_Invariant'Class | 1727 Invariant'Class 1728@end smallexample 1729 1730@noindent 1731This pragma is similar to the predefined pragma @code{Assert} except that an 1732extra identifier argument is present. In conjunction with pragma 1733@code{Check_Policy}, this can be used to define groups of assertions that can 1734be independently controlled. The identifier @code{Assertion} is special, it 1735refers to the normal set of pragma @code{Assert} statements. 1736 1737Checks introduced by this pragma are normally deactivated by default. They can 1738be activated either by the command line option @option{-gnata}, which turns on 1739all checks, or individually controlled using pragma @code{Check_Policy}. 1740 1741The identifiers @code{Assertions} and @code{Statement_Assertions} are not 1742permitted as check kinds, since this would cause confusion with the use 1743of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} 1744pragmas, where they are used to refer to sets of assertions. 1745 1746@node Pragma Check_Float_Overflow 1747@unnumberedsec Pragma Check_Float_Overflow 1748@cindex Floating-point overflow 1749@findex Check_Float_Overflow 1750@noindent 1751Syntax: 1752@smallexample @c ada 1753pragma Check_Float_Overflow; 1754@end smallexample 1755 1756@noindent 1757In Ada, the predefined floating-point types (@code{Short_Float}, 1758@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are 1759defined to be @emph{unconstrained}. This means that even though each 1760has a well-defined base range, an operation that delivers a result 1761outside this base range is not required to raise an exception. 1762This implementation permission accommodates the notion 1763of infinities in IEEE floating-point, and corresponds to the 1764efficient execution mode on most machines. GNAT will not raise 1765overflow exceptions on these machines; instead it will generate 1766infinities and NaN's as defined in the IEEE standard. 1767 1768Generating infinities, although efficient, is not always desirable. 1769Often the preferable approach is to check for overflow, even at the 1770(perhaps considerable) expense of run-time performance. 1771This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit 1772range constraints -- and indeed such a subtype 1773can have the same base range as its base type. For example: 1774 1775@smallexample @c ada 1776subtype My_Float is Float range Float'Range; 1777@end smallexample 1778 1779@noindent 1780Here @code{My_Float} has the same range as 1781@code{Float} but is constrained, so operations on 1782@code{My_Float} values will be checked for overflow 1783against this range. 1784 1785This style will achieve the desired goal, but 1786it is often more convenient to be able to simply use 1787the standard predefined floating-point types as long 1788as overflow checking could be guaranteed. 1789The @code{Check_Float_Overflow} 1790configuration pragma achieves this effect. If a unit is compiled 1791subject to this configuration pragma, then all operations 1792on predefined floating-point types will be treated as 1793though those types were constrained, and overflow checks 1794will be generated. The @code{Constraint_Error} 1795exception is raised if the result is out of range. 1796 1797This mode can also be set by use of the compiler 1798switch @option{-gnateF}. 1799 1800@node Pragma Check_Name 1801@unnumberedsec Pragma Check_Name 1802@cindex Defining check names 1803@cindex Check names, defining 1804@findex Check_Name 1805@noindent 1806Syntax: 1807@smallexample @c ada 1808pragma Check_Name (check_name_IDENTIFIER); 1809@end smallexample 1810 1811@noindent 1812This is a configuration pragma that defines a new implementation 1813defined check name (unless IDENTIFIER matches one of the predefined 1814check names, in which case the pragma has no effect). Check names 1815are global to a partition, so if two or more configuration pragmas 1816are present in a partition mentioning the same name, only one new 1817check name is introduced. 1818 1819An implementation defined check name introduced with this pragma may 1820be used in only three contexts: @code{pragma Suppress}, 1821@code{pragma Unsuppress}, 1822and as the prefix of a @code{Check_Name'Enabled} attribute reference. For 1823any of these three cases, the check name must be visible. A check 1824name is visible if it is in the configuration pragmas applying to 1825the current unit, or if it appears at the start of any unit that 1826is part of the dependency set of the current unit (e.g., units that 1827are mentioned in @code{with} clauses). 1828 1829Check names introduced by this pragma are subject to control by compiler 1830switches (in particular -gnatp) in the usual manner. 1831 1832@node Pragma Check_Policy 1833@unnumberedsec Pragma Check_Policy 1834@cindex Controlling assertions 1835@cindex Assertions, control 1836@cindex Check pragma control 1837@cindex Named assertions 1838@findex Check 1839@noindent 1840Syntax: 1841@smallexample @c ada 1842pragma Check_Policy 1843 ([Name =>] CHECK_KIND, 1844 [Policy =>] POLICY_IDENTIFIER); 1845 1846pragma Check_Policy ( 1847 CHECK_KIND => POLICY_IDENTIFIER 1848 @{, CHECK_KIND => POLICY_IDENTIFIER@}); 1849 1850ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND 1851 1852CHECK_KIND ::= IDENTIFIER | 1853 Pre'Class | 1854 Post'Class | 1855 Type_Invariant'Class | 1856 Invariant'Class 1857 1858The identifiers Name and Policy are not allowed as CHECK_KIND values. This 1859avoids confusion between the two possible syntax forms for this pragma. 1860 1861POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 1862@end smallexample 1863 1864@noindent 1865This pragma is used to set the checking policy for assertions (specified 1866by aspects or pragmas), the @code{Debug} pragma, or additional checks 1867to be checked using the @code{Check} pragma. It may appear either as 1868a configuration pragma, or within a declarative part of package. In the 1869latter case, it applies from the point where it appears to the end of 1870the declarative region (like pragma @code{Suppress}). 1871 1872The @code{Check_Policy} pragma is similar to the 1873predefined @code{Assertion_Policy} pragma, 1874and if the check kind corresponds to one of the assertion kinds that 1875are allowed by @code{Assertion_Policy}, then the effect is identical. 1876 1877If the first argument is Debug, then the policy applies to Debug pragmas, 1878disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or 1879@code{IGNORE}, and allowing them to execute with normal semantics if 1880the policy is @code{ON} or @code{CHECK}. In addition if the policy is 1881@code{DISABLE}, then the procedure call in @code{Debug} pragmas will 1882be totally ignored and not analyzed semantically. 1883 1884Finally the first argument may be some other identifier than the above 1885possibilities, in which case it controls a set of named assertions 1886that can be checked using pragma @code{Check}. For example, if the pragma: 1887 1888@smallexample @c ada 1889pragma Check_Policy (Critical_Error, OFF); 1890@end smallexample 1891 1892@noindent 1893is given, then subsequent @code{Check} pragmas whose first argument is also 1894@code{Critical_Error} will be disabled. 1895 1896The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} 1897to turn on corresponding checks. The default for a set of checks for which no 1898@code{Check_Policy} is given is @code{OFF} unless the compiler switch 1899@option{-gnata} is given, which turns on all checks by default. 1900 1901The check policy settings @code{CHECK} and @code{IGNORE} are recognized 1902as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for 1903compatibility with the standard @code{Assertion_Policy} pragma. The check 1904policy setting @code{DISABLE} causes the second argument of a corresponding 1905@code{Check} pragma to be completely ignored and not analyzed. 1906 1907@node Pragma CIL_Constructor 1908@unnumberedsec Pragma CIL_Constructor 1909@findex CIL_Constructor 1910@noindent 1911Syntax: 1912 1913@smallexample @c ada 1914pragma CIL_Constructor ([Entity =>] function_LOCAL_NAME); 1915@end smallexample 1916 1917@noindent 1918This pragma is used to assert that the specified Ada function should be 1919mapped to the .NET constructor for some Ada tagged record type. 1920 1921See section 4.1 of the 1922@code{GNAT User's Guide: Supplement for the .NET Platform.} 1923for related information. 1924 1925@node Pragma Comment 1926@unnumberedsec Pragma Comment 1927@findex Comment 1928@noindent 1929Syntax: 1930 1931@smallexample @c ada 1932pragma Comment (static_string_EXPRESSION); 1933@end smallexample 1934 1935@noindent 1936This is almost identical in effect to pragma @code{Ident}. It allows the 1937placement of a comment into the object file and hence into the 1938executable file if the operating system permits such usage. The 1939difference is that @code{Comment}, unlike @code{Ident}, has 1940no limitations on placement of the pragma (it can be placed 1941anywhere in the main source unit), and if more than one pragma 1942is used, all comments are retained. 1943 1944@node Pragma Common_Object 1945@unnumberedsec Pragma Common_Object 1946@findex Common_Object 1947@noindent 1948Syntax: 1949 1950@smallexample @c ada 1951pragma Common_Object ( 1952 [Internal =>] LOCAL_NAME 1953 [, [External =>] EXTERNAL_SYMBOL] 1954 [, [Size =>] EXTERNAL_SYMBOL] ); 1955 1956EXTERNAL_SYMBOL ::= 1957 IDENTIFIER 1958| static_string_EXPRESSION 1959@end smallexample 1960 1961@noindent 1962This pragma enables the shared use of variables stored in overlaid 1963linker areas corresponding to the use of @code{COMMON} 1964in Fortran. The single 1965object @var{LOCAL_NAME} is assigned to the area designated by 1966the @var{External} argument. 1967You may define a record to correspond to a series 1968of fields. The @var{Size} argument 1969is syntax checked in GNAT, but otherwise ignored. 1970 1971@code{Common_Object} is not supported on all platforms. If no 1972support is available, then the code generator will issue a message 1973indicating that the necessary attribute for implementation of this 1974pragma is not available. 1975 1976@node Pragma Compile_Time_Error 1977@unnumberedsec Pragma Compile_Time_Error 1978@findex Compile_Time_Error 1979@noindent 1980Syntax: 1981 1982@smallexample @c ada 1983pragma Compile_Time_Error 1984 (boolean_EXPRESSION, static_string_EXPRESSION); 1985@end smallexample 1986 1987@noindent 1988This pragma can be used to generate additional compile time 1989error messages. It 1990is particularly useful in generics, where errors can be issued for 1991specific problematic instantiations. The first parameter is a boolean 1992expression. The pragma is effective only if the value of this expression 1993is known at compile time, and has the value True. The set of expressions 1994whose values are known at compile time includes all static boolean 1995expressions, and also other values which the compiler can determine 1996at compile time (e.g., the size of a record type set by an explicit 1997size representation clause, or the value of a variable which was 1998initialized to a constant and is known not to have been modified). 1999If these conditions are met, an error message is generated using 2000the value given as the second argument. This string value may contain 2001embedded ASCII.LF characters to break the message into multiple lines. 2002 2003@node Pragma Compile_Time_Warning 2004@unnumberedsec Pragma Compile_Time_Warning 2005@findex Compile_Time_Warning 2006@noindent 2007Syntax: 2008 2009@smallexample @c ada 2010pragma Compile_Time_Warning 2011 (boolean_EXPRESSION, static_string_EXPRESSION); 2012@end smallexample 2013 2014@noindent 2015Same as pragma Compile_Time_Error, except a warning is issued instead 2016of an error message. Note that if this pragma is used in a package that 2017is with'ed by a client, the client will get the warning even though it 2018is issued by a with'ed package (normally warnings in with'ed units are 2019suppressed, but this is a special exception to that rule). 2020 2021One typical use is within a generic where compile time known characteristics 2022of formal parameters are tested, and warnings given appropriately. Another use 2023with a first parameter of True is to warn a client about use of a package, 2024for example that it is not fully implemented. 2025 2026@node Pragma Compiler_Unit 2027@unnumberedsec Pragma Compiler_Unit 2028@findex Compiler_Unit 2029@noindent 2030Syntax: 2031 2032@smallexample @c ada 2033pragma Compiler_Unit; 2034@end smallexample 2035 2036@noindent 2037This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is 2038retained so that old versions of the GNAT run-time that use this pragma can 2039be compiled with newer versions of the compiler. 2040 2041@node Pragma Compiler_Unit_Warning 2042@unnumberedsec Pragma Compiler_Unit_Warning 2043@findex Compiler_Unit_Warning 2044@noindent 2045Syntax: 2046 2047@smallexample @c ada 2048pragma Compiler_Unit_Warning; 2049@end smallexample 2050 2051@noindent 2052This pragma is intended only for internal use in the GNAT run-time library. 2053It indicates that the unit is used as part of the compiler build. The effect 2054is to generate warnings for the use of constructs (for example, conditional 2055expressions) that would cause trouble when bootstrapping using an older 2056version of GNAT. For the exact list of restrictions, see the compiler sources 2057and references to Check_Compiler_Unit. 2058 2059@node Pragma Complete_Representation 2060@unnumberedsec Pragma Complete_Representation 2061@findex Complete_Representation 2062@noindent 2063Syntax: 2064 2065@smallexample @c ada 2066pragma Complete_Representation; 2067@end smallexample 2068 2069@noindent 2070This pragma must appear immediately within a record representation 2071clause. Typical placements are before the first component clause 2072or after the last component clause. The effect is to give an error 2073message if any component is missing a component clause. This pragma 2074may be used to ensure that a record representation clause is 2075complete, and that this invariant is maintained if fields are 2076added to the record in the future. 2077 2078@node Pragma Complex_Representation 2079@unnumberedsec Pragma Complex_Representation 2080@findex Complex_Representation 2081@noindent 2082Syntax: 2083 2084@smallexample @c ada 2085pragma Complex_Representation 2086 ([Entity =>] LOCAL_NAME); 2087@end smallexample 2088 2089@noindent 2090The @var{Entity} argument must be the name of a record type which has 2091two fields of the same floating-point type. The effect of this pragma is 2092to force gcc to use the special internal complex representation form for 2093this record, which may be more efficient. Note that this may result in 2094the code for this type not conforming to standard ABI (application 2095binary interface) requirements for the handling of record types. For 2096example, in some environments, there is a requirement for passing 2097records by pointer, and the use of this pragma may result in passing 2098this type in floating-point registers. 2099 2100@node Pragma Component_Alignment 2101@unnumberedsec Pragma Component_Alignment 2102@cindex Alignments of components 2103@findex Component_Alignment 2104@noindent 2105Syntax: 2106 2107@smallexample @c ada 2108pragma Component_Alignment ( 2109 [Form =>] ALIGNMENT_CHOICE 2110 [, [Name =>] type_LOCAL_NAME]); 2111 2112ALIGNMENT_CHOICE ::= 2113 Component_Size 2114| Component_Size_4 2115| Storage_Unit 2116| Default 2117@end smallexample 2118 2119@noindent 2120Specifies the alignment of components in array or record types. 2121The meaning of the @var{Form} argument is as follows: 2122 2123@table @code 2124@findex Component_Size 2125@item Component_Size 2126Aligns scalar components and subcomponents of the array or record type 2127on boundaries appropriate to their inherent size (naturally 2128aligned). For example, 1-byte components are aligned on byte boundaries, 21292-byte integer components are aligned on 2-byte boundaries, 4-byte 2130integer components are aligned on 4-byte boundaries and so on. These 2131alignment rules correspond to the normal rules for C compilers on all 2132machines except the VAX@. 2133 2134@findex Component_Size_4 2135@item Component_Size_4 2136Naturally aligns components with a size of four or fewer 2137bytes. Components that are larger than 4 bytes are placed on the next 21384-byte boundary. 2139 2140@findex Storage_Unit 2141@item Storage_Unit 2142Specifies that array or record components are byte aligned, i.e.@: 2143aligned on boundaries determined by the value of the constant 2144@code{System.Storage_Unit}. 2145 2146@cindex OpenVMS 2147@item Default 2148Specifies that array or record components are aligned on default 2149boundaries, appropriate to the underlying hardware or operating system or 2150both. For OpenVMS VAX systems, the @code{Default} choice is the same as 2151the @code{Storage_Unit} choice (byte alignment). For all other systems, 2152the @code{Default} choice is the same as @code{Component_Size} (natural 2153alignment). 2154@end table 2155 2156@noindent 2157If the @code{Name} parameter is present, @var{type_LOCAL_NAME} must 2158refer to a local record or array type, and the specified alignment 2159choice applies to the specified type. The use of 2160@code{Component_Alignment} together with a pragma @code{Pack} causes the 2161@code{Component_Alignment} pragma to be ignored. The use of 2162@code{Component_Alignment} together with a record representation clause 2163is only effective for fields not specified by the representation clause. 2164 2165If the @code{Name} parameter is absent, the pragma can be used as either 2166a configuration pragma, in which case it applies to one or more units in 2167accordance with the normal rules for configuration pragmas, or it can be 2168used within a declarative part, in which case it applies to types that 2169are declared within this declarative part, or within any nested scope 2170within this declarative part. In either case it specifies the alignment 2171to be applied to any record or array type which has otherwise standard 2172representation. 2173 2174If the alignment for a record or array type is not specified (using 2175pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep 2176clause), the GNAT uses the default alignment as described previously. 2177 2178@node Pragma Contract_Cases 2179@unnumberedsec Pragma Contract_Cases 2180@cindex Contract cases 2181@findex Contract_Cases 2182@noindent 2183Syntax: 2184 2185@smallexample @c ada 2186pragma Contract_Cases ( 2187 Condition => Consequence 2188 @{,Condition => Consequence@}); 2189@end smallexample 2190 2191@noindent 2192The @code{Contract_Cases} pragma allows defining fine-grain specifications 2193that can complement or replace the contract given by a precondition and a 2194postcondition. Additionally, the @code{Contract_Cases} pragma can be used 2195by testing and formal verification tools. The compiler checks its validity and, 2196depending on the assertion policy at the point of declaration of the pragma, 2197it may insert a check in the executable. For code generation, the contract 2198cases 2199 2200@smallexample @c ada 2201pragma Contract_Cases ( 2202 Cond1 => Pred1, 2203 Cond2 => Pred2); 2204@end smallexample 2205 2206@noindent 2207are equivalent to 2208 2209@smallexample @c ada 2210C1 : constant Boolean := Cond1; -- evaluated at subprogram entry 2211C2 : constant Boolean := Cond2; -- evaluated at subprogram entry 2212pragma Precondition ((C1 and not C2) or (C2 and not C1)); 2213pragma Postcondition (if C1 then Pred1); 2214pragma Postcondition (if C2 then Pred2); 2215@end smallexample 2216 2217@noindent 2218The precondition ensures that one and only one of the conditions is 2219satisfied on entry to the subprogram. 2220The postcondition ensures that for the condition that was True on entry, 2221the corrresponding consequence is True on exit. Other consequence expressions 2222are not evaluated. 2223 2224A precondition @code{P} and postcondition @code{Q} can also be 2225expressed as contract cases: 2226 2227@smallexample @c ada 2228pragma Contract_Cases (P => Q); 2229@end smallexample 2230 2231The placement and visibility rules for @code{Contract_Cases} pragmas are 2232identical to those described for preconditions and postconditions. 2233 2234The compiler checks that boolean expressions given in conditions and 2235consequences are valid, where the rules for conditions are the same as 2236the rule for an expression in @code{Precondition} and the rules for 2237consequences are the same as the rule for an expression in 2238@code{Postcondition}. In particular, attributes @code{'Old} and 2239@code{'Result} can only be used within consequence expressions. 2240The condition for the last contract case may be @code{others}, to denote 2241any case not captured by the previous cases. The 2242following is an example of use within a package spec: 2243 2244@smallexample @c ada 2245package Math_Functions is 2246 ... 2247 function Sqrt (Arg : Float) return Float; 2248 pragma Contract_Cases ((Arg in 0 .. 99) => Sqrt'Result < 10, 2249 Arg >= 100 => Sqrt'Result >= 10, 2250 others => Sqrt'Result = 0); 2251 ... 2252end Math_Functions; 2253@end smallexample 2254 2255@noindent 2256The meaning of contract cases is that only one case should apply at each 2257call, as determined by the corresponding condition evaluating to True, 2258and that the consequence for this case should hold when the subprogram 2259returns. 2260 2261@node Pragma Convention_Identifier 2262@unnumberedsec Pragma Convention_Identifier 2263@findex Convention_Identifier 2264@cindex Conventions, synonyms 2265@noindent 2266Syntax: 2267 2268@smallexample @c ada 2269pragma Convention_Identifier ( 2270 [Name =>] IDENTIFIER, 2271 [Convention =>] convention_IDENTIFIER); 2272@end smallexample 2273 2274@noindent 2275This pragma provides a mechanism for supplying synonyms for existing 2276convention identifiers. The @code{Name} identifier can subsequently 2277be used as a synonym for the given convention in other pragmas (including 2278for example pragma @code{Import} or another @code{Convention_Identifier} 2279pragma). As an example of the use of this, suppose you had legacy code 2280which used Fortran77 as the identifier for Fortran. Then the pragma: 2281 2282@smallexample @c ada 2283pragma Convention_Identifier (Fortran77, Fortran); 2284@end smallexample 2285 2286@noindent 2287would allow the use of the convention identifier @code{Fortran77} in 2288subsequent code, avoiding the need to modify the sources. As another 2289example, you could use this to parameterize convention requirements 2290according to systems. Suppose you needed to use @code{Stdcall} on 2291windows systems, and @code{C} on some other system, then you could 2292define a convention identifier @code{Library} and use a single 2293@code{Convention_Identifier} pragma to specify which convention 2294would be used system-wide. 2295 2296@node Pragma CPP_Class 2297@unnumberedsec Pragma CPP_Class 2298@findex CPP_Class 2299@cindex Interfacing with C++ 2300@noindent 2301Syntax: 2302 2303@smallexample @c ada 2304pragma CPP_Class ([Entity =>] LOCAL_NAME); 2305@end smallexample 2306 2307@noindent 2308The argument denotes an entity in the current declarative region that is 2309declared as a record type. It indicates that the type corresponds to an 2310externally declared C++ class type, and is to be laid out the same way 2311that C++ would lay out the type. If the C++ class has virtual primitives 2312then the record must be declared as a tagged record type. 2313 2314Types for which @code{CPP_Class} is specified do not have assignment or 2315equality operators defined (such operations can be imported or declared 2316as subprograms as required). Initialization is allowed only by constructor 2317functions (see pragma @code{CPP_Constructor}). Such types are implicitly 2318limited if not explicitly declared as limited or derived from a limited 2319type, and an error is issued in that case. 2320 2321See @ref{Interfacing to C++} for related information. 2322 2323Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 2324for backward compatibility but its functionality is available 2325using pragma @code{Import} with @code{Convention} = @code{CPP}. 2326 2327@node Pragma CPP_Constructor 2328@unnumberedsec Pragma CPP_Constructor 2329@cindex Interfacing with C++ 2330@findex CPP_Constructor 2331@noindent 2332Syntax: 2333 2334@smallexample @c ada 2335pragma CPP_Constructor ([Entity =>] LOCAL_NAME 2336 [, [External_Name =>] static_string_EXPRESSION ] 2337 [, [Link_Name =>] static_string_EXPRESSION ]); 2338@end smallexample 2339 2340@noindent 2341This pragma identifies an imported function (imported in the usual way 2342with pragma @code{Import}) as corresponding to a C++ constructor. If 2343@code{External_Name} and @code{Link_Name} are not specified then the 2344@code{Entity} argument is a name that must have been previously mentioned 2345in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name 2346must be of one of the following forms: 2347 2348@itemize @bullet 2349@item 2350@code{function @var{Fname} return @var{T}} 2351 2352@itemize @bullet 2353@item 2354@code{function @var{Fname} return @var{T}'Class} 2355 2356@item 2357@code{function @var{Fname} (@dots{}) return @var{T}} 2358@end itemize 2359 2360@item 2361@code{function @var{Fname} (@dots{}) return @var{T}'Class} 2362@end itemize 2363 2364@noindent 2365where @var{T} is a limited record type imported from C++ with pragma 2366@code{Import} and @code{Convention} = @code{CPP}. 2367 2368The first two forms import the default constructor, used when an object 2369of type @var{T} is created on the Ada side with no explicit constructor. 2370The latter two forms cover all the non-default constructors of the type. 2371See the @value{EDITION} User's Guide for details. 2372 2373If no constructors are imported, it is impossible to create any objects 2374on the Ada side and the type is implicitly declared abstract. 2375 2376Pragma @code{CPP_Constructor} is intended primarily for automatic generation 2377using an automatic binding generator tool (such as the @code{-fdump-ada-spec} 2378GCC switch). 2379See @ref{Interfacing to C++} for more related information. 2380 2381Note: The use of functions returning class-wide types for constructors is 2382currently obsolete. They are supported for backward compatibility. The 2383use of functions returning the type T leave the Ada sources more clear 2384because the imported C++ constructors always return an object of type T; 2385that is, they never return an object whose type is a descendant of type T. 2386 2387@node Pragma CPP_Virtual 2388@unnumberedsec Pragma CPP_Virtual 2389@cindex Interfacing to C++ 2390@findex CPP_Virtual 2391@noindent 2392This pragma is now obsolete and, other than generating a warning if warnings 2393on obsolescent features are enabled, is completely ignored. 2394It is retained for compatibility 2395purposes. It used to be required to ensure compoatibility with C++, but 2396is no longer required for that purpose because GNAT generates 2397the same object layout as the G++ compiler by default. 2398 2399See @ref{Interfacing to C++} for related information. 2400 2401@node Pragma CPP_Vtable 2402@unnumberedsec Pragma CPP_Vtable 2403@cindex Interfacing with C++ 2404@findex CPP_Vtable 2405@noindent 2406This pragma is now obsolete and, other than generating a warning if warnings 2407on obsolescent features are enabled, is completely ignored. 2408It used to be required to ensure compatibility with C++, but 2409is no longer required for that purpose because GNAT generates 2410the same object layout than the G++ compiler by default. 2411 2412See @ref{Interfacing to C++} for related information. 2413 2414@node Pragma CPU 2415@unnumberedsec Pragma CPU 2416@findex CPU 2417@noindent 2418Syntax: 2419 2420@smallexample @c ada 2421pragma CPU (EXPRESSION); 2422@end smallexample 2423 2424@noindent 2425This pragma is standard in Ada 2012, but is available in all earlier 2426versions of Ada as an implementation-defined pragma. 2427See Ada 2012 Reference Manual for details. 2428 2429@node Pragma Debug 2430@unnumberedsec Pragma Debug 2431@findex Debug 2432@noindent 2433Syntax: 2434 2435@smallexample @c ada 2436pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 2437 2438PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 2439 PROCEDURE_NAME 2440| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 2441@end smallexample 2442 2443@noindent 2444The procedure call argument has the syntactic form of an expression, meeting 2445the syntactic requirements for pragmas. 2446 2447If debug pragmas are not enabled or if the condition is present and evaluates 2448to False, this pragma has no effect. If debug pragmas are enabled, the 2449semantics of the pragma is exactly equivalent to the procedure call statement 2450corresponding to the argument with a terminating semicolon. Pragmas are 2451permitted in sequences of declarations, so you can use pragma @code{Debug} to 2452intersperse calls to debug procedures in the middle of declarations. Debug 2453pragmas can be enabled either by use of the command line switch @option{-gnata} 2454or by use of the pragma @code{Check_Policy} with a first argument of 2455@code{Debug}. 2456 2457@node Pragma Debug_Policy 2458@unnumberedsec Pragma Debug_Policy 2459@findex Debug_Policy 2460@noindent 2461Syntax: 2462 2463@smallexample @c ada 2464pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); 2465@end smallexample 2466 2467@noindent 2468This pragma is equivalent to a corresponding @code{Check_Policy} pragma 2469with a first argument of @code{Debug}. It is retained for historical 2470compatibility reasons. 2471 2472@node Pragma Default_Storage_Pool 2473@unnumberedsec Pragma Default_Storage_Pool 2474@findex Default_Storage_Pool 2475@noindent 2476Syntax: 2477 2478@smallexample @c ada 2479pragma Default_Storage_Pool (storage_pool_NAME | null); 2480@end smallexample 2481 2482@noindent 2483This pragma is standard in Ada 2012, but is available in all earlier 2484versions of Ada as an implementation-defined pragma. 2485See Ada 2012 Reference Manual for details. 2486 2487@node Pragma Depends 2488@unnumberedsec Pragma Depends 2489@findex Depends 2490@noindent 2491For the description of this pragma, see SPARK 2014 Reference Manual, 2492section 6.1.5. 2493 2494@node Pragma Detect_Blocking 2495@unnumberedsec Pragma Detect_Blocking 2496@findex Detect_Blocking 2497@noindent 2498Syntax: 2499 2500@smallexample @c ada 2501pragma Detect_Blocking; 2502@end smallexample 2503 2504@noindent 2505This is a standard pragma in Ada 2005, that is available in all earlier 2506versions of Ada as an implementation-defined pragma. 2507 2508This is a configuration pragma that forces the detection of potentially 2509blocking operations within a protected operation, and to raise Program_Error 2510if that happens. 2511 2512@node Pragma Disable_Atomic_Synchronization 2513@unnumberedsec Pragma Disable_Atomic_Synchronization 2514@cindex Atomic Synchronization 2515@findex Disable_Atomic_Synchronization 2516@noindent 2517Syntax: 2518 2519@smallexample @c ada 2520pragma Disable_Atomic_Synchronization [(Entity)]; 2521@end smallexample 2522 2523@noindent 2524Ada requires that accesses (reads or writes) of an atomic variable be 2525regarded as synchronization points in the case of multiple tasks. 2526Particularly in the case of multi-processors this may require special 2527handling, e.g. the generation of memory barriers. This capability may 2528be turned off using this pragma in cases where it is known not to be 2529required. 2530 2531The placement and scope rules for this pragma are the same as those 2532for @code{pragma Suppress}. In particular it can be used as a 2533configuration pragma, or in a declaration sequence where it applies 2534till the end of the scope. If an @code{Entity} argument is present, 2535the action applies only to that entity. 2536 2537@node Pragma Dispatching_Domain 2538@unnumberedsec Pragma Dispatching_Domain 2539@findex Dispatching_Domain 2540@noindent 2541Syntax: 2542 2543@smallexample @c ada 2544pragma Dispatching_Domain (EXPRESSION); 2545@end smallexample 2546 2547@noindent 2548This pragma is standard in Ada 2012, but is available in all earlier 2549versions of Ada as an implementation-defined pragma. 2550See Ada 2012 Reference Manual for details. 2551 2552@node Pragma Elaboration_Checks 2553@unnumberedsec Pragma Elaboration_Checks 2554@cindex Elaboration control 2555@findex Elaboration_Checks 2556@noindent 2557Syntax: 2558 2559@smallexample @c ada 2560pragma Elaboration_Checks (Dynamic | Static); 2561@end smallexample 2562 2563@noindent 2564This is a configuration pragma that provides control over the 2565elaboration model used by the compilation affected by the 2566pragma. If the parameter is @code{Dynamic}, 2567then the dynamic elaboration 2568model described in the Ada Reference Manual is used, as though 2569the @option{-gnatE} switch had been specified on the command 2570line. If the parameter is @code{Static}, then the default GNAT static 2571model is used. This configuration pragma overrides the setting 2572of the command line. For full details on the elaboration models 2573used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,, 2574gnat_ugn, @value{EDITION} User's Guide}. 2575 2576@node Pragma Eliminate 2577@unnumberedsec Pragma Eliminate 2578@cindex Elimination of unused subprograms 2579@findex Eliminate 2580@noindent 2581Syntax: 2582 2583@smallexample @c ada 2584pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR, 2585 [Source_Location =>] STRING_LITERAL); 2586@end smallexample 2587 2588@noindent 2589The string literal given for the source location is a string which 2590specifies the line number of the occurrence of the entity, using 2591the syntax for SOURCE_TRACE given below: 2592 2593@smallexample @c ada 2594 SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET] 2595 2596 LBRACKET ::= [ 2597 RBRACKET ::= ] 2598 2599 SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 2600 2601 LINE_NUMBER ::= DIGIT @{DIGIT@} 2602@end smallexample 2603 2604@noindent 2605Spaces around the colon in a @code{Source_Reference} are optional. 2606 2607The @code{DEFINING_DESIGNATOR} matches the defining designator used in an 2608explicit subprogram declaration, where the @code{entity} name in this 2609designator appears on the source line specified by the source location. 2610 2611The source trace that is given as the @code{Source_Location} shall obey the 2612following rules. The @code{FILE_NAME} is the short name (with no directory 2613information) of an Ada source file, given using exactly the required syntax 2614for the underlying file system (e.g. case is important if the underlying 2615operating system is case sensitive). @code{LINE_NUMBER} gives the line 2616number of the occurrence of the @code{entity} 2617as a decimal literal without an exponent or point. If an @code{entity} is not 2618declared in a generic instantiation (this includes generic subprogram 2619instances), the source trace includes only one source reference. If an entity 2620is declared inside a generic instantiation, its source trace (when parsing 2621from left to right) starts with the source location of the declaration of the 2622entity in the generic unit and ends with the source location of the 2623instantiation (it is given in square brackets). This approach is recursively 2624used in case of nested instantiations: the rightmost (nested most deeply in 2625square brackets) element of the source trace is the location of the outermost 2626instantiation, the next to left element is the location of the next (first 2627nested) instantiation in the code of the corresponding generic unit, and so 2628on, and the leftmost element (that is out of any square brackets) is the 2629location of the declaration of the entity to eliminate in a generic unit. 2630 2631Note that the @code{Source_Location} argument specifies which of a set of 2632similarly named entities is being eliminated, dealing both with overloading, 2633and also appearance of the same entity name in different scopes. 2634 2635This pragma indicates that the given entity is not used in the program to be 2636compiled and built. The effect of the pragma is to allow the compiler to 2637eliminate the code or data associated with the named entity. Any reference to 2638an eliminated entity causes a compile-time or link-time error. 2639 2640The intention of pragma @code{Eliminate} is to allow a program to be compiled 2641in a system-independent manner, with unused entities eliminated, without 2642needing to modify the source text. Normally the required set of 2643@code{Eliminate} pragmas is constructed automatically using the gnatelim tool. 2644 2645Any source file change that removes, splits, or 2646adds lines may make the set of Eliminate pragmas invalid because their 2647@code{Source_Location} argument values may get out of date. 2648 2649Pragma @code{Eliminate} may be used where the referenced entity is a dispatching 2650operation. In this case all the subprograms to which the given operation can 2651dispatch are considered to be unused (are never called as a result of a direct 2652or a dispatching call). 2653 2654@node Pragma Enable_Atomic_Synchronization 2655@unnumberedsec Pragma Enable_Atomic_Synchronization 2656@cindex Atomic Synchronization 2657@findex Enable_Atomic_Synchronization 2658@noindent 2659Syntax: 2660 2661@smallexample @c ada 2662pragma Enable_Atomic_Synchronization [(Entity)]; 2663@end smallexample 2664 2665@noindent 2666Ada requires that accesses (reads or writes) of an atomic variable be 2667regarded as synchronization points in the case of multiple tasks. 2668Particularly in the case of multi-processors this may require special 2669handling, e.g. the generation of memory barriers. This synchronization 2670is performed by default, but can be turned off using 2671@code{pragma Disable_Atomic_Synchronization}. The 2672@code{Enable_Atomic_Synchronization} pragma can be used to turn 2673it back on. 2674 2675The placement and scope rules for this pragma are the same as those 2676for @code{pragma Unsuppress}. In particular it can be used as a 2677configuration pragma, or in a declaration sequence where it applies 2678till the end of the scope. If an @code{Entity} argument is present, 2679the action applies only to that entity. 2680 2681@node Pragma Export_Exception 2682@unnumberedsec Pragma Export_Exception 2683@cindex OpenVMS 2684@findex Export_Exception 2685@noindent 2686Syntax: 2687 2688@smallexample @c ada 2689pragma Export_Exception ( 2690 [Internal =>] LOCAL_NAME 2691 [, [External =>] EXTERNAL_SYMBOL] 2692 [, [Form =>] Ada | VMS] 2693 [, [Code =>] static_integer_EXPRESSION]); 2694 2695EXTERNAL_SYMBOL ::= 2696 IDENTIFIER 2697| static_string_EXPRESSION 2698@end smallexample 2699 2700@noindent 2701This pragma is implemented only in the OpenVMS implementation of GNAT@. It 2702causes the specified exception to be propagated outside of the Ada program, 2703so that it can be handled by programs written in other OpenVMS languages. 2704This pragma establishes an external name for an Ada exception and makes the 2705name available to the OpenVMS Linker as a global symbol. For further details 2706on this pragma, see the 2707DEC Ada Language Reference Manual, section 13.9a3.2. 2708 2709@node Pragma Export_Function 2710@unnumberedsec Pragma Export_Function 2711@cindex Argument passing mechanisms 2712@findex Export_Function 2713 2714@noindent 2715Syntax: 2716 2717@smallexample @c ada 2718pragma Export_Function ( 2719 [Internal =>] LOCAL_NAME 2720 [, [External =>] EXTERNAL_SYMBOL] 2721 [, [Parameter_Types =>] PARAMETER_TYPES] 2722 [, [Result_Type =>] result_SUBTYPE_MARK] 2723 [, [Mechanism =>] MECHANISM] 2724 [, [Result_Mechanism =>] MECHANISM_NAME]); 2725 2726EXTERNAL_SYMBOL ::= 2727 IDENTIFIER 2728| static_string_EXPRESSION 2729| "" 2730 2731PARAMETER_TYPES ::= 2732 null 2733| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 2734 2735TYPE_DESIGNATOR ::= 2736 subtype_NAME 2737| subtype_Name ' Access 2738 2739MECHANISM ::= 2740 MECHANISM_NAME 2741| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 2742 2743MECHANISM_ASSOCIATION ::= 2744 [formal_parameter_NAME =>] MECHANISM_NAME 2745 2746MECHANISM_NAME ::= 2747 Value 2748| Reference 2749| Descriptor [([Class =>] CLASS_NAME)] 2750| Short_Descriptor [([Class =>] CLASS_NAME)] 2751 2752CLASS_NAME ::= ubs | ubsb | uba | s | sb | a 2753@end smallexample 2754 2755@noindent 2756Use this pragma to make a function externally callable and optionally 2757provide information on mechanisms to be used for passing parameter and 2758result values. We recommend, for the purposes of improving portability, 2759this pragma always be used in conjunction with a separate pragma 2760@code{Export}, which must precede the pragma @code{Export_Function}. 2761GNAT does not require a separate pragma @code{Export}, but if none is 2762present, @code{Convention Ada} is assumed, which is usually 2763not what is wanted, so it is usually appropriate to use this 2764pragma in conjunction with a @code{Export} or @code{Convention} 2765pragma that specifies the desired foreign convention. 2766Pragma @code{Export_Function} 2767(and @code{Export}, if present) must appear in the same declarative 2768region as the function to which they apply. 2769 2770@var{internal_name} must uniquely designate the function to which the 2771pragma applies. If more than one function name exists of this name in 2772the declarative part you must use the @code{Parameter_Types} and 2773@code{Result_Type} parameters is mandatory to achieve the required 2774unique designation. @var{subtype_mark}s in these parameters must 2775exactly match the subtypes in the corresponding function specification, 2776using positional notation to match parameters with subtype marks. 2777The form with an @code{'Access} attribute can be used to match an 2778anonymous access parameter. 2779 2780@cindex OpenVMS 2781@cindex Passing by descriptor 2782Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 2783The default behavior for Export_Function is to accept either 64bit or 278432bit descriptors unless short_descriptor is specified, then only 32bit 2785descriptors are accepted. 2786 2787@cindex Suppressing external name 2788Special treatment is given if the EXTERNAL is an explicit null 2789string or a static string expressions that evaluates to the null 2790string. In this case, no external name is generated. This form 2791still allows the specification of parameter mechanisms. 2792 2793@node Pragma Export_Object 2794@unnumberedsec Pragma Export_Object 2795@findex Export_Object 2796@noindent 2797Syntax: 2798 2799@smallexample @c ada 2800pragma Export_Object 2801 [Internal =>] LOCAL_NAME 2802 [, [External =>] EXTERNAL_SYMBOL] 2803 [, [Size =>] EXTERNAL_SYMBOL] 2804 2805EXTERNAL_SYMBOL ::= 2806 IDENTIFIER 2807| static_string_EXPRESSION 2808@end smallexample 2809 2810@noindent 2811This pragma designates an object as exported, and apart from the 2812extended rules for external symbols, is identical in effect to the use of 2813the normal @code{Export} pragma applied to an object. You may use a 2814separate Export pragma (and you probably should from the point of view 2815of portability), but it is not required. @var{Size} is syntax checked, 2816but otherwise ignored by GNAT@. 2817 2818@node Pragma Export_Procedure 2819@unnumberedsec Pragma Export_Procedure 2820@findex Export_Procedure 2821@noindent 2822Syntax: 2823 2824@smallexample @c ada 2825pragma Export_Procedure ( 2826 [Internal =>] LOCAL_NAME 2827 [, [External =>] EXTERNAL_SYMBOL] 2828 [, [Parameter_Types =>] PARAMETER_TYPES] 2829 [, [Mechanism =>] MECHANISM]); 2830 2831EXTERNAL_SYMBOL ::= 2832 IDENTIFIER 2833| static_string_EXPRESSION 2834| "" 2835 2836PARAMETER_TYPES ::= 2837 null 2838| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 2839 2840TYPE_DESIGNATOR ::= 2841 subtype_NAME 2842| subtype_Name ' Access 2843 2844MECHANISM ::= 2845 MECHANISM_NAME 2846| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 2847 2848MECHANISM_ASSOCIATION ::= 2849 [formal_parameter_NAME =>] MECHANISM_NAME 2850 2851MECHANISM_NAME ::= 2852 Value 2853| Reference 2854| Descriptor [([Class =>] CLASS_NAME)] 2855| Short_Descriptor [([Class =>] CLASS_NAME)] 2856 2857CLASS_NAME ::= ubs | ubsb | uba | s | sb | a 2858@end smallexample 2859 2860@noindent 2861This pragma is identical to @code{Export_Function} except that it 2862applies to a procedure rather than a function and the parameters 2863@code{Result_Type} and @code{Result_Mechanism} are not permitted. 2864GNAT does not require a separate pragma @code{Export}, but if none is 2865present, @code{Convention Ada} is assumed, which is usually 2866not what is wanted, so it is usually appropriate to use this 2867pragma in conjunction with a @code{Export} or @code{Convention} 2868pragma that specifies the desired foreign convention. 2869 2870@cindex OpenVMS 2871@cindex Passing by descriptor 2872Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 2873The default behavior for Export_Procedure is to accept either 64bit or 287432bit descriptors unless short_descriptor is specified, then only 32bit 2875descriptors are accepted. 2876 2877@cindex Suppressing external name 2878Special treatment is given if the EXTERNAL is an explicit null 2879string or a static string expressions that evaluates to the null 2880string. In this case, no external name is generated. This form 2881still allows the specification of parameter mechanisms. 2882 2883@node Pragma Export_Value 2884@unnumberedsec Pragma Export_Value 2885@findex Export_Value 2886@noindent 2887Syntax: 2888 2889@smallexample @c ada 2890pragma Export_Value ( 2891 [Value =>] static_integer_EXPRESSION, 2892 [Link_Name =>] static_string_EXPRESSION); 2893@end smallexample 2894 2895@noindent 2896This pragma serves to export a static integer value for external use. 2897The first argument specifies the value to be exported. The Link_Name 2898argument specifies the symbolic name to be associated with the integer 2899value. This pragma is useful for defining a named static value in Ada 2900that can be referenced in assembly language units to be linked with 2901the application. This pragma is currently supported only for the 2902AAMP target and is ignored for other targets. 2903 2904@node Pragma Export_Valued_Procedure 2905@unnumberedsec Pragma Export_Valued_Procedure 2906@findex Export_Valued_Procedure 2907@noindent 2908Syntax: 2909 2910@smallexample @c ada 2911pragma Export_Valued_Procedure ( 2912 [Internal =>] LOCAL_NAME 2913 [, [External =>] EXTERNAL_SYMBOL] 2914 [, [Parameter_Types =>] PARAMETER_TYPES] 2915 [, [Mechanism =>] MECHANISM]); 2916 2917EXTERNAL_SYMBOL ::= 2918 IDENTIFIER 2919| static_string_EXPRESSION 2920| "" 2921 2922PARAMETER_TYPES ::= 2923 null 2924| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 2925 2926TYPE_DESIGNATOR ::= 2927 subtype_NAME 2928| subtype_Name ' Access 2929 2930MECHANISM ::= 2931 MECHANISM_NAME 2932| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 2933 2934MECHANISM_ASSOCIATION ::= 2935 [formal_parameter_NAME =>] MECHANISM_NAME 2936 2937MECHANISM_NAME ::= 2938 Value 2939| Reference 2940| Descriptor [([Class =>] CLASS_NAME)] 2941| Short_Descriptor [([Class =>] CLASS_NAME)] 2942 2943CLASS_NAME ::= ubs | ubsb | uba | s | sb | a 2944@end smallexample 2945 2946@noindent 2947This pragma is identical to @code{Export_Procedure} except that the 2948first parameter of @var{LOCAL_NAME}, which must be present, must be of 2949mode @code{OUT}, and externally the subprogram is treated as a function 2950with this parameter as the result of the function. GNAT provides for 2951this capability to allow the use of @code{OUT} and @code{IN OUT} 2952parameters in interfacing to external functions (which are not permitted 2953in Ada functions). 2954GNAT does not require a separate pragma @code{Export}, but if none is 2955present, @code{Convention Ada} is assumed, which is almost certainly 2956not what is wanted since the whole point of this pragma is to interface 2957with foreign language functions, so it is usually appropriate to use this 2958pragma in conjunction with a @code{Export} or @code{Convention} 2959pragma that specifies the desired foreign convention. 2960 2961@cindex OpenVMS 2962@cindex Passing by descriptor 2963Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 2964The default behavior for Export_Valued_Procedure is to accept either 64bit or 296532bit descriptors unless short_descriptor is specified, then only 32bit 2966descriptors are accepted. 2967 2968@cindex Suppressing external name 2969Special treatment is given if the EXTERNAL is an explicit null 2970string or a static string expressions that evaluates to the null 2971string. In this case, no external name is generated. This form 2972still allows the specification of parameter mechanisms. 2973 2974@node Pragma Extend_System 2975@unnumberedsec Pragma Extend_System 2976@cindex @code{system}, extending 2977@cindex Dec Ada 83 2978@findex Extend_System 2979@noindent 2980Syntax: 2981 2982@smallexample @c ada 2983pragma Extend_System ([Name =>] IDENTIFIER); 2984@end smallexample 2985 2986@noindent 2987This pragma is used to provide backwards compatibility with other 2988implementations that extend the facilities of package @code{System}. In 2989GNAT, @code{System} contains only the definitions that are present in 2990the Ada RM@. However, other implementations, notably the DEC Ada 83 2991implementation, provide many extensions to package @code{System}. 2992 2993For each such implementation accommodated by this pragma, GNAT provides a 2994package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83 2995implementation, which provides the required additional definitions. You 2996can use this package in two ways. You can @code{with} it in the normal 2997way and access entities either by selection or using a @code{use} 2998clause. In this case no special processing is required. 2999 3000However, if existing code contains references such as 3001@code{System.@var{xxx}} where @var{xxx} is an entity in the extended 3002definitions provided in package @code{System}, you may use this pragma 3003to extend visibility in @code{System} in a non-standard way that 3004provides greater compatibility with the existing code. Pragma 3005@code{Extend_System} is a configuration pragma whose single argument is 3006the name of the package containing the extended definition 3007(e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under 3008control of this pragma will be processed using special visibility 3009processing that looks in package @code{System.Aux_@var{xxx}} where 3010@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in 3011package @code{System}, but not found in package @code{System}. 3012 3013You can use this pragma either to access a predefined @code{System} 3014extension supplied with the compiler, for example @code{Aux_DEC} or 3015you can construct your own extension unit following the above 3016definition. Note that such a package is a child of @code{System} 3017and thus is considered part of the implementation. 3018To compile it you will have to use the @option{-gnatg} switch, 3019or the @option{/GNAT_INTERNAL} qualifier on OpenVMS, 3020for compiling System units, as explained in the 3021@value{EDITION} User's Guide. 3022 3023@node Pragma Extensions_Allowed 3024@unnumberedsec Pragma Extensions_Allowed 3025@cindex Ada Extensions 3026@cindex GNAT Extensions 3027@findex Extensions_Allowed 3028@noindent 3029Syntax: 3030 3031@smallexample @c ada 3032pragma Extensions_Allowed (On | Off); 3033@end smallexample 3034 3035@noindent 3036This configuration pragma enables or disables the implementation 3037extension mode (the use of Off as a parameter cancels the effect 3038of the @option{-gnatX} command switch). 3039 3040In extension mode, the latest version of the Ada language is 3041implemented (currently Ada 2012), and in addition a small number 3042of GNAT specific extensions are recognized as follows: 3043 3044@table @asis 3045@item Constrained attribute for generic objects 3046The @code{Constrained} attribute is permitted for objects of 3047generic types. The result indicates if the corresponding actual 3048is constrained. 3049 3050@end table 3051 3052@node Pragma External 3053@unnumberedsec Pragma External 3054@findex External 3055@noindent 3056Syntax: 3057 3058@smallexample @c ada 3059pragma External ( 3060 [ Convention =>] convention_IDENTIFIER, 3061 [ Entity =>] LOCAL_NAME 3062 [, [External_Name =>] static_string_EXPRESSION ] 3063 [, [Link_Name =>] static_string_EXPRESSION ]); 3064@end smallexample 3065 3066@noindent 3067This pragma is identical in syntax and semantics to pragma 3068@code{Export} as defined in the Ada Reference Manual. It is 3069provided for compatibility with some Ada 83 compilers that 3070used this pragma for exactly the same purposes as pragma 3071@code{Export} before the latter was standardized. 3072 3073@node Pragma External_Name_Casing 3074@unnumberedsec Pragma External_Name_Casing 3075@cindex Dec Ada 83 casing compatibility 3076@cindex External Names, casing 3077@cindex Casing of External names 3078@findex External_Name_Casing 3079@noindent 3080Syntax: 3081 3082@smallexample @c ada 3083pragma External_Name_Casing ( 3084 Uppercase | Lowercase 3085 [, Uppercase | Lowercase | As_Is]); 3086@end smallexample 3087 3088@noindent 3089This pragma provides control over the casing of external names associated 3090with Import and Export pragmas. There are two cases to consider: 3091 3092@table @asis 3093@item Implicit external names 3094Implicit external names are derived from identifiers. The most common case 3095arises when a standard Ada Import or Export pragma is used with only two 3096arguments, as in: 3097 3098@smallexample @c ada 3099 pragma Import (C, C_Routine); 3100@end smallexample 3101 3102@noindent 3103Since Ada is a case-insensitive language, the spelling of the identifier in 3104the Ada source program does not provide any information on the desired 3105casing of the external name, and so a convention is needed. In GNAT the 3106default treatment is that such names are converted to all lower case 3107letters. This corresponds to the normal C style in many environments. 3108The first argument of pragma @code{External_Name_Casing} can be used to 3109control this treatment. If @code{Uppercase} is specified, then the name 3110will be forced to all uppercase letters. If @code{Lowercase} is specified, 3111then the normal default of all lower case letters will be used. 3112 3113This same implicit treatment is also used in the case of extended DEC Ada 83 3114compatible Import and Export pragmas where an external name is explicitly 3115specified using an identifier rather than a string. 3116 3117@item Explicit external names 3118Explicit external names are given as string literals. The most common case 3119arises when a standard Ada Import or Export pragma is used with three 3120arguments, as in: 3121 3122@smallexample @c ada 3123pragma Import (C, C_Routine, "C_routine"); 3124@end smallexample 3125 3126@noindent 3127In this case, the string literal normally provides the exact casing required 3128for the external name. The second argument of pragma 3129@code{External_Name_Casing} may be used to modify this behavior. 3130If @code{Uppercase} is specified, then the name 3131will be forced to all uppercase letters. If @code{Lowercase} is specified, 3132then the name will be forced to all lowercase letters. A specification of 3133@code{As_Is} provides the normal default behavior in which the casing is 3134taken from the string provided. 3135@end table 3136 3137@noindent 3138This pragma may appear anywhere that a pragma is valid. In particular, it 3139can be used as a configuration pragma in the @file{gnat.adc} file, in which 3140case it applies to all subsequent compilations, or it can be used as a program 3141unit pragma, in which case it only applies to the current unit, or it can 3142be used more locally to control individual Import/Export pragmas. 3143 3144It is primarily intended for use with OpenVMS systems, where many 3145compilers convert all symbols to upper case by default. For interfacing to 3146such compilers (e.g.@: the DEC C compiler), it may be convenient to use 3147the pragma: 3148 3149@smallexample @c ada 3150pragma External_Name_Casing (Uppercase, Uppercase); 3151@end smallexample 3152 3153@noindent 3154to enforce the upper casing of all external symbols. 3155 3156@node Pragma Fast_Math 3157@unnumberedsec Pragma Fast_Math 3158@findex Fast_Math 3159@noindent 3160Syntax: 3161 3162@smallexample @c ada 3163pragma Fast_Math; 3164@end smallexample 3165 3166@noindent 3167This is a configuration pragma which activates a mode in which speed is 3168considered more important for floating-point operations than absolutely 3169accurate adherence to the requirements of the standard. Currently the 3170following operations are affected: 3171 3172@table @asis 3173@item Complex Multiplication 3174The normal simple formula for complex multiplication can result in intermediate 3175overflows for numbers near the end of the range. The Ada standard requires that 3176this situation be detected and corrected by scaling, but in Fast_Math mode such 3177cases will simply result in overflow. Note that to take advantage of this you 3178must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} 3179under control of the pragma, rather than use the preinstantiated versions. 3180@end table 3181 3182@node Pragma Favor_Top_Level 3183@unnumberedsec Pragma Favor_Top_Level 3184@findex Favor_Top_Level 3185@noindent 3186Syntax: 3187 3188@smallexample @c ada 3189pragma Favor_Top_Level (type_NAME); 3190@end smallexample 3191 3192@noindent 3193The named type must be an access-to-subprogram type. This pragma is an 3194efficiency hint to the compiler, regarding the use of 'Access or 3195'Unrestricted_Access on nested (non-library-level) subprograms. The 3196pragma means that nested subprograms are not used with this type, or 3197are rare, so that the generated code should be efficient in the 3198top-level case. When this pragma is used, dynamically generated 3199trampolines may be used on some targets for nested subprograms. 3200See also the No_Implicit_Dynamic_Code restriction. 3201 3202@node Pragma Finalize_Storage_Only 3203@unnumberedsec Pragma Finalize_Storage_Only 3204@findex Finalize_Storage_Only 3205@noindent 3206Syntax: 3207 3208@smallexample @c ada 3209pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 3210@end smallexample 3211 3212@noindent 3213This pragma allows the compiler not to emit a Finalize call for objects 3214defined at the library level. This is mostly useful for types where 3215finalization is only used to deal with storage reclamation since in most 3216environments it is not necessary to reclaim memory just before terminating 3217execution, hence the name. 3218 3219@node Pragma Float_Representation 3220@unnumberedsec Pragma Float_Representation 3221@cindex OpenVMS 3222@findex Float_Representation 3223@noindent 3224Syntax: 3225 3226@smallexample @c ada 3227pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 3228 3229FLOAT_REP ::= VAX_Float | IEEE_Float 3230@end smallexample 3231 3232@noindent 3233In the one argument form, this pragma is a configuration pragma which 3234allows control over the internal representation chosen for the predefined 3235floating point types declared in the packages @code{Standard} and 3236@code{System}. On all systems other than OpenVMS, the argument must 3237be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the 3238argument may be @code{VAX_Float} to specify the use of the VAX float 3239format for the floating-point types in Standard. This requires that 3240the standard runtime libraries be recompiled. 3241 3242The two argument form specifies the representation to be used for 3243the specified floating-point type. On all systems other than OpenVMS, 3244the argument must 3245be @code{IEEE_Float} to specify the use of IEEE format, as follows: 3246 3247@itemize @bullet 3248@item 3249For a digits value of 6, 32-bit IEEE short format will be used. 3250@item 3251For a digits value of 15, 64-bit IEEE long format will be used. 3252@item 3253No other value of digits is permitted. 3254@end itemize 3255 3256On OpenVMS, the 3257argument may be @code{VAX_Float} to specify the use of the VAX float 3258format, as follows: 3259 3260@itemize @bullet 3261@item 3262For digits values up to 6, F float format will be used. 3263@item 3264For digits values from 7 to 9, D float format will be used. 3265@item 3266For digits values from 10 to 15, G float format will be used. 3267@item 3268Digits values above 15 are not allowed. 3269@end itemize 3270 3271@node Pragma Global 3272@unnumberedsec Pragma Global 3273@findex Global 3274@noindent 3275For the description of this pragma, see SPARK 2014 Reference Manual, 3276section 6.1.4. 3277 3278@node Pragma Ident 3279@unnumberedsec Pragma Ident 3280@findex Ident 3281@noindent 3282Syntax: 3283 3284@smallexample @c ada 3285pragma Ident (static_string_EXPRESSION); 3286@end smallexample 3287 3288@noindent 3289This pragma provides a string identification in the generated object file, 3290if the system supports the concept of this kind of identification string. 3291This pragma is allowed only in the outermost declarative part or 3292declarative items of a compilation unit. If more than one @code{Ident} 3293pragma is given, only the last one processed is effective. 3294@cindex OpenVMS 3295On OpenVMS systems, the effect of the pragma is identical to the effect of 3296the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the 3297maximum allowed length is 31 characters, so if it is important to 3298maintain compatibility with this compiler, you should obey this length 3299limit. 3300 3301@node Pragma Implementation_Defined 3302@unnumberedsec Pragma Implementation_Defined 3303@findex Implementation_Defined 3304@noindent 3305Syntax: 3306 3307@smallexample @c ada 3308pragma Implementation_Defined (local_NAME); 3309@end smallexample 3310 3311@noindent 3312This pragma marks a previously declared entioty as implementation-defined. 3313For an overloaded entity, applies to the most recent homonym. 3314 3315@smallexample @c ada 3316pragma Implementation_Defined; 3317@end smallexample 3318 3319@noindent 3320The form with no arguments appears anywhere within a scope, most 3321typically a package spec, and indicates that all entities that are 3322defined within the package spec are Implementation_Defined. 3323 3324This pragma is used within the GNAT runtime library to identify 3325implementation-defined entities introduced in language-defined units, 3326for the purpose of implementing the No_Implementation_Identifiers 3327restriction. 3328 3329@node Pragma Implemented 3330@unnumberedsec Pragma Implemented 3331@findex Implemented 3332@noindent 3333Syntax: 3334 3335@smallexample @c ada 3336pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 3337 3338implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 3339@end smallexample 3340 3341@noindent 3342This is an Ada 2012 representation pragma which applies to protected, task 3343and synchronized interface primitives. The use of pragma Implemented provides 3344a way to impose a static requirement on the overriding operation by adhering 3345to one of the three implementation kinds: entry, protected procedure or any of 3346the above. This pragma is available in all earlier versions of Ada as an 3347implementation-defined pragma. 3348 3349@smallexample @c ada 3350type Synch_Iface is synchronized interface; 3351procedure Prim_Op (Obj : in out Iface) is abstract; 3352pragma Implemented (Prim_Op, By_Protected_Procedure); 3353 3354protected type Prot_1 is new Synch_Iface with 3355 procedure Prim_Op; -- Legal 3356end Prot_1; 3357 3358protected type Prot_2 is new Synch_Iface with 3359 entry Prim_Op; -- Illegal 3360end Prot_2; 3361 3362task type Task_Typ is new Synch_Iface with 3363 entry Prim_Op; -- Illegal 3364end Task_Typ; 3365@end smallexample 3366 3367@noindent 3368When applied to the procedure_or_entry_NAME of a requeue statement, pragma 3369Implemented determines the runtime behavior of the requeue. Implementation kind 3370By_Entry guarantees that the action of requeueing will proceed from an entry to 3371another entry. Implementation kind By_Protected_Procedure transforms the 3372requeue into a dispatching call, thus eliminating the chance of blocking. Kind 3373By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 3374the target's overriding subprogram kind. 3375 3376@node Pragma Implicit_Packing 3377@unnumberedsec Pragma Implicit_Packing 3378@findex Implicit_Packing 3379@cindex Rational Profile 3380@noindent 3381Syntax: 3382 3383@smallexample @c ada 3384pragma Implicit_Packing; 3385@end smallexample 3386 3387@noindent 3388This is a configuration pragma that requests implicit packing for packed 3389arrays for which a size clause is given but no explicit pragma Pack or 3390specification of Component_Size is present. It also applies to records 3391where no record representation clause is present. Consider this example: 3392 3393@smallexample @c ada 3394type R is array (0 .. 7) of Boolean; 3395for R'Size use 8; 3396@end smallexample 3397 3398@noindent 3399In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 3400does not change the layout of a composite object. So the Size clause in the 3401above example is normally rejected, since the default layout of the array uses 34028-bit components, and thus the array requires a minimum of 64 bits. 3403 3404If this declaration is compiled in a region of code covered by an occurrence 3405of the configuration pragma Implicit_Packing, then the Size clause in this 3406and similar examples will cause implicit packing and thus be accepted. For 3407this implicit packing to occur, the type in question must be an array of small 3408components whose size is known at compile time, and the Size clause must 3409specify the exact size that corresponds to the number of elements in the array 3410multiplied by the size in bits of the component type (both single and 3411multi-dimensioned arrays can be controlled with this pragma). 3412 3413@cindex Array packing 3414 3415Similarly, the following example shows the use in the record case 3416 3417@smallexample @c ada 3418type r is record 3419 a, b, c, d, e, f, g, h : boolean; 3420 chr : character; 3421end record; 3422for r'size use 16; 3423@end smallexample 3424 3425@noindent 3426Without a pragma Pack, each Boolean field requires 8 bits, so the 3427minimum size is 72 bits, but with a pragma Pack, 16 bits would be 3428sufficient. The use of pragma Implicit_Packing allows this record 3429declaration to compile without an explicit pragma Pack. 3430@node Pragma Import_Exception 3431@unnumberedsec Pragma Import_Exception 3432@cindex OpenVMS 3433@findex Import_Exception 3434@noindent 3435Syntax: 3436 3437@smallexample @c ada 3438pragma Import_Exception ( 3439 [Internal =>] LOCAL_NAME 3440 [, [External =>] EXTERNAL_SYMBOL] 3441 [, [Form =>] Ada | VMS] 3442 [, [Code =>] static_integer_EXPRESSION]); 3443 3444EXTERNAL_SYMBOL ::= 3445 IDENTIFIER 3446| static_string_EXPRESSION 3447@end smallexample 3448 3449@noindent 3450This pragma is implemented only in the OpenVMS implementation of GNAT@. 3451It allows OpenVMS conditions (for example, from OpenVMS system services or 3452other OpenVMS languages) to be propagated to Ada programs as Ada exceptions. 3453The pragma specifies that the exception associated with an exception 3454declaration in an Ada program be defined externally (in non-Ada code). 3455For further details on this pragma, see the 3456DEC Ada Language Reference Manual, section 13.9a.3.1. 3457 3458@node Pragma Import_Function 3459@unnumberedsec Pragma Import_Function 3460@findex Import_Function 3461@noindent 3462Syntax: 3463 3464@smallexample @c ada 3465pragma Import_Function ( 3466 [Internal =>] LOCAL_NAME, 3467 [, [External =>] EXTERNAL_SYMBOL] 3468 [, [Parameter_Types =>] PARAMETER_TYPES] 3469 [, [Result_Type =>] SUBTYPE_MARK] 3470 [, [Mechanism =>] MECHANISM] 3471 [, [Result_Mechanism =>] MECHANISM_NAME] 3472 [, [First_Optional_Parameter =>] IDENTIFIER]); 3473 3474EXTERNAL_SYMBOL ::= 3475 IDENTIFIER 3476| static_string_EXPRESSION 3477 3478PARAMETER_TYPES ::= 3479 null 3480| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3481 3482TYPE_DESIGNATOR ::= 3483 subtype_NAME 3484| subtype_Name ' Access 3485 3486MECHANISM ::= 3487 MECHANISM_NAME 3488| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3489 3490MECHANISM_ASSOCIATION ::= 3491 [formal_parameter_NAME =>] MECHANISM_NAME 3492 3493MECHANISM_NAME ::= 3494 Value 3495| Reference 3496| Descriptor [([Class =>] CLASS_NAME)] 3497| Short_Descriptor [([Class =>] CLASS_NAME)] 3498 3499CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 3500@end smallexample 3501 3502@noindent 3503This pragma is used in conjunction with a pragma @code{Import} to 3504specify additional information for an imported function. The pragma 3505@code{Import} (or equivalent pragma @code{Interface}) must precede the 3506@code{Import_Function} pragma and both must appear in the same 3507declarative part as the function specification. 3508 3509The @var{Internal} argument must uniquely designate 3510the function to which the 3511pragma applies. If more than one function name exists of this name in 3512the declarative part you must use the @code{Parameter_Types} and 3513@var{Result_Type} parameters to achieve the required unique 3514designation. Subtype marks in these parameters must exactly match the 3515subtypes in the corresponding function specification, using positional 3516notation to match parameters with subtype marks. 3517The form with an @code{'Access} attribute can be used to match an 3518anonymous access parameter. 3519 3520You may optionally use the @var{Mechanism} and @var{Result_Mechanism} 3521parameters to specify passing mechanisms for the 3522parameters and result. If you specify a single mechanism name, it 3523applies to all parameters. Otherwise you may specify a mechanism on a 3524parameter by parameter basis using either positional or named 3525notation. If the mechanism is not specified, the default mechanism 3526is used. 3527 3528@cindex OpenVMS 3529@cindex Passing by descriptor 3530Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 3531The default behavior for Import_Function is to pass a 64bit descriptor 3532unless short_descriptor is specified, then a 32bit descriptor is passed. 3533 3534@code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@. 3535It specifies that the designated parameter and all following parameters 3536are optional, meaning that they are not passed at the generated code 3537level (this is distinct from the notion of optional parameters in Ada 3538where the parameters are passed anyway with the designated optional 3539parameters). All optional parameters must be of mode @code{IN} and have 3540default parameter values that are either known at compile time 3541expressions, or uses of the @code{'Null_Parameter} attribute. 3542 3543@node Pragma Import_Object 3544@unnumberedsec Pragma Import_Object 3545@findex Import_Object 3546@noindent 3547Syntax: 3548 3549@smallexample @c ada 3550pragma Import_Object 3551 [Internal =>] LOCAL_NAME 3552 [, [External =>] EXTERNAL_SYMBOL] 3553 [, [Size =>] EXTERNAL_SYMBOL]); 3554 3555EXTERNAL_SYMBOL ::= 3556 IDENTIFIER 3557| static_string_EXPRESSION 3558@end smallexample 3559 3560@noindent 3561This pragma designates an object as imported, and apart from the 3562extended rules for external symbols, is identical in effect to the use of 3563the normal @code{Import} pragma applied to an object. Unlike the 3564subprogram case, you need not use a separate @code{Import} pragma, 3565although you may do so (and probably should do so from a portability 3566point of view). @var{size} is syntax checked, but otherwise ignored by 3567GNAT@. 3568 3569@node Pragma Import_Procedure 3570@unnumberedsec Pragma Import_Procedure 3571@findex Import_Procedure 3572@noindent 3573Syntax: 3574 3575@smallexample @c ada 3576pragma Import_Procedure ( 3577 [Internal =>] LOCAL_NAME 3578 [, [External =>] EXTERNAL_SYMBOL] 3579 [, [Parameter_Types =>] PARAMETER_TYPES] 3580 [, [Mechanism =>] MECHANISM] 3581 [, [First_Optional_Parameter =>] IDENTIFIER]); 3582 3583EXTERNAL_SYMBOL ::= 3584 IDENTIFIER 3585| static_string_EXPRESSION 3586 3587PARAMETER_TYPES ::= 3588 null 3589| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3590 3591TYPE_DESIGNATOR ::= 3592 subtype_NAME 3593| subtype_Name ' Access 3594 3595MECHANISM ::= 3596 MECHANISM_NAME 3597| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3598 3599MECHANISM_ASSOCIATION ::= 3600 [formal_parameter_NAME =>] MECHANISM_NAME 3601 3602MECHANISM_NAME ::= 3603 Value 3604| Reference 3605| Descriptor [([Class =>] CLASS_NAME)] 3606| Short_Descriptor [([Class =>] CLASS_NAME)] 3607 3608CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 3609@end smallexample 3610 3611@noindent 3612This pragma is identical to @code{Import_Function} except that it 3613applies to a procedure rather than a function and the parameters 3614@code{Result_Type} and @code{Result_Mechanism} are not permitted. 3615 3616@node Pragma Import_Valued_Procedure 3617@unnumberedsec Pragma Import_Valued_Procedure 3618@findex Import_Valued_Procedure 3619@noindent 3620Syntax: 3621 3622@smallexample @c ada 3623pragma Import_Valued_Procedure ( 3624 [Internal =>] LOCAL_NAME 3625 [, [External =>] EXTERNAL_SYMBOL] 3626 [, [Parameter_Types =>] PARAMETER_TYPES] 3627 [, [Mechanism =>] MECHANISM] 3628 [, [First_Optional_Parameter =>] IDENTIFIER]); 3629 3630EXTERNAL_SYMBOL ::= 3631 IDENTIFIER 3632| static_string_EXPRESSION 3633 3634PARAMETER_TYPES ::= 3635 null 3636| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3637 3638TYPE_DESIGNATOR ::= 3639 subtype_NAME 3640| subtype_Name ' Access 3641 3642MECHANISM ::= 3643 MECHANISM_NAME 3644| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3645 3646MECHANISM_ASSOCIATION ::= 3647 [formal_parameter_NAME =>] MECHANISM_NAME 3648 3649MECHANISM_NAME ::= 3650 Value 3651| Reference 3652| Descriptor [([Class =>] CLASS_NAME)] 3653| Short_Descriptor [([Class =>] CLASS_NAME)] 3654 3655CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 3656@end smallexample 3657 3658@noindent 3659This pragma is identical to @code{Import_Procedure} except that the 3660first parameter of @var{LOCAL_NAME}, which must be present, must be of 3661mode @code{OUT}, and externally the subprogram is treated as a function 3662with this parameter as the result of the function. The purpose of this 3663capability is to allow the use of @code{OUT} and @code{IN OUT} 3664parameters in interfacing to external functions (which are not permitted 3665in Ada functions). You may optionally use the @code{Mechanism} 3666parameters to specify passing mechanisms for the parameters. 3667If you specify a single mechanism name, it applies to all parameters. 3668Otherwise you may specify a mechanism on a parameter by parameter 3669basis using either positional or named notation. If the mechanism is not 3670specified, the default mechanism is used. 3671 3672Note that it is important to use this pragma in conjunction with a separate 3673pragma Import that specifies the desired convention, since otherwise the 3674default convention is Ada, which is almost certainly not what is required. 3675 3676@node Pragma Independent 3677@unnumberedsec Pragma Independent 3678@findex Independent 3679@noindent 3680Syntax: 3681 3682@smallexample @c ada 3683pragma Independent (Local_NAME); 3684@end smallexample 3685 3686@noindent 3687This pragma is standard in Ada 2012 mode (which also provides an aspect 3688of the same name). It is also available as an implementation-defined 3689pragma in all earlier versions. It specifies that the 3690designated object or all objects of the designated type must be 3691independently addressable. This means that separate tasks can safely 3692manipulate such objects. For example, if two components of a record are 3693independent, then two separate tasks may access these two components. 3694This may place 3695constraints on the representation of the object (for instance prohibiting 3696tight packing). 3697 3698@node Pragma Independent_Components 3699@unnumberedsec Pragma Independent_Components 3700@findex Independent_Components 3701@noindent 3702Syntax: 3703 3704@smallexample @c ada 3705pragma Independent_Components (Local_NAME); 3706@end smallexample 3707 3708@noindent 3709This pragma is standard in Ada 2012 mode (which also provides an aspect 3710of the same name). It is also available as an implementation-defined 3711pragma in all earlier versions. It specifies that the components of the 3712designated object, or the components of each object of the designated 3713type, must be 3714independently addressable. This means that separate tasks can safely 3715manipulate separate components in the composite object. This may place 3716constraints on the representation of the object (for instance prohibiting 3717tight packing). 3718 3719@node Pragma Initial_Condition 3720@unnumberedsec Pragma Initial_Condition 3721@findex Initial_Condition 3722@noindent 3723For the description of this pragma, see SPARK 2014 Reference Manual, 3724section 7.1.6. 3725 3726@node Pragma Initialize_Scalars 3727@unnumberedsec Pragma Initialize_Scalars 3728@findex Initialize_Scalars 3729@cindex debugging with Initialize_Scalars 3730@noindent 3731Syntax: 3732 3733@smallexample @c ada 3734pragma Initialize_Scalars; 3735@end smallexample 3736 3737@noindent 3738This pragma is similar to @code{Normalize_Scalars} conceptually but has 3739two important differences. First, there is no requirement for the pragma 3740to be used uniformly in all units of a partition, in particular, it is fine 3741to use this just for some or all of the application units of a partition, 3742without needing to recompile the run-time library. 3743 3744In the case where some units are compiled with the pragma, and some without, 3745then a declaration of a variable where the type is defined in package 3746Standard or is locally declared will always be subject to initialization, 3747as will any declaration of a scalar variable. For composite variables, 3748whether the variable is initialized may also depend on whether the package 3749in which the type of the variable is declared is compiled with the pragma. 3750 3751The other important difference is that you can control the value used 3752for initializing scalar objects. At bind time, you can select several 3753options for initialization. You can 3754initialize with invalid values (similar to Normalize_Scalars, though for 3755Initialize_Scalars it is not always possible to determine the invalid 3756values in complex cases like signed component fields with non-standard 3757sizes). You can also initialize with high or 3758low values, or with a specified bit pattern. See the @value{EDITION} 3759User's Guide for binder options for specifying these cases. 3760 3761This means that you can compile a program, and then without having to 3762recompile the program, you can run it with different values being used 3763for initializing otherwise uninitialized values, to test if your program 3764behavior depends on the choice. Of course the behavior should not change, 3765and if it does, then most likely you have an incorrect reference to an 3766uninitialized value. 3767 3768It is even possible to change the value at execution time eliminating even 3769the need to rebind with a different switch using an environment variable. 3770See the @value{EDITION} User's Guide for details. 3771 3772Note that pragma @code{Initialize_Scalars} is particularly useful in 3773conjunction with the enhanced validity checking that is now provided 3774in GNAT, which checks for invalid values under more conditions. 3775Using this feature (see description of the @option{-gnatV} flag in the 3776@value{EDITION} User's Guide) in conjunction with 3777pragma @code{Initialize_Scalars} 3778provides a powerful new tool to assist in the detection of problems 3779caused by uninitialized variables. 3780 3781Note: the use of @code{Initialize_Scalars} has a fairly extensive 3782effect on the generated code. This may cause your code to be 3783substantially larger. It may also cause an increase in the amount 3784of stack required, so it is probably a good idea to turn on stack 3785checking (see description of stack checking in the @value{EDITION} 3786User's Guide) when using this pragma. 3787 3788@node Pragma Initializes 3789@unnumberedsec Pragma Initializes 3790@findex Initializes 3791@noindent 3792For the description of this pragma, see SPARK 2014 Reference Manual, 3793section 7.1.5. 3794 3795@node Pragma Inline_Always 3796@unnumberedsec Pragma Inline_Always 3797@findex Inline_Always 3798@noindent 3799Syntax: 3800 3801@smallexample @c ada 3802pragma Inline_Always (NAME [, NAME]); 3803@end smallexample 3804 3805@noindent 3806Similar to pragma @code{Inline} except that inlining is not subject to 3807the use of option @option{-gnatn} or @option{-gnatN} and the inlining 3808happens regardless of whether these options are used. 3809 3810@node Pragma Inline_Generic 3811@unnumberedsec Pragma Inline_Generic 3812@findex Inline_Generic 3813@noindent 3814Syntax: 3815 3816@smallexample @c ada 3817pragma Inline_Generic (GNAME @{, GNAME@}); 3818 3819GNAME ::= generic_unit_NAME | generic_instance_NAME 3820@end smallexample 3821 3822@noindent 3823This pragma is provided for compatibility with Dec Ada 83. It has 3824no effect in @code{GNAT} (which always inlines generics), other 3825than to check that the given names are all names of generic units or 3826generic instances. 3827 3828@node Pragma Interface 3829@unnumberedsec Pragma Interface 3830@findex Interface 3831@noindent 3832Syntax: 3833 3834@smallexample @c ada 3835pragma Interface ( 3836 [Convention =>] convention_identifier, 3837 [Entity =>] local_NAME 3838 [, [External_Name =>] static_string_expression] 3839 [, [Link_Name =>] static_string_expression]); 3840@end smallexample 3841 3842@noindent 3843This pragma is identical in syntax and semantics to 3844the standard Ada pragma @code{Import}. It is provided for compatibility 3845with Ada 83. The definition is upwards compatible both with pragma 3846@code{Interface} as defined in the Ada 83 Reference Manual, and also 3847with some extended implementations of this pragma in certain Ada 83 3848implementations. The only difference between pragma @code{Interface} 3849and pragma @code{Import} is that there is special circuitry to allow 3850both pragmas to appear for the same subprogram entity (normally it 3851is illegal to have multiple @code{Import} pragmas. This is useful in 3852maintaining Ada 83/Ada 95 compatibility and is compatible with other 3853Ada 83 compilers. 3854 3855@node Pragma Interface_Name 3856@unnumberedsec Pragma Interface_Name 3857@findex Interface_Name 3858@noindent 3859Syntax: 3860 3861@smallexample @c ada 3862pragma Interface_Name ( 3863 [Entity =>] LOCAL_NAME 3864 [, [External_Name =>] static_string_EXPRESSION] 3865 [, [Link_Name =>] static_string_EXPRESSION]); 3866@end smallexample 3867 3868@noindent 3869This pragma provides an alternative way of specifying the interface name 3870for an interfaced subprogram, and is provided for compatibility with Ada 387183 compilers that use the pragma for this purpose. You must provide at 3872least one of @var{External_Name} or @var{Link_Name}. 3873 3874@node Pragma Interrupt_Handler 3875@unnumberedsec Pragma Interrupt_Handler 3876@findex Interrupt_Handler 3877@noindent 3878Syntax: 3879 3880@smallexample @c ada 3881pragma Interrupt_Handler (procedure_LOCAL_NAME); 3882@end smallexample 3883 3884@noindent 3885This program unit pragma is supported for parameterless protected procedures 3886as described in Annex C of the Ada Reference Manual. On the AAMP target 3887the pragma can also be specified for nonprotected parameterless procedures 3888that are declared at the library level (which includes procedures 3889declared at the top level of a library package). In the case of AAMP, 3890when this pragma is applied to a nonprotected procedure, the instruction 3891@code{IERET} is generated for returns from the procedure, enabling 3892maskable interrupts, in place of the normal return instruction. 3893 3894@node Pragma Interrupt_State 3895@unnumberedsec Pragma Interrupt_State 3896@findex Interrupt_State 3897@noindent 3898Syntax: 3899 3900@smallexample @c ada 3901pragma Interrupt_State 3902 ([Name =>] value, 3903 [State =>] SYSTEM | RUNTIME | USER); 3904@end smallexample 3905 3906@noindent 3907Normally certain interrupts are reserved to the implementation. Any attempt 3908to attach an interrupt causes Program_Error to be raised, as described in 3909RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 3910many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is 3911reserved to the implementation, so that @kbd{Ctrl-C} can be used to 3912interrupt execution. Additionally, signals such as @code{SIGSEGV}, 3913@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific 3914Ada exceptions, or used to implement run-time functions such as the 3915@code{abort} statement and stack overflow checking. 3916 3917Pragma @code{Interrupt_State} provides a general mechanism for overriding 3918such uses of interrupts. It subsumes the functionality of pragma 3919@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not 3920available on Windows or VMS. On all other platforms than VxWorks, 3921it applies to signals; on VxWorks, it applies to vectored hardware interrupts 3922and may be used to mark interrupts required by the board support package 3923as reserved. 3924 3925Interrupts can be in one of three states: 3926@itemize @bullet 3927@item System 3928 3929The interrupt is reserved (no Ada handler can be installed), and the 3930Ada run-time may not install a handler. As a result you are guaranteed 3931standard system default action if this interrupt is raised. 3932 3933@item Runtime 3934 3935The interrupt is reserved (no Ada handler can be installed). The run time 3936is allowed to install a handler for internal control purposes, but is 3937not required to do so. 3938 3939@item User 3940 3941The interrupt is unreserved. The user may install a handler to provide 3942some other action. 3943@end itemize 3944 3945@noindent 3946These states are the allowed values of the @code{State} parameter of the 3947pragma. The @code{Name} parameter is a value of the type 3948@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 3949@code{Ada.Interrupts.Names}. 3950 3951This is a configuration pragma, and the binder will check that there 3952are no inconsistencies between different units in a partition in how a 3953given interrupt is specified. It may appear anywhere a pragma is legal. 3954 3955The effect is to move the interrupt to the specified state. 3956 3957By declaring interrupts to be SYSTEM, you guarantee the standard system 3958action, such as a core dump. 3959 3960By declaring interrupts to be USER, you guarantee that you can install 3961a handler. 3962 3963Note that certain signals on many operating systems cannot be caught and 3964handled by applications. In such cases, the pragma is ignored. See the 3965operating system documentation, or the value of the array @code{Reserved} 3966declared in the spec of package @code{System.OS_Interface}. 3967 3968Overriding the default state of signals used by the Ada runtime may interfere 3969with an application's runtime behavior in the cases of the synchronous signals, 3970and in the case of the signal used to implement the @code{abort} statement. 3971 3972@node Pragma Invariant 3973@unnumberedsec Pragma Invariant 3974@findex Invariant 3975@noindent 3976Syntax: 3977 3978@smallexample @c ada 3979pragma Invariant 3980 ([Entity =>] private_type_LOCAL_NAME, 3981 [Check =>] EXPRESSION 3982 [,[Message =>] String_Expression]); 3983@end smallexample 3984 3985@noindent 3986This pragma provides exactly the same capabilities as the Type_Invariant aspect 3987defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 3988Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 3989requires the use of the aspect syntax, which is not available except in 2012 3990mode, it is not possible to use the Type_Invariant aspect in earlier versions 3991of Ada. However the Invariant pragma may be used in any version of Ada. Also 3992note that the aspect Invariant is a synonym in GNAT for the aspect 3993Type_Invariant, but there is no pragma Type_Invariant. 3994 3995The pragma must appear within the visible part of the package specification, 3996after the type to which its Entity argument appears. As with the Invariant 3997aspect, the Check expression is not analyzed until the end of the visible 3998part of the package, so it may contain forward references. The Message 3999argument, if present, provides the exception message used if the invariant 4000is violated. If no Message parameter is provided, a default message that 4001identifies the line on which the pragma appears is used. 4002 4003It is permissible to have multiple Invariants for the same type entity, in 4004which case they are and'ed together. It is permissible to use this pragma 4005in Ada 2012 mode, but you cannot have both an invariant aspect and an 4006invariant pragma for the same entity. 4007 4008For further details on the use of this pragma, see the Ada 2012 documentation 4009of the Type_Invariant aspect. 4010 4011@node Pragma Java_Constructor 4012@unnumberedsec Pragma Java_Constructor 4013@findex Java_Constructor 4014@noindent 4015Syntax: 4016 4017@smallexample @c ada 4018pragma Java_Constructor ([Entity =>] function_LOCAL_NAME); 4019@end smallexample 4020 4021@noindent 4022This pragma is used to assert that the specified Ada function should be 4023mapped to the Java constructor for some Ada tagged record type. 4024 4025See section 7.3.2 of the 4026@code{GNAT User's Guide: Supplement for the JVM Platform.} 4027for related information. 4028 4029@node Pragma Java_Interface 4030@unnumberedsec Pragma Java_Interface 4031@findex Java_Interface 4032@noindent 4033Syntax: 4034 4035@smallexample @c ada 4036pragma Java_Interface ([Entity =>] abstract_tagged_type_LOCAL_NAME); 4037@end smallexample 4038 4039@noindent 4040This pragma is used to assert that the specified Ada abstract tagged type 4041is to be mapped to a Java interface name. 4042 4043See sections 7.1 and 7.2 of the 4044@code{GNAT User's Guide: Supplement for the JVM Platform.} 4045for related information. 4046 4047@node Pragma Keep_Names 4048@unnumberedsec Pragma Keep_Names 4049@findex Keep_Names 4050@noindent 4051Syntax: 4052 4053@smallexample @c ada 4054pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 4055@end smallexample 4056 4057@noindent 4058The @var{LOCAL_NAME} argument 4059must refer to an enumeration first subtype 4060in the current declarative part. The effect is to retain the enumeration 4061literal names for use by @code{Image} and @code{Value} even if a global 4062@code{Discard_Names} pragma applies. This is useful when you want to 4063generally suppress enumeration literal names and for example you therefore 4064use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you 4065want to retain the names for specific enumeration types. 4066 4067@node Pragma License 4068@unnumberedsec Pragma License 4069@findex License 4070@cindex License checking 4071@noindent 4072Syntax: 4073 4074@smallexample @c ada 4075pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 4076@end smallexample 4077 4078@noindent 4079This pragma is provided to allow automated checking for appropriate license 4080conditions with respect to the standard and modified GPL@. A pragma 4081@code{License}, which is a configuration pragma that typically appears at 4082the start of a source file or in a separate @file{gnat.adc} file, specifies 4083the licensing conditions of a unit as follows: 4084 4085@itemize @bullet 4086@item Unrestricted 4087This is used for a unit that can be freely used with no license restrictions. 4088Examples of such units are public domain units, and units from the Ada 4089Reference Manual. 4090 4091@item GPL 4092This is used for a unit that is licensed under the unmodified GPL, and which 4093therefore cannot be @code{with}'ed by a restricted unit. 4094 4095@item Modified_GPL 4096This is used for a unit licensed under the GNAT modified GPL that includes 4097a special exception paragraph that specifically permits the inclusion of 4098the unit in programs without requiring the entire program to be released 4099under the GPL@. 4100 4101@item Restricted 4102This is used for a unit that is restricted in that it is not permitted to 4103depend on units that are licensed under the GPL@. Typical examples are 4104proprietary code that is to be released under more restrictive license 4105conditions. Note that restricted units are permitted to @code{with} units 4106which are licensed under the modified GPL (this is the whole point of the 4107modified GPL). 4108 4109@end itemize 4110 4111@noindent 4112Normally a unit with no @code{License} pragma is considered to have an 4113unknown license, and no checking is done. However, standard GNAT headers 4114are recognized, and license information is derived from them as follows. 4115 4116@itemize @bullet 4117 4118A GNAT license header starts with a line containing 78 hyphens. The following 4119comment text is searched for the appearance of any of the following strings. 4120 4121If the string ``GNU General Public License'' is found, then the unit is assumed 4122to have GPL license, unless the string ``As a special exception'' follows, in 4123which case the license is assumed to be modified GPL@. 4124 4125If one of the strings 4126``This specification is adapted from the Ada Semantic Interface'' or 4127``This specification is derived from the Ada Reference Manual'' is found 4128then the unit is assumed to be unrestricted. 4129@end itemize 4130 4131@noindent 4132These default actions means that a program with a restricted license pragma 4133will automatically get warnings if a GPL unit is inappropriately 4134@code{with}'ed. For example, the program: 4135 4136@smallexample @c ada 4137with Sem_Ch3; 4138with GNAT.Sockets; 4139procedure Secret_Stuff is 4140 @dots{} 4141end Secret_Stuff 4142@end smallexample 4143 4144@noindent 4145if compiled with pragma @code{License} (@code{Restricted}) in a 4146@file{gnat.adc} file will generate the warning: 4147 4148@smallexample 41491. with Sem_Ch3; 4150 | 4151 >>> license of withed unit "Sem_Ch3" is incompatible 4152 41532. with GNAT.Sockets; 41543. procedure Secret_Stuff is 4155@end smallexample 4156 4157@noindent 4158Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT 4159compiler and is licensed under the 4160GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 4161run time, and is therefore licensed under the modified GPL@. 4162 4163@node Pragma Link_With 4164@unnumberedsec Pragma Link_With 4165@findex Link_With 4166@noindent 4167Syntax: 4168 4169@smallexample @c ada 4170pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 4171@end smallexample 4172 4173@noindent 4174This pragma is provided for compatibility with certain Ada 83 compilers. 4175It has exactly the same effect as pragma @code{Linker_Options} except 4176that spaces occurring within one of the string expressions are treated 4177as separators. For example, in the following case: 4178 4179@smallexample @c ada 4180pragma Link_With ("-labc -ldef"); 4181@end smallexample 4182 4183@noindent 4184results in passing the strings @code{-labc} and @code{-ldef} as two 4185separate arguments to the linker. In addition pragma Link_With allows 4186multiple arguments, with the same effect as successive pragmas. 4187 4188@node Pragma Linker_Alias 4189@unnumberedsec Pragma Linker_Alias 4190@findex Linker_Alias 4191@noindent 4192Syntax: 4193 4194@smallexample @c ada 4195pragma Linker_Alias ( 4196 [Entity =>] LOCAL_NAME, 4197 [Target =>] static_string_EXPRESSION); 4198@end smallexample 4199 4200@noindent 4201@var{LOCAL_NAME} must refer to an object that is declared at the library 4202level. This pragma establishes the given entity as a linker alias for the 4203given target. It is equivalent to @code{__attribute__((alias))} in GNU C 4204and causes @var{LOCAL_NAME} to be emitted as an alias for the symbol 4205@var{static_string_EXPRESSION} in the object file, that is to say no space 4206is reserved for @var{LOCAL_NAME} by the assembler and it will be resolved 4207to the same address as @var{static_string_EXPRESSION} by the linker. 4208 4209The actual linker name for the target must be used (e.g.@: the fully 4210encoded name with qualification in Ada, or the mangled name in C++), 4211or it must be declared using the C convention with @code{pragma Import} 4212or @code{pragma Export}. 4213 4214Not all target machines support this pragma. On some of them it is accepted 4215only if @code{pragma Weak_External} has been applied to @var{LOCAL_NAME}. 4216 4217@smallexample @c ada 4218-- Example of the use of pragma Linker_Alias 4219 4220package p is 4221 i : Integer := 1; 4222 pragma Export (C, i); 4223 4224 new_name_for_i : Integer; 4225 pragma Linker_Alias (new_name_for_i, "i"); 4226end p; 4227@end smallexample 4228 4229@node Pragma Linker_Constructor 4230@unnumberedsec Pragma Linker_Constructor 4231@findex Linker_Constructor 4232@noindent 4233Syntax: 4234 4235@smallexample @c ada 4236pragma Linker_Constructor (procedure_LOCAL_NAME); 4237@end smallexample 4238 4239@noindent 4240@var{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4241is declared at the library level. A procedure to which this pragma is 4242applied will be treated as an initialization routine by the linker. 4243It is equivalent to @code{__attribute__((constructor))} in GNU C and 4244causes @var{procedure_LOCAL_NAME} to be invoked before the entry point 4245of the executable is called (or immediately after the shared library is 4246loaded if the procedure is linked in a shared library), in particular 4247before the Ada run-time environment is set up. 4248 4249Because of these specific contexts, the set of operations such a procedure 4250can perform is very limited and the type of objects it can manipulate is 4251essentially restricted to the elementary types. In particular, it must only 4252contain code to which pragma Restrictions (No_Elaboration_Code) applies. 4253 4254This pragma is used by GNAT to implement auto-initialization of shared Stand 4255Alone Libraries, which provides a related capability without the restrictions 4256listed above. Where possible, the use of Stand Alone Libraries is preferable 4257to the use of this pragma. 4258 4259@node Pragma Linker_Destructor 4260@unnumberedsec Pragma Linker_Destructor 4261@findex Linker_Destructor 4262@noindent 4263Syntax: 4264 4265@smallexample @c ada 4266pragma Linker_Destructor (procedure_LOCAL_NAME); 4267@end smallexample 4268 4269@noindent 4270@var{procedure_LOCAL_NAME} must refer to a parameterless procedure that 4271is declared at the library level. A procedure to which this pragma is 4272applied will be treated as a finalization routine by the linker. 4273It is equivalent to @code{__attribute__((destructor))} in GNU C and 4274causes @var{procedure_LOCAL_NAME} to be invoked after the entry point 4275of the executable has exited (or immediately before the shared library 4276is unloaded if the procedure is linked in a shared library), in particular 4277after the Ada run-time environment is shut down. 4278 4279See @code{pragma Linker_Constructor} for the set of restrictions that apply 4280because of these specific contexts. 4281 4282@node Pragma Linker_Section 4283@unnumberedsec Pragma Linker_Section 4284@findex Linker_Section 4285@noindent 4286Syntax: 4287 4288@smallexample @c ada 4289pragma Linker_Section ( 4290 [Entity =>] LOCAL_NAME, 4291 [Section =>] static_string_EXPRESSION); 4292@end smallexample 4293 4294@noindent 4295@var{LOCAL_NAME} must refer to an object, type, or subprogram that is 4296declared at the library level. This pragma specifies the name of the 4297linker section for the given entity. It is equivalent to 4298@code{__attribute__((section))} in GNU C and causes @var{LOCAL_NAME} to 4299be placed in the @var{static_string_EXPRESSION} section of the 4300executable (assuming the linker doesn't rename the section). 4301GNAT also provides an implementation defined aspect of the same name. 4302 4303In the case of specifying this aspect for a type, the effect is to 4304specify the corresponding for all library level objects of the type which 4305do not have an explicit linker section set. Note that this only applies to 4306whole objects, not to components of composite objects. 4307 4308In the case of a subprogram, the linker section applies to all previously 4309declared matching overloaded subprograms in the current declarative part 4310which do not already have a linker section assigned. The linker section 4311aspect is useful in this case for specifying different linker sections 4312for different elements of such an overloaded set. 4313 4314Note that an empty string specifies that no linker section is specified. 4315This is not quite the same as omitting the pragma or aspect, since it 4316can be used to specify that one element of an overloaded set of subprograms 4317has the default linker section, or that one object of a type for which a 4318linker section is specified should has the default linker section. 4319 4320The compiler normally places library-level entities in standard sections 4321depending on the class: procedures and functions generally go in the 4322@code{.text} section, initialized variables in the @code{.data} section 4323and uninitialized variables in the @code{.bss} section. 4324 4325Other, special sections may exist on given target machines to map special 4326hardware, for example I/O ports or flash memory. This pragma is a means to 4327defer the final layout of the executable to the linker, thus fully working 4328at the symbolic level with the compiler. 4329 4330Some file formats do not support arbitrary sections so not all target 4331machines support this pragma. The use of this pragma may cause a program 4332execution to be erroneous if it is used to place an entity into an 4333inappropriate section (e.g.@: a modified variable into the @code{.text} 4334section). See also @code{pragma Persistent_BSS}. 4335 4336@smallexample @c ada 4337-- Example of the use of pragma Linker_Section 4338 4339package IO_Card is 4340 Port_A : Integer; 4341 pragma Volatile (Port_A); 4342 pragma Linker_Section (Port_A, ".bss.port_a"); 4343 4344 Port_B : Integer; 4345 pragma Volatile (Port_B); 4346 pragma Linker_Section (Port_B, ".bss.port_b"); 4347 4348 type Port_Type is new Integer with Linker_Section => ".bss"; 4349 PA : Port_Type with Linker_Section => ".bss.PA"; 4350 PB : Port_Type; -- ends up in linker section ".bss" 4351 4352 procedure Q with Linker_Section => "Qsection"; 4353end IO_Card; 4354@end smallexample 4355 4356@node Pragma Long_Float 4357@unnumberedsec Pragma Long_Float 4358@cindex OpenVMS 4359@findex Long_Float 4360@noindent 4361Syntax: 4362 4363@smallexample @c ada 4364pragma Long_Float (FLOAT_FORMAT); 4365 4366FLOAT_FORMAT ::= D_Float | G_Float 4367@end smallexample 4368 4369@noindent 4370This pragma is implemented only in the OpenVMS implementation of GNAT@. 4371It allows control over the internal representation chosen for the predefined 4372type @code{Long_Float} and for floating point type representations with 4373@code{digits} specified in the range 7 through 15. 4374For further details on this pragma, see the 4375@cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use 4376this pragma, the standard runtime libraries must be recompiled. 4377 4378@node Pragma Loop_Invariant 4379@unnumberedsec Pragma Loop_Invariant 4380@findex Loop_Invariant 4381@noindent 4382Syntax: 4383 4384@smallexample @c ada 4385pragma Loop_Invariant ( boolean_EXPRESSION ); 4386@end smallexample 4387 4388@noindent 4389The effect of this pragma is similar to that of pragma @code{Assert}, 4390except that in an @code{Assertion_Policy} pragma, the identifier 4391@code{Loop_Invariant} is used to control whether it is ignored or checked 4392(or disabled). 4393 4394@code{Loop_Invariant} can only appear as one of the items in the sequence 4395of statements of a loop body, or nested inside block statements that 4396appear in the sequence of statements of a loop body. 4397The intention is that it be used to 4398represent a "loop invariant" assertion, i.e. something that is true each 4399time through the loop, and which can be used to show that the loop is 4400achieving its purpose. 4401 4402Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 4403apply to the same loop should be grouped in the same sequence of 4404statements. 4405 4406To aid in writing such invariants, the special attribute @code{Loop_Entry} 4407may be used to refer to the value of an expression on entry to the loop. This 4408attribute can only be used within the expression of a @code{Loop_Invariant} 4409pragma. For full details, see documentation of attribute @code{Loop_Entry}. 4410 4411@node Pragma Loop_Optimize 4412@unnumberedsec Pragma Loop_Optimize 4413@findex Loop_Optimize 4414@noindent 4415Syntax: 4416 4417@smallexample @c ada 4418pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); 4419 4420OPTIMIZATION_HINT ::= No_Unroll | Unroll | No_Vector | Vector 4421@end smallexample 4422 4423@noindent 4424This pragma must appear immediately within a loop statement. It allows the 4425programmer to specify optimization hints for the enclosing loop. The hints 4426are not mutually exclusive and can be freely mixed, but not all combinations 4427will yield a sensible outcome. 4428 4429There are four supported optimization hints for a loop: 4430@itemize @bullet 4431@item No_Unroll 4432 4433The loop must not be unrolled. This is a strong hint: the compiler will not 4434unroll a loop marked with this hint. 4435 4436@item Unroll 4437 4438The loop should be unrolled. This is a weak hint: the compiler will try to 4439apply unrolling to this loop preferably to other optimizations, notably 4440vectorization, but there is no guarantee that the loop will be unrolled. 4441 4442@item No_Vector 4443 4444The loop must not be vectorized. This is a strong hint: the compiler will not 4445vectorize a loop marked with this hint. 4446 4447@item Vector 4448 4449The loop should be vectorized. This is a weak hint: the compiler will try to 4450apply vectorization to this loop preferably to other optimizations, notably 4451unrolling, but there is no guarantee that the loop will be vectorized. 4452 4453@end itemize 4454 4455These hints do not void the need to pass the appropriate switches to the 4456compiler in order to enable the relevant optimizations, that is to say 4457@option{-funroll-loops} for unrolling and @option{-ftree-vectorize} for 4458vectorization. 4459 4460@node Pragma Loop_Variant 4461@unnumberedsec Pragma Loop_Variant 4462@findex Loop_Variant 4463@noindent 4464Syntax: 4465 4466@smallexample @c ada 4467pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); 4468LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION 4469CHANGE_DIRECTION ::= Increases | Decreases 4470@end smallexample 4471 4472@noindent 4473@code{Loop_Variant} can only appear as one of the items in the sequence 4474of statements of a loop body, or nested inside block statements that 4475appear in the sequence of statements of a loop body. 4476It allows the specification of quantities which must always 4477decrease or increase in successive iterations of the loop. In its simplest 4478form, just one expression is specified, whose value must increase or decrease 4479on each iteration of the loop. 4480 4481In a more complex form, multiple arguments can be given which are intepreted 4482in a nesting lexicographic manner. For example: 4483 4484@smallexample @c ada 4485pragma Loop_Variant (Increases => X, Decreases => Y); 4486@end smallexample 4487 4488@noindent 4489specifies that each time through the loop either X increases, or X stays 4490the same and Y decreases. A @code{Loop_Variant} pragma ensures that the 4491loop is making progress. It can be useful in helping to show informally 4492or prove formally that the loop always terminates. 4493 4494@code{Loop_Variant} is an assertion whose effect can be controlled using 4495an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The 4496policy can be @code{Check} to enable the loop variant check, @code{Ignore} 4497to ignore the check (in which case the pragma has no effect on the program), 4498or @code{Disable} in which case the pragma is not even checked for correct 4499syntax. 4500 4501Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that 4502apply to the same loop should be grouped in the same sequence of 4503statements. 4504 4505The @code{Loop_Entry} attribute may be used within the expressions of the 4506@code{Loop_Variant} pragma to refer to values on entry to the loop. 4507 4508@node Pragma Machine_Attribute 4509@unnumberedsec Pragma Machine_Attribute 4510@findex Machine_Attribute 4511@noindent 4512Syntax: 4513 4514@smallexample @c ada 4515pragma Machine_Attribute ( 4516 [Entity =>] LOCAL_NAME, 4517 [Attribute_Name =>] static_string_EXPRESSION 4518 [, [Info =>] static_EXPRESSION] ); 4519@end smallexample 4520 4521@noindent 4522Machine-dependent attributes can be specified for types and/or 4523declarations. This pragma is semantically equivalent to 4524@code{__attribute__((@var{attribute_name}))} (if @var{info} is not 4525specified) or @code{__attribute__((@var{attribute_name}(@var{info})))} 4526in GNU C, where @code{@var{attribute_name}} is recognized by the 4527compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine 4528specific macro. A string literal for the optional parameter @var{info} 4529is transformed into an identifier, which may make this pragma unusable 4530for some attributes. @xref{Target Attributes,, Defining target-specific 4531uses of @code{__attribute__}, gccint, GNU Compiler Collection (GCC) 4532Internals}, further information. 4533 4534@node Pragma Main 4535@unnumberedsec Pragma Main 4536@cindex OpenVMS 4537@findex Main 4538@noindent 4539Syntax: 4540 4541@smallexample @c ada 4542pragma Main 4543 (MAIN_OPTION [, MAIN_OPTION]); 4544 4545MAIN_OPTION ::= 4546 [Stack_Size =>] static_integer_EXPRESSION 4547| [Task_Stack_Size_Default =>] static_integer_EXPRESSION 4548| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 4549@end smallexample 4550 4551@noindent 4552This pragma is provided for compatibility with OpenVMS VAX Systems. It has 4553no effect in GNAT, other than being syntax checked. 4554 4555@node Pragma Main_Storage 4556@unnumberedsec Pragma Main_Storage 4557@cindex OpenVMS 4558@findex Main_Storage 4559@noindent 4560Syntax: 4561 4562@smallexample @c ada 4563pragma Main_Storage 4564 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 4565 4566MAIN_STORAGE_OPTION ::= 4567 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 4568| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 4569@end smallexample 4570 4571@noindent 4572This pragma is provided for compatibility with OpenVMS VAX Systems. It has 4573no effect in GNAT, other than being syntax checked. Note that the pragma 4574also has no effect in DEC Ada 83 for OpenVMS Alpha Systems. 4575 4576@node Pragma No_Body 4577@unnumberedsec Pragma No_Body 4578@findex No_Body 4579@noindent 4580Syntax: 4581 4582@smallexample @c ada 4583pragma No_Body; 4584@end smallexample 4585 4586@noindent 4587There are a number of cases in which a package spec does not require a body, 4588and in fact a body is not permitted. GNAT will not permit the spec to be 4589compiled if there is a body around. The pragma No_Body allows you to provide 4590a body file, even in a case where no body is allowed. The body file must 4591contain only comments and a single No_Body pragma. This is recognized by 4592the compiler as indicating that no body is logically present. 4593 4594This is particularly useful during maintenance when a package is modified in 4595such a way that a body needed before is no longer needed. The provision of a 4596dummy body with a No_Body pragma ensures that there is no interference from 4597earlier versions of the package body. 4598 4599@node Pragma No_Inline 4600@unnumberedsec Pragma No_Inline 4601@findex No_Inline 4602@noindent 4603Syntax: 4604 4605@smallexample @c ada 4606pragma No_Inline (NAME @{, NAME@}); 4607@end smallexample 4608 4609@noindent 4610This pragma suppresses inlining for the callable entity or the instances of 4611the generic subprogram designated by @var{NAME}, including inlining that 4612results from the use of pragma @code{Inline}. This pragma is always active, 4613in particular it is not subject to the use of option @option{-gnatn} or 4614@option{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and 4615pragma @code{Inline_Always} for the same @var{NAME}. 4616 4617@node Pragma No_Return 4618@unnumberedsec Pragma No_Return 4619@findex No_Return 4620@noindent 4621Syntax: 4622 4623@smallexample @c ada 4624pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); 4625@end smallexample 4626 4627@noindent 4628Each @var{procedure_LOCAL_NAME} argument must refer to one or more procedure 4629declarations in the current declarative part. A procedure to which this 4630pragma is applied may not contain any explicit @code{return} statements. 4631In addition, if the procedure contains any implicit returns from falling 4632off the end of a statement sequence, then execution of that implicit 4633return will cause Program_Error to be raised. 4634 4635One use of this pragma is to identify procedures whose only purpose is to raise 4636an exception. Another use of this pragma is to suppress incorrect warnings 4637about missing returns in functions, where the last statement of a function 4638statement sequence is a call to such a procedure. 4639 4640Note that in Ada 2005 mode, this pragma is part of the language. It is 4641available in all earlier versions of Ada as an implementation-defined 4642pragma. 4643 4644@node Pragma No_Run_Time 4645@unnumberedsec Pragma No_Run_Time 4646@findex No_Run_Time 4647@noindent 4648Syntax: 4649 4650@smallexample @c ada 4651pragma No_Run_Time; 4652@end smallexample 4653 4654@noindent 4655This is an obsolete configuration pragma that historically was used to 4656setup what is now called the "zero footprint" library. It causes any 4657library units outside this basic library to be ignored. The use of 4658this pragma has been superseded by the general configurable run-time 4659capability of @code{GNAT} where the compiler takes into account whatever 4660units happen to be accessible in the library. 4661 4662@node Pragma No_Strict_Aliasing 4663@unnumberedsec Pragma No_Strict_Aliasing 4664@findex No_Strict_Aliasing 4665@noindent 4666Syntax: 4667 4668@smallexample @c ada 4669pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 4670@end smallexample 4671 4672@noindent 4673@var{type_LOCAL_NAME} must refer to an access type 4674declaration in the current declarative part. The effect is to inhibit 4675strict aliasing optimization for the given type. The form with no 4676arguments is a configuration pragma which applies to all access types 4677declared in units to which the pragma applies. For a detailed 4678description of the strict aliasing optimization, and the situations 4679in which it must be suppressed, see @ref{Optimization and Strict 4680Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}. 4681 4682This pragma currently has no effects on access to unconstrained array types. 4683 4684@node Pragma Normalize_Scalars 4685@unnumberedsec Pragma Normalize_Scalars 4686@findex Normalize_Scalars 4687@noindent 4688Syntax: 4689 4690@smallexample @c ada 4691pragma Normalize_Scalars; 4692@end smallexample 4693 4694@noindent 4695This is a language defined pragma which is fully implemented in GNAT@. The 4696effect is to cause all scalar objects that are not otherwise initialized 4697to be initialized. The initial values are implementation dependent and 4698are as follows: 4699 4700@table @code 4701@item Standard.Character 4702@noindent 4703Objects whose root type is Standard.Character are initialized to 4704Character'Last unless the subtype range excludes NUL (in which case 4705NUL is used). This choice will always generate an invalid value if 4706one exists. 4707 4708@item Standard.Wide_Character 4709@noindent 4710Objects whose root type is Standard.Wide_Character are initialized to 4711Wide_Character'Last unless the subtype range excludes NUL (in which case 4712NUL is used). This choice will always generate an invalid value if 4713one exists. 4714 4715@item Standard.Wide_Wide_Character 4716@noindent 4717Objects whose root type is Standard.Wide_Wide_Character are initialized to 4718the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 4719which case NUL is used). This choice will always generate an invalid value if 4720one exists. 4721 4722@item Integer types 4723@noindent 4724Objects of an integer type are treated differently depending on whether 4725negative values are present in the subtype. If no negative values are 4726present, then all one bits is used as the initial value except in the 4727special case where zero is excluded from the subtype, in which case 4728all zero bits are used. This choice will always generate an invalid 4729value if one exists. 4730 4731For subtypes with negative values present, the largest negative number 4732is used, except in the unusual case where this largest negative number 4733is in the subtype, and the largest positive number is not, in which case 4734the largest positive value is used. This choice will always generate 4735an invalid value if one exists. 4736 4737@item Floating-Point Types 4738Objects of all floating-point types are initialized to all 1-bits. For 4739standard IEEE format, this corresponds to a NaN (not a number) which is 4740indeed an invalid value. 4741 4742@item Fixed-Point Types 4743Objects of all fixed-point types are treated as described above for integers, 4744with the rules applying to the underlying integer value used to represent 4745the fixed-point value. 4746 4747@item Modular types 4748Objects of a modular type are initialized to all one bits, except in 4749the special case where zero is excluded from the subtype, in which 4750case all zero bits are used. This choice will always generate an 4751invalid value if one exists. 4752 4753@item Enumeration types 4754Objects of an enumeration type are initialized to all one-bits, i.e.@: to 4755the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal 4756whose Pos value is zero, in which case a code of zero is used. This choice 4757will always generate an invalid value if one exists. 4758 4759@end table 4760 4761@node Pragma Obsolescent 4762@unnumberedsec Pragma Obsolescent 4763@findex Obsolescent 4764@noindent 4765Syntax: 4766 4767@smallexample @c ada 4768pragma Obsolescent; 4769 4770pragma Obsolescent ( 4771 [Message =>] static_string_EXPRESSION 4772[,[Version =>] Ada_05]]); 4773 4774pragma Obsolescent ( 4775 [Entity =>] NAME 4776[,[Message =>] static_string_EXPRESSION 4777[,[Version =>] Ada_05]] ); 4778@end smallexample 4779 4780@noindent 4781This pragma can occur immediately following a declaration of an entity, 4782including the case of a record component. If no Entity argument is present, 4783then this declaration is the one to which the pragma applies. If an Entity 4784parameter is present, it must either match the name of the entity in this 4785declaration, or alternatively, the pragma can immediately follow an enumeration 4786type declaration, where the Entity argument names one of the enumeration 4787literals. 4788 4789This pragma is used to indicate that the named entity 4790is considered obsolescent and should not be used. Typically this is 4791used when an API must be modified by eventually removing or modifying 4792existing subprograms or other entities. The pragma can be used at an 4793intermediate stage when the entity is still present, but will be 4794removed later. 4795 4796The effect of this pragma is to output a warning message on a reference to 4797an entity thus marked that the subprogram is obsolescent if the appropriate 4798warning option in the compiler is activated. If the Message parameter is 4799present, then a second warning message is given containing this text. In 4800addition, a reference to the entity is considered to be a violation of pragma 4801Restrictions (No_Obsolescent_Features). 4802 4803This pragma can also be used as a program unit pragma for a package, 4804in which case the entity name is the name of the package, and the 4805pragma indicates that the entire package is considered 4806obsolescent. In this case a client @code{with}'ing such a package 4807violates the restriction, and the @code{with} statement is 4808flagged with warnings if the warning option is set. 4809 4810If the Version parameter is present (which must be exactly 4811the identifier Ada_05, no other argument is allowed), then the 4812indication of obsolescence applies only when compiling in Ada 2005 4813mode. This is primarily intended for dealing with the situations 4814in the predefined library where subprograms or packages 4815have become defined as obsolescent in Ada 2005 4816(e.g.@: in Ada.Characters.Handling), but may be used anywhere. 4817 4818The following examples show typical uses of this pragma: 4819 4820@smallexample @c ada 4821package p is 4822 pragma Obsolescent (p, Message => "use pp instead of p"); 4823end p; 4824 4825package q is 4826 procedure q2; 4827 pragma Obsolescent ("use q2new instead"); 4828 4829 type R is new integer; 4830 pragma Obsolescent 4831 (Entity => R, 4832 Message => "use RR in Ada 2005", 4833 Version => Ada_05); 4834 4835 type M is record 4836 F1 : Integer; 4837 F2 : Integer; 4838 pragma Obsolescent; 4839 F3 : Integer; 4840 end record; 4841 4842 type E is (a, bc, 'd', quack); 4843 pragma Obsolescent (Entity => bc) 4844 pragma Obsolescent (Entity => 'd') 4845 4846 function "+" 4847 (a, b : character) return character; 4848 pragma Obsolescent (Entity => "+"); 4849end; 4850@end smallexample 4851 4852@noindent 4853Note that, as for all pragmas, if you use a pragma argument identifier, 4854then all subsequent parameters must also use a pragma argument identifier. 4855So if you specify "Entity =>" for the Entity argument, and a Message 4856argument is present, it must be preceded by "Message =>". 4857 4858@node Pragma Optimize_Alignment 4859@unnumberedsec Pragma Optimize_Alignment 4860@findex Optimize_Alignment 4861@cindex Alignment, default settings 4862@noindent 4863Syntax: 4864 4865@smallexample @c ada 4866pragma Optimize_Alignment (TIME | SPACE | OFF); 4867@end smallexample 4868 4869@noindent 4870This is a configuration pragma which affects the choice of default alignments 4871for types and objects where no alignment is explicitly specified. There is a 4872time/space trade-off in the selection of these values. Large alignments result 4873in more efficient code, at the expense of larger data space, since sizes have 4874to be increased to match these alignments. Smaller alignments save space, but 4875the access code is slower. The normal choice of default alignments for types 4876and individual alignment promotions for objects (which is what you get if you 4877do not use this pragma, or if you use an argument of OFF), tries to balance 4878these two requirements. 4879 4880Specifying SPACE causes smaller default alignments to be chosen in two cases. 4881First any packed record is given an alignment of 1. Second, if a size is given 4882for the type, then the alignment is chosen to avoid increasing this size. For 4883example, consider: 4884 4885@smallexample @c ada 4886 type R is record 4887 X : Integer; 4888 Y : Character; 4889 end record; 4890 4891 for R'Size use 5*8; 4892@end smallexample 4893 4894@noindent 4895In the default mode, this type gets an alignment of 4, so that access to the 4896Integer field X are efficient. But this means that objects of the type end up 4897with a size of 8 bytes. This is a valid choice, since sizes of objects are 4898allowed to be bigger than the size of the type, but it can waste space if for 4899example fields of type R appear in an enclosing record. If the above type is 4900compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. 4901 4902However, there is one case in which SPACE is ignored. If a variable length 4903record (that is a discriminated record with a component which is an array 4904whose length depends on a discriminant), has a pragma Pack, then it is not 4905in general possible to set the alignment of such a record to one, so the 4906pragma is ignored in this case (with a warning). 4907 4908Specifying SPACE also disables alignment promotions for standalone objects, 4909which occur when the compiler increases the alignment of a specific object 4910without changing the alignment of its type. 4911 4912Specifying TIME causes larger default alignments to be chosen in the case of 4913small types with sizes that are not a power of 2. For example, consider: 4914 4915@smallexample @c ada 4916 type R is record 4917 A : Character; 4918 B : Character; 4919 C : Boolean; 4920 end record; 4921 4922 pragma Pack (R); 4923 for R'Size use 17; 4924@end smallexample 4925 4926@noindent 4927The default alignment for this record is normally 1, but if this type is 4928compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set 4929to 4, which wastes space for objects of the type, since they are now 4 bytes 4930long, but results in more efficient access when the whole record is referenced. 4931 4932As noted above, this is a configuration pragma, and there is a requirement 4933that all units in a partition be compiled with a consistent setting of the 4934optimization setting. This would normally be achieved by use of a configuration 4935pragma file containing the appropriate setting. The exception to this rule is 4936that units with an explicit configuration pragma in the same file as the source 4937unit are excluded from the consistency check, as are all predefined units. The 4938latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 4939pragma appears at the start of the file. 4940 4941@node Pragma Ordered 4942@unnumberedsec Pragma Ordered 4943@findex Ordered 4944@findex pragma @code{Ordered} 4945@noindent 4946Syntax: 4947 4948@smallexample @c ada 4949pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 4950@end smallexample 4951 4952@noindent 4953Most enumeration types are from a conceptual point of view unordered. 4954For example, consider: 4955 4956@smallexample @c ada 4957type Color is (Red, Blue, Green, Yellow); 4958@end smallexample 4959 4960@noindent 4961By Ada semantics @code{Blue > Red} and @code{Green > Blue}, 4962but really these relations make no sense; the enumeration type merely 4963specifies a set of possible colors, and the order is unimportant. 4964 4965For unordered enumeration types, it is generally a good idea if 4966clients avoid comparisons (other than equality or inequality) and 4967explicit ranges. (A @emph{client} is a unit where the type is referenced, 4968other than the unit where the type is declared, its body, and its subunits.) 4969For example, if code buried in some client says: 4970 4971@smallexample @c ada 4972if Current_Color < Yellow then ... 4973if Current_Color in Blue .. Green then ... 4974@end smallexample 4975 4976@noindent 4977then the client code is relying on the order, which is undesirable. 4978It makes the code hard to read and creates maintenance difficulties if 4979entries have to be added to the enumeration type. Instead, 4980the code in the client should list the possibilities, or an 4981appropriate subtype should be declared in the unit that declares 4982the original enumeration type. E.g., the following subtype could 4983be declared along with the type @code{Color}: 4984 4985@smallexample @c ada 4986subtype RBG is Color range Red .. Green; 4987@end smallexample 4988 4989@noindent 4990and then the client could write: 4991 4992@smallexample @c ada 4993if Current_Color in RBG then ... 4994if Current_Color = Blue or Current_Color = Green then ... 4995@end smallexample 4996 4997@noindent 4998However, some enumeration types are legitimately ordered from a conceptual 4999point of view. For example, if you declare: 5000 5001@smallexample @c ada 5002type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 5003@end smallexample 5004 5005@noindent 5006then the ordering imposed by the language is reasonable, and 5007clients can depend on it, writing for example: 5008 5009@smallexample @c ada 5010if D in Mon .. Fri then ... 5011if D < Wed then ... 5012@end smallexample 5013 5014@noindent 5015The pragma @option{Ordered} is provided to mark enumeration types that 5016are conceptually ordered, alerting the reader that clients may depend 5017on the ordering. GNAT provides a pragma to mark enumerations as ordered 5018rather than one to mark them as unordered, since in our experience, 5019the great majority of enumeration types are conceptually unordered. 5020 5021The types @code{Boolean}, @code{Character}, @code{Wide_Character}, 5022and @code{Wide_Wide_Character} 5023are considered to be ordered types, so each is declared with a 5024pragma @code{Ordered} in package @code{Standard}. 5025 5026Normally pragma @code{Ordered} serves only as documentation and a guide for 5027coding standards, but GNAT provides a warning switch @option{-gnatw.u} that 5028requests warnings for inappropriate uses (comparisons and explicit 5029subranges) for unordered types. If this switch is used, then any 5030enumeration type not marked with pragma @code{Ordered} will be considered 5031as unordered, and will generate warnings for inappropriate uses. 5032 5033For additional information please refer to the description of the 5034@option{-gnatw.u} switch in the @value{EDITION} User's Guide. 5035 5036@node Pragma Overflow_Mode 5037@unnumberedsec Pragma Overflow_Mode 5038@findex Overflow checks 5039@findex Overflow mode 5040@findex pragma @code{Overflow_Mode} 5041@noindent 5042Syntax: 5043 5044@smallexample @c ada 5045pragma Overflow_Mode 5046 ( [General =>] MODE 5047 [,[Assertions =>] MODE]); 5048 5049MODE ::= STRICT | MINIMIZED | ELIMINATED 5050@end smallexample 5051 5052@noindent 5053This pragma sets the current overflow mode to the given setting. For details 5054of the meaning of these modes, please refer to the 5055``Overflow Check Handling in GNAT'' appendix in the 5056@value{EDITION} User's Guide. If only the @code{General} parameter is present, 5057the given mode applies to all expressions. If both parameters are present, 5058the @code{General} mode applies to expressions outside assertions, and 5059the @code{Eliminated} mode applies to expressions within assertions. 5060 5061The case of the @code{MODE} parameter is ignored, 5062so @code{MINIMIZED}, @code{Minimized} and 5063@code{minimized} all have the same effect. 5064 5065The @code{Overflow_Mode} pragma has the same scoping and placement 5066rules as pragma @code{Suppress}, so it can occur either as a 5067configuration pragma, specifying a default for the whole 5068program, or in a declarative scope, where it applies to the 5069remaining declarations and statements in that scope. 5070 5071The pragma @code{Suppress (Overflow_Check)} suppresses 5072overflow checking, but does not affect the overflow mode. 5073 5074The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) 5075overflow checking, but does not affect the overflow mode. 5076 5077@node Pragma Overriding_Renamings 5078@unnumberedsec Pragma Overriding_Renamings 5079@findex Overriding_Renamings 5080@cindex Rational profile 5081@cindex Rational compatibility 5082@noindent 5083Syntax: 5084 5085@smallexample @c ada 5086pragma Overriding_Renamings; 5087@end smallexample 5088 5089@noindent 5090This is a GNAT configuration pragma to simplify porting 5091legacy code accepted by the Rational 5092Ada compiler. In the presence of this pragma, a renaming declaration that 5093renames an inherited operation declared in the same scope is legal if selected 5094notation is used as in: 5095 5096@smallexample @c ada 5097pragma Overriding_Renamings; 5098... 5099package R is 5100 function F (..); 5101 ... 5102 function F (..) renames R.F; 5103end R; 5104@end smallexample 5105 5106even though 5107RM 8.3 (15) stipulates that an overridden operation is not visible within the 5108declaration of the overriding operation. 5109 5110@node Pragma Partition_Elaboration_Policy 5111@unnumberedsec Pragma Partition_Elaboration_Policy 5112@findex Partition_Elaboration_Policy 5113@noindent 5114Syntax: 5115 5116@smallexample @c ada 5117pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 5118 5119POLICY_IDENTIFIER ::= Concurrent | Sequential 5120@end smallexample 5121 5122@noindent 5123This pragma is standard in Ada 2005, but is available in all earlier 5124versions of Ada as an implementation-defined pragma. 5125See Ada 2012 Reference Manual for details. 5126 5127@node Pragma Passive 5128@unnumberedsec Pragma Passive 5129@findex Passive 5130@noindent 5131Syntax: 5132 5133@smallexample @c ada 5134pragma Passive [(Semaphore | No)]; 5135@end smallexample 5136 5137@noindent 5138Syntax checked, but otherwise ignored by GNAT@. This is recognized for 5139compatibility with DEC Ada 83 implementations, where it is used within a 5140task definition to request that a task be made passive. If the argument 5141@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 5142treats the pragma as an assertion that the containing task is passive 5143and that optimization of context switch with this task is permitted and 5144desired. If the argument @code{No} is present, the task must not be 5145optimized. GNAT does not attempt to optimize any tasks in this manner 5146(since protected objects are available in place of passive tasks). 5147 5148For more information on the subject of passive tasks, see the section 5149``Passive Task Optimization'' in the GNAT Users Guide. 5150 5151@node Pragma Persistent_BSS 5152@unnumberedsec Pragma Persistent_BSS 5153@findex Persistent_BSS 5154@noindent 5155Syntax: 5156 5157@smallexample @c ada 5158pragma Persistent_BSS [(LOCAL_NAME)] 5159@end smallexample 5160 5161@noindent 5162This pragma allows selected objects to be placed in the @code{.persistent_bss} 5163section. On some targets the linker and loader provide for special 5164treatment of this section, allowing a program to be reloaded without 5165affecting the contents of this data (hence the name persistent). 5166 5167There are two forms of usage. If an argument is given, it must be the 5168local name of a library level object, with no explicit initialization 5169and whose type is potentially persistent. If no argument is given, then 5170the pragma is a configuration pragma, and applies to all library level 5171objects with no explicit initialization of potentially persistent types. 5172 5173A potentially persistent type is a scalar type, or a non-tagged, 5174non-discriminated record, all of whose components have no explicit 5175initialization and are themselves of a potentially persistent type, 5176or an array, all of whose constraints are static, and whose component 5177type is potentially persistent. 5178 5179If this pragma is used on a target where this feature is not supported, 5180then the pragma will be ignored. See also @code{pragma Linker_Section}. 5181 5182@node Pragma Polling 5183@unnumberedsec Pragma Polling 5184@findex Polling 5185@noindent 5186Syntax: 5187 5188@smallexample @c ada 5189pragma Polling (ON | OFF); 5190@end smallexample 5191 5192@noindent 5193This pragma controls the generation of polling code. This is normally off. 5194If @code{pragma Polling (ON)} is used then periodic calls are generated to 5195the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the 5196runtime library, and can be found in file @file{a-excpol.adb}. 5197 5198Pragma @code{Polling} can appear as a configuration pragma (for example it 5199can be placed in the @file{gnat.adc} file) to enable polling globally, or it 5200can be used in the statement or declaration sequence to control polling 5201more locally. 5202 5203A call to the polling routine is generated at the start of every loop and 5204at the start of every subprogram call. This guarantees that the @code{Poll} 5205routine is called frequently, and places an upper bound (determined by 5206the complexity of the code) on the period between two @code{Poll} calls. 5207 5208The primary purpose of the polling interface is to enable asynchronous 5209aborts on targets that cannot otherwise support it (for example Windows 5210NT), but it may be used for any other purpose requiring periodic polling. 5211The standard version is null, and can be replaced by a user program. This 5212will require re-compilation of the @code{Ada.Exceptions} package that can 5213be found in files @file{a-except.ads} and @file{a-except.adb}. 5214 5215A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT 5216distribution) is used to enable the asynchronous abort capability on 5217targets that do not normally support the capability. The version of 5218@code{Poll} in this file makes a call to the appropriate runtime routine 5219to test for an abort condition. 5220 5221Note that polling can also be enabled by use of the @option{-gnatP} switch. 5222@xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for 5223details. 5224 5225@node Pragma Post 5226@unnumberedsec Pragma Post 5227@cindex Post 5228@cindex Checks, postconditions 5229@findex Postconditions 5230@noindent 5231Syntax: 5232 5233@smallexample @c ada 5234pragma Post (Boolean_Expression); 5235@end smallexample 5236 5237@noindent 5238The @code{Post} pragma is intended to be an exact replacement for 5239the language-defined 5240@code{Post} aspect, and shares its restrictions and semantics. 5241It must appear either immediately following the corresponding 5242subprogram declaration (only other pragmas may intervene), or 5243if there is no separate subprogram declaration, then it can 5244appear at the start of the declarations in a subprogram body 5245(preceded only by other pragmas). 5246 5247@node Pragma Postcondition 5248@unnumberedsec Pragma Postcondition 5249@cindex Postcondition 5250@cindex Checks, postconditions 5251@findex Postconditions 5252@noindent 5253Syntax: 5254 5255@smallexample @c ada 5256pragma Postcondition ( 5257 [Check =>] Boolean_Expression 5258 [,[Message =>] String_Expression]); 5259@end smallexample 5260 5261@noindent 5262The @code{Postcondition} pragma allows specification of automatic 5263postcondition checks for subprograms. These checks are similar to 5264assertions, but are automatically inserted just prior to the return 5265statements of the subprogram with which they are associated (including 5266implicit returns at the end of procedure bodies and associated 5267exception handlers). 5268 5269In addition, the boolean expression which is the condition which 5270must be true may contain references to function'Result in the case 5271of a function to refer to the returned value. 5272 5273@code{Postcondition} pragmas may appear either immediately following the 5274(separate) declaration of a subprogram, or at the start of the 5275declarations of a subprogram body. Only other pragmas may intervene 5276(that is appear between the subprogram declaration and its 5277postconditions, or appear before the postcondition in the 5278declaration sequence in a subprogram body). In the case of a 5279postcondition appearing after a subprogram declaration, the 5280formal arguments of the subprogram are visible, and can be 5281referenced in the postcondition expressions. 5282 5283The postconditions are collected and automatically tested just 5284before any return (implicit or explicit) in the subprogram body. 5285A postcondition is only recognized if postconditions are active 5286at the time the pragma is encountered. The compiler switch @option{gnata} 5287turns on all postconditions by default, and pragma @code{Check_Policy} 5288with an identifier of @code{Postcondition} can also be used to 5289control whether postconditions are active. 5290 5291The general approach is that postconditions are placed in the spec 5292if they represent functional aspects which make sense to the client. 5293For example we might have: 5294 5295@smallexample @c ada 5296 function Direction return Integer; 5297 pragma Postcondition 5298 (Direction'Result = +1 5299 or else 5300 Direction'Result = -1); 5301@end smallexample 5302 5303@noindent 5304which serves to document that the result must be +1 or -1, and 5305will test that this is the case at run time if postcondition 5306checking is active. 5307 5308Postconditions within the subprogram body can be used to 5309check that some internal aspect of the implementation, 5310not visible to the client, is operating as expected. 5311For instance if a square root routine keeps an internal 5312counter of the number of times it is called, then we 5313might have the following postcondition: 5314 5315@smallexample @c ada 5316 Sqrt_Calls : Natural := 0; 5317 5318 function Sqrt (Arg : Float) return Float is 5319 pragma Postcondition 5320 (Sqrt_Calls = Sqrt_Calls'Old + 1); 5321 ... 5322 end Sqrt 5323@end smallexample 5324 5325@noindent 5326As this example, shows, the use of the @code{Old} attribute 5327is often useful in postconditions to refer to the state on 5328entry to the subprogram. 5329 5330Note that postconditions are only checked on normal returns 5331from the subprogram. If an abnormal return results from 5332raising an exception, then the postconditions are not checked. 5333 5334If a postcondition fails, then the exception 5335@code{System.Assertions.Assert_Failure} is raised. If 5336a message argument was supplied, then the given string 5337will be used as the exception message. If no message 5338argument was supplied, then the default message has 5339the form "Postcondition failed at file:line". The 5340exception is raised in the context of the subprogram 5341body, so it is possible to catch postcondition failures 5342within the subprogram body itself. 5343 5344Within a package spec, normal visibility rules 5345in Ada would prevent forward references within a 5346postcondition pragma to functions defined later in 5347the same package. This would introduce undesirable 5348ordering constraints. To avoid this problem, all 5349postcondition pragmas are analyzed at the end of 5350the package spec, allowing forward references. 5351 5352The following example shows that this even allows 5353mutually recursive postconditions as in: 5354 5355@smallexample @c ada 5356package Parity_Functions is 5357 function Odd (X : Natural) return Boolean; 5358 pragma Postcondition 5359 (Odd'Result = 5360 (x = 1 5361 or else 5362 (x /= 0 and then Even (X - 1)))); 5363 5364 function Even (X : Natural) return Boolean; 5365 pragma Postcondition 5366 (Even'Result = 5367 (x = 0 5368 or else 5369 (x /= 1 and then Odd (X - 1)))); 5370 5371end Parity_Functions; 5372@end smallexample 5373 5374@noindent 5375There are no restrictions on the complexity or form of 5376conditions used within @code{Postcondition} pragmas. 5377The following example shows that it is even possible 5378to verify performance behavior. 5379 5380@smallexample @c ada 5381package Sort is 5382 5383 Performance : constant Float; 5384 -- Performance constant set by implementation 5385 -- to match target architecture behavior. 5386 5387 procedure Treesort (Arg : String); 5388 -- Sorts characters of argument using N*logN sort 5389 pragma Postcondition 5390 (Float (Clock - Clock'Old) <= 5391 Float (Arg'Length) * 5392 log (Float (Arg'Length)) * 5393 Performance); 5394end Sort; 5395@end smallexample 5396 5397@noindent 5398Note: postcondition pragmas associated with subprograms that are 5399marked as Inline_Always, or those marked as Inline with front-end 5400inlining (-gnatN option set) are accepted and legality-checked 5401by the compiler, but are ignored at run-time even if postcondition 5402checking is enabled. 5403 5404Note that pragma @code{Postcondition} differs from the language-defined 5405@code{Post} aspect (and corresponding @code{Post} pragma) in allowing 5406multiple occurrences, allowing occurences in the body even if there 5407is a separate spec, and allowing a second string parameter, and the 5408use of the pragma identifier @code{Check}. Historically, pragma 5409@code{Postcondition} was implemented prior to the development of 5410Ada 2012, and has been retained in its original form for 5411compatibility purposes. 5412 5413@node Pragma Post_Class 5414@unnumberedsec Pragma Post_Class 5415@cindex Post 5416@cindex Checks, postconditions 5417@findex Postconditions 5418@noindent 5419Syntax: 5420 5421@smallexample @c ada 5422pragma Post_Class (Boolean_Expression); 5423@end smallexample 5424 5425@noindent 5426The @code{Post_Class} pragma is intended to be an exact replacement for 5427the language-defined 5428@code{Post'Class} aspect, and shares its restrictions and semantics. 5429It must appear either immediately following the corresponding 5430subprogram declaration (only other pragmas may intervene), or 5431if there is no separate subprogram declaration, then it can 5432appear at the start of the declarations in a subprogram body 5433(preceded only by other pragmas). 5434 5435Note: This pragma is called @code{Post_Class} rather than 5436@code{Post'Class} because the latter would not be strictly 5437conforming to the allowed syntax for pragmas. The motivation 5438for provinding pragmas equivalent to the aspects is to allow a program 5439to be written using the pragmas, and then compiled if necessary 5440using an Ada compiler that does not recognize the pragmas or 5441aspects, but is prepared to ignore the pragmas. The assertion 5442policy that controls this pragma is @code{Post'Class}, not 5443@code{Post_Class}. 5444 5445@node Pragma Pre 5446@unnumberedsec Pragma Pre 5447@cindex Pre 5448@cindex Checks, preconditions 5449@findex Preconditions 5450@noindent 5451Syntax: 5452 5453@smallexample @c ada 5454pragma Pre (Boolean_Expression); 5455@end smallexample 5456 5457@noindent 5458The @code{Pre} pragma is intended to be an exact replacement for 5459the language-defined 5460@code{Pre} aspect, and shares its restrictions and semantics. 5461It must appear either immediately following the corresponding 5462subprogram declaration (only other pragmas may intervene), or 5463if there is no separate subprogram declaration, then it can 5464appear at the start of the declarations in a subprogram body 5465(preceded only by other pragmas). 5466 5467@node Pragma Precondition 5468@unnumberedsec Pragma Precondition 5469@cindex Preconditions 5470@cindex Checks, preconditions 5471@findex Preconditions 5472@noindent 5473Syntax: 5474 5475@smallexample @c ada 5476pragma Precondition ( 5477 [Check =>] Boolean_Expression 5478 [,[Message =>] String_Expression]); 5479@end smallexample 5480 5481@noindent 5482The @code{Precondition} pragma is similar to @code{Postcondition} 5483except that the corresponding checks take place immediately upon 5484entry to the subprogram, and if a precondition fails, the exception 5485is raised in the context of the caller, and the attribute 'Result 5486cannot be used within the precondition expression. 5487 5488Otherwise, the placement and visibility rules are identical to those 5489described for postconditions. The following is an example of use 5490within a package spec: 5491 5492@smallexample @c ada 5493package Math_Functions is 5494 ... 5495 function Sqrt (Arg : Float) return Float; 5496 pragma Precondition (Arg >= 0.0) 5497 ... 5498end Math_Functions; 5499@end smallexample 5500 5501@noindent 5502@code{Precondition} pragmas may appear either immediately following the 5503(separate) declaration of a subprogram, or at the start of the 5504declarations of a subprogram body. Only other pragmas may intervene 5505(that is appear between the subprogram declaration and its 5506postconditions, or appear before the postcondition in the 5507declaration sequence in a subprogram body). 5508 5509Note: precondition pragmas associated with subprograms that are 5510marked as Inline_Always, or those marked as Inline with front-end 5511inlining (-gnatN option set) are accepted and legality-checked 5512by the compiler, but are ignored at run-time even if precondition 5513checking is enabled. 5514 5515Note that pragma @code{Precondition} differs from the language-defined 5516@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing 5517multiple occurrences, allowing occurences in the body even if there 5518is a separate spec, and allowing a second string parameter, and the 5519use of the pragma identifier @code{Check}. Historically, pragma 5520@code{Precondition} was implemented prior to the development of 5521Ada 2012, and has been retained in its original form for 5522compatibility purposes. 5523 5524@node Pragma Predicate 5525@unnumberedsec Pragma Predicate 5526@findex Predicate 5527@findex Predicate pragma 5528@noindent 5529Syntax: 5530 5531@smallexample @c ada 5532pragma Predicate 5533 ([Entity =>] type_LOCAL_NAME, 5534 [Check =>] EXPRESSION); 5535@end smallexample 5536 5537@noindent 5538This pragma (available in all versions of Ada in GNAT) encompasses both 5539the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in 5540Ada 2012. A predicate is regarded as static if it has an allowed form 5541for @code{Static_Predicate} and is otherwise treated as a 5542@code{Dynamic_Predicate}. Otherwise, predicates specified by this 5543pragma behave exactly as described in the Ada 2012 reference manual. 5544For example, if we have 5545 5546@smallexample @c ada 5547type R is range 1 .. 10; 5548subtype S is R; 5549pragma Predicate (Entity => S, Check => S not in 4 .. 6); 5550subtype Q is R 5551pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); 5552@end smallexample 5553 5554@noindent 5555the effect is identical to the following Ada 2012 code: 5556 5557@smallexample @c ada 5558type R is range 1 .. 10; 5559subtype S is R with 5560 Static_Predicate => S not in 4 .. 6; 5561subtype Q is R with 5562 Dynamic_Predicate => F(Q) or G(Q); 5563@end smallexample 5564 5565Note that there is are no pragmas @code{Dynamic_Predicate} 5566or @code{Static_Predicate}. That is 5567because these pragmas would affect legality and semantics of 5568the program and thus do not have a neutral effect if ignored. 5569The motivation behind providing pragmas equivalent to 5570corresponding aspects is to allow a program to be written 5571using the pragmas, and then compiled with a compiler that 5572will ignore the pragmas. That doesn't work in the case of 5573static and dynamic predicates, since if the corresponding 5574pragmas are ignored, then the behavior of the program is 5575fundamentally changed (for example a membership test 5576@code{A in B} would not take into account a predicate 5577defined for subtype B). When following this approach, the 5578use of predicates should be avoided. 5579 5580@node Pragma Preelaborable_Initialization 5581@unnumberedsec Pragma Preelaborable_Initialization 5582@findex Preelaborable_Initialization 5583@noindent 5584Syntax: 5585 5586@smallexample @c ada 5587pragma Preelaborable_Initialization (DIRECT_NAME); 5588@end smallexample 5589 5590@noindent 5591This pragma is standard in Ada 2005, but is available in all earlier 5592versions of Ada as an implementation-defined pragma. 5593See Ada 2012 Reference Manual for details. 5594 5595@node Pragma Preelaborate_05 5596@unnumberedsec Pragma Preelaborate_05 5597@findex Preelaborate_05 5598@noindent 5599Syntax: 5600 5601@smallexample @c ada 5602pragma Preelaborate_05 [(library_unit_NAME)]; 5603@end smallexample 5604 5605@noindent 5606This pragma is only available in GNAT mode (@option{-gnatg} switch set) 5607and is intended for use in the standard run-time library only. It has 5608no effect in Ada 83 or Ada 95 mode, but is 5609equivalent to @code{pragma Prelaborate} when operating in later 5610Ada versions. This is used to handle some cases where packages 5611not previously preelaborable became so in Ada 2005. 5612 5613@node Pragma Pre_Class 5614@unnumberedsec Pragma Pre_Class 5615@cindex Pre_Class 5616@cindex Checks, preconditions 5617@findex Preconditions 5618@noindent 5619Syntax: 5620 5621@smallexample @c ada 5622pragma Pre_Class (Boolean_Expression); 5623@end smallexample 5624 5625@noindent 5626The @code{Pre_Class} pragma is intended to be an exact replacement for 5627the language-defined 5628@code{Pre'Class} aspect, and shares its restrictions and semantics. 5629It must appear either immediately following the corresponding 5630subprogram declaration (only other pragmas may intervene), or 5631if there is no separate subprogram declaration, then it can 5632appear at the start of the declarations in a subprogram body 5633(preceded only by other pragmas). 5634 5635Note: This pragma is called @code{Pre_Class} rather than 5636@code{Pre'Class} because the latter would not be strictly 5637conforming to the allowed syntax for pragmas. The motivation 5638for providing pragmas equivalent to the aspects is to allow a program 5639to be written using the pragmas, and then compiled if necessary 5640using an Ada compiler that does not recognize the pragmas or 5641aspects, but is prepared to ignore the pragmas. The assertion 5642policy that controls this pragma is @code{Pre'Class}, not 5643@code{Pre_Class}. 5644 5645@node Pragma Priority_Specific_Dispatching 5646@unnumberedsec Pragma Priority_Specific_Dispatching 5647@findex Priority_Specific_Dispatching 5648@noindent 5649Syntax: 5650 5651@smallexample @c ada 5652pragma Priority_Specific_Dispatching ( 5653 POLICY_IDENTIFIER, 5654 first_priority_EXPRESSION, 5655 last_priority_EXPRESSION) 5656 5657POLICY_IDENTIFIER ::= 5658 EDF_Across_Priorities | 5659 FIFO_Within_Priorities | 5660 Non_Preemptive_Within_Priorities | 5661 Round_Robin_Within_Priorities 5662@end smallexample 5663 5664@noindent 5665This pragma is standard in Ada 2005, but is available in all earlier 5666versions of Ada as an implementation-defined pragma. 5667See Ada 2012 Reference Manual for details. 5668 5669@node Pragma Profile 5670@unnumberedsec Pragma Profile 5671@findex Profile 5672@noindent 5673Syntax: 5674 5675@smallexample @c ada 5676pragma Profile (Ravenscar | Restricted | Rational); 5677@end smallexample 5678 5679@noindent 5680This pragma is standard in Ada 2005, but is available in all earlier 5681versions of Ada as an implementation-defined pragma. This is a 5682configuration pragma that establishes a set of configiuration pragmas 5683that depend on the argument. @code{Ravenscar} is standard in Ada 2005. 5684The other two possibilities (@code{Restricted} or @code{Rational}) 5685are implementation-defined. The set of configuration pragmas 5686is defined in the following sections. 5687 5688@itemize 5689 5690@item Pragma Profile (Ravenscar) 5691@findex Ravenscar 5692@noindent 5693 5694The @code{Ravenscar} profile is standard in Ada 2005, 5695but is available in all earlier 5696versions of Ada as an implementation-defined pragma. This profile 5697establishes the following set of configuration pragmas: 5698 5699@table @code 5700@item Task_Dispatching_Policy (FIFO_Within_Priorities) 5701[RM D.2.2] Tasks are dispatched following a preemptive 5702priority-ordered scheduling policy. 5703 5704@item Locking_Policy (Ceiling_Locking) 5705[RM D.3] While tasks and interrupts execute a protected action, they inherit 5706the ceiling priority of the corresponding protected object. 5707 5708@item Detect_Blocking 5709This pragma forces the detection of potentially blocking operations within a 5710protected operation, and to raise Program_Error if that happens. 5711@end table 5712@noindent 5713 5714plus the following set of restrictions: 5715 5716@table @code 5717@item Max_Entry_Queue_Length => 1 5718No task can be queued on a protected entry. 5719@item Max_Protected_Entries => 1 5720@item Max_Task_Entries => 0 5721No rendezvous statements are allowed. 5722@item No_Abort_Statements 5723@item No_Dynamic_Attachment 5724@item No_Dynamic_Priorities 5725@item No_Implicit_Heap_Allocations 5726@item No_Local_Protected_Objects 5727@item No_Local_Timing_Events 5728@item No_Protected_Type_Allocators 5729@item No_Relative_Delay 5730@item No_Requeue_Statements 5731@item No_Select_Statements 5732@item No_Specific_Termination_Handlers 5733@item No_Task_Allocators 5734@item No_Task_Hierarchy 5735@item No_Task_Termination 5736@item Simple_Barriers 5737@end table 5738@noindent 5739 5740The Ravenscar profile also includes the following restrictions that specify 5741that there are no semantic dependences on the corresponding predefined 5742packages: 5743 5744@table @code 5745@item No_Dependence => Ada.Asynchronous_Task_Control 5746@item No_Dependence => Ada.Calendar 5747@item No_Dependence => Ada.Execution_Time.Group_Budget 5748@item No_Dependence => Ada.Execution_Time.Timers 5749@item No_Dependence => Ada.Task_Attributes 5750@item No_Dependence => System.Multiprocessors.Dispatching_Domains 5751@end table 5752 5753@noindent 5754 5755This set of configuration pragmas and restrictions correspond to the 5756definition of the ``Ravenscar Profile'' for limited tasking, devised and 5757published by the @cite{International Real-Time Ada Workshop}, 1997, 5758and whose most recent description is available at 5759@url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. 5760 5761The original definition of the profile was revised at subsequent IRTAW 5762meetings. It has been included in the ISO 5763@cite{Guide for the Use of the Ada Programming Language in High 5764Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in 5765the next revision of the standard. The formal definition given by 5766the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 5767AI-305) available at 5768@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and 5769@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. 5770 5771The above set is a superset of the restrictions provided by pragma 5772@code{Profile (Restricted)}, it includes six additional restrictions 5773(@code{Simple_Barriers}, @code{No_Select_Statements}, 5774@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, 5775@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 5776that pragma @code{Profile (Ravenscar)}, like the pragma 5777@code{Profile (Restricted)}, 5778automatically causes the use of a simplified, 5779more efficient version of the tasking run-time system. 5780 5781@item Pragma Profile (Restricted) 5782@findex Restricted Run Time 5783@noindent 5784This profile corresponds to the GNAT restricted run time. It 5785establishes the following set of restrictions: 5786 5787@itemize @bullet 5788@item No_Abort_Statements 5789@item No_Entry_Queue 5790@item No_Task_Hierarchy 5791@item No_Task_Allocators 5792@item No_Dynamic_Priorities 5793@item No_Terminate_Alternatives 5794@item No_Dynamic_Attachment 5795@item No_Protected_Type_Allocators 5796@item No_Local_Protected_Objects 5797@item No_Requeue_Statements 5798@item No_Task_Attributes_Package 5799@item Max_Asynchronous_Select_Nesting = 0 5800@item Max_Task_Entries = 0 5801@item Max_Protected_Entries = 1 5802@item Max_Select_Alternatives = 0 5803@end itemize 5804 5805@noindent 5806This set of restrictions causes the automatic selection of a simplified 5807version of the run time that provides improved performance for the 5808limited set of tasking functionality permitted by this set of restrictions. 5809 5810@item Pragma Profile (Rational) 5811@findex Rational compatibility mode 5812@noindent 5813The Rational profile is intended to facilitate porting legacy code that 5814compiles with the Rational APEX compiler, even when the code includes non- 5815conforming Ada constructs. The profile enables the following three pragmas: 5816 5817@itemize @bullet 5818@item pragma Implicit_Packing 5819@item pragma Overriding_Renamings 5820@item pragma Use_VADS_Size 5821@end itemize 5822 5823@end itemize 5824 5825@node Pragma Profile_Warnings 5826@unnumberedsec Pragma Profile_Warnings 5827@findex Profile_Warnings 5828@noindent 5829Syntax: 5830 5831@smallexample @c ada 5832pragma Profile_Warnings (Ravenscar | Restricted | Rational); 5833@end smallexample 5834 5835@noindent 5836This is an implementation-defined pragma that is similar in 5837effect to @code{pragma Profile} except that instead of 5838generating @code{Restrictions} pragmas, it generates 5839@code{Restriction_Warnings} pragmas. The result is that 5840violations of the profile generate warning messages instead 5841of error messages. 5842 5843@node Pragma Propagate_Exceptions 5844@unnumberedsec Pragma Propagate_Exceptions 5845@cindex Interfacing to C++ 5846@findex Propagate_Exceptions 5847@noindent 5848Syntax: 5849 5850@smallexample @c ada 5851pragma Propagate_Exceptions; 5852@end smallexample 5853 5854@noindent 5855This pragma is now obsolete and, other than generating a warning if warnings 5856on obsolescent features are enabled, is ignored. 5857It is retained for compatibility 5858purposes. It used to be used in connection with optimization of 5859a now-obsolete mechanism for implementation of exceptions. 5860 5861@node Pragma Provide_Shift_Operators 5862@unnumberedsec Pragma Provide_Shift_Operators 5863@cindex Shift operators 5864@findex Provide_Shift_Operators 5865@noindent 5866Syntax: 5867 5868@smallexample @c ada 5869pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); 5870@end smallexample 5871 5872@noindent 5873This pragma can be applied to a first subtype local name that specifies 5874either an unsigned or signed type. It has the effect of providing the 5875five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, 5876Rotate_Left and Rotate_Right) for the given type. It is equivalent to 5877including the function declarations for these five operators, together 5878with the pragma Import (Intrinsic, ...) statements. 5879 5880@node Pragma Psect_Object 5881@unnumberedsec Pragma Psect_Object 5882@findex Psect_Object 5883@noindent 5884Syntax: 5885 5886@smallexample @c ada 5887pragma Psect_Object ( 5888 [Internal =>] LOCAL_NAME, 5889 [, [External =>] EXTERNAL_SYMBOL] 5890 [, [Size =>] EXTERNAL_SYMBOL]); 5891 5892EXTERNAL_SYMBOL ::= 5893 IDENTIFIER 5894| static_string_EXPRESSION 5895@end smallexample 5896 5897@noindent 5898This pragma is identical in effect to pragma @code{Common_Object}. 5899 5900@node Pragma Pure_05 5901@unnumberedsec Pragma Pure_05 5902@findex Pure_05 5903@noindent 5904Syntax: 5905 5906@smallexample @c ada 5907pragma Pure_05 [(library_unit_NAME)]; 5908@end smallexample 5909 5910@noindent 5911This pragma is only available in GNAT mode (@option{-gnatg} switch set) 5912and is intended for use in the standard run-time library only. It has 5913no effect in Ada 83 or Ada 95 mode, but is 5914equivalent to @code{pragma Pure} when operating in later 5915Ada versions. This is used to handle some cases where packages 5916not previously pure became so in Ada 2005. 5917 5918@node Pragma Pure_12 5919@unnumberedsec Pragma Pure_12 5920@findex Pure_12 5921@noindent 5922Syntax: 5923 5924@smallexample @c ada 5925pragma Pure_12 [(library_unit_NAME)]; 5926@end smallexample 5927 5928@noindent 5929This pragma is only available in GNAT mode (@option{-gnatg} switch set) 5930and is intended for use in the standard run-time library only. It has 5931no effect in Ada 83, Ada 95, or Ada 2005 modes, but is 5932equivalent to @code{pragma Pure} when operating in later 5933Ada versions. This is used to handle some cases where packages 5934not previously pure became so in Ada 2012. 5935 5936@node Pragma Pure_Function 5937@unnumberedsec Pragma Pure_Function 5938@findex Pure_Function 5939@noindent 5940Syntax: 5941 5942@smallexample @c ada 5943pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 5944@end smallexample 5945 5946@noindent 5947This pragma appears in the same declarative part as a function 5948declaration (or a set of function declarations if more than one 5949overloaded declaration exists, in which case the pragma applies 5950to all entities). It specifies that the function @code{Entity} is 5951to be considered pure for the purposes of code generation. This means 5952that the compiler can assume that there are no side effects, and 5953in particular that two calls with identical arguments produce the 5954same result. It also means that the function can be used in an 5955address clause. 5956 5957Note that, quite deliberately, there are no static checks to try 5958to ensure that this promise is met, so @code{Pure_Function} can be used 5959with functions that are conceptually pure, even if they do modify 5960global variables. For example, a square root function that is 5961instrumented to count the number of times it is called is still 5962conceptually pure, and can still be optimized, even though it 5963modifies a global variable (the count). Memo functions are another 5964example (where a table of previous calls is kept and consulted to 5965avoid re-computation). 5966 5967Note also that the normal rules excluding optimization of subprograms 5968in pure units (when parameter types are descended from System.Address, 5969or when the full view of a parameter type is limited), do not apply 5970for the Pure_Function case. If you explicitly specify Pure_Function, 5971the compiler may optimize away calls with identical arguments, and 5972if that results in unexpected behavior, the proper action is not to 5973use the pragma for subprograms that are not (conceptually) pure. 5974 5975@findex Pure 5976Note: Most functions in a @code{Pure} package are automatically pure, and 5977there is no need to use pragma @code{Pure_Function} for such functions. One 5978exception is any function that has at least one formal of type 5979@code{System.Address} or a type derived from it. Such functions are not 5980considered pure by default, since the compiler assumes that the 5981@code{Address} parameter may be functioning as a pointer and that the 5982referenced data may change even if the address value does not. 5983Similarly, imported functions are not considered to be pure by default, 5984since there is no way of checking that they are in fact pure. The use 5985of pragma @code{Pure_Function} for such a function will override these default 5986assumption, and cause the compiler to treat a designated subprogram as pure 5987in these cases. 5988 5989Note: If pragma @code{Pure_Function} is applied to a renamed function, it 5990applies to the underlying renamed function. This can be used to 5991disambiguate cases of overloading where some but not all functions 5992in a set of overloaded functions are to be designated as pure. 5993 5994If pragma @code{Pure_Function} is applied to a library level function, the 5995function is also considered pure from an optimization point of view, but the 5996unit is not a Pure unit in the categorization sense. So for example, a function 5997thus marked is free to @code{with} non-pure units. 5998 5999@node Pragma Ravenscar 6000@unnumberedsec Pragma Ravenscar 6001@findex Pragma Ravenscar 6002@noindent 6003Syntax: 6004 6005@smallexample @c ada 6006pragma Ravenscar; 6007@end smallexample 6008 6009@noindent 6010This pragma is considered obsolescent, but is retained for 6011compatibility purposes. It is equivalent to: 6012 6013@smallexample @c ada 6014pragma Profile (Ravenscar); 6015@end smallexample 6016 6017@noindent 6018which is the preferred method of setting the @code{Ravenscar} profile. 6019 6020@node Pragma Refined_State 6021@unnumberedsec Pragma Refined_State 6022@findex Refined_State 6023@noindent 6024For the description of this pragma, see SPARK 2014 Reference Manual, 6025section 7.2.2. 6026 6027@node Pragma Relative_Deadline 6028@unnumberedsec Pragma Relative_Deadline 6029@findex Relative_Deadline 6030@noindent 6031Syntax: 6032 6033@smallexample @c ada 6034pragma Relative_Deadline (time_span_EXPRESSION); 6035@end smallexample 6036 6037@noindent 6038This pragma is standard in Ada 2005, but is available in all earlier 6039versions of Ada as an implementation-defined pragma. 6040See Ada 2012 Reference Manual for details. 6041 6042@node Pragma Remote_Access_Type 6043@unnumberedsec Pragma Remote_Access_Type 6044@findex Remote_Access_Type 6045@noindent 6046Syntax: 6047 6048@smallexample @c ada 6049pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 6050@end smallexample 6051 6052@noindent 6053This pragma appears in the formal part of a generic declaration. 6054It specifies an exception to the RM rule from E.2.2(17/2), which forbids 6055the use of a remote access to class-wide type as actual for a formal 6056access type. 6057 6058When this pragma applies to a formal access type @code{Entity}, that 6059type is treated as a remote access to class-wide type in the generic. 6060It must be a formal general access type, and its designated type must 6061be the class-wide type of a formal tagged limited private type from the 6062same generic declaration. 6063 6064In the generic unit, the formal type is subject to all restrictions 6065pertaining to remote access to class-wide types. At instantiation, the 6066actual type must be a remote access to class-wide type. 6067 6068@node Pragma Restricted_Run_Time 6069@unnumberedsec Pragma Restricted_Run_Time 6070@findex Pragma Restricted_Run_Time 6071@noindent 6072Syntax: 6073 6074@smallexample @c ada 6075pragma Restricted_Run_Time; 6076@end smallexample 6077 6078@noindent 6079This pragma is considered obsolescent, but is retained for 6080compatibility purposes. It is equivalent to: 6081 6082@smallexample @c ada 6083pragma Profile (Restricted); 6084@end smallexample 6085 6086@noindent 6087which is the preferred method of setting the restricted run time 6088profile. 6089 6090@node Pragma Restriction_Warnings 6091@unnumberedsec Pragma Restriction_Warnings 6092@findex Restriction_Warnings 6093@noindent 6094Syntax: 6095 6096@smallexample @c ada 6097pragma Restriction_Warnings 6098 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 6099@end smallexample 6100 6101@noindent 6102This pragma allows a series of restriction identifiers to be 6103specified (the list of allowed identifiers is the same as for 6104pragma @code{Restrictions}). For each of these identifiers 6105the compiler checks for violations of the restriction, but 6106generates a warning message rather than an error message 6107if the restriction is violated. 6108 6109One use of this is in situations where you want to know 6110about violations of a restriction, but you want to ignore some of 6111these violations. Consider this example, where you want to set 6112Ada_95 mode and enable style checks, but you want to know about 6113any other use of implementation pragmas: 6114 6115@smallexample @c ada 6116pragma Restriction_Warnings (No_Implementation_Pragmas); 6117pragma Warnings (Off, "violation of*No_Implementation_Pragmas*"); 6118pragma Ada_95; 6119pragma Style_Checks ("2bfhkM160"); 6120pragma Warnings (On, "violation of*No_Implementation_Pragmas*"); 6121@end smallexample 6122 6123@noindent 6124By including the above lines in a configuration pragmas file, 6125the Ada_95 and Style_Checks pragmas are accepted without 6126generating a warning, but any other use of implementation 6127defined pragmas will cause a warning to be generated. 6128 6129@node Pragma Reviewable 6130@unnumberedsec Pragma Reviewable 6131@findex Reviewable 6132@noindent 6133Syntax: 6134 6135@smallexample @c ada 6136pragma Reviewable; 6137@end smallexample 6138 6139@noindent 6140This pragma is an RM-defined standard pragma, but has no effect on the 6141program being compiled, or on the code generated for the program. 6142 6143To obtain the required output specified in RM H.3.1, the compiler must be 6144run with various special switches as follows: 6145 6146@table @i 6147 6148@item Where compiler-generated run-time checks remain 6149 6150The switch @option{-gnatGL} 6151@findex @option{-gnatGL} 6152may be used to list the expanded code in pseudo-Ada form. 6153Runtime checks show up in the listing either as explicit 6154checks or operators marked with @{@} to indicate a check is present. 6155 6156@item An identification of known exceptions at compile time 6157 6158If the program is compiled with @option{-gnatwa}, 6159@findex @option{-gnatwa} 6160the compiler warning messages will indicate all cases where the compiler 6161detects that an exception is certain to occur at run time. 6162 6163@item Possible reads of uninitialized variables 6164 6165The compiler warns of many such cases, but its output is incomplete. 6166@ifclear FSFEDITION 6167The CodePeer analysis tool 6168@findex CodePeer static analysis tool 6169@end ifclear 6170@ifset FSFEDITION 6171A supplemental static analysis tool 6172@end ifset 6173may be used to obtain a comprehensive list of all 6174possible points at which uninitialized data may be read. 6175 6176@item Where run-time support routines are implicitly invoked 6177 6178In the output from @option{-gnatGL}, 6179@findex @option{-gnatGL} 6180run-time calls are explicitly listed as calls to the relevant 6181run-time routine. 6182 6183@item Object code listing 6184 6185This may be obtained either by using the @option{-S} switch, 6186@findex @option{-S} 6187or the objdump utility. 6188@findex objdump 6189 6190@item Constructs known to be erroneous at compile time 6191 6192These are identified by warnings issued by the compiler (use @option{-gnatwa}). 6193@findex @option{-gnatwa} 6194 6195@item Stack usage information 6196 6197Static stack usage data (maximum per-subprogram) can be obtained via the 6198@option{-fstack-usage} switch to the compiler. 6199@findex @option{-fstack-usage} 6200Dynamic stack usage data (per task) can be obtained via the @option{-u} switch 6201to gnatbind 6202@findex @option{-u} 6203@ifclear FSFEDITION 6204The gnatstack utility 6205@findex gnatstack 6206can be used to provide additional information on stack usage. 6207@end ifclear 6208 6209@item Object code listing of entire partition 6210 6211This can be obtained by compiling the partition with @option{-S}, 6212@findex @option{-S} 6213or by applying objdump 6214@findex objdump 6215to all the object files that are part of the partition. 6216 6217@item A description of the run-time model 6218 6219The full sources of the run-time are available, and the documentation of 6220these routines describes how these run-time routines interface to the 6221underlying operating system facilities. 6222 6223@item Control and data-flow information 6224 6225@ifclear FSFEDITION 6226The CodePeer tool 6227@findex CodePeer static analysis tool 6228@end ifclear 6229@ifset FSFEDITION 6230A supplemental static analysis tool 6231@end ifset 6232may be used to obtain complete control and data-flow information, as well as 6233comprehensive messages identifying possible problems based on this 6234information. 6235@end table 6236 6237@node Pragma Share_Generic 6238@unnumberedsec Pragma Share_Generic 6239@findex Share_Generic 6240@noindent 6241Syntax: 6242 6243@smallexample @c ada 6244pragma Share_Generic (GNAME @{, GNAME@}); 6245 6246GNAME ::= generic_unit_NAME | generic_instance_NAME 6247@end smallexample 6248 6249@noindent 6250This pragma is provided for compatibility with Dec Ada 83. It has 6251no effect in @code{GNAT} (which does not implement shared generics), other 6252than to check that the given names are all names of generic units or 6253generic instances. 6254 6255@node Pragma Shared 6256@unnumberedsec Pragma Shared 6257@findex Shared 6258 6259@noindent 6260This pragma is provided for compatibility with Ada 83. The syntax and 6261semantics are identical to pragma Atomic. 6262 6263@node Pragma Short_Circuit_And_Or 6264@unnumberedsec Pragma Short_Circuit_And_Or 6265@findex Short_Circuit_And_Or 6266@noindent 6267Syntax: 6268 6269@smallexample @c ada 6270pragma Short_Circuit_And_Or; 6271@end smallexample 6272 6273@noindent 6274This configuration pragma causes any occurrence of the AND operator applied to 6275operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 6276is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 6277may be useful in the context of certification protocols requiring the use of 6278short-circuited logical operators. If this configuration pragma occurs locally 6279within the file being compiled, it applies only to the file being compiled. 6280There is no requirement that all units in a partition use this option. 6281 6282@node Pragma Short_Descriptors 6283@unnumberedsec Pragma Short_Descriptors 6284@findex Short_Descriptors 6285@noindent 6286Syntax: 6287 6288@smallexample @c ada 6289pragma Short_Descriptors 6290@end smallexample 6291 6292@noindent 6293In VMS versions of the compiler, this configuration pragma causes all 6294occurrences of the mechanism types Descriptor[_xxx] to be treated as 6295Short_Descriptor[_xxx]. This is helpful in porting legacy applications from a 629632-bit environment to a 64-bit environment. This pragma is ignored for non-VMS 6297versions. 6298 6299@node Pragma Simple_Storage_Pool_Type 6300@unnumberedsec Pragma Simple_Storage_Pool_Type 6301@findex Simple_Storage_Pool_Type 6302@cindex Storage pool, simple 6303@cindex Simple storage pool 6304@noindent 6305Syntax: 6306 6307@smallexample @c ada 6308pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 6309@end smallexample 6310 6311@noindent 6312A type can be established as a ``simple storage pool type'' by applying 6313the representation pragma @code{Simple_Storage_Pool_Type} to the type. 6314A type named in the pragma must be a library-level immutably limited record 6315type or limited tagged type declared immediately within a package declaration. 6316The type can also be a limited private type whose full type is allowed as 6317a simple storage pool type. 6318 6319For a simple storage pool type @var{SSP}, nonabstract primitive subprograms 6320@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that 6321are subtype conformant with the following subprogram declarations: 6322 6323@smallexample @c ada 6324procedure Allocate 6325 (Pool : in out SSP; 6326 Storage_Address : out System.Address; 6327 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 6328 Alignment : System.Storage_Elements.Storage_Count); 6329 6330procedure Deallocate 6331 (Pool : in out SSP; 6332 Storage_Address : System.Address; 6333 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 6334 Alignment : System.Storage_Elements.Storage_Count); 6335 6336function Storage_Size (Pool : SSP) 6337 return System.Storage_Elements.Storage_Count; 6338@end smallexample 6339 6340@noindent 6341Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and 6342@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then 6343applying an unchecked deallocation has no effect other than to set its actual 6344parameter to null. If @code{Storage_Size} is not declared, then the 6345@code{Storage_Size} attribute applied to an access type associated with 6346a pool object of type SSP returns zero. Additional operations can be declared 6347for a simple storage pool type (such as for supporting a mark/release 6348storage-management discipline). 6349 6350An object of a simple storage pool type can be associated with an access 6351type by specifying the attribute @code{Simple_Storage_Pool}. For example: 6352 6353@smallexample @c ada 6354 6355My_Pool : My_Simple_Storage_Pool_Type; 6356 6357type Acc is access My_Data_Type; 6358 6359for Acc'Simple_Storage_Pool use My_Pool; 6360 6361@end smallexample 6362 6363@noindent 6364See attribute @code{Simple_Storage_Pool} for further details. 6365 6366@node Pragma Source_File_Name 6367@unnumberedsec Pragma Source_File_Name 6368@findex Source_File_Name 6369@noindent 6370Syntax: 6371 6372@smallexample @c ada 6373pragma Source_File_Name ( 6374 [Unit_Name =>] unit_NAME, 6375 Spec_File_Name => STRING_LITERAL, 6376 [Index => INTEGER_LITERAL]); 6377 6378pragma Source_File_Name ( 6379 [Unit_Name =>] unit_NAME, 6380 Body_File_Name => STRING_LITERAL, 6381 [Index => INTEGER_LITERAL]); 6382@end smallexample 6383 6384@noindent 6385Use this to override the normal naming convention. It is a configuration 6386pragma, and so has the usual applicability of configuration pragmas 6387(i.e.@: it applies to either an entire partition, or to all units in a 6388compilation, or to a single unit, depending on how it is used. 6389@var{unit_name} is mapped to @var{file_name_literal}. The identifier for 6390the second argument is required, and indicates whether this is the file 6391name for the spec or for the body. 6392 6393The optional Index argument should be used when a file contains multiple 6394units, and when you do not want to use @code{gnatchop} to separate then 6395into multiple files (which is the recommended procedure to limit the 6396number of recompilations that are needed when some sources change). 6397For instance, if the source file @file{source.ada} contains 6398 6399@smallexample @c ada 6400package B is 6401... 6402end B; 6403 6404with B; 6405procedure A is 6406begin 6407 .. 6408end A; 6409@end smallexample 6410 6411you could use the following configuration pragmas: 6412 6413@smallexample @c ada 6414pragma Source_File_Name 6415 (B, Spec_File_Name => "source.ada", Index => 1); 6416pragma Source_File_Name 6417 (A, Body_File_Name => "source.ada", Index => 2); 6418@end smallexample 6419 6420Note that the @code{gnatname} utility can also be used to generate those 6421configuration pragmas. 6422 6423Another form of the @code{Source_File_Name} pragma allows 6424the specification of patterns defining alternative file naming schemes 6425to apply to all files. 6426 6427@smallexample @c ada 6428pragma Source_File_Name 6429 ( [Spec_File_Name =>] STRING_LITERAL 6430 [,[Casing =>] CASING_SPEC] 6431 [,[Dot_Replacement =>] STRING_LITERAL]); 6432 6433pragma Source_File_Name 6434 ( [Body_File_Name =>] STRING_LITERAL 6435 [,[Casing =>] CASING_SPEC] 6436 [,[Dot_Replacement =>] STRING_LITERAL]); 6437 6438pragma Source_File_Name 6439 ( [Subunit_File_Name =>] STRING_LITERAL 6440 [,[Casing =>] CASING_SPEC] 6441 [,[Dot_Replacement =>] STRING_LITERAL]); 6442 6443CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 6444@end smallexample 6445 6446@noindent 6447The first argument is a pattern that contains a single asterisk indicating 6448the point at which the unit name is to be inserted in the pattern string 6449to form the file name. The second argument is optional. If present it 6450specifies the casing of the unit name in the resulting file name string. 6451The default is lower case. Finally the third argument allows for systematic 6452replacement of any dots in the unit name by the specified string literal. 6453 6454Note that Source_File_Name pragmas should not be used if you are using 6455project files. The reason for this rule is that the project manager is not 6456aware of these pragmas, and so other tools that use the projet file would not 6457be aware of the intended naming conventions. If you are using project files, 6458file naming is controlled by Source_File_Name_Project pragmas, which are 6459usually supplied automatically by the project manager. A pragma 6460Source_File_Name cannot appear after a @ref{Pragma Source_File_Name_Project}. 6461 6462For more details on the use of the @code{Source_File_Name} pragma, 6463@xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide}, 6464and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION} 6465User's Guide}. 6466 6467@node Pragma Source_File_Name_Project 6468@unnumberedsec Pragma Source_File_Name_Project 6469@findex Source_File_Name_Project 6470@noindent 6471 6472This pragma has the same syntax and semantics as pragma Source_File_Name. 6473It is only allowed as a stand alone configuration pragma. 6474It cannot appear after a @ref{Pragma Source_File_Name}, and 6475most importantly, once pragma Source_File_Name_Project appears, 6476no further Source_File_Name pragmas are allowed. 6477 6478The intention is that Source_File_Name_Project pragmas are always 6479generated by the Project Manager in a manner consistent with the naming 6480specified in a project file, and when naming is controlled in this manner, 6481it is not permissible to attempt to modify this naming scheme using 6482Source_File_Name or Source_File_Name_Project pragmas (which would not be 6483known to the project manager). 6484 6485@node Pragma Source_Reference 6486@unnumberedsec Pragma Source_Reference 6487@findex Source_Reference 6488@noindent 6489Syntax: 6490 6491@smallexample @c ada 6492pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 6493@end smallexample 6494 6495@noindent 6496This pragma must appear as the first line of a source file. 6497@var{integer_literal} is the logical line number of the line following 6498the pragma line (for use in error messages and debugging 6499information). @var{string_literal} is a static string constant that 6500specifies the file name to be used in error messages and debugging 6501information. This is most notably used for the output of @code{gnatchop} 6502with the @option{-r} switch, to make sure that the original unchopped 6503source file is the one referred to. 6504 6505The second argument must be a string literal, it cannot be a static 6506string expression other than a string literal. This is because its value 6507is needed for error messages issued by all phases of the compiler. 6508 6509@node Pragma SPARK_Mode 6510@unnumberedsec Pragma SPARK_Mode 6511@findex SPARK_Mode 6512@noindent 6513Syntax: 6514 6515@smallexample @c ada 6516pragma SPARK_Mode [(On | Off)] ; 6517@end smallexample 6518 6519@noindent 6520In general a program can have some parts that are in SPARK 2014 (and 6521follow all the rules in the SPARK Reference Manual), and some parts 6522that are full Ada 2012. 6523 6524The SPARK_Mode pragma is used to identify which parts are in SPARK 65252014 (by default programs are in full Ada). The SPARK_Mode pragma can 6526be used in the following places: 6527 6528@itemize @bullet 6529 6530@item 6531As a configuration pragma, in which case it sets the default mode for 6532all units compiled with this pragma. 6533 6534@item 6535Immediately following a library-level subprogram spec 6536 6537@item 6538Immediately within a library-level package body 6539 6540@item 6541Immediately following the @code{private} keyword of a library-level 6542package spec 6543 6544@item 6545Immediately following the @code{begin} keyword of a library-level 6546package body 6547 6548@item 6549Immediately within a library-level subprogram body 6550 6551@end itemize 6552 6553@noindent 6554Normally a subprogram or package spec/body inherits the current mode 6555that is active at the point it is declared. But this can be overridden 6556by pragma within the spec or body as above. 6557 6558The basic consistency rule is that you can't turn SPARK_Mode back 6559@code{On}, once you have explicitly (with a pragma) turned if 6560@code{Off}. So the following rules apply: 6561 6562@noindent 6563If a subprogram spec has SPARK_Mode @code{Off}, then the body must 6564also have SPARK_Mode @code{Off}. 6565 6566@noindent 6567For a package, we have four parts: 6568 6569@itemize 6570@item 6571the package public declarations 6572@item 6573the package private part 6574@item 6575the body of the package 6576@item 6577the elaboration code after @code{begin} 6578@end itemize 6579 6580@noindent 6581For a package, the rule is that if you explicitly turn SPARK_Mode 6582@code{Off} for any part, then all the following parts must have 6583SPARK_Mode @code{Off}. Note that this may require repeating a pragma 6584SPARK_Mode (@code{Off}) in the body. For example, if we have a 6585configuration pragma SPARK_Mode (@code{On}) that turns the mode on by 6586default everywhere, and one particular package spec has pragma 6587SPARK_Mode (@code{Off}), then that pragma will need to be repeated in 6588the package body. 6589 6590@node Pragma Static_Elaboration_Desired 6591@unnumberedsec Pragma Static_Elaboration_Desired 6592@findex Static_Elaboration_Desired 6593@noindent 6594Syntax: 6595 6596@smallexample @c ada 6597pragma Static_Elaboration_Desired; 6598@end smallexample 6599 6600@noindent 6601This pragma is used to indicate that the compiler should attempt to initialize 6602statically the objects declared in the library unit to which the pragma applies, 6603when these objects are initialized (explicitly or implicitly) by an aggregate. 6604In the absence of this pragma, aggregates in object declarations are expanded 6605into assignments and loops, even when the aggregate components are static 6606constants. When the aggregate is present the compiler builds a static expression 6607that requires no run-time code, so that the initialized object can be placed in 6608read-only data space. If the components are not static, or the aggregate has 6609more that 100 components, the compiler emits a warning that the pragma cannot 6610be obeyed. (See also the restriction No_Implicit_Loops, which supports static 6611construction of larger aggregates with static components that include an others 6612choice.) 6613 6614@node Pragma Stream_Convert 6615@unnumberedsec Pragma Stream_Convert 6616@findex Stream_Convert 6617@noindent 6618Syntax: 6619 6620@smallexample @c ada 6621pragma Stream_Convert ( 6622 [Entity =>] type_LOCAL_NAME, 6623 [Read =>] function_NAME, 6624 [Write =>] function_NAME); 6625@end smallexample 6626 6627@noindent 6628This pragma provides an efficient way of providing user-defined stream 6629attributes. Not only is it simpler to use than specifying the attributes 6630directly, but more importantly, it allows the specification to be made in such 6631a way that the predefined unit Ada.Streams is not loaded unless it is actually 6632needed (i.e. unless the stream attributes are actually used); the use of 6633the Stream_Convert pragma adds no overhead at all, unless the stream 6634attributes are actually used on the designated type. 6635 6636The first argument specifies the type for which stream functions are 6637provided. The second parameter provides a function used to read values 6638of this type. It must name a function whose argument type may be any 6639subtype, and whose returned type must be the type given as the first 6640argument to the pragma. 6641 6642The meaning of the @var{Read} parameter is that if a stream attribute directly 6643or indirectly specifies reading of the type given as the first parameter, 6644then a value of the type given as the argument to the Read function is 6645read from the stream, and then the Read function is used to convert this 6646to the required target type. 6647 6648Similarly the @var{Write} parameter specifies how to treat write attributes 6649that directly or indirectly apply to the type given as the first parameter. 6650It must have an input parameter of the type specified by the first parameter, 6651and the return type must be the same as the input type of the Read function. 6652The effect is to first call the Write function to convert to the given stream 6653type, and then write the result type to the stream. 6654 6655The Read and Write functions must not be overloaded subprograms. If necessary 6656renamings can be supplied to meet this requirement. 6657The usage of this attribute is best illustrated by a simple example, taken 6658from the GNAT implementation of package Ada.Strings.Unbounded: 6659 6660@smallexample @c ada 6661function To_Unbounded (S : String) 6662 return Unbounded_String 6663 renames To_Unbounded_String; 6664 6665pragma Stream_Convert 6666 (Unbounded_String, To_Unbounded, To_String); 6667@end smallexample 6668 6669@noindent 6670The specifications of the referenced functions, as given in the Ada 6671Reference Manual are: 6672 6673@smallexample @c ada 6674function To_Unbounded_String (Source : String) 6675 return Unbounded_String; 6676 6677function To_String (Source : Unbounded_String) 6678 return String; 6679@end smallexample 6680 6681@noindent 6682The effect is that if the value of an unbounded string is written to a stream, 6683then the representation of the item in the stream is in the same format that 6684would be used for @code{Standard.String'Output}, and this same representation 6685is expected when a value of this type is read from the stream. Note that the 6686value written always includes the bounds, even for Unbounded_String'Write, 6687since Unbounded_String is not an array type. 6688 6689Note that the @code{Stream_Convert} pragma is not effective in the case of 6690a derived type of a non-limited tagged type. If such a type is specified then 6691the pragma is silently ignored, and the default implementation of the stream 6692attributes is used instead. 6693 6694@node Pragma Style_Checks 6695@unnumberedsec Pragma Style_Checks 6696@findex Style_Checks 6697@noindent 6698Syntax: 6699 6700@smallexample @c ada 6701pragma Style_Checks (string_LITERAL | ALL_CHECKS | 6702 On | Off [, LOCAL_NAME]); 6703@end smallexample 6704 6705@noindent 6706This pragma is used in conjunction with compiler switches to control the 6707built in style checking provided by GNAT@. The compiler switches, if set, 6708provide an initial setting for the switches, and this pragma may be used 6709to modify these settings, or the settings may be provided entirely by 6710the use of the pragma. This pragma can be used anywhere that a pragma 6711is legal, including use as a configuration pragma (including use in 6712the @file{gnat.adc} file). 6713 6714The form with a string literal specifies which style options are to be 6715activated. These are additive, so they apply in addition to any previously 6716set style check options. The codes for the options are the same as those 6717used in the @option{-gnaty} switch to @command{gcc} or @command{gnatmake}. 6718For example the following two methods can be used to enable 6719layout checking: 6720 6721@itemize @bullet 6722@item 6723@smallexample @c ada 6724pragma Style_Checks ("l"); 6725@end smallexample 6726 6727@item 6728@smallexample 6729gcc -c -gnatyl @dots{} 6730@end smallexample 6731@end itemize 6732 6733@noindent 6734The form ALL_CHECKS activates all standard checks (its use is equivalent 6735to the use of the @code{gnaty} switch with no options. @xref{Top, 6736@value{EDITION} User's Guide, About This Guide, gnat_ugn, 6737@value{EDITION} User's Guide}, for details.) 6738 6739Note: the behavior is slightly different in GNAT mode (@option{-gnatg} used). 6740In this case, ALL_CHECKS implies the standard set of GNAT mode style check 6741options (i.e. equivalent to -gnatyg). 6742 6743The forms with @code{Off} and @code{On} 6744can be used to temporarily disable style checks 6745as shown in the following example: 6746 6747@smallexample @c ada 6748@iftex 6749@leftskip=0cm 6750@end iftex 6751pragma Style_Checks ("k"); -- requires keywords in lower case 6752pragma Style_Checks (Off); -- turn off style checks 6753NULL; -- this will not generate an error message 6754pragma Style_Checks (On); -- turn style checks back on 6755NULL; -- this will generate an error message 6756@end smallexample 6757 6758@noindent 6759Finally the two argument form is allowed only if the first argument is 6760@code{On} or @code{Off}. The effect is to turn of semantic style checks 6761for the specified entity, as shown in the following example: 6762 6763@smallexample @c ada 6764@iftex 6765@leftskip=0cm 6766@end iftex 6767pragma Style_Checks ("r"); -- require consistency of identifier casing 6768Arg : Integer; 6769Rf1 : Integer := ARG; -- incorrect, wrong case 6770pragma Style_Checks (Off, Arg); 6771Rf2 : Integer := ARG; -- OK, no error 6772@end smallexample 6773 6774@node Pragma Subtitle 6775@unnumberedsec Pragma Subtitle 6776@findex Subtitle 6777@noindent 6778Syntax: 6779 6780@smallexample @c ada 6781pragma Subtitle ([Subtitle =>] STRING_LITERAL); 6782@end smallexample 6783 6784@noindent 6785This pragma is recognized for compatibility with other Ada compilers 6786but is ignored by GNAT@. 6787 6788@node Pragma Suppress 6789@unnumberedsec Pragma Suppress 6790@findex Suppress 6791@noindent 6792Syntax: 6793 6794@smallexample @c ada 6795pragma Suppress (Identifier [, [On =>] Name]); 6796@end smallexample 6797 6798@noindent 6799This is a standard pragma, and supports all the check names required in 6800the RM. It is included here because GNAT recognizes some additional check 6801names that are implementation defined (as permitted by the RM): 6802 6803@itemize @bullet 6804 6805@item 6806@code{Alignment_Check} can be used to suppress alignment checks 6807on addresses used in address clauses. Such checks can also be suppressed 6808by suppressing range checks, but the specific use of @code{Alignment_Check} 6809allows suppression of alignment checks without suppressing other range checks. 6810 6811@item 6812@code{Predicate_Check} can be used to control whether predicate checks are 6813active. It is applicable only to predicates for which the policy is 6814@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given 6815predicate is ignored or checked for the whole program, the use of 6816@code{Suppress} and @code{Unsuppress} with this check name allows a given 6817predicate to be turned on and off at specific points in the program. 6818 6819@item 6820@code{Validity_Check} can be used specifically to control validity checks. 6821If @code{Suppress} is used to suppress validity checks, then no validity 6822checks are performed, including those specified by the appropriate compiler 6823switch or the @code{Validity_Checks} pragma. 6824 6825@item 6826Additional check names previously introduced by use of the @code{Check_Name} 6827pragma are also allowed. 6828 6829@end itemize 6830 6831@noindent 6832Note that pragma Suppress gives the compiler permission to omit 6833checks, but does not require the compiler to omit checks. The compiler 6834will generate checks if they are essentially free, even when they are 6835suppressed. In particular, if the compiler can prove that a certain 6836check will necessarily fail, it will generate code to do an 6837unconditional ``raise'', even if checks are suppressed. The compiler 6838warns in this case. 6839 6840Of course, run-time checks are omitted whenever the compiler can prove 6841that they will not fail, whether or not checks are suppressed. 6842 6843@node Pragma Suppress_All 6844@unnumberedsec Pragma Suppress_All 6845@findex Suppress_All 6846@noindent 6847Syntax: 6848 6849@smallexample @c ada 6850pragma Suppress_All; 6851@end smallexample 6852 6853@noindent 6854This pragma can appear anywhere within a unit. 6855The effect is to apply @code{Suppress (All_Checks)} to the unit 6856in which it appears. This pragma is implemented for compatibility with DEC 6857Ada 83 usage where it appears at the end of a unit, and for compatibility 6858with Rational Ada, where it appears as a program unit pragma. 6859The use of the standard Ada pragma @code{Suppress (All_Checks)} 6860as a normal configuration pragma is the preferred usage in GNAT@. 6861 6862@node Pragma Suppress_Debug_Info 6863@unnumberedsec Pragma Suppress_Debug_Info 6864@findex Suppress_Debug_Info 6865@noindent 6866Syntax: 6867 6868@smallexample @c ada 6869Suppress_Debug_Info ([Entity =>] LOCAL_NAME); 6870@end smallexample 6871 6872@noindent 6873This pragma can be used to suppress generation of debug information 6874for the specified entity. It is intended primarily for use in debugging 6875the debugger, and navigating around debugger problems. 6876 6877@node Pragma Suppress_Exception_Locations 6878@unnumberedsec Pragma Suppress_Exception_Locations 6879@findex Suppress_Exception_Locations 6880@noindent 6881Syntax: 6882 6883@smallexample @c ada 6884pragma Suppress_Exception_Locations; 6885@end smallexample 6886 6887@noindent 6888In normal mode, a raise statement for an exception by default generates 6889an exception message giving the file name and line number for the location 6890of the raise. This is useful for debugging and logging purposes, but this 6891entails extra space for the strings for the messages. The configuration 6892pragma @code{Suppress_Exception_Locations} can be used to suppress the 6893generation of these strings, with the result that space is saved, but the 6894exception message for such raises is null. This configuration pragma may 6895appear in a global configuration pragma file, or in a specific unit as 6896usual. It is not required that this pragma be used consistently within 6897a partition, so it is fine to have some units within a partition compiled 6898with this pragma and others compiled in normal mode without it. 6899 6900@node Pragma Suppress_Initialization 6901@unnumberedsec Pragma Suppress_Initialization 6902@findex Suppress_Initialization 6903@cindex Suppressing initialization 6904@cindex Initialization, suppression of 6905@noindent 6906Syntax: 6907 6908@smallexample @c ada 6909pragma Suppress_Initialization ([Entity =>] subtype_Name); 6910@end smallexample 6911 6912@noindent 6913Here subtype_Name is the name introduced by a type declaration 6914or subtype declaration. 6915This pragma suppresses any implicit or explicit initialization 6916for all variables of the given type or subtype, 6917including initialization resulting from the use of pragmas 6918Normalize_Scalars or Initialize_Scalars. 6919 6920This is considered a representation item, so it cannot be given after 6921the type is frozen. It applies to all subsequent object declarations, 6922and also any allocator that creates objects of the type. 6923 6924If the pragma is given for the first subtype, then it is considered 6925to apply to the base type and all its subtypes. If the pragma is given 6926for other than a first subtype, then it applies only to the given subtype. 6927The pragma may not be given after the type is frozen. 6928 6929@node Pragma Task_Info 6930@unnumberedsec Pragma Task_Info 6931@findex Task_Info 6932@noindent 6933Syntax 6934 6935@smallexample @c ada 6936pragma Task_Info (EXPRESSION); 6937@end smallexample 6938 6939@noindent 6940This pragma appears within a task definition (like pragma 6941@code{Priority}) and applies to the task in which it appears. The 6942argument must be of type @code{System.Task_Info.Task_Info_Type}. 6943The @code{Task_Info} pragma provides system dependent control over 6944aspects of tasking implementation, for example, the ability to map 6945tasks to specific processors. For details on the facilities available 6946for the version of GNAT that you are using, see the documentation 6947in the spec of package System.Task_Info in the runtime 6948library. 6949 6950@node Pragma Task_Name 6951@unnumberedsec Pragma Task_Name 6952@findex Task_Name 6953@noindent 6954Syntax 6955 6956@smallexample @c ada 6957pragma Task_Name (string_EXPRESSION); 6958@end smallexample 6959 6960@noindent 6961This pragma appears within a task definition (like pragma 6962@code{Priority}) and applies to the task in which it appears. The 6963argument must be of type String, and provides a name to be used for 6964the task instance when the task is created. Note that this expression 6965is not required to be static, and in particular, it can contain 6966references to task discriminants. This facility can be used to 6967provide different names for different tasks as they are created, 6968as illustrated in the example below. 6969 6970The task name is recorded internally in the run-time structures 6971and is accessible to tools like the debugger. In addition the 6972routine @code{Ada.Task_Identification.Image} will return this 6973string, with a unique task address appended. 6974 6975@smallexample @c ada 6976-- Example of the use of pragma Task_Name 6977 6978with Ada.Task_Identification; 6979use Ada.Task_Identification; 6980with Text_IO; use Text_IO; 6981procedure t3 is 6982 6983 type Astring is access String; 6984 6985 task type Task_Typ (Name : access String) is 6986 pragma Task_Name (Name.all); 6987 end Task_Typ; 6988 6989 task body Task_Typ is 6990 Nam : constant String := Image (Current_Task); 6991 begin 6992 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 6993 end Task_Typ; 6994 6995 type Ptr_Task is access Task_Typ; 6996 Task_Var : Ptr_Task; 6997 6998begin 6999 Task_Var := 7000 new Task_Typ (new String'("This is task 1")); 7001 Task_Var := 7002 new Task_Typ (new String'("This is task 2")); 7003end; 7004@end smallexample 7005 7006@node Pragma Task_Storage 7007@unnumberedsec Pragma Task_Storage 7008@findex Task_Storage 7009Syntax: 7010 7011@smallexample @c ada 7012pragma Task_Storage ( 7013 [Task_Type =>] LOCAL_NAME, 7014 [Top_Guard =>] static_integer_EXPRESSION); 7015@end smallexample 7016 7017@noindent 7018This pragma specifies the length of the guard area for tasks. The guard 7019area is an additional storage area allocated to a task. A value of zero 7020means that either no guard area is created or a minimal guard area is 7021created, depending on the target. This pragma can appear anywhere a 7022@code{Storage_Size} attribute definition clause is allowed for a task 7023type. 7024 7025@node Pragma Test_Case 7026@unnumberedsec Pragma Test_Case 7027@cindex Test cases 7028@findex Test_Case 7029@noindent 7030Syntax: 7031 7032@smallexample @c ada 7033pragma Test_Case ( 7034 [Name =>] static_string_Expression 7035 ,[Mode =>] (Nominal | Robustness) 7036 [, Requires => Boolean_Expression] 7037 [, Ensures => Boolean_Expression]); 7038@end smallexample 7039 7040@noindent 7041The @code{Test_Case} pragma allows defining fine-grain specifications 7042for use by testing tools. 7043The compiler checks the validity of the @code{Test_Case} pragma, but its 7044presence does not lead to any modification of the code generated by the 7045compiler. 7046 7047@code{Test_Case} pragmas may only appear immediately following the 7048(separate) declaration of a subprogram in a package declaration, inside 7049a package spec unit. Only other pragmas may intervene (that is appear 7050between the subprogram declaration and a test case). 7051 7052The compiler checks that boolean expressions given in @code{Requires} and 7053@code{Ensures} are valid, where the rules for @code{Requires} are the 7054same as the rule for an expression in @code{Precondition} and the rules 7055for @code{Ensures} are the same as the rule for an expression in 7056@code{Postcondition}. In particular, attributes @code{'Old} and 7057@code{'Result} can only be used within the @code{Ensures} 7058expression. The following is an example of use within a package spec: 7059 7060@smallexample @c ada 7061package Math_Functions is 7062 ... 7063 function Sqrt (Arg : Float) return Float; 7064 pragma Test_Case (Name => "Test 1", 7065 Mode => Nominal, 7066 Requires => Arg < 10000, 7067 Ensures => Sqrt'Result < 10); 7068 ... 7069end Math_Functions; 7070@end smallexample 7071 7072@noindent 7073The meaning of a test case is that there is at least one context where 7074@code{Requires} holds such that, if the associated subprogram is executed in 7075that context, then @code{Ensures} holds when the subprogram returns. 7076Mode @code{Nominal} indicates that the input context should also satisfy the 7077precondition of the subprogram, and the output context should also satisfy its 7078postcondition. More @code{Robustness} indicates that the precondition and 7079postcondition of the subprogram should be ignored for this test case. 7080 7081@node Pragma Thread_Local_Storage 7082@unnumberedsec Pragma Thread_Local_Storage 7083@findex Thread_Local_Storage 7084@cindex Task specific storage 7085@cindex TLS (Thread Local Storage) 7086@cindex Task_Attributes 7087Syntax: 7088 7089@smallexample @c ada 7090pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 7091@end smallexample 7092 7093@noindent 7094This pragma specifies that the specified entity, which must be 7095a variable declared in a library level package, is to be marked as 7096"Thread Local Storage" (@code{TLS}). On systems supporting this (which 7097include Solaris, GNU/Linux and VxWorks 6), this causes each thread 7098(and hence each Ada task) to see a distinct copy of the variable. 7099 7100The variable may not have default initialization, and if there is 7101an explicit initialization, it must be either @code{null} for an 7102access variable, or a static expression for a scalar variable. 7103This provides a low level mechanism similar to that provided by 7104the @code{Ada.Task_Attributes} package, but much more efficient 7105and is also useful in writing interface code that will interact 7106with foreign threads. 7107 7108If this pragma is used on a system where @code{TLS} is not supported, 7109then an error message will be generated and the program will be rejected. 7110 7111@node Pragma Time_Slice 7112@unnumberedsec Pragma Time_Slice 7113@findex Time_Slice 7114@noindent 7115Syntax: 7116 7117@smallexample @c ada 7118pragma Time_Slice (static_duration_EXPRESSION); 7119@end smallexample 7120 7121@noindent 7122For implementations of GNAT on operating systems where it is possible 7123to supply a time slice value, this pragma may be used for this purpose. 7124It is ignored if it is used in a system that does not allow this control, 7125or if it appears in other than the main program unit. 7126@cindex OpenVMS 7127Note that the effect of this pragma is identical to the effect of the 7128DEC Ada 83 pragma of the same name when operating under OpenVMS systems. 7129 7130@node Pragma Title 7131@unnumberedsec Pragma Title 7132@findex Title 7133@noindent 7134Syntax: 7135 7136@smallexample @c ada 7137pragma Title (TITLING_OPTION [, TITLING OPTION]); 7138 7139TITLING_OPTION ::= 7140 [Title =>] STRING_LITERAL, 7141| [Subtitle =>] STRING_LITERAL 7142@end smallexample 7143 7144@noindent 7145Syntax checked but otherwise ignored by GNAT@. This is a listing control 7146pragma used in DEC Ada 83 implementations to provide a title and/or 7147subtitle for the program listing. The program listing generated by GNAT 7148does not have titles or subtitles. 7149 7150Unlike other pragmas, the full flexibility of named notation is allowed 7151for this pragma, i.e.@: the parameters may be given in any order if named 7152notation is used, and named and positional notation can be mixed 7153following the normal rules for procedure calls in Ada. 7154 7155@node Pragma Type_Invariant 7156@unnumberedsec Pragma Type_Invariant 7157@findex Invariant 7158@findex Type_Invariant pragma 7159@noindent 7160Syntax: 7161 7162@smallexample @c ada 7163pragma Type_Invariant 7164 ([Entity =>] type_LOCAL_NAME, 7165 [Check =>] EXPRESSION); 7166@end smallexample 7167 7168@noindent 7169The @code{Type_Invariant} pragma is intended to be an exact 7170replacement for the language-defined @code{Type_Invariant} 7171aspect, and shares its restrictions and semantics. It differs 7172from the language defined @code{Invariant} pragma in that it 7173does not permit a string parameter, and it is 7174controlled by the assertion identifier @code{Type_Invariant} 7175rather than @code{Invariant}. 7176 7177@node Pragma Type_Invariant_Class 7178@unnumberedsec Pragma Type_Invariant_Class 7179@findex Invariant 7180@findex Type_Invariant_Class pragma 7181@noindent 7182Syntax: 7183 7184@smallexample @c ada 7185pragma Type_Invariant_Class 7186 ([Entity =>] type_LOCAL_NAME, 7187 [Check =>] EXPRESSION); 7188@end smallexample 7189 7190@noindent 7191The @code{Type_Invariant_Class} pragma is intended to be an exact 7192replacement for the language-defined @code{Type_Invariant'Class} 7193aspect, and shares its restrictions and semantics. 7194 7195Note: This pragma is called @code{Type_Invariant_Class} rather than 7196@code{Type_Invariant'Class} because the latter would not be strictly 7197conforming to the allowed syntax for pragmas. The motivation 7198for providing pragmas equivalent to the aspects is to allow a program 7199to be written using the pragmas, and then compiled if necessary 7200using an Ada compiler that does not recognize the pragmas or 7201aspects, but is prepared to ignore the pragmas. The assertion 7202policy that controls this pragma is @code{Type_Invariant'Class}, 7203not @code{Type_Invariant_Class}. 7204 7205@node Pragma Unchecked_Union 7206@unnumberedsec Pragma Unchecked_Union 7207@cindex Unions in C 7208@findex Unchecked_Union 7209@noindent 7210Syntax: 7211 7212@smallexample @c ada 7213pragma Unchecked_Union (first_subtype_LOCAL_NAME); 7214@end smallexample 7215 7216@noindent 7217This pragma is used to specify a representation of a record type that is 7218equivalent to a C union. It was introduced as a GNAT implementation defined 7219pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 7220pragma, making it language defined, and GNAT fully implements this extended 7221version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 7222details, consult the Ada 2012 Reference Manual, section B.3.3. 7223 7224@node Pragma Unimplemented_Unit 7225@unnumberedsec Pragma Unimplemented_Unit 7226@findex Unimplemented_Unit 7227@noindent 7228Syntax: 7229 7230@smallexample @c ada 7231pragma Unimplemented_Unit; 7232@end smallexample 7233 7234@noindent 7235If this pragma occurs in a unit that is processed by the compiler, GNAT 7236aborts with the message @samp{@var{xxx} not implemented}, where 7237@var{xxx} is the name of the current compilation unit. This pragma is 7238intended to allow the compiler to handle unimplemented library units in 7239a clean manner. 7240 7241The abort only happens if code is being generated. Thus you can use 7242specs of unimplemented packages in syntax or semantic checking mode. 7243 7244@node Pragma Universal_Aliasing 7245@unnumberedsec Pragma Universal_Aliasing 7246@findex Universal_Aliasing 7247@noindent 7248Syntax: 7249 7250@smallexample @c ada 7251pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 7252@end smallexample 7253 7254@noindent 7255@var{type_LOCAL_NAME} must refer to a type declaration in the current 7256declarative part. The effect is to inhibit strict type-based aliasing 7257optimization for the given type. In other words, the effect is as though 7258access types designating this type were subject to pragma No_Strict_Aliasing. 7259For a detailed description of the strict aliasing optimization, and the 7260situations in which it must be suppressed, @xref{Optimization and Strict 7261Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}. 7262 7263@node Pragma Universal_Data 7264@unnumberedsec Pragma Universal_Data 7265@findex Universal_Data 7266@noindent 7267Syntax: 7268 7269@smallexample @c ada 7270pragma Universal_Data [(library_unit_Name)]; 7271@end smallexample 7272 7273@noindent 7274This pragma is supported only for the AAMP target and is ignored for 7275other targets. The pragma specifies that all library-level objects 7276(Counter 0 data) associated with the library unit are to be accessed 7277and updated using universal addressing (24-bit addresses for AAMP5) 7278rather than the default of 16-bit Data Environment (DENV) addressing. 7279Use of this pragma will generally result in less efficient code for 7280references to global data associated with the library unit, but 7281allows such data to be located anywhere in memory. This pragma is 7282a library unit pragma, but can also be used as a configuration pragma 7283(including use in the @file{gnat.adc} file). The functionality 7284of this pragma is also available by applying the -univ switch on the 7285compilations of units where universal addressing of the data is desired. 7286 7287@node Pragma Unmodified 7288@unnumberedsec Pragma Unmodified 7289@findex Unmodified 7290@cindex Warnings, unmodified 7291@noindent 7292Syntax: 7293 7294@smallexample @c ada 7295pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); 7296@end smallexample 7297 7298@noindent 7299This pragma signals that the assignable entities (variables, 7300@code{out} parameters, @code{in out} parameters) whose names are listed are 7301deliberately not assigned in the current source unit. This 7302suppresses warnings about the 7303entities being referenced but not assigned, and in addition a warning will be 7304generated if one of these entities is in fact assigned in the 7305same unit as the pragma (or in the corresponding body, or one 7306of its subunits). 7307 7308This is particularly useful for clearly signaling that a particular 7309parameter is not modified, even though the spec suggests that it might 7310be. 7311 7312For the variable case, warnings are never given for unreferenced variables 7313whose name contains one of the substrings 7314@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 7315are typically to be used in cases where such warnings are expected. 7316Thus it is never necessary to use @code{pragma Unmodified} for such 7317variables, though it is harmless to do so. 7318 7319@node Pragma Unreferenced 7320@unnumberedsec Pragma Unreferenced 7321@findex Unreferenced 7322@cindex Warnings, unreferenced 7323@noindent 7324Syntax: 7325 7326@smallexample @c ada 7327pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); 7328pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); 7329@end smallexample 7330 7331@noindent 7332This pragma signals that the entities whose names are listed are 7333deliberately not referenced in the current source unit. This 7334suppresses warnings about the 7335entities being unreferenced, and in addition a warning will be 7336generated if one of these entities is in fact subsequently referenced in the 7337same unit as the pragma (or in the corresponding body, or one 7338of its subunits). 7339 7340This is particularly useful for clearly signaling that a particular 7341parameter is not referenced in some particular subprogram implementation 7342and that this is deliberate. It can also be useful in the case of 7343objects declared only for their initialization or finalization side 7344effects. 7345 7346If @code{LOCAL_NAME} identifies more than one matching homonym in the 7347current scope, then the entity most recently declared is the one to which 7348the pragma applies. Note that in the case of accept formals, the pragma 7349Unreferenced may appear immediately after the keyword @code{do} which 7350allows the indication of whether or not accept formals are referenced 7351or not to be given individually for each accept statement. 7352 7353The left hand side of an assignment does not count as a reference for the 7354purpose of this pragma. Thus it is fine to assign to an entity for which 7355pragma Unreferenced is given. 7356 7357Note that if a warning is desired for all calls to a given subprogram, 7358regardless of whether they occur in the same unit as the subprogram 7359declaration, then this pragma should not be used (calls from another 7360unit would not be flagged); pragma Obsolescent can be used instead 7361for this purpose, see @xref{Pragma Obsolescent}. 7362 7363The second form of pragma @code{Unreferenced} is used within a context 7364clause. In this case the arguments must be unit names of units previously 7365mentioned in @code{with} clauses (similar to the usage of pragma 7366@code{Elaborate_All}. The effect is to suppress warnings about unreferenced 7367units and unreferenced entities within these units. 7368 7369For the variable case, warnings are never given for unreferenced variables 7370whose name contains one of the substrings 7371@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names 7372are typically to be used in cases where such warnings are expected. 7373Thus it is never necessary to use @code{pragma Unreferenced} for such 7374variables, though it is harmless to do so. 7375 7376@node Pragma Unreferenced_Objects 7377@unnumberedsec Pragma Unreferenced_Objects 7378@findex Unreferenced_Objects 7379@cindex Warnings, unreferenced 7380@noindent 7381Syntax: 7382 7383@smallexample @c ada 7384pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); 7385@end smallexample 7386 7387@noindent 7388This pragma signals that for the types or subtypes whose names are 7389listed, objects which are declared with one of these types or subtypes may 7390not be referenced, and if no references appear, no warnings are given. 7391 7392This is particularly useful for objects which are declared solely for their 7393initialization and finalization effect. Such variables are sometimes referred 7394to as RAII variables (Resource Acquisition Is Initialization). Using this 7395pragma on the relevant type (most typically a limited controlled type), the 7396compiler will automatically suppress unwanted warnings about these variables 7397not being referenced. 7398 7399@node Pragma Unreserve_All_Interrupts 7400@unnumberedsec Pragma Unreserve_All_Interrupts 7401@findex Unreserve_All_Interrupts 7402@noindent 7403Syntax: 7404 7405@smallexample @c ada 7406pragma Unreserve_All_Interrupts; 7407@end smallexample 7408 7409@noindent 7410Normally certain interrupts are reserved to the implementation. Any attempt 7411to attach an interrupt causes Program_Error to be raised, as described in 7412RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 7413many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is 7414reserved to the implementation, so that @kbd{Ctrl-C} can be used to 7415interrupt execution. 7416 7417If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in 7418a program, then all such interrupts are unreserved. This allows the 7419program to handle these interrupts, but disables their standard 7420functions. For example, if this pragma is used, then pressing 7421@kbd{Ctrl-C} will not automatically interrupt execution. However, 7422a program can then handle the @code{SIGINT} interrupt as it chooses. 7423 7424For a full list of the interrupts handled in a specific implementation, 7425see the source code for the spec of @code{Ada.Interrupts.Names} in 7426file @file{a-intnam.ads}. This is a target dependent file that contains the 7427list of interrupts recognized for a given target. The documentation in 7428this file also specifies what interrupts are affected by the use of 7429the @code{Unreserve_All_Interrupts} pragma. 7430 7431For a more general facility for controlling what interrupts can be 7432handled, see pragma @code{Interrupt_State}, which subsumes the functionality 7433of the @code{Unreserve_All_Interrupts} pragma. 7434 7435@node Pragma Unsuppress 7436@unnumberedsec Pragma Unsuppress 7437@findex Unsuppress 7438@noindent 7439Syntax: 7440 7441@smallexample @c ada 7442pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 7443@end smallexample 7444 7445@noindent 7446This pragma undoes the effect of a previous pragma @code{Suppress}. If 7447there is no corresponding pragma @code{Suppress} in effect, it has no 7448effect. The range of the effect is the same as for pragma 7449@code{Suppress}. The meaning of the arguments is identical to that used 7450in pragma @code{Suppress}. 7451 7452One important application is to ensure that checks are on in cases where 7453code depends on the checks for its correct functioning, so that the code 7454will compile correctly even if the compiler switches are set to suppress 7455checks. 7456 7457This pragma is standard in Ada 2005. It is available in all earlier versions 7458of Ada as an implementation-defined pragma. 7459 7460Note that in addition to the checks defined in the Ada RM, GNAT recogizes 7461a number of implementation-defined check names. See description of pragma 7462@code{Suppress} for full details. 7463 7464@node Pragma Use_VADS_Size 7465@unnumberedsec Pragma Use_VADS_Size 7466@cindex @code{Size}, VADS compatibility 7467@cindex Rational profile 7468@findex Use_VADS_Size 7469@noindent 7470Syntax: 7471 7472@smallexample @c ada 7473pragma Use_VADS_Size; 7474@end smallexample 7475 7476@noindent 7477This is a configuration pragma. In a unit to which it applies, any use 7478of the 'Size attribute is automatically interpreted as a use of the 7479'VADS_Size attribute. Note that this may result in incorrect semantic 7480processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 7481the handling of existing code which depends on the interpretation of Size 7482as implemented in the VADS compiler. See description of the VADS_Size 7483attribute for further details. 7484 7485@node Pragma Validity_Checks 7486@unnumberedsec Pragma Validity_Checks 7487@findex Validity_Checks 7488@noindent 7489Syntax: 7490 7491@smallexample @c ada 7492pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 7493@end smallexample 7494 7495@noindent 7496This pragma is used in conjunction with compiler switches to control the 7497built-in validity checking provided by GNAT@. The compiler switches, if set 7498provide an initial setting for the switches, and this pragma may be used 7499to modify these settings, or the settings may be provided entirely by 7500the use of the pragma. This pragma can be used anywhere that a pragma 7501is legal, including use as a configuration pragma (including use in 7502the @file{gnat.adc} file). 7503 7504The form with a string literal specifies which validity options are to be 7505activated. The validity checks are first set to include only the default 7506reference manual settings, and then a string of letters in the string 7507specifies the exact set of options required. The form of this string 7508is exactly as described for the @option{-gnatVx} compiler switch (see the 7509@value{EDITION} User's Guide for details). For example the following two 7510methods can be used to enable validity checking for mode @code{in} and 7511@code{in out} subprogram parameters: 7512 7513@itemize @bullet 7514@item 7515@smallexample @c ada 7516pragma Validity_Checks ("im"); 7517@end smallexample 7518 7519@item 7520@smallexample 7521gcc -c -gnatVim @dots{} 7522@end smallexample 7523@end itemize 7524 7525@noindent 7526The form ALL_CHECKS activates all standard checks (its use is equivalent 7527to the use of the @code{gnatva} switch. 7528 7529The forms with @code{Off} and @code{On} 7530can be used to temporarily disable validity checks 7531as shown in the following example: 7532 7533@smallexample @c ada 7534@iftex 7535@leftskip=0cm 7536@end iftex 7537pragma Validity_Checks ("c"); -- validity checks for copies 7538pragma Validity_Checks (Off); -- turn off validity checks 7539A := B; -- B will not be validity checked 7540pragma Validity_Checks (On); -- turn validity checks back on 7541A := C; -- C will be validity checked 7542@end smallexample 7543 7544@node Pragma Volatile 7545@unnumberedsec Pragma Volatile 7546@findex Volatile 7547@noindent 7548Syntax: 7549 7550@smallexample @c ada 7551pragma Volatile (LOCAL_NAME); 7552@end smallexample 7553 7554@noindent 7555This pragma is defined by the Ada Reference Manual, and the GNAT 7556implementation is fully conformant with this definition. The reason it 7557is mentioned in this section is that a pragma of the same name was supplied 7558in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 7559implementation of pragma Volatile is upwards compatible with the 7560implementation in DEC Ada 83. 7561 7562@node Pragma Warning_As_Error 7563@unnumberedsec Pragma Warning_As_Error 7564@findex Warning_As_Error 7565@noindent 7566Syntax: 7567 7568@smallexample @c ada 7569pragma Warning_As_Error (static_string_EXPRESSION); 7570@end smallexample 7571 7572@noindent 7573This configuration pragma allows the programmer to specify a set 7574of warnings that will be treated as errors. Any warning which 7575matches the pattern given by the pragma argument will be treated 7576as an error. This gives much more precise control that -gnatwe 7577which treats all warnings as errors. 7578 7579The pattern may contain asterisks, which match zero or more characters in 7580the message. For example, you can use 7581@code{pragma Warning_As_Error ("*bits of*unused")} to treat the warning 7582message @code{warning: 960 bits of "a" unused} as an error. No other regular 7583expression notations are permitted. All characters other than asterisk in 7584these three specific cases are treated as literal characters in the match. 7585The match is case insensitive, for example XYZ matches xyz. 7586 7587Another possibility for the static_string_EXPRESSION which works whether 7588or not error tags are enabled (@option{-gnatw.d}) is to use the 7589@option{-gnatw} tag string, enclosed in brackets, 7590as shown in the example below, to treat a class of warnings as errors. 7591 7592The above use of patterns to match the message applies only to warning 7593messages generated by the front end. This pragma can also be applied to 7594warnings provided by the back end and mentioned in @ref{Pragma Warnings}. 7595By using a single full @option{-Wxxx} switch in the pragma, such warnings 7596can also be treated as errors. 7597 7598The pragma can appear either in a global configuration pragma file 7599(e.g. @file{gnat.adc}), or at the start of a file. Given a global 7600configuration pragma file containing: 7601 7602@smallexample @c ada 7603pragma Warning_As_Error ("[-gnatwj]"); 7604@end smallexample 7605 7606@noindent 7607which will treat all obsolescent feature warnings as errors, the 7608following program compiles as shown (compile options here are 7609@option{-gnatwa.d -gnatl -gnatj55}). 7610 7611@smallexample @c ada 7612 1. pragma Warning_As_Error ("*never assigned*"); 7613 2. function Warnerr return String is 7614 3. X : Integer; 7615 | 7616 >>> error: variable "X" is never read and 7617 never assigned [-gnatwv] [warning-as-error] 7618 7619 4. Y : Integer; 7620 | 7621 >>> warning: variable "Y" is assigned but 7622 never read [-gnatwu] 7623 7624 5. begin 7625 6. Y := 0; 7626 7. return %ABC%; 7627 | 7628 >>> error: use of "%" is an obsolescent 7629 feature (RM J.2(4)), use """ instead 7630 [-gnatwj] [warning-as-error] 7631 7632 8. end; 7633 7634 8 lines: No errors, 3 warnings (2 treated as errors) 7635@end smallexample 7636 7637@noindent 7638Note that this pragma does not affect the set of warnings issued in 7639any way, it merely changes the effect of a matching warning if one 7640is produced as a result of other warnings options. As shown in this 7641example, if the pragma results in a warning being treated as an error, 7642the tag is changed from "warning:" to "error:" and the string 7643"[warning-as-error]" is appended to the end of the message. 7644 7645@node Pragma Warnings 7646@unnumberedsec Pragma Warnings 7647@findex Warnings 7648@noindent 7649Syntax: 7650 7651@smallexample @c ada 7652pragma Warnings (On | Off [,REASON]); 7653pragma Warnings (On | Off, LOCAL_NAME [,REASON]); 7654pragma Warnings (static_string_EXPRESSION [,REASON]); 7655pragma Warnings (On | Off, static_string_EXPRESSION [,REASON]); 7656 7657REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} 7658@end smallexample 7659 7660@noindent 7661Normally warnings are enabled, with the output being controlled by 7662the command line switch. Warnings (@code{Off}) turns off generation of 7663warnings until a Warnings (@code{On}) is encountered or the end of the 7664current unit. If generation of warnings is turned off using this 7665pragma, then some or all of the warning messages are suppressed, 7666regardless of the setting of the command line switches. 7667 7668The @code{Reason} parameter may optionally appear as the last argument 7669in any of the forms of this pragma. It is intended purely for the 7670purposes of documenting the reason for the @code{Warnings} pragma. 7671The compiler will check that the argument is a static string but 7672otherwise ignore this argument. Other tools may provide specialized 7673processing for this string. 7674 7675The form with a single argument (or two arguments if Reason present), 7676where the first argument is @code{ON} or @code{OFF} 7677may be used as a configuration pragma. 7678 7679If the @var{LOCAL_NAME} parameter is present, warnings are suppressed for 7680the specified entity. This suppression is effective from the point where 7681it occurs till the end of the extended scope of the variable (similar to 7682the scope of @code{Suppress}). This form cannot be used as a configuration 7683pragma. 7684 7685The form with a single static_string_EXPRESSION argument (and possible 7686reason) provides more precise 7687control over which warnings are active. The string is a list of letters 7688specifying which warnings are to be activated and which deactivated. The 7689code for these letters is the same as the string used in the command 7690line switch controlling warnings. For a brief summary, use the gnatmake 7691command with no arguments, which will generate usage information containing 7692the list of warnings switches supported. For 7693full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION} 7694User's Guide}. This form can also be used as a configuration pragma. 7695 7696@noindent 7697The warnings controlled by the @option{-gnatw} switch are generated by the 7698front end of the compiler. The GCC back end can provide additional warnings 7699and they are controlled by the @option{-W} switch. Such warnings can be 7700identified by the appearance of a string of the form @code{[-Wxxx]} in the 7701message which designates the @option{-Wxxx} switch that controls the message. 7702The form with a single static_string_EXPRESSION argument also works for these 7703warnings, but the string must be a single full @option{-Wxxx} switch in this 7704case. The above reference lists a few examples of these additional warnings. 7705 7706@noindent 7707The specified warnings will be in effect until the end of the program 7708or another pragma Warnings is encountered. The effect of the pragma is 7709cumulative. Initially the set of warnings is the standard default set 7710as possibly modified by compiler switches. Then each pragma Warning 7711modifies this set of warnings as specified. This form of the pragma may 7712also be used as a configuration pragma. 7713 7714The fourth form, with an @code{On|Off} parameter and a string, is used to 7715control individual messages, based on their text. The string argument 7716is a pattern that is used to match against the text of individual 7717warning messages (not including the initial "warning: " tag). 7718 7719The pattern may contain asterisks, which match zero or more characters in 7720the message. For example, you can use 7721@code{pragma Warnings (Off, "*bits of*unused")} to suppress the warning 7722message @code{warning: 960 bits of "a" unused}. No other regular 7723expression notations are permitted. All characters other than asterisk in 7724these three specific cases are treated as literal characters in the match. 7725The match is case insensitive, for example XYZ matches xyz. 7726 7727The above use of patterns to match the message applies only to warning 7728messages generated by the front end. This form of the pragma with a string 7729argument can also be used to control warnings provided by the back end and 7730mentioned above. By using a single full @option{-Wxxx} switch in the pragma, 7731such warnings can be turned on and off. 7732 7733There are two ways to use the pragma in this form. The OFF form can be used as a 7734configuration pragma. The effect is to suppress all warnings (if any) 7735that match the pattern string throughout the compilation (or match the 7736-W switch in the back end case). 7737 7738The second usage is to suppress a warning locally, and in this case, two 7739pragmas must appear in sequence: 7740 7741@smallexample @c ada 7742pragma Warnings (Off, Pattern); 7743@dots{} code where given warning is to be suppressed 7744pragma Warnings (On, Pattern); 7745@end smallexample 7746 7747@noindent 7748In this usage, the pattern string must match in the Off and On pragmas, 7749and at least one matching warning must be suppressed. 7750 7751Note: to write a string that will match any warning, use the string 7752@code{"***"}. It will not work to use a single asterisk or two asterisks 7753since this looks like an operator name. This form with three asterisks 7754is similar in effect to specifying @code{pragma Warnings (Off)} except that a 7755matching @code{pragma Warnings (On, "***")} will be required. This can be 7756helpful in avoiding forgetting to turn warnings back on. 7757 7758Note: the debug flag -gnatd.i (@code{/NOWARNINGS_PRAGMAS} in VMS) can be 7759used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 7760be useful in checking whether obsolete pragmas in existing programs are hiding 7761real problems. 7762 7763Note: pragma Warnings does not affect the processing of style messages. See 7764separate entry for pragma Style_Checks for control of style messages. 7765 7766@node Pragma Weak_External 7767@unnumberedsec Pragma Weak_External 7768@findex Weak_External 7769@noindent 7770Syntax: 7771 7772@smallexample @c ada 7773pragma Weak_External ([Entity =>] LOCAL_NAME); 7774@end smallexample 7775 7776@noindent 7777@var{LOCAL_NAME} must refer to an object that is declared at the library 7778level. This pragma specifies that the given entity should be marked as a 7779weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} 7780in GNU C and causes @var{LOCAL_NAME} to be emitted as a weak symbol instead 7781of a regular symbol, that is to say a symbol that does not have to be 7782resolved by the linker if used in conjunction with a pragma Import. 7783 7784When a weak symbol is not resolved by the linker, its address is set to 7785zero. This is useful in writing interfaces to external modules that may 7786or may not be linked in the final executable, for example depending on 7787configuration settings. 7788 7789If a program references at run time an entity to which this pragma has been 7790applied, and the corresponding symbol was not resolved at link time, then 7791the execution of the program is erroneous. It is not erroneous to take the 7792Address of such an entity, for example to guard potential references, 7793as shown in the example below. 7794 7795Some file formats do not support weak symbols so not all target machines 7796support this pragma. 7797 7798@smallexample @c ada 7799-- Example of the use of pragma Weak_External 7800 7801package External_Module is 7802 key : Integer; 7803 pragma Import (C, key); 7804 pragma Weak_External (key); 7805 function Present return boolean; 7806end External_Module; 7807 7808with System; use System; 7809package body External_Module is 7810 function Present return boolean is 7811 begin 7812 return key'Address /= System.Null_Address; 7813 end Present; 7814end External_Module; 7815@end smallexample 7816 7817@node Pragma Wide_Character_Encoding 7818@unnumberedsec Pragma Wide_Character_Encoding 7819@findex Wide_Character_Encoding 7820@noindent 7821Syntax: 7822 7823@smallexample @c ada 7824pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 7825@end smallexample 7826 7827@noindent 7828This pragma specifies the wide character encoding to be used in program 7829source text appearing subsequently. It is a configuration pragma, but may 7830also be used at any point that a pragma is allowed, and it is permissible 7831to have more than one such pragma in a file, allowing multiple encodings 7832to appear within the same file. 7833 7834The argument can be an identifier or a character literal. In the identifier 7835case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, 7836@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal 7837case it is correspondingly one of the characters @samp{h}, @samp{u}, 7838@samp{s}, @samp{e}, @samp{8}, or @samp{b}. 7839 7840Note that when the pragma is used within a file, it affects only the 7841encoding within that file, and does not affect withed units, specs, 7842or subunits. 7843 7844@node Implementation Defined Aspects 7845@chapter Implementation Defined Aspects 7846Ada defines (throughout the Ada 2012 reference manual, summarized 7847in Annex K) a set of aspects that can be specified for certain entities. 7848These language defined aspects are implemented in GNAT in Ada 2012 mode 7849and work as described in the Ada 2012 Reference Manual. 7850 7851In addition, Ada 2012 allows implementations to define additional aspects 7852whose meaning is defined by the implementation. GNAT provides 7853a number of these implementation-defined aspects which can be used 7854to extend and enhance the functionality of the compiler. This section of 7855the GNAT reference manual describes these additional aspects. 7856 7857Note that any program using these aspects may not be portable to 7858other compilers (although GNAT implements this set of aspects on all 7859platforms). Therefore if portability to other compilers is an important 7860consideration, you should minimize the use of these aspects. 7861 7862Note that for many of these aspects, the effect is essentially similar 7863to the use of a pragma or attribute specification with the same name 7864applied to the entity. For example, if we write: 7865 7866@smallexample @c ada 7867type R is range 1 .. 100 7868 with Value_Size => 10; 7869@end smallexample 7870 7871@noindent 7872then the effect is the same as: 7873 7874@smallexample @c ada 7875type R is range 1 .. 100; 7876for R'Value_Size use 10; 7877@end smallexample 7878 7879@noindent 7880and if we write: 7881 7882@smallexample @c ada 7883type R is new Integer 7884 with Shared => True; 7885@end smallexample 7886 7887@noindent 7888then the effect is the same as: 7889 7890@smallexample @c ada 7891type R is new Integer; 7892pragma Shared (R); 7893@end smallexample 7894 7895@noindent 7896In the documentation below, such cases are simply marked 7897as being equivalent to the corresponding pragma or attribute definition 7898clause. 7899 7900@menu 7901* Aspect Abstract_State:: 7902* Aspect Contract_Cases:: 7903* Aspect Depends:: 7904* Aspect Dimension:: 7905* Aspect Dimension_System:: 7906* Aspect Favor_Top_Level:: 7907* Aspect Global:: 7908* Aspect Initial_Condition:: 7909* Aspect Initializes:: 7910* Aspect Inline_Always:: 7911* Aspect Invariant:: 7912* Aspect Linker_Section:: 7913* Aspect Lock_Free:: 7914* Aspect Object_Size:: 7915* Aspect Persistent_BSS:: 7916* Aspect Predicate:: 7917* Aspect Preelaborate_05:: 7918* Aspect Pure_05:: 7919* Aspect Pure_12:: 7920* Aspect Pure_Function:: 7921* Aspect Refined_State:: 7922* Aspect Remote_Access_Type:: 7923* Aspect Scalar_Storage_Order:: 7924* Aspect Shared:: 7925* Aspect Simple_Storage_Pool:: 7926* Aspect Simple_Storage_Pool_Type:: 7927* Aspect SPARK_Mode:: 7928* Aspect Suppress_Debug_Info:: 7929* Aspect Test_Case:: 7930* Aspect Universal_Aliasing:: 7931* Aspect Universal_Data:: 7932* Aspect Unmodified:: 7933* Aspect Unreferenced:: 7934* Aspect Unreferenced_Objects:: 7935* Aspect Value_Size:: 7936* Aspect Warnings:: 7937@end menu 7938 7939@node Aspect Abstract_State 7940@unnumberedsec Aspect Abstract_State 7941@findex Abstract_State 7942@noindent 7943This aspect is equivalent to pragma @code{Abstract_State}. 7944 7945@node Aspect Contract_Cases 7946@unnumberedsec Aspect Contract_Cases 7947@findex Contract_Cases 7948@noindent 7949This aspect is equivalent to pragma @code{Contract_Cases}, the sequence 7950of clauses being enclosed in parentheses so that syntactically it is an 7951aggregate. 7952 7953@node Aspect Depends 7954@unnumberedsec Aspect Depends 7955@findex Depends 7956@noindent 7957This aspect is equivalent to pragma @code{Depends}. 7958 7959@node Aspect Dimension 7960@unnumberedsec Aspect Dimension 7961@findex Dimension 7962@noindent 7963The @code{Dimension} aspect is used to specify the dimensions of a given 7964subtype of a dimensioned numeric type. The aspect also specifies a symbol 7965used when doing formatted output of dimensioned quantities. The syntax is: 7966 7967@smallexample @c ada 7968with Dimension => 7969 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) 7970 7971SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL 7972 7973DIMENSION_VALUE ::= 7974 RATIONAL 7975| others => RATIONAL 7976| DISCRETE_CHOICE_LIST => RATIONAL 7977 7978RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] 7979@end smallexample 7980 7981@noindent 7982This aspect can only be applied to a subtype whose parent type has 7983a @code{Dimension_Systen} aspect. The aspect must specify values for 7984all dimensions of the system. The rational values are the powers of the 7985corresponding dimensions that are used by the compiler to verify that 7986physical (numeric) computations are dimensionally consistent. For example, 7987the computation of a force must result in dimensions (L => 1, M => 1, T => -2). 7988For further examples of the usage 7989of this aspect, see package @code{System.Dim.Mks}. 7990Note that when the dimensioned type is an integer type, then any 7991dimension value must be an integer literal. 7992 7993@node Aspect Dimension_System 7994@unnumberedsec Aspect Dimension_System 7995@findex Dimension_System 7996@noindent 7997The @code{Dimension_System} aspect is used to define a system of 7998dimensions that will be used in subsequent subtype declarations with 7999@code{Dimension} aspects that reference this system. The syntax is: 8000 8001@smallexample @c ada 8002with Dimension_System => (DIMENSION @{, DIMENSION@}); 8003 8004DIMENSION ::= ([Unit_Name =>] IDENTIFIER, 8005 [Unit_Symbol =>] SYMBOL, 8006 [Dim_Symbol =>] SYMBOL) 8007 8008SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL 8009@end smallexample 8010 8011@noindent 8012This aspect is applied to a type, which must be a numeric derived type 8013(typically a floating-point type), that 8014will represent values within the dimension system. Each @code{DIMENSION} 8015corresponds to one particular dimension. A maximum of 7 dimensions may 8016be specified. @code{Unit_Name} is the name of the dimension (for example 8017@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities 8018of this dimension (for example @code{m} for @code{Meter}). 8019@code{Dim_Symbol} gives 8020the identification within the dimension system (typically this is a 8021single letter, e.g. @code{L} standing for length for unit name @code{Meter}). 8022The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. 8023The @code{Dim_Symbol} is used in error messages when numeric operations have 8024inconsistent dimensions. 8025 8026GNAT provides the standard definition of the International MKS system in 8027the run-time package @code{System.Dim.Mks}. You can easily define 8028similar packages for cgs units or British units, and define conversion factors 8029between values in different systems. The MKS system is characterized by the 8030following aspect: 8031 8032@smallexample @c ada 8033 type Mks_Type is new Long_Long_Float 8034 with 8035 Dimension_System => ( 8036 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), 8037 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), 8038 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), 8039 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), 8040 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"), 8041 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), 8042 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); 8043@end smallexample 8044 8045@noindent 8046See section ``Performing Dimensionality Analysis in GNAT'' in the GNAT Users 8047Guide for detailed examples of use of the dimension system. 8048 8049@node Aspect Favor_Top_Level 8050@unnumberedsec Aspect Favor_Top_Level 8051@findex Favor_Top_Level 8052@noindent 8053This aspect is equivalent to pragma @code{Favor_Top_Level}. 8054 8055@node Aspect Global 8056@unnumberedsec Aspect Global 8057@findex Global 8058@noindent 8059This aspect is equivalent to pragma @code{Global}. 8060 8061@node Aspect Initial_Condition 8062@unnumberedsec Aspect Initial_Condition 8063@findex Initial_Condition 8064@noindent 8065This aspect is equivalent to pragma @code{Initial_Condition}. 8066 8067@node Aspect Initializes 8068@unnumberedsec Aspect Initializes 8069@findex Initializes 8070@noindent 8071This aspect is equivalent to pragma @code{Initializes}. 8072 8073@node Aspect Inline_Always 8074@unnumberedsec Aspect Inline_Always 8075@findex Inline_Always 8076@noindent 8077This aspect is equivalent to pragma @code{Inline_Always}. 8078 8079@node Aspect Invariant 8080@unnumberedsec Aspect Invariant 8081@findex Invariant 8082@noindent 8083This aspect is equivalent to pragma @code{Invariant}. It is a 8084synonym for the language defined aspect @code{Type_Invariant} except 8085that it is separately controllable using pragma @code{Assertion_Policy}. 8086 8087@node Aspect Linker_Section 8088@unnumberedsec Aspect Linker_Section 8089@findex Linker_Section 8090@noindent 8091This aspect is equivalent to an @code{Linker_Section} pragma. 8092 8093@node Aspect Lock_Free 8094@unnumberedsec Aspect Lock_Free 8095@findex Lock_Free 8096@noindent 8097This aspect is equivalent to pragma @code{Lock_Free}. 8098 8099@node Aspect Object_Size 8100@unnumberedsec Aspect Object_Size 8101@findex Object_Size 8102@noindent 8103This aspect is equivalent to an @code{Object_Size} attribute definition 8104clause. 8105 8106@node Aspect Persistent_BSS 8107@unnumberedsec Aspect Persistent_BSS 8108@findex Persistent_BSS 8109@noindent 8110This aspect is equivalent to pragma @code{Persistent_BSS}. 8111 8112@node Aspect Predicate 8113@unnumberedsec Aspect Predicate 8114@findex Predicate 8115@noindent 8116This aspect is equivalent to pragma @code{Predicate}. It is thus 8117similar to the language defined aspects @code{Dynamic_Predicate} 8118and @code{Static_Predicate} except that whether the resulting 8119predicate is static or dynamic is controlled by the form of the 8120expression. It is also separately controllable using pragma 8121@code{Assertion_Policy}. 8122 8123@node Aspect Preelaborate_05 8124@unnumberedsec Aspect Preelaborate_05 8125@findex Preelaborate_05 8126@noindent 8127This aspect is equivalent to pragma @code{Preelaborate_05}. 8128 8129@node Aspect Pure_05 8130@unnumberedsec Aspect Pure_05 8131@findex Pure_05 8132@noindent 8133This aspect is equivalent to pragma @code{Pure_05}. 8134 8135@node Aspect Pure_12 8136@unnumberedsec Aspect Pure_12 8137@findex Pure_12 8138@noindent 8139This aspect is equivalent to pragma @code{Pure_12}. 8140 8141@node Aspect Pure_Function 8142@unnumberedsec Aspect Pure_Function 8143@findex Pure_Function 8144@noindent 8145This aspect is equivalent to pragma @code{Pure_Function}. 8146 8147@node Aspect Refined_State 8148@unnumberedsec Aspect Refined_State 8149@findex Refined_State 8150@noindent 8151This aspect is equivalent to pragma @code{Refined_State}. 8152 8153@node Aspect Remote_Access_Type 8154@unnumberedsec Aspect Remote_Access_Type 8155@findex Remote_Access_Type 8156@noindent 8157This aspect is equivalent to pragma @code{Remote_Access_Type}. 8158 8159@node Aspect Scalar_Storage_Order 8160@unnumberedsec Aspect Scalar_Storage_Order 8161@findex Scalar_Storage_Order 8162@noindent 8163This aspect is equivalent to a @code{Scalar_Storage_Order} 8164attribute definition clause. 8165 8166@node Aspect Shared 8167@unnumberedsec Aspect Shared 8168@findex Shared 8169@noindent 8170This aspect is equivalent to pragma @code{Shared}, and is thus a synonym 8171for aspect @code{Atomic}. 8172 8173@node Aspect Simple_Storage_Pool 8174@unnumberedsec Aspect Simple_Storage_Pool 8175@findex Simple_Storage_Pool 8176@noindent 8177This aspect is equivalent to a @code{Simple_Storage_Pool} 8178attribute definition clause. 8179 8180@node Aspect Simple_Storage_Pool_Type 8181@unnumberedsec Aspect Simple_Storage_Pool_Type 8182@findex Simple_Storage_Pool_Type 8183@noindent 8184This aspect is equivalent to pragma @code{Simple_Storage_Pool_Type}. 8185 8186@node Aspect SPARK_Mode 8187@unnumberedsec Aspect SPARK_Mode 8188@findex SPARK_Mode 8189@noindent 8190This aspect is equivalent to pragma @code{SPARK_Mode} and 8191may be specified for either or both of the specification and body 8192of a subprogram or package. 8193 8194@node Aspect Suppress_Debug_Info 8195@unnumberedsec Aspect Suppress_Debug_Info 8196@findex Suppress_Debug_Info 8197@noindent 8198This aspect is equivalent to pragma @code{Suppress_Debug_Info}. 8199 8200@node Aspect Test_Case 8201@unnumberedsec Aspect Test_Case 8202@findex Test_Case 8203@noindent 8204This aspect is equivalent to pragma @code{Test_Case}. 8205 8206@node Aspect Universal_Aliasing 8207@unnumberedsec Aspect Universal_Aliasing 8208@findex Universal_Aliasing 8209@noindent 8210This aspect is equivalent to pragma @code{Universal_Aliasing}. 8211 8212@node Aspect Universal_Data 8213@unnumberedsec Aspect Universal_Data 8214@findex Universal_Data 8215@noindent 8216This aspect is equivalent to pragma @code{Universal_Data}. 8217 8218@node Aspect Unmodified 8219@unnumberedsec Aspect Unmodified 8220@findex Unmodified 8221@noindent 8222This aspect is equivalent to pragma @code{Unmodified}. 8223 8224@node Aspect Unreferenced 8225@unnumberedsec Aspect Unreferenced 8226@findex Unreferenced 8227@noindent 8228This aspect is equivalent to pragma @code{Unreferenced}. 8229 8230@node Aspect Unreferenced_Objects 8231@unnumberedsec Aspect Unreferenced_Objects 8232@findex Unreferenced_Objects 8233@noindent 8234This aspect is equivalent to pragma @code{Unreferenced_Objects}. 8235 8236@node Aspect Value_Size 8237@unnumberedsec Aspect Value_Size 8238@findex Value_Size 8239@noindent 8240This aspect is equivalent to a @code{Value_Size} 8241attribute definition clause. 8242 8243@node Aspect Warnings 8244@unnumberedsec Aspect Warnings 8245@findex Warnings 8246@noindent 8247This aspect is equivalent to the two argument form of pragma @code{Warnings}, 8248where the first argument is @code{ON} or @code{OFF} and the second argument 8249is the entity. 8250 8251 8252@node Implementation Defined Attributes 8253@chapter Implementation Defined Attributes 8254Ada defines (throughout the Ada reference manual, 8255summarized in Annex K), 8256a set of attributes that provide useful additional functionality in all 8257areas of the language. These language defined attributes are implemented 8258in GNAT and work as described in the Ada Reference Manual. 8259 8260In addition, Ada allows implementations to define additional 8261attributes whose meaning is defined by the implementation. GNAT provides 8262a number of these implementation-dependent attributes which can be used 8263to extend and enhance the functionality of the compiler. This section of 8264the GNAT reference manual describes these additional attributes. 8265 8266Note that any program using these attributes may not be portable to 8267other compilers (although GNAT implements this set of attributes on all 8268platforms). Therefore if portability to other compilers is an important 8269consideration, you should minimize the use of these attributes. 8270 8271@menu 8272* Attribute Abort_Signal:: 8273* Attribute Address_Size:: 8274* Attribute Asm_Input:: 8275* Attribute Asm_Output:: 8276* Attribute AST_Entry:: 8277* Attribute Bit:: 8278* Attribute Bit_Position:: 8279* Attribute Compiler_Version:: 8280* Attribute Code_Address:: 8281* Attribute Default_Bit_Order:: 8282* Attribute Descriptor_Size:: 8283* Attribute Elaborated:: 8284* Attribute Elab_Body:: 8285* Attribute Elab_Spec:: 8286* Attribute Elab_Subp_Body:: 8287* Attribute Emax:: 8288* Attribute Enabled:: 8289* Attribute Enum_Rep:: 8290* Attribute Enum_Val:: 8291* Attribute Epsilon:: 8292* Attribute Fixed_Value:: 8293* Attribute Has_Access_Values:: 8294* Attribute Has_Discriminants:: 8295* Attribute Img:: 8296* Attribute Integer_Value:: 8297* Attribute Invalid_Value:: 8298* Attribute Large:: 8299* Attribute Library_Level:: 8300* Attribute Loop_Entry:: 8301* Attribute Machine_Size:: 8302* Attribute Mantissa:: 8303* Attribute Max_Interrupt_Priority:: 8304* Attribute Max_Priority:: 8305* Attribute Maximum_Alignment:: 8306* Attribute Mechanism_Code:: 8307* Attribute Null_Parameter:: 8308* Attribute Object_Size:: 8309* Attribute Passed_By_Reference:: 8310* Attribute Pool_Address:: 8311* Attribute Range_Length:: 8312* Attribute Ref:: 8313* Attribute Restriction_Set:: 8314* Attribute Result:: 8315* Attribute Safe_Emax:: 8316* Attribute Safe_Large:: 8317* Attribute Scalar_Storage_Order:: 8318* Attribute Simple_Storage_Pool:: 8319* Attribute Small:: 8320* Attribute Storage_Unit:: 8321* Attribute Stub_Type:: 8322* Attribute System_Allocator_Alignment:: 8323* Attribute Target_Name:: 8324* Attribute Tick:: 8325* Attribute To_Address:: 8326* Attribute Type_Class:: 8327* Attribute UET_Address:: 8328* Attribute Unconstrained_Array:: 8329* Attribute Universal_Literal_String:: 8330* Attribute Unrestricted_Access:: 8331* Attribute Update:: 8332* Attribute Valid_Scalars:: 8333* Attribute VADS_Size:: 8334* Attribute Value_Size:: 8335* Attribute Wchar_T_Size:: 8336* Attribute Word_Size:: 8337@end menu 8338 8339@node Attribute Abort_Signal 8340@unnumberedsec Attribute Abort_Signal 8341@findex Abort_Signal 8342@noindent 8343@code{Standard'Abort_Signal} (@code{Standard} is the only allowed 8344prefix) provides the entity for the special exception used to signal 8345task abort or asynchronous transfer of control. Normally this attribute 8346should only be used in the tasking runtime (it is highly peculiar, and 8347completely outside the normal semantics of Ada, for a user program to 8348intercept the abort exception). 8349 8350@node Attribute Address_Size 8351@unnumberedsec Attribute Address_Size 8352@cindex Size of @code{Address} 8353@findex Address_Size 8354@noindent 8355@code{Standard'Address_Size} (@code{Standard} is the only allowed 8356prefix) is a static constant giving the number of bits in an 8357@code{Address}. It is the same value as System.Address'Size, 8358but has the advantage of being static, while a direct 8359reference to System.Address'Size is non-static because Address 8360is a private type. 8361 8362@node Attribute Asm_Input 8363@unnumberedsec Attribute Asm_Input 8364@findex Asm_Input 8365@noindent 8366The @code{Asm_Input} attribute denotes a function that takes two 8367parameters. The first is a string, the second is an expression of the 8368type designated by the prefix. The first (string) argument is required 8369to be a static expression, and is the constraint for the parameter, 8370(e.g.@: what kind of register is required). The second argument is the 8371value to be used as the input argument. The possible values for the 8372constant are the same as those used in the RTL, and are dependent on 8373the configuration file used to built the GCC back end. 8374@ref{Machine Code Insertions} 8375 8376@node Attribute Asm_Output 8377@unnumberedsec Attribute Asm_Output 8378@findex Asm_Output 8379@noindent 8380The @code{Asm_Output} attribute denotes a function that takes two 8381parameters. The first is a string, the second is the name of a variable 8382of the type designated by the attribute prefix. The first (string) 8383argument is required to be a static expression and designates the 8384constraint for the parameter (e.g.@: what kind of register is 8385required). The second argument is the variable to be updated with the 8386result. The possible values for constraint are the same as those used in 8387the RTL, and are dependent on the configuration file used to build the 8388GCC back end. If there are no output operands, then this argument may 8389either be omitted, or explicitly given as @code{No_Output_Operands}. 8390@ref{Machine Code Insertions} 8391 8392@node Attribute AST_Entry 8393@unnumberedsec Attribute AST_Entry 8394@cindex OpenVMS 8395@findex AST_Entry 8396@noindent 8397This attribute is implemented only in OpenVMS versions of GNAT@. Applied to 8398the name of an entry, it yields a value of the predefined type AST_Handler 8399(declared in the predefined package System, as extended by the use of 8400pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to 8401be called when an AST occurs. For further details, refer to the @cite{DEC Ada 8402Language Reference Manual}, section 9.12a. 8403 8404@node Attribute Bit 8405@unnumberedsec Attribute Bit 8406@findex Bit 8407@code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit 8408offset within the storage unit (byte) that contains the first bit of 8409storage allocated for the object. The value of this attribute is of the 8410type @code{Universal_Integer}, and is always a non-negative number not 8411exceeding the value of @code{System.Storage_Unit}. 8412 8413For an object that is a variable or a constant allocated in a register, 8414the value is zero. (The use of this attribute does not force the 8415allocation of a variable to memory). 8416 8417For an object that is a formal parameter, this attribute applies 8418to either the matching actual parameter or to a copy of the 8419matching actual parameter. 8420 8421For an access object the value is zero. Note that 8422@code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the 8423designated object. Similarly for a record component 8424@code{@var{X}.@var{C}'Bit} is subject to a discriminant check and 8425@code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit} 8426are subject to index checks. 8427 8428This attribute is designed to be compatible with the DEC Ada 83 definition 8429and implementation of the @code{Bit} attribute. 8430 8431@node Attribute Bit_Position 8432@unnumberedsec Attribute Bit_Position 8433@findex Bit_Position 8434@noindent 8435@code{@var{R.C}'Bit_Position}, where @var{R} is a record object and C is one 8436of the fields of the record type, yields the bit 8437offset within the record contains the first bit of 8438storage allocated for the object. The value of this attribute is of the 8439type @code{Universal_Integer}. The value depends only on the field 8440@var{C} and is independent of the alignment of 8441the containing record @var{R}. 8442 8443@node Attribute Compiler_Version 8444@unnumberedsec Attribute Compiler_Version 8445@findex Compiler_Version 8446@noindent 8447@code{Standard'Compiler_Version} (@code{Standard} is the only allowed 8448prefix) yields a static string identifying the version of the compiler 8449being used to compile the unit containing the attribute reference. A 8450typical result would be something like "@value{EDITION} @i{version} (20090221)". 8451 8452@node Attribute Code_Address 8453@unnumberedsec Attribute Code_Address 8454@findex Code_Address 8455@cindex Subprogram address 8456@cindex Address of subprogram code 8457@noindent 8458The @code{'Address} 8459attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 8460intended effect seems to be to provide 8461an address value which can be used to call the subprogram by means of 8462an address clause as in the following example: 8463 8464@smallexample @c ada 8465procedure K is @dots{} 8466 8467procedure L; 8468for L'Address use K'Address; 8469pragma Import (Ada, L); 8470@end smallexample 8471 8472@noindent 8473A call to @code{L} is then expected to result in a call to @code{K}@. 8474In Ada 83, where there were no access-to-subprogram values, this was 8475a common work-around for getting the effect of an indirect call. 8476GNAT implements the above use of @code{Address} and the technique 8477illustrated by the example code works correctly. 8478 8479However, for some purposes, it is useful to have the address of the start 8480of the generated code for the subprogram. On some architectures, this is 8481not necessarily the same as the @code{Address} value described above. 8482For example, the @code{Address} value may reference a subprogram 8483descriptor rather than the subprogram itself. 8484 8485The @code{'Code_Address} attribute, which can only be applied to 8486subprogram entities, always returns the address of the start of the 8487generated code of the specified subprogram, which may or may not be 8488the same value as is returned by the corresponding @code{'Address} 8489attribute. 8490 8491@node Attribute Default_Bit_Order 8492@unnumberedsec Attribute Default_Bit_Order 8493@cindex Big endian 8494@cindex Little endian 8495@findex Default_Bit_Order 8496@noindent 8497@code{Standard'Default_Bit_Order} (@code{Standard} is the only 8498permissible prefix), provides the value @code{System.Default_Bit_Order} 8499as a @code{Pos} value (0 for @code{High_Order_First}, 1 for 8500@code{Low_Order_First}). This is used to construct the definition of 8501@code{Default_Bit_Order} in package @code{System}. 8502 8503@node Attribute Descriptor_Size 8504@unnumberedsec Attribute Descriptor_Size 8505@cindex Descriptor 8506@cindex Dope vector 8507@findex Descriptor_Size 8508@noindent 8509Non-static attribute @code{Descriptor_Size} returns the size in bits of the 8510descriptor allocated for a type. The result is non-zero only for unconstrained 8511array types and the returned value is of type universal integer. In GNAT, an 8512array descriptor contains bounds information and is located immediately before 8513the first element of the array. 8514 8515@smallexample @c ada 8516type Unconstr_Array is array (Positive range <>) of Boolean; 8517Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 8518@end smallexample 8519 8520@noindent 8521The attribute takes into account any additional padding due to type alignment. 8522In the example above, the descriptor contains two values of type 8523@code{Positive} representing the low and high bound. Since @code{Positive} has 8524a size of 31 bits and an alignment of 4, the descriptor size is @code{2 * 8525Positive'Size + 2} or 64 bits. 8526 8527@node Attribute Elaborated 8528@unnumberedsec Attribute Elaborated 8529@findex Elaborated 8530@noindent 8531The prefix of the @code{'Elaborated} attribute must be a unit name. The 8532value is a Boolean which indicates whether or not the given unit has been 8533elaborated. This attribute is primarily intended for internal use by the 8534generated code for dynamic elaboration checking, but it can also be used 8535in user programs. The value will always be True once elaboration of all 8536units has been completed. An exception is for units which need no 8537elaboration, the value is always False for such units. 8538 8539@node Attribute Elab_Body 8540@unnumberedsec Attribute Elab_Body 8541@findex Elab_Body 8542@noindent 8543This attribute can only be applied to a program unit name. It returns 8544the entity for the corresponding elaboration procedure for elaborating 8545the body of the referenced unit. This is used in the main generated 8546elaboration procedure by the binder and is not normally used in any 8547other context. However, there may be specialized situations in which it 8548is useful to be able to call this elaboration procedure from Ada code, 8549e.g.@: if it is necessary to do selective re-elaboration to fix some 8550error. 8551 8552@node Attribute Elab_Spec 8553@unnumberedsec Attribute Elab_Spec 8554@findex Elab_Spec 8555@noindent 8556This attribute can only be applied to a program unit name. It returns 8557the entity for the corresponding elaboration procedure for elaborating 8558the spec of the referenced unit. This is used in the main 8559generated elaboration procedure by the binder and is not normally used 8560in any other context. However, there may be specialized situations in 8561which it is useful to be able to call this elaboration procedure from 8562Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix 8563some error. 8564 8565@node Attribute Elab_Subp_Body 8566@unnumberedsec Attribute Elab_Subp_Body 8567@findex Elab_Subp_Body 8568@noindent 8569This attribute can only be applied to a library level subprogram 8570name and is only allowed in CodePeer mode. It returns the entity 8571for the corresponding elaboration procedure for elaborating the body 8572of the referenced subprogram unit. This is used in the main generated 8573elaboration procedure by the binder in CodePeer mode only and is unrecognized 8574otherwise. 8575 8576@node Attribute Emax 8577@unnumberedsec Attribute Emax 8578@cindex Ada 83 attributes 8579@findex Emax 8580@noindent 8581The @code{Emax} attribute is provided for compatibility with Ada 83. See 8582the Ada 83 reference manual for an exact description of the semantics of 8583this attribute. 8584 8585@node Attribute Enabled 8586@unnumberedsec Attribute Enabled 8587@findex Enabled 8588@noindent 8589The @code{Enabled} attribute allows an application program to check at compile 8590time to see if the designated check is currently enabled. The prefix is a 8591simple identifier, referencing any predefined check name (other than 8592@code{All_Checks}) or a check name introduced by pragma Check_Name. If 8593no argument is given for the attribute, the check is for the general state 8594of the check, if an argument is given, then it is an entity name, and the 8595check indicates whether an @code{Suppress} or @code{Unsuppress} has been 8596given naming the entity (if not, then the argument is ignored). 8597 8598Note that instantiations inherit the check status at the point of the 8599instantiation, so a useful idiom is to have a library package that 8600introduces a check name with @code{pragma Check_Name}, and then contains 8601generic packages or subprograms which use the @code{Enabled} attribute 8602to see if the check is enabled. A user of this package can then issue 8603a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating 8604the package or subprogram, controlling whether the check will be present. 8605 8606@node Attribute Enum_Rep 8607@unnumberedsec Attribute Enum_Rep 8608@cindex Representation of enums 8609@findex Enum_Rep 8610@noindent 8611For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a 8612function with the following spec: 8613 8614@smallexample @c ada 8615function @var{S}'Enum_Rep (Arg : @var{S}'Base) 8616 return @i{Universal_Integer}; 8617@end smallexample 8618 8619@noindent 8620It is also allowable to apply @code{Enum_Rep} directly to an object of an 8621enumeration type or to a non-overloaded enumeration 8622literal. In this case @code{@var{S}'Enum_Rep} is equivalent to 8623@code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the 8624enumeration literal or object. 8625 8626The function returns the representation value for the given enumeration 8627value. This will be equal to value of the @code{Pos} attribute in the 8628absence of an enumeration representation clause. This is a static 8629attribute (i.e.@: the result is static if the argument is static). 8630 8631@code{@var{S}'Enum_Rep} can also be used with integer types and objects, 8632in which case it simply returns the integer value. The reason for this 8633is to allow it to be used for @code{(<>)} discrete formal arguments in 8634a generic unit that can be instantiated with either enumeration types 8635or integer types. Note that if @code{Enum_Rep} is used on a modular 8636type whose upper bound exceeds the upper bound of the largest signed 8637integer type, and the argument is a variable, so that the universal 8638integer calculation is done at run time, then the call to @code{Enum_Rep} 8639may raise @code{Constraint_Error}. 8640 8641@node Attribute Enum_Val 8642@unnumberedsec Attribute Enum_Val 8643@cindex Representation of enums 8644@findex Enum_Val 8645@noindent 8646For every enumeration subtype @var{S}, @code{@var{S}'Enum_Val} denotes a 8647function with the following spec: 8648 8649@smallexample @c ada 8650function @var{S}'Enum_Val (Arg : @i{Universal_Integer) 8651 return @var{S}'Base}; 8652@end smallexample 8653 8654@noindent 8655The function returns the enumeration value whose representation matches the 8656argument, or raises Constraint_Error if no enumeration literal of the type 8657has the matching value. 8658This will be equal to value of the @code{Val} attribute in the 8659absence of an enumeration representation clause. This is a static 8660attribute (i.e.@: the result is static if the argument is static). 8661 8662@node Attribute Epsilon 8663@unnumberedsec Attribute Epsilon 8664@cindex Ada 83 attributes 8665@findex Epsilon 8666@noindent 8667The @code{Epsilon} attribute is provided for compatibility with Ada 83. See 8668the Ada 83 reference manual for an exact description of the semantics of 8669this attribute. 8670 8671@node Attribute Fixed_Value 8672@unnumberedsec Attribute Fixed_Value 8673@findex Fixed_Value 8674@noindent 8675For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a 8676function with the following specification: 8677 8678@smallexample @c ada 8679function @var{S}'Fixed_Value (Arg : @i{Universal_Integer}) 8680 return @var{S}; 8681@end smallexample 8682 8683@noindent 8684The value returned is the fixed-point value @var{V} such that 8685 8686@smallexample @c ada 8687@var{V} = Arg * @var{S}'Small 8688@end smallexample 8689 8690@noindent 8691The effect is thus similar to first converting the argument to the 8692integer type used to represent @var{S}, and then doing an unchecked 8693conversion to the fixed-point type. The difference is 8694that there are full range checks, to ensure that the result is in range. 8695This attribute is primarily intended for use in implementation of the 8696input-output functions for fixed-point values. 8697 8698@node Attribute Has_Access_Values 8699@unnumberedsec Attribute Has_Access_Values 8700@cindex Access values, testing for 8701@findex Has_Access_Values 8702@noindent 8703The prefix of the @code{Has_Access_Values} attribute is a type. The result 8704is a Boolean value which is True if the is an access type, or is a composite 8705type with a component (at any nesting depth) that is an access type, and is 8706False otherwise. 8707The intended use of this attribute is in conjunction with generic 8708definitions. If the attribute is applied to a generic private type, it 8709indicates whether or not the corresponding actual type has access values. 8710 8711@node Attribute Has_Discriminants 8712@unnumberedsec Attribute Has_Discriminants 8713@cindex Discriminants, testing for 8714@findex Has_Discriminants 8715@noindent 8716The prefix of the @code{Has_Discriminants} attribute is a type. The result 8717is a Boolean value which is True if the type has discriminants, and False 8718otherwise. The intended use of this attribute is in conjunction with generic 8719definitions. If the attribute is applied to a generic private type, it 8720indicates whether or not the corresponding actual type has discriminants. 8721 8722@node Attribute Img 8723@unnumberedsec Attribute Img 8724@findex Img 8725@noindent 8726The @code{Img} attribute differs from @code{Image} in that it is applied 8727directly to an object, and yields the same result as 8728@code{Image} for the subtype of the object. This is convenient for 8729debugging: 8730 8731@smallexample @c ada 8732Put_Line ("X = " & X'Img); 8733@end smallexample 8734 8735@noindent 8736has the same meaning as the more verbose: 8737 8738@smallexample @c ada 8739Put_Line ("X = " & @var{T}'Image (X)); 8740@end smallexample 8741 8742@noindent 8743where @var{T} is the (sub)type of the object @code{X}. 8744 8745Note that technically, in analogy to @code{Image}, 8746@code{X'Img} returns a parameterless function 8747that returns the appropriate string when called. This means that 8748@code{X'Img} can be renamed as a function-returning-string, or used 8749in an instantiation as a function parameter. 8750 8751@node Attribute Integer_Value 8752@unnumberedsec Attribute Integer_Value 8753@findex Integer_Value 8754@noindent 8755For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a 8756function with the following spec: 8757 8758@smallexample @c ada 8759function @var{S}'Integer_Value (Arg : @i{Universal_Fixed}) 8760 return @var{S}; 8761@end smallexample 8762 8763@noindent 8764The value returned is the integer value @var{V}, such that 8765 8766@smallexample @c ada 8767Arg = @var{V} * @var{T}'Small 8768@end smallexample 8769 8770@noindent 8771where @var{T} is the type of @code{Arg}. 8772The effect is thus similar to first doing an unchecked conversion from 8773the fixed-point type to its corresponding implementation type, and then 8774converting the result to the target integer type. The difference is 8775that there are full range checks, to ensure that the result is in range. 8776This attribute is primarily intended for use in implementation of the 8777standard input-output functions for fixed-point values. 8778 8779@node Attribute Invalid_Value 8780@unnumberedsec Attribute Invalid_Value 8781@findex Invalid_Value 8782@noindent 8783For every scalar type S, S'Invalid_Value returns an undefined value of the 8784type. If possible this value is an invalid representation for the type. The 8785value returned is identical to the value used to initialize an otherwise 8786uninitialized value of the type if pragma Initialize_Scalars is used, 8787including the ability to modify the value with the binder -Sxx flag and 8788relevant environment variables at run time. 8789 8790@node Attribute Large 8791@unnumberedsec Attribute Large 8792@cindex Ada 83 attributes 8793@findex Large 8794@noindent 8795The @code{Large} attribute is provided for compatibility with Ada 83. See 8796the Ada 83 reference manual for an exact description of the semantics of 8797this attribute. 8798 8799@node Attribute Library_Level 8800@unnumberedsec Attribute Library_Level 8801@findex Library_Level 8802@noindent 8803@noindent 8804@code{P'Library_Level}, where P is an entity name, 8805returns a Boolean value which is True if the entity is declared 8806at the library level, and False otherwise. Note that within a 8807generic instantition, the name of the generic unit denotes the 8808instance, which means that this attribute can be used to test 8809if a generic is instantiated at the library level, as shown 8810in this example: 8811 8812@smallexample @c ada 8813generic 8814 ... 8815package Gen is 8816 pragma Compile_Time_Error 8817 (not Gen'Library_Level, 8818 "Gen can only be instantiated at library level"); 8819 ... 8820end Gen; 8821@end smallexample 8822 8823@node Attribute Loop_Entry 8824@unnumberedsec Attribute Loop_Entry 8825@findex Loop_Entry 8826@noindent 8827Syntax: 8828 8829@smallexample @c ada 8830X'Loop_Entry [(loop_name)] 8831@end smallexample 8832 8833@noindent 8834The @code{Loop_Entry} attribute is used to refer to the value that an 8835expression had upon entry to a given loop in much the same way that the 8836@code{Old} attribute in a subprogram postcondition can be used to refer 8837to the value an expression had upon entry to the subprogram. The 8838relevant loop is either identified by the given loop name, or it is the 8839innermost enclosing loop when no loop name is given. 8840 8841@noindent 8842A @code{Loop_Entry} attribute can only occur within a 8843@code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of 8844@code{Loop_Entry} is to compare the current value of objects with their 8845initial value at loop entry, in a @code{Loop_Invariant} pragma. 8846 8847@noindent 8848The effect of using @code{X'Loop_Entry} is the same as declaring 8849a constant initialized with the initial value of @code{X} at loop 8850entry. This copy is not performed if the loop is not entered, or if the 8851corresponding pragmas are ignored or disabled. 8852 8853@node Attribute Machine_Size 8854@unnumberedsec Attribute Machine_Size 8855@findex Machine_Size 8856@noindent 8857This attribute is identical to the @code{Object_Size} attribute. It is 8858provided for compatibility with the DEC Ada 83 attribute of this name. 8859 8860@node Attribute Mantissa 8861@unnumberedsec Attribute Mantissa 8862@cindex Ada 83 attributes 8863@findex Mantissa 8864@noindent 8865The @code{Mantissa} attribute is provided for compatibility with Ada 83. See 8866the Ada 83 reference manual for an exact description of the semantics of 8867this attribute. 8868 8869@node Attribute Max_Interrupt_Priority 8870@unnumberedsec Attribute Max_Interrupt_Priority 8871@cindex Interrupt priority, maximum 8872@findex Max_Interrupt_Priority 8873@noindent 8874@code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only 8875permissible prefix), provides the same value as 8876@code{System.Max_Interrupt_Priority}. 8877 8878@node Attribute Max_Priority 8879@unnumberedsec Attribute Max_Priority 8880@cindex Priority, maximum 8881@findex Max_Priority 8882@noindent 8883@code{Standard'Max_Priority} (@code{Standard} is the only permissible 8884prefix) provides the same value as @code{System.Max_Priority}. 8885 8886@node Attribute Maximum_Alignment 8887@unnumberedsec Attribute Maximum_Alignment 8888@cindex Alignment, maximum 8889@findex Maximum_Alignment 8890@noindent 8891@code{Standard'Maximum_Alignment} (@code{Standard} is the only 8892permissible prefix) provides the maximum useful alignment value for the 8893target. This is a static value that can be used to specify the alignment 8894for an object, guaranteeing that it is properly aligned in all 8895cases. 8896 8897@node Attribute Mechanism_Code 8898@unnumberedsec Attribute Mechanism_Code 8899@cindex Return values, passing mechanism 8900@cindex Parameters, passing mechanism 8901@findex Mechanism_Code 8902@noindent 8903@code{@var{function}'Mechanism_Code} yields an integer code for the 8904mechanism used for the result of function, and 8905@code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism 8906used for formal parameter number @var{n} (a static integer value with 1 8907meaning the first parameter) of @var{subprogram}. The code returned is: 8908 8909@table @asis 8910@item 1 8911by copy (value) 8912@item 2 8913by reference 8914@item 3 8915by descriptor (default descriptor class) 8916@item 4 8917by descriptor (UBS: unaligned bit string) 8918@item 5 8919by descriptor (UBSB: aligned bit string with arbitrary bounds) 8920@item 6 8921by descriptor (UBA: unaligned bit array) 8922@item 7 8923by descriptor (S: string, also scalar access type parameter) 8924@item 8 8925by descriptor (SB: string with arbitrary bounds) 8926@item 9 8927by descriptor (A: contiguous array) 8928@item 10 8929by descriptor (NCA: non-contiguous array) 8930@end table 8931 8932@noindent 8933Values from 3 through 10 are only relevant to Digital OpenVMS implementations. 8934@cindex OpenVMS 8935 8936@node Attribute Null_Parameter 8937@unnumberedsec Attribute Null_Parameter 8938@cindex Zero address, passing 8939@findex Null_Parameter 8940@noindent 8941A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of 8942type or subtype @var{T} allocated at machine address zero. The attribute 8943is allowed only as the default expression of a formal parameter, or as 8944an actual expression of a subprogram call. In either case, the 8945subprogram must be imported. 8946 8947The identity of the object is represented by the address zero in the 8948argument list, independent of the passing mechanism (explicit or 8949default). 8950 8951This capability is needed to specify that a zero address should be 8952passed for a record or other composite object passed by reference. 8953There is no way of indicating this without the @code{Null_Parameter} 8954attribute. 8955 8956@node Attribute Object_Size 8957@unnumberedsec Attribute Object_Size 8958@cindex Size, used for objects 8959@findex Object_Size 8960@noindent 8961The size of an object is not necessarily the same as the size of the type 8962of an object. This is because by default object sizes are increased to be 8963a multiple of the alignment of the object. For example, 8964@code{Natural'Size} is 896531, but by default objects of type @code{Natural} will have a size of 32 bits. 8966Similarly, a record containing an integer and a character: 8967 8968@smallexample @c ada 8969type Rec is record 8970 I : Integer; 8971 C : Character; 8972end record; 8973@end smallexample 8974 8975@noindent 8976will have a size of 40 (that is @code{Rec'Size} will be 40). The 8977alignment will be 4, because of the 8978integer field, and so the default size of record objects for this type 8979will be 64 (8 bytes). 8980 8981If the alignment of the above record is specified to be 1, then the 8982object size will be 40 (5 bytes). This is true by default, and also 8983an object size of 40 can be explicitly specified in this case. 8984 8985A consequence of this capability is that different object sizes can be 8986given to subtypes that would otherwise be considered in Ada to be 8987statically matching. But it makes no sense to consider such subtypes 8988as statically matching. Consequently, in @code{GNAT} we add a rule 8989to the static matching rules that requires object sizes to match. 8990Consider this example: 8991 8992@smallexample @c ada 8993 1. procedure BadAVConvert is 8994 2. type R is new Integer; 8995 3. subtype R1 is R range 1 .. 10; 8996 4. subtype R2 is R range 1 .. 10; 8997 5. for R1'Object_Size use 8; 8998 6. for R2'Object_Size use 16; 8999 7. type R1P is access all R1; 9000 8. type R2P is access all R2; 9001 9. R1PV : R1P := new R1'(4); 900210. R2PV : R2P; 900311. begin 900412. R2PV := R2P (R1PV); 9005 | 9006 >>> target designated subtype not compatible with 9007 type "R1" defined at line 3 9008 900913. end; 9010@end smallexample 9011 9012@noindent 9013In the absence of lines 5 and 6, 9014types @code{R1} and @code{R2} statically match and 9015hence the conversion on line 12 is legal. But since lines 5 and 6 9016cause the object sizes to differ, @code{GNAT} considers that types 9017@code{R1} and @code{R2} are not statically matching, and line 12 9018generates the diagnostic shown above. 9019 9020@noindent 9021Similar additional checks are performed in other contexts requiring 9022statically matching subtypes. 9023 9024@node Attribute Passed_By_Reference 9025@unnumberedsec Attribute Passed_By_Reference 9026@cindex Parameters, when passed by reference 9027@findex Passed_By_Reference 9028@noindent 9029@code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns 9030a value of type @code{Boolean} value that is @code{True} if the type is 9031normally passed by reference and @code{False} if the type is normally 9032passed by copy in calls. For scalar types, the result is always @code{False} 9033and is static. For non-scalar types, the result is non-static. 9034 9035@node Attribute Pool_Address 9036@unnumberedsec Attribute Pool_Address 9037@cindex Parameters, when passed by reference 9038@findex Pool_Address 9039@noindent 9040@code{@var{X}'Pool_Address} for any object @var{X} returns the address 9041of X within its storage pool. This is the same as 9042@code{@var{X}'Address}, except that for an unconstrained array whose 9043bounds are allocated just before the first component, 9044@code{@var{X}'Pool_Address} returns the address of those bounds, 9045whereas @code{@var{X}'Address} returns the address of the first 9046component. 9047 9048Here, we are interpreting ``storage pool'' broadly to mean ``wherever 9049the object is allocated'', which could be a user-defined storage pool, 9050the global heap, on the stack, or in a static memory area. For an 9051object created by @code{new}, @code{@var{Ptr.all}'Pool_Address} is 9052what is passed to @code{Allocate} and returned from @code{Deallocate}. 9053 9054@node Attribute Range_Length 9055@unnumberedsec Attribute Range_Length 9056@findex Range_Length 9057@noindent 9058@code{@var{type}'Range_Length} for any discrete type @var{type} yields 9059the number of values represented by the subtype (zero for a null 9060range). The result is static for static subtypes. @code{Range_Length} 9061applied to the index subtype of a one dimensional array always gives the 9062same result as @code{Length} applied to the array itself. 9063 9064@node Attribute Ref 9065@unnumberedsec Attribute Ref 9066@findex Ref 9067@noindent 9068 9069 9070@node Attribute Restriction_Set 9071@unnumberedsec Attribute Restriction_Set 9072@findex Restriction_Set 9073@cindex Restrictions 9074@noindent 9075This attribute allows compile time testing of restrictions that 9076are currently in effect. It is primarily intended for specializing 9077code in the run-time based on restrictions that are active (e.g. 9078don't need to save fpt registers if restriction No_Floating_Point 9079is known to be in effect), but can be used anywhere. 9080 9081There are two forms: 9082 9083@smallexample @c ada 9084System'Restriction_Set (partition_boolean_restriction_NAME) 9085System'Restriction_Set (No_Dependence => library_unit_NAME); 9086@end smallexample 9087 9088@noindent 9089In the case of the first form, the only restriction names 9090allowed are parameterless restrictions that are checked 9091for consistency at bind time. For a complete list see the 9092subtype @code{System.Rident.Partition_Boolean_Restrictions}. 9093 9094The result returned is True if the restriction is known to 9095be in effect, and False if the restriction is known not to 9096be in effect. An important guarantee is that the value of 9097a Restriction_Set attribute is known to be consistent throughout 9098all the code of a partition. 9099 9100This is trivially achieved if the entire partition is compiled 9101with a consistent set of restriction pragmas. However, the 9102compilation model does not require this. It is possible to 9103compile one set of units with one set of pragmas, and another 9104set of units with another set of pragmas. It is even possible 9105to compile a spec with one set of pragmas, and then WITH the 9106same spec with a different set of pragmas. Inconsistencies 9107in the actual use of the restriction are checked at bind time. 9108 9109In order to achieve the guarantee of consistency for the 9110Restriction_Set pragma, we consider that a use of the pragma 9111that yields False is equivalent to a violation of the 9112restriction. 9113 9114So for example if you write 9115 9116@smallexample @c ada 9117if System'Restriction_Set (No_Floating_Point) then 9118 ... 9119else 9120 ... 9121end if; 9122@end smallexample 9123 9124@noindent 9125And the result is False, so that the else branch is executed, 9126you can assume that this restriction is not set for any unit 9127in the partition. This is checked by considering this use of 9128the restriction pragma to be a violation of the restriction 9129No_Floating_Point. This means that no other unit can attempt 9130to set this restriction (if some unit does attempt to set it, 9131the binder will refuse to bind the partition). 9132 9133Technical note: The restriction name and the unit name are 9134intepreted entirely syntactically, as in the corresponding 9135Restrictions pragma, they are not analyzed semantically, 9136so they do not have a type. 9137 9138@node Attribute Result 9139@unnumberedsec Attribute Result 9140@findex Result 9141@noindent 9142@code{@var{function}'Result} can only be used with in a Postcondition pragma 9143for a function. The prefix must be the name of the corresponding function. This 9144is used to refer to the result of the function in the postcondition expression. 9145For a further discussion of the use of this attribute and examples of its use, 9146see the description of pragma Postcondition. 9147 9148@node Attribute Safe_Emax 9149@unnumberedsec Attribute Safe_Emax 9150@cindex Ada 83 attributes 9151@findex Safe_Emax 9152@noindent 9153The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See 9154the Ada 83 reference manual for an exact description of the semantics of 9155this attribute. 9156 9157@node Attribute Safe_Large 9158@unnumberedsec Attribute Safe_Large 9159@cindex Ada 83 attributes 9160@findex Safe_Large 9161@noindent 9162The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See 9163the Ada 83 reference manual for an exact description of the semantics of 9164this attribute. 9165 9166@node Attribute Scalar_Storage_Order 9167@unnumberedsec Attribute Scalar_Storage_Order 9168@cindex Endianness 9169@cindex Scalar storage order 9170@findex Scalar_Storage_Order 9171@noindent 9172For every array or record type @var{S}, the representation attribute 9173@code{Scalar_Storage_Order} denotes the order in which storage elements 9174that make up scalar components are ordered within S: 9175 9176@smallexample @c ada 9177 -- Component type definitions 9178 9179 subtype Yr_Type is Natural range 0 .. 127; 9180 subtype Mo_Type is Natural range 1 .. 12; 9181 subtype Da_Type is Natural range 1 .. 31; 9182 9183 -- Record declaration 9184 9185 type Date is record 9186 Years_Since_1980 : Yr_Type; 9187 Month : Mo_Type; 9188 Day_Of_Month : Da_Type; 9189 end record; 9190 9191 -- Record representation clause 9192 9193 for Date use record 9194 Years_Since_1980 at 0 range 0 .. 6; 9195 Month at 0 range 7 .. 10; 9196 Day_Of_Month at 0 range 11 .. 15; 9197 end record; 9198 9199 -- Attribute definition clauses 9200 9201 for Date'Bit_Order use System.High_Order_First; 9202 for Date'Scalar_Storage_Order use System.High_Order_First; 9203 -- If Scalar_Storage_Order is specified, it must be consistent with 9204 -- Bit_Order, so it's best to always define the latter explicitly if 9205 -- the former is used. 9206@end smallexample 9207 9208Other properties are 9209as for standard representation attribute @code{Bit_Order}, as defined by 9210Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. 9211 9212For a record type @var{S}, if @code{@var{S}'Scalar_Storage_Order} is 9213specified explicitly, it shall be equal to @code{@var{S}'Bit_Order}. Note: 9214this means that if a @code{Scalar_Storage_Order} attribute definition 9215clause is not confirming, then the type's @code{Bit_Order} shall be 9216specified explicitly and set to the same value. 9217 9218For a record extension, the derived type shall have the same scalar storage 9219order as the parent type. 9220 9221If a component of @var{S} has itself a record or array type, then it shall also 9222have a @code{Scalar_Storage_Order} attribute definition clause. In addition, 9223if the component is a packed array, or does not start on a byte boundary, then 9224the scalar storage order specified for S and for the nested component type shall 9225be identical. 9226 9227If @var{S} appears as the type of a record or array component, the enclosing 9228record or array shall also have a @code{Scalar_Storage_Order} attribute 9229definition clause. 9230 9231No component of a type that has a @code{Scalar_Storage_Order} attribute 9232definition may be aliased. 9233 9234A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. 9235with a value equal to @code{System.Default_Bit_Order}) has no effect. 9236 9237If the opposite storage order is specified, then whenever the value of 9238a scalar component of an object of type @var{S} is read, the storage 9239elements of the enclosing machine scalar are first reversed (before 9240retrieving the component value, possibly applying some shift and mask 9241operatings on the enclosing machine scalar), and the opposite operation 9242is done for writes. 9243 9244In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 9245are relaxed. Instead, the following rules apply: 9246 9247@itemize @bullet 9248@item the underlying storage elements are those at positions 9249 @code{(position + first_bit / storage_element_size) .. 9250 (position + (last_bit + storage_element_size - 1) / 9251 storage_element_size)} 9252@item the sequence of underlying storage elements shall have 9253 a size no greater than the largest machine scalar 9254@item the enclosing machine scalar is defined as the smallest machine 9255 scalar starting at a position no greater than 9256 @code{position + first_bit / storage_element_size} and covering 9257 storage elements at least up to @code{position + (last_bit + 9258 storage_element_size - 1) / storage_element_size} 9259@item the position of the component is interpreted relative to that machine 9260 scalar. 9261 9262@end itemize 9263 9264@node Attribute Simple_Storage_Pool 9265@unnumberedsec Attribute Simple_Storage_Pool 9266@cindex Storage pool, simple 9267@cindex Simple storage pool 9268@findex Simple_Storage_Pool 9269@noindent 9270For every nonformal, nonderived access-to-object type @var{Acc}, the 9271representation attribute @code{Simple_Storage_Pool} may be specified 9272via an attribute_definition_clause (or by specifying the equivalent aspect): 9273 9274@smallexample @c ada 9275 9276My_Pool : My_Simple_Storage_Pool_Type; 9277 9278type Acc is access My_Data_Type; 9279 9280for Acc'Simple_Storage_Pool use My_Pool; 9281 9282@end smallexample 9283 9284@noindent 9285The name given in an attribute_definition_clause for the 9286@code{Simple_Storage_Pool} attribute shall denote a variable of 9287a ``simple storage pool type'' (see pragma @code{Simple_Storage_Pool_Type}). 9288 9289The use of this attribute is only allowed for a prefix denoting a type 9290for which it has been specified. The type of the attribute is the type 9291of the variable specified as the simple storage pool of the access type, 9292and the attribute denotes that variable. 9293 9294It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} 9295for the same access type. 9296 9297If the @code{Simple_Storage_Pool} attribute has been specified for an access 9298type, then applying the @code{Storage_Pool} attribute to the type is flagged 9299with a warning and its evaluation raises the exception @code{Program_Error}. 9300 9301If the Simple_Storage_Pool attribute has been specified for an access 9302type @var{S}, then the evaluation of the attribute @code{@var{S}'Storage_Size} 9303returns the result of calling @code{Storage_Size (@var{S}'Simple_Storage_Pool)}, 9304which is intended to indicate the number of storage elements reserved for 9305the simple storage pool. If the Storage_Size function has not been defined 9306for the simple storage pool type, then this attribute returns zero. 9307 9308If an access type @var{S} has a specified simple storage pool of type 9309@var{SSP}, then the evaluation of an allocator for that access type calls 9310the primitive @code{Allocate} procedure for type @var{SSP}, passing 9311@code{@var{S}'Simple_Storage_Pool} as the pool parameter. The detailed 9312semantics of such allocators is the same as those defined for allocators 9313in section 13.11 of the Ada Reference Manual, with the term 9314``simple storage pool'' substituted for ``storage pool''. 9315 9316If an access type @var{S} has a specified simple storage pool of type 9317@var{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} 9318for that access type invokes the primitive @code{Deallocate} procedure 9319for type @var{SSP}, passing @code{@var{S}'Simple_Storage_Pool} as the pool 9320parameter. The detailed semantics of such unchecked deallocations is the same 9321as defined in section 13.11.2 of the Ada Reference Manual, except that the 9322term ``simple storage pool'' is substituted for ``storage pool''. 9323 9324@node Attribute Small 9325@unnumberedsec Attribute Small 9326@cindex Ada 83 attributes 9327@findex Small 9328@noindent 9329The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for 9330fixed-point types. 9331GNAT also allows this attribute to be applied to floating-point types 9332for compatibility with Ada 83. See 9333the Ada 83 reference manual for an exact description of the semantics of 9334this attribute when applied to floating-point types. 9335 9336@node Attribute Storage_Unit 9337@unnumberedsec Attribute Storage_Unit 9338@findex Storage_Unit 9339@noindent 9340@code{Standard'Storage_Unit} (@code{Standard} is the only permissible 9341prefix) provides the same value as @code{System.Storage_Unit}. 9342 9343@node Attribute Stub_Type 9344@unnumberedsec Attribute Stub_Type 9345@findex Stub_Type 9346@noindent 9347The GNAT implementation of remote access-to-classwide types is 9348organized as described in AARM section E.4 (20.t): a value of an RACW type 9349(designating a remote object) is represented as a normal access 9350value, pointing to a "stub" object which in turn contains the 9351necessary information to contact the designated remote object. A 9352call on any dispatching operation of such a stub object does the 9353remote call, if necessary, using the information in the stub object 9354to locate the target partition, etc. 9355 9356For a prefix @code{T} that denotes a remote access-to-classwide type, 9357@code{T'Stub_Type} denotes the type of the corresponding stub objects. 9358 9359By construction, the layout of @code{T'Stub_Type} is identical to that of 9360type @code{RACW_Stub_Type} declared in the internal implementation-defined 9361unit @code{System.Partition_Interface}. Use of this attribute will create 9362an implicit dependency on this unit. 9363 9364@node Attribute System_Allocator_Alignment 9365@unnumberedsec Attribute System_Allocator_Alignment 9366@cindex Alignment, allocator 9367@findex System_Allocator_Alignment 9368@noindent 9369@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only 9370permissible prefix) provides the observable guaranted to be honored by 9371the system allocator (malloc). This is a static value that can be used 9372in user storage pools based on malloc either to reject allocation 9373with alignment too large or to enable a realignment circuitry if the 9374alignment request is larger than this value. 9375 9376@node Attribute Target_Name 9377@unnumberedsec Attribute Target_Name 9378@findex Target_Name 9379@noindent 9380@code{Standard'Target_Name} (@code{Standard} is the only permissible 9381prefix) provides a static string value that identifies the target 9382for the current compilation. For GCC implementations, this is the 9383standard gcc target name without the terminating slash (for 9384example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 9385 9386@node Attribute Tick 9387@unnumberedsec Attribute Tick 9388@findex Tick 9389@noindent 9390@code{Standard'Tick} (@code{Standard} is the only permissible prefix) 9391provides the same value as @code{System.Tick}, 9392 9393@node Attribute To_Address 9394@unnumberedsec Attribute To_Address 9395@findex To_Address 9396@noindent 9397The @code{System'To_Address} 9398(@code{System} is the only permissible prefix) 9399denotes a function identical to 9400@code{System.Storage_Elements.To_Address} except that 9401it is a static attribute. This means that if its argument is 9402a static expression, then the result of the attribute is a 9403static expression. This means that such an expression can be 9404used in contexts (e.g.@: preelaborable packages) which require a 9405static expression and where the function call could not be used 9406(since the function call is always non-static, even if its 9407argument is static). The argument must be in the range 9408-(2**(m-1) .. 2**m-1, where m is the memory size 9409(typically 32 or 64). Negative values are intepreted in a 9410modular manner (e.g. -1 means the same as 16#FFFF_FFFF# on 9411a 32 bits machine). 9412 9413@node Attribute Type_Class 9414@unnumberedsec Attribute Type_Class 9415@findex Type_Class 9416@noindent 9417@code{@var{type}'Type_Class} for any type or subtype @var{type} yields 9418the value of the type class for the full type of @var{type}. If 9419@var{type} is a generic formal type, the value is the value for the 9420corresponding actual subtype. The value of this attribute is of type 9421@code{System.Aux_DEC.Type_Class}, which has the following definition: 9422 9423@smallexample @c ada 9424 type Type_Class is 9425 (Type_Class_Enumeration, 9426 Type_Class_Integer, 9427 Type_Class_Fixed_Point, 9428 Type_Class_Floating_Point, 9429 Type_Class_Array, 9430 Type_Class_Record, 9431 Type_Class_Access, 9432 Type_Class_Task, 9433 Type_Class_Address); 9434@end smallexample 9435 9436@noindent 9437Protected types yield the value @code{Type_Class_Task}, which thus 9438applies to all concurrent types. This attribute is designed to 9439be compatible with the DEC Ada 83 attribute of the same name. 9440 9441@node Attribute UET_Address 9442@unnumberedsec Attribute UET_Address 9443@findex UET_Address 9444@noindent 9445The @code{UET_Address} attribute can only be used for a prefix which 9446denotes a library package. It yields the address of the unit exception 9447table when zero cost exception handling is used. This attribute is 9448intended only for use within the GNAT implementation. See the unit 9449@code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb} 9450for details on how this attribute is used in the implementation. 9451 9452@node Attribute Unconstrained_Array 9453@unnumberedsec Attribute Unconstrained_Array 9454@findex Unconstrained_Array 9455@noindent 9456The @code{Unconstrained_Array} attribute can be used with a prefix that 9457denotes any type or subtype. It is a static attribute that yields 9458@code{True} if the prefix designates an unconstrained array, 9459and @code{False} otherwise. In a generic instance, the result is 9460still static, and yields the result of applying this test to the 9461generic actual. 9462 9463@node Attribute Universal_Literal_String 9464@unnumberedsec Attribute Universal_Literal_String 9465@cindex Named numbers, representation of 9466@findex Universal_Literal_String 9467@noindent 9468The prefix of @code{Universal_Literal_String} must be a named 9469number. The static result is the string consisting of the characters of 9470the number as defined in the original source. This allows the user 9471program to access the actual text of named numbers without intermediate 9472conversions and without the need to enclose the strings in quotes (which 9473would preclude their use as numbers). 9474 9475For example, the following program prints the first 50 digits of pi: 9476 9477@smallexample @c ada 9478with Text_IO; use Text_IO; 9479with Ada.Numerics; 9480procedure Pi is 9481begin 9482 Put (Ada.Numerics.Pi'Universal_Literal_String); 9483end; 9484@end smallexample 9485 9486@node Attribute Unrestricted_Access 9487@unnumberedsec Attribute Unrestricted_Access 9488@cindex @code{Access}, unrestricted 9489@findex Unrestricted_Access 9490@noindent 9491The @code{Unrestricted_Access} attribute is similar to @code{Access} 9492except that all accessibility and aliased view checks are omitted. This 9493is a user-beware attribute. It is similar to 9494@code{Address}, for which it is a desirable replacement where the value 9495desired is an access type. In other words, its effect is identical to 9496first applying the @code{Address} attribute and then doing an unchecked 9497conversion to a desired access type. In GNAT, but not necessarily in 9498other implementations, the use of static chains for inner level 9499subprograms means that @code{Unrestricted_Access} applied to a 9500subprogram yields a value that can be called as long as the subprogram 9501is in scope (normal Ada accessibility rules restrict this usage). 9502 9503It is possible to use @code{Unrestricted_Access} for any type, but care 9504must be exercised if it is used to create pointers to unconstrained 9505objects. In this case, the resulting pointer has the same scope as the 9506context of the attribute, and may not be returned to some enclosing 9507scope. For instance, a function cannot use @code{Unrestricted_Access} 9508to create a unconstrained pointer and then return that value to the 9509caller. 9510 9511@node Attribute Update 9512@unnumberedsec Attribute Update 9513@findex Update 9514@noindent 9515The @code{Update} attribute creates a copy of an array or record value 9516with one or more modified components. The syntax is: 9517 9518@smallexample @c ada 9519PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) 9520PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) 9521PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION 9522 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) 9523 9524MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION 9525INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} 9526INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) 9527@end smallexample 9528 9529@noindent 9530where @code{PREFIX} is the name of an array or record object, and 9531the association list in parentheses does not contain an @code{others} 9532choice. The effect is to yield a copy of the array or record value which 9533is unchanged apart from the components mentioned in the association list, which 9534are changed to the indicated value. The original value of the array or 9535record value is not affected. For example: 9536 9537@smallexample @c ada 9538type Arr is Array (1 .. 5) of Integer; 9539... 9540Avar1 : Arr := (1,2,3,4,5); 9541Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); 9542@end smallexample 9543 9544@noindent 9545yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} 9546begin unmodified. Similarly: 9547 9548@smallexample @c ada 9549type Rec is A, B, C : Integer; 9550... 9551Rvar1 : Rec := (A => 1, B => 2, C => 3); 9552Rvar2 : Rec := Rvar1'Update (B => 20); 9553@end smallexample 9554 9555@noindent 9556yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), 9557with @code{Rvar1} being unmodifed. 9558Note that the value of the attribute reference is computed 9559completely before it is used. This means that if you write: 9560 9561@smallexample @c ada 9562Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); 9563@end smallexample 9564 9565@noindent 9566then the value of @code{Avar1} is not modified if @code{Function_Call} 9567raises an exception, unlike the effect of a series of direct assignments 9568to elements of @code{Avar1}. In general this requires that 9569two extra complete copies of the object are required, which should be 9570kept in mind when considering efficiency. 9571 9572The @code{Update} attribute cannot be applied to prefixes of a limited 9573type, and cannot reference discriminants in the case of a record type. 9574The accessibility level of an Update attribute result object is defined 9575as for an aggregate. 9576 9577In the record case, no component can be mentioned more than once. In 9578the array case, two overlapping ranges can appear in the association list, 9579in which case the modifications are processed left to right. 9580 9581Multi-dimensional arrays can be modified, as shown by this example: 9582 9583@smallexample @c ada 9584A : array (1 .. 10, 1 .. 10) of Integer; 9585.. 9586A := A'Update ((1, 2) => 20, (3, 4) => 30); 9587@end smallexample 9588 9589@noindent 9590which changes element (1,2) to 20 and (3,4) to 30. 9591 9592@node Attribute Valid_Scalars 9593@unnumberedsec Attribute Valid_Scalars 9594@findex Valid_Scalars 9595@noindent 9596The @code{'Valid_Scalars} attribute is intended to make it easier to 9597check the validity of scalar subcomponents of composite objects. It 9598is defined for any prefix @code{X} that denotes an object. 9599The value of this attribute is of the predefined type Boolean. 9600@code{X'Valid_Scalars} yields True if and only if evaluation of 9601@code{P'Valid} yields True for every scalar part P of X or if X has 9602no scalar parts. It is not specified in what order the scalar parts 9603are checked, nor whether any more are checked after any one of them 9604is determined to be invalid. If the prefix @code{X} is of a class-wide 9605type @code{T'Class} (where @code{T} is the associated specific type), 9606or if the prefix @code{X} is of a specific tagged type @code{T}, then 9607only the scalar parts of components of @code{T} are traversed; in other 9608words, components of extensions of @code{T} are not traversed even if 9609@code{T'Class (X)'Tag /= T'Tag} . The compiler will issue a warning if it can 9610be determined at compile time that the prefix of the attribute has no 9611scalar parts (e.g., if the prefix is of an access type, an interface type, 9612an undiscriminated task type, or an undiscriminated protected type). 9613 9614@node Attribute VADS_Size 9615@unnumberedsec Attribute VADS_Size 9616@cindex @code{Size}, VADS compatibility 9617@findex VADS_Size 9618@noindent 9619The @code{'VADS_Size} attribute is intended to make it easier to port 9620legacy code which relies on the semantics of @code{'Size} as implemented 9621by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 9622same semantic interpretation. In particular, @code{'VADS_Size} applied 9623to a predefined or other primitive type with no Size clause yields the 9624Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on 9625typical machines). In addition @code{'VADS_Size} applied to an object 9626gives the result that would be obtained by applying the attribute to 9627the corresponding type. 9628 9629@node Attribute Value_Size 9630@unnumberedsec Attribute Value_Size 9631@cindex @code{Size}, setting for not-first subtype 9632@findex Value_Size 9633@code{@var{type}'Value_Size} is the number of bits required to represent 9634a value of the given subtype. It is the same as @code{@var{type}'Size}, 9635but, unlike @code{Size}, may be set for non-first subtypes. 9636 9637@node Attribute Wchar_T_Size 9638@unnumberedsec Attribute Wchar_T_Size 9639@findex Wchar_T_Size 9640@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible 9641prefix) provides the size in bits of the C @code{wchar_t} type 9642primarily for constructing the definition of this type in 9643package @code{Interfaces.C}. 9644 9645@node Attribute Word_Size 9646@unnumberedsec Attribute Word_Size 9647@findex Word_Size 9648@code{Standard'Word_Size} (@code{Standard} is the only permissible 9649prefix) provides the value @code{System.Word_Size}. 9650 9651@node Standard and Implementation Defined Restrictions 9652@chapter Standard and Implementation Defined Restrictions 9653 9654@noindent 9655All RM defined Restriction identifiers are implemented: 9656 9657@itemize @bullet 9658@item language-defined restrictions (see 13.12.1) 9659@item tasking restrictions (see D.7) 9660@item high integrity restrictions (see H.4) 9661@end itemize 9662 9663@noindent 9664GNAT implements additional restriction identifiers. All restrictions, whether 9665language defined or GNAT-specific, are listed in the following. 9666 9667@menu 9668* Partition-Wide Restrictions:: 9669* Program Unit Level Restrictions:: 9670@end menu 9671 9672@node Partition-Wide Restrictions 9673@section Partition-Wide Restrictions 9674 9675There are two separate lists of restriction identifiers. The first 9676set requires consistency throughout a partition (in other words, if the 9677restriction identifier is used for any compilation unit in the partition, 9678then all compilation units in the partition must obey the restriction). 9679 9680@menu 9681* Immediate_Reclamation:: 9682* Max_Asynchronous_Select_Nesting:: 9683* Max_Entry_Queue_Length:: 9684* Max_Protected_Entries:: 9685* Max_Select_Alternatives:: 9686* Max_Storage_At_Blocking:: 9687* Max_Task_Entries:: 9688* Max_Tasks:: 9689* No_Abort_Statements:: 9690* No_Access_Parameter_Allocators:: 9691* No_Access_Subprograms:: 9692* No_Allocators:: 9693* No_Anonymous_Allocators:: 9694* No_Calendar:: 9695* No_Coextensions:: 9696* No_Default_Initialization:: 9697* No_Delay:: 9698* No_Dependence:: 9699* No_Direct_Boolean_Operators:: 9700* No_Dispatch:: 9701* No_Dispatching_Calls:: 9702* No_Dynamic_Attachment:: 9703* No_Dynamic_Priorities:: 9704* No_Entry_Calls_In_Elaboration_Code:: 9705* No_Enumeration_Maps:: 9706* No_Exception_Handlers:: 9707* No_Exception_Propagation:: 9708* No_Exception_Registration:: 9709* No_Exceptions:: 9710* No_Finalization:: 9711* No_Fixed_Point:: 9712* No_Floating_Point:: 9713* No_Implicit_Conditionals:: 9714* No_Implicit_Dynamic_Code:: 9715* No_Implicit_Heap_Allocations:: 9716* No_Implicit_Loops:: 9717* No_Initialize_Scalars:: 9718* No_IO:: 9719* No_Local_Allocators:: 9720* No_Local_Protected_Objects:: 9721* No_Local_Timing_Events:: 9722* No_Nested_Finalization:: 9723* No_Protected_Type_Allocators:: 9724* No_Protected_Types:: 9725* No_Recursion:: 9726* No_Reentrancy:: 9727* No_Relative_Delay:: 9728* No_Requeue_Statements:: 9729* No_Secondary_Stack:: 9730* No_Select_Statements:: 9731* No_Specific_Termination_Handlers:: 9732* No_Specification_of_Aspect:: 9733* No_Standard_Allocators_After_Elaboration:: 9734* No_Standard_Storage_Pools:: 9735* No_Stream_Optimizations:: 9736* No_Streams:: 9737* No_Task_Allocators:: 9738* No_Task_Attributes_Package:: 9739* No_Task_Hierarchy:: 9740* No_Task_Termination:: 9741* No_Tasking:: 9742* No_Terminate_Alternatives:: 9743* No_Unchecked_Access:: 9744* Simple_Barriers:: 9745* Static_Priorities:: 9746* Static_Storage_Size:: 9747@end menu 9748 9749@node Immediate_Reclamation 9750@unnumberedsubsec Immediate_Reclamation 9751@findex Immediate_Reclamation 9752[RM H.4] This restriction ensures that, except for storage occupied by 9753objects created by allocators and not deallocated via unchecked 9754deallocation, any storage reserved at run time for an object is 9755immediately reclaimed when the object no longer exists. 9756 9757@node Max_Asynchronous_Select_Nesting 9758@unnumberedsubsec Max_Asynchronous_Select_Nesting 9759@findex Max_Asynchronous_Select_Nesting 9760[RM D.7] Specifies the maximum dynamic nesting level of asynchronous 9761selects. Violations of this restriction with a value of zero are 9762detected at compile time. Violations of this restriction with values 9763other than zero cause Storage_Error to be raised. 9764 9765@node Max_Entry_Queue_Length 9766@unnumberedsubsec Max_Entry_Queue_Length 9767@findex Max_Entry_Queue_Length 9768[RM D.7] This restriction is a declaration that any protected entry compiled in 9769the scope of the restriction has at most the specified number of 9770tasks waiting on the entry at any one time, and so no queue is required. 9771Note that this restriction is checked at run time. Violation of this 9772restriction results in the raising of Program_Error exception at the point of 9773the call. 9774 9775@findex Max_Entry_Queue_Depth 9776The restriction @code{Max_Entry_Queue_Depth} is recognized as a 9777synonym for @code{Max_Entry_Queue_Length}. This is retained for historical 9778compatibility purposes (and a warning will be generated for its use if 9779warnings on obsolescent features are activated). 9780 9781@node Max_Protected_Entries 9782@unnumberedsubsec Max_Protected_Entries 9783@findex Max_Protected_Entries 9784[RM D.7] Specifies the maximum number of entries per protected type. The 9785bounds of every entry family of a protected unit shall be static, or shall be 9786defined by a discriminant of a subtype whose corresponding bound is static. 9787 9788@node Max_Select_Alternatives 9789@unnumberedsubsec Max_Select_Alternatives 9790@findex Max_Select_Alternatives 9791[RM D.7] Specifies the maximum number of alternatives in a selective accept. 9792 9793@node Max_Storage_At_Blocking 9794@unnumberedsubsec Max_Storage_At_Blocking 9795@findex Max_Storage_At_Blocking 9796[RM D.7] Specifies the maximum portion (in storage elements) of a task's 9797Storage_Size that can be retained by a blocked task. A violation of this 9798restriction causes Storage_Error to be raised. 9799 9800@node Max_Task_Entries 9801@unnumberedsubsec Max_Task_Entries 9802@findex Max_Task_Entries 9803[RM D.7] Specifies the maximum number of entries 9804per task. The bounds of every entry family 9805of a task unit shall be static, or shall be 9806defined by a discriminant of a subtype whose 9807corresponding bound is static. 9808 9809@node Max_Tasks 9810@unnumberedsubsec Max_Tasks 9811@findex Max_Tasks 9812[RM D.7] Specifies the maximum number of task that may be created, not 9813counting the creation of the environment task. Violations of this 9814restriction with a value of zero are detected at compile 9815time. Violations of this restriction with values other than zero cause 9816Storage_Error to be raised. 9817 9818@node No_Abort_Statements 9819@unnumberedsubsec No_Abort_Statements 9820@findex No_Abort_Statements 9821[RM D.7] There are no abort_statements, and there are 9822no calls to Task_Identification.Abort_Task. 9823 9824@node No_Access_Parameter_Allocators 9825@unnumberedsubsec No_Access_Parameter_Allocators 9826@findex No_Access_Parameter_Allocators 9827[RM H.4] This restriction ensures at compile time that there are no 9828occurrences of an allocator as the actual parameter to an access 9829parameter. 9830 9831@node No_Access_Subprograms 9832@unnumberedsubsec No_Access_Subprograms 9833@findex No_Access_Subprograms 9834[RM H.4] This restriction ensures at compile time that there are no 9835declarations of access-to-subprogram types. 9836 9837@node No_Allocators 9838@unnumberedsubsec No_Allocators 9839@findex No_Allocators 9840[RM H.4] This restriction ensures at compile time that there are no 9841occurrences of an allocator. 9842 9843@node No_Anonymous_Allocators 9844@unnumberedsubsec No_Anonymous_Allocators 9845@findex No_Anonymous_Allocators 9846[RM H.4] This restriction ensures at compile time that there are no 9847occurrences of an allocator of anonymous access type. 9848 9849@node No_Calendar 9850@unnumberedsubsec No_Calendar 9851@findex No_Calendar 9852[GNAT] This restriction ensures at compile time that there is no implicit or 9853explicit dependence on the package @code{Ada.Calendar}. 9854 9855@node No_Coextensions 9856@unnumberedsubsec No_Coextensions 9857@findex No_Coextensions 9858[RM H.4] This restriction ensures at compile time that there are no 9859coextensions. See 3.10.2. 9860 9861@node No_Default_Initialization 9862@unnumberedsubsec No_Default_Initialization 9863@findex No_Default_Initialization 9864 9865[GNAT] This restriction prohibits any instance of default initialization 9866of variables. The binder implements a consistency rule which prevents 9867any unit compiled without the restriction from with'ing a unit with the 9868restriction (this allows the generation of initialization procedures to 9869be skipped, since you can be sure that no call is ever generated to an 9870initialization procedure in a unit with the restriction active). If used 9871in conjunction with Initialize_Scalars or Normalize_Scalars, the effect 9872is to prohibit all cases of variables declared without a specific 9873initializer (including the case of OUT scalar parameters). 9874 9875@node No_Delay 9876@unnumberedsubsec No_Delay 9877@findex No_Delay 9878[RM H.4] This restriction ensures at compile time that there are no 9879delay statements and no dependences on package Calendar. 9880 9881@node No_Dependence 9882@unnumberedsubsec No_Dependence 9883@findex No_Dependence 9884[RM 13.12.1] This restriction checks at compile time that there are no 9885dependence on a library unit. 9886 9887@node No_Direct_Boolean_Operators 9888@unnumberedsubsec No_Direct_Boolean_Operators 9889@findex No_Direct_Boolean_Operators 9890[GNAT] This restriction ensures that no logical operators (and/or/xor) 9891are used on operands of type Boolean (or any type derived from Boolean). 9892This is intended for use in safety critical programs where the certification 9893protocol requires the use of short-circuit (and then, or else) forms for all 9894composite boolean operations. 9895 9896@node No_Dispatch 9897@unnumberedsubsec No_Dispatch 9898@findex No_Dispatch 9899[RM H.4] This restriction ensures at compile time that there are no 9900occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. 9901 9902@node No_Dispatching_Calls 9903@unnumberedsubsec No_Dispatching_Calls 9904@findex No_Dispatching_Calls 9905[GNAT] This restriction ensures at compile time that the code generated by the 9906compiler involves no dispatching calls. The use of this restriction allows the 9907safe use of record extensions, classwide membership tests and other classwide 9908features not involving implicit dispatching. This restriction ensures that 9909the code contains no indirect calls through a dispatching mechanism. Note that 9910this includes internally-generated calls created by the compiler, for example 9911in the implementation of class-wide objects assignments. The 9912membership test is allowed in the presence of this restriction, because its 9913implementation requires no dispatching. 9914This restriction is comparable to the official Ada restriction 9915@code{No_Dispatch} except that it is a bit less restrictive in that it allows 9916all classwide constructs that do not imply dispatching. 9917The following example indicates constructs that violate this restriction. 9918 9919@smallexample 9920package Pkg is 9921 type T is tagged record 9922 Data : Natural; 9923 end record; 9924 procedure P (X : T); 9925 9926 type DT is new T with record 9927 More_Data : Natural; 9928 end record; 9929 procedure Q (X : DT); 9930end Pkg; 9931 9932with Pkg; use Pkg; 9933procedure Example is 9934 procedure Test (O : T'Class) is 9935 N : Natural := O'Size;-- Error: Dispatching call 9936 C : T'Class := O; -- Error: implicit Dispatching Call 9937 begin 9938 if O in DT'Class then -- OK : Membership test 9939 Q (DT (O)); -- OK : Type conversion plus direct call 9940 else 9941 P (O); -- Error: Dispatching call 9942 end if; 9943 end Test; 9944 9945 Obj : DT; 9946begin 9947 P (Obj); -- OK : Direct call 9948 P (T (Obj)); -- OK : Type conversion plus direct call 9949 P (T'Class (Obj)); -- Error: Dispatching call 9950 9951 Test (Obj); -- OK : Type conversion 9952 9953 if Obj in T'Class then -- OK : Membership test 9954 null; 9955 end if; 9956end Example; 9957@end smallexample 9958 9959@node No_Dynamic_Attachment 9960@unnumberedsubsec No_Dynamic_Attachment 9961@findex No_Dynamic_Attachment 9962[RM D.7] This restriction ensures that there is no call to any of the 9963operations defined in package Ada.Interrupts 9964(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, 9965Detach_Handler, and Reference). 9966 9967@findex No_Dynamic_Interrupts 9968The restriction @code{No_Dynamic_Interrupts} is recognized as a 9969synonym for @code{No_Dynamic_Attachment}. This is retained for historical 9970compatibility purposes (and a warning will be generated for its use if 9971warnings on obsolescent features are activated). 9972 9973@node No_Dynamic_Priorities 9974@unnumberedsubsec No_Dynamic_Priorities 9975@findex No_Dynamic_Priorities 9976[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 9977 9978@node No_Entry_Calls_In_Elaboration_Code 9979@unnumberedsubsec No_Entry_Calls_In_Elaboration_Code 9980@findex No_Entry_Calls_In_Elaboration_Code 9981[GNAT] This restriction ensures at compile time that no task or protected entry 9982calls are made during elaboration code. As a result of the use of this 9983restriction, the compiler can assume that no code past an accept statement 9984in a task can be executed at elaboration time. 9985 9986@node No_Enumeration_Maps 9987@unnumberedsubsec No_Enumeration_Maps 9988@findex No_Enumeration_Maps 9989[GNAT] This restriction ensures at compile time that no operations requiring 9990enumeration maps are used (that is Image and Value attributes applied 9991to enumeration types). 9992 9993@node No_Exception_Handlers 9994@unnumberedsubsec No_Exception_Handlers 9995@findex No_Exception_Handlers 9996[GNAT] This restriction ensures at compile time that there are no explicit 9997exception handlers. It also indicates that no exception propagation will 9998be provided. In this mode, exceptions may be raised but will result in 9999an immediate call to the last chance handler, a routine that the user 10000must define with the following profile: 10001 10002@smallexample @c ada 10003procedure Last_Chance_Handler 10004 (Source_Location : System.Address; Line : Integer); 10005pragma Export (C, Last_Chance_Handler, 10006 "__gnat_last_chance_handler"); 10007@end smallexample 10008 10009The parameter is a C null-terminated string representing a message to be 10010associated with the exception (typically the source location of the raise 10011statement generated by the compiler). The Line parameter when nonzero 10012represents the line number in the source program where the raise occurs. 10013 10014@node No_Exception_Propagation 10015@unnumberedsubsec No_Exception_Propagation 10016@findex No_Exception_Propagation 10017[GNAT] This restriction guarantees that exceptions are never propagated 10018to an outer subprogram scope. The only case in which an exception may 10019be raised is when the handler is statically in the same subprogram, so 10020that the effect of a raise is essentially like a goto statement. Any 10021other raise statement (implicit or explicit) will be considered 10022unhandled. Exception handlers are allowed, but may not contain an 10023exception occurrence identifier (exception choice). In addition, use of 10024the package GNAT.Current_Exception is not permitted, and reraise 10025statements (raise with no operand) are not permitted. 10026 10027@node No_Exception_Registration 10028@unnumberedsubsec No_Exception_Registration 10029@findex No_Exception_Registration 10030[GNAT] This restriction ensures at compile time that no stream operations for 10031types Exception_Id or Exception_Occurrence are used. This also makes it 10032impossible to pass exceptions to or from a partition with this restriction 10033in a distributed environment. If this exception is active, then the generated 10034code is simplified by omitting the otherwise-required global registration 10035of exceptions when they are declared. 10036 10037@node No_Exceptions 10038@unnumberedsubsec No_Exceptions 10039@findex No_Exceptions 10040[RM H.4] This restriction ensures at compile time that there are no 10041raise statements and no exception handlers. 10042 10043@node No_Finalization 10044@unnumberedsubsec No_Finalization 10045@findex No_Finalization 10046[GNAT] This restriction disables the language features described in 10047chapter 7.6 of the Ada 2005 RM as well as all form of code generation 10048performed by the compiler to support these features. The following types 10049are no longer considered controlled when this restriction is in effect: 10050@itemize @bullet 10051@item 10052@code{Ada.Finalization.Controlled} 10053@item 10054@code{Ada.Finalization.Limited_Controlled} 10055@item 10056Derivations from @code{Controlled} or @code{Limited_Controlled} 10057@item 10058Class-wide types 10059@item 10060Protected types 10061@item 10062Task types 10063@item 10064Array and record types with controlled components 10065@end itemize 10066The compiler no longer generates code to initialize, finalize or adjust an 10067object or a nested component, either declared on the stack or on the heap. The 10068deallocation of a controlled object no longer finalizes its contents. 10069 10070@node No_Fixed_Point 10071@unnumberedsubsec No_Fixed_Point 10072@findex No_Fixed_Point 10073[RM H.4] This restriction ensures at compile time that there are no 10074occurrences of fixed point types and operations. 10075 10076@node No_Floating_Point 10077@unnumberedsubsec No_Floating_Point 10078@findex No_Floating_Point 10079[RM H.4] This restriction ensures at compile time that there are no 10080occurrences of floating point types and operations. 10081 10082@node No_Implicit_Conditionals 10083@unnumberedsubsec No_Implicit_Conditionals 10084@findex No_Implicit_Conditionals 10085[GNAT] This restriction ensures that the generated code does not contain any 10086implicit conditionals, either by modifying the generated code where possible, 10087or by rejecting any construct that would otherwise generate an implicit 10088conditional. Note that this check does not include run time constraint 10089checks, which on some targets may generate implicit conditionals as 10090well. To control the latter, constraint checks can be suppressed in the 10091normal manner. Constructs generating implicit conditionals include comparisons 10092of composite objects and the Max/Min attributes. 10093 10094@node No_Implicit_Dynamic_Code 10095@unnumberedsubsec No_Implicit_Dynamic_Code 10096@findex No_Implicit_Dynamic_Code 10097@cindex trampoline 10098[GNAT] This restriction prevents the compiler from building ``trampolines''. 10099This is a structure that is built on the stack and contains dynamic 10100code to be executed at run time. On some targets, a trampoline is 10101built for the following features: @code{Access}, 10102@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; 10103nested task bodies; primitive operations of nested tagged types. 10104Trampolines do not work on machines that prevent execution of stack 10105data. For example, on windows systems, enabling DEP (data execution 10106protection) will cause trampolines to raise an exception. 10107Trampolines are also quite slow at run time. 10108 10109On many targets, trampolines have been largely eliminated. Look at the 10110version of system.ads for your target --- if it has 10111Always_Compatible_Rep equal to False, then trampolines are largely 10112eliminated. In particular, a trampoline is built for the following 10113features: @code{Address} of a nested subprogram; 10114@code{Access} or @code{Unrestricted_Access} of a nested subprogram, 10115but only if pragma Favor_Top_Level applies, or the access type has a 10116foreign-language convention; primitive operations of nested tagged 10117types. 10118 10119@node No_Implicit_Heap_Allocations 10120@unnumberedsubsec No_Implicit_Heap_Allocations 10121@findex No_Implicit_Heap_Allocations 10122[RM D.7] No constructs are allowed to cause implicit heap allocation. 10123 10124@node No_Implicit_Loops 10125@unnumberedsubsec No_Implicit_Loops 10126@findex No_Implicit_Loops 10127[GNAT] This restriction ensures that the generated code does not contain any 10128implicit @code{for} loops, either by modifying 10129the generated code where possible, 10130or by rejecting any construct that would otherwise generate an implicit 10131@code{for} loop. If this restriction is active, it is possible to build 10132large array aggregates with all static components without generating an 10133intermediate temporary, and without generating a loop to initialize individual 10134components. Otherwise, a loop is created for arrays larger than about 5000 10135scalar components. 10136 10137@node No_Initialize_Scalars 10138@unnumberedsubsec No_Initialize_Scalars 10139@findex No_Initialize_Scalars 10140[GNAT] This restriction ensures that no unit in the partition is compiled with 10141pragma Initialize_Scalars. This allows the generation of more efficient 10142code, and in particular eliminates dummy null initialization routines that 10143are otherwise generated for some record and array types. 10144 10145@node No_IO 10146@unnumberedsubsec No_IO 10147@findex No_IO 10148[RM H.4] This restriction ensures at compile time that there are no 10149dependences on any of the library units Sequential_IO, Direct_IO, 10150Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. 10151 10152@node No_Local_Allocators 10153@unnumberedsubsec No_Local_Allocators 10154@findex No_Local_Allocators 10155[RM H.4] This restriction ensures at compile time that there are no 10156occurrences of an allocator in subprograms, generic subprograms, tasks, 10157and entry bodies. 10158 10159@node No_Local_Protected_Objects 10160@unnumberedsubsec No_Local_Protected_Objects 10161@findex No_Local_Protected_Objects 10162[RM D.7] This restriction ensures at compile time that protected objects are 10163only declared at the library level. 10164 10165@node No_Local_Timing_Events 10166@unnumberedsubsec No_Local_Timing_Events 10167@findex No_Local_Timing_Events 10168[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are 10169declared at the library level. 10170 10171@node No_Nested_Finalization 10172@unnumberedsubsec No_Nested_Finalization 10173@findex No_Nested_Finalization 10174[RM D.7] All objects requiring finalization are declared at the library level. 10175 10176@node No_Protected_Type_Allocators 10177@unnumberedsubsec No_Protected_Type_Allocators 10178@findex No_Protected_Type_Allocators 10179[RM D.7] This restriction ensures at compile time that there are no allocator 10180expressions that attempt to allocate protected objects. 10181 10182@node No_Protected_Types 10183@unnumberedsubsec No_Protected_Types 10184@findex No_Protected_Types 10185[RM H.4] This restriction ensures at compile time that there are no 10186declarations of protected types or protected objects. 10187 10188@node No_Recursion 10189@unnumberedsubsec No_Recursion 10190@findex No_Recursion 10191[RM H.4] A program execution is erroneous if a subprogram is invoked as 10192part of its execution. 10193 10194@node No_Reentrancy 10195@unnumberedsubsec No_Reentrancy 10196@findex No_Reentrancy 10197[RM H.4] A program execution is erroneous if a subprogram is executed by 10198two tasks at the same time. 10199 10200@node No_Relative_Delay 10201@unnumberedsubsec No_Relative_Delay 10202@findex No_Relative_Delay 10203[RM D.7] This restriction ensures at compile time that there are no delay 10204relative statements and prevents expressions such as @code{delay 1.23;} from 10205appearing in source code. 10206 10207@node No_Requeue_Statements 10208@unnumberedsubsec No_Requeue_Statements 10209@findex No_Requeue_Statements 10210[RM D.7] This restriction ensures at compile time that no requeue statements 10211are permitted and prevents keyword @code{requeue} from being used in source 10212code. 10213 10214@findex No_Requeue 10215The restriction @code{No_Requeue} is recognized as a 10216synonym for @code{No_Requeue_Statements}. This is retained for historical 10217compatibility purposes (and a warning will be generated for its use if 10218warnings on oNobsolescent features are activated). 10219 10220@node No_Secondary_Stack 10221@unnumberedsubsec No_Secondary_Stack 10222@findex No_Secondary_Stack 10223[GNAT] This restriction ensures at compile time that the generated code 10224does not contain any reference to the secondary stack. The secondary 10225stack is used to implement functions returning unconstrained objects 10226(arrays or records) on some targets. 10227 10228@node No_Select_Statements 10229@unnumberedsubsec No_Select_Statements 10230@findex No_Select_Statements 10231[RM D.7] This restriction ensures at compile time no select statements of any 10232kind are permitted, that is the keyword @code{select} may not appear. 10233 10234@node No_Specific_Termination_Handlers 10235@unnumberedsubsec No_Specific_Termination_Handlers 10236@findex No_Specific_Termination_Handlers 10237[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler 10238or to Ada.Task_Termination.Specific_Handler. 10239 10240@node No_Specification_of_Aspect 10241@unnumberedsubsec No_Specification_of_Aspect 10242@findex No_Specification_of_Aspect 10243[RM 13.12.1] This restriction checks at compile time that no aspect 10244specification, attribute definition clause, or pragma is given for a 10245given aspect. 10246 10247@node No_Standard_Allocators_After_Elaboration 10248@unnumberedsubsec No_Standard_Allocators_After_Elaboration 10249@findex No_Standard_Allocators_After_Elaboration 10250[RM D.7] Specifies that an allocator using a standard storage pool 10251should never be evaluated at run time after the elaboration of the 10252library items of the partition has completed. Otherwise, Storage_Error 10253is raised. 10254 10255@node No_Standard_Storage_Pools 10256@unnumberedsubsec No_Standard_Storage_Pools 10257@findex No_Standard_Storage_Pools 10258[GNAT] This restriction ensures at compile time that no access types 10259use the standard default storage pool. Any access type declared must 10260have an explicit Storage_Pool attribute defined specifying a 10261user-defined storage pool. 10262 10263@node No_Stream_Optimizations 10264@unnumberedsubsec No_Stream_Optimizations 10265@findex No_Stream_Optimizations 10266[GNAT] This restriction affects the performance of stream operations on types 10267@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the 10268compiler uses block reads and writes when manipulating @code{String} objects 10269due to their supperior performance. When this restriction is in effect, the 10270compiler performs all IO operations on a per-character basis. 10271 10272@node No_Streams 10273@unnumberedsubsec No_Streams 10274@findex No_Streams 10275[GNAT] This restriction ensures at compile/bind time that there are no 10276stream objects created and no use of stream attributes. 10277This restriction does not forbid dependences on the package 10278@code{Ada.Streams}. So it is permissible to with 10279@code{Ada.Streams} (or another package that does so itself) 10280as long as no actual stream objects are created and no 10281stream attributes are used. 10282 10283Note that the use of restriction allows optimization of tagged types, 10284since they do not need to worry about dispatching stream operations. 10285To take maximum advantage of this space-saving optimization, any 10286unit declaring a tagged type should be compiled with the restriction, 10287though this is not required. 10288 10289@node No_Task_Allocators 10290@unnumberedsubsec No_Task_Allocators 10291@findex No_Task_Allocators 10292[RM D.7] There are no allocators for task types 10293or types containing task subcomponents. 10294 10295@node No_Task_Attributes_Package 10296@unnumberedsubsec No_Task_Attributes_Package 10297@findex No_Task_Attributes_Package 10298[GNAT] This restriction ensures at compile time that there are no implicit or 10299explicit dependencies on the package @code{Ada.Task_Attributes}. 10300 10301@findex No_Task_Attributes 10302The restriction @code{No_Task_Attributes} is recognized as a synonym 10303for @code{No_Task_Attributes_Package}. This is retained for historical 10304compatibility purposes (and a warning will be generated for its use if 10305warnings on obsolescent features are activated). 10306 10307@node No_Task_Hierarchy 10308@unnumberedsubsec No_Task_Hierarchy 10309@findex No_Task_Hierarchy 10310[RM D.7] All (non-environment) tasks depend 10311directly on the environment task of the partition. 10312 10313@node No_Task_Termination 10314@unnumberedsubsec No_Task_Termination 10315@findex No_Task_Termination 10316[RM D.7] Tasks which terminate are erroneous. 10317 10318@node No_Tasking 10319@unnumberedsubsec No_Tasking 10320@findex No_Tasking 10321[GNAT] This restriction prevents the declaration of tasks or task types 10322throughout the partition. It is similar in effect to the use of 10323@code{Max_Tasks => 0} except that violations are caught at compile time 10324and cause an error message to be output either by the compiler or 10325binder. 10326 10327@node No_Terminate_Alternatives 10328@unnumberedsubsec No_Terminate_Alternatives 10329@findex No_Terminate_Alternatives 10330[RM D.7] There are no selective accepts with terminate alternatives. 10331 10332@node No_Unchecked_Access 10333@unnumberedsubsec No_Unchecked_Access 10334@findex No_Unchecked_Access 10335[RM H.4] This restriction ensures at compile time that there are no 10336occurrences of the Unchecked_Access attribute. 10337 10338@node Simple_Barriers 10339@unnumberedsubsec Simple_Barriers 10340@findex Simple_Barriers 10341[RM D.7] This restriction ensures at compile time that barriers in entry 10342declarations for protected types are restricted to either static boolean 10343expressions or references to simple boolean variables defined in the private 10344part of the protected type. No other form of entry barriers is permitted. 10345 10346@findex Boolean_Entry_Barriers 10347The restriction @code{Boolean_Entry_Barriers} is recognized as a 10348synonym for @code{Simple_Barriers}. This is retained for historical 10349compatibility purposes (and a warning will be generated for its use if 10350warnings on obsolescent features are activated). 10351 10352@node Static_Priorities 10353@unnumberedsubsec Static_Priorities 10354@findex Static_Priorities 10355[GNAT] This restriction ensures at compile time that all priority expressions 10356are static, and that there are no dependences on the package 10357@code{Ada.Dynamic_Priorities}. 10358 10359@node Static_Storage_Size 10360@unnumberedsubsec Static_Storage_Size 10361@findex Static_Storage_Size 10362[GNAT] This restriction ensures at compile time that any expression appearing 10363in a Storage_Size pragma or attribute definition clause is static. 10364 10365@node Program Unit Level Restrictions 10366@section Program Unit Level Restrictions 10367 10368@noindent 10369The second set of restriction identifiers 10370does not require partition-wide consistency. 10371The restriction may be enforced for a single 10372compilation unit without any effect on any of the 10373other compilation units in the partition. 10374 10375@menu 10376* No_Elaboration_Code:: 10377* No_Entry_Queue:: 10378* No_Implementation_Aspect_Specifications:: 10379* No_Implementation_Attributes:: 10380* No_Implementation_Identifiers:: 10381* No_Implementation_Pragmas:: 10382* No_Implementation_Restrictions:: 10383* No_Implementation_Units:: 10384* No_Implicit_Aliasing:: 10385* No_Obsolescent_Features:: 10386* No_Wide_Characters:: 10387* SPARK_05:: 10388@end menu 10389 10390@node No_Elaboration_Code 10391@unnumberedsubsec No_Elaboration_Code 10392@findex No_Elaboration_Code 10393[GNAT] This restriction ensures at compile time that no elaboration code is 10394generated. Note that this is not the same condition as is enforced 10395by pragma @code{Preelaborate}. There are cases in which pragma 10396@code{Preelaborate} still permits code to be generated (e.g.@: code 10397to initialize a large array to all zeroes), and there are cases of units 10398which do not meet the requirements for pragma @code{Preelaborate}, 10399but for which no elaboration code is generated. Generally, it is 10400the case that preelaborable units will meet the restrictions, with 10401the exception of large aggregates initialized with an others_clause, 10402and exception declarations (which generate calls to a run-time 10403registry procedure). This restriction is enforced on 10404a unit by unit basis, it need not be obeyed consistently 10405throughout a partition. 10406 10407In the case of aggregates with others, if the aggregate has a dynamic 10408size, there is no way to eliminate the elaboration code (such dynamic 10409bounds would be incompatible with @code{Preelaborate} in any case). If 10410the bounds are static, then use of this restriction actually modifies 10411the code choice of the compiler to avoid generating a loop, and instead 10412generate the aggregate statically if possible, no matter how many times 10413the data for the others clause must be repeatedly generated. 10414 10415It is not possible to precisely document 10416the constructs which are compatible with this restriction, since, 10417unlike most other restrictions, this is not a restriction on the 10418source code, but a restriction on the generated object code. For 10419example, if the source contains a declaration: 10420 10421@smallexample 10422 Val : constant Integer := X; 10423@end smallexample 10424 10425@noindent 10426where X is not a static constant, it may be possible, depending 10427on complex optimization circuitry, for the compiler to figure 10428out the value of X at compile time, in which case this initialization 10429can be done by the loader, and requires no initialization code. It 10430is not possible to document the precise conditions under which the 10431optimizer can figure this out. 10432 10433Note that this the implementation of this restriction requires full 10434code generation. If it is used in conjunction with "semantics only" 10435checking, then some cases of violations may be missed. 10436 10437@node No_Entry_Queue 10438@unnumberedsubsec No_Entry_Queue 10439@findex No_Entry_Queue 10440[GNAT] This restriction is a declaration that any protected entry compiled in 10441the scope of the restriction has at most one task waiting on the entry 10442at any one time, and so no queue is required. This restriction is not 10443checked at compile time. A program execution is erroneous if an attempt 10444is made to queue a second task on such an entry. 10445 10446@node No_Implementation_Aspect_Specifications 10447@unnumberedsubsec No_Implementation_Aspect_Specifications 10448@findex No_Implementation_Aspect_Specifications 10449[RM 13.12.1] This restriction checks at compile time that no 10450GNAT-defined aspects are present. With this restriction, the only 10451aspects that can be used are those defined in the Ada Reference Manual. 10452 10453@node No_Implementation_Attributes 10454@unnumberedsubsec No_Implementation_Attributes 10455@findex No_Implementation_Attributes 10456[RM 13.12.1] This restriction checks at compile time that no 10457GNAT-defined attributes are present. With this restriction, the only 10458attributes that can be used are those defined in the Ada Reference 10459Manual. 10460 10461@node No_Implementation_Identifiers 10462@unnumberedsubsec No_Implementation_Identifiers 10463@findex No_Implementation_Identifiers 10464[RM 13.12.1] This restriction checks at compile time that no 10465implementation-defined identifiers (marked with pragma Implementation_Defined) 10466occur within language-defined packages. 10467 10468@node No_Implementation_Pragmas 10469@unnumberedsubsec No_Implementation_Pragmas 10470@findex No_Implementation_Pragmas 10471[RM 13.12.1] This restriction checks at compile time that no 10472GNAT-defined pragmas are present. With this restriction, the only 10473pragmas that can be used are those defined in the Ada Reference Manual. 10474 10475@node No_Implementation_Restrictions 10476@unnumberedsubsec No_Implementation_Restrictions 10477@findex No_Implementation_Restrictions 10478[GNAT] This restriction checks at compile time that no GNAT-defined restriction 10479identifiers (other than @code{No_Implementation_Restrictions} itself) 10480are present. With this restriction, the only other restriction identifiers 10481that can be used are those defined in the Ada Reference Manual. 10482 10483@node No_Implementation_Units 10484@unnumberedsubsec No_Implementation_Units 10485@findex No_Implementation_Units 10486[RM 13.12.1] This restriction checks at compile time that there is no 10487mention in the context clause of any implementation-defined descendants 10488of packages Ada, Interfaces, or System. 10489 10490@node No_Implicit_Aliasing 10491@unnumberedsubsec No_Implicit_Aliasing 10492@findex No_Implicit_Aliasing 10493[GNAT] This restriction, which is not required to be partition-wide consistent, 10494requires an explicit aliased keyword for an object to which 'Access, 10495'Unchecked_Access, or 'Address is applied, and forbids entirely the use of 10496the 'Unrestricted_Access attribute for objects. Note: the reason that 10497Unrestricted_Access is forbidden is that it would require the prefix 10498to be aliased, and in such cases, it can always be replaced by 10499the standard attribute Unchecked_Access which is preferable. 10500 10501@node No_Obsolescent_Features 10502@unnumberedsubsec No_Obsolescent_Features 10503@findex No_Obsolescent_Features 10504[RM 13.12.1] This restriction checks at compile time that no obsolescent 10505features are used, as defined in Annex J of the Ada Reference Manual. 10506 10507@node No_Wide_Characters 10508@unnumberedsubsec No_Wide_Characters 10509@findex No_Wide_Characters 10510[GNAT] This restriction ensures at compile time that no uses of the types 10511@code{Wide_Character} or @code{Wide_String} or corresponding wide 10512wide types 10513appear, and that no wide or wide wide string or character literals 10514appear in the program (that is literals representing characters not in 10515type @code{Character}). 10516 10517@node SPARK_05 10518@unnumberedsubsec SPARK_05 10519@findex SPARK_05 10520[GNAT] This restriction checks at compile time that some constructs 10521forbidden in SPARK 2005 are not present. Error messages related to 10522SPARK restriction have the form: 10523 10524@findex SPARK 10525The restriction @code{SPARK} is recognized as a 10526synonym for @code{SPARK_05}. This is retained for historical 10527compatibility purposes (and an unconditional warning will be generated 10528for its use, advising replacement by @code{SPARK}. 10529 10530@smallexample 10531violation of restriction "SPARK" at <file> 10532 <error message> 10533@end smallexample 10534 10535This is not a replacement for the semantic checks performed by the 10536SPARK Examiner tool, as the compiler only deals currently with code, 10537not at all with SPARK 2005 annotations and does not guarantee catching all 10538cases of constructs forbidden by SPARK 2005. 10539 10540Thus it may well be the case that code which passes the compiler with 10541the SPARK restriction is rejected by the SPARK Examiner, e.g. due to 10542the different visibility rules of the Examiner based on SPARK 2005 10543@code{inherit} annotations. 10544 10545This restriction can be useful in providing an initial filter for code 10546developed using SPARK 2005, or in examining legacy code to see how far 10547it is from meeting SPARK restrictions. 10548 10549Note that if a unit is compiled in Ada 95 mode with SPARK restriction, 10550violations will be reported for constructs forbidden in SPARK 95, 10551instead of SPARK 2005. 10552 10553@c ------------------------ 10554@node Implementation Advice 10555@chapter Implementation Advice 10556@noindent 10557The main text of the Ada Reference Manual describes the required 10558behavior of all Ada compilers, and the GNAT compiler conforms to 10559these requirements. 10560 10561In addition, there are sections throughout the Ada Reference Manual headed 10562by the phrase ``Implementation advice''. These sections are not normative, 10563i.e., they do not specify requirements that all compilers must 10564follow. Rather they provide advice on generally desirable behavior. You 10565may wonder why they are not requirements. The most typical answer is 10566that they describe behavior that seems generally desirable, but cannot 10567be provided on all systems, or which may be undesirable on some systems. 10568 10569As far as practical, GNAT follows the implementation advice sections in 10570the Ada Reference Manual. This chapter contains a table giving the 10571reference manual section number, paragraph number and several keywords 10572for each advice. Each entry consists of the text of the advice followed 10573by the GNAT interpretation of this advice. Most often, this simply says 10574``followed'', which means that GNAT follows the advice. However, in a 10575number of cases, GNAT deliberately deviates from this advice, in which 10576case the text describes what GNAT does and why. 10577 10578@cindex Error detection 10579@unnumberedsec 1.1.3(20): Error Detection 10580@sp 1 10581@cartouche 10582If an implementation detects the use of an unsupported Specialized Needs 10583Annex feature at run time, it should raise @code{Program_Error} if 10584feasible. 10585@end cartouche 10586Not relevant. All specialized needs annex features are either supported, 10587or diagnosed at compile time. 10588 10589@cindex Child Units 10590@unnumberedsec 1.1.3(31): Child Units 10591@sp 1 10592@cartouche 10593If an implementation wishes to provide implementation-defined 10594extensions to the functionality of a language-defined library unit, it 10595should normally do so by adding children to the library unit. 10596@end cartouche 10597Followed. 10598 10599@cindex Bounded errors 10600@unnumberedsec 1.1.5(12): Bounded Errors 10601@sp 1 10602@cartouche 10603If an implementation detects a bounded error or erroneous 10604execution, it should raise @code{Program_Error}. 10605@end cartouche 10606Followed in all cases in which the implementation detects a bounded 10607error or erroneous execution. Not all such situations are detected at 10608runtime. 10609 10610@cindex Pragmas 10611@unnumberedsec 2.8(16): Pragmas 10612@sp 1 10613@cartouche 10614Normally, implementation-defined pragmas should have no semantic effect 10615for error-free programs; that is, if the implementation-defined pragmas 10616are removed from a working program, the program should still be legal, 10617and should still have the same semantics. 10618@end cartouche 10619The following implementation defined pragmas are exceptions to this 10620rule: 10621 10622@table @code 10623@item Abort_Defer 10624Affects semantics 10625@item Ada_83 10626Affects legality 10627@item Assert 10628Affects semantics 10629@item CPP_Class 10630Affects semantics 10631@item CPP_Constructor 10632Affects semantics 10633@item Debug 10634Affects semantics 10635@item Interface_Name 10636Affects semantics 10637@item Machine_Attribute 10638Affects semantics 10639@item Unimplemented_Unit 10640Affects legality 10641@item Unchecked_Union 10642Affects semantics 10643@end table 10644 10645@noindent 10646In each of the above cases, it is essential to the purpose of the pragma 10647that this advice not be followed. For details see the separate section 10648on implementation defined pragmas. 10649 10650@unnumberedsec 2.8(17-19): Pragmas 10651@sp 1 10652@cartouche 10653Normally, an implementation should not define pragmas that can 10654make an illegal program legal, except as follows: 10655@end cartouche 10656@sp 1 10657@cartouche 10658A pragma used to complete a declaration, such as a pragma @code{Import}; 10659@end cartouche 10660@sp 1 10661@cartouche 10662A pragma used to configure the environment by adding, removing, or 10663replacing @code{library_items}. 10664@end cartouche 10665See response to paragraph 16 of this same section. 10666 10667@cindex Character Sets 10668@cindex Alternative Character Sets 10669@unnumberedsec 3.5.2(5): Alternative Character Sets 10670@sp 1 10671@cartouche 10672If an implementation supports a mode with alternative interpretations 10673for @code{Character} and @code{Wide_Character}, the set of graphic 10674characters of @code{Character} should nevertheless remain a proper 10675subset of the set of graphic characters of @code{Wide_Character}. Any 10676character set ``localizations'' should be reflected in the results of 10677the subprograms defined in the language-defined package 10678@code{Characters.Handling} (see A.3) available in such a mode. In a mode with 10679an alternative interpretation of @code{Character}, the implementation should 10680also support a corresponding change in what is a legal 10681@code{identifier_letter}. 10682@end cartouche 10683Not all wide character modes follow this advice, in particular the JIS 10684and IEC modes reflect standard usage in Japan, and in these encoding, 10685the upper half of the Latin-1 set is not part of the wide-character 10686subset, since the most significant bit is used for wide character 10687encoding. However, this only applies to the external forms. Internally 10688there is no such restriction. 10689 10690@cindex Integer types 10691@unnumberedsec 3.5.4(28): Integer Types 10692 10693@sp 1 10694@cartouche 10695An implementation should support @code{Long_Integer} in addition to 10696@code{Integer} if the target machine supports 32-bit (or longer) 10697arithmetic. No other named integer subtypes are recommended for package 10698@code{Standard}. Instead, appropriate named integer subtypes should be 10699provided in the library package @code{Interfaces} (see B.2). 10700@end cartouche 10701@code{Long_Integer} is supported. Other standard integer types are supported 10702so this advice is not fully followed. These types 10703are supported for convenient interface to C, and so that all hardware 10704types of the machine are easily available. 10705@unnumberedsec 3.5.4(29): Integer Types 10706 10707@sp 1 10708@cartouche 10709An implementation for a two's complement machine should support 10710modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 10711implementation should support a non-binary modules up to @code{Integer'Last}. 10712@end cartouche 10713Followed. 10714 10715@cindex Enumeration values 10716@unnumberedsec 3.5.5(8): Enumeration Values 10717@sp 1 10718@cartouche 10719For the evaluation of a call on @code{@var{S}'Pos} for an enumeration 10720subtype, if the value of the operand does not correspond to the internal 10721code for any enumeration literal of its type (perhaps due to an 10722un-initialized variable), then the implementation should raise 10723@code{Program_Error}. This is particularly important for enumeration 10724types with noncontiguous internal codes specified by an 10725enumeration_representation_clause. 10726@end cartouche 10727Followed. 10728 10729@cindex Float types 10730@unnumberedsec 3.5.7(17): Float Types 10731@sp 1 10732@cartouche 10733An implementation should support @code{Long_Float} in addition to 10734@code{Float} if the target machine supports 11 or more digits of 10735precision. No other named floating point subtypes are recommended for 10736package @code{Standard}. Instead, appropriate named floating point subtypes 10737should be provided in the library package @code{Interfaces} (see B.2). 10738@end cartouche 10739@code{Short_Float} and @code{Long_Long_Float} are also provided. The 10740former provides improved compatibility with other implementations 10741supporting this type. The latter corresponds to the highest precision 10742floating-point type supported by the hardware. On most machines, this 10743will be the same as @code{Long_Float}, but on some machines, it will 10744correspond to the IEEE extended form. The notable case is all ia32 10745(x86) implementations, where @code{Long_Long_Float} corresponds to 10746the 80-bit extended precision format supported in hardware on this 10747processor. Note that the 128-bit format on SPARC is not supported, 10748since this is a software rather than a hardware format. 10749 10750@cindex Multidimensional arrays 10751@cindex Arrays, multidimensional 10752@unnumberedsec 3.6.2(11): Multidimensional Arrays 10753@sp 1 10754@cartouche 10755An implementation should normally represent multidimensional arrays in 10756row-major order, consistent with the notation used for multidimensional 10757array aggregates (see 4.3.3). However, if a pragma @code{Convention} 10758(@code{Fortran}, @dots{}) applies to a multidimensional array type, then 10759column-major order should be used instead (see B.5, ``Interfacing with 10760Fortran''). 10761@end cartouche 10762Followed. 10763 10764@findex Duration'Small 10765@unnumberedsec 9.6(30-31): Duration'Small 10766@sp 1 10767@cartouche 10768Whenever possible in an implementation, the value of @code{Duration'Small} 10769should be no greater than 100 microseconds. 10770@end cartouche 10771Followed. (@code{Duration'Small} = 10**(@minus{}9)). 10772 10773@sp 1 10774@cartouche 10775The time base for @code{delay_relative_statements} should be monotonic; 10776it need not be the same time base as used for @code{Calendar.Clock}. 10777@end cartouche 10778Followed. 10779 10780@unnumberedsec 10.2.1(12): Consistent Representation 10781@sp 1 10782@cartouche 10783In an implementation, a type declared in a pre-elaborated package should 10784have the same representation in every elaboration of a given version of 10785the package, whether the elaborations occur in distinct executions of 10786the same program, or in executions of distinct programs or partitions 10787that include the given version. 10788@end cartouche 10789Followed, except in the case of tagged types. Tagged types involve 10790implicit pointers to a local copy of a dispatch table, and these pointers 10791have representations which thus depend on a particular elaboration of the 10792package. It is not easy to see how it would be possible to follow this 10793advice without severely impacting efficiency of execution. 10794 10795@cindex Exception information 10796@unnumberedsec 11.4.1(19): Exception Information 10797@sp 1 10798@cartouche 10799@code{Exception_Message} by default and @code{Exception_Information} 10800should produce information useful for 10801debugging. @code{Exception_Message} should be short, about one 10802line. @code{Exception_Information} can be long. @code{Exception_Message} 10803should not include the 10804@code{Exception_Name}. @code{Exception_Information} should include both 10805the @code{Exception_Name} and the @code{Exception_Message}. 10806@end cartouche 10807Followed. For each exception that doesn't have a specified 10808@code{Exception_Message}, the compiler generates one containing the location 10809of the raise statement. This location has the form ``file:line'', where 10810file is the short file name (without path information) and line is the line 10811number in the file. Note that in the case of the Zero Cost Exception 10812mechanism, these messages become redundant with the Exception_Information that 10813contains a full backtrace of the calling sequence, so they are disabled. 10814To disable explicitly the generation of the source location message, use the 10815Pragma @code{Discard_Names}. 10816 10817@cindex Suppression of checks 10818@cindex Checks, suppression of 10819@unnumberedsec 11.5(28): Suppression of Checks 10820@sp 1 10821@cartouche 10822The implementation should minimize the code executed for checks that 10823have been suppressed. 10824@end cartouche 10825Followed. 10826 10827@cindex Representation clauses 10828@unnumberedsec 13.1 (21-24): Representation Clauses 10829@sp 1 10830@cartouche 10831The recommended level of support for all representation items is 10832qualified as follows: 10833@end cartouche 10834@sp 1 10835@cartouche 10836An implementation need not support representation items containing 10837non-static expressions, except that an implementation should support a 10838representation item for a given entity if each non-static expression in 10839the representation item is a name that statically denotes a constant 10840declared before the entity. 10841@end cartouche 10842Followed. In fact, GNAT goes beyond the recommended level of support 10843by allowing nonstatic expressions in some representation clauses even 10844without the need to declare constants initialized with the values of 10845such expressions. 10846For example: 10847 10848@smallexample @c ada 10849 X : Integer; 10850 Y : Float; 10851 for Y'Address use X'Address;>> 10852@end smallexample 10853 10854@sp 1 10855@cartouche 10856An implementation need not support a specification for the @code{Size} 10857for a given composite subtype, nor the size or storage place for an 10858object (including a component) of a given composite subtype, unless the 10859constraints on the subtype and its composite subcomponents (if any) are 10860all static constraints. 10861@end cartouche 10862Followed. Size Clauses are not permitted on non-static components, as 10863described above. 10864 10865@sp 1 10866@cartouche 10867An aliased component, or a component whose type is by-reference, should 10868always be allocated at an addressable location. 10869@end cartouche 10870Followed. 10871 10872@cindex Packed types 10873@unnumberedsec 13.2(6-8): Packed Types 10874@sp 1 10875@cartouche 10876If a type is packed, then the implementation should try to minimize 10877storage allocated to objects of the type, possibly at the expense of 10878speed of accessing components, subject to reasonable complexity in 10879addressing calculations. 10880@end cartouche 10881@sp 1 10882@cartouche 10883The recommended level of support pragma @code{Pack} is: 10884 10885For a packed record type, the components should be packed as tightly as 10886possible subject to the Sizes of the component subtypes, and subject to 10887any @code{record_representation_clause} that applies to the type; the 10888implementation may, but need not, reorder components or cross aligned 10889word boundaries to improve the packing. A component whose @code{Size} is 10890greater than the word size may be allocated an integral number of words. 10891@end cartouche 10892Followed. Tight packing of arrays is supported for all component sizes 10893up to 64-bits. If the array component size is 1 (that is to say, if 10894the component is a boolean type or an enumeration type with two values) 10895then values of the type are implicitly initialized to zero. This 10896happens both for objects of the packed type, and for objects that have a 10897subcomponent of the packed type. 10898 10899@sp 1 10900@cartouche 10901An implementation should support Address clauses for imported 10902subprograms. 10903@end cartouche 10904Followed. 10905@cindex @code{Address} clauses 10906@unnumberedsec 13.3(14-19): Address Clauses 10907 10908@sp 1 10909@cartouche 10910For an array @var{X}, @code{@var{X}'Address} should point at the first 10911component of the array, and not at the array bounds. 10912@end cartouche 10913Followed. 10914 10915@sp 1 10916@cartouche 10917The recommended level of support for the @code{Address} attribute is: 10918 10919@code{@var{X}'Address} should produce a useful result if @var{X} is an 10920object that is aliased or of a by-reference type, or is an entity whose 10921@code{Address} has been specified. 10922@end cartouche 10923Followed. A valid address will be produced even if none of those 10924conditions have been met. If necessary, the object is forced into 10925memory to ensure the address is valid. 10926 10927@sp 1 10928@cartouche 10929An implementation should support @code{Address} clauses for imported 10930subprograms. 10931@end cartouche 10932Followed. 10933 10934@sp 1 10935@cartouche 10936Objects (including subcomponents) that are aliased or of a by-reference 10937type should be allocated on storage element boundaries. 10938@end cartouche 10939Followed. 10940 10941@sp 1 10942@cartouche 10943If the @code{Address} of an object is specified, or it is imported or exported, 10944then the implementation should not perform optimizations based on 10945assumptions of no aliases. 10946@end cartouche 10947Followed. 10948 10949@cindex @code{Alignment} clauses 10950@unnumberedsec 13.3(29-35): Alignment Clauses 10951@sp 1 10952@cartouche 10953The recommended level of support for the @code{Alignment} attribute for 10954subtypes is: 10955 10956An implementation should support specified Alignments that are factors 10957and multiples of the number of storage elements per word, subject to the 10958following: 10959@end cartouche 10960Followed. 10961 10962@sp 1 10963@cartouche 10964An implementation need not support specified @code{Alignment}s for 10965combinations of @code{Size}s and @code{Alignment}s that cannot be easily 10966loaded and stored by available machine instructions. 10967@end cartouche 10968Followed. 10969 10970@sp 1 10971@cartouche 10972An implementation need not support specified @code{Alignment}s that are 10973greater than the maximum @code{Alignment} the implementation ever returns by 10974default. 10975@end cartouche 10976Followed. 10977 10978@sp 1 10979@cartouche 10980The recommended level of support for the @code{Alignment} attribute for 10981objects is: 10982 10983Same as above, for subtypes, but in addition: 10984@end cartouche 10985Followed. 10986 10987@sp 1 10988@cartouche 10989For stand-alone library-level objects of statically constrained 10990subtypes, the implementation should support all @code{Alignment}s 10991supported by the target linker. For example, page alignment is likely to 10992be supported for such objects, but not for subtypes. 10993@end cartouche 10994Followed. 10995 10996@cindex @code{Size} clauses 10997@unnumberedsec 13.3(42-43): Size Clauses 10998@sp 1 10999@cartouche 11000The recommended level of support for the @code{Size} attribute of 11001objects is: 11002 11003A @code{Size} clause should be supported for an object if the specified 11004@code{Size} is at least as large as its subtype's @code{Size}, and 11005corresponds to a size in storage elements that is a multiple of the 11006object's @code{Alignment} (if the @code{Alignment} is nonzero). 11007@end cartouche 11008Followed. 11009 11010@unnumberedsec 13.3(50-56): Size Clauses 11011@sp 1 11012@cartouche 11013If the @code{Size} of a subtype is specified, and allows for efficient 11014independent addressability (see 9.10) on the target architecture, then 11015the @code{Size} of the following objects of the subtype should equal the 11016@code{Size} of the subtype: 11017 11018Aliased objects (including components). 11019@end cartouche 11020Followed. 11021 11022@sp 1 11023@cartouche 11024@code{Size} clause on a composite subtype should not affect the 11025internal layout of components. 11026@end cartouche 11027Followed. But note that this can be overridden by use of the implementation 11028pragma Implicit_Packing in the case of packed arrays. 11029 11030@sp 1 11031@cartouche 11032The recommended level of support for the @code{Size} attribute of subtypes is: 11033@end cartouche 11034@sp 1 11035@cartouche 11036The @code{Size} (if not specified) of a static discrete or fixed point 11037subtype should be the number of bits needed to represent each value 11038belonging to the subtype using an unbiased representation, leaving space 11039for a sign bit only if the subtype contains negative values. If such a 11040subtype is a first subtype, then an implementation should support a 11041specified @code{Size} for it that reflects this representation. 11042@end cartouche 11043Followed. 11044 11045@sp 1 11046@cartouche 11047For a subtype implemented with levels of indirection, the @code{Size} 11048should include the size of the pointers, but not the size of what they 11049point at. 11050@end cartouche 11051Followed. 11052 11053@cindex @code{Component_Size} clauses 11054@unnumberedsec 13.3(71-73): Component Size Clauses 11055@sp 1 11056@cartouche 11057The recommended level of support for the @code{Component_Size} 11058attribute is: 11059@end cartouche 11060@sp 1 11061@cartouche 11062An implementation need not support specified @code{Component_Sizes} that are 11063less than the @code{Size} of the component subtype. 11064@end cartouche 11065Followed. 11066 11067@sp 1 11068@cartouche 11069An implementation should support specified @code{Component_Size}s that 11070are factors and multiples of the word size. For such 11071@code{Component_Size}s, the array should contain no gaps between 11072components. For other @code{Component_Size}s (if supported), the array 11073should contain no gaps between components when packing is also 11074specified; the implementation should forbid this combination in cases 11075where it cannot support a no-gaps representation. 11076@end cartouche 11077Followed. 11078 11079@cindex Enumeration representation clauses 11080@cindex Representation clauses, enumeration 11081@unnumberedsec 13.4(9-10): Enumeration Representation Clauses 11082@sp 1 11083@cartouche 11084The recommended level of support for enumeration representation clauses 11085is: 11086 11087An implementation need not support enumeration representation clauses 11088for boolean types, but should at minimum support the internal codes in 11089the range @code{System.Min_Int.System.Max_Int}. 11090@end cartouche 11091Followed. 11092 11093@cindex Record representation clauses 11094@cindex Representation clauses, records 11095@unnumberedsec 13.5.1(17-22): Record Representation Clauses 11096@sp 1 11097@cartouche 11098The recommended level of support for 11099@*@code{record_representation_clauses} is: 11100 11101An implementation should support storage places that can be extracted 11102with a load, mask, shift sequence of machine code, and set with a load, 11103shift, mask, store sequence, given the available machine instructions 11104and run-time model. 11105@end cartouche 11106Followed. 11107 11108@sp 1 11109@cartouche 11110A storage place should be supported if its size is equal to the 11111@code{Size} of the component subtype, and it starts and ends on a 11112boundary that obeys the @code{Alignment} of the component subtype. 11113@end cartouche 11114Followed. 11115 11116@sp 1 11117@cartouche 11118If the default bit ordering applies to the declaration of a given type, 11119then for a component whose subtype's @code{Size} is less than the word 11120size, any storage place that does not cross an aligned word boundary 11121should be supported. 11122@end cartouche 11123Followed. 11124 11125@sp 1 11126@cartouche 11127An implementation may reserve a storage place for the tag field of a 11128tagged type, and disallow other components from overlapping that place. 11129@end cartouche 11130Followed. The storage place for the tag field is the beginning of the tagged 11131record, and its size is Address'Size. GNAT will reject an explicit component 11132clause for the tag field. 11133 11134@sp 1 11135@cartouche 11136An implementation need not support a @code{component_clause} for a 11137component of an extension part if the storage place is not after the 11138storage places of all components of the parent type, whether or not 11139those storage places had been specified. 11140@end cartouche 11141Followed. The above advice on record representation clauses is followed, 11142and all mentioned features are implemented. 11143 11144@cindex Storage place attributes 11145@unnumberedsec 13.5.2(5): Storage Place Attributes 11146@sp 1 11147@cartouche 11148If a component is represented using some form of pointer (such as an 11149offset) to the actual data of the component, and this data is contiguous 11150with the rest of the object, then the storage place attributes should 11151reflect the place of the actual data, not the pointer. If a component is 11152allocated discontinuously from the rest of the object, then a warning 11153should be generated upon reference to one of its storage place 11154attributes. 11155@end cartouche 11156Followed. There are no such components in GNAT@. 11157 11158@cindex Bit ordering 11159@unnumberedsec 13.5.3(7-8): Bit Ordering 11160@sp 1 11161@cartouche 11162The recommended level of support for the non-default bit ordering is: 11163@end cartouche 11164@sp 1 11165@cartouche 11166If @code{Word_Size} = @code{Storage_Unit}, then the implementation 11167should support the non-default bit ordering in addition to the default 11168bit ordering. 11169@end cartouche 11170Followed. Word size does not equal storage size in this implementation. 11171Thus non-default bit ordering is not supported. 11172 11173@cindex @code{Address}, as private type 11174@unnumberedsec 13.7(37): Address as Private 11175@sp 1 11176@cartouche 11177@code{Address} should be of a private type. 11178@end cartouche 11179Followed. 11180 11181@cindex Operations, on @code{Address} 11182@cindex @code{Address}, operations of 11183@unnumberedsec 13.7.1(16): Address Operations 11184@sp 1 11185@cartouche 11186Operations in @code{System} and its children should reflect the target 11187environment semantics as closely as is reasonable. For example, on most 11188machines, it makes sense for address arithmetic to ``wrap around''. 11189Operations that do not make sense should raise @code{Program_Error}. 11190@end cartouche 11191Followed. Address arithmetic is modular arithmetic that wraps around. No 11192operation raises @code{Program_Error}, since all operations make sense. 11193 11194@cindex Unchecked conversion 11195@unnumberedsec 13.9(14-17): Unchecked Conversion 11196@sp 1 11197@cartouche 11198The @code{Size} of an array object should not include its bounds; hence, 11199the bounds should not be part of the converted data. 11200@end cartouche 11201Followed. 11202 11203@sp 1 11204@cartouche 11205The implementation should not generate unnecessary run-time checks to 11206ensure that the representation of @var{S} is a representation of the 11207target type. It should take advantage of the permission to return by 11208reference when possible. Restrictions on unchecked conversions should be 11209avoided unless required by the target environment. 11210@end cartouche 11211Followed. There are no restrictions on unchecked conversion. A warning is 11212generated if the source and target types do not have the same size since 11213the semantics in this case may be target dependent. 11214 11215@sp 1 11216@cartouche 11217The recommended level of support for unchecked conversions is: 11218@end cartouche 11219@sp 1 11220@cartouche 11221Unchecked conversions should be supported and should be reversible in 11222the cases where this clause defines the result. To enable meaningful use 11223of unchecked conversion, a contiguous representation should be used for 11224elementary subtypes, for statically constrained array subtypes whose 11225component subtype is one of the subtypes described in this paragraph, 11226and for record subtypes without discriminants whose component subtypes 11227are described in this paragraph. 11228@end cartouche 11229Followed. 11230 11231@cindex Heap usage, implicit 11232@unnumberedsec 13.11(23-25): Implicit Heap Usage 11233@sp 1 11234@cartouche 11235An implementation should document any cases in which it dynamically 11236allocates heap storage for a purpose other than the evaluation of an 11237allocator. 11238@end cartouche 11239Followed, the only other points at which heap storage is dynamically 11240allocated are as follows: 11241 11242@itemize @bullet 11243@item 11244At initial elaboration time, to allocate dynamically sized global 11245objects. 11246 11247@item 11248To allocate space for a task when a task is created. 11249 11250@item 11251To extend the secondary stack dynamically when needed. The secondary 11252stack is used for returning variable length results. 11253@end itemize 11254 11255@sp 1 11256@cartouche 11257A default (implementation-provided) storage pool for an 11258access-to-constant type should not have overhead to support deallocation of 11259individual objects. 11260@end cartouche 11261Followed. 11262 11263@sp 1 11264@cartouche 11265A storage pool for an anonymous access type should be created at the 11266point of an allocator for the type, and be reclaimed when the designated 11267object becomes inaccessible. 11268@end cartouche 11269Followed. 11270 11271@cindex Unchecked deallocation 11272@unnumberedsec 13.11.2(17): Unchecked De-allocation 11273@sp 1 11274@cartouche 11275For a standard storage pool, @code{Free} should actually reclaim the 11276storage. 11277@end cartouche 11278Followed. 11279 11280@cindex Stream oriented attributes 11281@unnumberedsec 13.13.2(17): Stream Oriented Attributes 11282@sp 1 11283@cartouche 11284If a stream element is the same size as a storage element, then the 11285normal in-memory representation should be used by @code{Read} and 11286@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write} 11287should use the smallest number of stream elements needed to represent 11288all values in the base range of the scalar type. 11289@end cartouche 11290 11291Followed. By default, GNAT uses the interpretation suggested by AI-195, 11292which specifies using the size of the first subtype. 11293However, such an implementation is based on direct binary 11294representations and is therefore target- and endianness-dependent. 11295To address this issue, GNAT also supplies an alternate implementation 11296of the stream attributes @code{Read} and @code{Write}, 11297which uses the target-independent XDR standard representation 11298for scalar types. 11299@cindex XDR representation 11300@cindex @code{Read} attribute 11301@cindex @code{Write} attribute 11302@cindex Stream oriented attributes 11303The XDR implementation is provided as an alternative body of the 11304@code{System.Stream_Attributes} package, in the file 11305@file{s-stratt-xdr.adb} in the GNAT library. 11306There is no @file{s-stratt-xdr.ads} file. 11307In order to install the XDR implementation, do the following: 11308@enumerate 11309@item Replace the default implementation of the 11310@code{System.Stream_Attributes} package with the XDR implementation. 11311For example on a Unix platform issue the commands: 11312@smallexample 11313$ mv s-stratt.adb s-stratt-default.adb 11314$ mv s-stratt-xdr.adb s-stratt.adb 11315@end smallexample 11316 11317@item 11318Rebuild the GNAT run-time library as documented in 11319@ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} User's Guide}. 11320@end enumerate 11321 11322@unnumberedsec A.1(52): Names of Predefined Numeric Types 11323@sp 1 11324@cartouche 11325If an implementation provides additional named predefined integer types, 11326then the names should end with @samp{Integer} as in 11327@samp{Long_Integer}. If an implementation provides additional named 11328predefined floating point types, then the names should end with 11329@samp{Float} as in @samp{Long_Float}. 11330@end cartouche 11331Followed. 11332 11333@findex Ada.Characters.Handling 11334@unnumberedsec A.3.2(49): @code{Ada.Characters.Handling} 11335@sp 1 11336@cartouche 11337If an implementation provides a localized definition of @code{Character} 11338or @code{Wide_Character}, then the effects of the subprograms in 11339@code{Characters.Handling} should reflect the localizations. See also 113403.5.2. 11341@end cartouche 11342Followed. GNAT provides no such localized definitions. 11343 11344@cindex Bounded-length strings 11345@unnumberedsec A.4.4(106): Bounded-Length String Handling 11346@sp 1 11347@cartouche 11348Bounded string objects should not be implemented by implicit pointers 11349and dynamic allocation. 11350@end cartouche 11351Followed. No implicit pointers or dynamic allocation are used. 11352 11353@cindex Random number generation 11354@unnumberedsec A.5.2(46-47): Random Number Generation 11355@sp 1 11356@cartouche 11357Any storage associated with an object of type @code{Generator} should be 11358reclaimed on exit from the scope of the object. 11359@end cartouche 11360Followed. 11361 11362@sp 1 11363@cartouche 11364If the generator period is sufficiently long in relation to the number 11365of distinct initiator values, then each possible value of 11366@code{Initiator} passed to @code{Reset} should initiate a sequence of 11367random numbers that does not, in a practical sense, overlap the sequence 11368initiated by any other value. If this is not possible, then the mapping 11369between initiator values and generator states should be a rapidly 11370varying function of the initiator value. 11371@end cartouche 11372Followed. The generator period is sufficiently long for the first 11373condition here to hold true. 11374 11375@findex Get_Immediate 11376@unnumberedsec A.10.7(23): @code{Get_Immediate} 11377@sp 1 11378@cartouche 11379The @code{Get_Immediate} procedures should be implemented with 11380unbuffered input. For a device such as a keyboard, input should be 11381@dfn{available} if a key has already been typed, whereas for a disk 11382file, input should always be available except at end of file. For a file 11383associated with a keyboard-like device, any line-editing features of the 11384underlying operating system should be disabled during the execution of 11385@code{Get_Immediate}. 11386@end cartouche 11387Followed on all targets except VxWorks. For VxWorks, there is no way to 11388provide this functionality that does not result in the input buffer being 11389flushed before the @code{Get_Immediate} call. A special unit 11390@code{Interfaces.Vxworks.IO} is provided that contains routines to enable 11391this functionality. 11392 11393@findex Export 11394@unnumberedsec B.1(39-41): Pragma @code{Export} 11395@sp 1 11396@cartouche 11397If an implementation supports pragma @code{Export} to a given language, 11398then it should also allow the main subprogram to be written in that 11399language. It should support some mechanism for invoking the elaboration 11400of the Ada library units included in the system, and for invoking the 11401finalization of the environment task. On typical systems, the 11402recommended mechanism is to provide two subprograms whose link names are 11403@code{adainit} and @code{adafinal}. @code{adainit} should contain the 11404elaboration code for library units. @code{adafinal} should contain the 11405finalization code. These subprograms should have no effect the second 11406and subsequent time they are called. 11407@end cartouche 11408Followed. 11409 11410@sp 1 11411@cartouche 11412Automatic elaboration of pre-elaborated packages should be 11413provided when pragma @code{Export} is supported. 11414@end cartouche 11415Followed when the main program is in Ada. If the main program is in a 11416foreign language, then 11417@code{adainit} must be called to elaborate pre-elaborated 11418packages. 11419 11420@sp 1 11421@cartouche 11422For each supported convention @var{L} other than @code{Intrinsic}, an 11423implementation should support @code{Import} and @code{Export} pragmas 11424for objects of @var{L}-compatible types and for subprograms, and pragma 11425@code{Convention} for @var{L}-eligible types and for subprograms, 11426presuming the other language has corresponding features. Pragma 11427@code{Convention} need not be supported for scalar types. 11428@end cartouche 11429Followed. 11430 11431@cindex Package @code{Interfaces} 11432@findex Interfaces 11433@unnumberedsec B.2(12-13): Package @code{Interfaces} 11434@sp 1 11435@cartouche 11436For each implementation-defined convention identifier, there should be a 11437child package of package Interfaces with the corresponding name. This 11438package should contain any declarations that would be useful for 11439interfacing to the language (implementation) represented by the 11440convention. Any declarations useful for interfacing to any language on 11441the given hardware architecture should be provided directly in 11442@code{Interfaces}. 11443@end cartouche 11444Followed. An additional package not defined 11445in the Ada Reference Manual is @code{Interfaces.CPP}, used 11446for interfacing to C++. 11447 11448@sp 1 11449@cartouche 11450An implementation supporting an interface to C, COBOL, or Fortran should 11451provide the corresponding package or packages described in the following 11452clauses. 11453@end cartouche 11454Followed. GNAT provides all the packages described in this section. 11455 11456@cindex C, interfacing with 11457@unnumberedsec B.3(63-71): Interfacing with C 11458@sp 1 11459@cartouche 11460An implementation should support the following interface correspondences 11461between Ada and C@. 11462@end cartouche 11463Followed. 11464 11465@sp 1 11466@cartouche 11467An Ada procedure corresponds to a void-returning C function. 11468@end cartouche 11469Followed. 11470 11471@sp 1 11472@cartouche 11473An Ada function corresponds to a non-void C function. 11474@end cartouche 11475Followed. 11476 11477@sp 1 11478@cartouche 11479An Ada @code{in} scalar parameter is passed as a scalar argument to a C 11480function. 11481@end cartouche 11482Followed. 11483 11484@sp 1 11485@cartouche 11486An Ada @code{in} parameter of an access-to-object type with designated 11487type @var{T} is passed as a @code{@var{t}*} argument to a C function, 11488where @var{t} is the C type corresponding to the Ada type @var{T}. 11489@end cartouche 11490Followed. 11491 11492@sp 1 11493@cartouche 11494An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out} 11495parameter of an elementary type @var{T}, is passed as a @code{@var{t}*} 11496argument to a C function, where @var{t} is the C type corresponding to 11497the Ada type @var{T}. In the case of an elementary @code{out} or 11498@code{in out} parameter, a pointer to a temporary copy is used to 11499preserve by-copy semantics. 11500@end cartouche 11501Followed. 11502 11503@sp 1 11504@cartouche 11505An Ada parameter of a record type @var{T}, of any mode, is passed as a 11506@code{@var{t}*} argument to a C function, where @var{t} is the C 11507structure corresponding to the Ada type @var{T}. 11508@end cartouche 11509Followed. This convention may be overridden by the use of the C_Pass_By_Copy 11510pragma, or Convention, or by explicitly specifying the mechanism for a given 11511call using an extended import or export pragma. 11512 11513@sp 1 11514@cartouche 11515An Ada parameter of an array type with component type @var{T}, of any 11516mode, is passed as a @code{@var{t}*} argument to a C function, where 11517@var{t} is the C type corresponding to the Ada type @var{T}. 11518@end cartouche 11519Followed. 11520 11521@sp 1 11522@cartouche 11523An Ada parameter of an access-to-subprogram type is passed as a pointer 11524to a C function whose prototype corresponds to the designated 11525subprogram's specification. 11526@end cartouche 11527Followed. 11528 11529@cindex COBOL, interfacing with 11530@unnumberedsec B.4(95-98): Interfacing with COBOL 11531@sp 1 11532@cartouche 11533An Ada implementation should support the following interface 11534correspondences between Ada and COBOL@. 11535@end cartouche 11536Followed. 11537 11538@sp 1 11539@cartouche 11540An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of 11541the COBOL type corresponding to @var{T}. 11542@end cartouche 11543Followed. 11544 11545@sp 1 11546@cartouche 11547An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of 11548the corresponding COBOL type. 11549@end cartouche 11550Followed. 11551 11552@sp 1 11553@cartouche 11554Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the 11555COBOL type corresponding to the Ada parameter type; for scalars, a local 11556copy is used if necessary to ensure by-copy semantics. 11557@end cartouche 11558Followed. 11559 11560@cindex Fortran, interfacing with 11561@unnumberedsec B.5(22-26): Interfacing with Fortran 11562@sp 1 11563@cartouche 11564An Ada implementation should support the following interface 11565correspondences between Ada and Fortran: 11566@end cartouche 11567Followed. 11568 11569@sp 1 11570@cartouche 11571An Ada procedure corresponds to a Fortran subroutine. 11572@end cartouche 11573Followed. 11574 11575@sp 1 11576@cartouche 11577An Ada function corresponds to a Fortran function. 11578@end cartouche 11579Followed. 11580 11581@sp 1 11582@cartouche 11583An Ada parameter of an elementary, array, or record type @var{T} is 11584passed as a @var{T} argument to a Fortran procedure, where @var{T} is 11585the Fortran type corresponding to the Ada type @var{T}, and where the 11586INTENT attribute of the corresponding dummy argument matches the Ada 11587formal parameter mode; the Fortran implementation's parameter passing 11588conventions are used. For elementary types, a local copy is used if 11589necessary to ensure by-copy semantics. 11590@end cartouche 11591Followed. 11592 11593@sp 1 11594@cartouche 11595An Ada parameter of an access-to-subprogram type is passed as a 11596reference to a Fortran procedure whose interface corresponds to the 11597designated subprogram's specification. 11598@end cartouche 11599Followed. 11600 11601@cindex Machine operations 11602@unnumberedsec C.1(3-5): Access to Machine Operations 11603@sp 1 11604@cartouche 11605The machine code or intrinsic support should allow access to all 11606operations normally available to assembly language programmers for the 11607target environment, including privileged instructions, if any. 11608@end cartouche 11609Followed. 11610 11611@sp 1 11612@cartouche 11613The interfacing pragmas (see Annex B) should support interface to 11614assembler; the default assembler should be associated with the 11615convention identifier @code{Assembler}. 11616@end cartouche 11617Followed. 11618 11619@sp 1 11620@cartouche 11621If an entity is exported to assembly language, then the implementation 11622should allocate it at an addressable location, and should ensure that it 11623is retained by the linking process, even if not otherwise referenced 11624from the Ada code. The implementation should assume that any call to a 11625machine code or assembler subprogram is allowed to read or update every 11626object that is specified as exported. 11627@end cartouche 11628Followed. 11629 11630@unnumberedsec C.1(10-16): Access to Machine Operations 11631@sp 1 11632@cartouche 11633The implementation should ensure that little or no overhead is 11634associated with calling intrinsic and machine-code subprograms. 11635@end cartouche 11636Followed for both intrinsics and machine-code subprograms. 11637 11638@sp 1 11639@cartouche 11640It is recommended that intrinsic subprograms be provided for convenient 11641access to any machine operations that provide special capabilities or 11642efficiency and that are not otherwise available through the language 11643constructs. 11644@end cartouche 11645Followed. A full set of machine operation intrinsic subprograms is provided. 11646 11647@sp 1 11648@cartouche 11649Atomic read-modify-write operations---e.g.@:, test and set, compare and 11650swap, decrement and test, enqueue/dequeue. 11651@end cartouche 11652Followed on any target supporting such operations. 11653 11654@sp 1 11655@cartouche 11656Standard numeric functions---e.g.@:, sin, log. 11657@end cartouche 11658Followed on any target supporting such operations. 11659 11660@sp 1 11661@cartouche 11662String manipulation operations---e.g.@:, translate and test. 11663@end cartouche 11664Followed on any target supporting such operations. 11665 11666@sp 1 11667@cartouche 11668Vector operations---e.g.@:, compare vector against thresholds. 11669@end cartouche 11670Followed on any target supporting such operations. 11671 11672@sp 1 11673@cartouche 11674Direct operations on I/O ports. 11675@end cartouche 11676Followed on any target supporting such operations. 11677 11678@cindex Interrupt support 11679@unnumberedsec C.3(28): Interrupt Support 11680@sp 1 11681@cartouche 11682If the @code{Ceiling_Locking} policy is not in effect, the 11683implementation should provide means for the application to specify which 11684interrupts are to be blocked during protected actions, if the underlying 11685system allows for a finer-grain control of interrupt blocking. 11686@end cartouche 11687Followed. The underlying system does not allow for finer-grain control 11688of interrupt blocking. 11689 11690@cindex Protected procedure handlers 11691@unnumberedsec C.3.1(20-21): Protected Procedure Handlers 11692@sp 1 11693@cartouche 11694Whenever possible, the implementation should allow interrupt handlers to 11695be called directly by the hardware. 11696@end cartouche 11697Followed on any target where the underlying operating system permits 11698such direct calls. 11699 11700@sp 1 11701@cartouche 11702Whenever practical, violations of any 11703implementation-defined restrictions should be detected before run time. 11704@end cartouche 11705Followed. Compile time warnings are given when possible. 11706 11707@cindex Package @code{Interrupts} 11708@findex Interrupts 11709@unnumberedsec C.3.2(25): Package @code{Interrupts} 11710 11711@sp 1 11712@cartouche 11713If implementation-defined forms of interrupt handler procedures are 11714supported, such as protected procedures with parameters, then for each 11715such form of a handler, a type analogous to @code{Parameterless_Handler} 11716should be specified in a child package of @code{Interrupts}, with the 11717same operations as in the predefined package Interrupts. 11718@end cartouche 11719Followed. 11720 11721@cindex Pre-elaboration requirements 11722@unnumberedsec C.4(14): Pre-elaboration Requirements 11723@sp 1 11724@cartouche 11725It is recommended that pre-elaborated packages be implemented in such a 11726way that there should be little or no code executed at run time for the 11727elaboration of entities not already covered by the Implementation 11728Requirements. 11729@end cartouche 11730Followed. Executable code is generated in some cases, e.g.@: loops 11731to initialize large arrays. 11732 11733@unnumberedsec C.5(8): Pragma @code{Discard_Names} 11734@sp 1 11735@cartouche 11736If the pragma applies to an entity, then the implementation should 11737reduce the amount of storage used for storing names associated with that 11738entity. 11739@end cartouche 11740Followed. 11741 11742@cindex Package @code{Task_Attributes} 11743@findex Task_Attributes 11744@unnumberedsec C.7.2(30): The Package Task_Attributes 11745@sp 1 11746@cartouche 11747Some implementations are targeted to domains in which memory use at run 11748time must be completely deterministic. For such implementations, it is 11749recommended that the storage for task attributes will be pre-allocated 11750statically and not from the heap. This can be accomplished by either 11751placing restrictions on the number and the size of the task's 11752attributes, or by using the pre-allocated storage for the first @var{N} 11753attribute objects, and the heap for the others. In the latter case, 11754@var{N} should be documented. 11755@end cartouche 11756Not followed. This implementation is not targeted to such a domain. 11757 11758@cindex Locking Policies 11759@unnumberedsec D.3(17): Locking Policies 11760 11761@sp 1 11762@cartouche 11763The implementation should use names that end with @samp{_Locking} for 11764locking policies defined by the implementation. 11765@end cartouche 11766Followed. Two implementation-defined locking policies are defined, 11767whose names (@code{Inheritance_Locking} and 11768@code{Concurrent_Readers_Locking}) follow this suggestion. 11769 11770@cindex Entry queuing policies 11771@unnumberedsec D.4(16): Entry Queuing Policies 11772@sp 1 11773@cartouche 11774Names that end with @samp{_Queuing} should be used 11775for all implementation-defined queuing policies. 11776@end cartouche 11777Followed. No such implementation-defined queuing policies exist. 11778 11779@cindex Preemptive abort 11780@unnumberedsec D.6(9-10): Preemptive Abort 11781@sp 1 11782@cartouche 11783Even though the @code{abort_statement} is included in the list of 11784potentially blocking operations (see 9.5.1), it is recommended that this 11785statement be implemented in a way that never requires the task executing 11786the @code{abort_statement} to block. 11787@end cartouche 11788Followed. 11789 11790@sp 1 11791@cartouche 11792On a multi-processor, the delay associated with aborting a task on 11793another processor should be bounded; the implementation should use 11794periodic polling, if necessary, to achieve this. 11795@end cartouche 11796Followed. 11797 11798@cindex Tasking restrictions 11799@unnumberedsec D.7(21): Tasking Restrictions 11800@sp 1 11801@cartouche 11802When feasible, the implementation should take advantage of the specified 11803restrictions to produce a more efficient implementation. 11804@end cartouche 11805GNAT currently takes advantage of these restrictions by providing an optimized 11806run time when the Ravenscar profile and the GNAT restricted run time set 11807of restrictions are specified. See pragma @code{Profile (Ravenscar)} and 11808pragma @code{Profile (Restricted)} for more details. 11809 11810@cindex Time, monotonic 11811@unnumberedsec D.8(47-49): Monotonic Time 11812@sp 1 11813@cartouche 11814When appropriate, implementations should provide configuration 11815mechanisms to change the value of @code{Tick}. 11816@end cartouche 11817Such configuration mechanisms are not appropriate to this implementation 11818and are thus not supported. 11819 11820@sp 1 11821@cartouche 11822It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} 11823be implemented as transformations of the same time base. 11824@end cartouche 11825Followed. 11826 11827@sp 1 11828@cartouche 11829It is recommended that the @dfn{best} time base which exists in 11830the underlying system be available to the application through 11831@code{Clock}. @dfn{Best} may mean highest accuracy or largest range. 11832@end cartouche 11833Followed. 11834 11835@cindex Partition communication subsystem 11836@cindex PCS 11837@unnumberedsec E.5(28-29): Partition Communication Subsystem 11838@sp 1 11839@cartouche 11840Whenever possible, the PCS on the called partition should allow for 11841multiple tasks to call the RPC-receiver with different messages and 11842should allow them to block until the corresponding subprogram body 11843returns. 11844@end cartouche 11845Followed by GLADE, a separately supplied PCS that can be used with 11846GNAT. 11847 11848@sp 1 11849@cartouche 11850The @code{Write} operation on a stream of type @code{Params_Stream_Type} 11851should raise @code{Storage_Error} if it runs out of space trying to 11852write the @code{Item} into the stream. 11853@end cartouche 11854Followed by GLADE, a separately supplied PCS that can be used with 11855GNAT@. 11856 11857@cindex COBOL support 11858@unnumberedsec F(7): COBOL Support 11859@sp 1 11860@cartouche 11861If COBOL (respectively, C) is widely supported in the target 11862environment, implementations supporting the Information Systems Annex 11863should provide the child package @code{Interfaces.COBOL} (respectively, 11864@code{Interfaces.C}) specified in Annex B and should support a 11865@code{convention_identifier} of COBOL (respectively, C) in the interfacing 11866pragmas (see Annex B), thus allowing Ada programs to interface with 11867programs written in that language. 11868@end cartouche 11869Followed. 11870 11871@cindex Decimal radix support 11872@unnumberedsec F.1(2): Decimal Radix Support 11873@sp 1 11874@cartouche 11875Packed decimal should be used as the internal representation for objects 11876of subtype @var{S} when @var{S}'Machine_Radix = 10. 11877@end cartouche 11878Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary 11879representations. 11880 11881@cindex Numerics 11882@unnumberedsec G: Numerics 11883@sp 2 11884@cartouche 11885If Fortran (respectively, C) is widely supported in the target 11886environment, implementations supporting the Numerics Annex 11887should provide the child package @code{Interfaces.Fortran} (respectively, 11888@code{Interfaces.C}) specified in Annex B and should support a 11889@code{convention_identifier} of Fortran (respectively, C) in the interfacing 11890pragmas (see Annex B), thus allowing Ada programs to interface with 11891programs written in that language. 11892@end cartouche 11893Followed. 11894 11895@cindex Complex types 11896@unnumberedsec G.1.1(56-58): Complex Types 11897@sp 2 11898@cartouche 11899Because the usual mathematical meaning of multiplication of a complex 11900operand and a real operand is that of the scaling of both components of 11901the former by the latter, an implementation should not perform this 11902operation by first promoting the real operand to complex type and then 11903performing a full complex multiplication. In systems that, in the 11904future, support an Ada binding to IEC 559:1989, the latter technique 11905will not generate the required result when one of the components of the 11906complex operand is infinite. (Explicit multiplication of the infinite 11907component by the zero component obtained during promotion yields a NaN 11908that propagates into the final result.) Analogous advice applies in the 11909case of multiplication of a complex operand and a pure-imaginary 11910operand, and in the case of division of a complex operand by a real or 11911pure-imaginary operand. 11912@end cartouche 11913Not followed. 11914 11915@sp 1 11916@cartouche 11917Similarly, because the usual mathematical meaning of addition of a 11918complex operand and a real operand is that the imaginary operand remains 11919unchanged, an implementation should not perform this operation by first 11920promoting the real operand to complex type and then performing a full 11921complex addition. In implementations in which the @code{Signed_Zeros} 11922attribute of the component type is @code{True} (and which therefore 11923conform to IEC 559:1989 in regard to the handling of the sign of zero in 11924predefined arithmetic operations), the latter technique will not 11925generate the required result when the imaginary component of the complex 11926operand is a negatively signed zero. (Explicit addition of the negative 11927zero to the zero obtained during promotion yields a positive zero.) 11928Analogous advice applies in the case of addition of a complex operand 11929and a pure-imaginary operand, and in the case of subtraction of a 11930complex operand and a real or pure-imaginary operand. 11931@end cartouche 11932Not followed. 11933 11934@sp 1 11935@cartouche 11936Implementations in which @code{Real'Signed_Zeros} is @code{True} should 11937attempt to provide a rational treatment of the signs of zero results and 11938result components. As one example, the result of the @code{Argument} 11939function should have the sign of the imaginary component of the 11940parameter @code{X} when the point represented by that parameter lies on 11941the positive real axis; as another, the sign of the imaginary component 11942of the @code{Compose_From_Polar} function should be the same as 11943(respectively, the opposite of) that of the @code{Argument} parameter when that 11944parameter has a value of zero and the @code{Modulus} parameter has a 11945nonnegative (respectively, negative) value. 11946@end cartouche 11947Followed. 11948 11949@cindex Complex elementary functions 11950@unnumberedsec G.1.2(49): Complex Elementary Functions 11951@sp 1 11952@cartouche 11953Implementations in which @code{Complex_Types.Real'Signed_Zeros} is 11954@code{True} should attempt to provide a rational treatment of the signs 11955of zero results and result components. For example, many of the complex 11956elementary functions have components that are odd functions of one of 11957the parameter components; in these cases, the result component should 11958have the sign of the parameter component at the origin. Other complex 11959elementary functions have zero components whose sign is opposite that of 11960a parameter component at the origin, or is always positive or always 11961negative. 11962@end cartouche 11963Followed. 11964 11965@cindex Accuracy requirements 11966@unnumberedsec G.2.4(19): Accuracy Requirements 11967@sp 1 11968@cartouche 11969The versions of the forward trigonometric functions without a 11970@code{Cycle} parameter should not be implemented by calling the 11971corresponding version with a @code{Cycle} parameter of 11972@code{2.0*Numerics.Pi}, since this will not provide the required 11973accuracy in some portions of the domain. For the same reason, the 11974version of @code{Log} without a @code{Base} parameter should not be 11975implemented by calling the corresponding version with a @code{Base} 11976parameter of @code{Numerics.e}. 11977@end cartouche 11978Followed. 11979 11980@cindex Complex arithmetic accuracy 11981@cindex Accuracy, complex arithmetic 11982@unnumberedsec G.2.6(15): Complex Arithmetic Accuracy 11983 11984@sp 1 11985@cartouche 11986The version of the @code{Compose_From_Polar} function without a 11987@code{Cycle} parameter should not be implemented by calling the 11988corresponding version with a @code{Cycle} parameter of 11989@code{2.0*Numerics.Pi}, since this will not provide the required 11990accuracy in some portions of the domain. 11991@end cartouche 11992Followed. 11993 11994@cindex Sequential elaboration policy 11995@unnumberedsec H.6(15/2): Pragma Partition_Elaboration_Policy 11996 11997@sp 1 11998@cartouche 11999If the partition elaboration policy is @code{Sequential} and the 12000Environment task becomes permanently blocked during elaboration then the 12001partition is deadlocked and it is recommended that the partition be 12002immediately terminated. 12003@end cartouche 12004Not followed. 12005 12006@c ----------------------------------------- 12007@node Implementation Defined Characteristics 12008@chapter Implementation Defined Characteristics 12009 12010@noindent 12011In addition to the implementation dependent pragmas and attributes, and the 12012implementation advice, there are a number of other Ada features that are 12013potentially implementation dependent and are designated as 12014implementation-defined. These are mentioned throughout the Ada Reference 12015Manual, and are summarized in Annex M@. 12016 12017A requirement for conforming Ada compilers is that they provide 12018documentation describing how the implementation deals with each of these 12019issues. In this chapter, you will find each point in Annex M listed 12020followed by a description in italic font of how GNAT 12021handles the implementation dependence. 12022 12023You can use this chapter as a guide to minimizing implementation 12024dependent features in your programs if portability to other compilers 12025and other operating systems is an important consideration. The numbers 12026in each section below correspond to the paragraph number in the Ada 12027Reference Manual. 12028 12029@sp 1 12030@cartouche 12031@noindent 12032@strong{2}. Whether or not each recommendation given in Implementation 12033Advice is followed. See 1.1.2(37). 12034@end cartouche 12035@noindent 12036@xref{Implementation Advice}. 12037 12038@sp 1 12039@cartouche 12040@noindent 12041@strong{3}. Capacity limitations of the implementation. See 1.1.3(3). 12042@end cartouche 12043@noindent 12044The complexity of programs that can be processed is limited only by the 12045total amount of available virtual memory, and disk space for the 12046generated object files. 12047 12048@sp 1 12049@cartouche 12050@noindent 12051@strong{4}. Variations from the standard that are impractical to avoid 12052given the implementation's execution environment. See 1.1.3(6). 12053@end cartouche 12054@noindent 12055There are no variations from the standard. 12056 12057@sp 1 12058@cartouche 12059@noindent 12060@strong{5}. Which @code{code_statement}s cause external 12061interactions. See 1.1.3(10). 12062@end cartouche 12063@noindent 12064Any @code{code_statement} can potentially cause external interactions. 12065 12066@sp 1 12067@cartouche 12068@noindent 12069@strong{6}. The coded representation for the text of an Ada 12070program. See 2.1(4). 12071@end cartouche 12072@noindent 12073See separate section on source representation. 12074 12075@sp 1 12076@cartouche 12077@noindent 12078@strong{7}. The control functions allowed in comments. See 2.1(14). 12079@end cartouche 12080@noindent 12081See separate section on source representation. 12082 12083@sp 1 12084@cartouche 12085@noindent 12086@strong{8}. The representation for an end of line. See 2.2(2). 12087@end cartouche 12088@noindent 12089See separate section on source representation. 12090 12091@sp 1 12092@cartouche 12093@noindent 12094@strong{9}. Maximum supported line length and lexical element 12095length. See 2.2(15). 12096@end cartouche 12097@noindent 12098The maximum line length is 255 characters and the maximum length of 12099a lexical element is also 255 characters. This is the default setting 12100if not overridden by the use of compiler switch @option{-gnaty} (which 12101sets the maximum to 79) or @option{-gnatyMnn} which allows the maximum 12102line length to be specified to be any value up to 32767. The maximum 12103length of a lexical element is the same as the maximum line length. 12104 12105@sp 1 12106@cartouche 12107@noindent 12108@strong{10}. Implementation defined pragmas. See 2.8(14). 12109@end cartouche 12110@noindent 12111 12112@xref{Implementation Defined Pragmas}. 12113 12114@sp 1 12115@cartouche 12116@noindent 12117@strong{11}. Effect of pragma @code{Optimize}. See 2.8(27). 12118@end cartouche 12119@noindent 12120Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} 12121parameter, checks that the optimization flag is set, and aborts if it is 12122not. 12123 12124@sp 1 12125@cartouche 12126@noindent 12127@strong{12}. The sequence of characters of the value returned by 12128@code{@var{S}'Image} when some of the graphic characters of 12129@code{@var{S}'Wide_Image} are not defined in @code{Character}. See 121303.5(37). 12131@end cartouche 12132@noindent 12133The sequence of characters is as defined by the wide character encoding 12134method used for the source. See section on source representation for 12135further details. 12136 12137@sp 1 12138@cartouche 12139@noindent 12140@strong{13}. The predefined integer types declared in 12141@code{Standard}. See 3.5.4(25). 12142@end cartouche 12143@noindent 12144@table @code 12145@item Short_Short_Integer 121468 bit signed 12147@item Short_Integer 12148(Short) 16 bit signed 12149@item Integer 1215032 bit signed 12151@item Long_Integer 1215264 bit signed (on most 64 bit targets, depending on the C definition of long). 1215332 bit signed (all other targets) 12154@item Long_Long_Integer 1215564 bit signed 12156@end table 12157 12158@sp 1 12159@cartouche 12160@noindent 12161@strong{14}. Any nonstandard integer types and the operators defined 12162for them. See 3.5.4(26). 12163@end cartouche 12164@noindent 12165There are no nonstandard integer types. 12166 12167@sp 1 12168@cartouche 12169@noindent 12170@strong{15}. Any nonstandard real types and the operators defined for 12171them. See 3.5.6(8). 12172@end cartouche 12173@noindent 12174There are no nonstandard real types. 12175 12176@sp 1 12177@cartouche 12178@noindent 12179@strong{16}. What combinations of requested decimal precision and range 12180are supported for floating point types. See 3.5.7(7). 12181@end cartouche 12182@noindent 12183The precision and range is as defined by the IEEE standard. 12184 12185@sp 1 12186@cartouche 12187@noindent 12188@strong{17}. The predefined floating point types declared in 12189@code{Standard}. See 3.5.7(16). 12190@end cartouche 12191@noindent 12192@table @code 12193@item Short_Float 1219432 bit IEEE short 12195@item Float 12196(Short) 32 bit IEEE short 12197@item Long_Float 1219864 bit IEEE long 12199@item Long_Long_Float 1220064 bit IEEE long (80 bit IEEE long on x86 processors) 12201@end table 12202 12203@sp 1 12204@cartouche 12205@noindent 12206@strong{18}. The small of an ordinary fixed point type. See 3.5.9(8). 12207@end cartouche 12208@noindent 12209@code{Fine_Delta} is 2**(@minus{}63) 12210 12211@sp 1 12212@cartouche 12213@noindent 12214@strong{19}. What combinations of small, range, and digits are 12215supported for fixed point types. See 3.5.9(10). 12216@end cartouche 12217@noindent 12218Any combinations are permitted that do not result in a small less than 12219@code{Fine_Delta} and do not result in a mantissa larger than 63 bits. 12220If the mantissa is larger than 53 bits on machines where Long_Long_Float 12221is 64 bits (true of all architectures except ia32), then the output from 12222Text_IO is accurate to only 53 bits, rather than the full mantissa. This 12223is because floating-point conversions are used to convert fixed point. 12224 12225@sp 1 12226@cartouche 12227@noindent 12228@strong{20}. The result of @code{Tags.Expanded_Name} for types declared 12229within an unnamed @code{block_statement}. See 3.9(10). 12230@end cartouche 12231@noindent 12232Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a 12233decimal integer are allocated. 12234 12235@sp 1 12236@cartouche 12237@noindent 12238@strong{21}. Implementation-defined attributes. See 4.1.4(12). 12239@end cartouche 12240@noindent 12241@xref{Implementation Defined Attributes}. 12242 12243@sp 1 12244@cartouche 12245@noindent 12246@strong{22}. Any implementation-defined time types. See 9.6(6). 12247@end cartouche 12248@noindent 12249There are no implementation-defined time types. 12250 12251@sp 1 12252@cartouche 12253@noindent 12254@strong{23}. The time base associated with relative delays. 12255@end cartouche 12256@noindent 12257See 9.6(20). The time base used is that provided by the C library 12258function @code{gettimeofday}. 12259 12260@sp 1 12261@cartouche 12262@noindent 12263@strong{24}. The time base of the type @code{Calendar.Time}. See 122649.6(23). 12265@end cartouche 12266@noindent 12267The time base used is that provided by the C library function 12268@code{gettimeofday}. 12269 12270@sp 1 12271@cartouche 12272@noindent 12273@strong{25}. The time zone used for package @code{Calendar} 12274operations. See 9.6(24). 12275@end cartouche 12276@noindent 12277The time zone used by package @code{Calendar} is the current system time zone 12278setting for local time, as accessed by the C library function 12279@code{localtime}. 12280 12281@sp 1 12282@cartouche 12283@noindent 12284@strong{26}. Any limit on @code{delay_until_statements} of 12285@code{select_statements}. See 9.6(29). 12286@end cartouche 12287@noindent 12288There are no such limits. 12289 12290@sp 1 12291@cartouche 12292@noindent 12293@strong{27}. Whether or not two non-overlapping parts of a composite 12294object are independently addressable, in the case where packing, record 12295layout, or @code{Component_Size} is specified for the object. See 122969.10(1). 12297@end cartouche 12298@noindent 12299Separate components are independently addressable if they do not share 12300overlapping storage units. 12301 12302@sp 1 12303@cartouche 12304@noindent 12305@strong{28}. The representation for a compilation. See 10.1(2). 12306@end cartouche 12307@noindent 12308A compilation is represented by a sequence of files presented to the 12309compiler in a single invocation of the @command{gcc} command. 12310 12311@sp 1 12312@cartouche 12313@noindent 12314@strong{29}. Any restrictions on compilations that contain multiple 12315compilation_units. See 10.1(4). 12316@end cartouche 12317@noindent 12318No single file can contain more than one compilation unit, but any 12319sequence of files can be presented to the compiler as a single 12320compilation. 12321 12322@sp 1 12323@cartouche 12324@noindent 12325@strong{30}. The mechanisms for creating an environment and for adding 12326and replacing compilation units. See 10.1.4(3). 12327@end cartouche 12328@noindent 12329See separate section on compilation model. 12330 12331@sp 1 12332@cartouche 12333@noindent 12334@strong{31}. The manner of explicitly assigning library units to a 12335partition. See 10.2(2). 12336@end cartouche 12337@noindent 12338If a unit contains an Ada main program, then the Ada units for the partition 12339are determined by recursive application of the rules in the Ada Reference 12340Manual section 10.2(2-6). In other words, the Ada units will be those that 12341are needed by the main program, and then this definition of need is applied 12342recursively to those units, and the partition contains the transitive 12343closure determined by this relationship. In short, all the necessary units 12344are included, with no need to explicitly specify the list. If additional 12345units are required, e.g.@: by foreign language units, then all units must be 12346mentioned in the context clause of one of the needed Ada units. 12347 12348If the partition contains no main program, or if the main program is in 12349a language other than Ada, then GNAT 12350provides the binder options @option{-z} and @option{-n} respectively, and in 12351this case a list of units can be explicitly supplied to the binder for 12352inclusion in the partition (all units needed by these units will also 12353be included automatically). For full details on the use of these 12354options, refer to @ref{The GNAT Make Program gnatmake,,, gnat_ugn, 12355@value{EDITION} User's Guide}. 12356 12357@sp 1 12358@cartouche 12359@noindent 12360@strong{32}. The implementation-defined means, if any, of specifying 12361which compilation units are needed by a given compilation unit. See 1236210.2(2). 12363@end cartouche 12364@noindent 12365The units needed by a given compilation unit are as defined in 12366the Ada Reference Manual section 10.2(2-6). There are no 12367implementation-defined pragmas or other implementation-defined 12368means for specifying needed units. 12369 12370@sp 1 12371@cartouche 12372@noindent 12373@strong{33}. The manner of designating the main subprogram of a 12374partition. See 10.2(7). 12375@end cartouche 12376@noindent 12377The main program is designated by providing the name of the 12378corresponding @file{ALI} file as the input parameter to the binder. 12379 12380@sp 1 12381@cartouche 12382@noindent 12383@strong{34}. The order of elaboration of @code{library_items}. See 1238410.2(18). 12385@end cartouche 12386@noindent 12387The first constraint on ordering is that it meets the requirements of 12388Chapter 10 of the Ada Reference Manual. This still leaves some 12389implementation dependent choices, which are resolved by first 12390elaborating bodies as early as possible (i.e., in preference to specs 12391where there is a choice), and second by evaluating the immediate with 12392clauses of a unit to determine the probably best choice, and 12393third by elaborating in alphabetical order of unit names 12394where a choice still remains. 12395 12396@sp 1 12397@cartouche 12398@noindent 12399@strong{35}. Parameter passing and function return for the main 12400subprogram. See 10.2(21). 12401@end cartouche 12402@noindent 12403The main program has no parameters. It may be a procedure, or a function 12404returning an integer type. In the latter case, the returned integer 12405value is the return code of the program (overriding any value that 12406may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). 12407 12408@sp 1 12409@cartouche 12410@noindent 12411@strong{36}. The mechanisms for building and running partitions. See 1241210.2(24). 12413@end cartouche 12414@noindent 12415GNAT itself supports programs with only a single partition. The GNATDIST 12416tool provided with the GLADE package (which also includes an implementation 12417of the PCS) provides a completely flexible method for building and running 12418programs consisting of multiple partitions. See the separate GLADE manual 12419for details. 12420 12421@sp 1 12422@cartouche 12423@noindent 12424@strong{37}. The details of program execution, including program 12425termination. See 10.2(25). 12426@end cartouche 12427@noindent 12428See separate section on compilation model. 12429 12430@sp 1 12431@cartouche 12432@noindent 12433@strong{38}. The semantics of any non-active partitions supported by the 12434implementation. See 10.2(28). 12435@end cartouche 12436@noindent 12437Passive partitions are supported on targets where shared memory is 12438provided by the operating system. See the GLADE reference manual for 12439further details. 12440 12441@sp 1 12442@cartouche 12443@noindent 12444@strong{39}. The information returned by @code{Exception_Message}. See 1244511.4.1(10). 12446@end cartouche 12447@noindent 12448Exception message returns the null string unless a specific message has 12449been passed by the program. 12450 12451@sp 1 12452@cartouche 12453@noindent 12454@strong{40}. The result of @code{Exceptions.Exception_Name} for types 12455declared within an unnamed @code{block_statement}. See 11.4.1(12). 12456@end cartouche 12457@noindent 12458Blocks have implementation defined names of the form @code{B@var{nnn}} 12459where @var{nnn} is an integer. 12460 12461@sp 1 12462@cartouche 12463@noindent 12464@strong{41}. The information returned by 12465@code{Exception_Information}. See 11.4.1(13). 12466@end cartouche 12467@noindent 12468@code{Exception_Information} returns a string in the following format: 12469 12470@smallexample 12471@emph{Exception_Name:} nnnnn 12472@emph{Message:} mmmmm 12473@emph{PID:} ppp 12474@emph{Load address:} 0xhhhh 12475@emph{Call stack traceback locations:} 124760xhhhh 0xhhhh 0xhhhh ... 0xhhh 12477@end smallexample 12478 12479@noindent 12480where 12481 12482@itemize @bullet 12483@item 12484@code{nnnn} is the fully qualified name of the exception in all upper 12485case letters. This line is always present. 12486 12487@item 12488@code{mmmm} is the message (this line present only if message is non-null) 12489 12490@item 12491@code{ppp} is the Process Id value as a decimal integer (this line is 12492present only if the Process Id is nonzero). Currently we are 12493not making use of this field. 12494 12495@item 12496The Load address line, the Call stack traceback locations line and the 12497following values are present only if at least one traceback location was 12498recorded. The Load address indicates the address at which the main executable 12499was loaded; this line may not be present if operating system hasn't relocated 12500the main executable. The values are given in C style format, with lower case 12501letters for a-f, and only as many digits present as are necessary. 12502@end itemize 12503 12504@noindent 12505The line terminator sequence at the end of each line, including 12506the last line is a single @code{LF} character (@code{16#0A#}). 12507 12508@sp 1 12509@cartouche 12510@noindent 12511@strong{42}. Implementation-defined check names. See 11.5(27). 12512@end cartouche 12513@noindent 12514The implementation defined check name Alignment_Check controls checking of 12515address clause values for proper alignment (that is, the address supplied 12516must be consistent with the alignment of the type). 12517 12518The implementation defined check name Predicate_Check controls whether 12519predicate checks are generated. 12520 12521The implementation defined check name Validity_Check controls whether 12522validity checks are generated. 12523 12524In addition, a user program can add implementation-defined check names 12525by means of the pragma Check_Name. 12526 12527@sp 1 12528@cartouche 12529@noindent 12530@strong{43}. The interpretation of each aspect of representation. See 1253113.1(20). 12532@end cartouche 12533@noindent 12534See separate section on data representations. 12535 12536@sp 1 12537@cartouche 12538@noindent 12539@strong{44}. Any restrictions placed upon representation items. See 1254013.1(20). 12541@end cartouche 12542@noindent 12543See separate section on data representations. 12544 12545@sp 1 12546@cartouche 12547@noindent 12548@strong{45}. The meaning of @code{Size} for indefinite subtypes. See 1254913.3(48). 12550@end cartouche 12551@noindent 12552Size for an indefinite subtype is the maximum possible size, except that 12553for the case of a subprogram parameter, the size of the parameter object 12554is the actual size. 12555 12556@sp 1 12557@cartouche 12558@noindent 12559@strong{46}. The default external representation for a type tag. See 1256013.3(75). 12561@end cartouche 12562@noindent 12563The default external representation for a type tag is the fully expanded 12564name of the type in upper case letters. 12565 12566@sp 1 12567@cartouche 12568@noindent 12569@strong{47}. What determines whether a compilation unit is the same in 12570two different partitions. See 13.3(76). 12571@end cartouche 12572@noindent 12573A compilation unit is the same in two different partitions if and only 12574if it derives from the same source file. 12575 12576@sp 1 12577@cartouche 12578@noindent 12579@strong{48}. Implementation-defined components. See 13.5.1(15). 12580@end cartouche 12581@noindent 12582The only implementation defined component is the tag for a tagged type, 12583which contains a pointer to the dispatching table. 12584 12585@sp 1 12586@cartouche 12587@noindent 12588@strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit 12589ordering. See 13.5.3(5). 12590@end cartouche 12591@noindent 12592@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this 12593implementation, so no non-default bit ordering is supported. The default 12594bit ordering corresponds to the natural endianness of the target architecture. 12595 12596@sp 1 12597@cartouche 12598@noindent 12599@strong{50}. The contents of the visible part of package @code{System} 12600and its language-defined children. See 13.7(2). 12601@end cartouche 12602@noindent 12603See the definition of these packages in files @file{system.ads} and 12604@file{s-stoele.ads}. 12605 12606@sp 1 12607@cartouche 12608@noindent 12609@strong{51}. The contents of the visible part of package 12610@code{System.Machine_Code}, and the meaning of 12611@code{code_statements}. See 13.8(7). 12612@end cartouche 12613@noindent 12614See the definition and documentation in file @file{s-maccod.ads}. 12615 12616@sp 1 12617@cartouche 12618@noindent 12619@strong{52}. The effect of unchecked conversion. See 13.9(11). 12620@end cartouche 12621@noindent 12622Unchecked conversion between types of the same size 12623results in an uninterpreted transmission of the bits from one type 12624to the other. If the types are of unequal sizes, then in the case of 12625discrete types, a shorter source is first zero or sign extended as 12626necessary, and a shorter target is simply truncated on the left. 12627For all non-discrete types, the source is first copied if necessary 12628to ensure that the alignment requirements of the target are met, then 12629a pointer is constructed to the source value, and the result is obtained 12630by dereferencing this pointer after converting it to be a pointer to the 12631target type. Unchecked conversions where the target subtype is an 12632unconstrained array are not permitted. If the target alignment is 12633greater than the source alignment, then a copy of the result is 12634made with appropriate alignment 12635 12636@sp 1 12637@cartouche 12638@noindent 12639@strong{53}. The semantics of operations on invalid representations. 12640See 13.9.2(10-11). 12641@end cartouche 12642@noindent 12643For assignments and other operations where the use of invalid values cannot 12644result in erroneous behavior, the compiler ignores the possibility of invalid 12645values. An exception is raised at the point where an invalid value would 12646result in erroneous behavior. For example executing: 12647 12648@smallexample @c ada 12649procedure invalidvals is 12650 X : Integer := -1; 12651 Y : Natural range 1 .. 10; 12652 for Y'Address use X'Address; 12653 Z : Natural range 1 .. 10; 12654 A : array (Natural range 1 .. 10) of Integer; 12655begin 12656 Z := Y; -- no exception 12657 A (Z) := 3; -- exception raised; 12658end; 12659@end smallexample 12660 12661@noindent 12662As indicated, an exception is raised on the array assignment, but not 12663on the simple assignment of the invalid negative value from Y to Z. 12664 12665@sp 1 12666@cartouche 12667@noindent 12668@strong{53}. The manner of choosing a storage pool for an access type 12669when @code{Storage_Pool} is not specified for the type. See 13.11(17). 12670@end cartouche 12671@noindent 12672There are 3 different standard pools used by the compiler when 12673@code{Storage_Pool} is not specified depending whether the type is local 12674to a subprogram or defined at the library level and whether 12675@code{Storage_Size}is specified or not. See documentation in the runtime 12676library units @code{System.Pool_Global}, @code{System.Pool_Size} and 12677@code{System.Pool_Local} in files @file{s-poosiz.ads}, 12678@file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the 12679default pools used. 12680 12681@sp 1 12682@cartouche 12683@noindent 12684@strong{54}. Whether or not the implementation provides user-accessible 12685names for the standard pool type(s). See 13.11(17). 12686@end cartouche 12687@noindent 12688 12689See documentation in the sources of the run time mentioned in paragraph 12690@strong{53} . All these pools are accessible by means of @code{with}'ing 12691these units. 12692 12693@sp 1 12694@cartouche 12695@noindent 12696@strong{55}. The meaning of @code{Storage_Size}. See 13.11(18). 12697@end cartouche 12698@noindent 12699@code{Storage_Size} is measured in storage units, and refers to the 12700total space available for an access type collection, or to the primary 12701stack space for a task. 12702 12703@sp 1 12704@cartouche 12705@noindent 12706@strong{56}. Implementation-defined aspects of storage pools. See 1270713.11(22). 12708@end cartouche 12709@noindent 12710See documentation in the sources of the run time mentioned in paragraph 12711@strong{53} for details on GNAT-defined aspects of storage pools. 12712 12713@sp 1 12714@cartouche 12715@noindent 12716@strong{57}. The set of restrictions allowed in a pragma 12717@code{Restrictions}. See 13.12(7). 12718@end cartouche 12719@noindent 12720@xref{Standard and Implementation Defined Restrictions}. 12721 12722@sp 1 12723@cartouche 12724@noindent 12725@strong{58}. The consequences of violating limitations on 12726@code{Restrictions} pragmas. See 13.12(9). 12727@end cartouche 12728@noindent 12729Restrictions that can be checked at compile time result in illegalities 12730if violated. Currently there are no other consequences of violating 12731restrictions. 12732 12733@sp 1 12734@cartouche 12735@noindent 12736@strong{59}. The representation used by the @code{Read} and 12737@code{Write} attributes of elementary types in terms of stream 12738elements. See 13.13.2(9). 12739@end cartouche 12740@noindent 12741The representation is the in-memory representation of the base type of 12742the type, using the number of bits corresponding to the 12743@code{@var{type}'Size} value, and the natural ordering of the machine. 12744 12745@sp 1 12746@cartouche 12747@noindent 12748@strong{60}. The names and characteristics of the numeric subtypes 12749declared in the visible part of package @code{Standard}. See A.1(3). 12750@end cartouche 12751@noindent 12752See items describing the integer and floating-point types supported. 12753 12754@sp 1 12755@cartouche 12756@noindent 12757@strong{61}. The string returned by @code{Character_Set_Version}. 12758See A.3.5(3). 12759@end cartouche 12760@noindent 12761@code{Ada.Wide_Characters.Handling.Character_Set_Version} returns 12762the string "Unicode 4.0", referring to version 4.0 of the 12763Unicode specification. 12764 12765@sp 1 12766@cartouche 12767@noindent 12768@strong{62}. The accuracy actually achieved by the elementary 12769functions. See A.5.1(1). 12770@end cartouche 12771@noindent 12772The elementary functions correspond to the functions available in the C 12773library. Only fast math mode is implemented. 12774 12775@sp 1 12776@cartouche 12777@noindent 12778@strong{63}. The sign of a zero result from some of the operators or 12779functions in @code{Numerics.Generic_Elementary_Functions}, when 12780@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46). 12781@end cartouche 12782@noindent 12783The sign of zeroes follows the requirements of the IEEE 754 standard on 12784floating-point. 12785 12786@sp 1 12787@cartouche 12788@noindent 12789@strong{64}. The value of 12790@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27). 12791@end cartouche 12792@noindent 12793Maximum image width is 6864, see library file @file{s-rannum.ads}. 12794 12795@sp 1 12796@cartouche 12797@noindent 12798@strong{65}. The value of 12799@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27). 12800@end cartouche 12801@noindent 12802Maximum image width is 6864, see library file @file{s-rannum.ads}. 12803 12804@sp 1 12805@cartouche 12806@noindent 12807@strong{66}. The algorithms for random number generation. See 12808A.5.2(32). 12809@end cartouche 12810@noindent 12811The algorithm is the Mersenne Twister, as documented in the source file 12812@file{s-rannum.adb}. This version of the algorithm has a period of 128132**19937-1. 12814 12815@sp 1 12816@cartouche 12817@noindent 12818@strong{67}. The string representation of a random number generator's 12819state. See A.5.2(38). 12820@end cartouche 12821@noindent 12822The value returned by the Image function is the concatenation of 12823the fixed-width decimal representations of the 624 32-bit integers 12824of the state vector. 12825 12826@sp 1 12827@cartouche 12828@noindent 12829@strong{68}. The minimum time interval between calls to the 12830time-dependent Reset procedure that are guaranteed to initiate different 12831random number sequences. See A.5.2(45). 12832@end cartouche 12833@noindent 12834The minimum period between reset calls to guarantee distinct series of 12835random numbers is one microsecond. 12836 12837@sp 1 12838@cartouche 12839@noindent 12840@strong{69}. The values of the @code{Model_Mantissa}, 12841@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, 12842@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics 12843Annex is not supported. See A.5.3(72). 12844@end cartouche 12845@noindent 12846Run the compiler with @option{-gnatS} to produce a listing of package 12847@code{Standard}, has the values of all numeric attributes. 12848 12849@sp 1 12850@cartouche 12851@noindent 12852@strong{70}. Any implementation-defined characteristics of the 12853input-output packages. See A.7(14). 12854@end cartouche 12855@noindent 12856There are no special implementation defined characteristics for these 12857packages. 12858 12859@sp 1 12860@cartouche 12861@noindent 12862@strong{71}. The value of @code{Buffer_Size} in @code{Storage_IO}. See 12863A.9(10). 12864@end cartouche 12865@noindent 12866All type representations are contiguous, and the @code{Buffer_Size} is 12867the value of @code{@var{type}'Size} rounded up to the next storage unit 12868boundary. 12869 12870@sp 1 12871@cartouche 12872@noindent 12873@strong{72}. External files for standard input, standard output, and 12874standard error See A.10(5). 12875@end cartouche 12876@noindent 12877These files are mapped onto the files provided by the C streams 12878libraries. See source file @file{i-cstrea.ads} for further details. 12879 12880@sp 1 12881@cartouche 12882@noindent 12883@strong{73}. The accuracy of the value produced by @code{Put}. See 12884A.10.9(36). 12885@end cartouche 12886@noindent 12887If more digits are requested in the output than are represented by the 12888precision of the value, zeroes are output in the corresponding least 12889significant digit positions. 12890 12891@sp 1 12892@cartouche 12893@noindent 12894@strong{74}. The meaning of @code{Argument_Count}, @code{Argument}, and 12895@code{Command_Name}. See A.15(1). 12896@end cartouche 12897@noindent 12898These are mapped onto the @code{argv} and @code{argc} parameters of the 12899main program in the natural manner. 12900 12901@sp 1 12902@cartouche 12903@noindent 12904@strong{75}. The interpretation of the @code{Form} parameter in procedure 12905@code{Create_Directory}. See A.16(56). 12906@end cartouche 12907@noindent 12908The @code{Form} parameter is not used. 12909 12910@sp 1 12911@cartouche 12912@noindent 12913@strong{76}. The interpretation of the @code{Form} parameter in procedure 12914@code{Create_Path}. See A.16(60). 12915@end cartouche 12916@noindent 12917The @code{Form} parameter is not used. 12918 12919@sp 1 12920@cartouche 12921@noindent 12922@strong{77}. The interpretation of the @code{Form} parameter in procedure 12923@code{Copy_File}. See A.16(68). 12924@end cartouche 12925@noindent 12926The @code{Form} parameter is case-insensitive. 12927 12928Two fields are recognized in the @code{Form} parameter: 12929 12930@table @code 12931 12932@item preserve=<value> 12933 12934@item mode=<value> 12935 12936@end table 12937 12938@noindent 12939<value> starts immediately after the character '=' and ends with the 12940character immediately preceding the next comma (',') or with the last 12941character of the parameter. 12942 12943The only possible values for preserve= are: 12944 12945@table @code 12946 12947@item no_attributes 12948Do not try to preserve any file attributes. This is the default if no 12949preserve= is found in Form. 12950 12951@item all_attributes 12952Try to preserve all file attributes (timestamps, access rights). 12953 12954@item timestamps 12955Preserve the timestamp of the copied file, but not the other file attributes. 12956 12957@end table 12958 12959@noindent 12960The only possible values for mode= are: 12961 12962@table @code 12963 12964@item copy 12965Only do the copy if the destination file does not already exist. If it already 12966exists, Copy_File fails. 12967 12968@item overwrite 12969Copy the file in all cases. Overwrite an already existing destination file. 12970 12971@item append 12972Append the original file to the destination file. If the destination file does 12973not exist, the destination file is a copy of the source file. When mode=append, 12974the field preserve=, if it exists, is not taken into account. 12975 12976@end table 12977 12978@noindent 12979If the Form parameter includes one or both of the fields and the value or 12980values are incorrect, Copy_file fails with Use_Error. 12981 12982Examples of correct Forms: 12983 12984@smallexample 12985Form => "preserve=no_attributes,mode=overwrite" (the default) 12986Form => "mode=append" 12987Form => "mode=copy, preserve=all_attributes" 12988@end smallexample 12989 12990@noindent 12991Examples of incorrect Forms 12992 12993@smallexample 12994Form => "preserve=junk" 12995Form => "mode=internal, preserve=timestamps" 12996@end smallexample 12997 12998@sp 1 12999@cartouche 13000@noindent 13001@strong{78}. Implementation-defined convention names. See B.1(11). 13002@end cartouche 13003@noindent 13004The following convention names are supported 13005 13006@table @code 13007@item Ada 13008Ada 13009@item Ada_Pass_By_Copy 13010Allowed for any types except by-reference types such as limited 13011records. Compatible with convention Ada, but causes any parameters 13012with this convention to be passed by copy. 13013@item Ada_Pass_By_Reference 13014Allowed for any types except by-copy types such as scalars. 13015Compatible with convention Ada, but causes any parameters 13016with this convention to be passed by reference. 13017@item Assembler 13018Assembly language 13019@item Asm 13020Synonym for Assembler 13021@item Assembly 13022Synonym for Assembler 13023@item C 13024C 13025@item C_Pass_By_Copy 13026Allowed only for record types, like C, but also notes that record 13027is to be passed by copy rather than reference. 13028@item COBOL 13029COBOL 13030@item C_Plus_Plus (or CPP) 13031C++ 13032@item Default 13033Treated the same as C 13034@item External 13035Treated the same as C 13036@item Fortran 13037Fortran 13038@item Intrinsic 13039For support of pragma @code{Import} with convention Intrinsic, see 13040separate section on Intrinsic Subprograms. 13041@item Stdcall 13042Stdcall (used for Windows implementations only). This convention correspond 13043to the WINAPI (previously called Pascal convention) C/C++ convention under 13044Windows. A routine with this convention cleans the stack before 13045exit. This pragma cannot be applied to a dispatching call. 13046@item DLL 13047Synonym for Stdcall 13048@item Win32 13049Synonym for Stdcall 13050@item Stubbed 13051Stubbed is a special convention used to indicate that the body of the 13052subprogram will be entirely ignored. Any call to the subprogram 13053is converted into a raise of the @code{Program_Error} exception. If a 13054pragma @code{Import} specifies convention @code{stubbed} then no body need 13055be present at all. This convention is useful during development for the 13056inclusion of subprograms whose body has not yet been written. 13057 13058@end table 13059@noindent 13060In addition, all otherwise unrecognized convention names are also 13061treated as being synonymous with convention C@. In all implementations 13062except for VMS, use of such other names results in a warning. In VMS 13063implementations, these names are accepted silently. 13064 13065@sp 1 13066@cartouche 13067@noindent 13068@strong{79}. The meaning of link names. See B.1(36). 13069@end cartouche 13070@noindent 13071Link names are the actual names used by the linker. 13072 13073@sp 1 13074@cartouche 13075@noindent 13076@strong{80}. The manner of choosing link names when neither the link 13077name nor the address of an imported or exported entity is specified. See 13078B.1(36). 13079@end cartouche 13080@noindent 13081The default linker name is that which would be assigned by the relevant 13082external language, interpreting the Ada name as being in all lower case 13083letters. 13084 13085@sp 1 13086@cartouche 13087@noindent 13088@strong{81}. The effect of pragma @code{Linker_Options}. See B.1(37). 13089@end cartouche 13090@noindent 13091The string passed to @code{Linker_Options} is presented uninterpreted as 13092an argument to the link command, unless it contains ASCII.NUL characters. 13093NUL characters if they appear act as argument separators, so for example 13094 13095@smallexample @c ada 13096pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); 13097@end smallexample 13098 13099@noindent 13100causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the 13101linker. The order of linker options is preserved for a given unit. The final 13102list of options passed to the linker is in reverse order of the elaboration 13103order. For example, linker options for a body always appear before the options 13104from the corresponding package spec. 13105 13106@sp 1 13107@cartouche 13108@noindent 13109@strong{82}. The contents of the visible part of package 13110@code{Interfaces} and its language-defined descendants. See B.2(1). 13111@end cartouche 13112@noindent 13113See files with prefix @file{i-} in the distributed library. 13114 13115@sp 1 13116@cartouche 13117@noindent 13118@strong{83}. Implementation-defined children of package 13119@code{Interfaces}. The contents of the visible part of package 13120@code{Interfaces}. See B.2(11). 13121@end cartouche 13122@noindent 13123See files with prefix @file{i-} in the distributed library. 13124 13125@sp 1 13126@cartouche 13127@noindent 13128@strong{84}. The types @code{Floating}, @code{Long_Floating}, 13129@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and 13130@code{COBOL_Character}; and the initialization of the variables 13131@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in 13132@code{Interfaces.COBOL}. See B.4(50). 13133@end cartouche 13134@noindent 13135@table @code 13136@item Floating 13137Float 13138@item Long_Floating 13139(Floating) Long_Float 13140@item Binary 13141Integer 13142@item Long_Binary 13143Long_Long_Integer 13144@item Decimal_Element 13145Character 13146@item COBOL_Character 13147Character 13148@end table 13149 13150@noindent 13151For initialization, see the file @file{i-cobol.ads} in the distributed library. 13152 13153@sp 1 13154@cartouche 13155@noindent 13156@strong{85}. Support for access to machine instructions. See C.1(1). 13157@end cartouche 13158@noindent 13159See documentation in file @file{s-maccod.ads} in the distributed library. 13160 13161@sp 1 13162@cartouche 13163@noindent 13164@strong{86}. Implementation-defined aspects of access to machine 13165operations. See C.1(9). 13166@end cartouche 13167@noindent 13168See documentation in file @file{s-maccod.ads} in the distributed library. 13169 13170@sp 1 13171@cartouche 13172@noindent 13173@strong{87}. Implementation-defined aspects of interrupts. See C.3(2). 13174@end cartouche 13175@noindent 13176Interrupts are mapped to signals or conditions as appropriate. See 13177definition of unit 13178@code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details 13179on the interrupts supported on a particular target. 13180 13181@sp 1 13182@cartouche 13183@noindent 13184@strong{88}. Implementation-defined aspects of pre-elaboration. See 13185C.4(13). 13186@end cartouche 13187@noindent 13188GNAT does not permit a partition to be restarted without reloading, 13189except under control of the debugger. 13190 13191@sp 1 13192@cartouche 13193@noindent 13194@strong{89}. The semantics of pragma @code{Discard_Names}. See C.5(7). 13195@end cartouche 13196@noindent 13197Pragma @code{Discard_Names} causes names of enumeration literals to 13198be suppressed. In the presence of this pragma, the Image attribute 13199provides the image of the Pos of the literal, and Value accepts 13200Pos values. 13201 13202@sp 1 13203@cartouche 13204@noindent 13205@strong{90}. The result of the @code{Task_Identification.Image} 13206attribute. See C.7.1(7). 13207@end cartouche 13208@noindent 13209The result of this attribute is a string that identifies 13210the object or component that denotes a given task. If a variable @code{Var} 13211has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}}, 13212where the suffix 13213is the hexadecimal representation of the virtual address of the corresponding 13214task control block. If the variable is an array of tasks, the image of each 13215task will have the form of an indexed component indicating the position of a 13216given task in the array, e.g.@: @code{Group(5)_@var{XXXXXXX}}. If the task is a 13217component of a record, the image of the task will have the form of a selected 13218component. These rules are fully recursive, so that the image of a task that 13219is a subcomponent of a composite object corresponds to the expression that 13220designates this task. 13221@noindent 13222If a task is created by an allocator, its image depends on the context. If the 13223allocator is part of an object declaration, the rules described above are used 13224to construct its image, and this image is not affected by subsequent 13225assignments. If the allocator appears within an expression, the image 13226includes only the name of the task type. 13227@noindent 13228If the configuration pragma Discard_Names is present, or if the restriction 13229No_Implicit_Heap_Allocation is in effect, the image reduces to 13230the numeric suffix, that is to say the hexadecimal representation of the 13231virtual address of the control block of the task. 13232@sp 1 13233@cartouche 13234@noindent 13235@strong{91}. The value of @code{Current_Task} when in a protected entry 13236or interrupt handler. See C.7.1(17). 13237@end cartouche 13238@noindent 13239Protected entries or interrupt handlers can be executed by any 13240convenient thread, so the value of @code{Current_Task} is undefined. 13241 13242@sp 1 13243@cartouche 13244@noindent 13245@strong{92}. The effect of calling @code{Current_Task} from an entry 13246body or interrupt handler. See C.7.1(19). 13247@end cartouche 13248@noindent 13249The effect of calling @code{Current_Task} from an entry body or 13250interrupt handler is to return the identification of the task currently 13251executing the code. 13252 13253@sp 1 13254@cartouche 13255@noindent 13256@strong{93}. Implementation-defined aspects of 13257@code{Task_Attributes}. See C.7.2(19). 13258@end cartouche 13259@noindent 13260There are no implementation-defined aspects of @code{Task_Attributes}. 13261 13262@sp 1 13263@cartouche 13264@noindent 13265@strong{94}. Values of all @code{Metrics}. See D(2). 13266@end cartouche 13267@noindent 13268The metrics information for GNAT depends on the performance of the 13269underlying operating system. The sources of the run-time for tasking 13270implementation, together with the output from @option{-gnatG} can be 13271used to determine the exact sequence of operating systems calls made 13272to implement various tasking constructs. Together with appropriate 13273information on the performance of the underlying operating system, 13274on the exact target in use, this information can be used to determine 13275the required metrics. 13276 13277@sp 1 13278@cartouche 13279@noindent 13280@strong{95}. The declarations of @code{Any_Priority} and 13281@code{Priority}. See D.1(11). 13282@end cartouche 13283@noindent 13284See declarations in file @file{system.ads}. 13285 13286@sp 1 13287@cartouche 13288@noindent 13289@strong{96}. Implementation-defined execution resources. See D.1(15). 13290@end cartouche 13291@noindent 13292There are no implementation-defined execution resources. 13293 13294@sp 1 13295@cartouche 13296@noindent 13297@strong{97}. Whether, on a multiprocessor, a task that is waiting for 13298access to a protected object keeps its processor busy. See D.2.1(3). 13299@end cartouche 13300@noindent 13301On a multi-processor, a task that is waiting for access to a protected 13302object does not keep its processor busy. 13303 13304@sp 1 13305@cartouche 13306@noindent 13307@strong{98}. The affect of implementation defined execution resources 13308on task dispatching. See D.2.1(9). 13309@end cartouche 13310@noindent 13311Tasks map to threads in the threads package used by GNAT@. Where possible 13312and appropriate, these threads correspond to native threads of the 13313underlying operating system. 13314 13315@sp 1 13316@cartouche 13317@noindent 13318@strong{99}. Implementation-defined @code{policy_identifiers} allowed 13319in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3). 13320@end cartouche 13321@noindent 13322There are no implementation-defined policy-identifiers allowed in this 13323pragma. 13324 13325@sp 1 13326@cartouche 13327@noindent 13328@strong{100}. Implementation-defined aspects of priority inversion. See 13329D.2.2(16). 13330@end cartouche 13331@noindent 13332Execution of a task cannot be preempted by the implementation processing 13333of delay expirations for lower priority tasks. 13334 13335@sp 1 13336@cartouche 13337@noindent 13338@strong{101}. Implementation-defined task dispatching. See D.2.2(18). 13339@end cartouche 13340@noindent 13341The policy is the same as that of the underlying threads implementation. 13342 13343@sp 1 13344@cartouche 13345@noindent 13346@strong{102}. Implementation-defined @code{policy_identifiers} allowed 13347in a pragma @code{Locking_Policy}. See D.3(4). 13348@end cartouche 13349@noindent 13350The two implementation defined policies permitted in GNAT are 13351@code{Inheritance_Locking} and @code{Conccurent_Readers_Locking}. On 13352targets that support the @code{Inheritance_Locking} policy, locking is 13353implemented by inheritance, i.e.@: the task owning the lock operates 13354at a priority equal to the highest priority of any task currently 13355requesting the lock. On targets that support the 13356@code{Conccurent_Readers_Locking} policy, locking is implemented with a 13357read/write lock allowing multiple propected object functions to enter 13358concurrently. 13359 13360@sp 1 13361@cartouche 13362@noindent 13363@strong{103}. Default ceiling priorities. See D.3(10). 13364@end cartouche 13365@noindent 13366The ceiling priority of protected objects of the type 13367@code{System.Interrupt_Priority'Last} as described in the Ada 13368Reference Manual D.3(10), 13369 13370@sp 1 13371@cartouche 13372@noindent 13373@strong{104}. The ceiling of any protected object used internally by 13374the implementation. See D.3(16). 13375@end cartouche 13376@noindent 13377The ceiling priority of internal protected objects is 13378@code{System.Priority'Last}. 13379 13380@sp 1 13381@cartouche 13382@noindent 13383@strong{105}. Implementation-defined queuing policies. See D.4(1). 13384@end cartouche 13385@noindent 13386There are no implementation-defined queuing policies. 13387 13388@sp 1 13389@cartouche 13390@noindent 13391@strong{106}. On a multiprocessor, any conditions that cause the 13392completion of an aborted construct to be delayed later than what is 13393specified for a single processor. See D.6(3). 13394@end cartouche 13395@noindent 13396The semantics for abort on a multi-processor is the same as on a single 13397processor, there are no further delays. 13398 13399@sp 1 13400@cartouche 13401@noindent 13402@strong{107}. Any operations that implicitly require heap storage 13403allocation. See D.7(8). 13404@end cartouche 13405@noindent 13406The only operation that implicitly requires heap storage allocation is 13407task creation. 13408 13409@sp 1 13410@cartouche 13411@noindent 13412@strong{108}. Implementation-defined aspects of pragma 13413@code{Restrictions}. See D.7(20). 13414@end cartouche 13415@noindent 13416There are no such implementation-defined aspects. 13417 13418@sp 1 13419@cartouche 13420@noindent 13421@strong{109}. Implementation-defined aspects of package 13422@code{Real_Time}. See D.8(17). 13423@end cartouche 13424@noindent 13425There are no implementation defined aspects of package @code{Real_Time}. 13426 13427@sp 1 13428@cartouche 13429@noindent 13430@strong{110}. Implementation-defined aspects of 13431@code{delay_statements}. See D.9(8). 13432@end cartouche 13433@noindent 13434Any difference greater than one microsecond will cause the task to be 13435delayed (see D.9(7)). 13436 13437@sp 1 13438@cartouche 13439@noindent 13440@strong{111}. The upper bound on the duration of interrupt blocking 13441caused by the implementation. See D.12(5). 13442@end cartouche 13443@noindent 13444The upper bound is determined by the underlying operating system. In 13445no cases is it more than 10 milliseconds. 13446 13447@sp 1 13448@cartouche 13449@noindent 13450@strong{112}. The means for creating and executing distributed 13451programs. See E(5). 13452@end cartouche 13453@noindent 13454The GLADE package provides a utility GNATDIST for creating and executing 13455distributed programs. See the GLADE reference manual for further details. 13456 13457@sp 1 13458@cartouche 13459@noindent 13460@strong{113}. Any events that can result in a partition becoming 13461inaccessible. See E.1(7). 13462@end cartouche 13463@noindent 13464See the GLADE reference manual for full details on such events. 13465 13466@sp 1 13467@cartouche 13468@noindent 13469@strong{114}. The scheduling policies, treatment of priorities, and 13470management of shared resources between partitions in certain cases. See 13471E.1(11). 13472@end cartouche 13473@noindent 13474See the GLADE reference manual for full details on these aspects of 13475multi-partition execution. 13476 13477@sp 1 13478@cartouche 13479@noindent 13480@strong{115}. Events that cause the version of a compilation unit to 13481change. See E.3(5). 13482@end cartouche 13483@noindent 13484Editing the source file of a compilation unit, or the source files of 13485any units on which it is dependent in a significant way cause the version 13486to change. No other actions cause the version number to change. All changes 13487are significant except those which affect only layout, capitalization or 13488comments. 13489 13490@sp 1 13491@cartouche 13492@noindent 13493@strong{116}. Whether the execution of the remote subprogram is 13494immediately aborted as a result of cancellation. See E.4(13). 13495@end cartouche 13496@noindent 13497See the GLADE reference manual for details on the effect of abort in 13498a distributed application. 13499 13500@sp 1 13501@cartouche 13502@noindent 13503@strong{117}. Implementation-defined aspects of the PCS@. See E.5(25). 13504@end cartouche 13505@noindent 13506See the GLADE reference manual for a full description of all implementation 13507defined aspects of the PCS@. 13508 13509@sp 1 13510@cartouche 13511@noindent 13512@strong{118}. Implementation-defined interfaces in the PCS@. See 13513E.5(26). 13514@end cartouche 13515@noindent 13516See the GLADE reference manual for a full description of all 13517implementation defined interfaces. 13518 13519@sp 1 13520@cartouche 13521@noindent 13522@strong{119}. The values of named numbers in the package 13523@code{Decimal}. See F.2(7). 13524@end cartouche 13525@noindent 13526@table @code 13527@item Max_Scale 13528+18 13529@item Min_Scale 13530-18 13531@item Min_Delta 135321.0E-18 13533@item Max_Delta 135341.0E+18 13535@item Max_Decimal_Digits 1353618 13537@end table 13538 13539@sp 1 13540@cartouche 13541@noindent 13542@strong{120}. The value of @code{Max_Picture_Length} in the package 13543@code{Text_IO.Editing}. See F.3.3(16). 13544@end cartouche 13545@noindent 1354664 13547 13548@sp 1 13549@cartouche 13550@noindent 13551@strong{121}. The value of @code{Max_Picture_Length} in the package 13552@code{Wide_Text_IO.Editing}. See F.3.4(5). 13553@end cartouche 13554@noindent 1355564 13556 13557@sp 1 13558@cartouche 13559@noindent 13560@strong{122}. The accuracy actually achieved by the complex elementary 13561functions and by other complex arithmetic operations. See G.1(1). 13562@end cartouche 13563@noindent 13564Standard library functions are used for the complex arithmetic 13565operations. Only fast math mode is currently supported. 13566 13567@sp 1 13568@cartouche 13569@noindent 13570@strong{123}. The sign of a zero result (or a component thereof) from 13571any operator or function in @code{Numerics.Generic_Complex_Types}, when 13572@code{Real'Signed_Zeros} is True. See G.1.1(53). 13573@end cartouche 13574@noindent 13575The signs of zero values are as recommended by the relevant 13576implementation advice. 13577 13578@sp 1 13579@cartouche 13580@noindent 13581@strong{124}. The sign of a zero result (or a component thereof) from 13582any operator or function in 13583@code{Numerics.Generic_Complex_Elementary_Functions}, when 13584@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45). 13585@end cartouche 13586@noindent 13587The signs of zero values are as recommended by the relevant 13588implementation advice. 13589 13590@sp 1 13591@cartouche 13592@noindent 13593@strong{125}. Whether the strict mode or the relaxed mode is the 13594default. See G.2(2). 13595@end cartouche 13596@noindent 13597The strict mode is the default. There is no separate relaxed mode. GNAT 13598provides a highly efficient implementation of strict mode. 13599 13600@sp 1 13601@cartouche 13602@noindent 13603@strong{126}. The result interval in certain cases of fixed-to-float 13604conversion. See G.2.1(10). 13605@end cartouche 13606@noindent 13607For cases where the result interval is implementation dependent, the 13608accuracy is that provided by performing all operations in 64-bit IEEE 13609floating-point format. 13610 13611@sp 1 13612@cartouche 13613@noindent 13614@strong{127}. The result of a floating point arithmetic operation in 13615overflow situations, when the @code{Machine_Overflows} attribute of the 13616result type is @code{False}. See G.2.1(13). 13617@end cartouche 13618@noindent 13619Infinite and NaN values are produced as dictated by the IEEE 13620floating-point standard. 13621 13622Note that on machines that are not fully compliant with the IEEE 13623floating-point standard, such as Alpha, the @option{-mieee} compiler flag 13624must be used for achieving IEEE conforming behavior (although at the cost 13625of a significant performance penalty), so infinite and NaN values are 13626properly generated. 13627 13628@sp 1 13629@cartouche 13630@noindent 13631@strong{128}. The result interval for division (or exponentiation by a 13632negative exponent), when the floating point hardware implements division 13633as multiplication by a reciprocal. See G.2.1(16). 13634@end cartouche 13635@noindent 13636Not relevant, division is IEEE exact. 13637 13638@sp 1 13639@cartouche 13640@noindent 13641@strong{129}. The definition of close result set, which determines the 13642accuracy of certain fixed point multiplications and divisions. See 13643G.2.3(5). 13644@end cartouche 13645@noindent 13646Operations in the close result set are performed using IEEE long format 13647floating-point arithmetic. The input operands are converted to 13648floating-point, the operation is done in floating-point, and the result 13649is converted to the target type. 13650 13651@sp 1 13652@cartouche 13653@noindent 13654@strong{130}. Conditions on a @code{universal_real} operand of a fixed 13655point multiplication or division for which the result shall be in the 13656perfect result set. See G.2.3(22). 13657@end cartouche 13658@noindent 13659The result is only defined to be in the perfect result set if the result 13660can be computed by a single scaling operation involving a scale factor 13661representable in 64-bits. 13662 13663@sp 1 13664@cartouche 13665@noindent 13666@strong{131}. The result of a fixed point arithmetic operation in 13667overflow situations, when the @code{Machine_Overflows} attribute of the 13668result type is @code{False}. See G.2.3(27). 13669@end cartouche 13670@noindent 13671Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point 13672types. 13673 13674@sp 1 13675@cartouche 13676@noindent 13677@strong{132}. The result of an elementary function reference in 13678overflow situations, when the @code{Machine_Overflows} attribute of the 13679result type is @code{False}. See G.2.4(4). 13680@end cartouche 13681@noindent 13682IEEE infinite and Nan values are produced as appropriate. 13683 13684@sp 1 13685@cartouche 13686@noindent 13687@strong{133}. The value of the angle threshold, within which certain 13688elementary functions, complex arithmetic operations, and complex 13689elementary functions yield results conforming to a maximum relative 13690error bound. See G.2.4(10). 13691@end cartouche 13692@noindent 13693Information on this subject is not yet available. 13694 13695@sp 1 13696@cartouche 13697@noindent 13698@strong{134}. The accuracy of certain elementary functions for 13699parameters beyond the angle threshold. See G.2.4(10). 13700@end cartouche 13701@noindent 13702Information on this subject is not yet available. 13703 13704@sp 1 13705@cartouche 13706@noindent 13707@strong{135}. The result of a complex arithmetic operation or complex 13708elementary function reference in overflow situations, when the 13709@code{Machine_Overflows} attribute of the corresponding real type is 13710@code{False}. See G.2.6(5). 13711@end cartouche 13712@noindent 13713IEEE infinite and Nan values are produced as appropriate. 13714 13715@sp 1 13716@cartouche 13717@noindent 13718@strong{136}. The accuracy of certain complex arithmetic operations and 13719certain complex elementary functions for parameters (or components 13720thereof) beyond the angle threshold. See G.2.6(8). 13721@end cartouche 13722@noindent 13723Information on those subjects is not yet available. 13724 13725@sp 1 13726@cartouche 13727@noindent 13728@strong{137}. Information regarding bounded errors and erroneous 13729execution. See H.2(1). 13730@end cartouche 13731@noindent 13732Information on this subject is not yet available. 13733 13734@sp 1 13735@cartouche 13736@noindent 13737@strong{138}. Implementation-defined aspects of pragma 13738@code{Inspection_Point}. See H.3.2(8). 13739@end cartouche 13740@noindent 13741Pragma @code{Inspection_Point} ensures that the variable is live and can 13742be examined by the debugger at the inspection point. 13743 13744@sp 1 13745@cartouche 13746@noindent 13747@strong{139}. Implementation-defined aspects of pragma 13748@code{Restrictions}. See H.4(25). 13749@end cartouche 13750@noindent 13751There are no implementation-defined aspects of pragma @code{Restrictions}. The 13752use of pragma @code{Restrictions [No_Exceptions]} has no effect on the 13753generated code. Checks must suppressed by use of pragma @code{Suppress}. 13754 13755@sp 1 13756@cartouche 13757@noindent 13758@strong{140}. Any restrictions on pragma @code{Restrictions}. See 13759H.4(27). 13760@end cartouche 13761@noindent 13762There are no restrictions on pragma @code{Restrictions}. 13763 13764@node Intrinsic Subprograms 13765@chapter Intrinsic Subprograms 13766@cindex Intrinsic Subprograms 13767 13768@menu 13769* Intrinsic Operators:: 13770* Enclosing_Entity:: 13771* Exception_Information:: 13772* Exception_Message:: 13773* Exception_Name:: 13774* File:: 13775* Line:: 13776* Shifts and Rotates:: 13777* Source_Location:: 13778@end menu 13779 13780@noindent 13781GNAT allows a user application program to write the declaration: 13782 13783@smallexample @c ada 13784 pragma Import (Intrinsic, name); 13785@end smallexample 13786 13787@noindent 13788providing that the name corresponds to one of the implemented intrinsic 13789subprograms in GNAT, and that the parameter profile of the referenced 13790subprogram meets the requirements. This chapter describes the set of 13791implemented intrinsic subprograms, and the requirements on parameter profiles. 13792Note that no body is supplied; as with other uses of pragma Import, the 13793body is supplied elsewhere (in this case by the compiler itself). Note 13794that any use of this feature is potentially non-portable, since the 13795Ada standard does not require Ada compilers to implement this feature. 13796 13797@node Intrinsic Operators 13798@section Intrinsic Operators 13799@cindex Intrinsic operator 13800 13801@noindent 13802All the predefined numeric operators in package Standard 13803in @code{pragma Import (Intrinsic,..)} 13804declarations. In the binary operator case, the operands must have the same 13805size. The operand or operands must also be appropriate for 13806the operator. For example, for addition, the operands must 13807both be floating-point or both be fixed-point, and the 13808right operand for @code{"**"} must have a root type of 13809@code{Standard.Integer'Base}. 13810You can use an intrinsic operator declaration as in the following example: 13811 13812@smallexample @c ada 13813 type Int1 is new Integer; 13814 type Int2 is new Integer; 13815 13816 function "+" (X1 : Int1; X2 : Int2) return Int1; 13817 function "+" (X1 : Int1; X2 : Int2) return Int2; 13818 pragma Import (Intrinsic, "+"); 13819@end smallexample 13820 13821@noindent 13822This declaration would permit ``mixed mode'' arithmetic on items 13823of the differing types @code{Int1} and @code{Int2}. 13824It is also possible to specify such operators for private types, if the 13825full views are appropriate arithmetic types. 13826 13827@node Enclosing_Entity 13828@section Enclosing_Entity 13829@cindex Enclosing_Entity 13830@noindent 13831This intrinsic subprogram is used in the implementation of the 13832library routine @code{GNAT.Source_Info}. The only useful use of the 13833intrinsic import in this case is the one in this unit, so an 13834application program should simply call the function 13835@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 13836the current subprogram, package, task, entry, or protected subprogram. 13837 13838@node Exception_Information 13839@section Exception_Information 13840@cindex Exception_Information' 13841@noindent 13842This intrinsic subprogram is used in the implementation of the 13843library routine @code{GNAT.Current_Exception}. The only useful 13844use of the intrinsic import in this case is the one in this unit, 13845so an application program should simply call the function 13846@code{GNAT.Current_Exception.Exception_Information} to obtain 13847the exception information associated with the current exception. 13848 13849@node Exception_Message 13850@section Exception_Message 13851@cindex Exception_Message 13852@noindent 13853This intrinsic subprogram is used in the implementation of the 13854library routine @code{GNAT.Current_Exception}. The only useful 13855use of the intrinsic import in this case is the one in this unit, 13856so an application program should simply call the function 13857@code{GNAT.Current_Exception.Exception_Message} to obtain 13858the message associated with the current exception. 13859 13860@node Exception_Name 13861@section Exception_Name 13862@cindex Exception_Name 13863@noindent 13864This intrinsic subprogram is used in the implementation of the 13865library routine @code{GNAT.Current_Exception}. The only useful 13866use of the intrinsic import in this case is the one in this unit, 13867so an application program should simply call the function 13868@code{GNAT.Current_Exception.Exception_Name} to obtain 13869the name of the current exception. 13870 13871@node File 13872@section File 13873@cindex File 13874@noindent 13875This intrinsic subprogram is used in the implementation of the 13876library routine @code{GNAT.Source_Info}. The only useful use of the 13877intrinsic import in this case is the one in this unit, so an 13878application program should simply call the function 13879@code{GNAT.Source_Info.File} to obtain the name of the current 13880file. 13881 13882@node Line 13883@section Line 13884@cindex Line 13885@noindent 13886This intrinsic subprogram is used in the implementation of the 13887library routine @code{GNAT.Source_Info}. The only useful use of the 13888intrinsic import in this case is the one in this unit, so an 13889application program should simply call the function 13890@code{GNAT.Source_Info.Line} to obtain the number of the current 13891source line. 13892 13893@node Shifts and Rotates 13894@section Shifts and Rotates 13895@cindex Shift_Left 13896@cindex Shift_Right 13897@cindex Shift_Right_Arithmetic 13898@cindex Rotate_Left 13899@cindex Rotate_Right 13900@noindent 13901In standard Ada, the shift and rotate functions are available only 13902for the predefined modular types in package @code{Interfaces}. However, in 13903GNAT it is possible to define these functions for any integer 13904type (signed or modular), as in this example: 13905 13906@smallexample @c ada 13907 function Shift_Left 13908 (Value : T; 13909 Amount : Natural) return T; 13910@end smallexample 13911 13912@noindent 13913The function name must be one of 13914Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or 13915Rotate_Right. T must be an integer type. T'Size must be 139168, 16, 32 or 64 bits; if T is modular, the modulus 13917must be 2**8, 2**16, 2**32 or 2**64. 13918The result type must be the same as the type of @code{Value}. 13919The shift amount must be Natural. 13920The formal parameter names can be anything. 13921 13922A more convenient way of providing these shift operators is to use 13923the Provide_Shift_Operators pragma, which provides the function declarations 13924and corresponding pragma Import's for all five shift functions. 13925 13926@node Source_Location 13927@section Source_Location 13928@cindex Source_Location 13929@noindent 13930This intrinsic subprogram is used in the implementation of the 13931library routine @code{GNAT.Source_Info}. The only useful use of the 13932intrinsic import in this case is the one in this unit, so an 13933application program should simply call the function 13934@code{GNAT.Source_Info.Source_Location} to obtain the current 13935source file location. 13936 13937@node Representation Clauses and Pragmas 13938@chapter Representation Clauses and Pragmas 13939@cindex Representation Clauses 13940 13941@menu 13942* Alignment Clauses:: 13943* Size Clauses:: 13944* Storage_Size Clauses:: 13945* Size of Variant Record Objects:: 13946* Biased Representation :: 13947* Value_Size and Object_Size Clauses:: 13948* Component_Size Clauses:: 13949* Bit_Order Clauses:: 13950* Effect of Bit_Order on Byte Ordering:: 13951* Pragma Pack for Arrays:: 13952* Pragma Pack for Records:: 13953* Record Representation Clauses:: 13954* Handling of Records with Holes:: 13955* Enumeration Clauses:: 13956* Address Clauses:: 13957* Effect of Convention on Representation:: 13958* Conventions and Anonymous Access Types:: 13959* Determining the Representations chosen by GNAT:: 13960@end menu 13961 13962@noindent 13963@cindex Representation Clause 13964@cindex Representation Pragma 13965@cindex Pragma, representation 13966This section describes the representation clauses accepted by GNAT, and 13967their effect on the representation of corresponding data objects. 13968 13969GNAT fully implements Annex C (Systems Programming). This means that all 13970the implementation advice sections in chapter 13 are fully implemented. 13971However, these sections only require a minimal level of support for 13972representation clauses. GNAT provides much more extensive capabilities, 13973and this section describes the additional capabilities provided. 13974 13975@node Alignment Clauses 13976@section Alignment Clauses 13977@cindex Alignment Clause 13978 13979@noindent 13980GNAT requires that all alignment clauses specify a power of 2, and all 13981default alignments are always a power of 2. The default alignment 13982values are as follows: 13983 13984@itemize @bullet 13985@item @emph{Primitive Types}. 13986For primitive types, the alignment is the minimum of the actual size of 13987objects of the type divided by @code{Storage_Unit}, 13988and the maximum alignment supported by the target. 13989(This maximum alignment is given by the GNAT-specific attribute 13990@code{Standard'Maximum_Alignment}; see @ref{Attribute Maximum_Alignment}.) 13991@cindex @code{Maximum_Alignment} attribute 13992For example, for type @code{Long_Float}, the object size is 8 bytes, and the 13993default alignment will be 8 on any target that supports alignments 13994this large, but on some targets, the maximum alignment may be smaller 13995than 8, in which case objects of type @code{Long_Float} will be maximally 13996aligned. 13997 13998@item @emph{Arrays}. 13999For arrays, the alignment is equal to the alignment of the component type 14000for the normal case where no packing or component size is given. If the 14001array is packed, and the packing is effective (see separate section on 14002packed arrays), then the alignment will be one for long packed arrays, 14003or arrays whose length is not known at compile time. For short packed 14004arrays, which are handled internally as modular types, the alignment 14005will be as described for primitive types, e.g.@: a packed array of length 1400631 bits will have an object size of four bytes, and an alignment of 4. 14007 14008@item @emph{Records}. 14009For the normal non-packed case, the alignment of a record is equal to 14010the maximum alignment of any of its components. For tagged records, this 14011includes the implicit access type used for the tag. If a pragma @code{Pack} 14012is used and all components are packable (see separate section on pragma 14013@code{Pack}), then the resulting alignment is 1, unless the layout of the 14014record makes it profitable to increase it. 14015 14016A special case is when: 14017@itemize @bullet 14018@item 14019the size of the record is given explicitly, or a 14020full record representation clause is given, and 14021@item 14022the size of the record is 2, 4, or 8 bytes. 14023@end itemize 14024@noindent 14025In this case, an alignment is chosen to match the 14026size of the record. For example, if we have: 14027 14028@smallexample @c ada 14029 type Small is record 14030 A, B : Character; 14031 end record; 14032 for Small'Size use 16; 14033@end smallexample 14034 14035@noindent 14036then the default alignment of the record type @code{Small} is 2, not 1. This 14037leads to more efficient code when the record is treated as a unit, and also 14038allows the type to specified as @code{Atomic} on architectures requiring 14039strict alignment. 14040 14041@end itemize 14042 14043@noindent 14044An alignment clause may specify a larger alignment than the default value 14045up to some maximum value dependent on the target (obtainable by using the 14046attribute reference @code{Standard'Maximum_Alignment}). It may also specify 14047a smaller alignment than the default value for enumeration, integer and 14048fixed point types, as well as for record types, for example 14049 14050@smallexample @c ada 14051 type V is record 14052 A : Integer; 14053 end record; 14054 14055 for V'alignment use 1; 14056@end smallexample 14057 14058@noindent 14059@cindex Alignment, default 14060The default alignment for the type @code{V} is 4, as a result of the 14061Integer field in the record, but it is permissible, as shown, to 14062override the default alignment of the record with a smaller value. 14063 14064@cindex Alignment, subtypes 14065Note that according to the Ada standard, an alignment clause applies only 14066to the first named subtype. If additional subtypes are declared, then the 14067compiler is allowed to choose any alignment it likes, and there is no way 14068to control this choice. Consider: 14069 14070@smallexample @c ada 14071 type R is range 1 .. 10_000; 14072 for R'Alignment use 1; 14073 subtype RS is R range 1 .. 1000; 14074@end smallexample 14075 14076@noindent 14077The alignment clause specifies an alignment of 1 for the first named subtype 14078@code{R} but this does not necessarily apply to @code{RS}. When writing 14079portable Ada code, you should avoid writing code that explicitly or 14080implicitly relies on the alignment of such subtypes. 14081 14082For the GNAT compiler, if an explicit alignment clause is given, this 14083value is also used for any subsequent subtypes. So for GNAT, in the 14084above example, you can count on the alignment of @code{RS} being 1. But this 14085assumption is non-portable, and other compilers may choose different 14086alignments for the subtype @code{RS}. 14087 14088@node Size Clauses 14089@section Size Clauses 14090@cindex Size Clause 14091 14092@noindent 14093The default size for a type @code{T} is obtainable through the 14094language-defined attribute @code{T'Size} and also through the 14095equivalent GNAT-defined attribute @code{T'Value_Size}. 14096For objects of type @code{T}, GNAT will generally increase the type size 14097so that the object size (obtainable through the GNAT-defined attribute 14098@code{T'Object_Size}) 14099is a multiple of @code{T'Alignment * Storage_Unit}. 14100For example 14101 14102@smallexample @c ada 14103 type Smallint is range 1 .. 6; 14104 14105 type Rec is record 14106 Y1 : integer; 14107 Y2 : boolean; 14108 end record; 14109@end smallexample 14110 14111@noindent 14112In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, 14113as specified by the RM rules, 14114but objects of this type will have a size of 8 14115(@code{Smallint'Object_Size} = 8), 14116since objects by default occupy an integral number 14117of storage units. On some targets, notably older 14118versions of the Digital Alpha, the size of stand 14119alone objects of this type may be 32, reflecting 14120the inability of the hardware to do byte load/stores. 14121 14122Similarly, the size of type @code{Rec} is 40 bits 14123(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but 14124the alignment is 4, so objects of this type will have 14125their size increased to 64 bits so that it is a multiple 14126of the alignment (in bits). This decision is 14127in accordance with the specific Implementation Advice in RM 13.3(43): 14128 14129@quotation 14130A @code{Size} clause should be supported for an object if the specified 14131@code{Size} is at least as large as its subtype's @code{Size}, and corresponds 14132to a size in storage elements that is a multiple of the object's 14133@code{Alignment} (if the @code{Alignment} is nonzero). 14134@end quotation 14135 14136@noindent 14137An explicit size clause may be used to override the default size by 14138increasing it. For example, if we have: 14139 14140@smallexample @c ada 14141 type My_Boolean is new Boolean; 14142 for My_Boolean'Size use 32; 14143@end smallexample 14144 14145@noindent 14146then values of this type will always be 32 bits long. In the case of 14147discrete types, the size can be increased up to 64 bits, with the effect 14148that the entire specified field is used to hold the value, sign- or 14149zero-extended as appropriate. If more than 64 bits is specified, then 14150padding space is allocated after the value, and a warning is issued that 14151there are unused bits. 14152 14153Similarly the size of records and arrays may be increased, and the effect 14154is to add padding bits after the value. This also causes a warning message 14155to be generated. 14156 14157The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a 14158Size in bits, this corresponds to an object of size 256 megabytes (minus 14159one). This limitation is true on all targets. The reason for this 14160limitation is that it improves the quality of the code in many cases 14161if it is known that a Size value can be accommodated in an object of 14162type Integer. 14163 14164@node Storage_Size Clauses 14165@section Storage_Size Clauses 14166@cindex Storage_Size Clause 14167 14168@noindent 14169For tasks, the @code{Storage_Size} clause specifies the amount of space 14170to be allocated for the task stack. This cannot be extended, and if the 14171stack is exhausted, then @code{Storage_Error} will be raised (if stack 14172checking is enabled). Use a @code{Storage_Size} attribute definition clause, 14173or a @code{Storage_Size} pragma in the task definition to set the 14174appropriate required size. A useful technique is to include in every 14175task definition a pragma of the form: 14176 14177@smallexample @c ada 14178 pragma Storage_Size (Default_Stack_Size); 14179@end smallexample 14180 14181@noindent 14182Then @code{Default_Stack_Size} can be defined in a global package, and 14183modified as required. Any tasks requiring stack sizes different from the 14184default can have an appropriate alternative reference in the pragma. 14185 14186You can also use the @option{-d} binder switch to modify the default stack 14187size. 14188 14189For access types, the @code{Storage_Size} clause specifies the maximum 14190space available for allocation of objects of the type. If this space is 14191exceeded then @code{Storage_Error} will be raised by an allocation attempt. 14192In the case where the access type is declared local to a subprogram, the 14193use of a @code{Storage_Size} clause triggers automatic use of a special 14194predefined storage pool (@code{System.Pool_Size}) that ensures that all 14195space for the pool is automatically reclaimed on exit from the scope in 14196which the type is declared. 14197 14198A special case recognized by the compiler is the specification of a 14199@code{Storage_Size} of zero for an access type. This means that no 14200items can be allocated from the pool, and this is recognized at compile 14201time, and all the overhead normally associated with maintaining a fixed 14202size storage pool is eliminated. Consider the following example: 14203 14204@smallexample @c ada 14205 procedure p is 14206 type R is array (Natural) of Character; 14207 type P is access all R; 14208 for P'Storage_Size use 0; 14209 -- Above access type intended only for interfacing purposes 14210 14211 y : P; 14212 14213 procedure g (m : P); 14214 pragma Import (C, g); 14215 14216 -- @dots{} 14217 14218 begin 14219 -- @dots{} 14220 y := new R; 14221 end; 14222@end smallexample 14223 14224@noindent 14225As indicated in this example, these dummy storage pools are often useful in 14226connection with interfacing where no object will ever be allocated. If you 14227compile the above example, you get the warning: 14228 14229@smallexample 14230 p.adb:16:09: warning: allocation from empty storage pool 14231 p.adb:16:09: warning: Storage_Error will be raised at run time 14232@end smallexample 14233 14234@noindent 14235Of course in practice, there will not be any explicit allocators in the 14236case of such an access declaration. 14237 14238@node Size of Variant Record Objects 14239@section Size of Variant Record Objects 14240@cindex Size, variant record objects 14241@cindex Variant record objects, size 14242 14243@noindent 14244In the case of variant record objects, there is a question whether Size gives 14245information about a particular variant, or the maximum size required 14246for any variant. Consider the following program 14247 14248@smallexample @c ada 14249with Text_IO; use Text_IO; 14250procedure q is 14251 type R1 (A : Boolean := False) is record 14252 case A is 14253 when True => X : Character; 14254 when False => null; 14255 end case; 14256 end record; 14257 14258 V1 : R1 (False); 14259 V2 : R1; 14260 14261begin 14262 Put_Line (Integer'Image (V1'Size)); 14263 Put_Line (Integer'Image (V2'Size)); 14264end q; 14265@end smallexample 14266 14267@noindent 14268Here we are dealing with a variant record, where the True variant 14269requires 16 bits, and the False variant requires 8 bits. 14270In the above example, both V1 and V2 contain the False variant, 14271which is only 8 bits long. However, the result of running the 14272program is: 14273 14274@smallexample 142758 1427616 14277@end smallexample 14278 14279@noindent 14280The reason for the difference here is that the discriminant value of 14281V1 is fixed, and will always be False. It is not possible to assign 14282a True variant value to V1, therefore 8 bits is sufficient. On the 14283other hand, in the case of V2, the initial discriminant value is 14284False (from the default), but it is possible to assign a True 14285variant value to V2, therefore 16 bits must be allocated for V2 14286in the general case, even fewer bits may be needed at any particular 14287point during the program execution. 14288 14289As can be seen from the output of this program, the @code{'Size} 14290attribute applied to such an object in GNAT gives the actual allocated 14291size of the variable, which is the largest size of any of the variants. 14292The Ada Reference Manual is not completely clear on what choice should 14293be made here, but the GNAT behavior seems most consistent with the 14294language in the RM@. 14295 14296In some cases, it may be desirable to obtain the size of the current 14297variant, rather than the size of the largest variant. This can be 14298achieved in GNAT by making use of the fact that in the case of a 14299subprogram parameter, GNAT does indeed return the size of the current 14300variant (because a subprogram has no way of knowing how much space 14301is actually allocated for the actual). 14302 14303Consider the following modified version of the above program: 14304 14305@smallexample @c ada 14306with Text_IO; use Text_IO; 14307procedure q is 14308 type R1 (A : Boolean := False) is record 14309 case A is 14310 when True => X : Character; 14311 when False => null; 14312 end case; 14313 end record; 14314 14315 V2 : R1; 14316 14317 function Size (V : R1) return Integer is 14318 begin 14319 return V'Size; 14320 end Size; 14321 14322begin 14323 Put_Line (Integer'Image (V2'Size)); 14324 Put_Line (Integer'IMage (Size (V2))); 14325 V2 := (True, 'x'); 14326 Put_Line (Integer'Image (V2'Size)); 14327 Put_Line (Integer'IMage (Size (V2))); 14328end q; 14329@end smallexample 14330 14331@noindent 14332The output from this program is 14333 14334@smallexample 1433516 143368 1433716 1433816 14339@end smallexample 14340 14341@noindent 14342Here we see that while the @code{'Size} attribute always returns 14343the maximum size, regardless of the current variant value, the 14344@code{Size} function does indeed return the size of the current 14345variant value. 14346 14347@node Biased Representation 14348@section Biased Representation 14349@cindex Size for biased representation 14350@cindex Biased representation 14351 14352@noindent 14353In the case of scalars with a range starting at other than zero, it is 14354possible in some cases to specify a size smaller than the default minimum 14355value, and in such cases, GNAT uses an unsigned biased representation, 14356in which zero is used to represent the lower bound, and successive values 14357represent successive values of the type. 14358 14359For example, suppose we have the declaration: 14360 14361@smallexample @c ada 14362 type Small is range -7 .. -4; 14363 for Small'Size use 2; 14364@end smallexample 14365 14366@noindent 14367Although the default size of type @code{Small} is 4, the @code{Size} 14368clause is accepted by GNAT and results in the following representation 14369scheme: 14370 14371@smallexample 14372 -7 is represented as 2#00# 14373 -6 is represented as 2#01# 14374 -5 is represented as 2#10# 14375 -4 is represented as 2#11# 14376@end smallexample 14377 14378@noindent 14379Biased representation is only used if the specified @code{Size} clause 14380cannot be accepted in any other manner. These reduced sizes that force 14381biased representation can be used for all discrete types except for 14382enumeration types for which a representation clause is given. 14383 14384@node Value_Size and Object_Size Clauses 14385@section Value_Size and Object_Size Clauses 14386@findex Value_Size 14387@findex Object_Size 14388@cindex Size, of objects 14389 14390@noindent 14391In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum 14392number of bits required to hold values of type @code{T}. 14393Although this interpretation was allowed in Ada 83, it was not required, 14394and this requirement in practice can cause some significant difficulties. 14395For example, in most Ada 83 compilers, @code{Natural'Size} was 32. 14396However, in Ada 95 and Ada 2005, 14397@code{Natural'Size} is 14398typically 31. This means that code may change in behavior when moving 14399from Ada 83 to Ada 95 or Ada 2005. For example, consider: 14400 14401@smallexample @c ada 14402 type Rec is record; 14403 A : Natural; 14404 B : Natural; 14405 end record; 14406 14407 for Rec use record 14408 at 0 range 0 .. Natural'Size - 1; 14409 at 0 range Natural'Size .. 2 * Natural'Size - 1; 14410 end record; 14411@end smallexample 14412 14413@noindent 14414In the above code, since the typical size of @code{Natural} objects 14415is 32 bits and @code{Natural'Size} is 31, the above code can cause 14416unexpected inefficient packing in Ada 95 and Ada 2005, and in general 14417there are cases where the fact that the object size can exceed the 14418size of the type causes surprises. 14419 14420To help get around this problem GNAT provides two implementation 14421defined attributes, @code{Value_Size} and @code{Object_Size}. When 14422applied to a type, these attributes yield the size of the type 14423(corresponding to the RM defined size attribute), and the size of 14424objects of the type respectively. 14425 14426The @code{Object_Size} is used for determining the default size of 14427objects and components. This size value can be referred to using the 14428@code{Object_Size} attribute. The phrase ``is used'' here means that it is 14429the basis of the determination of the size. The backend is free to 14430pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone 14431character might be stored in 32 bits on a machine with no efficient 14432byte access instructions such as the Alpha. 14433 14434The default rules for the value of @code{Object_Size} for 14435discrete types are as follows: 14436 14437@itemize @bullet 14438@item 14439The @code{Object_Size} for base subtypes reflect the natural hardware 14440size in bits (run the compiler with @option{-gnatS} to find those values 14441for numeric types). Enumeration types and fixed-point base subtypes have 144428, 16, 32 or 64 bits for this size, depending on the range of values 14443to be stored. 14444 14445@item 14446The @code{Object_Size} of a subtype is the same as the 14447@code{Object_Size} of 14448the type from which it is obtained. 14449 14450@item 14451The @code{Object_Size} of a derived base type is copied from the parent 14452base type, and the @code{Object_Size} of a derived first subtype is copied 14453from the parent first subtype. 14454@end itemize 14455 14456@noindent 14457The @code{Value_Size} attribute 14458is the (minimum) number of bits required to store a value 14459of the type. 14460This value is used to determine how tightly to pack 14461records or arrays with components of this type, and also affects 14462the semantics of unchecked conversion (unchecked conversions where 14463the @code{Value_Size} values differ generate a warning, and are potentially 14464target dependent). 14465 14466The default rules for the value of @code{Value_Size} are as follows: 14467 14468@itemize @bullet 14469@item 14470The @code{Value_Size} for a base subtype is the minimum number of bits 14471required to store all values of the type (including the sign bit 14472only if negative values are possible). 14473 14474@item 14475If a subtype statically matches the first subtype of a given type, then it has 14476by default the same @code{Value_Size} as the first subtype. This is a 14477consequence of RM 13.1(14) (``if two subtypes statically match, 14478then their subtype-specific aspects are the same''.) 14479 14480@item 14481All other subtypes have a @code{Value_Size} corresponding to the minimum 14482number of bits required to store all values of the subtype. For 14483dynamic bounds, it is assumed that the value can range down or up 14484to the corresponding bound of the ancestor 14485@end itemize 14486 14487@noindent 14488The RM defined attribute @code{Size} corresponds to the 14489@code{Value_Size} attribute. 14490 14491The @code{Size} attribute may be defined for a first-named subtype. This sets 14492the @code{Value_Size} of 14493the first-named subtype to the given value, and the 14494@code{Object_Size} of this first-named subtype to the given value padded up 14495to an appropriate boundary. It is a consequence of the default rules 14496above that this @code{Object_Size} will apply to all further subtypes. On the 14497other hand, @code{Value_Size} is affected only for the first subtype, any 14498dynamic subtypes obtained from it directly, and any statically matching 14499subtypes. The @code{Value_Size} of any other static subtypes is not affected. 14500 14501@code{Value_Size} and 14502@code{Object_Size} may be explicitly set for any subtype using 14503an attribute definition clause. Note that the use of these attributes 14504can cause the RM 13.1(14) rule to be violated. If two access types 14505reference aliased objects whose subtypes have differing @code{Object_Size} 14506values as a result of explicit attribute definition clauses, then it 14507is illegal to convert from one access subtype to the other. For a more 14508complete description of this additional legality rule, see the 14509description of the @code{Object_Size} attribute. 14510 14511At the implementation level, Esize stores the Object_Size and the 14512RM_Size field stores the @code{Value_Size} (and hence the value of the 14513@code{Size} attribute, 14514which, as noted above, is equivalent to @code{Value_Size}). 14515 14516To get a feel for the difference, consider the following examples (note 14517that in each case the base is @code{Short_Short_Integer} with a size of 8): 14518 14519@smallexample 14520 Object_Size Value_Size 14521 14522type x1 is range 0 .. 5; 8 3 14523 14524type x2 is range 0 .. 5; 14525for x2'size use 12; 16 12 14526 14527subtype x3 is x2 range 0 .. 3; 16 2 14528 14529subtype x4 is x2'base range 0 .. 10; 8 4 14530 14531subtype x5 is x2 range 0 .. dynamic; 16 3* 14532 14533subtype x6 is x2'base range 0 .. dynamic; 8 3* 14534 14535@end smallexample 14536 14537@noindent 14538Note: the entries marked ``3*'' are not actually specified by the Ada 14539Reference Manual, but it seems in the spirit of the RM rules to allocate 14540the minimum number of bits (here 3, given the range for @code{x2}) 14541known to be large enough to hold the given range of values. 14542 14543So far, so good, but GNAT has to obey the RM rules, so the question is 14544under what conditions must the RM @code{Size} be used. 14545The following is a list 14546of the occasions on which the RM @code{Size} must be used: 14547 14548@itemize @bullet 14549@item 14550Component size for packed arrays or records 14551 14552@item 14553Value of the attribute @code{Size} for a type 14554 14555@item 14556Warning about sizes not matching for unchecked conversion 14557@end itemize 14558 14559@noindent 14560For record types, the @code{Object_Size} is always a multiple of the 14561alignment of the type (this is true for all types). In some cases the 14562@code{Value_Size} can be smaller. Consider: 14563 14564@smallexample 14565 type R is record 14566 X : Integer; 14567 Y : Character; 14568 end record; 14569@end smallexample 14570 14571@noindent 14572On a typical 32-bit architecture, the X component will be four bytes, and 14573require four-byte alignment, and the Y component will be one byte. In this 14574case @code{R'Value_Size} will be 40 (bits) since this is the minimum size 14575required to store a value of this type, and for example, it is permissible 14576to have a component of type R in an outer array whose component size is 14577specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits), 14578since it must be rounded up so that this value is a multiple of the 14579alignment (4 bytes = 32 bits). 14580 14581@noindent 14582For all other types, the @code{Object_Size} 14583and Value_Size are the same (and equivalent to the RM attribute @code{Size}). 14584Only @code{Size} may be specified for such types. 14585 14586Note that @code{Value_Size} can be used to force biased representation 14587for a particular subtype. Consider this example: 14588 14589@smallexample 14590 type R is (A, B, C, D, E, F); 14591 subtype RAB is R range A .. B; 14592 subtype REF is R range E .. F; 14593@end smallexample 14594 14595@noindent 14596By default, @code{RAB} 14597has a size of 1 (sufficient to accommodate the representation 14598of @code{A} and @code{B}, 0 and 1), and @code{REF} 14599has a size of 3 (sufficient to accommodate the representation 14600of @code{E} and @code{F}, 4 and 5). But if we add the 14601following @code{Value_Size} attribute definition clause: 14602 14603@smallexample 14604 for REF'Value_Size use 1; 14605@end smallexample 14606 14607@noindent 14608then biased representation is forced for @code{REF}, 14609and 0 will represent @code{E} and 1 will represent @code{F}. 14610A warning is issued when a @code{Value_Size} attribute 14611definition clause forces biased representation. This 14612warning can be turned off using @code{-gnatw.B}. 14613 14614@node Component_Size Clauses 14615@section Component_Size Clauses 14616@cindex Component_Size Clause 14617 14618@noindent 14619Normally, the value specified in a component size clause must be consistent 14620with the subtype of the array component with regard to size and alignment. 14621In other words, the value specified must be at least equal to the size 14622of this subtype, and must be a multiple of the alignment value. 14623 14624In addition, component size clauses are allowed which cause the array 14625to be packed, by specifying a smaller value. A first case is for 14626component size values in the range 1 through 63. The value specified 14627must not be smaller than the Size of the subtype. GNAT will accurately 14628honor all packing requests in this range. For example, if we have: 14629 14630@smallexample @c ada 14631type r is array (1 .. 8) of Natural; 14632for r'Component_Size use 31; 14633@end smallexample 14634 14635@noindent 14636then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 14637Of course access to the components of such an array is considerably 14638less efficient than if the natural component size of 32 is used. 14639A second case is when the subtype of the component is a record type 14640padded because of its default alignment. For example, if we have: 14641 14642@smallexample @c ada 14643type r is record 14644 i : Integer; 14645 j : Integer; 14646 b : Boolean; 14647end record; 14648 14649type a is array (1 .. 8) of r; 14650for a'Component_Size use 72; 14651@end smallexample 14652 14653@noindent 14654then the resulting array has a length of 72 bytes, instead of 96 bytes 14655if the alignment of the record (4) was obeyed. 14656 14657Note that there is no point in giving both a component size clause 14658and a pragma Pack for the same array type. if such duplicate 14659clauses are given, the pragma Pack will be ignored. 14660 14661@node Bit_Order Clauses 14662@section Bit_Order Clauses 14663@cindex Bit_Order Clause 14664@cindex bit ordering 14665@cindex ordering, of bits 14666 14667@noindent 14668For record subtypes, GNAT permits the specification of the @code{Bit_Order} 14669attribute. The specification may either correspond to the default bit 14670order for the target, in which case the specification has no effect and 14671places no additional restrictions, or it may be for the non-standard 14672setting (that is the opposite of the default). 14673 14674In the case where the non-standard value is specified, the effect is 14675to renumber bits within each byte, but the ordering of bytes is not 14676affected. There are certain 14677restrictions placed on component clauses as follows: 14678 14679@itemize @bullet 14680 14681@item Components fitting within a single storage unit. 14682@noindent 14683These are unrestricted, and the effect is merely to renumber bits. For 14684example if we are on a little-endian machine with @code{Low_Order_First} 14685being the default, then the following two declarations have exactly 14686the same effect: 14687 14688@smallexample @c ada 14689 type R1 is record 14690 A : Boolean; 14691 B : Integer range 1 .. 120; 14692 end record; 14693 14694 for R1 use record 14695 A at 0 range 0 .. 0; 14696 B at 0 range 1 .. 7; 14697 end record; 14698 14699 type R2 is record 14700 A : Boolean; 14701 B : Integer range 1 .. 120; 14702 end record; 14703 14704 for R2'Bit_Order use High_Order_First; 14705 14706 for R2 use record 14707 A at 0 range 7 .. 7; 14708 B at 0 range 0 .. 6; 14709 end record; 14710@end smallexample 14711 14712@noindent 14713The useful application here is to write the second declaration with the 14714@code{Bit_Order} attribute definition clause, and know that it will be treated 14715the same, regardless of whether the target is little-endian or big-endian. 14716 14717@item Components occupying an integral number of bytes. 14718@noindent 14719These are components that exactly fit in two or more bytes. Such component 14720declarations are allowed, but have no effect, since it is important to realize 14721that the @code{Bit_Order} specification does not affect the ordering of bytes. 14722In particular, the following attempt at getting an endian-independent integer 14723does not work: 14724 14725@smallexample @c ada 14726 type R2 is record 14727 A : Integer; 14728 end record; 14729 14730 for R2'Bit_Order use High_Order_First; 14731 14732 for R2 use record 14733 A at 0 range 0 .. 31; 14734 end record; 14735@end smallexample 14736 14737@noindent 14738This declaration will result in a little-endian integer on a 14739little-endian machine, and a big-endian integer on a big-endian machine. 14740If byte flipping is required for interoperability between big- and 14741little-endian machines, this must be explicitly programmed. This capability 14742is not provided by @code{Bit_Order}. 14743 14744@item Components that are positioned across byte boundaries 14745@noindent 14746but do not occupy an integral number of bytes. Given that bytes are not 14747reordered, such fields would occupy a non-contiguous sequence of bits 14748in memory, requiring non-trivial code to reassemble. They are for this 14749reason not permitted, and any component clause specifying such a layout 14750will be flagged as illegal by GNAT@. 14751 14752@end itemize 14753 14754@noindent 14755Since the misconception that Bit_Order automatically deals with all 14756endian-related incompatibilities is a common one, the specification of 14757a component field that is an integral number of bytes will always 14758generate a warning. This warning may be suppressed using @code{pragma 14759Warnings (Off)} if desired. The following section contains additional 14760details regarding the issue of byte ordering. 14761 14762@node Effect of Bit_Order on Byte Ordering 14763@section Effect of Bit_Order on Byte Ordering 14764@cindex byte ordering 14765@cindex ordering, of bytes 14766 14767@noindent 14768In this section we will review the effect of the @code{Bit_Order} attribute 14769definition clause on byte ordering. Briefly, it has no effect at all, but 14770a detailed example will be helpful. Before giving this 14771example, let us review the precise 14772definition of the effect of defining @code{Bit_Order}. The effect of a 14773non-standard bit order is described in section 15.5.3 of the Ada 14774Reference Manual: 14775 14776@quotation 147772 A bit ordering is a method of interpreting the meaning of 14778the storage place attributes. 14779@end quotation 14780 14781@noindent 14782To understand the precise definition of storage place attributes in 14783this context, we visit section 13.5.1 of the manual: 14784 14785@quotation 1478613 A record_representation_clause (without the mod_clause) 14787specifies the layout. The storage place attributes (see 13.5.2) 14788are taken from the values of the position, first_bit, and last_bit 14789expressions after normalizing those values so that first_bit is 14790less than Storage_Unit. 14791@end quotation 14792 14793@noindent 14794The critical point here is that storage places are taken from 14795the values after normalization, not before. So the @code{Bit_Order} 14796interpretation applies to normalized values. The interpretation 14797is described in the later part of the 15.5.3 paragraph: 14798 14799@quotation 148002 A bit ordering is a method of interpreting the meaning of 14801the storage place attributes. High_Order_First (known in the 14802vernacular as ``big endian'') means that the first bit of a 14803storage element (bit 0) is the most significant bit (interpreting 14804the sequence of bits that represent a component as an unsigned 14805integer value). Low_Order_First (known in the vernacular as 14806``little endian'') means the opposite: the first bit is the 14807least significant. 14808@end quotation 14809 14810@noindent 14811Note that the numbering is with respect to the bits of a storage 14812unit. In other words, the specification affects only the numbering 14813of bits within a single storage unit. 14814 14815We can make the effect clearer by giving an example. 14816 14817Suppose that we have an external device which presents two bytes, the first 14818byte presented, which is the first (low addressed byte) of the two byte 14819record is called Master, and the second byte is called Slave. 14820 14821The left most (most significant bit is called Control for each byte, and 14822the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost 14823(least significant) bit. 14824 14825On a big-endian machine, we can write the following representation clause 14826 14827@smallexample @c ada 14828 type Data is record 14829 Master_Control : Bit; 14830 Master_V1 : Bit; 14831 Master_V2 : Bit; 14832 Master_V3 : Bit; 14833 Master_V4 : Bit; 14834 Master_V5 : Bit; 14835 Master_V6 : Bit; 14836 Master_V7 : Bit; 14837 Slave_Control : Bit; 14838 Slave_V1 : Bit; 14839 Slave_V2 : Bit; 14840 Slave_V3 : Bit; 14841 Slave_V4 : Bit; 14842 Slave_V5 : Bit; 14843 Slave_V6 : Bit; 14844 Slave_V7 : Bit; 14845 end record; 14846 14847 for Data use record 14848 Master_Control at 0 range 0 .. 0; 14849 Master_V1 at 0 range 1 .. 1; 14850 Master_V2 at 0 range 2 .. 2; 14851 Master_V3 at 0 range 3 .. 3; 14852 Master_V4 at 0 range 4 .. 4; 14853 Master_V5 at 0 range 5 .. 5; 14854 Master_V6 at 0 range 6 .. 6; 14855 Master_V7 at 0 range 7 .. 7; 14856 Slave_Control at 1 range 0 .. 0; 14857 Slave_V1 at 1 range 1 .. 1; 14858 Slave_V2 at 1 range 2 .. 2; 14859 Slave_V3 at 1 range 3 .. 3; 14860 Slave_V4 at 1 range 4 .. 4; 14861 Slave_V5 at 1 range 5 .. 5; 14862 Slave_V6 at 1 range 6 .. 6; 14863 Slave_V7 at 1 range 7 .. 7; 14864 end record; 14865@end smallexample 14866 14867@noindent 14868Now if we move this to a little endian machine, then the bit ordering within 14869the byte is backwards, so we have to rewrite the record rep clause as: 14870 14871@smallexample @c ada 14872 for Data use record 14873 Master_Control at 0 range 7 .. 7; 14874 Master_V1 at 0 range 6 .. 6; 14875 Master_V2 at 0 range 5 .. 5; 14876 Master_V3 at 0 range 4 .. 4; 14877 Master_V4 at 0 range 3 .. 3; 14878 Master_V5 at 0 range 2 .. 2; 14879 Master_V6 at 0 range 1 .. 1; 14880 Master_V7 at 0 range 0 .. 0; 14881 Slave_Control at 1 range 7 .. 7; 14882 Slave_V1 at 1 range 6 .. 6; 14883 Slave_V2 at 1 range 5 .. 5; 14884 Slave_V3 at 1 range 4 .. 4; 14885 Slave_V4 at 1 range 3 .. 3; 14886 Slave_V5 at 1 range 2 .. 2; 14887 Slave_V6 at 1 range 1 .. 1; 14888 Slave_V7 at 1 range 0 .. 0; 14889 end record; 14890@end smallexample 14891 14892@noindent 14893It is a nuisance to have to rewrite the clause, especially if 14894the code has to be maintained on both machines. However, 14895this is a case that we can handle with the 14896@code{Bit_Order} attribute if it is implemented. 14897Note that the implementation is not required on byte addressed 14898machines, but it is indeed implemented in GNAT. 14899This means that we can simply use the 14900first record clause, together with the declaration 14901 14902@smallexample @c ada 14903 for Data'Bit_Order use High_Order_First; 14904@end smallexample 14905 14906@noindent 14907and the effect is what is desired, namely the layout is exactly the same, 14908independent of whether the code is compiled on a big-endian or little-endian 14909machine. 14910 14911The important point to understand is that byte ordering is not affected. 14912A @code{Bit_Order} attribute definition never affects which byte a field 14913ends up in, only where it ends up in that byte. 14914To make this clear, let us rewrite the record rep clause of the previous 14915example as: 14916 14917@smallexample @c ada 14918 for Data'Bit_Order use High_Order_First; 14919 for Data use record 14920 Master_Control at 0 range 0 .. 0; 14921 Master_V1 at 0 range 1 .. 1; 14922 Master_V2 at 0 range 2 .. 2; 14923 Master_V3 at 0 range 3 .. 3; 14924 Master_V4 at 0 range 4 .. 4; 14925 Master_V5 at 0 range 5 .. 5; 14926 Master_V6 at 0 range 6 .. 6; 14927 Master_V7 at 0 range 7 .. 7; 14928 Slave_Control at 0 range 8 .. 8; 14929 Slave_V1 at 0 range 9 .. 9; 14930 Slave_V2 at 0 range 10 .. 10; 14931 Slave_V3 at 0 range 11 .. 11; 14932 Slave_V4 at 0 range 12 .. 12; 14933 Slave_V5 at 0 range 13 .. 13; 14934 Slave_V6 at 0 range 14 .. 14; 14935 Slave_V7 at 0 range 15 .. 15; 14936 end record; 14937@end smallexample 14938 14939@noindent 14940This is exactly equivalent to saying (a repeat of the first example): 14941 14942@smallexample @c ada 14943 for Data'Bit_Order use High_Order_First; 14944 for Data use record 14945 Master_Control at 0 range 0 .. 0; 14946 Master_V1 at 0 range 1 .. 1; 14947 Master_V2 at 0 range 2 .. 2; 14948 Master_V3 at 0 range 3 .. 3; 14949 Master_V4 at 0 range 4 .. 4; 14950 Master_V5 at 0 range 5 .. 5; 14951 Master_V6 at 0 range 6 .. 6; 14952 Master_V7 at 0 range 7 .. 7; 14953 Slave_Control at 1 range 0 .. 0; 14954 Slave_V1 at 1 range 1 .. 1; 14955 Slave_V2 at 1 range 2 .. 2; 14956 Slave_V3 at 1 range 3 .. 3; 14957 Slave_V4 at 1 range 4 .. 4; 14958 Slave_V5 at 1 range 5 .. 5; 14959 Slave_V6 at 1 range 6 .. 6; 14960 Slave_V7 at 1 range 7 .. 7; 14961 end record; 14962@end smallexample 14963 14964@noindent 14965Why are they equivalent? Well take a specific field, the @code{Slave_V2} 14966field. The storage place attributes are obtained by normalizing the 14967values given so that the @code{First_Bit} value is less than 8. After 14968normalizing the values (0,10,10) we get (1,2,2) which is exactly what 14969we specified in the other case. 14970 14971Now one might expect that the @code{Bit_Order} attribute might affect 14972bit numbering within the entire record component (two bytes in this 14973case, thus affecting which byte fields end up in), but that is not 14974the way this feature is defined, it only affects numbering of bits, 14975not which byte they end up in. 14976 14977Consequently it never makes sense to specify a starting bit number 14978greater than 7 (for a byte addressable field) if an attribute 14979definition for @code{Bit_Order} has been given, and indeed it 14980may be actively confusing to specify such a value, so the compiler 14981generates a warning for such usage. 14982 14983If you do need to control byte ordering then appropriate conditional 14984values must be used. If in our example, the slave byte came first on 14985some machines we might write: 14986 14987@smallexample @c ada 14988 Master_Byte_First constant Boolean := @dots{}; 14989 14990 Master_Byte : constant Natural := 14991 1 - Boolean'Pos (Master_Byte_First); 14992 Slave_Byte : constant Natural := 14993 Boolean'Pos (Master_Byte_First); 14994 14995 for Data'Bit_Order use High_Order_First; 14996 for Data use record 14997 Master_Control at Master_Byte range 0 .. 0; 14998 Master_V1 at Master_Byte range 1 .. 1; 14999 Master_V2 at Master_Byte range 2 .. 2; 15000 Master_V3 at Master_Byte range 3 .. 3; 15001 Master_V4 at Master_Byte range 4 .. 4; 15002 Master_V5 at Master_Byte range 5 .. 5; 15003 Master_V6 at Master_Byte range 6 .. 6; 15004 Master_V7 at Master_Byte range 7 .. 7; 15005 Slave_Control at Slave_Byte range 0 .. 0; 15006 Slave_V1 at Slave_Byte range 1 .. 1; 15007 Slave_V2 at Slave_Byte range 2 .. 2; 15008 Slave_V3 at Slave_Byte range 3 .. 3; 15009 Slave_V4 at Slave_Byte range 4 .. 4; 15010 Slave_V5 at Slave_Byte range 5 .. 5; 15011 Slave_V6 at Slave_Byte range 6 .. 6; 15012 Slave_V7 at Slave_Byte range 7 .. 7; 15013 end record; 15014@end smallexample 15015 15016@noindent 15017Now to switch between machines, all that is necessary is 15018to set the boolean constant @code{Master_Byte_First} in 15019an appropriate manner. 15020 15021@node Pragma Pack for Arrays 15022@section Pragma Pack for Arrays 15023@cindex Pragma Pack (for arrays) 15024 15025@noindent 15026Pragma @code{Pack} applied to an array has no effect unless the component type 15027is packable. For a component type to be packable, it must be one of the 15028following cases: 15029 15030@itemize @bullet 15031@item 15032Any scalar type 15033@item 15034Any type whose size is specified with a size clause 15035@item 15036Any packed array type with a static size 15037@item 15038Any record type padded because of its default alignment 15039@end itemize 15040 15041@noindent 15042For all these cases, if the component subtype size is in the range 150431 through 63, then the effect of the pragma @code{Pack} is exactly as though a 15044component size were specified giving the component subtype size. 15045For example if we have: 15046 15047@smallexample @c ada 15048 type r is range 0 .. 17; 15049 15050 type ar is array (1 .. 8) of r; 15051 pragma Pack (ar); 15052@end smallexample 15053 15054@noindent 15055Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size}, 15056and the size of the array @code{ar} will be exactly 40 bits. 15057 15058Note that in some cases this rather fierce approach to packing can produce 15059unexpected effects. For example, in Ada 95 and Ada 2005, 15060subtype @code{Natural} typically has a size of 31, meaning that if you 15061pack an array of @code{Natural}, you get 31-bit 15062close packing, which saves a few bits, but results in far less efficient 15063access. Since many other Ada compilers will ignore such a packing request, 15064GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses 15065might not be what is intended. You can easily remove this warning by 15066using an explicit @code{Component_Size} setting instead, which never generates 15067a warning, since the intention of the programmer is clear in this case. 15068 15069GNAT treats packed arrays in one of two ways. If the size of the array is 15070known at compile time and is less than 64 bits, then internally the array 15071is represented as a single modular type, of exactly the appropriate number 15072of bits. If the length is greater than 63 bits, or is not known at compile 15073time, then the packed array is represented as an array of bytes, and the 15074length is always a multiple of 8 bits. 15075 15076Note that to represent a packed array as a modular type, the alignment must 15077be suitable for the modular type involved. For example, on typical machines 15078a 32-bit packed array will be represented by a 32-bit modular integer with 15079an alignment of four bytes. If you explicitly override the default alignment 15080with an alignment clause that is too small, the modular representation 15081cannot be used. For example, consider the following set of declarations: 15082 15083@smallexample @c ada 15084 type R is range 1 .. 3; 15085 type S is array (1 .. 31) of R; 15086 for S'Component_Size use 2; 15087 for S'Size use 62; 15088 for S'Alignment use 1; 15089@end smallexample 15090 15091@noindent 15092If the alignment clause were not present, then a 62-bit modular 15093representation would be chosen (typically with an alignment of 4 or 8 15094bytes depending on the target). But the default alignment is overridden 15095with the explicit alignment clause. This means that the modular 15096representation cannot be used, and instead the array of bytes 15097representation must be used, meaning that the length must be a multiple 15098of 8. Thus the above set of declarations will result in a diagnostic 15099rejecting the size clause and noting that the minimum size allowed is 64. 15100 15101@cindex Pragma Pack (for type Natural) 15102@cindex Pragma Pack warning 15103 15104One special case that is worth noting occurs when the base type of the 15105component size is 8/16/32 and the subtype is one bit less. Notably this 15106occurs with subtype @code{Natural}. Consider: 15107 15108@smallexample @c ada 15109 type Arr is array (1 .. 32) of Natural; 15110 pragma Pack (Arr); 15111@end smallexample 15112 15113@noindent 15114In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 15115since typically @code{Natural'Size} is 32 in Ada 83, and in any case most 15116Ada 83 compilers did not attempt 31 bit packing. 15117 15118In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, 15119GNAT really does pack 31-bit subtype to 31 bits. This may result in a 15120substantial unintended performance penalty when porting legacy Ada 83 code. 15121To help prevent this, GNAT generates a warning in such cases. If you really 15122want 31 bit packing in a case like this, you can set the component size 15123explicitly: 15124 15125@smallexample @c ada 15126 type Arr is array (1 .. 32) of Natural; 15127 for Arr'Component_Size use 31; 15128@end smallexample 15129 15130@noindent 15131Here 31-bit packing is achieved as required, and no warning is generated, 15132since in this case the programmer intention is clear. 15133 15134@node Pragma Pack for Records 15135@section Pragma Pack for Records 15136@cindex Pragma Pack (for records) 15137 15138@noindent 15139Pragma @code{Pack} applied to a record will pack the components to reduce 15140wasted space from alignment gaps and by reducing the amount of space 15141taken by components. We distinguish between @emph{packable} components and 15142@emph{non-packable} components. 15143Components of the following types are considered packable: 15144@itemize @bullet 15145@item 15146All primitive types are packable. 15147 15148@item 15149Small packed arrays, whose size does not exceed 64 bits, and where the 15150size is statically known at compile time, are represented internally 15151as modular integers, and so they are also packable. 15152 15153@end itemize 15154 15155@noindent 15156All packable components occupy the exact number of bits corresponding to 15157their @code{Size} value, and are packed with no padding bits, i.e.@: they 15158can start on an arbitrary bit boundary. 15159 15160All other types are non-packable, they occupy an integral number of 15161storage units, and 15162are placed at a boundary corresponding to their alignment requirements. 15163 15164For example, consider the record 15165 15166@smallexample @c ada 15167 type Rb1 is array (1 .. 13) of Boolean; 15168 pragma Pack (rb1); 15169 15170 type Rb2 is array (1 .. 65) of Boolean; 15171 pragma Pack (rb2); 15172 15173 type x2 is record 15174 l1 : Boolean; 15175 l2 : Duration; 15176 l3 : Float; 15177 l4 : Boolean; 15178 l5 : Rb1; 15179 l6 : Rb2; 15180 end record; 15181 pragma Pack (x2); 15182@end smallexample 15183 15184@noindent 15185The representation for the record x2 is as follows: 15186 15187@smallexample @c ada 15188for x2'Size use 224; 15189for x2 use record 15190 l1 at 0 range 0 .. 0; 15191 l2 at 0 range 1 .. 64; 15192 l3 at 12 range 0 .. 31; 15193 l4 at 16 range 0 .. 0; 15194 l5 at 16 range 1 .. 13; 15195 l6 at 18 range 0 .. 71; 15196end record; 15197@end smallexample 15198 15199@noindent 15200Studying this example, we see that the packable fields @code{l1} 15201and @code{l2} are 15202of length equal to their sizes, and placed at specific bit boundaries (and 15203not byte boundaries) to 15204eliminate padding. But @code{l3} is of a non-packable float type, so 15205it is on the next appropriate alignment boundary. 15206 15207The next two fields are fully packable, so @code{l4} and @code{l5} are 15208minimally packed with no gaps. However, type @code{Rb2} is a packed 15209array that is longer than 64 bits, so it is itself non-packable. Thus 15210the @code{l6} field is aligned to the next byte boundary, and takes an 15211integral number of bytes, i.e.@: 72 bits. 15212 15213@node Record Representation Clauses 15214@section Record Representation Clauses 15215@cindex Record Representation Clause 15216 15217@noindent 15218Record representation clauses may be given for all record types, including 15219types obtained by record extension. Component clauses are allowed for any 15220static component. The restrictions on component clauses depend on the type 15221of the component. 15222 15223@cindex Component Clause 15224For all components of an elementary type, the only restriction on component 15225clauses is that the size must be at least the 'Size value of the type 15226(actually the Value_Size). There are no restrictions due to alignment, 15227and such components may freely cross storage boundaries. 15228 15229Packed arrays with a size up to and including 64 bits are represented 15230internally using a modular type with the appropriate number of bits, and 15231thus the same lack of restriction applies. For example, if you declare: 15232 15233@smallexample @c ada 15234 type R is array (1 .. 49) of Boolean; 15235 pragma Pack (R); 15236 for R'Size use 49; 15237@end smallexample 15238 15239@noindent 15240then a component clause for a component of type R may start on any 15241specified bit boundary, and may specify a value of 49 bits or greater. 15242 15243For packed bit arrays that are longer than 64 bits, there are two 15244cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), 15245including the important case of single bits or boolean values, then 15246there are no limitations on placement of such components, and they 15247may start and end at arbitrary bit boundaries. 15248 15249If the component size is not a power of 2 (e.g.@: 3 or 5), then 15250an array of this type longer than 64 bits must always be placed on 15251on a storage unit (byte) boundary and occupy an integral number 15252of storage units (bytes). Any component clause that does not 15253meet this requirement will be rejected. 15254 15255Any aliased component, or component of an aliased type, must 15256have its normal alignment and size. A component clause that 15257does not meet this requirement will be rejected. 15258 15259The tag field of a tagged type always occupies an address sized field at 15260the start of the record. No component clause may attempt to overlay this 15261tag. When a tagged type appears as a component, the tag field must have 15262proper alignment 15263 15264In the case of a record extension T1, of a type T, no component clause applied 15265to the type T1 can specify a storage location that would overlap the first 15266T'Size bytes of the record. 15267 15268For all other component types, including non-bit-packed arrays, 15269the component can be placed at an arbitrary bit boundary, 15270so for example, the following is permitted: 15271 15272@smallexample @c ada 15273 type R is array (1 .. 10) of Boolean; 15274 for R'Size use 80; 15275 15276 type Q is record 15277 G, H : Boolean; 15278 L, M : R; 15279 end record; 15280 15281 for Q use record 15282 G at 0 range 0 .. 0; 15283 H at 0 range 1 .. 1; 15284 L at 0 range 2 .. 81; 15285 R at 0 range 82 .. 161; 15286 end record; 15287@end smallexample 15288 15289@noindent 15290Note: the above rules apply to recent releases of GNAT 5. 15291In GNAT 3, there are more severe restrictions on larger components. 15292For non-primitive types, including packed arrays with a size greater than 1529364 bits, component clauses must respect the alignment requirement of the 15294type, in particular, always starting on a byte boundary, and the length 15295must be a multiple of the storage unit. 15296 15297@node Handling of Records with Holes 15298@section Handling of Records with Holes 15299@cindex Handling of Records with Holes 15300 15301As a result of alignment considerations, records may contain "holes" 15302or gaps 15303which do not correspond to the data bits of any of the components. 15304Record representation clauses can also result in holes in records. 15305 15306GNAT does not attempt to clear these holes, so in record objects, 15307they should be considered to hold undefined rubbish. The generated 15308equality routine just tests components so does not access these 15309undefined bits, and assignment and copy operations may or may not 15310preserve the contents of these holes (for assignments, the holes 15311in the target will in practice contain either the bits that are 15312present in the holes in the source, or the bits that were present 15313in the target before the assignment). 15314 15315If it is necessary to ensure that holes in records have all zero 15316bits, then record objects for which this initialization is desired 15317should be explicitly set to all zero values using Unchecked_Conversion 15318or address overlays. For example 15319 15320@smallexample @c ada 15321type HRec is record 15322 C : Character; 15323 I : Integer; 15324end record; 15325@end smallexample 15326 15327@noindent 15328On typical machines, integers need to be aligned on a four-byte 15329boundary, resulting in three bytes of undefined rubbish following 15330the 8-bit field for C. To ensure that the hole in a variable of 15331type HRec is set to all zero bits, 15332you could for example do: 15333 15334@smallexample @c ada 15335type Base is record 15336 Dummy1, Dummy2 : Integer := 0; 15337end record; 15338 15339BaseVar : Base; 15340RealVar : Hrec; 15341for RealVar'Address use BaseVar'Address; 15342@end smallexample 15343 15344@noindent 15345Now the 8-bytes of the value of RealVar start out containing all zero 15346bits. A safer approach is to just define dummy fields, avoiding the 15347holes, as in: 15348 15349@smallexample @c ada 15350type HRec is record 15351 C : Character; 15352 Dummy1 : Short_Short_Integer := 0; 15353 Dummy2 : Short_Short_Integer := 0; 15354 Dummy3 : Short_Short_Integer := 0; 15355 I : Integer; 15356end record; 15357@end smallexample 15358 15359@noindent 15360And to make absolutely sure that the intent of this is followed, you 15361can use representation clauses: 15362 15363@smallexample @c ada 15364for Hrec use record 15365 C at 0 range 0 .. 7; 15366 Dummy1 at 1 range 0 .. 7; 15367 Dummy2 at 2 range 0 .. 7; 15368 Dummy3 at 3 range 0 .. 7; 15369 I at 4 range 0 .. 31; 15370end record; 15371for Hrec'Size use 64; 15372@end smallexample 15373 15374@node Enumeration Clauses 15375@section Enumeration Clauses 15376 15377The only restriction on enumeration clauses is that the range of values 15378must be representable. For the signed case, if one or more of the 15379representation values are negative, all values must be in the range: 15380 15381@smallexample @c ada 15382 System.Min_Int .. System.Max_Int 15383@end smallexample 15384 15385@noindent 15386For the unsigned case, where all values are nonnegative, the values must 15387be in the range: 15388 15389@smallexample @c ada 15390 0 .. System.Max_Binary_Modulus; 15391@end smallexample 15392 15393@noindent 15394A @emph{confirming} representation clause is one in which the values range 15395from 0 in sequence, i.e.@: a clause that confirms the default representation 15396for an enumeration type. 15397Such a confirming representation 15398is permitted by these rules, and is specially recognized by the compiler so 15399that no extra overhead results from the use of such a clause. 15400 15401If an array has an index type which is an enumeration type to which an 15402enumeration clause has been applied, then the array is stored in a compact 15403manner. Consider the declarations: 15404 15405@smallexample @c ada 15406 type r is (A, B, C); 15407 for r use (A => 1, B => 5, C => 10); 15408 type t is array (r) of Character; 15409@end smallexample 15410 15411@noindent 15412The array type t corresponds to a vector with exactly three elements and 15413has a default size equal to @code{3*Character'Size}. This ensures efficient 15414use of space, but means that accesses to elements of the array will incur 15415the overhead of converting representation values to the corresponding 15416positional values, (i.e.@: the value delivered by the @code{Pos} attribute). 15417 15418@node Address Clauses 15419@section Address Clauses 15420@cindex Address Clause 15421 15422The reference manual allows a general restriction on representation clauses, 15423as found in RM 13.1(22): 15424 15425@quotation 15426An implementation need not support representation 15427items containing nonstatic expressions, except that 15428an implementation should support a representation item 15429for a given entity if each nonstatic expression in the 15430representation item is a name that statically denotes 15431a constant declared before the entity. 15432@end quotation 15433 15434@noindent 15435In practice this is applicable only to address clauses, since this is the 15436only case in which a non-static expression is permitted by the syntax. As 15437the AARM notes in sections 13.1 (22.a-22.h): 15438 15439@display 15440 22.a Reason: This is to avoid the following sort of thing: 15441 15442 22.b X : Integer := F(@dots{}); 15443 Y : Address := G(@dots{}); 15444 for X'Address use Y; 15445 15446 22.c In the above, we have to evaluate the 15447 initialization expression for X before we 15448 know where to put the result. This seems 15449 like an unreasonable implementation burden. 15450 15451 22.d The above code should instead be written 15452 like this: 15453 15454 22.e Y : constant Address := G(@dots{}); 15455 X : Integer := F(@dots{}); 15456 for X'Address use Y; 15457 15458 22.f This allows the expression ``Y'' to be safely 15459 evaluated before X is created. 15460 15461 22.g The constant could be a formal parameter of mode in. 15462 15463 22.h An implementation can support other nonstatic 15464 expressions if it wants to. Expressions of type 15465 Address are hardly ever static, but their value 15466 might be known at compile time anyway in many 15467 cases. 15468@end display 15469 15470@noindent 15471GNAT does indeed permit many additional cases of non-static expressions. In 15472particular, if the type involved is elementary there are no restrictions 15473(since in this case, holding a temporary copy of the initialization value, 15474if one is present, is inexpensive). In addition, if there is no implicit or 15475explicit initialization, then there are no restrictions. GNAT will reject 15476only the case where all three of these conditions hold: 15477 15478@itemize @bullet 15479 15480@item 15481The type of the item is non-elementary (e.g.@: a record or array). 15482 15483@item 15484There is explicit or implicit initialization required for the object. 15485Note that access values are always implicitly initialized. 15486 15487@item 15488The address value is non-static. Here GNAT is more permissive than the 15489RM, and allows the address value to be the address of a previously declared 15490stand-alone variable, as long as it does not itself have an address clause. 15491 15492@smallexample @c ada 15493 Anchor : Some_Initialized_Type; 15494 Overlay : Some_Initialized_Type; 15495 for Overlay'Address use Anchor'Address; 15496@end smallexample 15497 15498@noindent 15499However, the prefix of the address clause cannot be an array component, or 15500a component of a discriminated record. 15501 15502@end itemize 15503 15504@noindent 15505As noted above in section 22.h, address values are typically non-static. In 15506particular the To_Address function, even if applied to a literal value, is 15507a non-static function call. To avoid this minor annoyance, GNAT provides 15508the implementation defined attribute 'To_Address. The following two 15509expressions have identical values: 15510 15511@findex Attribute 15512@findex To_Address 15513@smallexample @c ada 15514 To_Address (16#1234_0000#) 15515 System'To_Address (16#1234_0000#); 15516@end smallexample 15517 15518@noindent 15519except that the second form is considered to be a static expression, and 15520thus when used as an address clause value is always permitted. 15521 15522@noindent 15523Additionally, GNAT treats as static an address clause that is an 15524unchecked_conversion of a static integer value. This simplifies the porting 15525of legacy code, and provides a portable equivalent to the GNAT attribute 15526@code{To_Address}. 15527 15528Another issue with address clauses is the interaction with alignment 15529requirements. When an address clause is given for an object, the address 15530value must be consistent with the alignment of the object (which is usually 15531the same as the alignment of the type of the object). If an address clause 15532is given that specifies an inappropriately aligned address value, then the 15533program execution is erroneous. 15534 15535Since this source of erroneous behavior can have unfortunate effects, GNAT 15536checks (at compile time if possible, generating a warning, or at execution 15537time with a run-time check) that the alignment is appropriate. If the 15538run-time check fails, then @code{Program_Error} is raised. This run-time 15539check is suppressed if range checks are suppressed, or if the special GNAT 15540check Alignment_Check is suppressed, or if 15541@code{pragma Restrictions (No_Elaboration_Code)} is in effect. 15542 15543Finally, GNAT does not permit overlaying of objects of controlled types or 15544composite types containing a controlled component. In most cases, the compiler 15545can detect an attempt at such overlays and will generate a warning at compile 15546time and a Program_Error exception at run time. 15547 15548@findex Export 15549An address clause cannot be given for an exported object. More 15550understandably the real restriction is that objects with an address 15551clause cannot be exported. This is because such variables are not 15552defined by the Ada program, so there is no external object to export. 15553 15554@findex Import 15555It is permissible to give an address clause and a pragma Import for the 15556same object. In this case, the variable is not really defined by the 15557Ada program, so there is no external symbol to be linked. The link name 15558and the external name are ignored in this case. The reason that we allow this 15559combination is that it provides a useful idiom to avoid unwanted 15560initializations on objects with address clauses. 15561 15562When an address clause is given for an object that has implicit or 15563explicit initialization, then by default initialization takes place. This 15564means that the effect of the object declaration is to overwrite the 15565memory at the specified address. This is almost always not what the 15566programmer wants, so GNAT will output a warning: 15567 15568@smallexample 15569 with System; 15570 package G is 15571 type R is record 15572 M : Integer := 0; 15573 end record; 15574 15575 Ext : R; 15576 for Ext'Address use System'To_Address (16#1234_1234#); 15577 | 15578 >>> warning: implicit initialization of "Ext" may 15579 modify overlaid storage 15580 >>> warning: use pragma Import for "Ext" to suppress 15581 initialization (RM B(24)) 15582 15583 end G; 15584@end smallexample 15585 15586@noindent 15587As indicated by the warning message, the solution is to use a (dummy) pragma 15588Import to suppress this initialization. The pragma tell the compiler that the 15589object is declared and initialized elsewhere. The following package compiles 15590without warnings (and the initialization is suppressed): 15591 15592@smallexample @c ada 15593 with System; 15594 package G is 15595 type R is record 15596 M : Integer := 0; 15597 end record; 15598 15599 Ext : R; 15600 for Ext'Address use System'To_Address (16#1234_1234#); 15601 pragma Import (Ada, Ext); 15602 end G; 15603@end smallexample 15604 15605@noindent 15606A final issue with address clauses involves their use for overlaying 15607variables, as in the following example: 15608@cindex Overlaying of objects 15609 15610@smallexample @c ada 15611 A : Integer; 15612 B : Integer; 15613 for B'Address use A'Address; 15614@end smallexample 15615 15616@noindent 15617or alternatively, using the form recommended by the RM: 15618 15619@smallexample @c ada 15620 A : Integer; 15621 Addr : constant Address := A'Address; 15622 B : Integer; 15623 for B'Address use Addr; 15624@end smallexample 15625 15626@noindent 15627In both of these cases, @code{A} 15628and @code{B} become aliased to one another via the 15629address clause. This use of address clauses to overlay 15630variables, achieving an effect similar to unchecked 15631conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005 15632the effect is implementation defined. Furthermore, the 15633Ada RM specifically recommends that in a situation 15634like this, @code{B} should be subject to the following 15635implementation advice (RM 13.3(19)): 15636 15637@quotation 1563819 If the Address of an object is specified, or it is imported 15639 or exported, then the implementation should not perform 15640 optimizations based on assumptions of no aliases. 15641@end quotation 15642 15643@noindent 15644GNAT follows this recommendation, and goes further by also applying 15645this recommendation to the overlaid variable (@code{A} 15646in the above example) in this case. This means that the overlay 15647works "as expected", in that a modification to one of the variables 15648will affect the value of the other. 15649 15650Note that when address clause overlays are used in this way, there is an 15651issue of unintentional initialization, as shown by this example: 15652 15653@smallexample @c ada 15654package Overwrite_Record is 15655 type R is record 15656 A : Character := 'C'; 15657 B : Character := 'A'; 15658 end record; 15659 X : Short_Integer := 3; 15660 Y : R; 15661 for Y'Address use X'Address; 15662 | 15663>>> warning: default initialization of "Y" may 15664 modify "X", use pragma Import for "Y" to 15665 suppress initialization (RM B.1(24)) 15666 15667end Overwrite_Record; 15668@end smallexample 15669 15670@noindent 15671Here the default initialization of @code{Y} will clobber the value 15672of @code{X}, which justifies the warning. The warning notes that 15673this effect can be eliminated by adding a @code{pragma Import} 15674which suppresses the initialization: 15675 15676@smallexample @c ada 15677package Overwrite_Record is 15678 type R is record 15679 A : Character := 'C'; 15680 B : Character := 'A'; 15681 end record; 15682 X : Short_Integer := 3; 15683 Y : R; 15684 for Y'Address use X'Address; 15685 pragma Import (Ada, Y); 15686end Overwrite_Record; 15687@end smallexample 15688 15689@noindent 15690Note that the use of @code{pragma Initialize_Scalars} may cause variables to 15691be initialized when they would not otherwise have been in the absence 15692of the use of this pragma. This may cause an overlay to have this 15693unintended clobbering effect. The compiler avoids this for scalar 15694types, but not for composite objects (where in general the effect 15695of @code{Initialize_Scalars} is part of the initialization routine 15696for the composite object: 15697 15698@smallexample @c ada 15699pragma Initialize_Scalars; 15700with Ada.Text_IO; use Ada.Text_IO; 15701procedure Overwrite_Array is 15702 type Arr is array (1 .. 5) of Integer; 15703 X : Arr := (others => 1); 15704 A : Arr; 15705 for A'Address use X'Address; 15706 | 15707>>> warning: default initialization of "A" may 15708 modify "X", use pragma Import for "A" to 15709 suppress initialization (RM B.1(24)) 15710 15711begin 15712 if X /= Arr'(others => 1) then 15713 Put_Line ("X was clobbered"); 15714 else 15715 Put_Line ("X was not clobbered"); 15716 end if; 15717end Overwrite_Array; 15718@end smallexample 15719 15720@noindent 15721The above program generates the warning as shown, and at execution 15722time, prints @code{X was clobbered}. If the @code{pragma Import} is 15723added as suggested: 15724 15725@smallexample @c ada 15726pragma Initialize_Scalars; 15727with Ada.Text_IO; use Ada.Text_IO; 15728procedure Overwrite_Array is 15729 type Arr is array (1 .. 5) of Integer; 15730 X : Arr := (others => 1); 15731 A : Arr; 15732 for A'Address use X'Address; 15733 pragma Import (Ada, A); 15734begin 15735 if X /= Arr'(others => 1) then 15736 Put_Line ("X was clobbered"); 15737 else 15738 Put_Line ("X was not clobbered"); 15739 end if; 15740end Overwrite_Array; 15741@end smallexample 15742 15743@noindent 15744then the program compiles without the waraning and when run will generate 15745the output @code{X was not clobbered}. 15746 15747@node Effect of Convention on Representation 15748@section Effect of Convention on Representation 15749@cindex Convention, effect on representation 15750 15751@noindent 15752Normally the specification of a foreign language convention for a type or 15753an object has no effect on the chosen representation. In particular, the 15754representation chosen for data in GNAT generally meets the standard system 15755conventions, and for example records are laid out in a manner that is 15756consistent with C@. This means that specifying convention C (for example) 15757has no effect. 15758 15759There are four exceptions to this general rule: 15760 15761@itemize @bullet 15762 15763@item Convention Fortran and array subtypes 15764If pragma Convention Fortran is specified for an array subtype, then in 15765accordance with the implementation advice in section 3.6.2(11) of the 15766Ada Reference Manual, the array will be stored in a Fortran-compatible 15767column-major manner, instead of the normal default row-major order. 15768 15769@item Convention C and enumeration types 15770GNAT normally stores enumeration types in 8, 16, or 32 bits as required 15771to accommodate all values of the type. For example, for the enumeration 15772type declared by: 15773 15774@smallexample @c ada 15775 type Color is (Red, Green, Blue); 15776@end smallexample 15777 15778@noindent 157798 bits is sufficient to store all values of the type, so by default, objects 15780of type @code{Color} will be represented using 8 bits. However, normal C 15781convention is to use 32 bits for all enum values in C, since enum values 15782are essentially of type int. If pragma @code{Convention C} is specified for an 15783Ada enumeration type, then the size is modified as necessary (usually to 1578432 bits) to be consistent with the C convention for enum values. 15785 15786Note that this treatment applies only to types. If Convention C is given for 15787an enumeration object, where the enumeration type is not Convention C, then 15788Object_Size bits are allocated. For example, for a normal enumeration type, 15789with less than 256 elements, only 8 bits will be allocated for the object. 15790Since this may be a surprise in terms of what C expects, GNAT will issue a 15791warning in this situation. The warning can be suppressed by giving an explicit 15792size clause specifying the desired size. 15793 15794@item Convention C/Fortran and Boolean types 15795In C, the usual convention for boolean values, that is values used for 15796conditions, is that zero represents false, and nonzero values represent 15797true. In Ada, the normal convention is that two specific values, typically 157980/1, are used to represent false/true respectively. 15799 15800Fortran has a similar convention for @code{LOGICAL} values (any nonzero 15801value represents true). 15802 15803To accommodate the Fortran and C conventions, if a pragma Convention specifies 15804C or Fortran convention for a derived Boolean, as in the following example: 15805 15806@smallexample @c ada 15807 type C_Switch is new Boolean; 15808 pragma Convention (C, C_Switch); 15809@end smallexample 15810 15811@noindent 15812then the GNAT generated code will treat any nonzero value as true. For truth 15813values generated by GNAT, the conventional value 1 will be used for True, but 15814when one of these values is read, any nonzero value is treated as True. 15815 15816@item Access types on OpenVMS 15817For 64-bit OpenVMS systems, access types (other than those for unconstrained 15818arrays) are 64-bits long. An exception to this rule is for the case of 15819C-convention access types where there is no explicit size clause present (or 15820inherited for derived types). In this case, GNAT chooses to make these 15821pointers 32-bits, which provides an easier path for migration of 32-bit legacy 15822code. size clause specifying 64-bits must be used to obtain a 64-bit pointer. 15823 15824@end itemize 15825 15826@node Conventions and Anonymous Access Types 15827@section Conventions and Anonymous Access Types 15828@cindex Anonymous access types 15829@cindex Convention for anonymous access types 15830 15831The RM is not entirely clear on convention handling in a number of cases, 15832and in particular, it is not clear on the convention to be given to 15833anonymous access types in general, and in particular what is to be 15834done for the case of anonymous access-to-subprogram. 15835 15836In GNAT, we decide that if an explicit Convention is applied 15837to an object or component, and its type is such an anonymous type, 15838then the convention will apply to this anonymous type as well. This 15839seems to make sense since it is anomolous in any case to have a 15840different convention for an object and its type, and there is clearly 15841no way to explicitly specify a convention for an anonymous type, since 15842it doesn't have a name to specify! 15843 15844Furthermore, we decide that if a convention is applied to a record type, 15845then this convention is inherited by any of its components that are of an 15846anonymous access type which do not have an explicitly specified convention. 15847 15848The following program shows these conventions in action: 15849 15850@smallexample @c ada 15851package ConvComp is 15852 type Foo is range 1 .. 10; 15853 type T1 is record 15854 A : access function (X : Foo) return Integer; 15855 B : Integer; 15856 end record; 15857 pragma Convention (C, T1); 15858 15859 type T2 is record 15860 A : access function (X : Foo) return Integer; 15861 pragma Convention (C, A); 15862 B : Integer; 15863 end record; 15864 pragma Convention (COBOL, T2); 15865 15866 type T3 is record 15867 A : access function (X : Foo) return Integer; 15868 pragma Convention (COBOL, A); 15869 B : Integer; 15870 end record; 15871 pragma Convention (C, T3); 15872 15873 type T4 is record 15874 A : access function (X : Foo) return Integer; 15875 B : Integer; 15876 end record; 15877 pragma Convention (COBOL, T4); 15878 15879 function F (X : Foo) return Integer; 15880 pragma Convention (C, F); 15881 15882 function F (X : Foo) return Integer is (13); 15883 15884 TV1 : T1 := (F'Access, 12); -- OK 15885 TV2 : T2 := (F'Access, 13); -- OK 15886 15887 TV3 : T3 := (F'Access, 13); -- ERROR 15888 | 15889>>> subprogram "F" has wrong convention 15890>>> does not match access to subprogram declared at line 17 15891 38. TV4 : T4 := (F'Access, 13); -- ERROR 15892 | 15893>>> subprogram "F" has wrong convention 15894>>> does not match access to subprogram declared at line 24 15895 39. end ConvComp; 15896@end smallexample 15897 15898@node Determining the Representations chosen by GNAT 15899@section Determining the Representations chosen by GNAT 15900@cindex Representation, determination of 15901@cindex @option{-gnatR} switch 15902 15903@noindent 15904Although the descriptions in this section are intended to be complete, it is 15905often easier to simply experiment to see what GNAT accepts and what the 15906effect is on the layout of types and objects. 15907 15908As required by the Ada RM, if a representation clause is not accepted, then 15909it must be rejected as illegal by the compiler. However, when a 15910representation clause or pragma is accepted, there can still be questions 15911of what the compiler actually does. For example, if a partial record 15912representation clause specifies the location of some components and not 15913others, then where are the non-specified components placed? Or if pragma 15914@code{Pack} is used on a record, then exactly where are the resulting 15915fields placed? The section on pragma @code{Pack} in this chapter can be 15916used to answer the second question, but it is often easier to just see 15917what the compiler does. 15918 15919For this purpose, GNAT provides the option @option{-gnatR}. If you compile 15920with this option, then the compiler will output information on the actual 15921representations chosen, in a format similar to source representation 15922clauses. For example, if we compile the package: 15923 15924@smallexample @c ada 15925package q is 15926 type r (x : boolean) is tagged record 15927 case x is 15928 when True => S : String (1 .. 100); 15929 when False => null; 15930 end case; 15931 end record; 15932 15933 type r2 is new r (false) with record 15934 y2 : integer; 15935 end record; 15936 15937 for r2 use record 15938 y2 at 16 range 0 .. 31; 15939 end record; 15940 15941 type x is record 15942 y : character; 15943 end record; 15944 15945 type x1 is array (1 .. 10) of x; 15946 for x1'component_size use 11; 15947 15948 type ia is access integer; 15949 15950 type Rb1 is array (1 .. 13) of Boolean; 15951 pragma Pack (rb1); 15952 15953 type Rb2 is array (1 .. 65) of Boolean; 15954 pragma Pack (rb2); 15955 15956 type x2 is record 15957 l1 : Boolean; 15958 l2 : Duration; 15959 l3 : Float; 15960 l4 : Boolean; 15961 l5 : Rb1; 15962 l6 : Rb2; 15963 end record; 15964 pragma Pack (x2); 15965end q; 15966@end smallexample 15967 15968@noindent 15969using the switch @option{-gnatR} we obtain the following output: 15970 15971@smallexample 15972Representation information for unit q 15973------------------------------------- 15974 15975for r'Size use ??; 15976for r'Alignment use 4; 15977for r use record 15978 x at 4 range 0 .. 7; 15979 _tag at 0 range 0 .. 31; 15980 s at 5 range 0 .. 799; 15981end record; 15982 15983for r2'Size use 160; 15984for r2'Alignment use 4; 15985for r2 use record 15986 x at 4 range 0 .. 7; 15987 _tag at 0 range 0 .. 31; 15988 _parent at 0 range 0 .. 63; 15989 y2 at 16 range 0 .. 31; 15990end record; 15991 15992for x'Size use 8; 15993for x'Alignment use 1; 15994for x use record 15995 y at 0 range 0 .. 7; 15996end record; 15997 15998for x1'Size use 112; 15999for x1'Alignment use 1; 16000for x1'Component_Size use 11; 16001 16002for rb1'Size use 13; 16003for rb1'Alignment use 2; 16004for rb1'Component_Size use 1; 16005 16006for rb2'Size use 72; 16007for rb2'Alignment use 1; 16008for rb2'Component_Size use 1; 16009 16010for x2'Size use 224; 16011for x2'Alignment use 4; 16012for x2 use record 16013 l1 at 0 range 0 .. 0; 16014 l2 at 0 range 1 .. 64; 16015 l3 at 12 range 0 .. 31; 16016 l4 at 16 range 0 .. 0; 16017 l5 at 16 range 1 .. 13; 16018 l6 at 18 range 0 .. 71; 16019end record; 16020@end smallexample 16021 16022@noindent 16023The Size values are actually the Object_Size, i.e.@: the default size that 16024will be allocated for objects of the type. 16025The ?? size for type r indicates that we have a variant record, and the 16026actual size of objects will depend on the discriminant value. 16027 16028The Alignment values show the actual alignment chosen by the compiler 16029for each record or array type. 16030 16031The record representation clause for type r shows where all fields 16032are placed, including the compiler generated tag field (whose location 16033cannot be controlled by the programmer). 16034 16035The record representation clause for the type extension r2 shows all the 16036fields present, including the parent field, which is a copy of the fields 16037of the parent type of r2, i.e.@: r1. 16038 16039The component size and size clauses for types rb1 and rb2 show 16040the exact effect of pragma @code{Pack} on these arrays, and the record 16041representation clause for type x2 shows how pragma @code{Pack} affects 16042this record type. 16043 16044In some cases, it may be useful to cut and paste the representation clauses 16045generated by the compiler into the original source to fix and guarantee 16046the actual representation to be used. 16047 16048@node Standard Library Routines 16049@chapter Standard Library Routines 16050 16051@noindent 16052The Ada Reference Manual contains in Annex A a full description of an 16053extensive set of standard library routines that can be used in any Ada 16054program, and which must be provided by all Ada compilers. They are 16055analogous to the standard C library used by C programs. 16056 16057GNAT implements all of the facilities described in annex A, and for most 16058purposes the description in the Ada Reference Manual, or appropriate Ada 16059text book, will be sufficient for making use of these facilities. 16060 16061In the case of the input-output facilities, 16062@xref{The Implementation of Standard I/O}, 16063gives details on exactly how GNAT interfaces to the 16064file system. For the remaining packages, the Ada Reference Manual 16065should be sufficient. The following is a list of the packages included, 16066together with a brief description of the functionality that is provided. 16067 16068For completeness, references are included to other predefined library 16069routines defined in other sections of the Ada Reference Manual (these are 16070cross-indexed from Annex A). For further details see the relevant 16071package declarations in the run-time library. In particular, a few units 16072are not implemented, as marked by the presence of pragma Unimplemented_Unit, 16073and in this case the package declaration contains comments explaining why 16074the unit is not implemented. 16075 16076@table @code 16077@item Ada (A.2) 16078This is a parent package for all the standard library packages. It is 16079usually included implicitly in your program, and itself contains no 16080useful data or routines. 16081 16082@item Ada.Assertions (11.4.2) 16083@code{Assertions} provides the @code{Assert} subprograms, and also 16084the declaration of the @code{Assertion_Error} exception. 16085 16086@item Ada.Asynchronous_Task_Control (D.11) 16087@code{Asynchronous_Task_Control} provides low level facilities for task 16088synchronization. It is typically not implemented. See package spec for details. 16089 16090@item Ada.Calendar (9.6) 16091@code{Calendar} provides time of day access, and routines for 16092manipulating times and durations. 16093 16094@item Ada.Calendar.Arithmetic (9.6.1) 16095This package provides additional arithmetic 16096operations for @code{Calendar}. 16097 16098@item Ada.Calendar.Formatting (9.6.1) 16099This package provides formatting operations for @code{Calendar}. 16100 16101@item Ada.Calendar.Time_Zones (9.6.1) 16102This package provides additional @code{Calendar} facilities 16103for handling time zones. 16104 16105@item Ada.Characters (A.3.1) 16106This is a dummy parent package that contains no useful entities 16107 16108@item Ada.Characters.Conversions (A.3.2) 16109This package provides character conversion functions. 16110 16111@item Ada.Characters.Handling (A.3.2) 16112This package provides some basic character handling capabilities, 16113including classification functions for classes of characters (e.g.@: test 16114for letters, or digits). 16115 16116@item Ada.Characters.Latin_1 (A.3.3) 16117This package includes a complete set of definitions of the characters 16118that appear in type CHARACTER@. It is useful for writing programs that 16119will run in international environments. For example, if you want an 16120upper case E with an acute accent in a string, it is often better to use 16121the definition of @code{UC_E_Acute} in this package. Then your program 16122will print in an understandable manner even if your environment does not 16123support these extended characters. 16124 16125@item Ada.Command_Line (A.15) 16126This package provides access to the command line parameters and the name 16127of the current program (analogous to the use of @code{argc} and @code{argv} 16128in C), and also allows the exit status for the program to be set in a 16129system-independent manner. 16130 16131@item Ada.Complex_Text_IO (G.1.3) 16132This package provides text input and output of complex numbers. 16133 16134@item Ada.Containers (A.18.1) 16135A top level package providing a few basic definitions used by all the 16136following specific child packages that provide specific kinds of 16137containers. 16138 16139@item Ada.Containers.Bounded_Priority_Queues (A.18.31) 16140 16141@item Ada.Containers.Bounded_Synchronized_Queues (A.18.29) 16142 16143@item Ada.Containers.Doubly_Linked_Lists (A.18.3) 16144 16145@item Ada.Containers.Generic_Array_Sort (A.18.26) 16146 16147@item Ada.Containers.Generic_Constrained_Array_Sort (A.18.26) 16148 16149@item Ada.Containers.Generic_Sort (A.18.26) 16150 16151@item Ada.Containers.Hashed_Maps (A.18.5) 16152 16153@item Ada.Containers.Hashed_Sets (A.18.8) 16154 16155@item Ada.Containers.Indefinite_Doubly_Linked_Lists (A.18.12) 16156 16157@item Ada.Containers.Indefinite_Hashed_Maps (A.18.13) 16158 16159@item Ada.Containers.Indefinite_Hashed_Sets (A.18.15) 16160 16161@item Ada.Containers.Indefinite_Holders (A.18.18) 16162 16163@item Ada.Containers.Indefinite_Multiway_Trees (A.18.17) 16164 16165@item Ada.Containers.Indefinite_Ordered_Maps (A.18.14) 16166 16167@item Ada.Containers.Indefinite_Ordered_Sets (A.18.16) 16168 16169@item Ada.Containers.Indefinite_Vectors (A.18.11) 16170 16171@item Ada.Containers.Multiway_Trees (A.18.10) 16172 16173@item Ada.Containers.Ordered_Maps (A.18.6) 16174 16175@item Ada.Containers.Ordered_Sets (A.18.9) 16176 16177@item Ada.Containers.Synchronized_Queue_Interfaces (A.18.27) 16178 16179@item Ada.Containers.Unbounded_Priority_Queues (A.18.30) 16180 16181@item Ada.Containers.Unbounded_Synchronized_Queues (A.18.28) 16182 16183@item Ada.Containers.Vectors (A.18.2) 16184 16185@item Ada.Directories (A.16) 16186This package provides operations on directories. 16187 16188@item Ada.Directories.Hierarchical_File_Names (A.16.1) 16189This package provides additional directory operations handling 16190hiearchical file names. 16191 16192@item Ada.Directories.Information (A.16) 16193This is an implementation defined package for additional directory 16194operations, which is not implemented in GNAT. 16195 16196@item Ada.Decimal (F.2) 16197This package provides constants describing the range of decimal numbers 16198implemented, and also a decimal divide routine (analogous to the COBOL 16199verb DIVIDE @dots{} GIVING @dots{} REMAINDER @dots{}) 16200 16201@item Ada.Direct_IO (A.8.4) 16202This package provides input-output using a model of a set of records of 16203fixed-length, containing an arbitrary definite Ada type, indexed by an 16204integer record number. 16205 16206@item Ada.Dispatching (D.2.1) 16207A parent package containing definitions for task dispatching operations. 16208 16209@item Ada.Dispatching.EDF (D.2.6) 16210Not implemented in GNAT. 16211 16212@item Ada.Dispatching.Non_Preemptive (D.2.4) 16213Not implemented in GNAT. 16214 16215@item Ada.Dispatching.Round_Robin (D.2.5) 16216Not implemented in GNAT. 16217 16218@item Ada.Dynamic_Priorities (D.5) 16219This package allows the priorities of a task to be adjusted dynamically 16220as the task is running. 16221 16222@item Ada.Environment_Variables (A.17) 16223This package provides facilities for accessing environment variables. 16224 16225@item Ada.Exceptions (11.4.1) 16226This package provides additional information on exceptions, and also 16227contains facilities for treating exceptions as data objects, and raising 16228exceptions with associated messages. 16229 16230@item Ada.Execution_Time (D.14) 16231Not implemented in GNAT. 16232 16233@item Ada.Execution_Time.Group_Budgets (D.14.2) 16234Not implemented in GNAT. 16235 16236@item Ada.Execution_Time.Timers (D.14.1)' 16237Not implemented in GNAT. 16238 16239@item Ada.Finalization (7.6) 16240This package contains the declarations and subprograms to support the 16241use of controlled types, providing for automatic initialization and 16242finalization (analogous to the constructors and destructors of C++). 16243 16244@item Ada.Float_Text_IO (A.10.9) 16245A library level instantiation of Text_IO.Float_IO for type Float. 16246 16247@item Ada.Float_Wide_Text_IO (A.10.9) 16248A library level instantiation of Wide_Text_IO.Float_IO for type Float. 16249 16250@item Ada.Float_Wide_Wide_Text_IO (A.10.9) 16251A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. 16252 16253@item Ada.Integer_Text_IO (A.10.9) 16254A library level instantiation of Text_IO.Integer_IO for type Integer. 16255 16256@item Ada.Integer_Wide_Text_IO (A.10.9) 16257A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. 16258 16259@item Ada.Integer_Wide_Wide_Text_IO (A.10.9) 16260A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. 16261 16262@item Ada.Interrupts (C.3.2) 16263This package provides facilities for interfacing to interrupts, which 16264includes the set of signals or conditions that can be raised and 16265recognized as interrupts. 16266 16267@item Ada.Interrupts.Names (C.3.2) 16268This package provides the set of interrupt names (actually signal 16269or condition names) that can be handled by GNAT@. 16270 16271@item Ada.IO_Exceptions (A.13) 16272This package defines the set of exceptions that can be raised by use of 16273the standard IO packages. 16274 16275@item Ada.Iterator_Interfaces (5.5.1) 16276This package provides a generic interface to generalized iterators. 16277 16278@item Ada.Locales (A.19) 16279This package provides declarations providing information (Language 16280and Country) about the current locale. 16281 16282@item Ada.Numerics 16283This package contains some standard constants and exceptions used 16284throughout the numerics packages. Note that the constants pi and e are 16285defined here, and it is better to use these definitions than rolling 16286your own. 16287 16288@item Ada.Numerics.Complex_Arrays (G.3.2) 16289Provides operations on arrays of complex numbers. 16290 16291@item Ada.Numerics.Complex_Elementary_Functions 16292Provides the implementation of standard elementary functions (such as 16293log and trigonometric functions) operating on complex numbers using the 16294standard @code{Float} and the @code{Complex} and @code{Imaginary} types 16295created by the package @code{Numerics.Complex_Types}. 16296 16297@item Ada.Numerics.Complex_Types 16298This is a predefined instantiation of 16299@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to 16300build the type @code{Complex} and @code{Imaginary}. 16301 16302@item Ada.Numerics.Discrete_Random 16303This generic package provides a random number generator suitable for generating 16304uniformly distributed values of a specified discrete subtype. 16305 16306@item Ada.Numerics.Float_Random 16307This package provides a random number generator suitable for generating 16308uniformly distributed floating point values in the unit interval. 16309 16310@item Ada.Numerics.Generic_Complex_Elementary_Functions 16311This is a generic version of the package that provides the 16312implementation of standard elementary functions (such as log and 16313trigonometric functions) for an arbitrary complex type. 16314 16315The following predefined instantiations of this package are provided: 16316 16317@table @code 16318@item Short_Float 16319@code{Ada.Numerics.Short_Complex_Elementary_Functions} 16320@item Float 16321@code{Ada.Numerics.Complex_Elementary_Functions} 16322@item Long_Float 16323@code{Ada.Numerics.Long_Complex_Elementary_Functions} 16324@end table 16325 16326@item Ada.Numerics.Generic_Complex_Types 16327This is a generic package that allows the creation of complex types, 16328with associated complex arithmetic operations. 16329 16330The following predefined instantiations of this package exist 16331@table @code 16332@item Short_Float 16333@code{Ada.Numerics.Short_Complex_Complex_Types} 16334@item Float 16335@code{Ada.Numerics.Complex_Complex_Types} 16336@item Long_Float 16337@code{Ada.Numerics.Long_Complex_Complex_Types} 16338@end table 16339 16340@item Ada.Numerics.Generic_Elementary_Functions 16341This is a generic package that provides the implementation of standard 16342elementary functions (such as log an trigonometric functions) for an 16343arbitrary float type. 16344 16345The following predefined instantiations of this package exist 16346 16347@table @code 16348@item Short_Float 16349@code{Ada.Numerics.Short_Elementary_Functions} 16350@item Float 16351@code{Ada.Numerics.Elementary_Functions} 16352@item Long_Float 16353@code{Ada.Numerics.Long_Elementary_Functions} 16354@end table 16355 16356@item Ada.Numerics.Generic_Real_Arrays (G.3.1) 16357Generic operations on arrays of reals 16358 16359@item Ada.Numerics.Real_Arrays (G.3.1) 16360Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). 16361 16362@item Ada.Real_Time (D.8) 16363This package provides facilities similar to those of @code{Calendar}, but 16364operating with a finer clock suitable for real time control. Note that 16365annex D requires that there be no backward clock jumps, and GNAT generally 16366guarantees this behavior, but of course if the external clock on which 16367the GNAT runtime depends is deliberately reset by some external event, 16368then such a backward jump may occur. 16369 16370@item Ada.Real_Time.Timing_Events (D.15) 16371Not implemented in GNAT. 16372 16373@item Ada.Sequential_IO (A.8.1) 16374This package provides input-output facilities for sequential files, 16375which can contain a sequence of values of a single type, which can be 16376any Ada type, including indefinite (unconstrained) types. 16377 16378@item Ada.Storage_IO (A.9) 16379This package provides a facility for mapping arbitrary Ada types to and 16380from a storage buffer. It is primarily intended for the creation of new 16381IO packages. 16382 16383@item Ada.Streams (13.13.1) 16384This is a generic package that provides the basic support for the 16385concept of streams as used by the stream attributes (@code{Input}, 16386@code{Output}, @code{Read} and @code{Write}). 16387 16388@item Ada.Streams.Stream_IO (A.12.1) 16389This package is a specialization of the type @code{Streams} defined in 16390package @code{Streams} together with a set of operations providing 16391Stream_IO capability. The Stream_IO model permits both random and 16392sequential access to a file which can contain an arbitrary set of values 16393of one or more Ada types. 16394 16395@item Ada.Strings (A.4.1) 16396This package provides some basic constants used by the string handling 16397packages. 16398 16399@item Ada.Strings.Bounded (A.4.4) 16400This package provides facilities for handling variable length 16401strings. The bounded model requires a maximum length. It is thus 16402somewhat more limited than the unbounded model, but avoids the use of 16403dynamic allocation or finalization. 16404 16405@item Ada.Strings.Bounded.Equal_Case_Insensitive (A.4.10) 16406Provides case-insensitive comparisons of bounded strings 16407 16408@item Ada.Strings.Bounded.Hash (A.4.9) 16409This package provides a generic hash function for bounded strings 16410 16411@item Ada.Strings.Bounded.Hash_Case_Insensitive (A.4.9) 16412This package provides a generic hash function for bounded strings that 16413converts the string to be hashed to lower case. 16414 16415@item Ada.Strings.Bounded.Less_Case_Insensitive (A.4.10) 16416This package provides a comparison function for bounded strings that works 16417in a case insensitive manner by converting to lower case before the comparison. 16418 16419@item Ada.Strings.Fixed (A.4.3) 16420This package provides facilities for handling fixed length strings. 16421 16422@item Ada.Strings.Fixed.Equal_Case_Insensitive (A.4.10) 16423This package provides an equality function for fixed strings that compares 16424the strings after converting both to lower case. 16425 16426@item Ada.Strings.Fixed.Hash_Case_Insensitive (A.4.9) 16427This package provides a case insensitive hash function for fixed strings that 16428converts the string to lower case before computing the hash. 16429 16430@item Ada.Strings.Fixed.Less_Case_Insensitive (A.4.10) 16431This package provides a comparison function for fixed strings that works 16432in a case insensitive manner by converting to lower case before the comparison. 16433 16434Ada.Strings.Hash (A.4.9) 16435This package provides a hash function for strings. 16436 16437Ada.Strings.Hash_Case_Insensitive (A.4.9) 16438This package provides a hash function for strings that is case insensitive. 16439The string is converted to lower case before computing the hash. 16440 16441@item Ada.Strings.Less_Case_Insensitive (A.4.10) 16442This package provides a comparison function for\strings that works 16443in a case insensitive manner by converting to lower case before the comparison. 16444 16445@item Ada.Strings.Maps (A.4.2) 16446This package provides facilities for handling character mappings and 16447arbitrarily defined subsets of characters. For instance it is useful in 16448defining specialized translation tables. 16449 16450@item Ada.Strings.Maps.Constants (A.4.6) 16451This package provides a standard set of predefined mappings and 16452predefined character sets. For example, the standard upper to lower case 16453conversion table is found in this package. Note that upper to lower case 16454conversion is non-trivial if you want to take the entire set of 16455characters, including extended characters like E with an acute accent, 16456into account. You should use the mappings in this package (rather than 16457adding 32 yourself) to do case mappings. 16458 16459@item Ada.Strings.Unbounded (A.4.5) 16460This package provides facilities for handling variable length 16461strings. The unbounded model allows arbitrary length strings, but 16462requires the use of dynamic allocation and finalization. 16463 16464@item Ada.Strings.Unbounded.Equal_Case_Insensitive (A.4.10) 16465Provides case-insensitive comparisons of unbounded strings 16466 16467@item Ada.Strings.Unbounded.Hash (A.4.9) 16468This package provides a generic hash function for unbounded strings 16469 16470@item Ada.Strings.Unbounded.Hash_Case_Insensitive (A.4.9) 16471This package provides a generic hash function for unbounded strings that 16472converts the string to be hashed to lower case. 16473 16474@item Ada.Strings.Unbounded.Less_Case_Insensitive (A.4.10) 16475This package provides a comparison function for unbounded strings that works 16476in a case insensitive manner by converting to lower case before the comparison. 16477 16478@item Ada.Strings.UTF_Encoding (A.4.11) 16479This package provides basic definitions for dealing with UTF-encoded strings. 16480 16481@item Ada.Strings.UTF_Encoding.Conversions (A.4.11) 16482This package provides conversion functions for UTF-encoded strings. 16483 16484@item Ada.Strings.UTF_Encoding.Strings (A.4.11) 16485@itemx Ada.Strings.UTF_Encoding.Wide_Strings (A.4.11) 16486@itemx Ada.Strings.UTF_Encoding.Wide_Wide_Strings (A.4.11) 16487These packages provide facilities for handling UTF encodings for 16488Strings, Wide_Strings and Wide_Wide_Strings. 16489 16490@item Ada.Strings.Wide_Bounded (A.4.7) 16491@itemx Ada.Strings.Wide_Fixed (A.4.7) 16492@itemx Ada.Strings.Wide_Maps (A.4.7) 16493@itemx Ada.Strings.Wide_Unbounded (A.4.7) 16494These packages provide analogous capabilities to the corresponding 16495packages without @samp{Wide_} in the name, but operate with the types 16496@code{Wide_String} and @code{Wide_Character} instead of @code{String} 16497and @code{Character}. Versions of all the child packages are available. 16498 16499@item Ada.Strings.Wide_Wide_Bounded (A.4.7) 16500@itemx Ada.Strings.Wide_Wide_Fixed (A.4.7) 16501@itemx Ada.Strings.Wide_Wide_Maps (A.4.7) 16502@itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7) 16503These packages provide analogous capabilities to the corresponding 16504packages without @samp{Wide_} in the name, but operate with the types 16505@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead 16506of @code{String} and @code{Character}. 16507 16508@item Ada.Synchronous_Barriers (D.10.1) 16509This package provides facilities for synchronizing tasks at a low level 16510with barriers. 16511 16512@item Ada.Synchronous_Task_Control (D.10) 16513This package provides some standard facilities for controlling task 16514communication in a synchronous manner. 16515 16516@item Ada.Synchronous_Task_Control.EDF (D.10) 16517Not implemented in GNAT. 16518 16519@item Ada.Tags 16520This package contains definitions for manipulation of the tags of tagged 16521values. 16522 16523@item Ada.Tags.Generic_Dispatching_Constructor (3.9) 16524This package provides a way of constructing tagged class-wide values given 16525only the tag value. 16526 16527@item Ada.Task_Attributes (C.7.2) 16528This package provides the capability of associating arbitrary 16529task-specific data with separate tasks. 16530 16531@item Ada.Task_Identifification (C.7.1) 16532This package provides capabilities for task identification. 16533 16534@item Ada.Task_Termination (C.7.3) 16535This package provides control over task termination. 16536 16537@item Ada.Text_IO 16538This package provides basic text input-output capabilities for 16539character, string and numeric data. The subpackages of this 16540package are listed next. Note that although these are defined 16541as subpackages in the RM, they are actually transparently 16542implemented as child packages in GNAT, meaning that they 16543are only loaded if needed. 16544 16545@item Ada.Text_IO.Decimal_IO 16546Provides input-output facilities for decimal fixed-point types 16547 16548@item Ada.Text_IO.Enumeration_IO 16549Provides input-output facilities for enumeration types. 16550 16551@item Ada.Text_IO.Fixed_IO 16552Provides input-output facilities for ordinary fixed-point types. 16553 16554@item Ada.Text_IO.Float_IO 16555Provides input-output facilities for float types. The following 16556predefined instantiations of this generic package are available: 16557 16558@table @code 16559@item Short_Float 16560@code{Short_Float_Text_IO} 16561@item Float 16562@code{Float_Text_IO} 16563@item Long_Float 16564@code{Long_Float_Text_IO} 16565@end table 16566 16567@item Ada.Text_IO.Integer_IO 16568Provides input-output facilities for integer types. The following 16569predefined instantiations of this generic package are available: 16570 16571@table @code 16572@item Short_Short_Integer 16573@code{Ada.Short_Short_Integer_Text_IO} 16574@item Short_Integer 16575@code{Ada.Short_Integer_Text_IO} 16576@item Integer 16577@code{Ada.Integer_Text_IO} 16578@item Long_Integer 16579@code{Ada.Long_Integer_Text_IO} 16580@item Long_Long_Integer 16581@code{Ada.Long_Long_Integer_Text_IO} 16582@end table 16583 16584@item Ada.Text_IO.Modular_IO 16585Provides input-output facilities for modular (unsigned) types. 16586 16587@item Ada.Text_IO.Bounded_IO (A.10.11) 16588Provides input-output facilities for bounded strings. 16589 16590@item Ada.Text_IO.Complex_IO (G.1.3) 16591This package provides basic text input-output capabilities for complex 16592data. 16593 16594@item Ada.Text_IO.Editing (F.3.3) 16595This package contains routines for edited output, analogous to the use 16596of pictures in COBOL@. The picture formats used by this package are a 16597close copy of the facility in COBOL@. 16598 16599@item Ada.Text_IO.Text_Streams (A.12.2) 16600This package provides a facility that allows Text_IO files to be treated 16601as streams, so that the stream attributes can be used for writing 16602arbitrary data, including binary data, to Text_IO files. 16603 16604@item Ada.Text_IO.Unbounded_IO (A.10.12) 16605This package provides input-output facilities for unbounded strings. 16606 16607@item Ada.Unchecked_Conversion (13.9) 16608This generic package allows arbitrary conversion from one type to 16609another of the same size, providing for breaking the type safety in 16610special circumstances. 16611 16612If the types have the same Size (more accurately the same Value_Size), 16613then the effect is simply to transfer the bits from the source to the 16614target type without any modification. This usage is well defined, and 16615for simple types whose representation is typically the same across 16616all implementations, gives a portable method of performing such 16617conversions. 16618 16619If the types do not have the same size, then the result is implementation 16620defined, and thus may be non-portable. The following describes how GNAT 16621handles such unchecked conversion cases. 16622 16623If the types are of different sizes, and are both discrete types, then 16624the effect is of a normal type conversion without any constraint checking. 16625In particular if the result type has a larger size, the result will be 16626zero or sign extended. If the result type has a smaller size, the result 16627will be truncated by ignoring high order bits. 16628 16629If the types are of different sizes, and are not both discrete types, 16630then the conversion works as though pointers were created to the source 16631and target, and the pointer value is converted. The effect is that bits 16632are copied from successive low order storage units and bits of the source 16633up to the length of the target type. 16634 16635A warning is issued if the lengths differ, since the effect in this 16636case is implementation dependent, and the above behavior may not match 16637that of some other compiler. 16638 16639A pointer to one type may be converted to a pointer to another type using 16640unchecked conversion. The only case in which the effect is undefined is 16641when one or both pointers are pointers to unconstrained array types. In 16642this case, the bounds information may get incorrectly transferred, and in 16643particular, GNAT uses double size pointers for such types, and it is 16644meaningless to convert between such pointer types. GNAT will issue a 16645warning if the alignment of the target designated type is more strict 16646than the alignment of the source designated type (since the result may 16647be unaligned in this case). 16648 16649A pointer other than a pointer to an unconstrained array type may be 16650converted to and from System.Address. Such usage is common in Ada 83 16651programs, but note that Ada.Address_To_Access_Conversions is the 16652preferred method of performing such conversions in Ada 95 and Ada 2005. 16653Neither 16654unchecked conversion nor Ada.Address_To_Access_Conversions should be 16655used in conjunction with pointers to unconstrained objects, since 16656the bounds information cannot be handled correctly in this case. 16657 16658@item Ada.Unchecked_Deallocation (13.11.2) 16659This generic package allows explicit freeing of storage previously 16660allocated by use of an allocator. 16661 16662@item Ada.Wide_Text_IO (A.11) 16663This package is similar to @code{Ada.Text_IO}, except that the external 16664file supports wide character representations, and the internal types are 16665@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 16666and @code{String}. The corresponding set of nested packages and child 16667packages are defined. 16668 16669@item Ada.Wide_Wide_Text_IO (A.11) 16670This package is similar to @code{Ada.Text_IO}, except that the external 16671file supports wide character representations, and the internal types are 16672@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 16673and @code{String}. The corresponding set of nested packages and child 16674packages are defined. 16675 16676@end table 16677 16678For packages in Interfaces and System, all the RM defined packages are 16679available in GNAT, see the Ada 2012 RM for full details. 16680 16681@node The Implementation of Standard I/O 16682@chapter The Implementation of Standard I/O 16683 16684@noindent 16685GNAT implements all the required input-output facilities described in 16686A.6 through A.14. These sections of the Ada Reference Manual describe the 16687required behavior of these packages from the Ada point of view, and if 16688you are writing a portable Ada program that does not need to know the 16689exact manner in which Ada maps to the outside world when it comes to 16690reading or writing external files, then you do not need to read this 16691chapter. As long as your files are all regular files (not pipes or 16692devices), and as long as you write and read the files only from Ada, the 16693description in the Ada Reference Manual is sufficient. 16694 16695However, if you want to do input-output to pipes or other devices, such 16696as the keyboard or screen, or if the files you are dealing with are 16697either generated by some other language, or to be read by some other 16698language, then you need to know more about the details of how the GNAT 16699implementation of these input-output facilities behaves. 16700 16701In this chapter we give a detailed description of exactly how GNAT 16702interfaces to the file system. As always, the sources of the system are 16703available to you for answering questions at an even more detailed level, 16704but for most purposes the information in this chapter will suffice. 16705 16706Another reason that you may need to know more about how input-output is 16707implemented arises when you have a program written in mixed languages 16708where, for example, files are shared between the C and Ada sections of 16709the same program. GNAT provides some additional facilities, in the form 16710of additional child library packages, that facilitate this sharing, and 16711these additional facilities are also described in this chapter. 16712 16713@menu 16714* Standard I/O Packages:: 16715* FORM Strings:: 16716* Direct_IO:: 16717* Sequential_IO:: 16718* Text_IO:: 16719* Wide_Text_IO:: 16720* Wide_Wide_Text_IO:: 16721* Stream_IO:: 16722* Text Translation:: 16723* Shared Files:: 16724* Filenames encoding:: 16725* Open Modes:: 16726* Operations on C Streams:: 16727* Interfacing to C Streams:: 16728@end menu 16729 16730@node Standard I/O Packages 16731@section Standard I/O Packages 16732 16733@noindent 16734The Standard I/O packages described in Annex A for 16735 16736@itemize @bullet 16737@item 16738Ada.Text_IO 16739@item 16740Ada.Text_IO.Complex_IO 16741@item 16742Ada.Text_IO.Text_Streams 16743@item 16744Ada.Wide_Text_IO 16745@item 16746Ada.Wide_Text_IO.Complex_IO 16747@item 16748Ada.Wide_Text_IO.Text_Streams 16749@item 16750Ada.Wide_Wide_Text_IO 16751@item 16752Ada.Wide_Wide_Text_IO.Complex_IO 16753@item 16754Ada.Wide_Wide_Text_IO.Text_Streams 16755@item 16756Ada.Stream_IO 16757@item 16758Ada.Sequential_IO 16759@item 16760Ada.Direct_IO 16761@end itemize 16762 16763@noindent 16764are implemented using the C 16765library streams facility; where 16766 16767@itemize @bullet 16768@item 16769All files are opened using @code{fopen}. 16770@item 16771All input/output operations use @code{fread}/@code{fwrite}. 16772@end itemize 16773 16774@noindent 16775There is no internal buffering of any kind at the Ada library level. The only 16776buffering is that provided at the system level in the implementation of the 16777library routines that support streams. This facilitates shared use of these 16778streams by mixed language programs. Note though that system level buffering is 16779explicitly enabled at elaboration of the standard I/O packages and that can 16780have an impact on mixed language programs, in particular those using I/O before 16781calling the Ada elaboration routine (e.g.@: adainit). It is recommended to call 16782the Ada elaboration routine before performing any I/O or when impractical, 16783flush the common I/O streams and in particular Standard_Output before 16784elaborating the Ada code. 16785 16786@node FORM Strings 16787@section FORM Strings 16788 16789@noindent 16790The format of a FORM string in GNAT is: 16791 16792@smallexample 16793"keyword=value,keyword=value,@dots{},keyword=value" 16794@end smallexample 16795 16796@noindent 16797where letters may be in upper or lower case, and there are no spaces 16798between values. The order of the entries is not important. Currently 16799the following keywords defined. 16800 16801@smallexample 16802TEXT_TRANSLATION=[YES|NO] 16803SHARED=[YES|NO] 16804WCEM=[n|h|u|s|e|8|b] 16805ENCODING=[UTF8|8BITS] 16806@end smallexample 16807 16808@noindent 16809The use of these parameters is described later in this section. If an 16810unrecognized keyword appears in a form string, it is silently ignored 16811and not considered invalid. 16812 16813@noindent 16814For OpenVMS additional FORM string keywords are available for use with 16815RMS services. The syntax is: 16816 16817@smallexample 16818VMS_RMS_Keys=(keyword=value,@dots{},keyword=value) 16819@end smallexample 16820 16821@noindent 16822The following RMS keywords and values are currently defined: 16823 16824@smallexample 16825Context=Force_Stream_Mode|Force_Record_Mode 16826@end smallexample 16827 16828@noindent 16829VMS RMS keys are silently ignored on non-VMS systems. On OpenVMS 16830unimplented RMS keywords, values, or invalid syntax will raise Use_Error. 16831 16832@node Direct_IO 16833@section Direct_IO 16834 16835@noindent 16836Direct_IO can only be instantiated for definite types. This is a 16837restriction of the Ada language, which means that the records are fixed 16838length (the length being determined by @code{@var{type}'Size}, rounded 16839up to the next storage unit boundary if necessary). 16840 16841The records of a Direct_IO file are simply written to the file in index 16842sequence, with the first record starting at offset zero, and subsequent 16843records following. There is no control information of any kind. For 16844example, if 32-bit integers are being written, each record takes 168454-bytes, so the record at index @var{K} starts at offset 16846(@var{K}@minus{}1)*4. 16847 16848There is no limit on the size of Direct_IO files, they are expanded as 16849necessary to accommodate whatever records are written to the file. 16850 16851@node Sequential_IO 16852@section Sequential_IO 16853 16854@noindent 16855Sequential_IO may be instantiated with either a definite (constrained) 16856or indefinite (unconstrained) type. 16857 16858For the definite type case, the elements written to the file are simply 16859the memory images of the data values with no control information of any 16860kind. The resulting file should be read using the same type, no validity 16861checking is performed on input. 16862 16863For the indefinite type case, the elements written consist of two 16864parts. First is the size of the data item, written as the memory image 16865of a @code{Interfaces.C.size_t} value, followed by the memory image of 16866the data value. The resulting file can only be read using the same 16867(unconstrained) type. Normal assignment checks are performed on these 16868read operations, and if these checks fail, @code{Data_Error} is 16869raised. In particular, in the array case, the lengths must match, and in 16870the variant record case, if the variable for a particular read operation 16871is constrained, the discriminants must match. 16872 16873Note that it is not possible to use Sequential_IO to write variable 16874length array items, and then read the data back into different length 16875arrays. For example, the following will raise @code{Data_Error}: 16876 16877@smallexample @c ada 16878 package IO is new Sequential_IO (String); 16879 F : IO.File_Type; 16880 S : String (1..4); 16881 @dots{} 16882 IO.Create (F) 16883 IO.Write (F, "hello!") 16884 IO.Reset (F, Mode=>In_File); 16885 IO.Read (F, S); 16886 Put_Line (S); 16887 16888@end smallexample 16889 16890@noindent 16891On some Ada implementations, this will print @code{hell}, but the program is 16892clearly incorrect, since there is only one element in the file, and that 16893element is the string @code{hello!}. 16894 16895In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved 16896using Stream_IO, and this is the preferred mechanism. In particular, the 16897above program fragment rewritten to use Stream_IO will work correctly. 16898 16899@node Text_IO 16900@section Text_IO 16901 16902@noindent 16903Text_IO files consist of a stream of characters containing the following 16904special control characters: 16905 16906@smallexample 16907LF (line feed, 16#0A#) Line Mark 16908FF (form feed, 16#0C#) Page Mark 16909@end smallexample 16910 16911@noindent 16912A canonical Text_IO file is defined as one in which the following 16913conditions are met: 16914 16915@itemize @bullet 16916@item 16917The character @code{LF} is used only as a line mark, i.e.@: to mark the end 16918of the line. 16919 16920@item 16921The character @code{FF} is used only as a page mark, i.e.@: to mark the 16922end of a page and consequently can appear only immediately following a 16923@code{LF} (line mark) character. 16924 16925@item 16926The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF} 16927(line mark, page mark). In the former case, the page mark is implicitly 16928assumed to be present. 16929@end itemize 16930 16931@noindent 16932A file written using Text_IO will be in canonical form provided that no 16933explicit @code{LF} or @code{FF} characters are written using @code{Put} 16934or @code{Put_Line}. There will be no @code{FF} character at the end of 16935the file unless an explicit @code{New_Page} operation was performed 16936before closing the file. 16937 16938A canonical Text_IO file that is a regular file (i.e., not a device or a 16939pipe) can be read using any of the routines in Text_IO@. The 16940semantics in this case will be exactly as defined in the Ada Reference 16941Manual, and all the routines in Text_IO are fully implemented. 16942 16943A text file that does not meet the requirements for a canonical Text_IO 16944file has one of the following: 16945 16946@itemize @bullet 16947@item 16948The file contains @code{FF} characters not immediately following a 16949@code{LF} character. 16950 16951@item 16952The file contains @code{LF} or @code{FF} characters written by 16953@code{Put} or @code{Put_Line}, which are not logically considered to be 16954line marks or page marks. 16955 16956@item 16957The file ends in a character other than @code{LF} or @code{FF}, 16958i.e.@: there is no explicit line mark or page mark at the end of the file. 16959@end itemize 16960 16961@noindent 16962Text_IO can be used to read such non-standard text files but subprograms 16963to do with line or page numbers do not have defined meanings. In 16964particular, a @code{FF} character that does not follow a @code{LF} 16965character may or may not be treated as a page mark from the point of 16966view of page and line numbering. Every @code{LF} character is considered 16967to end a line, and there is an implied @code{LF} character at the end of 16968the file. 16969 16970@menu 16971* Text_IO Stream Pointer Positioning:: 16972* Text_IO Reading and Writing Non-Regular Files:: 16973* Get_Immediate:: 16974* Treating Text_IO Files as Streams:: 16975* Text_IO Extensions:: 16976* Text_IO Facilities for Unbounded Strings:: 16977@end menu 16978 16979@node Text_IO Stream Pointer Positioning 16980@subsection Stream Pointer Positioning 16981 16982@noindent 16983@code{Ada.Text_IO} has a definition of current position for a file that 16984is being read. No internal buffering occurs in Text_IO, and usually the 16985physical position in the stream used to implement the file corresponds 16986to this logical position defined by Text_IO@. There are two exceptions: 16987 16988@itemize @bullet 16989@item 16990After a call to @code{End_Of_Page} that returns @code{True}, the stream 16991is positioned past the @code{LF} (line mark) that precedes the page 16992mark. Text_IO maintains an internal flag so that subsequent read 16993operations properly handle the logical position which is unchanged by 16994the @code{End_Of_Page} call. 16995 16996@item 16997After a call to @code{End_Of_File} that returns @code{True}, if the 16998Text_IO file was positioned before the line mark at the end of file 16999before the call, then the logical position is unchanged, but the stream 17000is physically positioned right at the end of file (past the line mark, 17001and past a possible page mark following the line mark. Again Text_IO 17002maintains internal flags so that subsequent read operations properly 17003handle the logical position. 17004@end itemize 17005 17006@noindent 17007These discrepancies have no effect on the observable behavior of 17008Text_IO, but if a single Ada stream is shared between a C program and 17009Ada program, or shared (using @samp{shared=yes} in the form string) 17010between two Ada files, then the difference may be observable in some 17011situations. 17012 17013@node Text_IO Reading and Writing Non-Regular Files 17014@subsection Reading and Writing Non-Regular Files 17015 17016@noindent 17017A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 17018can be used for reading and writing. Writing is not affected and the 17019sequence of characters output is identical to the normal file case, but 17020for reading, the behavior of Text_IO is modified to avoid undesirable 17021look-ahead as follows: 17022 17023An input file that is not a regular file is considered to have no page 17024marks. Any @code{Ascii.FF} characters (the character normally used for a 17025page mark) appearing in the file are considered to be data 17026characters. In particular: 17027 17028@itemize @bullet 17029@item 17030@code{Get_Line} and @code{Skip_Line} do not test for a page mark 17031following a line mark. If a page mark appears, it will be treated as a 17032data character. 17033 17034@item 17035This avoids the need to wait for an extra character to be typed or 17036entered from the pipe to complete one of these operations. 17037 17038@item 17039@code{End_Of_Page} always returns @code{False} 17040 17041@item 17042@code{End_Of_File} will return @code{False} if there is a page mark at 17043the end of the file. 17044@end itemize 17045 17046@noindent 17047Output to non-regular files is the same as for regular files. Page marks 17048may be written to non-regular files using @code{New_Page}, but as noted 17049above they will not be treated as page marks on input if the output is 17050piped to another Ada program. 17051 17052Another important discrepancy when reading non-regular files is that the end 17053of file indication is not ``sticky''. If an end of file is entered, e.g.@: by 17054pressing the @key{EOT} key, 17055then end of file 17056is signaled once (i.e.@: the test @code{End_Of_File} 17057will yield @code{True}, or a read will 17058raise @code{End_Error}), but then reading can resume 17059to read data past that end of 17060file indication, until another end of file indication is entered. 17061 17062@node Get_Immediate 17063@subsection Get_Immediate 17064@cindex Get_Immediate 17065 17066@noindent 17067Get_Immediate returns the next character (including control characters) 17068from the input file. In particular, Get_Immediate will return LF or FF 17069characters used as line marks or page marks. Such operations leave the 17070file positioned past the control character, and it is thus not treated 17071as having its normal function. This means that page, line and column 17072counts after this kind of Get_Immediate call are set as though the mark 17073did not occur. In the case where a Get_Immediate leaves the file 17074positioned between the line mark and page mark (which is not normally 17075possible), it is undefined whether the FF character will be treated as a 17076page mark. 17077 17078@node Treating Text_IO Files as Streams 17079@subsection Treating Text_IO Files as Streams 17080@cindex Stream files 17081 17082@noindent 17083The package @code{Text_IO.Streams} allows a Text_IO file to be treated 17084as a stream. Data written to a Text_IO file in this stream mode is 17085binary data. If this binary data contains bytes 16#0A# (@code{LF}) or 1708616#0C# (@code{FF}), the resulting file may have non-standard 17087format. Similarly if read operations are used to read from a Text_IO 17088file treated as a stream, then @code{LF} and @code{FF} characters may be 17089skipped and the effect is similar to that described above for 17090@code{Get_Immediate}. 17091 17092@node Text_IO Extensions 17093@subsection Text_IO Extensions 17094@cindex Text_IO extensions 17095 17096@noindent 17097A package GNAT.IO_Aux in the GNAT library provides some useful extensions 17098to the standard @code{Text_IO} package: 17099 17100@itemize @bullet 17101@item function File_Exists (Name : String) return Boolean; 17102Determines if a file of the given name exists. 17103 17104@item function Get_Line return String; 17105Reads a string from the standard input file. The value returned is exactly 17106the length of the line that was read. 17107 17108@item function Get_Line (File : Ada.Text_IO.File_Type) return String; 17109Similar, except that the parameter File specifies the file from which 17110the string is to be read. 17111 17112@end itemize 17113 17114@node Text_IO Facilities for Unbounded Strings 17115@subsection Text_IO Facilities for Unbounded Strings 17116@cindex Text_IO for unbounded strings 17117@cindex Unbounded_String, Text_IO operations 17118 17119@noindent 17120The package @code{Ada.Strings.Unbounded.Text_IO} 17121in library files @code{a-suteio.ads/adb} contains some GNAT-specific 17122subprograms useful for Text_IO operations on unbounded strings: 17123 17124@itemize @bullet 17125 17126@item function Get_Line (File : File_Type) return Unbounded_String; 17127Reads a line from the specified file 17128and returns the result as an unbounded string. 17129 17130@item procedure Put (File : File_Type; U : Unbounded_String); 17131Writes the value of the given unbounded string to the specified file 17132Similar to the effect of 17133@code{Put (To_String (U))} except that an extra copy is avoided. 17134 17135@item procedure Put_Line (File : File_Type; U : Unbounded_String); 17136Writes the value of the given unbounded string to the specified file, 17137followed by a @code{New_Line}. 17138Similar to the effect of @code{Put_Line (To_String (U))} except 17139that an extra copy is avoided. 17140@end itemize 17141 17142@noindent 17143In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} 17144and is optional. If the parameter is omitted, then the standard input or 17145output file is referenced as appropriate. 17146 17147The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 17148files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended 17149@code{Wide_Text_IO} functionality for unbounded wide strings. 17150 17151The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library 17152files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended 17153@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. 17154 17155@node Wide_Text_IO 17156@section Wide_Text_IO 17157 17158@noindent 17159@code{Wide_Text_IO} is similar in most respects to Text_IO, except that 17160both input and output files may contain special sequences that represent 17161wide character values. The encoding scheme for a given file may be 17162specified using a FORM parameter: 17163 17164@smallexample 17165WCEM=@var{x} 17166@end smallexample 17167 17168@noindent 17169as part of the FORM string (WCEM = wide character encoding method), 17170where @var{x} is one of the following characters 17171 17172@table @samp 17173@item h 17174Hex ESC encoding 17175@item u 17176Upper half encoding 17177@item s 17178Shift-JIS encoding 17179@item e 17180EUC Encoding 17181@item 8 17182UTF-8 encoding 17183@item b 17184Brackets encoding 17185@end table 17186 17187@noindent 17188The encoding methods match those that 17189can be used in a source 17190program, but there is no requirement that the encoding method used for 17191the source program be the same as the encoding method used for files, 17192and different files may use different encoding methods. 17193 17194The default encoding method for the standard files, and for opened files 17195for which no WCEM parameter is given in the FORM string matches the 17196wide character encoding specified for the main program (the default 17197being brackets encoding if no coding method was specified with -gnatW). 17198 17199@table @asis 17200@item Hex Coding 17201In this encoding, a wide character is represented by a five character 17202sequence: 17203 17204@smallexample 17205ESC a b c d 17206@end smallexample 17207 17208@noindent 17209where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal 17210characters (using upper case letters) of the wide character code. For 17211example, ESC A345 is used to represent the wide character with code 1721216#A345#. This scheme is compatible with use of the full 17213@code{Wide_Character} set. 17214 17215@item Upper Half Coding 17216The wide character with encoding 16#abcd#, where the upper bit is on 17217(i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and 1721816#cd#. The second byte may never be a format control character, but is 17219not required to be in the upper half. This method can be also used for 17220shift-JIS or EUC where the internal coding matches the external coding. 17221 17222@item Shift JIS Coding 17223A wide character is represented by a two character sequence 16#ab# and 1722416#cd#, with the restrictions described for upper half encoding as 17225described above. The internal character code is the corresponding JIS 17226character according to the standard algorithm for Shift-JIS 17227conversion. Only characters defined in the JIS code set table can be 17228used with this encoding method. 17229 17230@item EUC Coding 17231A wide character is represented by a two character sequence 16#ab# and 1723216#cd#, with both characters being in the upper half. The internal 17233character code is the corresponding JIS character according to the EUC 17234encoding algorithm. Only characters defined in the JIS code set table 17235can be used with this encoding method. 17236 17237@item UTF-8 Coding 17238A wide character is represented using 17239UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 1724010646-1/Am.2. Depending on the character value, the representation 17241is a one, two, or three byte sequence: 17242 17243@smallexample 1724416#0000#-16#007f#: 2#0xxxxxxx# 1724516#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 1724616#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 17247@end smallexample 17248 17249@noindent 17250where the @var{xxx} bits correspond to the left-padded bits of the 1725116-bit character value. Note that all lower half ASCII characters 17252are represented as ASCII bytes and all upper half characters and 17253other wide characters are represented as sequences of upper-half 17254(The full UTF-8 scheme allows for encoding 31-bit characters as 172556-byte sequences, but in this implementation, all UTF-8 sequences 17256of four or more bytes length will raise a Constraint_Error, as 17257will all invalid UTF-8 sequences.) 17258 17259@item Brackets Coding 17260In this encoding, a wide character is represented by the following eight 17261character sequence: 17262 17263@smallexample 17264[ " a b c d " ] 17265@end smallexample 17266 17267@noindent 17268where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 17269characters (using uppercase letters) of the wide character code. For 17270example, @code{["A345"]} is used to represent the wide character with code 17271@code{16#A345#}. 17272This scheme is compatible with use of the full Wide_Character set. 17273On input, brackets coding can also be used for upper half characters, 17274e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation 17275is only used for wide characters with a code greater than @code{16#FF#}. 17276 17277Note that brackets coding is not normally used in the context of 17278Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as 17279a portable way of encoding source files. In the context of Wide_Text_IO 17280or Wide_Wide_Text_IO, it can only be used if the file does not contain 17281any instance of the left bracket character other than to encode wide 17282character values using the brackets encoding method. In practice it is 17283expected that some standard wide character encoding method such 17284as UTF-8 will be used for text input output. 17285 17286If brackets notation is used, then any occurrence of a left bracket 17287in the input file which is not the start of a valid wide character 17288sequence will cause Constraint_Error to be raised. It is possible to 17289encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO 17290input will interpret this as a left bracket. 17291 17292However, when a left bracket is output, it will be output as a left bracket 17293and not as ["5B"]. We make this decision because for normal use of 17294Wide_Text_IO for outputting messages, it is unpleasant to clobber left 17295brackets. For example, if we write: 17296 17297@smallexample 17298 Put_Line ("Start of output [first run]"); 17299@end smallexample 17300 17301@noindent 17302we really do not want to have the left bracket in this message clobbered so 17303that the output reads: 17304 17305@smallexample 17306 Start of output ["5B"]first run] 17307@end smallexample 17308 17309@noindent 17310In practice brackets encoding is reasonably useful for normal Put_Line use 17311since we won't get confused between left brackets and wide character 17312sequences in the output. But for input, or when files are written out 17313and read back in, it really makes better sense to use one of the standard 17314encoding methods such as UTF-8. 17315 17316@end table 17317 17318@noindent 17319For the coding schemes other than UTF-8, Hex, or Brackets encoding, 17320not all wide character 17321values can be represented. An attempt to output a character that cannot 17322be represented using the encoding scheme for the file causes 17323Constraint_Error to be raised. An invalid wide character sequence on 17324input also causes Constraint_Error to be raised. 17325 17326@menu 17327* Wide_Text_IO Stream Pointer Positioning:: 17328* Wide_Text_IO Reading and Writing Non-Regular Files:: 17329@end menu 17330 17331@node Wide_Text_IO Stream Pointer Positioning 17332@subsection Stream Pointer Positioning 17333 17334@noindent 17335@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 17336of stream pointer positioning (@pxref{Text_IO}). There is one additional 17337case: 17338 17339If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 17340normal lower ASCII set (i.e.@: a character in the range: 17341 17342@smallexample @c ada 17343Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 17344@end smallexample 17345 17346@noindent 17347then although the logical position of the file pointer is unchanged by 17348the @code{Look_Ahead} call, the stream is physically positioned past the 17349wide character sequence. Again this is to avoid the need for buffering 17350or backup, and all @code{Wide_Text_IO} routines check the internal 17351indication that this situation has occurred so that this is not visible 17352to a normal program using @code{Wide_Text_IO}. However, this discrepancy 17353can be observed if the wide text file shares a stream with another file. 17354 17355@node Wide_Text_IO Reading and Writing Non-Regular Files 17356@subsection Reading and Writing Non-Regular Files 17357 17358@noindent 17359As in the case of Text_IO, when a non-regular file is read, it is 17360assumed that the file contains no page marks (any form characters are 17361treated as data characters), and @code{End_Of_Page} always returns 17362@code{False}. Similarly, the end of file indication is not sticky, so 17363it is possible to read beyond an end of file. 17364 17365@node Wide_Wide_Text_IO 17366@section Wide_Wide_Text_IO 17367 17368@noindent 17369@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that 17370both input and output files may contain special sequences that represent 17371wide wide character values. The encoding scheme for a given file may be 17372specified using a FORM parameter: 17373 17374@smallexample 17375WCEM=@var{x} 17376@end smallexample 17377 17378@noindent 17379as part of the FORM string (WCEM = wide character encoding method), 17380where @var{x} is one of the following characters 17381 17382@table @samp 17383@item h 17384Hex ESC encoding 17385@item u 17386Upper half encoding 17387@item s 17388Shift-JIS encoding 17389@item e 17390EUC Encoding 17391@item 8 17392UTF-8 encoding 17393@item b 17394Brackets encoding 17395@end table 17396 17397@noindent 17398The encoding methods match those that 17399can be used in a source 17400program, but there is no requirement that the encoding method used for 17401the source program be the same as the encoding method used for files, 17402and different files may use different encoding methods. 17403 17404The default encoding method for the standard files, and for opened files 17405for which no WCEM parameter is given in the FORM string matches the 17406wide character encoding specified for the main program (the default 17407being brackets encoding if no coding method was specified with -gnatW). 17408 17409@table @asis 17410 17411@item UTF-8 Coding 17412A wide character is represented using 17413UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 1741410646-1/Am.2. Depending on the character value, the representation 17415is a one, two, three, or four byte sequence: 17416 17417@smallexample 1741816#000000#-16#00007f#: 2#0xxxxxxx# 1741916#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# 1742016#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 1742116#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# 17422@end smallexample 17423 17424@noindent 17425where the @var{xxx} bits correspond to the left-padded bits of the 1742621-bit character value. Note that all lower half ASCII characters 17427are represented as ASCII bytes and all upper half characters and 17428other wide characters are represented as sequences of upper-half 17429characters. 17430 17431@item Brackets Coding 17432In this encoding, a wide wide character is represented by the following eight 17433character sequence if is in wide character range 17434 17435@smallexample 17436[ " a b c d " ] 17437@end smallexample 17438 17439and by the following ten character sequence if not 17440 17441@smallexample 17442[ " a b c d e f " ] 17443@end smallexample 17444 17445@noindent 17446where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} 17447are the four or six hexadecimal 17448characters (using uppercase letters) of the wide wide character code. For 17449example, @code{["01A345"]} is used to represent the wide wide character 17450with code @code{16#01A345#}. 17451 17452This scheme is compatible with use of the full Wide_Wide_Character set. 17453On input, brackets coding can also be used for upper half characters, 17454e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation 17455is only used for wide characters with a code greater than @code{16#FF#}. 17456 17457@end table 17458 17459@noindent 17460If is also possible to use the other Wide_Character encoding methods, 17461such as Shift-JIS, but the other schemes cannot support the full range 17462of wide wide characters. 17463An attempt to output a character that cannot 17464be represented using the encoding scheme for the file causes 17465Constraint_Error to be raised. An invalid wide character sequence on 17466input also causes Constraint_Error to be raised. 17467 17468@menu 17469* Wide_Wide_Text_IO Stream Pointer Positioning:: 17470* Wide_Wide_Text_IO Reading and Writing Non-Regular Files:: 17471@end menu 17472 17473@node Wide_Wide_Text_IO Stream Pointer Positioning 17474@subsection Stream Pointer Positioning 17475 17476@noindent 17477@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 17478of stream pointer positioning (@pxref{Text_IO}). There is one additional 17479case: 17480 17481If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the 17482normal lower ASCII set (i.e.@: a character in the range: 17483 17484@smallexample @c ada 17485Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) 17486@end smallexample 17487 17488@noindent 17489then although the logical position of the file pointer is unchanged by 17490the @code{Look_Ahead} call, the stream is physically positioned past the 17491wide character sequence. Again this is to avoid the need for buffering 17492or backup, and all @code{Wide_Wide_Text_IO} routines check the internal 17493indication that this situation has occurred so that this is not visible 17494to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy 17495can be observed if the wide text file shares a stream with another file. 17496 17497@node Wide_Wide_Text_IO Reading and Writing Non-Regular Files 17498@subsection Reading and Writing Non-Regular Files 17499 17500@noindent 17501As in the case of Text_IO, when a non-regular file is read, it is 17502assumed that the file contains no page marks (any form characters are 17503treated as data characters), and @code{End_Of_Page} always returns 17504@code{False}. Similarly, the end of file indication is not sticky, so 17505it is possible to read beyond an end of file. 17506 17507@node Stream_IO 17508@section Stream_IO 17509 17510@noindent 17511A stream file is a sequence of bytes, where individual elements are 17512written to the file as described in the Ada Reference Manual. The type 17513@code{Stream_Element} is simply a byte. There are two ways to read or 17514write a stream file. 17515 17516@itemize @bullet 17517@item 17518The operations @code{Read} and @code{Write} directly read or write a 17519sequence of stream elements with no control information. 17520 17521@item 17522The stream attributes applied to a stream file transfer data in the 17523manner described for stream attributes. 17524@end itemize 17525 17526@node Text Translation 17527@section Text Translation 17528 17529@noindent 17530@samp{Text_Translation=@var{xxx}} may be used as the Form parameter 17531passed to Text_IO.Create and Text_IO.Open: 17532@samp{Text_Translation=@var{Yes}} is the default, which means to 17533translate LF to/from CR/LF on Windows systems. 17534@samp{Text_Translation=@var{No}} disables this translation; i.e. it 17535uses binary mode. For output files, @samp{Text_Translation=@var{No}} 17536may be used to create Unix-style files on 17537Windows. @samp{Text_Translation=@var{xxx}} has no effect on Unix 17538systems. 17539 17540@node Shared Files 17541@section Shared Files 17542 17543@noindent 17544Section A.14 of the Ada Reference Manual allows implementations to 17545provide a wide variety of behavior if an attempt is made to access the 17546same external file with two or more internal files. 17547 17548To provide a full range of functionality, while at the same time 17549minimizing the problems of portability caused by this implementation 17550dependence, GNAT handles file sharing as follows: 17551 17552@itemize @bullet 17553@item 17554In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt 17555to open two or more files with the same full name is considered an error 17556and is not supported. The exception @code{Use_Error} will be 17557raised. Note that a file that is not explicitly closed by the program 17558remains open until the program terminates. 17559 17560@item 17561If the form parameter @samp{shared=no} appears in the form string, the 17562file can be opened or created with its own separate stream identifier, 17563regardless of whether other files sharing the same external file are 17564opened. The exact effect depends on how the C stream routines handle 17565multiple accesses to the same external files using separate streams. 17566 17567@item 17568If the form parameter @samp{shared=yes} appears in the form string for 17569each of two or more files opened using the same full name, the same 17570stream is shared between these files, and the semantics are as described 17571in Ada Reference Manual, Section A.14. 17572@end itemize 17573 17574@noindent 17575When a program that opens multiple files with the same name is ported 17576from another Ada compiler to GNAT, the effect will be that 17577@code{Use_Error} is raised. 17578 17579The documentation of the original compiler and the documentation of the 17580program should then be examined to determine if file sharing was 17581expected, and @samp{shared=@var{xxx}} parameters added to @code{Open} 17582and @code{Create} calls as required. 17583 17584When a program is ported from GNAT to some other Ada compiler, no 17585special attention is required unless the @samp{shared=@var{xxx}} form 17586parameter is used in the program. In this case, you must examine the 17587documentation of the new compiler to see if it supports the required 17588file sharing semantics, and form strings modified appropriately. Of 17589course it may be the case that the program cannot be ported if the 17590target compiler does not support the required functionality. The best 17591approach in writing portable code is to avoid file sharing (and hence 17592the use of the @samp{shared=@var{xxx}} parameter in the form string) 17593completely. 17594 17595One common use of file sharing in Ada 83 is the use of instantiations of 17596Sequential_IO on the same file with different types, to achieve 17597heterogeneous input-output. Although this approach will work in GNAT if 17598@samp{shared=yes} is specified, it is preferable in Ada to use Stream_IO 17599for this purpose (using the stream attributes) 17600 17601@node Filenames encoding 17602@section Filenames encoding 17603 17604@noindent 17605An encoding form parameter can be used to specify the filename 17606encoding @samp{encoding=@var{xxx}}. 17607 17608@itemize @bullet 17609@item 17610If the form parameter @samp{encoding=utf8} appears in the form string, the 17611filename must be encoded in UTF-8. 17612 17613@item 17614If the form parameter @samp{encoding=8bits} appears in the form 17615string, the filename must be a standard 8bits string. 17616@end itemize 17617 17618In the absence of a @samp{encoding=@var{xxx}} form parameter, the 17619encoding is controlled by the @samp{GNAT_CODE_PAGE} environment 17620variable. And if not set @samp{utf8} is assumed. 17621 17622@table @samp 17623@item CP_ACP 17624The current system Windows ANSI code page. 17625@item CP_UTF8 17626UTF-8 encoding 17627@end table 17628 17629This encoding form parameter is only supported on the Windows 17630platform. On the other Operating Systems the run-time is supporting 17631UTF-8 natively. 17632 17633@node Open Modes 17634@section Open Modes 17635 17636@noindent 17637@code{Open} and @code{Create} calls result in a call to @code{fopen} 17638using the mode shown in the following table: 17639 17640@sp 2 17641@center @code{Open} and @code{Create} Call Modes 17642@smallexample 17643 @b{OPEN } @b{CREATE} 17644Append_File "r+" "w+" 17645In_File "r" "w+" 17646Out_File (Direct_IO) "r+" "w" 17647Out_File (all other cases) "w" "w" 17648Inout_File "r+" "w+" 17649@end smallexample 17650 17651@noindent 17652If text file translation is required, then either @samp{b} or @samp{t} 17653is added to the mode, depending on the setting of Text. Text file 17654translation refers to the mapping of CR/LF sequences in an external file 17655to LF characters internally. This mapping only occurs in DOS and 17656DOS-like systems, and is not relevant to other systems. 17657 17658A special case occurs with Stream_IO@. As shown in the above table, the 17659file is initially opened in @samp{r} or @samp{w} mode for the 17660@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation 17661subsequently requires switching from reading to writing or vice-versa, 17662then the file is reopened in @samp{r+} mode to permit the required operation. 17663 17664@node Operations on C Streams 17665@section Operations on C Streams 17666The package @code{Interfaces.C_Streams} provides an Ada program with direct 17667access to the C library functions for operations on C streams: 17668 17669@smallexample @c adanocomment 17670package Interfaces.C_Streams is 17671 -- Note: the reason we do not use the types that are in 17672 -- Interfaces.C is that we want to avoid dragging in the 17673 -- code in this unit if possible. 17674 subtype chars is System.Address; 17675 -- Pointer to null-terminated array of characters 17676 subtype FILEs is System.Address; 17677 -- Corresponds to the C type FILE* 17678 subtype voids is System.Address; 17679 -- Corresponds to the C type void* 17680 subtype int is Integer; 17681 subtype long is Long_Integer; 17682 -- Note: the above types are subtypes deliberately, and it 17683 -- is part of this spec that the above correspondences are 17684 -- guaranteed. This means that it is legitimate to, for 17685 -- example, use Integer instead of int. We provide these 17686 -- synonyms for clarity, but in some cases it may be 17687 -- convenient to use the underlying types (for example to 17688 -- avoid an unnecessary dependency of a spec on the spec 17689 -- of this unit). 17690 type size_t is mod 2 ** Standard'Address_Size; 17691 NULL_Stream : constant FILEs; 17692 -- Value returned (NULL in C) to indicate an 17693 -- fdopen/fopen/tmpfile error 17694 ---------------------------------- 17695 -- Constants Defined in stdio.h -- 17696 ---------------------------------- 17697 EOF : constant int; 17698 -- Used by a number of routines to indicate error or 17699 -- end of file 17700 IOFBF : constant int; 17701 IOLBF : constant int; 17702 IONBF : constant int; 17703 -- Used to indicate buffering mode for setvbuf call 17704 SEEK_CUR : constant int; 17705 SEEK_END : constant int; 17706 SEEK_SET : constant int; 17707 -- Used to indicate origin for fseek call 17708 function stdin return FILEs; 17709 function stdout return FILEs; 17710 function stderr return FILEs; 17711 -- Streams associated with standard files 17712 -------------------------- 17713 -- Standard C functions -- 17714 -------------------------- 17715 -- The functions selected below are ones that are 17716 -- available in UNIX (but not necessarily in ANSI C). 17717 -- These are very thin interfaces 17718 -- which copy exactly the C headers. For more 17719 -- documentation on these functions, see the Microsoft C 17720 -- "Run-Time Library Reference" (Microsoft Press, 1990, 17721 -- ISBN 1-55615-225-6), which includes useful information 17722 -- on system compatibility. 17723 procedure clearerr (stream : FILEs); 17724 function fclose (stream : FILEs) return int; 17725 function fdopen (handle : int; mode : chars) return FILEs; 17726 function feof (stream : FILEs) return int; 17727 function ferror (stream : FILEs) return int; 17728 function fflush (stream : FILEs) return int; 17729 function fgetc (stream : FILEs) return int; 17730 function fgets (strng : chars; n : int; stream : FILEs) 17731 return chars; 17732 function fileno (stream : FILEs) return int; 17733 function fopen (filename : chars; Mode : chars) 17734 return FILEs; 17735 -- Note: to maintain target independence, use 17736 -- text_translation_required, a boolean variable defined in 17737 -- a-sysdep.c to deal with the target dependent text 17738 -- translation requirement. If this variable is set, 17739 -- then b/t should be appended to the standard mode 17740 -- argument to set the text translation mode off or on 17741 -- as required. 17742 function fputc (C : int; stream : FILEs) return int; 17743 function fputs (Strng : chars; Stream : FILEs) return int; 17744 function fread 17745 (buffer : voids; 17746 size : size_t; 17747 count : size_t; 17748 stream : FILEs) 17749 return size_t; 17750 function freopen 17751 (filename : chars; 17752 mode : chars; 17753 stream : FILEs) 17754 return FILEs; 17755 function fseek 17756 (stream : FILEs; 17757 offset : long; 17758 origin : int) 17759 return int; 17760 function ftell (stream : FILEs) return long; 17761 function fwrite 17762 (buffer : voids; 17763 size : size_t; 17764 count : size_t; 17765 stream : FILEs) 17766 return size_t; 17767 function isatty (handle : int) return int; 17768 procedure mktemp (template : chars); 17769 -- The return value (which is just a pointer to template) 17770 -- is discarded 17771 procedure rewind (stream : FILEs); 17772 function rmtmp return int; 17773 function setvbuf 17774 (stream : FILEs; 17775 buffer : chars; 17776 mode : int; 17777 size : size_t) 17778 return int; 17779 17780 function tmpfile return FILEs; 17781 function ungetc (c : int; stream : FILEs) return int; 17782 function unlink (filename : chars) return int; 17783 --------------------- 17784 -- Extra functions -- 17785 --------------------- 17786 -- These functions supply slightly thicker bindings than 17787 -- those above. They are derived from functions in the 17788 -- C Run-Time Library, but may do a bit more work than 17789 -- just directly calling one of the Library functions. 17790 function is_regular_file (handle : int) return int; 17791 -- Tests if given handle is for a regular file (result 1) 17792 -- or for a non-regular file (pipe or device, result 0). 17793 --------------------------------- 17794 -- Control of Text/Binary Mode -- 17795 --------------------------------- 17796 -- If text_translation_required is true, then the following 17797 -- functions may be used to dynamically switch a file from 17798 -- binary to text mode or vice versa. These functions have 17799 -- no effect if text_translation_required is false (i.e.@: in 17800 -- normal UNIX mode). Use fileno to get a stream handle. 17801 procedure set_binary_mode (handle : int); 17802 procedure set_text_mode (handle : int); 17803 ---------------------------- 17804 -- Full Path Name support -- 17805 ---------------------------- 17806 procedure full_name (nam : chars; buffer : chars); 17807 -- Given a NUL terminated string representing a file 17808 -- name, returns in buffer a NUL terminated string 17809 -- representing the full path name for the file name. 17810 -- On systems where it is relevant the drive is also 17811 -- part of the full path name. It is the responsibility 17812 -- of the caller to pass an actual parameter for buffer 17813 -- that is big enough for any full path name. Use 17814 -- max_path_len given below as the size of buffer. 17815 max_path_len : integer; 17816 -- Maximum length of an allowable full path name on the 17817 -- system, including a terminating NUL character. 17818end Interfaces.C_Streams; 17819@end smallexample 17820 17821@node Interfacing to C Streams 17822@section Interfacing to C Streams 17823 17824@noindent 17825The packages in this section permit interfacing Ada files to C Stream 17826operations. 17827 17828@smallexample @c ada 17829 with Interfaces.C_Streams; 17830 package Ada.Sequential_IO.C_Streams is 17831 function C_Stream (F : File_Type) 17832 return Interfaces.C_Streams.FILEs; 17833 procedure Open 17834 (File : in out File_Type; 17835 Mode : in File_Mode; 17836 C_Stream : in Interfaces.C_Streams.FILEs; 17837 Form : in String := ""); 17838 end Ada.Sequential_IO.C_Streams; 17839 17840 with Interfaces.C_Streams; 17841 package Ada.Direct_IO.C_Streams is 17842 function C_Stream (F : File_Type) 17843 return Interfaces.C_Streams.FILEs; 17844 procedure Open 17845 (File : in out File_Type; 17846 Mode : in File_Mode; 17847 C_Stream : in Interfaces.C_Streams.FILEs; 17848 Form : in String := ""); 17849 end Ada.Direct_IO.C_Streams; 17850 17851 with Interfaces.C_Streams; 17852 package Ada.Text_IO.C_Streams is 17853 function C_Stream (F : File_Type) 17854 return Interfaces.C_Streams.FILEs; 17855 procedure Open 17856 (File : in out File_Type; 17857 Mode : in File_Mode; 17858 C_Stream : in Interfaces.C_Streams.FILEs; 17859 Form : in String := ""); 17860 end Ada.Text_IO.C_Streams; 17861 17862 with Interfaces.C_Streams; 17863 package Ada.Wide_Text_IO.C_Streams is 17864 function C_Stream (F : File_Type) 17865 return Interfaces.C_Streams.FILEs; 17866 procedure Open 17867 (File : in out File_Type; 17868 Mode : in File_Mode; 17869 C_Stream : in Interfaces.C_Streams.FILEs; 17870 Form : in String := ""); 17871 end Ada.Wide_Text_IO.C_Streams; 17872 17873 with Interfaces.C_Streams; 17874 package Ada.Wide_Wide_Text_IO.C_Streams is 17875 function C_Stream (F : File_Type) 17876 return Interfaces.C_Streams.FILEs; 17877 procedure Open 17878 (File : in out File_Type; 17879 Mode : in File_Mode; 17880 C_Stream : in Interfaces.C_Streams.FILEs; 17881 Form : in String := ""); 17882 end Ada.Wide_Wide_Text_IO.C_Streams; 17883 17884 with Interfaces.C_Streams; 17885 package Ada.Stream_IO.C_Streams is 17886 function C_Stream (F : File_Type) 17887 return Interfaces.C_Streams.FILEs; 17888 procedure Open 17889 (File : in out File_Type; 17890 Mode : in File_Mode; 17891 C_Stream : in Interfaces.C_Streams.FILEs; 17892 Form : in String := ""); 17893 end Ada.Stream_IO.C_Streams; 17894@end smallexample 17895 17896@noindent 17897In each of these six packages, the @code{C_Stream} function obtains the 17898@code{FILE} pointer from a currently opened Ada file. It is then 17899possible to use the @code{Interfaces.C_Streams} package to operate on 17900this stream, or the stream can be passed to a C program which can 17901operate on it directly. Of course the program is responsible for 17902ensuring that only appropriate sequences of operations are executed. 17903 17904One particular use of relevance to an Ada program is that the 17905@code{setvbuf} function can be used to control the buffering of the 17906stream used by an Ada file. In the absence of such a call the standard 17907default buffering is used. 17908 17909The @code{Open} procedures in these packages open a file giving an 17910existing C Stream instead of a file name. Typically this stream is 17911imported from a C program, allowing an Ada file to operate on an 17912existing C file. 17913 17914@node The GNAT Library 17915@chapter The GNAT Library 17916 17917@noindent 17918The GNAT library contains a number of general and special purpose packages. 17919It represents functionality that the GNAT developers have found useful, and 17920which is made available to GNAT users. The packages described here are fully 17921supported, and upwards compatibility will be maintained in future releases, 17922so you can use these facilities with the confidence that the same functionality 17923will be available in future releases. 17924 17925The chapter here simply gives a brief summary of the facilities available. 17926The full documentation is found in the spec file for the package. The full 17927sources of these library packages, including both spec and body, are provided 17928with all GNAT releases. For example, to find out the full specifications of 17929the SPITBOL pattern matching capability, including a full tutorial and 17930extensive examples, look in the @file{g-spipat.ads} file in the library. 17931 17932For each entry here, the package name (as it would appear in a @code{with} 17933clause) is given, followed by the name of the corresponding spec file in 17934parentheses. The packages are children in four hierarchies, @code{Ada}, 17935@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a 17936GNAT-specific hierarchy. 17937 17938Note that an application program should only use packages in one of these 17939four hierarchies if the package is defined in the Ada Reference Manual, 17940or is listed in this section of the GNAT Programmers Reference Manual. 17941All other units should be considered internal implementation units and 17942should not be directly @code{with}'ed by application code. The use of 17943a @code{with} statement that references one of these internal implementation 17944units makes an application potentially dependent on changes in versions 17945of GNAT, and will generate a warning message. 17946 17947@menu 17948* Ada.Characters.Latin_9 (a-chlat9.ads):: 17949* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: 17950* Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: 17951* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads):: 17952* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads):: 17953* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads):: 17954* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads):: 17955* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads):: 17956* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads):: 17957* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads):: 17958* Ada.Containers.Formal_Vectors (a-cofove.ads):: 17959* Ada.Command_Line.Environment (a-colien.ads):: 17960* Ada.Command_Line.Remove (a-colire.ads):: 17961* Ada.Command_Line.Response_File (a-clrefi.ads):: 17962* Ada.Direct_IO.C_Streams (a-diocst.ads):: 17963* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: 17964* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads):: 17965* Ada.Exceptions.Traceback (a-exctra.ads):: 17966* Ada.Sequential_IO.C_Streams (a-siocst.ads):: 17967* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: 17968* Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: 17969* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: 17970* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads):: 17971* Ada.Text_IO.C_Streams (a-tiocst.ads):: 17972* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads):: 17973* Ada.Wide_Characters.Unicode (a-wichun.ads):: 17974* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: 17975* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads):: 17976* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads):: 17977* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: 17978* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads):: 17979* GNAT.Altivec (g-altive.ads):: 17980* GNAT.Altivec.Conversions (g-altcon.ads):: 17981* GNAT.Altivec.Vector_Operations (g-alveop.ads):: 17982* GNAT.Altivec.Vector_Types (g-alvety.ads):: 17983* GNAT.Altivec.Vector_Views (g-alvevi.ads):: 17984* GNAT.Array_Split (g-arrspl.ads):: 17985* GNAT.AWK (g-awk.ads):: 17986* GNAT.Bounded_Buffers (g-boubuf.ads):: 17987* GNAT.Bounded_Mailboxes (g-boumai.ads):: 17988* GNAT.Bubble_Sort (g-bubsor.ads):: 17989* GNAT.Bubble_Sort_A (g-busora.ads):: 17990* GNAT.Bubble_Sort_G (g-busorg.ads):: 17991* GNAT.Byte_Order_Mark (g-byorma.ads):: 17992* GNAT.Byte_Swapping (g-bytswa.ads):: 17993* GNAT.Calendar (g-calend.ads):: 17994* GNAT.Calendar.Time_IO (g-catiio.ads):: 17995* GNAT.Case_Util (g-casuti.ads):: 17996* GNAT.CGI (g-cgi.ads):: 17997* GNAT.CGI.Cookie (g-cgicoo.ads):: 17998* GNAT.CGI.Debug (g-cgideb.ads):: 17999* GNAT.Command_Line (g-comlin.ads):: 18000* GNAT.Compiler_Version (g-comver.ads):: 18001* GNAT.Ctrl_C (g-ctrl_c.ads):: 18002* GNAT.CRC32 (g-crc32.ads):: 18003* GNAT.Current_Exception (g-curexc.ads):: 18004* GNAT.Debug_Pools (g-debpoo.ads):: 18005* GNAT.Debug_Utilities (g-debuti.ads):: 18006* GNAT.Decode_String (g-decstr.ads):: 18007* GNAT.Decode_UTF8_String (g-deutst.ads):: 18008* GNAT.Directory_Operations (g-dirope.ads):: 18009* GNAT.Directory_Operations.Iteration (g-diopit.ads):: 18010* GNAT.Dynamic_HTables (g-dynhta.ads):: 18011* GNAT.Dynamic_Tables (g-dyntab.ads):: 18012* GNAT.Encode_String (g-encstr.ads):: 18013* GNAT.Encode_UTF8_String (g-enutst.ads):: 18014* GNAT.Exception_Actions (g-excact.ads):: 18015* GNAT.Exception_Traces (g-exctra.ads):: 18016* GNAT.Exceptions (g-except.ads):: 18017* GNAT.Expect (g-expect.ads):: 18018* GNAT.Expect.TTY (g-exptty.ads):: 18019* GNAT.Float_Control (g-flocon.ads):: 18020* GNAT.Heap_Sort (g-heasor.ads):: 18021* GNAT.Heap_Sort_A (g-hesora.ads):: 18022* GNAT.Heap_Sort_G (g-hesorg.ads):: 18023* GNAT.HTable (g-htable.ads):: 18024* GNAT.IO (g-io.ads):: 18025* GNAT.IO_Aux (g-io_aux.ads):: 18026* GNAT.Lock_Files (g-locfil.ads):: 18027* GNAT.MBBS_Discrete_Random (g-mbdira.ads):: 18028* GNAT.MBBS_Float_Random (g-mbflra.ads):: 18029* GNAT.MD5 (g-md5.ads):: 18030* GNAT.Memory_Dump (g-memdum.ads):: 18031* GNAT.Most_Recent_Exception (g-moreex.ads):: 18032* GNAT.OS_Lib (g-os_lib.ads):: 18033* GNAT.Perfect_Hash_Generators (g-pehage.ads):: 18034* GNAT.Random_Numbers (g-rannum.ads):: 18035* GNAT.Regexp (g-regexp.ads):: 18036* GNAT.Registry (g-regist.ads):: 18037* GNAT.Regpat (g-regpat.ads):: 18038* GNAT.Secondary_Stack_Info (g-sestin.ads):: 18039* GNAT.Semaphores (g-semaph.ads):: 18040* GNAT.Serial_Communications (g-sercom.ads):: 18041* GNAT.SHA1 (g-sha1.ads):: 18042* GNAT.SHA224 (g-sha224.ads):: 18043* GNAT.SHA256 (g-sha256.ads):: 18044* GNAT.SHA384 (g-sha384.ads):: 18045* GNAT.SHA512 (g-sha512.ads):: 18046* GNAT.Signals (g-signal.ads):: 18047* GNAT.Sockets (g-socket.ads):: 18048* GNAT.Source_Info (g-souinf.ads):: 18049* GNAT.Spelling_Checker (g-speche.ads):: 18050* GNAT.Spelling_Checker_Generic (g-spchge.ads):: 18051* GNAT.Spitbol.Patterns (g-spipat.ads):: 18052* GNAT.Spitbol (g-spitbo.ads):: 18053* GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: 18054* GNAT.Spitbol.Table_Integer (g-sptain.ads):: 18055* GNAT.Spitbol.Table_VString (g-sptavs.ads):: 18056* GNAT.SSE (g-sse.ads):: 18057* GNAT.SSE.Vector_Types (g-ssvety.ads):: 18058* GNAT.Strings (g-string.ads):: 18059* GNAT.String_Split (g-strspl.ads):: 18060* GNAT.Table (g-table.ads):: 18061* GNAT.Task_Lock (g-tasloc.ads):: 18062* GNAT.Threads (g-thread.ads):: 18063* GNAT.Time_Stamp (g-timsta.ads):: 18064* GNAT.Traceback (g-traceb.ads):: 18065* GNAT.Traceback.Symbolic (g-trasym.ads):: 18066* GNAT.UTF_32 (g-utf_32.ads):: 18067* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads):: 18068* GNAT.Wide_Spelling_Checker (g-wispch.ads):: 18069* GNAT.Wide_String_Split (g-wistsp.ads):: 18070* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads):: 18071* GNAT.Wide_Wide_String_Split (g-zistsp.ads):: 18072* Interfaces.C.Extensions (i-cexten.ads):: 18073* Interfaces.C.Streams (i-cstrea.ads):: 18074* Interfaces.CPP (i-cpp.ads):: 18075* Interfaces.Packed_Decimal (i-pacdec.ads):: 18076* Interfaces.VxWorks (i-vxwork.ads):: 18077* Interfaces.VxWorks.IO (i-vxwoio.ads):: 18078* System.Address_Image (s-addima.ads):: 18079* System.Assertions (s-assert.ads):: 18080* System.Memory (s-memory.ads):: 18081* System.Multiprocessors (s-multip.ads):: 18082* System.Multiprocessors.Dispatching_Domains (s-mudido.ads):: 18083* System.Partition_Interface (s-parint.ads):: 18084* System.Pool_Global (s-pooglo.ads):: 18085* System.Pool_Local (s-pooloc.ads):: 18086* System.Restrictions (s-restri.ads):: 18087* System.Rident (s-rident.ads):: 18088* System.Strings.Stream_Ops (s-ststop.ads):: 18089* System.Task_Info (s-tasinf.ads):: 18090* System.Wch_Cnv (s-wchcnv.ads):: 18091* System.Wch_Con (s-wchcon.ads):: 18092@end menu 18093 18094@node Ada.Characters.Latin_9 (a-chlat9.ads) 18095@section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) 18096@cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) 18097@cindex Latin_9 constants for Character 18098 18099@noindent 18100This child of @code{Ada.Characters} 18101provides a set of definitions corresponding to those in the 18102RM-defined package @code{Ada.Characters.Latin_1} but with the 18103few modifications required for @code{Latin-9} 18104The provision of such a package 18105is specifically authorized by the Ada Reference Manual 18106(RM A.3.3(27)). 18107 18108@node Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 18109@section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) 18110@cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) 18111@cindex Latin_1 constants for Wide_Character 18112 18113@noindent 18114This child of @code{Ada.Characters} 18115provides a set of definitions corresponding to those in the 18116RM-defined package @code{Ada.Characters.Latin_1} but with the 18117types of the constants being @code{Wide_Character} 18118instead of @code{Character}. The provision of such a package 18119is specifically authorized by the Ada Reference Manual 18120(RM A.3.3(27)). 18121 18122@node Ada.Characters.Wide_Latin_9 (a-cwila9.ads) 18123@section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) 18124@cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) 18125@cindex Latin_9 constants for Wide_Character 18126 18127@noindent 18128This child of @code{Ada.Characters} 18129provides a set of definitions corresponding to those in the 18130GNAT defined package @code{Ada.Characters.Latin_9} but with the 18131types of the constants being @code{Wide_Character} 18132instead of @code{Character}. The provision of such a package 18133is specifically authorized by the Ada Reference Manual 18134(RM A.3.3(27)). 18135 18136@node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) 18137@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads}) 18138@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads}) 18139@cindex Latin_1 constants for Wide_Wide_Character 18140 18141@noindent 18142This child of @code{Ada.Characters} 18143provides a set of definitions corresponding to those in the 18144RM-defined package @code{Ada.Characters.Latin_1} but with the 18145types of the constants being @code{Wide_Wide_Character} 18146instead of @code{Character}. The provision of such a package 18147is specifically authorized by the Ada Reference Manual 18148(RM A.3.3(27)). 18149 18150@node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) 18151@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads}) 18152@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads}) 18153@cindex Latin_9 constants for Wide_Wide_Character 18154 18155@noindent 18156This child of @code{Ada.Characters} 18157provides a set of definitions corresponding to those in the 18158GNAT defined package @code{Ada.Characters.Latin_9} but with the 18159types of the constants being @code{Wide_Wide_Character} 18160instead of @code{Character}. The provision of such a package 18161is specifically authorized by the Ada Reference Manual 18162(RM A.3.3(27)). 18163 18164@node Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) 18165@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads}) 18166@cindex @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads}) 18167@cindex Formal container for doubly linked lists 18168 18169@noindent 18170This child of @code{Ada.Containers} defines a modified version of the 18171Ada 2005 container for doubly linked lists, meant to facilitate formal 18172verification of code using such containers. The specification of this 18173unit is compatible with SPARK 2014. 18174 18175Note that although this container was designed with formal verification 18176in mind, it may well be generally useful in that it is a simplified more 18177efficient version than the one defined in the standard. In particular it 18178does not have the complex overhead required to detect cursor tampering. 18179 18180@node Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) 18181@section @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads}) 18182@cindex @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads}) 18183@cindex Formal container for hashed maps 18184 18185@noindent 18186This child of @code{Ada.Containers} defines a modified version of the 18187Ada 2005 container for hashed maps, meant to facilitate formal 18188verification of code using such containers. The specification of this 18189unit is compatible with SPARK 2014. 18190 18191Note that although this container was designed with formal verification 18192in mind, it may well be generally useful in that it is a simplified more 18193efficient version than the one defined in the standard. In particular it 18194does not have the complex overhead required to detect cursor tampering. 18195 18196@node Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) 18197@section @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads}) 18198@cindex @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads}) 18199@cindex Formal container for hashed sets 18200 18201@noindent 18202This child of @code{Ada.Containers} defines a modified version of the 18203Ada 2005 container for hashed sets, meant to facilitate formal 18204verification of code using such containers. The specification of this 18205unit is compatible with SPARK 2014. 18206 18207Note that although this container was designed with formal verification 18208in mind, it may well be generally useful in that it is a simplified more 18209efficient version than the one defined in the standard. In particular it 18210does not have the complex overhead required to detect cursor tampering. 18211 18212@node Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) 18213@section @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads}) 18214@cindex @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads}) 18215@cindex Formal container for ordered maps 18216 18217@noindent 18218This child of @code{Ada.Containers} defines a modified version of the 18219Ada 2005 container for ordered maps, meant to facilitate formal 18220verification of code using such containers. The specification of this 18221unit is compatible with SPARK 2014. 18222 18223Note that although this container was designed with formal verification 18224in mind, it may well be generally useful in that it is a simplified more 18225efficient version than the one defined in the standard. In particular it 18226does not have the complex overhead required to detect cursor tampering. 18227 18228@node Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) 18229@section @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads}) 18230@cindex @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads}) 18231@cindex Formal container for ordered sets 18232 18233@noindent 18234This child of @code{Ada.Containers} defines a modified version of the 18235Ada 2005 container for ordered sets, meant to facilitate formal 18236verification of code using such containers. The specification of this 18237unit is compatible with SPARK 2014. 18238 18239Note that although this container was designed with formal verification 18240in mind, it may well be generally useful in that it is a simplified more 18241efficient version than the one defined in the standard. In particular it 18242does not have the complex overhead required to detect cursor tampering. 18243 18244@node Ada.Containers.Formal_Vectors (a-cofove.ads) 18245@section @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads}) 18246@cindex @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads}) 18247@cindex Formal container for vectors 18248 18249@noindent 18250This child of @code{Ada.Containers} defines a modified version of the 18251Ada 2005 container for vectors, meant to facilitate formal 18252verification of code using such containers. The specification of this 18253unit is compatible with SPARK 2014. 18254 18255Note that although this container was designed with formal verification 18256in mind, it may well be generally useful in that it is a simplified more 18257efficient version than the one defined in the standard. In particular it 18258does not have the complex overhead required to detect cursor tampering. 18259 18260@node Ada.Command_Line.Environment (a-colien.ads) 18261@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) 18262@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) 18263@cindex Environment entries 18264 18265@noindent 18266This child of @code{Ada.Command_Line} 18267provides a mechanism for obtaining environment values on systems 18268where this concept makes sense. 18269 18270@node Ada.Command_Line.Remove (a-colire.ads) 18271@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) 18272@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) 18273@cindex Removing command line arguments 18274@cindex Command line, argument removal 18275 18276@noindent 18277This child of @code{Ada.Command_Line} 18278provides a mechanism for logically removing 18279arguments from the argument list. Once removed, an argument is not visible 18280to further calls on the subprograms in @code{Ada.Command_Line} will not 18281see the removed argument. 18282 18283@node Ada.Command_Line.Response_File (a-clrefi.ads) 18284@section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads}) 18285@cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads}) 18286@cindex Response file for command line 18287@cindex Command line, response file 18288@cindex Command line, handling long command lines 18289 18290@noindent 18291This child of @code{Ada.Command_Line} provides a mechanism facilities for 18292getting command line arguments from a text file, called a "response file". 18293Using a response file allow passing a set of arguments to an executable longer 18294than the maximum allowed by the system on the command line. 18295 18296@node Ada.Direct_IO.C_Streams (a-diocst.ads) 18297@section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) 18298@cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) 18299@cindex C Streams, Interfacing with Direct_IO 18300 18301@noindent 18302This package provides subprograms that allow interfacing between 18303C streams and @code{Direct_IO}. The stream identifier can be 18304extracted from a file opened on the Ada side, and an Ada file 18305can be constructed from a stream opened on the C side. 18306 18307@node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 18308@section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) 18309@cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) 18310@cindex Null_Occurrence, testing for 18311 18312@noindent 18313This child subprogram provides a way of testing for the null 18314exception occurrence (@code{Null_Occurrence}) without raising 18315an exception. 18316 18317@node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) 18318@section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads}) 18319@cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads}) 18320@cindex Null_Occurrence, testing for 18321 18322@noindent 18323This child subprogram is used for handling otherwise unhandled 18324exceptions (hence the name last chance), and perform clean ups before 18325terminating the program. Note that this subprogram never returns. 18326 18327@node Ada.Exceptions.Traceback (a-exctra.ads) 18328@section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) 18329@cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) 18330@cindex Traceback for Exception Occurrence 18331 18332@noindent 18333This child package provides the subprogram (@code{Tracebacks}) to 18334give a traceback array of addresses based on an exception 18335occurrence. 18336 18337@node Ada.Sequential_IO.C_Streams (a-siocst.ads) 18338@section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) 18339@cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) 18340@cindex C Streams, Interfacing with Sequential_IO 18341 18342@noindent 18343This package provides subprograms that allow interfacing between 18344C streams and @code{Sequential_IO}. The stream identifier can be 18345extracted from a file opened on the Ada side, and an Ada file 18346can be constructed from a stream opened on the C side. 18347 18348@node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 18349@section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) 18350@cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) 18351@cindex C Streams, Interfacing with Stream_IO 18352 18353@noindent 18354This package provides subprograms that allow interfacing between 18355C streams and @code{Stream_IO}. The stream identifier can be 18356extracted from a file opened on the Ada side, and an Ada file 18357can be constructed from a stream opened on the C side. 18358 18359@node Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 18360@section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) 18361@cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) 18362@cindex @code{Unbounded_String}, IO support 18363@cindex @code{Text_IO}, extensions for unbounded strings 18364 18365@noindent 18366This package provides subprograms for Text_IO for unbounded 18367strings, avoiding the necessity for an intermediate operation 18368with ordinary strings. 18369 18370@node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 18371@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) 18372@cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) 18373@cindex @code{Unbounded_Wide_String}, IO support 18374@cindex @code{Text_IO}, extensions for unbounded wide strings 18375 18376@noindent 18377This package provides subprograms for Text_IO for unbounded 18378wide strings, avoiding the necessity for an intermediate operation 18379with ordinary wide strings. 18380 18381@node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) 18382@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads}) 18383@cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads}) 18384@cindex @code{Unbounded_Wide_Wide_String}, IO support 18385@cindex @code{Text_IO}, extensions for unbounded wide wide strings 18386 18387@noindent 18388This package provides subprograms for Text_IO for unbounded 18389wide wide strings, avoiding the necessity for an intermediate operation 18390with ordinary wide wide strings. 18391 18392@node Ada.Text_IO.C_Streams (a-tiocst.ads) 18393@section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) 18394@cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) 18395@cindex C Streams, Interfacing with @code{Text_IO} 18396 18397@noindent 18398This package provides subprograms that allow interfacing between 18399C streams and @code{Text_IO}. The stream identifier can be 18400extracted from a file opened on the Ada side, and an Ada file 18401can be constructed from a stream opened on the C side. 18402 18403@node Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) 18404@section @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads}) 18405@cindex @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads}) 18406@cindex @code{Text_IO} resetting standard files 18407 18408@noindent 18409This procedure is used to reset the status of the standard files used 18410by Ada.Text_IO. This is useful in a situation (such as a restart in an 18411embedded application) where the status of the files may change during 18412execution (for example a standard input file may be redefined to be 18413interactive). 18414 18415@node Ada.Wide_Characters.Unicode (a-wichun.ads) 18416@section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads}) 18417@cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads}) 18418@cindex Unicode categorization, Wide_Character 18419 18420@noindent 18421This package provides subprograms that allow categorization of 18422Wide_Character values according to Unicode categories. 18423 18424@node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 18425@section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) 18426@cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) 18427@cindex C Streams, Interfacing with @code{Wide_Text_IO} 18428 18429@noindent 18430This package provides subprograms that allow interfacing between 18431C streams and @code{Wide_Text_IO}. The stream identifier can be 18432extracted from a file opened on the Ada side, and an Ada file 18433can be constructed from a stream opened on the C side. 18434 18435@node Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) 18436@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads}) 18437@cindex @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads}) 18438@cindex @code{Wide_Text_IO} resetting standard files 18439 18440@noindent 18441This procedure is used to reset the status of the standard files used 18442by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an 18443embedded application) where the status of the files may change during 18444execution (for example a standard input file may be redefined to be 18445interactive). 18446 18447@node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) 18448@section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads}) 18449@cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads}) 18450@cindex Unicode categorization, Wide_Wide_Character 18451 18452@noindent 18453This package provides subprograms that allow categorization of 18454Wide_Wide_Character values according to Unicode categories. 18455 18456@node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) 18457@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads}) 18458@cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads}) 18459@cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO} 18460 18461@noindent 18462This package provides subprograms that allow interfacing between 18463C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be 18464extracted from a file opened on the Ada side, and an Ada file 18465can be constructed from a stream opened on the C side. 18466 18467@node Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) 18468@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads}) 18469@cindex @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads}) 18470@cindex @code{Wide_Wide_Text_IO} resetting standard files 18471 18472@noindent 18473This procedure is used to reset the status of the standard files used 18474by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a 18475restart in an embedded application) where the status of the files may 18476change during execution (for example a standard input file may be 18477redefined to be interactive). 18478 18479@node GNAT.Altivec (g-altive.ads) 18480@section @code{GNAT.Altivec} (@file{g-altive.ads}) 18481@cindex @code{GNAT.Altivec} (@file{g-altive.ads}) 18482@cindex AltiVec 18483 18484@noindent 18485This is the root package of the GNAT AltiVec binding. It provides 18486definitions of constants and types common to all the versions of the 18487binding. 18488 18489@node GNAT.Altivec.Conversions (g-altcon.ads) 18490@section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads}) 18491@cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads}) 18492@cindex AltiVec 18493 18494@noindent 18495This package provides the Vector/View conversion routines. 18496 18497@node GNAT.Altivec.Vector_Operations (g-alveop.ads) 18498@section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads}) 18499@cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads}) 18500@cindex AltiVec 18501 18502@noindent 18503This package exposes the Ada interface to the AltiVec operations on 18504vector objects. A soft emulation is included by default in the GNAT 18505library. The hard binding is provided as a separate package. This unit 18506is common to both bindings. 18507 18508@node GNAT.Altivec.Vector_Types (g-alvety.ads) 18509@section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads}) 18510@cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads}) 18511@cindex AltiVec 18512 18513@noindent 18514This package exposes the various vector types part of the Ada binding 18515to AltiVec facilities. 18516 18517@node GNAT.Altivec.Vector_Views (g-alvevi.ads) 18518@section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads}) 18519@cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads}) 18520@cindex AltiVec 18521 18522@noindent 18523This package provides public 'View' data types from/to which private 18524vector representations can be converted via 18525GNAT.Altivec.Conversions. This allows convenient access to individual 18526vector elements and provides a simple way to initialize vector 18527objects. 18528 18529@node GNAT.Array_Split (g-arrspl.ads) 18530@section @code{GNAT.Array_Split} (@file{g-arrspl.ads}) 18531@cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads}) 18532@cindex Array splitter 18533 18534@noindent 18535Useful array-manipulation routines: given a set of separators, split 18536an array wherever the separators appear, and provide direct access 18537to the resulting slices. 18538 18539@node GNAT.AWK (g-awk.ads) 18540@section @code{GNAT.AWK} (@file{g-awk.ads}) 18541@cindex @code{GNAT.AWK} (@file{g-awk.ads}) 18542@cindex Parsing 18543@cindex AWK 18544 18545@noindent 18546Provides AWK-like parsing functions, with an easy interface for parsing one 18547or more files containing formatted data. The file is viewed as a database 18548where each record is a line and a field is a data element in this line. 18549 18550@node GNAT.Bounded_Buffers (g-boubuf.ads) 18551@section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) 18552@cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) 18553@cindex Parsing 18554@cindex Bounded Buffers 18555 18556@noindent 18557Provides a concurrent generic bounded buffer abstraction. Instances are 18558useful directly or as parts of the implementations of other abstractions, 18559such as mailboxes. 18560 18561@node GNAT.Bounded_Mailboxes (g-boumai.ads) 18562@section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) 18563@cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) 18564@cindex Parsing 18565@cindex Mailboxes 18566 18567@noindent 18568Provides a thread-safe asynchronous intertask mailbox communication facility. 18569 18570@node GNAT.Bubble_Sort (g-bubsor.ads) 18571@section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) 18572@cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) 18573@cindex Sorting 18574@cindex Bubble sort 18575 18576@noindent 18577Provides a general implementation of bubble sort usable for sorting arbitrary 18578data items. Exchange and comparison procedures are provided by passing 18579access-to-procedure values. 18580 18581@node GNAT.Bubble_Sort_A (g-busora.ads) 18582@section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) 18583@cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) 18584@cindex Sorting 18585@cindex Bubble sort 18586 18587@noindent 18588Provides a general implementation of bubble sort usable for sorting arbitrary 18589data items. Move and comparison procedures are provided by passing 18590access-to-procedure values. This is an older version, retained for 18591compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. 18592 18593@node GNAT.Bubble_Sort_G (g-busorg.ads) 18594@section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) 18595@cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) 18596@cindex Sorting 18597@cindex Bubble sort 18598 18599@noindent 18600Similar to @code{Bubble_Sort_A} except that the move and sorting procedures 18601are provided as generic parameters, this improves efficiency, especially 18602if the procedures can be inlined, at the expense of duplicating code for 18603multiple instantiations. 18604 18605@node GNAT.Byte_Order_Mark (g-byorma.ads) 18606@section @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads}) 18607@cindex @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads}) 18608@cindex UTF-8 representation 18609@cindex Wide characte representations 18610 18611@noindent 18612Provides a routine which given a string, reads the start of the string to 18613see whether it is one of the standard byte order marks (BOM's) which signal 18614the encoding of the string. The routine includes detection of special XML 18615sequences for various UCS input formats. 18616 18617@node GNAT.Byte_Swapping (g-bytswa.ads) 18618@section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads}) 18619@cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads}) 18620@cindex Byte swapping 18621@cindex Endianness 18622 18623@noindent 18624General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. 18625Machine-specific implementations are available in some cases. 18626 18627@node GNAT.Calendar (g-calend.ads) 18628@section @code{GNAT.Calendar} (@file{g-calend.ads}) 18629@cindex @code{GNAT.Calendar} (@file{g-calend.ads}) 18630@cindex @code{Calendar} 18631 18632@noindent 18633Extends the facilities provided by @code{Ada.Calendar} to include handling 18634of days of the week, an extended @code{Split} and @code{Time_Of} capability. 18635Also provides conversion of @code{Ada.Calendar.Time} values to and from the 18636C @code{timeval} format. 18637 18638@node GNAT.Calendar.Time_IO (g-catiio.ads) 18639@section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) 18640@cindex @code{Calendar} 18641@cindex Time 18642@cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) 18643 18644@node GNAT.CRC32 (g-crc32.ads) 18645@section @code{GNAT.CRC32} (@file{g-crc32.ads}) 18646@cindex @code{GNAT.CRC32} (@file{g-crc32.ads}) 18647@cindex CRC32 18648@cindex Cyclic Redundancy Check 18649 18650@noindent 18651This package implements the CRC-32 algorithm. For a full description 18652of this algorithm see 18653``Computation of Cyclic Redundancy Checks via Table Look-Up'', 18654@cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013, 18655Aug.@: 1988. Sarwate, D.V@. 18656 18657@node GNAT.Case_Util (g-casuti.ads) 18658@section @code{GNAT.Case_Util} (@file{g-casuti.ads}) 18659@cindex @code{GNAT.Case_Util} (@file{g-casuti.ads}) 18660@cindex Casing utilities 18661@cindex Character handling (@code{GNAT.Case_Util}) 18662 18663@noindent 18664A set of simple routines for handling upper and lower casing of strings 18665without the overhead of the full casing tables 18666in @code{Ada.Characters.Handling}. 18667 18668@node GNAT.CGI (g-cgi.ads) 18669@section @code{GNAT.CGI} (@file{g-cgi.ads}) 18670@cindex @code{GNAT.CGI} (@file{g-cgi.ads}) 18671@cindex CGI (Common Gateway Interface) 18672 18673@noindent 18674This is a package for interfacing a GNAT program with a Web server via the 18675Common Gateway Interface (CGI)@. Basically this package parses the CGI 18676parameters, which are a set of key/value pairs sent by the Web server. It 18677builds a table whose index is the key and provides some services to deal 18678with this table. 18679 18680@node GNAT.CGI.Cookie (g-cgicoo.ads) 18681@section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) 18682@cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) 18683@cindex CGI (Common Gateway Interface) cookie support 18684@cindex Cookie support in CGI 18685 18686@noindent 18687This is a package to interface a GNAT program with a Web server via the 18688Common Gateway Interface (CGI). It exports services to deal with Web 18689cookies (piece of information kept in the Web client software). 18690 18691@node GNAT.CGI.Debug (g-cgideb.ads) 18692@section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) 18693@cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) 18694@cindex CGI (Common Gateway Interface) debugging 18695 18696@noindent 18697This is a package to help debugging CGI (Common Gateway Interface) 18698programs written in Ada. 18699 18700@node GNAT.Command_Line (g-comlin.ads) 18701@section @code{GNAT.Command_Line} (@file{g-comlin.ads}) 18702@cindex @code{GNAT.Command_Line} (@file{g-comlin.ads}) 18703@cindex Command line 18704 18705@noindent 18706Provides a high level interface to @code{Ada.Command_Line} facilities, 18707including the ability to scan for named switches with optional parameters 18708and expand file names using wild card notations. 18709 18710@node GNAT.Compiler_Version (g-comver.ads) 18711@section @code{GNAT.Compiler_Version} (@file{g-comver.ads}) 18712@cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads}) 18713@cindex Compiler Version 18714@cindex Version, of compiler 18715 18716@noindent 18717Provides a routine for obtaining the version of the compiler used to 18718compile the program. More accurately this is the version of the binder 18719used to bind the program (this will normally be the same as the version 18720of the compiler if a consistent tool set is used to compile all units 18721of a partition). 18722 18723@node GNAT.Ctrl_C (g-ctrl_c.ads) 18724@section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) 18725@cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) 18726@cindex Interrupt 18727 18728@noindent 18729Provides a simple interface to handle Ctrl-C keyboard events. 18730 18731@node GNAT.Current_Exception (g-curexc.ads) 18732@section @code{GNAT.Current_Exception} (@file{g-curexc.ads}) 18733@cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads}) 18734@cindex Current exception 18735@cindex Exception retrieval 18736 18737@noindent 18738Provides access to information on the current exception that has been raised 18739without the need for using the Ada 95 / Ada 2005 exception choice parameter 18740specification syntax. 18741This is particularly useful in simulating typical facilities for 18742obtaining information about exceptions provided by Ada 83 compilers. 18743 18744@node GNAT.Debug_Pools (g-debpoo.ads) 18745@section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) 18746@cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) 18747@cindex Debugging 18748@cindex Debug pools 18749@cindex Memory corruption debugging 18750 18751@noindent 18752Provide a debugging storage pools that helps tracking memory corruption 18753problems. @xref{The GNAT Debug Pool Facility,,, gnat_ugn, 18754@value{EDITION} User's Guide}. 18755 18756@node GNAT.Debug_Utilities (g-debuti.ads) 18757@section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) 18758@cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) 18759@cindex Debugging 18760 18761@noindent 18762Provides a few useful utilities for debugging purposes, including conversion 18763to and from string images of address values. Supports both C and Ada formats 18764for hexadecimal literals. 18765 18766@node GNAT.Decode_String (g-decstr.ads) 18767@section @code{GNAT.Decode_String} (@file{g-decstr.ads}) 18768@cindex @code{GNAT.Decode_String} (@file{g-decstr.ads}) 18769@cindex Decoding strings 18770@cindex String decoding 18771@cindex Wide character encoding 18772@cindex UTF-8 18773@cindex Unicode 18774 18775@noindent 18776A generic package providing routines for decoding wide character and wide wide 18777character strings encoded as sequences of 8-bit characters using a specified 18778encoding method. Includes validation routines, and also routines for stepping 18779to next or previous encoded character in an encoded string. 18780Useful in conjunction with Unicode character coding. Note there is a 18781preinstantiation for UTF-8. See next entry. 18782 18783@node GNAT.Decode_UTF8_String (g-deutst.ads) 18784@section @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads}) 18785@cindex @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads}) 18786@cindex Decoding strings 18787@cindex Decoding UTF-8 strings 18788@cindex UTF-8 string decoding 18789@cindex Wide character decoding 18790@cindex UTF-8 18791@cindex Unicode 18792 18793@noindent 18794A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. 18795 18796@node GNAT.Directory_Operations (g-dirope.ads) 18797@section @code{GNAT.Directory_Operations} (@file{g-dirope.ads}) 18798@cindex @code{GNAT.Directory_Operations} (@file{g-dirope.ads}) 18799@cindex Directory operations 18800 18801@noindent 18802Provides a set of routines for manipulating directories, including changing 18803the current directory, making new directories, and scanning the files in a 18804directory. 18805 18806@node GNAT.Directory_Operations.Iteration (g-diopit.ads) 18807@section @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads}) 18808@cindex @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads}) 18809@cindex Directory operations iteration 18810 18811@noindent 18812A child unit of GNAT.Directory_Operations providing additional operations 18813for iterating through directories. 18814 18815@node GNAT.Dynamic_HTables (g-dynhta.ads) 18816@section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) 18817@cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) 18818@cindex Hash tables 18819 18820@noindent 18821A generic implementation of hash tables that can be used to hash arbitrary 18822data. Provided in two forms, a simple form with built in hash functions, 18823and a more complex form in which the hash function is supplied. 18824 18825@noindent 18826This package provides a facility similar to that of @code{GNAT.HTable}, 18827except that this package declares a type that can be used to define 18828dynamic instances of the hash table, while an instantiation of 18829@code{GNAT.HTable} creates a single instance of the hash table. 18830 18831@node GNAT.Dynamic_Tables (g-dyntab.ads) 18832@section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) 18833@cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) 18834@cindex Table implementation 18835@cindex Arrays, extendable 18836 18837@noindent 18838A generic package providing a single dimension array abstraction where the 18839length of the array can be dynamically modified. 18840 18841@noindent 18842This package provides a facility similar to that of @code{GNAT.Table}, 18843except that this package declares a type that can be used to define 18844dynamic instances of the table, while an instantiation of 18845@code{GNAT.Table} creates a single instance of the table type. 18846 18847@node GNAT.Encode_String (g-encstr.ads) 18848@section @code{GNAT.Encode_String} (@file{g-encstr.ads}) 18849@cindex @code{GNAT.Encode_String} (@file{g-encstr.ads}) 18850@cindex Encoding strings 18851@cindex String encoding 18852@cindex Wide character encoding 18853@cindex UTF-8 18854@cindex Unicode 18855 18856@noindent 18857A generic package providing routines for encoding wide character and wide 18858wide character strings as sequences of 8-bit characters using a specified 18859encoding method. Useful in conjunction with Unicode character coding. 18860Note there is a preinstantiation for UTF-8. See next entry. 18861 18862@node GNAT.Encode_UTF8_String (g-enutst.ads) 18863@section @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads}) 18864@cindex @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads}) 18865@cindex Encoding strings 18866@cindex Encoding UTF-8 strings 18867@cindex UTF-8 string encoding 18868@cindex Wide character encoding 18869@cindex UTF-8 18870@cindex Unicode 18871 18872@noindent 18873A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. 18874 18875@node GNAT.Exception_Actions (g-excact.ads) 18876@section @code{GNAT.Exception_Actions} (@file{g-excact.ads}) 18877@cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads}) 18878@cindex Exception actions 18879 18880@noindent 18881Provides callbacks when an exception is raised. Callbacks can be registered 18882for specific exceptions, or when any exception is raised. This 18883can be used for instance to force a core dump to ease debugging. 18884 18885@node GNAT.Exception_Traces (g-exctra.ads) 18886@section @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) 18887@cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) 18888@cindex Exception traces 18889@cindex Debugging 18890 18891@noindent 18892Provides an interface allowing to control automatic output upon exception 18893occurrences. 18894 18895@node GNAT.Exceptions (g-except.ads) 18896@section @code{GNAT.Exceptions} (@file{g-expect.ads}) 18897@cindex @code{GNAT.Exceptions} (@file{g-expect.ads}) 18898@cindex Exceptions, Pure 18899@cindex Pure packages, exceptions 18900 18901@noindent 18902Normally it is not possible to raise an exception with 18903a message from a subprogram in a pure package, since the 18904necessary types and subprograms are in @code{Ada.Exceptions} 18905which is not a pure unit. @code{GNAT.Exceptions} provides a 18906facility for getting around this limitation for a few 18907predefined exceptions, and for example allow raising 18908@code{Constraint_Error} with a message from a pure subprogram. 18909 18910@node GNAT.Expect (g-expect.ads) 18911@section @code{GNAT.Expect} (@file{g-expect.ads}) 18912@cindex @code{GNAT.Expect} (@file{g-expect.ads}) 18913 18914@noindent 18915Provides a set of subprograms similar to what is available 18916with the standard Tcl Expect tool. 18917It allows you to easily spawn and communicate with an external process. 18918You can send commands or inputs to the process, and compare the output 18919with some expected regular expression. Currently @code{GNAT.Expect} 18920is implemented on all native GNAT ports except for OpenVMS@. 18921It is not implemented for cross ports, and in particular is not 18922implemented for VxWorks or LynxOS@. 18923 18924@node GNAT.Expect.TTY (g-exptty.ads) 18925@section @code{GNAT.Expect.TTY} (@file{g-exptty.ads}) 18926@cindex @code{GNAT.Expect.TTY} (@file{g-exptty.ads}) 18927 18928@noindent 18929As GNAT.Expect but using pseudo-terminal. 18930Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT 18931ports except for OpenVMS@. It is not implemented for cross ports, and 18932in particular is not implemented for VxWorks or LynxOS@. 18933 18934@node GNAT.Float_Control (g-flocon.ads) 18935@section @code{GNAT.Float_Control} (@file{g-flocon.ads}) 18936@cindex @code{GNAT.Float_Control} (@file{g-flocon.ads}) 18937@cindex Floating-Point Processor 18938 18939@noindent 18940Provides an interface for resetting the floating-point processor into the 18941mode required for correct semantic operation in Ada. Some third party 18942library calls may cause this mode to be modified, and the Reset procedure 18943in this package can be used to reestablish the required mode. 18944 18945@node GNAT.Heap_Sort (g-heasor.ads) 18946@section @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) 18947@cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) 18948@cindex Sorting 18949 18950@noindent 18951Provides a general implementation of heap sort usable for sorting arbitrary 18952data items. Exchange and comparison procedures are provided by passing 18953access-to-procedure values. The algorithm used is a modified heap sort 18954that performs approximately N*log(N) comparisons in the worst case. 18955 18956@node GNAT.Heap_Sort_A (g-hesora.ads) 18957@section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) 18958@cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) 18959@cindex Sorting 18960 18961@noindent 18962Provides a general implementation of heap sort usable for sorting arbitrary 18963data items. Move and comparison procedures are provided by passing 18964access-to-procedure values. The algorithm used is a modified heap sort 18965that performs approximately N*log(N) comparisons in the worst case. 18966This differs from @code{GNAT.Heap_Sort} in having a less convenient 18967interface, but may be slightly more efficient. 18968 18969@node GNAT.Heap_Sort_G (g-hesorg.ads) 18970@section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) 18971@cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) 18972@cindex Sorting 18973 18974@noindent 18975Similar to @code{Heap_Sort_A} except that the move and sorting procedures 18976are provided as generic parameters, this improves efficiency, especially 18977if the procedures can be inlined, at the expense of duplicating code for 18978multiple instantiations. 18979 18980@node GNAT.HTable (g-htable.ads) 18981@section @code{GNAT.HTable} (@file{g-htable.ads}) 18982@cindex @code{GNAT.HTable} (@file{g-htable.ads}) 18983@cindex Hash tables 18984 18985@noindent 18986A generic implementation of hash tables that can be used to hash arbitrary 18987data. Provides two approaches, one a simple static approach, and the other 18988allowing arbitrary dynamic hash tables. 18989 18990@node GNAT.IO (g-io.ads) 18991@section @code{GNAT.IO} (@file{g-io.ads}) 18992@cindex @code{GNAT.IO} (@file{g-io.ads}) 18993@cindex Simple I/O 18994@cindex Input/Output facilities 18995 18996@noindent 18997A simple preelaborable input-output package that provides a subset of 18998simple Text_IO functions for reading characters and strings from 18999Standard_Input, and writing characters, strings and integers to either 19000Standard_Output or Standard_Error. 19001 19002@node GNAT.IO_Aux (g-io_aux.ads) 19003@section @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) 19004@cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) 19005@cindex Text_IO 19006@cindex Input/Output facilities 19007 19008Provides some auxiliary functions for use with Text_IO, including a test 19009for whether a file exists, and functions for reading a line of text. 19010 19011@node GNAT.Lock_Files (g-locfil.ads) 19012@section @code{GNAT.Lock_Files} (@file{g-locfil.ads}) 19013@cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads}) 19014@cindex File locking 19015@cindex Locking using files 19016 19017@noindent 19018Provides a general interface for using files as locks. Can be used for 19019providing program level synchronization. 19020 19021@node GNAT.MBBS_Discrete_Random (g-mbdira.ads) 19022@section @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads}) 19023@cindex @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads}) 19024@cindex Random number generation 19025 19026@noindent 19027The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses 19028a modified version of the Blum-Blum-Shub generator. 19029 19030@node GNAT.MBBS_Float_Random (g-mbflra.ads) 19031@section @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads}) 19032@cindex @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads}) 19033@cindex Random number generation 19034 19035@noindent 19036The original implementation of @code{Ada.Numerics.Float_Random}. Uses 19037a modified version of the Blum-Blum-Shub generator. 19038 19039@node GNAT.MD5 (g-md5.ads) 19040@section @code{GNAT.MD5} (@file{g-md5.ads}) 19041@cindex @code{GNAT.MD5} (@file{g-md5.ads}) 19042@cindex Message Digest MD5 19043 19044@noindent 19045Implements the MD5 Message-Digest Algorithm as described in RFC 1321. 19046 19047@node GNAT.Memory_Dump (g-memdum.ads) 19048@section @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) 19049@cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) 19050@cindex Dump Memory 19051 19052@noindent 19053Provides a convenient routine for dumping raw memory to either the 19054standard output or standard error files. Uses GNAT.IO for actual 19055output. 19056 19057@node GNAT.Most_Recent_Exception (g-moreex.ads) 19058@section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) 19059@cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) 19060@cindex Exception, obtaining most recent 19061 19062@noindent 19063Provides access to the most recently raised exception. Can be used for 19064various logging purposes, including duplicating functionality of some 19065Ada 83 implementation dependent extensions. 19066 19067@node GNAT.OS_Lib (g-os_lib.ads) 19068@section @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) 19069@cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) 19070@cindex Operating System interface 19071@cindex Spawn capability 19072 19073@noindent 19074Provides a range of target independent operating system interface functions, 19075including time/date management, file operations, subprocess management, 19076including a portable spawn procedure, and access to environment variables 19077and error return codes. 19078 19079@node GNAT.Perfect_Hash_Generators (g-pehage.ads) 19080@section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads}) 19081@cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads}) 19082@cindex Hash functions 19083 19084@noindent 19085Provides a generator of static minimal perfect hash functions. No 19086collisions occur and each item can be retrieved from the table in one 19087probe (perfect property). The hash table size corresponds to the exact 19088size of the key set and no larger (minimal property). The key set has to 19089be know in advance (static property). The hash functions are also order 19090preserving. If w2 is inserted after w1 in the generator, their 19091hashcode are in the same order. These hashing functions are very 19092convenient for use with realtime applications. 19093 19094@node GNAT.Random_Numbers (g-rannum.ads) 19095@section @code{GNAT.Random_Numbers} (@file{g-rannum.ads}) 19096@cindex @code{GNAT.Random_Numbers} (@file{g-rannum.ads}) 19097@cindex Random number generation 19098 19099@noindent 19100Provides random number capabilities which extend those available in the 19101standard Ada library and are more convenient to use. 19102 19103@node GNAT.Regexp (g-regexp.ads) 19104@section @code{GNAT.Regexp} (@file{g-regexp.ads}) 19105@cindex @code{GNAT.Regexp} (@file{g-regexp.ads}) 19106@cindex Regular expressions 19107@cindex Pattern matching 19108 19109@noindent 19110A simple implementation of regular expressions, using a subset of regular 19111expression syntax copied from familiar Unix style utilities. This is the 19112simples of the three pattern matching packages provided, and is particularly 19113suitable for ``file globbing'' applications. 19114 19115@node GNAT.Registry (g-regist.ads) 19116@section @code{GNAT.Registry} (@file{g-regist.ads}) 19117@cindex @code{GNAT.Registry} (@file{g-regist.ads}) 19118@cindex Windows Registry 19119 19120@noindent 19121This is a high level binding to the Windows registry. It is possible to 19122do simple things like reading a key value, creating a new key. For full 19123registry API, but at a lower level of abstraction, refer to the Win32.Winreg 19124package provided with the Win32Ada binding 19125 19126@node GNAT.Regpat (g-regpat.ads) 19127@section @code{GNAT.Regpat} (@file{g-regpat.ads}) 19128@cindex @code{GNAT.Regpat} (@file{g-regpat.ads}) 19129@cindex Regular expressions 19130@cindex Pattern matching 19131 19132@noindent 19133A complete implementation of Unix-style regular expression matching, copied 19134from the original V7 style regular expression library written in C by 19135Henry Spencer (and binary compatible with this C library). 19136 19137@node GNAT.Secondary_Stack_Info (g-sestin.ads) 19138@section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) 19139@cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) 19140@cindex Secondary Stack Info 19141 19142@noindent 19143Provide the capability to query the high water mark of the current task's 19144secondary stack. 19145 19146@node GNAT.Semaphores (g-semaph.ads) 19147@section @code{GNAT.Semaphores} (@file{g-semaph.ads}) 19148@cindex @code{GNAT.Semaphores} (@file{g-semaph.ads}) 19149@cindex Semaphores 19150 19151@noindent 19152Provides classic counting and binary semaphores using protected types. 19153 19154@node GNAT.Serial_Communications (g-sercom.ads) 19155@section @code{GNAT.Serial_Communications} (@file{g-sercom.ads}) 19156@cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads}) 19157@cindex Serial_Communications 19158 19159@noindent 19160Provides a simple interface to send and receive data over a serial 19161port. This is only supported on GNU/Linux and Windows. 19162 19163@node GNAT.SHA1 (g-sha1.ads) 19164@section @code{GNAT.SHA1} (@file{g-sha1.ads}) 19165@cindex @code{GNAT.SHA1} (@file{g-sha1.ads}) 19166@cindex Secure Hash Algorithm SHA-1 19167 19168@noindent 19169Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 19170and RFC 3174. 19171 19172@node GNAT.SHA224 (g-sha224.ads) 19173@section @code{GNAT.SHA224} (@file{g-sha224.ads}) 19174@cindex @code{GNAT.SHA224} (@file{g-sha224.ads}) 19175@cindex Secure Hash Algorithm SHA-224 19176 19177@noindent 19178Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3. 19179 19180@node GNAT.SHA256 (g-sha256.ads) 19181@section @code{GNAT.SHA256} (@file{g-sha256.ads}) 19182@cindex @code{GNAT.SHA256} (@file{g-sha256.ads}) 19183@cindex Secure Hash Algorithm SHA-256 19184 19185@noindent 19186Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3. 19187 19188@node GNAT.SHA384 (g-sha384.ads) 19189@section @code{GNAT.SHA384} (@file{g-sha384.ads}) 19190@cindex @code{GNAT.SHA384} (@file{g-sha384.ads}) 19191@cindex Secure Hash Algorithm SHA-384 19192 19193@noindent 19194Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3. 19195 19196@node GNAT.SHA512 (g-sha512.ads) 19197@section @code{GNAT.SHA512} (@file{g-sha512.ads}) 19198@cindex @code{GNAT.SHA512} (@file{g-sha512.ads}) 19199@cindex Secure Hash Algorithm SHA-512 19200 19201@noindent 19202Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3. 19203 19204@node GNAT.Signals (g-signal.ads) 19205@section @code{GNAT.Signals} (@file{g-signal.ads}) 19206@cindex @code{GNAT.Signals} (@file{g-signal.ads}) 19207@cindex Signals 19208 19209@noindent 19210Provides the ability to manipulate the blocked status of signals on supported 19211targets. 19212 19213@node GNAT.Sockets (g-socket.ads) 19214@section @code{GNAT.Sockets} (@file{g-socket.ads}) 19215@cindex @code{GNAT.Sockets} (@file{g-socket.ads}) 19216@cindex Sockets 19217 19218@noindent 19219A high level and portable interface to develop sockets based applications. 19220This package is based on the sockets thin binding found in 19221@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented 19222on all native GNAT ports except for OpenVMS@. It is not implemented 19223for the LynxOS@ cross port. 19224 19225@node GNAT.Source_Info (g-souinf.ads) 19226@section @code{GNAT.Source_Info} (@file{g-souinf.ads}) 19227@cindex @code{GNAT.Source_Info} (@file{g-souinf.ads}) 19228@cindex Source Information 19229 19230@noindent 19231Provides subprograms that give access to source code information known at 19232compile time, such as the current file name and line number. 19233 19234@node GNAT.Spelling_Checker (g-speche.ads) 19235@section @code{GNAT.Spelling_Checker} (@file{g-speche.ads}) 19236@cindex @code{GNAT.Spelling_Checker} (@file{g-speche.ads}) 19237@cindex Spell checking 19238 19239@noindent 19240Provides a function for determining whether one string is a plausible 19241near misspelling of another string. 19242 19243@node GNAT.Spelling_Checker_Generic (g-spchge.ads) 19244@section @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads}) 19245@cindex @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads}) 19246@cindex Spell checking 19247 19248@noindent 19249Provides a generic function that can be instantiated with a string type for 19250determining whether one string is a plausible near misspelling of another 19251string. 19252 19253@node GNAT.Spitbol.Patterns (g-spipat.ads) 19254@section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) 19255@cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) 19256@cindex SPITBOL pattern matching 19257@cindex Pattern matching 19258 19259@noindent 19260A complete implementation of SNOBOL4 style pattern matching. This is the 19261most elaborate of the pattern matching packages provided. It fully duplicates 19262the SNOBOL4 dynamic pattern construction and matching capabilities, using the 19263efficient algorithm developed by Robert Dewar for the SPITBOL system. 19264 19265@node GNAT.Spitbol (g-spitbo.ads) 19266@section @code{GNAT.Spitbol} (@file{g-spitbo.ads}) 19267@cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads}) 19268@cindex SPITBOL interface 19269 19270@noindent 19271The top level package of the collection of SPITBOL-style functionality, this 19272package provides basic SNOBOL4 string manipulation functions, such as 19273Pad, Reverse, Trim, Substr capability, as well as a generic table function 19274useful for constructing arbitrary mappings from strings in the style of 19275the SNOBOL4 TABLE function. 19276 19277@node GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 19278@section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) 19279@cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) 19280@cindex Sets of strings 19281@cindex SPITBOL Tables 19282 19283@noindent 19284A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 19285for type @code{Standard.Boolean}, giving an implementation of sets of 19286string values. 19287 19288@node GNAT.Spitbol.Table_Integer (g-sptain.ads) 19289@section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) 19290@cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) 19291@cindex Integer maps 19292@cindex Maps 19293@cindex SPITBOL Tables 19294 19295@noindent 19296A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 19297for type @code{Standard.Integer}, giving an implementation of maps 19298from string to integer values. 19299 19300@node GNAT.Spitbol.Table_VString (g-sptavs.ads) 19301@section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) 19302@cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) 19303@cindex String maps 19304@cindex Maps 19305@cindex SPITBOL Tables 19306 19307@noindent 19308A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for 19309a variable length string type, giving an implementation of general 19310maps from strings to strings. 19311 19312@node GNAT.SSE (g-sse.ads) 19313@section @code{GNAT.SSE} (@file{g-sse.ads}) 19314@cindex @code{GNAT.SSE} (@file{g-sse.ads}) 19315 19316@noindent 19317Root of a set of units aimed at offering Ada bindings to a subset of 19318the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of 19319targets. It exposes vector component types together with a general 19320introduction to the binding contents and use. 19321 19322@node GNAT.SSE.Vector_Types (g-ssvety.ads) 19323@section @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads}) 19324@cindex @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads}) 19325 19326@noindent 19327SSE vector types for use with SSE related intrinsics. 19328 19329@node GNAT.Strings (g-string.ads) 19330@section @code{GNAT.Strings} (@file{g-string.ads}) 19331@cindex @code{GNAT.Strings} (@file{g-string.ads}) 19332 19333@noindent 19334Common String access types and related subprograms. Basically it 19335defines a string access and an array of string access types. 19336 19337@node GNAT.String_Split (g-strspl.ads) 19338@section @code{GNAT.String_Split} (@file{g-strspl.ads}) 19339@cindex @code{GNAT.String_Split} (@file{g-strspl.ads}) 19340@cindex String splitter 19341 19342@noindent 19343Useful string manipulation routines: given a set of separators, split 19344a string wherever the separators appear, and provide direct access 19345to the resulting slices. This package is instantiated from 19346@code{GNAT.Array_Split}. 19347 19348@node GNAT.Table (g-table.ads) 19349@section @code{GNAT.Table} (@file{g-table.ads}) 19350@cindex @code{GNAT.Table} (@file{g-table.ads}) 19351@cindex Table implementation 19352@cindex Arrays, extendable 19353 19354@noindent 19355A generic package providing a single dimension array abstraction where the 19356length of the array can be dynamically modified. 19357 19358@noindent 19359This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, 19360except that this package declares a single instance of the table type, 19361while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be 19362used to define dynamic instances of the table. 19363 19364@node GNAT.Task_Lock (g-tasloc.ads) 19365@section @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) 19366@cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) 19367@cindex Task synchronization 19368@cindex Task locking 19369@cindex Locking 19370 19371@noindent 19372A very simple facility for locking and unlocking sections of code using a 19373single global task lock. Appropriate for use in situations where contention 19374between tasks is very rarely expected. 19375 19376@node GNAT.Time_Stamp (g-timsta.ads) 19377@section @code{GNAT.Time_Stamp} (@file{g-timsta.ads}) 19378@cindex @code{GNAT.Time_Stamp} (@file{g-timsta.ads}) 19379@cindex Time stamp 19380@cindex Current time 19381 19382@noindent 19383Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that 19384represents the current date and time in ISO 8601 format. This is a very simple 19385routine with minimal code and there are no dependencies on any other unit. 19386 19387@node GNAT.Threads (g-thread.ads) 19388@section @code{GNAT.Threads} (@file{g-thread.ads}) 19389@cindex @code{GNAT.Threads} (@file{g-thread.ads}) 19390@cindex Foreign threads 19391@cindex Threads, foreign 19392 19393@noindent 19394Provides facilities for dealing with foreign threads which need to be known 19395by the GNAT run-time system. Consult the documentation of this package for 19396further details if your program has threads that are created by a non-Ada 19397environment which then accesses Ada code. 19398 19399@node GNAT.Traceback (g-traceb.ads) 19400@section @code{GNAT.Traceback} (@file{g-traceb.ads}) 19401@cindex @code{GNAT.Traceback} (@file{g-traceb.ads}) 19402@cindex Trace back facilities 19403 19404@noindent 19405Provides a facility for obtaining non-symbolic traceback information, useful 19406in various debugging situations. 19407 19408@node GNAT.Traceback.Symbolic (g-trasym.ads) 19409@section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) 19410@cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) 19411@cindex Trace back facilities 19412 19413@node GNAT.UTF_32 (g-utf_32.ads) 19414@section @code{GNAT.UTF_32} (@file{g-table.ads}) 19415@cindex @code{GNAT.UTF_32} (@file{g-table.ads}) 19416@cindex Wide character codes 19417 19418@noindent 19419This is a package intended to be used in conjunction with the 19420@code{Wide_Character} type in Ada 95 and the 19421@code{Wide_Wide_Character} type in Ada 2005 (available 19422in @code{GNAT} in Ada 2005 mode). This package contains 19423Unicode categorization routines, as well as lexical 19424categorization routines corresponding to the Ada 2005 19425lexical rules for identifiers and strings, and also a 19426lower case to upper case fold routine corresponding to 19427the Ada 2005 rules for identifier equivalence. 19428 19429@node GNAT.UTF_32_Spelling_Checker (g-u3spch.ads) 19430@section @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads}) 19431@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads}) 19432@cindex Spell checking 19433 19434@noindent 19435Provides a function for determining whether one wide wide string is a plausible 19436near misspelling of another wide wide string, where the strings are represented 19437using the UTF_32_String type defined in System.Wch_Cnv. 19438 19439@node GNAT.Wide_Spelling_Checker (g-wispch.ads) 19440@section @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads}) 19441@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads}) 19442@cindex Spell checking 19443 19444@noindent 19445Provides a function for determining whether one wide string is a plausible 19446near misspelling of another wide string. 19447 19448@node GNAT.Wide_String_Split (g-wistsp.ads) 19449@section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) 19450@cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) 19451@cindex Wide_String splitter 19452 19453@noindent 19454Useful wide string manipulation routines: given a set of separators, split 19455a wide string wherever the separators appear, and provide direct access 19456to the resulting slices. This package is instantiated from 19457@code{GNAT.Array_Split}. 19458 19459@node GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) 19460@section @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads}) 19461@cindex @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads}) 19462@cindex Spell checking 19463 19464@noindent 19465Provides a function for determining whether one wide wide string is a plausible 19466near misspelling of another wide wide string. 19467 19468@node GNAT.Wide_Wide_String_Split (g-zistsp.ads) 19469@section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads}) 19470@cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads}) 19471@cindex Wide_Wide_String splitter 19472 19473@noindent 19474Useful wide wide string manipulation routines: given a set of separators, split 19475a wide wide string wherever the separators appear, and provide direct access 19476to the resulting slices. This package is instantiated from 19477@code{GNAT.Array_Split}. 19478 19479@node Interfaces.C.Extensions (i-cexten.ads) 19480@section @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) 19481@cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) 19482 19483@noindent 19484This package contains additional C-related definitions, intended 19485for use with either manually or automatically generated bindings 19486to C libraries. 19487 19488@node Interfaces.C.Streams (i-cstrea.ads) 19489@section @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) 19490@cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) 19491@cindex C streams, interfacing 19492 19493@noindent 19494This package is a binding for the most commonly used operations 19495on C streams. 19496 19497@node Interfaces.CPP (i-cpp.ads) 19498@section @code{Interfaces.CPP} (@file{i-cpp.ads}) 19499@cindex @code{Interfaces.CPP} (@file{i-cpp.ads}) 19500@cindex C++ interfacing 19501@cindex Interfacing, to C++ 19502 19503@noindent 19504This package provides facilities for use in interfacing to C++. It 19505is primarily intended to be used in connection with automated tools 19506for the generation of C++ interfaces. 19507 19508@node Interfaces.Packed_Decimal (i-pacdec.ads) 19509@section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) 19510@cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) 19511@cindex IBM Packed Format 19512@cindex Packed Decimal 19513 19514@noindent 19515This package provides a set of routines for conversions to and 19516from a packed decimal format compatible with that used on IBM 19517mainframes. 19518 19519@node Interfaces.VxWorks (i-vxwork.ads) 19520@section @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) 19521@cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) 19522@cindex Interfacing to VxWorks 19523@cindex VxWorks, interfacing 19524 19525@noindent 19526This package provides a limited binding to the VxWorks API. 19527In particular, it interfaces with the 19528VxWorks hardware interrupt facilities. 19529 19530@node Interfaces.VxWorks.IO (i-vxwoio.ads) 19531@section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) 19532@cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) 19533@cindex Interfacing to VxWorks' I/O 19534@cindex VxWorks, I/O interfacing 19535@cindex VxWorks, Get_Immediate 19536@cindex Get_Immediate, VxWorks 19537 19538@noindent 19539This package provides a binding to the ioctl (IO/Control) 19540function of VxWorks, defining a set of option values and 19541function codes. A particular use of this package is 19542to enable the use of Get_Immediate under VxWorks. 19543 19544@node System.Address_Image (s-addima.ads) 19545@section @code{System.Address_Image} (@file{s-addima.ads}) 19546@cindex @code{System.Address_Image} (@file{s-addima.ads}) 19547@cindex Address image 19548@cindex Image, of an address 19549 19550@noindent 19551This function provides a useful debugging 19552function that gives an (implementation dependent) 19553string which identifies an address. 19554 19555@node System.Assertions (s-assert.ads) 19556@section @code{System.Assertions} (@file{s-assert.ads}) 19557@cindex @code{System.Assertions} (@file{s-assert.ads}) 19558@cindex Assertions 19559@cindex Assert_Failure, exception 19560 19561@noindent 19562This package provides the declaration of the exception raised 19563by an run-time assertion failure, as well as the routine that 19564is used internally to raise this assertion. 19565 19566@node System.Memory (s-memory.ads) 19567@section @code{System.Memory} (@file{s-memory.ads}) 19568@cindex @code{System.Memory} (@file{s-memory.ads}) 19569@cindex Memory allocation 19570 19571@noindent 19572This package provides the interface to the low level routines used 19573by the generated code for allocation and freeing storage for the 19574default storage pool (analogous to the C routines malloc and free. 19575It also provides a reallocation interface analogous to the C routine 19576realloc. The body of this unit may be modified to provide alternative 19577allocation mechanisms for the default pool, and in addition, direct 19578calls to this unit may be made for low level allocation uses (for 19579example see the body of @code{GNAT.Tables}). 19580 19581@node System.Multiprocessors (s-multip.ads) 19582@section @code{System.Multiprocessors} (@file{s-multip.ads}) 19583@cindex @code{System.Multiprocessors} (@file{s-multip.ads}) 19584@cindex Multiprocessor interface 19585This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 19586in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 19587technically an implementation-defined addition). 19588 19589@node System.Multiprocessors.Dispatching_Domains (s-mudido.ads) 19590@section @code{System.Multiprocessors.Dispatching_Domains} (@file{s-mudido.ads}) 19591@cindex @code{System.Multiprocessors.Dispatching_Domains} (@file{s-mudido.ads}) 19592@cindex Multiprocessor interface 19593This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but 19594in GNAT we also make it available in Ada 95 and Ada 2005 (where it is 19595technically an implementation-defined addition). 19596 19597@node System.Partition_Interface (s-parint.ads) 19598@section @code{System.Partition_Interface} (@file{s-parint.ads}) 19599@cindex @code{System.Partition_Interface} (@file{s-parint.ads}) 19600@cindex Partition interfacing functions 19601 19602@noindent 19603This package provides facilities for partition interfacing. It 19604is used primarily in a distribution context when using Annex E 19605with @code{GLADE}. 19606 19607@node System.Pool_Global (s-pooglo.ads) 19608@section @code{System.Pool_Global} (@file{s-pooglo.ads}) 19609@cindex @code{System.Pool_Global} (@file{s-pooglo.ads}) 19610@cindex Storage pool, global 19611@cindex Global storage pool 19612 19613@noindent 19614This package provides a storage pool that is equivalent to the default 19615storage pool used for access types for which no pool is specifically 19616declared. It uses malloc/free to allocate/free and does not attempt to 19617do any automatic reclamation. 19618 19619@node System.Pool_Local (s-pooloc.ads) 19620@section @code{System.Pool_Local} (@file{s-pooloc.ads}) 19621@cindex @code{System.Pool_Local} (@file{s-pooloc.ads}) 19622@cindex Storage pool, local 19623@cindex Local storage pool 19624 19625@noindent 19626This package provides a storage pool that is intended for use with locally 19627defined access types. It uses malloc/free for allocate/free, and maintains 19628a list of allocated blocks, so that all storage allocated for the pool can 19629be freed automatically when the pool is finalized. 19630 19631@node System.Restrictions (s-restri.ads) 19632@section @code{System.Restrictions} (@file{s-restri.ads}) 19633@cindex @code{System.Restrictions} (@file{s-restri.ads}) 19634@cindex Run-time restrictions access 19635 19636@noindent 19637This package provides facilities for accessing at run time 19638the status of restrictions specified at compile time for 19639the partition. Information is available both with regard 19640to actual restrictions specified, and with regard to 19641compiler determined information on which restrictions 19642are violated by one or more packages in the partition. 19643 19644@node System.Rident (s-rident.ads) 19645@section @code{System.Rident} (@file{s-rident.ads}) 19646@cindex @code{System.Rident} (@file{s-rident.ads}) 19647@cindex Restrictions definitions 19648 19649@noindent 19650This package provides definitions of the restrictions 19651identifiers supported by GNAT, and also the format of 19652the restrictions provided in package System.Restrictions. 19653It is not normally necessary to @code{with} this generic package 19654since the necessary instantiation is included in 19655package System.Restrictions. 19656 19657@node System.Strings.Stream_Ops (s-ststop.ads) 19658@section @code{System.Strings.Stream_Ops} (@file{s-ststop.ads}) 19659@cindex @code{System.Strings.Stream_Ops} (@file{s-ststop.ads}) 19660@cindex Stream operations 19661@cindex String stream operations 19662 19663@noindent 19664This package provides a set of stream subprograms for standard string types. 19665It is intended primarily to support implicit use of such subprograms when 19666stream attributes are applied to string types, but the subprograms in this 19667package can be used directly by application programs. 19668 19669@node System.Task_Info (s-tasinf.ads) 19670@section @code{System.Task_Info} (@file{s-tasinf.ads}) 19671@cindex @code{System.Task_Info} (@file{s-tasinf.ads}) 19672@cindex Task_Info pragma 19673 19674@noindent 19675This package provides target dependent functionality that is used 19676to support the @code{Task_Info} pragma 19677 19678@node System.Wch_Cnv (s-wchcnv.ads) 19679@section @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) 19680@cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) 19681@cindex Wide Character, Representation 19682@cindex Wide String, Conversion 19683@cindex Representation of wide characters 19684 19685@noindent 19686This package provides routines for converting between 19687wide and wide wide characters and a representation as a value of type 19688@code{Standard.String}, using a specified wide character 19689encoding method. It uses definitions in 19690package @code{System.Wch_Con}. 19691 19692@node System.Wch_Con (s-wchcon.ads) 19693@section @code{System.Wch_Con} (@file{s-wchcon.ads}) 19694@cindex @code{System.Wch_Con} (@file{s-wchcon.ads}) 19695 19696@noindent 19697This package provides definitions and descriptions of 19698the various methods used for encoding wide characters 19699in ordinary strings. These definitions are used by 19700the package @code{System.Wch_Cnv}. 19701 19702@node Interfacing to Other Languages 19703@chapter Interfacing to Other Languages 19704@noindent 19705The facilities in annex B of the Ada Reference Manual are fully 19706implemented in GNAT, and in addition, a full interface to C++ is 19707provided. 19708 19709@menu 19710* Interfacing to C:: 19711* Interfacing to C++:: 19712* Interfacing to COBOL:: 19713* Interfacing to Fortran:: 19714* Interfacing to non-GNAT Ada code:: 19715@end menu 19716 19717@node Interfacing to C 19718@section Interfacing to C 19719 19720@noindent 19721Interfacing to C with GNAT can use one of two approaches: 19722 19723@itemize @bullet 19724@item 19725The types in the package @code{Interfaces.C} may be used. 19726@item 19727Standard Ada types may be used directly. This may be less portable to 19728other compilers, but will work on all GNAT compilers, which guarantee 19729correspondence between the C and Ada types. 19730@end itemize 19731 19732@noindent 19733Pragma @code{Convention C} may be applied to Ada types, but mostly has no 19734effect, since this is the default. The following table shows the 19735correspondence between Ada scalar types and the corresponding C types. 19736 19737@table @code 19738@item Integer 19739@code{int} 19740@item Short_Integer 19741@code{short} 19742@item Short_Short_Integer 19743@code{signed char} 19744@item Long_Integer 19745@code{long} 19746@item Long_Long_Integer 19747@code{long long} 19748@item Short_Float 19749@code{float} 19750@item Float 19751@code{float} 19752@item Long_Float 19753@code{double} 19754@item Long_Long_Float 19755This is the longest floating-point type supported by the hardware. 19756@end table 19757 19758@noindent 19759Additionally, there are the following general correspondences between Ada 19760and C types: 19761@itemize @bullet 19762@item 19763Ada enumeration types map to C enumeration types directly if pragma 19764@code{Convention C} is specified, which causes them to have int 19765length. Without pragma @code{Convention C}, Ada enumeration types map to 197668, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short}, 19767@code{int}, respectively) depending on the number of values passed. 19768This is the only case in which pragma @code{Convention C} affects the 19769representation of an Ada type. 19770 19771@item 19772Ada access types map to C pointers, except for the case of pointers to 19773unconstrained types in Ada, which have no direct C equivalent. 19774 19775@item 19776Ada arrays map directly to C arrays. 19777 19778@item 19779Ada records map directly to C structures. 19780 19781@item 19782Packed Ada records map to C structures where all members are bit fields 19783of the length corresponding to the @code{@var{type}'Size} value in Ada. 19784@end itemize 19785 19786@node Interfacing to C++ 19787@section Interfacing to C++ 19788 19789@noindent 19790The interface to C++ makes use of the following pragmas, which are 19791primarily intended to be constructed automatically using a binding generator 19792tool, although it is possible to construct them by hand. 19793 19794Using these pragmas it is possible to achieve complete 19795inter-operability between Ada tagged types and C++ class definitions. 19796See @ref{Implementation Defined Pragmas}, for more details. 19797 19798@table @code 19799@item pragma CPP_Class ([Entity =>] @var{LOCAL_NAME}) 19800The argument denotes an entity in the current declarative region that is 19801declared as a tagged or untagged record type. It indicates that the type 19802corresponds to an externally declared C++ class type, and is to be laid 19803out the same way that C++ would lay out the type. 19804 19805Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 19806for backward compatibility but its functionality is available 19807using pragma @code{Import} with @code{Convention} = @code{CPP}. 19808 19809@item pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME}) 19810This pragma identifies an imported function (imported in the usual way 19811with pragma @code{Import}) as corresponding to a C++ constructor. 19812@end table 19813 19814A few restrictions are placed on the use of the @code{Access} attribute 19815in conjunction with subprograms subject to convention @code{CPP}: the 19816attribute may be used neither on primitive operations of a tagged 19817record type with convention @code{CPP}, imported or not, nor on 19818subprograms imported with pragma @code{CPP_Constructor}. 19819 19820In addition, C++ exceptions are propagated and can be handled in an 19821@code{others} choice of an exception handler. The corresponding Ada 19822occurrence has no message, and the simple name of the exception identity 19823contains @samp{Foreign_Exception}. Finalization and awaiting dependent 19824tasks works properly when such foreign exceptions are propagated. 19825 19826It is also possible to import a C++ exception using the following syntax: 19827 19828@smallexample @c ada 19829LOCAL_NAME : exception; 19830pragma Import (Cpp, 19831 [Entity =>] LOCAL_NAME, 19832 [External_Name =>] static_string_EXPRESSION); 19833@end smallexample 19834 19835@noindent 19836The @code{External_Name} is the name of the C++ RTTI symbol. You can then 19837cover a specific C++ exception in an exception handler. 19838 19839@node Interfacing to COBOL 19840@section Interfacing to COBOL 19841 19842@noindent 19843Interfacing to COBOL is achieved as described in section B.4 of 19844the Ada Reference Manual. 19845 19846@node Interfacing to Fortran 19847@section Interfacing to Fortran 19848 19849@noindent 19850Interfacing to Fortran is achieved as described in section B.5 of the 19851Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a 19852multi-dimensional array causes the array to be stored in column-major 19853order as required for convenient interface to Fortran. 19854 19855@node Interfacing to non-GNAT Ada code 19856@section Interfacing to non-GNAT Ada code 19857 19858It is possible to specify the convention @code{Ada} in a pragma 19859@code{Import} or pragma @code{Export}. However this refers to 19860the calling conventions used by GNAT, which may or may not be 19861similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 19862compiler to allow interoperation. 19863 19864If arguments types are kept simple, and if the foreign compiler generally 19865follows system calling conventions, then it may be possible to integrate 19866files compiled by other Ada compilers, provided that the elaboration 19867issues are adequately addressed (for example by eliminating the 19868need for any load time elaboration). 19869 19870In particular, GNAT running on VMS is designed to 19871be highly compatible with the DEC Ada 83 compiler, so this is one 19872case in which it is possible to import foreign units of this type, 19873provided that the data items passed are restricted to simple scalar 19874values or simple record types without variants, or simple array 19875types with fixed bounds. 19876 19877@node Specialized Needs Annexes 19878@chapter Specialized Needs Annexes 19879 19880@noindent 19881Ada 95 and Ada 2005 define a number of Specialized Needs Annexes, which are not 19882required in all implementations. However, as described in this chapter, 19883GNAT implements all of these annexes: 19884 19885@table @asis 19886@item Systems Programming (Annex C) 19887The Systems Programming Annex is fully implemented. 19888 19889@item Real-Time Systems (Annex D) 19890The Real-Time Systems Annex is fully implemented. 19891 19892@item Distributed Systems (Annex E) 19893Stub generation is fully implemented in the GNAT compiler. In addition, 19894a complete compatible PCS is available as part of the GLADE system, 19895a separate product. When the two 19896products are used in conjunction, this annex is fully implemented. 19897 19898@item Information Systems (Annex F) 19899The Information Systems annex is fully implemented. 19900 19901@item Numerics (Annex G) 19902The Numerics Annex is fully implemented. 19903 19904@item Safety and Security / High-Integrity Systems (Annex H) 19905The Safety and Security Annex (termed the High-Integrity Systems Annex 19906in Ada 2005) is fully implemented. 19907@end table 19908 19909@node Implementation of Specific Ada Features 19910@chapter Implementation of Specific Ada Features 19911 19912@noindent 19913This chapter describes the GNAT implementation of several Ada language 19914facilities. 19915 19916@menu 19917* Machine Code Insertions:: 19918* GNAT Implementation of Tasking:: 19919* GNAT Implementation of Shared Passive Packages:: 19920* Code Generation for Array Aggregates:: 19921* The Size of Discriminated Records with Default Discriminants:: 19922* Strict Conformance to the Ada Reference Manual:: 19923@end menu 19924 19925@node Machine Code Insertions 19926@section Machine Code Insertions 19927@cindex Machine Code insertions 19928 19929@noindent 19930Package @code{Machine_Code} provides machine code support as described 19931in the Ada Reference Manual in two separate forms: 19932@itemize @bullet 19933@item 19934Machine code statements, consisting of qualified expressions that 19935fit the requirements of RM section 13.8. 19936@item 19937An intrinsic callable procedure, providing an alternative mechanism of 19938including machine instructions in a subprogram. 19939@end itemize 19940 19941@noindent 19942The two features are similar, and both are closely related to the mechanism 19943provided by the asm instruction in the GNU C compiler. Full understanding 19944and use of the facilities in this package requires understanding the asm 19945instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression 19946Operands, gcc, Using the GNU Compiler Collection (GCC)}. 19947 19948Calls to the function @code{Asm} and the procedure @code{Asm} have identical 19949semantic restrictions and effects as described below. Both are provided so 19950that the procedure call can be used as a statement, and the function call 19951can be used to form a code_statement. 19952 19953The first example given in the GCC documentation is the C @code{asm} 19954instruction: 19955@smallexample 19956 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 19957@end smallexample 19958 19959@noindent 19960The equivalent can be written for GNAT as: 19961 19962@smallexample @c ada 19963Asm ("fsinx %1 %0", 19964 My_Float'Asm_Output ("=f", result), 19965 My_Float'Asm_Input ("f", angle)); 19966@end smallexample 19967 19968@noindent 19969The first argument to @code{Asm} is the assembler template, and is 19970identical to what is used in GNU C@. This string must be a static 19971expression. The second argument is the output operand list. It is 19972either a single @code{Asm_Output} attribute reference, or a list of such 19973references enclosed in parentheses (technically an array aggregate of 19974such references). 19975 19976The @code{Asm_Output} attribute denotes a function that takes two 19977parameters. The first is a string, the second is the name of a variable 19978of the type designated by the attribute prefix. The first (string) 19979argument is required to be a static expression and designates the 19980constraint for the parameter (e.g.@: what kind of register is 19981required). The second argument is the variable to be updated with the 19982result. The possible values for constraint are the same as those used in 19983the RTL, and are dependent on the configuration file used to build the 19984GCC back end. If there are no output operands, then this argument may 19985either be omitted, or explicitly given as @code{No_Output_Operands}. 19986 19987The second argument of @code{@var{my_float}'Asm_Output} functions as 19988though it were an @code{out} parameter, which is a little curious, but 19989all names have the form of expressions, so there is no syntactic 19990irregularity, even though normally functions would not be permitted 19991@code{out} parameters. The third argument is the list of input 19992operands. It is either a single @code{Asm_Input} attribute reference, or 19993a list of such references enclosed in parentheses (technically an array 19994aggregate of such references). 19995 19996The @code{Asm_Input} attribute denotes a function that takes two 19997parameters. The first is a string, the second is an expression of the 19998type designated by the prefix. The first (string) argument is required 19999to be a static expression, and is the constraint for the parameter, 20000(e.g.@: what kind of register is required). The second argument is the 20001value to be used as the input argument. The possible values for the 20002constant are the same as those used in the RTL, and are dependent on 20003the configuration file used to built the GCC back end. 20004 20005If there are no input operands, this argument may either be omitted, or 20006explicitly given as @code{No_Input_Operands}. The fourth argument, not 20007present in the above example, is a list of register names, called the 20008@dfn{clobber} argument. This argument, if given, must be a static string 20009expression, and is a space or comma separated list of names of registers 20010that must be considered destroyed as a result of the @code{Asm} call. If 20011this argument is the null string (the default value), then the code 20012generator assumes that no additional registers are destroyed. 20013 20014The fifth argument, not present in the above example, called the 20015@dfn{volatile} argument, is by default @code{False}. It can be set to 20016the literal value @code{True} to indicate to the code generator that all 20017optimizations with respect to the instruction specified should be 20018suppressed, and that in particular, for an instruction that has outputs, 20019the instruction will still be generated, even if none of the outputs are 20020used. @xref{Extended Asm,, Assembler Instructions with C Expression Operands, 20021gcc, Using the GNU Compiler Collection (GCC)}, for the full description. 20022Generally it is strongly advisable to use Volatile for any ASM statement 20023that is missing either input or output operands, or when two or more ASM 20024statements appear in sequence, to avoid unwanted optimizations. A warning 20025is generated if this advice is not followed. 20026 20027The @code{Asm} subprograms may be used in two ways. First the procedure 20028forms can be used anywhere a procedure call would be valid, and 20029correspond to what the RM calls ``intrinsic'' routines. Such calls can 20030be used to intersperse machine instructions with other Ada statements. 20031Second, the function forms, which return a dummy value of the limited 20032private type @code{Asm_Insn}, can be used in code statements, and indeed 20033this is the only context where such calls are allowed. Code statements 20034appear as aggregates of the form: 20035 20036@smallexample @c ada 20037Asm_Insn'(Asm (@dots{})); 20038Asm_Insn'(Asm_Volatile (@dots{})); 20039@end smallexample 20040 20041@noindent 20042In accordance with RM rules, such code statements are allowed only 20043within subprograms whose entire body consists of such statements. It is 20044not permissible to intermix such statements with other Ada statements. 20045 20046Typically the form using intrinsic procedure calls is more convenient 20047and more flexible. The code statement form is provided to meet the RM 20048suggestion that such a facility should be made available. The following 20049is the exact syntax of the call to @code{Asm}. As usual, if named notation 20050is used, the arguments may be given in arbitrary order, following the 20051normal rules for use of positional and named arguments) 20052 20053@smallexample 20054ASM_CALL ::= Asm ( 20055 [Template =>] static_string_EXPRESSION 20056 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 20057 [,[Inputs =>] INPUT_OPERAND_LIST ] 20058 [,[Clobber =>] static_string_EXPRESSION ] 20059 [,[Volatile =>] static_boolean_EXPRESSION] ) 20060 20061OUTPUT_OPERAND_LIST ::= 20062 [PREFIX.]No_Output_Operands 20063| OUTPUT_OPERAND_ATTRIBUTE 20064| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 20065 20066OUTPUT_OPERAND_ATTRIBUTE ::= 20067 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 20068 20069INPUT_OPERAND_LIST ::= 20070 [PREFIX.]No_Input_Operands 20071| INPUT_OPERAND_ATTRIBUTE 20072| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 20073 20074INPUT_OPERAND_ATTRIBUTE ::= 20075 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 20076@end smallexample 20077 20078@noindent 20079The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} 20080are declared in the package @code{Machine_Code} and must be referenced 20081according to normal visibility rules. In particular if there is no 20082@code{use} clause for this package, then appropriate package name 20083qualification is required. 20084 20085@node GNAT Implementation of Tasking 20086@section GNAT Implementation of Tasking 20087 20088@noindent 20089This chapter outlines the basic GNAT approach to tasking (in particular, 20090a multi-layered library for portability) and discusses issues related 20091to compliance with the Real-Time Systems Annex. 20092 20093@menu 20094* Mapping Ada Tasks onto the Underlying Kernel Threads:: 20095* Ensuring Compliance with the Real-Time Annex:: 20096@end menu 20097 20098@node Mapping Ada Tasks onto the Underlying Kernel Threads 20099@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 20100 20101@noindent 20102GNAT's run-time support comprises two layers: 20103 20104@itemize @bullet 20105@item GNARL (GNAT Run-time Layer) 20106@item GNULL (GNAT Low-level Library) 20107@end itemize 20108 20109@noindent 20110In GNAT, Ada's tasking services rely on a platform and OS independent 20111layer known as GNARL@. This code is responsible for implementing the 20112correct semantics of Ada's task creation, rendezvous, protected 20113operations etc. 20114 20115GNARL decomposes Ada's tasking semantics into simpler lower level 20116operations such as create a thread, set the priority of a thread, 20117yield, create a lock, lock/unlock, etc. The spec for these low-level 20118operations constitutes GNULLI, the GNULL Interface. This interface is 20119directly inspired from the POSIX real-time API@. 20120 20121If the underlying executive or OS implements the POSIX standard 20122faithfully, the GNULL Interface maps as is to the services offered by 20123the underlying kernel. Otherwise, some target dependent glue code maps 20124the services offered by the underlying kernel to the semantics expected 20125by GNARL@. 20126 20127Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the 20128key point is that each Ada task is mapped on a thread in the underlying 20129kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 20130 20131In addition Ada task priorities map onto the underlying thread priorities. 20132Mapping Ada tasks onto the underlying kernel threads has several advantages: 20133 20134@itemize @bullet 20135@item 20136The underlying scheduler is used to schedule the Ada tasks. This 20137makes Ada tasks as efficient as kernel threads from a scheduling 20138standpoint. 20139 20140@item 20141Interaction with code written in C containing threads is eased 20142since at the lowest level Ada tasks and C threads map onto the same 20143underlying kernel concept. 20144 20145@item 20146When an Ada task is blocked during I/O the remaining Ada tasks are 20147able to proceed. 20148 20149@item 20150On multiprocessor systems Ada tasks can execute in parallel. 20151@end itemize 20152 20153@noindent 20154Some threads libraries offer a mechanism to fork a new process, with the 20155child process duplicating the threads from the parent. 20156GNAT does not 20157support this functionality when the parent contains more than one task. 20158@cindex Forking a new process 20159 20160@node Ensuring Compliance with the Real-Time Annex 20161@subsection Ensuring Compliance with the Real-Time Annex 20162@cindex Real-Time Systems Annex compliance 20163 20164@noindent 20165Although mapping Ada tasks onto 20166the underlying threads has significant advantages, it does create some 20167complications when it comes to respecting the scheduling semantics 20168specified in the real-time annex (Annex D). 20169 20170For instance the Annex D requirement for the @code{FIFO_Within_Priorities} 20171scheduling policy states: 20172 20173@quotation 20174@emph{When the active priority of a ready task that is not running 20175changes, or the setting of its base priority takes effect, the 20176task is removed from the ready queue for its old active priority 20177and is added at the tail of the ready queue for its new active 20178priority, except in the case where the active priority is lowered 20179due to the loss of inherited priority, in which case the task is 20180added at the head of the ready queue for its new active priority.} 20181@end quotation 20182 20183@noindent 20184While most kernels do put tasks at the end of the priority queue when 20185a task changes its priority, (which respects the main 20186FIFO_Within_Priorities requirement), almost none keep a thread at the 20187beginning of its priority queue when its priority drops from the loss 20188of inherited priority. 20189 20190As a result most vendors have provided incomplete Annex D implementations. 20191 20192The GNAT run-time, has a nice cooperative solution to this problem 20193which ensures that accurate FIFO_Within_Priorities semantics are 20194respected. 20195 20196The principle is as follows. When an Ada task T is about to start 20197running, it checks whether some other Ada task R with the same 20198priority as T has been suspended due to the loss of priority 20199inheritance. If this is the case, T yields and is placed at the end of 20200its priority queue. When R arrives at the front of the queue it 20201executes. 20202 20203Note that this simple scheme preserves the relative order of the tasks 20204that were ready to execute in the priority queue where R has been 20205placed at the end. 20206 20207@node GNAT Implementation of Shared Passive Packages 20208@section GNAT Implementation of Shared Passive Packages 20209@cindex Shared passive packages 20210 20211@noindent 20212GNAT fully implements the pragma @code{Shared_Passive} for 20213@cindex pragma @code{Shared_Passive} 20214the purpose of designating shared passive packages. 20215This allows the use of passive partitions in the 20216context described in the Ada Reference Manual; i.e., for communication 20217between separate partitions of a distributed application using the 20218features in Annex E. 20219@cindex Annex E 20220@cindex Distribution Systems Annex 20221 20222However, the implementation approach used by GNAT provides for more 20223extensive usage as follows: 20224 20225@table @emph 20226@item Communication between separate programs 20227 20228This allows separate programs to access the data in passive 20229partitions, using protected objects for synchronization where 20230needed. The only requirement is that the two programs have a 20231common shared file system. It is even possible for programs 20232running on different machines with different architectures 20233(e.g.@: different endianness) to communicate via the data in 20234a passive partition. 20235 20236@item Persistence between program runs 20237 20238The data in a passive package can persist from one run of a 20239program to another, so that a later program sees the final 20240values stored by a previous run of the same program. 20241 20242@end table 20243 20244@noindent 20245The implementation approach used is to store the data in files. A 20246separate stream file is created for each object in the package, and 20247an access to an object causes the corresponding file to be read or 20248written. 20249 20250The environment variable @code{SHARED_MEMORY_DIRECTORY} should be 20251@cindex @code{SHARED_MEMORY_DIRECTORY} environment variable 20252set to the directory to be used for these files. 20253The files in this directory 20254have names that correspond to their fully qualified names. For 20255example, if we have the package 20256 20257@smallexample @c ada 20258package X is 20259 pragma Shared_Passive (X); 20260 Y : Integer; 20261 Z : Float; 20262end X; 20263@end smallexample 20264 20265@noindent 20266and the environment variable is set to @code{/stemp/}, then the files created 20267will have the names: 20268 20269@smallexample 20270/stemp/x.y 20271/stemp/x.z 20272@end smallexample 20273 20274@noindent 20275These files are created when a value is initially written to the object, and 20276the files are retained until manually deleted. This provides the persistence 20277semantics. If no file exists, it means that no partition has assigned a value 20278to the variable; in this case the initial value declared in the package 20279will be used. This model ensures that there are no issues in synchronizing 20280the elaboration process, since elaboration of passive packages elaborates the 20281initial values, but does not create the files. 20282 20283The files are written using normal @code{Stream_IO} access. 20284If you want to be able 20285to communicate between programs or partitions running on different 20286architectures, then you should use the XDR versions of the stream attribute 20287routines, since these are architecture independent. 20288 20289If active synchronization is required for access to the variables in the 20290shared passive package, then as described in the Ada Reference Manual, the 20291package may contain protected objects used for this purpose. In this case 20292a lock file (whose name is @file{___lock} (three underscores) 20293is created in the shared memory directory. 20294@cindex @file{___lock} file (for shared passive packages) 20295This is used to provide the required locking 20296semantics for proper protected object synchronization. 20297 20298As of January 2003, GNAT supports shared passive packages on all platforms 20299except for OpenVMS. 20300 20301@node Code Generation for Array Aggregates 20302@section Code Generation for Array Aggregates 20303 20304@menu 20305* Static constant aggregates with static bounds:: 20306* Constant aggregates with unconstrained nominal types:: 20307* Aggregates with static bounds:: 20308* Aggregates with non-static bounds:: 20309* Aggregates in assignment statements:: 20310@end menu 20311 20312@noindent 20313Aggregates have a rich syntax and allow the user to specify the values of 20314complex data structures by means of a single construct. As a result, the 20315code generated for aggregates can be quite complex and involve loops, case 20316statements and multiple assignments. In the simplest cases, however, the 20317compiler will recognize aggregates whose components and constraints are 20318fully static, and in those cases the compiler will generate little or no 20319executable code. The following is an outline of the code that GNAT generates 20320for various aggregate constructs. For further details, you will find it 20321useful to examine the output produced by the -gnatG flag to see the expanded 20322source that is input to the code generator. You may also want to examine 20323the assembly code generated at various levels of optimization. 20324 20325The code generated for aggregates depends on the context, the component values, 20326and the type. In the context of an object declaration the code generated is 20327generally simpler than in the case of an assignment. As a general rule, static 20328component values and static subtypes also lead to simpler code. 20329 20330@node Static constant aggregates with static bounds 20331@subsection Static constant aggregates with static bounds 20332 20333@noindent 20334For the declarations: 20335@smallexample @c ada 20336 type One_Dim is array (1..10) of integer; 20337 ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 20338@end smallexample 20339 20340@noindent 20341GNAT generates no executable code: the constant ar0 is placed in static memory. 20342The same is true for constant aggregates with named associations: 20343 20344@smallexample @c ada 20345 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); 20346 Cr3 : constant One_Dim := (others => 7777); 20347@end smallexample 20348 20349@noindent 20350The same is true for multidimensional constant arrays such as: 20351 20352@smallexample @c ada 20353 type two_dim is array (1..3, 1..3) of integer; 20354 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 20355@end smallexample 20356 20357@noindent 20358The same is true for arrays of one-dimensional arrays: the following are 20359static: 20360 20361@smallexample @c ada 20362type ar1b is array (1..3) of boolean; 20363type ar_ar is array (1..3) of ar1b; 20364None : constant ar1b := (others => false); -- fully static 20365None2 : constant ar_ar := (1..3 => None); -- fully static 20366@end smallexample 20367 20368@noindent 20369However, for multidimensional aggregates with named associations, GNAT will 20370generate assignments and loops, even if all associations are static. The 20371following two declarations generate a loop for the first dimension, and 20372individual component assignments for the second dimension: 20373 20374@smallexample @c ada 20375Zero1: constant two_dim := (1..3 => (1..3 => 0)); 20376Zero2: constant two_dim := (others => (others => 0)); 20377@end smallexample 20378 20379@node Constant aggregates with unconstrained nominal types 20380@subsection Constant aggregates with unconstrained nominal types 20381 20382@noindent 20383In such cases the aggregate itself establishes the subtype, so that 20384associations with @code{others} cannot be used. GNAT determines the 20385bounds for the actual subtype of the aggregate, and allocates the 20386aggregate statically as well. No code is generated for the following: 20387 20388@smallexample @c ada 20389 type One_Unc is array (natural range <>) of integer; 20390 Cr_Unc : constant One_Unc := (12,24,36); 20391@end smallexample 20392 20393@node Aggregates with static bounds 20394@subsection Aggregates with static bounds 20395 20396@noindent 20397In all previous examples the aggregate was the initial (and immutable) value 20398of a constant. If the aggregate initializes a variable, then code is generated 20399for it as a combination of individual assignments and loops over the target 20400object. The declarations 20401 20402@smallexample @c ada 20403 Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); 20404 Cr_Var2 : One_Dim := (others > -1); 20405@end smallexample 20406 20407@noindent 20408generate the equivalent of 20409 20410@smallexample @c ada 20411 Cr_Var1 (1) := 2; 20412 Cr_Var1 (2) := 3; 20413 Cr_Var1 (3) := 5; 20414 Cr_Var1 (4) := 11; 20415 20416 for I in Cr_Var2'range loop 20417 Cr_Var2 (I) := -1; 20418 end loop; 20419@end smallexample 20420 20421@node Aggregates with non-static bounds 20422@subsection Aggregates with non-static bounds 20423 20424@noindent 20425If the bounds of the aggregate are not statically compatible with the bounds 20426of the nominal subtype of the target, then constraint checks have to be 20427generated on the bounds. For a multidimensional array, constraint checks may 20428have to be applied to sub-arrays individually, if they do not have statically 20429compatible subtypes. 20430 20431@node Aggregates in assignment statements 20432@subsection Aggregates in assignment statements 20433 20434@noindent 20435In general, aggregate assignment requires the construction of a temporary, 20436and a copy from the temporary to the target of the assignment. This is because 20437it is not always possible to convert the assignment into a series of individual 20438component assignments. For example, consider the simple case: 20439 20440@smallexample @c ada 20441 A := (A(2), A(1)); 20442@end smallexample 20443 20444@noindent 20445This cannot be converted into: 20446 20447@smallexample @c ada 20448 A(1) := A(2); 20449 A(2) := A(1); 20450@end smallexample 20451 20452@noindent 20453So the aggregate has to be built first in a separate location, and then 20454copied into the target. GNAT recognizes simple cases where this intermediate 20455step is not required, and the assignments can be performed in place, directly 20456into the target. The following sufficient criteria are applied: 20457 20458@itemize @bullet 20459@item 20460The bounds of the aggregate are static, and the associations are static. 20461@item 20462The components of the aggregate are static constants, names of 20463simple variables that are not renamings, or expressions not involving 20464indexed components whose operands obey these rules. 20465@end itemize 20466 20467@noindent 20468If any of these conditions are violated, the aggregate will be built in 20469a temporary (created either by the front-end or the code generator) and then 20470that temporary will be copied onto the target. 20471 20472@node The Size of Discriminated Records with Default Discriminants 20473@section The Size of Discriminated Records with Default Discriminants 20474 20475@noindent 20476If a discriminated type @code{T} has discriminants with default values, it is 20477possible to declare an object of this type without providing an explicit 20478constraint: 20479 20480@smallexample @c ada 20481@group 20482type Size is range 1..100; 20483 20484type Rec (D : Size := 15) is record 20485 Name : String (1..D); 20486end T; 20487 20488Word : Rec; 20489@end group 20490@end smallexample 20491 20492@noindent 20493Such an object is said to be @emph{unconstrained}. 20494The discriminant of the object 20495can be modified by a full assignment to the object, as long as it preserves the 20496relation between the value of the discriminant, and the value of the components 20497that depend on it: 20498 20499@smallexample @c ada 20500@group 20501Word := (3, "yes"); 20502 20503Word := (5, "maybe"); 20504 20505Word := (5, "no"); -- raises Constraint_Error 20506@end group 20507@end smallexample 20508 20509@noindent 20510In order to support this behavior efficiently, an unconstrained object is 20511given the maximum size that any value of the type requires. In the case 20512above, @code{Word} has storage for the discriminant and for 20513a @code{String} of length 100. 20514It is important to note that unconstrained objects do not require dynamic 20515allocation. It would be an improper implementation to place on the heap those 20516components whose size depends on discriminants. (This improper implementation 20517was used by some Ada83 compilers, where the @code{Name} component above 20518would have 20519been stored as a pointer to a dynamic string). Following the principle that 20520dynamic storage management should never be introduced implicitly, 20521an Ada compiler should reserve the full size for an unconstrained declared 20522object, and place it on the stack. 20523 20524This maximum size approach 20525has been a source of surprise to some users, who expect the default 20526values of the discriminants to determine the size reserved for an 20527unconstrained object: ``If the default is 15, why should the object occupy 20528a larger size?'' 20529The answer, of course, is that the discriminant may be later modified, 20530and its full range of values must be taken into account. This is why the 20531declaration: 20532 20533@smallexample 20534@group 20535type Rec (D : Positive := 15) is record 20536 Name : String (1..D); 20537end record; 20538 20539Too_Large : Rec; 20540@end group 20541@end smallexample 20542 20543@noindent 20544is flagged by the compiler with a warning: 20545an attempt to create @code{Too_Large} will raise @code{Storage_Error}, 20546because the required size includes @code{Positive'Last} 20547bytes. As the first example indicates, the proper approach is to declare an 20548index type of ``reasonable'' range so that unconstrained objects are not too 20549large. 20550 20551One final wrinkle: if the object is declared to be @code{aliased}, or if it is 20552created in the heap by means of an allocator, then it is @emph{not} 20553unconstrained: 20554it is constrained by the default values of the discriminants, and those values 20555cannot be modified by full assignment. This is because in the presence of 20556aliasing all views of the object (which may be manipulated by different tasks, 20557say) must be consistent, so it is imperative that the object, once created, 20558remain invariant. 20559 20560@node Strict Conformance to the Ada Reference Manual 20561@section Strict Conformance to the Ada Reference Manual 20562 20563@noindent 20564The dynamic semantics defined by the Ada Reference Manual impose a set of 20565run-time checks to be generated. By default, the GNAT compiler will insert many 20566run-time checks into the compiled code, including most of those required by the 20567Ada Reference Manual. However, there are three checks that are not enabled 20568in the default mode for efficiency reasons: arithmetic overflow checking for 20569integer operations (including division by zero), checks for access before 20570elaboration on subprogram calls, and stack overflow checking (most operating 20571systems do not perform this check by default). 20572 20573Strict conformance to the Ada Reference Manual can be achieved by adding 20574three compiler options for overflow checking for integer operations 20575(@option{-gnato}), dynamic checks for access-before-elaboration on subprogram 20576calls and generic instantiations (@option{-gnatE}), and stack overflow 20577checking (@option{-fstack-check}). 20578 20579Note that the result of a floating point arithmetic operation in overflow and 20580invalid situations, when the @code{Machine_Overflows} attribute of the result 20581type is @code{False}, is to generate IEEE NaN and infinite values. This is the 20582case for machines compliant with the IEEE floating-point standard, but on 20583machines that are not fully compliant with this standard, such as Alpha, the 20584@option{-mieee} compiler flag must be used for achieving IEEE confirming 20585behavior (although at the cost of a significant performance penalty), so 20586infinite and NaN values are properly generated. 20587 20588 20589@node Implementation of Ada 2012 Features 20590@chapter Implementation of Ada 2012 Features 20591@cindex Ada 2012 implementation status 20592 20593This chapter contains a complete list of Ada 2012 features that have been 20594implemented as of GNAT version 6.4. Generally, these features are only 20595available if the @option{-gnat12} (Ada 2012 features enabled) flag is set 20596@cindex @option{-gnat12} option 20597or if the configuration pragma @code{Ada_2012} is used. 20598@cindex pragma @code{Ada_2012} 20599@cindex configuration pragma @code{Ada_2012} 20600@cindex @code{Ada_2012} configuration pragma 20601However, new pragmas, attributes, and restrictions are 20602unconditionally available, since the Ada 95 standard allows the addition of 20603new pragmas, attributes, and restrictions (there are exceptions, which are 20604documented in the individual descriptions), and also certain packages 20605were made available in earlier versions of Ada. 20606 20607An ISO date (YYYY-MM-DD) appears in parentheses on the description line. 20608This date shows the implementation date of the feature. Any wavefront 20609subsequent to this date will contain the indicated feature, as will any 20610subsequent releases. A date of 0000-00-00 means that GNAT has always 20611implemented the feature, or implemented it as soon as it appeared as a 20612binding interpretation. 20613 20614Each feature corresponds to an Ada Issue (``AI'') approved by the Ada 20615standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. 20616The features are ordered based on the relevant sections of the Ada 20617Reference Manual (``RM''). When a given AI relates to multiple points 20618in the RM, the earliest is used. 20619 20620A complete description of the AIs may be found in 20621@url{www.ada-auth.org/ai05-summary.html}. 20622 20623@itemize @bullet 20624 20625@item 20626@emph{AI-0176 Quantified expressions (2010-09-29)} 20627@cindex AI-0176 (Ada 2012 feature) 20628 20629@noindent 20630 Both universally and existentially quantified expressions are implemented. 20631 They use the new syntax for iterators proposed in AI05-139-2, as well as 20632 the standard Ada loop syntax. 20633 20634@noindent 20635 RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) 20636 20637@item 20638@emph{AI-0079 Allow @i{other_format} characters in source (2010-07-10)} 20639@cindex AI-0079 (Ada 2012 feature) 20640 20641@noindent 20642 Wide characters in the unicode category @i{other_format} are now allowed in 20643 source programs between tokens, but not within a token such as an identifier. 20644 20645@noindent 20646 RM References: 2.01 (4/2) 2.02 (7) 20647 20648@item 20649@emph{AI-0091 Do not allow @i{other_format} in identifiers (0000-00-00)} 20650@cindex AI-0091 (Ada 2012 feature) 20651 20652@noindent 20653 Wide characters in the unicode category @i{other_format} are not permitted 20654 within an identifier, since this can be a security problem. The error 20655 message for this case has been improved to be more specific, but GNAT has 20656 never allowed such characters to appear in identifiers. 20657 20658@noindent 20659 RM 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) 20660 20661@item 20662@emph{AI-0100 Placement of pragmas (2010-07-01)} 20663@cindex AI-0100 (Ada 2012 feature) 20664 20665@noindent 20666 This AI is an earlier version of AI-163. It simplifies the rules 20667 for legal placement of pragmas. In the case of lists that allow pragmas, if 20668 the list may have no elements, then the list may consist solely of pragmas. 20669 20670@noindent 20671 RM References: 2.08 (7) 20672 20673@item 20674@emph{AI-0163 Pragmas in place of null (2010-07-01)} 20675@cindex AI-0163 (Ada 2012 feature) 20676 20677@noindent 20678 A statement sequence may be composed entirely of pragmas. It is no longer 20679 necessary to add a dummy @code{null} statement to make the sequence legal. 20680 20681@noindent 20682 RM References: 2.08 (7) 2.08 (16) 20683 20684 20685@item 20686@emph{AI-0080 ``View of'' not needed if clear from context (0000-00-00)} 20687@cindex AI-0080 (Ada 2012 feature) 20688 20689@noindent 20690 This is an editorial change only, described as non-testable in the AI. 20691 20692@noindent 20693 RM References: 3.01 (7) 20694 20695 20696@item 20697@emph{AI-0183 Aspect specifications (2010-08-16)} 20698@cindex AI-0183 (Ada 2012 feature) 20699 20700@noindent 20701 Aspect specifications have been fully implemented except for pre and post- 20702 conditions, and type invariants, which have their own separate AI's. All 20703 forms of declarations listed in the AI are supported. The following is a 20704 list of the aspects supported (with GNAT implementation aspects marked) 20705 20706@multitable {@code{Preelaborable_Initialization}} {--GNAT} 20707@item @code{Ada_2005} @tab -- GNAT 20708@item @code{Ada_2012} @tab -- GNAT 20709@item @code{Address} @tab 20710@item @code{Alignment} @tab 20711@item @code{Atomic} @tab 20712@item @code{Atomic_Components} @tab 20713@item @code{Bit_Order} @tab 20714@item @code{Component_Size} @tab 20715@item @code{Contract_Cases} @tab -- GNAT 20716@item @code{Discard_Names} @tab 20717@item @code{External_Tag} @tab 20718@item @code{Favor_Top_Level} @tab -- GNAT 20719@item @code{Inline} @tab 20720@item @code{Inline_Always} @tab -- GNAT 20721@item @code{Invariant} @tab -- GNAT 20722@item @code{Machine_Radix} @tab 20723@item @code{No_Return} @tab 20724@item @code{Object_Size} @tab -- GNAT 20725@item @code{Pack} @tab 20726@item @code{Persistent_BSS} @tab -- GNAT 20727@item @code{Post} @tab 20728@item @code{Pre} @tab 20729@item @code{Predicate} @tab 20730@item @code{Preelaborable_Initialization} @tab 20731@item @code{Pure_Function} @tab -- GNAT 20732@item @code{Remote_Access_Type} @tab -- GNAT 20733@item @code{Shared} @tab -- GNAT 20734@item @code{Size} @tab 20735@item @code{Storage_Pool} @tab 20736@item @code{Storage_Size} @tab 20737@item @code{Stream_Size} @tab 20738@item @code{Suppress} @tab 20739@item @code{Suppress_Debug_Info} @tab -- GNAT 20740@item @code{Test_Case} @tab -- GNAT 20741@item @code{Type_Invariant} @tab 20742@item @code{Unchecked_Union} @tab 20743@item @code{Universal_Aliasing} @tab -- GNAT 20744@item @code{Unmodified} @tab -- GNAT 20745@item @code{Unreferenced} @tab -- GNAT 20746@item @code{Unreferenced_Objects} @tab -- GNAT 20747@item @code{Unsuppress} @tab 20748@item @code{Value_Size} @tab -- GNAT 20749@item @code{Volatile} @tab 20750@item @code{Volatile_Components} 20751@item @code{Warnings} @tab -- GNAT 20752@end multitable 20753 20754@noindent 20755 Note that for aspects with an expression, e.g. @code{Size}, the expression is 20756 treated like a default expression (visibility is analyzed at the point of 20757 occurrence of the aspect, but evaluation of the expression occurs at the 20758 freeze point of the entity involved). 20759 20760@noindent 20761 RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) 20762 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 20763 (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) 20764 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) 20765 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) 20766 13.03.01 (0) 20767 20768 20769@item 20770@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} 20771@cindex AI-0128 (Ada 2012 feature) 20772 20773@noindent 20774 If an equality operator ("=") is declared for a type, then the implicitly 20775 declared inequality operator ("/=") is a primitive operation of the type. 20776 This is the only reasonable interpretation, and is the one always implemented 20777 by GNAT, but the RM was not entirely clear in making this point. 20778 20779@noindent 20780 RM References: 3.02.03 (6) 6.06 (6) 20781 20782@item 20783@emph{AI-0003 Qualified expressions as names (2010-07-11)} 20784@cindex AI-0003 (Ada 2012 feature) 20785 20786@noindent 20787 In Ada 2012, a qualified expression is considered to be syntactically a name, 20788 meaning that constructs such as @code{A'(F(X)).B} are now legal. This is 20789 useful in disambiguating some cases of overloading. 20790 20791@noindent 20792 RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) 20793 5.04 (7) 20794 20795@item 20796@emph{AI-0120 Constant instance of protected object (0000-00-00)} 20797@cindex AI-0120 (Ada 2012 feature) 20798 20799@noindent 20800 This is an RM editorial change only. The section that lists objects that are 20801 constant failed to include the current instance of a protected object 20802 within a protected function. This has always been treated as a constant 20803 in GNAT. 20804 20805@noindent 20806 RM References: 3.03 (21) 20807 20808@item 20809@emph{AI-0008 General access to constrained objects (0000-00-00)} 20810@cindex AI-0008 (Ada 2012 feature) 20811 20812@noindent 20813 The wording in the RM implied that if you have a general access to a 20814 constrained object, it could be used to modify the discriminants. This was 20815 obviously not intended. @code{Constraint_Error} should be raised, and GNAT 20816 has always done so in this situation. 20817 20818@noindent 20819 RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) 20820 20821 20822@item 20823@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} 20824@cindex AI-0093 (Ada 2012 feature) 20825 20826@noindent 20827 This is an editorial change only, to make more widespread use of the Ada 2012 20828 ``immutably limited''. 20829 20830@noindent 20831 RM References: 3.03 (23.4/3) 20832 20833 20834 20835@item 20836@emph{AI-0096 Deriving from formal private types (2010-07-20)} 20837@cindex AI-0096 (Ada 2012 feature) 20838 20839@noindent 20840 In general it is illegal for a type derived from a formal limited type to be 20841 nonlimited. This AI makes an exception to this rule: derivation is legal 20842 if it appears in the private part of the generic, and the formal type is not 20843 tagged. If the type is tagged, the legality check must be applied to the 20844 private part of the package. 20845 20846@noindent 20847 RM References: 3.04 (5.1/2) 6.02 (7) 20848 20849 20850@item 20851@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} 20852@cindex AI-0181 (Ada 2012 feature) 20853 20854@noindent 20855 From Ada 2005 on, soft hyphen is considered a non-graphic character, which 20856 means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the 20857 @code{Image} and @code{Value} attributes for the character types. Strictly 20858 speaking this is an inconsistency with Ada 95, but in practice the use of 20859 these attributes is so obscure that it will not cause problems. 20860 20861@noindent 20862 RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) 20863 20864 20865@item 20866@emph{AI-0182 Additional forms for @code{Character'Value} (0000-00-00)} 20867@cindex AI-0182 (Ada 2012 feature) 20868 20869@noindent 20870 This AI allows @code{Character'Value} to accept the string @code{'?'} where 20871 @code{?} is any character including non-graphic control characters. GNAT has 20872 always accepted such strings. It also allows strings such as 20873 @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this 20874 permission and raises @code{Constraint_Error}, as is certainly still 20875 permitted. 20876 20877@noindent 20878 RM References: 3.05 (56/2) 20879 20880 20881@item 20882@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} 20883@cindex AI-0214 (Ada 2012 feature) 20884 20885@noindent 20886 Ada 2012 relaxes the restriction that forbids discriminants of tagged types 20887 to have default expressions by allowing them when the type is limited. It 20888 is often useful to define a default value for a discriminant even though 20889 it can't be changed by assignment. 20890 20891@noindent 20892 RM References: 3.07 (9.1/2) 3.07.02 (3) 20893 20894 20895@item 20896@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} 20897@cindex AI-0102 (Ada 2012 feature) 20898 20899@noindent 20900 It is illegal to assign an anonymous access constant to an anonymous access 20901 variable. The RM did not have a clear rule to prevent this, but GNAT has 20902 always generated an error for this usage. 20903 20904@noindent 20905 RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) 20906 20907 20908@item 20909@emph{AI-0158 Generalizing membership tests (2010-09-16)} 20910@cindex AI-0158 (Ada 2012 feature) 20911 20912@noindent 20913 This AI extends the syntax of membership tests to simplify complex conditions 20914 that can be expressed as membership in a subset of values of any type. It 20915 introduces syntax for a list of expressions that may be used in loop contexts 20916 as well. 20917 20918@noindent 20919 RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) 20920 20921 20922@item 20923@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} 20924@cindex AI-0173 (Ada 2012 feature) 20925 20926@noindent 20927 The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked 20928 with the tag of an abstract type, and @code{False} otherwise. 20929 20930@noindent 20931 RM References: 3.09 (7.4/2) 3.09 (12.4/2) 20932 20933 20934 20935@item 20936@emph{AI-0076 function with controlling result (0000-00-00)} 20937@cindex AI-0076 (Ada 2012 feature) 20938 20939@noindent 20940 This is an editorial change only. The RM defines calls with controlling 20941 results, but uses the term ``function with controlling result'' without an 20942 explicit definition. 20943 20944@noindent 20945 RM References: 3.09.02 (2/2) 20946 20947 20948@item 20949@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} 20950@cindex AI-0126 (Ada 2012 feature) 20951 20952@noindent 20953 This AI clarifies dispatching rules, and simply confirms that dispatching 20954 executes the operation of the parent type when there is no explicitly or 20955 implicitly declared operation for the descendant type. This has always been 20956 the case in all versions of GNAT. 20957 20958@noindent 20959 RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) 20960 20961 20962@item 20963@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} 20964@cindex AI-0097 (Ada 2012 feature) 20965 20966@noindent 20967 The RM as written implied that in some cases it was possible to create an 20968 object of an abstract type, by having an abstract extension inherit a non- 20969 abstract constructor from its parent type. This mistake has been corrected 20970 in GNAT and in the RM, and this construct is now illegal. 20971 20972@noindent 20973 RM References: 3.09.03 (4/2) 20974 20975 20976@item 20977@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} 20978@cindex AI-0203 (Ada 2012 feature) 20979 20980@noindent 20981 A return_subtype_indication cannot denote an abstract subtype. GNAT has never 20982 permitted such usage. 20983 20984@noindent 20985 RM References: 3.09.03 (8/3) 20986 20987 20988@item 20989@emph{AI-0198 Inheriting abstract operators (0000-00-00)} 20990@cindex AI-0198 (Ada 2012 feature) 20991 20992@noindent 20993 This AI resolves a conflict between two rules involving inherited abstract 20994 operations and predefined operators. If a derived numeric type inherits 20995 an abstract operator, it overrides the predefined one. This interpretation 20996 was always the one implemented in GNAT. 20997 20998@noindent 20999 RM References: 3.09.03 (4/3) 21000 21001@item 21002@emph{AI-0073 Functions returning abstract types (2010-07-10)} 21003@cindex AI-0073 (Ada 2012 feature) 21004 21005@noindent 21006 This AI covers a number of issues regarding returning abstract types. In 21007 particular generic functions cannot have abstract result types or access 21008 result types designated an abstract type. There are some other cases which 21009 are detailed in the AI. Note that this binding interpretation has not been 21010 retrofitted to operate before Ada 2012 mode, since it caused a significant 21011 number of regressions. 21012 21013@noindent 21014 RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) 21015 21016 21017@item 21018@emph{AI-0070 Elaboration of interface types (0000-00-00)} 21019@cindex AI-0070 (Ada 2012 feature) 21020 21021@noindent 21022 This is an editorial change only, there are no testable consequences short of 21023 checking for the absence of generated code for an interface declaration. 21024 21025@noindent 21026 RM References: 3.09.04 (18/2) 21027 21028 21029@item 21030@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} 21031@cindex AI-0208 (Ada 2012 feature) 21032 21033@noindent 21034 The wording in the Ada 2005 RM concerning characteristics of incomplete views 21035 was incorrect and implied that some programs intended to be legal were now 21036 illegal. GNAT had never considered such programs illegal, so it has always 21037 implemented the intent of this AI. 21038 21039@noindent 21040 RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) 21041 21042 21043@item 21044@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} 21045@cindex AI-0162 (Ada 2012 feature) 21046 21047@noindent 21048 Incomplete types are made more useful by allowing them to be completed by 21049 private types and private extensions. 21050 21051@noindent 21052 RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) 21053 21054 21055 21056@item 21057@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} 21058@cindex AI-0098 (Ada 2012 feature) 21059 21060@noindent 21061 An unintentional omission in the RM implied some inconsistent restrictions on 21062 the use of anonymous access to subprogram values. These restrictions were not 21063 intentional, and have never been enforced by GNAT. 21064 21065@noindent 21066 RM References: 3.10.01 (6) 3.10.01 (9.2/2) 21067 21068 21069@item 21070@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} 21071@cindex AI-0199 (Ada 2012 feature) 21072 21073@noindent 21074 A choice list in a record aggregate can include several components of 21075 (distinct) anonymous access types as long as they have matching designated 21076 subtypes. 21077 21078@noindent 21079 RM References: 4.03.01 (16) 21080 21081 21082@item 21083@emph{AI-0220 Needed components for aggregates (0000-00-00)} 21084@cindex AI-0220 (Ada 2012 feature) 21085 21086@noindent 21087 This AI addresses a wording problem in the RM that appears to permit some 21088 complex cases of aggregates with non-static discriminants. GNAT has always 21089 implemented the intended semantics. 21090 21091@noindent 21092 RM References: 4.03.01 (17) 21093 21094@item 21095@emph{AI-0147 Conditional expressions (2009-03-29)} 21096@cindex AI-0147 (Ada 2012 feature) 21097 21098@noindent 21099 Conditional expressions are permitted. The form of such an expression is: 21100 21101@smallexample 21102 (@b{if} @i{expr} @b{then} @i{expr} @{@b{elsif} @i{expr} @b{then} @i{expr}@} [@b{else} @i{expr}]) 21103@end smallexample 21104 21105 The parentheses can be omitted in contexts where parentheses are present 21106 anyway, such as subprogram arguments and pragma arguments. If the @b{else} 21107 clause is omitted, @b{else True} is assumed; 21108 thus @code{(@b{if} A @b{then} B)} is a way to conveniently represent 21109 @emph{(A implies B)} in standard logic. 21110 21111@noindent 21112 RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) 21113 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) 21114 21115 21116@item 21117@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} 21118@cindex AI-0037 (Ada 2012 feature) 21119 21120@noindent 21121 This AI confirms that an association of the form @code{Indx => <>} in an 21122 array aggregate must raise @code{Constraint_Error} if @code{Indx} 21123 is out of range. The RM specified a range check on other associations, but 21124 not when the value of the association was defaulted. GNAT has always inserted 21125 a constraint check on the index value. 21126 21127@noindent 21128 RM References: 4.03.03 (29) 21129 21130 21131@item 21132@emph{AI-0123 Composability of equality (2010-04-13)} 21133@cindex AI-0123 (Ada 2012 feature) 21134 21135@noindent 21136 Equality of untagged record composes, so that the predefined equality for a 21137 composite type that includes a component of some untagged record type 21138 @code{R} uses the equality operation of @code{R} (which may be user-defined 21139 or predefined). This makes the behavior of untagged records identical to that 21140 of tagged types in this respect. 21141 21142 This change is an incompatibility with previous versions of Ada, but it 21143 corrects a non-uniformity that was often a source of confusion. Analysis of 21144 a large number of industrial programs indicates that in those rare cases 21145 where a composite type had an untagged record component with a user-defined 21146 equality, either there was no use of the composite equality, or else the code 21147 expected the same composability as for tagged types, and thus had a bug that 21148 would be fixed by this change. 21149 21150@noindent 21151 RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) 21152 8.05.04 (8) 21153 21154 21155@item 21156@emph{AI-0088 The value of exponentiation (0000-00-00)} 21157@cindex AI-0088 (Ada 2012 feature) 21158 21159@noindent 21160 This AI clarifies the equivalence rule given for the dynamic semantics of 21161 exponentiation: the value of the operation can be obtained by repeated 21162 multiplication, but the operation can be implemented otherwise (for example 21163 using the familiar divide-by-two-and-square algorithm, even if this is less 21164 accurate), and does not imply repeated reads of a volatile base. 21165 21166@noindent 21167 RM References: 4.05.06 (11) 21168 21169@item 21170@emph{AI-0188 Case expressions (2010-01-09)} 21171@cindex AI-0188 (Ada 2012 feature) 21172 21173@noindent 21174 Case expressions are permitted. This allows use of constructs such as: 21175@smallexample 21176 X := (@b{case} Y @b{is when} 1 => 2, @b{when} 2 => 3, @b{when others} => 31) 21177@end smallexample 21178 21179@noindent 21180 RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) 21181 21182@item 21183@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} 21184@cindex AI-0104 (Ada 2012 feature) 21185 21186@noindent 21187 The assignment @code{Ptr := @b{new not null} Some_Ptr;} will raise 21188 @code{Constraint_Error} because the default value of the allocated object is 21189 @b{null}. This useless construct is illegal in Ada 2012. 21190 21191@noindent 21192 RM References: 4.08 (2) 21193 21194@item 21195@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} 21196@cindex AI-0157 (Ada 2012 feature) 21197 21198@noindent 21199 Allocation and Deallocation from an empty storage pool (i.e. allocation or 21200 deallocation of a pointer for which a static storage size clause of zero 21201 has been given) is now illegal and is detected as such. GNAT 21202 previously gave a warning but not an error. 21203 21204@noindent 21205 RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) 21206 21207@item 21208@emph{AI-0179 Statement not required after label (2010-04-10)} 21209@cindex AI-0179 (Ada 2012 feature) 21210 21211@noindent 21212 It is not necessary to have a statement following a label, so a label 21213 can appear at the end of a statement sequence without the need for putting a 21214 null statement afterwards, but it is not allowable to have only labels and 21215 no real statements in a statement sequence. 21216 21217@noindent 21218 RM References: 5.01 (2) 21219 21220 21221@item 21222@emph{AI-139-2 Syntactic sugar for iterators (2010-09-29)} 21223@cindex AI-139-2 (Ada 2012 feature) 21224 21225@noindent 21226 The new syntax for iterating over arrays and containers is now implemented. 21227 Iteration over containers is for now limited to read-only iterators. Only 21228 default iterators are supported, with the syntax: @code{@b{for} Elem @b{of} C}. 21229 21230@noindent 21231 RM References: 5.05 21232 21233@item 21234@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} 21235@cindex AI-0134 (Ada 2012 feature) 21236 21237@noindent 21238 For full conformance, the profiles of anonymous-access-to-subprogram 21239 parameters must match. GNAT has always enforced this rule. 21240 21241@noindent 21242 RM References: 6.03.01 (18) 21243 21244@item 21245@emph{AI-0207 Mode conformance and access constant (0000-00-00)} 21246@cindex AI-0207 (Ada 2012 feature) 21247 21248@noindent 21249 This AI confirms that access_to_constant indication must match for mode 21250 conformance. This was implemented in GNAT when the qualifier was originally 21251 introduced in Ada 2005. 21252 21253@noindent 21254 RM References: 6.03.01 (16/2) 21255 21256 21257@item 21258@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} 21259@cindex AI-0046 (Ada 2012 feature) 21260 21261@noindent 21262 For full conformance, in the case of access parameters, the null exclusion 21263 must match (either both or neither must have @code{@b{not null}}). 21264 21265@noindent 21266 RM References: 6.03.02 (18) 21267 21268 21269@item 21270@emph{AI-0118 The association of parameter associations (0000-00-00)} 21271@cindex AI-0118 (Ada 2012 feature) 21272 21273@noindent 21274 This AI clarifies the rules for named associations in subprogram calls and 21275 generic instantiations. The rules have been in place since Ada 83. 21276 21277@noindent 21278 RM References: 6.04.01 (2) 12.03 (9) 21279 21280 21281@item 21282@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} 21283@cindex AI-0196 (Ada 2012 feature) 21284 21285@noindent 21286 Null exclusion checks are not made for @code{@b{out}} parameters when 21287 evaluating the actual parameters. GNAT has never generated these checks. 21288 21289@noindent 21290 RM References: 6.04.01 (13) 21291 21292@item 21293@emph{AI-0015 Constant return objects (0000-00-00)} 21294@cindex AI-0015 (Ada 2012 feature) 21295 21296@noindent 21297 The return object declared in an @i{extended_return_statement} may be 21298 declared constant. This was always intended, and GNAT has always allowed it. 21299 21300@noindent 21301 RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) 21302 6.05 (5.7/2) 21303 21304 21305@item 21306@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} 21307@cindex AI-0032 (Ada 2012 feature) 21308 21309@noindent 21310 If a function returns a class-wide type, the object of an extended return 21311 statement can be declared with a specific type that is covered by the class- 21312 wide type. This has been implemented in GNAT since the introduction of 21313 extended returns. Note AI-0103 complements this AI by imposing matching 21314 rules for constrained return types. 21315 21316@noindent 21317 RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) 21318 6.05 (8/2) 21319 21320@item 21321@emph{AI-0103 Static matching for extended return (2010-07-23)} 21322@cindex AI-0103 (Ada 2012 feature) 21323 21324@noindent 21325 If the return subtype of a function is an elementary type or a constrained 21326 type, the subtype indication in an extended return statement must match 21327 statically this return subtype. 21328 21329@noindent 21330 RM References: 6.05 (5.2/2) 21331 21332 21333@item 21334@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} 21335@cindex AI-0058 (Ada 2012 feature) 21336 21337@noindent 21338 The RM had some incorrect wording implying wrong treatment of abnormal 21339 completion in an extended return. GNAT has always implemented the intended 21340 correct semantics as described by this AI. 21341 21342@noindent 21343 RM References: 6.05 (22/2) 21344 21345 21346@item 21347@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} 21348@cindex AI-0050 (Ada 2012 feature) 21349 21350@noindent 21351 The implementation permissions for raising @code{Constraint_Error} early on a function call when it was clear an exception would be raised were over-permissive and allowed mishandling of discriminants in some cases. GNAT did 21352 not take advantage of these incorrect permissions in any case. 21353 21354@noindent 21355 RM References: 6.05 (24/2) 21356 21357 21358@item 21359@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} 21360@cindex AI-0125 (Ada 2012 feature) 21361 21362@noindent 21363 In Ada 2012, the declaration of a primitive operation of a type extension 21364 or private extension can also override an inherited primitive that is not 21365 visible at the point of this declaration. 21366 21367@noindent 21368 RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) 21369 21370@item 21371@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} 21372@cindex AI-0062 (Ada 2012 feature) 21373 21374@noindent 21375 A full constant may have a null exclusion even if its associated deferred 21376 constant does not. GNAT has always allowed this. 21377 21378@noindent 21379 RM References: 7.04 (6/2) 7.04 (7.1/2) 21380 21381 21382@item 21383@emph{AI-0178 Incomplete views are limited (0000-00-00)} 21384@cindex AI-0178 (Ada 2012 feature) 21385 21386@noindent 21387 This AI clarifies the role of incomplete views and plugs an omission in the 21388 RM. GNAT always correctly restricted the use of incomplete views and types. 21389 21390@noindent 21391 RM References: 7.05 (3/2) 7.05 (6/2) 21392 21393@item 21394@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} 21395@cindex AI-0087 (Ada 2012 feature) 21396 21397@noindent 21398 The actual for a formal nonlimited derived type cannot be limited. In 21399 particular, a formal derived type that extends a limited interface but which 21400 is not explicitly limited cannot be instantiated with a limited type. 21401 21402@noindent 21403 RM References: 7.05 (5/2) 12.05.01 (5.1/2) 21404 21405@item 21406@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} 21407@cindex AI-0099 (Ada 2012 feature) 21408 21409@noindent 21410 This AI clarifies that ``needs finalization'' is part of dynamic semantics, 21411 and therefore depends on the run-time characteristics of an object (i.e. its 21412 tag) and not on its nominal type. As the AI indicates: ``we do not expect 21413 this to affect any implementation''. 21414 21415@noindent 21416 RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) 21417 21418 21419 21420@item 21421@emph{AI-0064 Redundant finalization rule (0000-00-00)} 21422@cindex AI-0064 (Ada 2012 feature) 21423 21424@noindent 21425 This is an editorial change only. The intended behavior is already checked 21426 by an existing ACATS test, which GNAT has always executed correctly. 21427 21428@noindent 21429 RM References: 7.06.01 (17.1/1) 21430 21431@item 21432@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} 21433@cindex AI-0026 (Ada 2012 feature) 21434 21435@noindent 21436 Record representation clauses concerning Unchecked_Union types cannot mention 21437 the discriminant of the type. The type of a component declared in the variant 21438 part of an Unchecked_Union cannot be controlled, have controlled components, 21439 nor have protected or task parts. If an Unchecked_Union type is declared 21440 within the body of a generic unit or its descendants, then the type of a 21441 component declared in the variant part cannot be a formal private type or a 21442 formal private extension declared within the same generic unit. 21443 21444@noindent 21445 RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) 21446 21447 21448@item 21449@emph{AI-0205 Extended return declares visible name (0000-00-00)} 21450@cindex AI-0205 (Ada 2012 feature) 21451 21452@noindent 21453 This AI corrects a simple omission in the RM. Return objects have always 21454 been visible within an extended return statement. 21455 21456@noindent 21457 RM References: 8.03 (17) 21458 21459 21460@item 21461@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} 21462@cindex AI-0042 (Ada 2012 feature) 21463 21464@noindent 21465 This AI fixes a wording gap in the RM. An operation of a synchronized 21466 interface can be implemented by a protected or task entry, but the abstract 21467 operation is not being overridden in the usual sense, and it must be stated 21468 separately that this implementation is legal. This has always been the case 21469 in GNAT. 21470 21471@noindent 21472 RM References: 9.01 (9.2/2) 9.04 (11.1/2) 21473 21474@item 21475@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} 21476@cindex AI-0030 (Ada 2012 feature) 21477 21478@noindent 21479 Requeue is permitted to a protected, synchronized or task interface primitive 21480 providing it is known that the overriding operation is an entry. Otherwise 21481 the requeue statement has the same effect as a procedure call. Use of pragma 21482 @code{Implemented} provides a way to impose a static requirement on the 21483 overriding operation by adhering to one of the implementation kinds: entry, 21484 protected procedure or any of the above. 21485 21486@noindent 21487 RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) 21488 9.05.04 (6) 9.05.04 (7) 9.05.04 (12) 21489 21490 21491@item 21492@emph{AI-0201 Independence of atomic object components (2010-07-22)} 21493@cindex AI-0201 (Ada 2012 feature) 21494 21495@noindent 21496 If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} 21497 attribute, then individual components may not be addressable by independent 21498 tasks. However, if the representation clause has no effect (is confirming), 21499 then independence is not compromised. Furthermore, in GNAT, specification of 21500 other appropriately addressable component sizes (e.g. 16 for 8-bit 21501 characters) also preserves independence. GNAT now gives very clear warnings 21502 both for the declaration of such a type, and for any assignment to its components. 21503 21504@noindent 21505 RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) 21506 21507@item 21508@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} 21509@cindex AI-0009 (Ada 2012 feature) 21510 21511@noindent 21512 This AI introduces the new pragmas @code{Independent} and 21513 @code{Independent_Components}, 21514 which control guaranteeing independence of access to objects and components. 21515 The AI also requires independence not unaffected by confirming rep clauses. 21516 21517@noindent 21518 RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) 21519 C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) 21520 21521 21522@item 21523@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)} 21524@cindex AI-0072 (Ada 2012 feature) 21525 21526@noindent 21527 This AI clarifies that task signalling for reading @code{'Terminated} only 21528 occurs if the result is True. GNAT semantics has always been consistent with 21529 this notion of task signalling. 21530 21531@noindent 21532 RM References: 9.10 (6.1/1) 21533 21534@item 21535@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} 21536@cindex AI-0108 (Ada 2012 feature) 21537 21538@noindent 21539 This AI confirms that an incomplete type from a limited view does not have 21540 discriminants. This has always been the case in GNAT. 21541 21542@noindent 21543 RM References: 10.01.01 (12.3/2) 21544 21545@item 21546@emph{AI-0129 Limited views and incomplete types (0000-00-00)} 21547@cindex AI-0129 (Ada 2012 feature) 21548 21549@noindent 21550 This AI clarifies the description of limited views: a limited view of a 21551 package includes only one view of a type that has an incomplete declaration 21552 and a full declaration (there is no possible ambiguity in a client package). 21553 This AI also fixes an omission: a nested package in the private part has no 21554 limited view. GNAT always implemented this correctly. 21555 21556@noindent 21557 RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) 21558 21559 21560 21561@item 21562@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} 21563@cindex AI-0077 (Ada 2012 feature) 21564 21565@noindent 21566 This AI clarifies that a declaration does not include a context clause, 21567 and confirms that it is illegal to have a context in which both a limited 21568 and a nonlimited view of a package are accessible. Such double visibility 21569 was always rejected by GNAT. 21570 21571@noindent 21572 RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) 21573 21574@item 21575@emph{AI-0122 Private with and children of generics (0000-00-00)} 21576@cindex AI-0122 (Ada 2012 feature) 21577 21578@noindent 21579 This AI clarifies the visibility of private children of generic units within 21580 instantiations of a parent. GNAT has always handled this correctly. 21581 21582@noindent 21583 RM References: 10.01.02 (12/2) 21584 21585 21586 21587@item 21588@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} 21589@cindex AI-0040 (Ada 2012 feature) 21590 21591@noindent 21592 This AI confirms that a limited with clause in a child unit cannot name 21593 an ancestor of the unit. This has always been checked in GNAT. 21594 21595@noindent 21596 RM References: 10.01.02 (20/2) 21597 21598@item 21599@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} 21600@cindex AI-0132 (Ada 2012 feature) 21601 21602@noindent 21603 This AI fills a gap in the description of library unit pragmas. The pragma 21604 clearly must apply to a library unit, even if it does not carry the name 21605 of the enclosing unit. GNAT has always enforced the required check. 21606 21607@noindent 21608 RM References: 10.01.05 (7) 21609 21610 21611@item 21612@emph{AI-0034 Categorization of limited views (0000-00-00)} 21613@cindex AI-0034 (Ada 2012 feature) 21614 21615@noindent 21616 The RM makes certain limited with clauses illegal because of categorization 21617 considerations, when the corresponding normal with would be legal. This is 21618 not intended, and GNAT has always implemented the recommended behavior. 21619 21620@noindent 21621 RM References: 10.02.01 (11/1) 10.02.01 (17/2) 21622 21623 21624@item 21625@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} 21626@cindex AI-0035 (Ada 2012 feature) 21627 21628@noindent 21629 This AI remedies some inconsistencies in the legality rules for Pure units. 21630 Derived access types are legal in a pure unit (on the assumption that the 21631 rule for a zero storage pool size has been enforced on the ancestor type). 21632 The rules are enforced in generic instances and in subunits. GNAT has always 21633 implemented the recommended behavior. 21634 21635@noindent 21636 RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) 21637 21638 21639@item 21640@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} 21641@cindex AI-0219 (Ada 2012 feature) 21642 21643@noindent 21644 This AI refines the rules for the cases with limited parameters which do not 21645 allow the implementations to omit ``redundant''. GNAT now properly conforms 21646 to the requirements of this binding interpretation. 21647 21648@noindent 21649 RM References: 10.02.01 (18/2) 21650 21651@item 21652@emph{AI-0043 Rules about raising exceptions (0000-00-00)} 21653@cindex AI-0043 (Ada 2012 feature) 21654 21655@noindent 21656 This AI covers various omissions in the RM regarding the raising of 21657 exceptions. GNAT has always implemented the intended semantics. 21658 21659@noindent 21660 RM References: 11.04.01 (10.1/2) 11 (2) 21661 21662 21663@item 21664@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} 21665@cindex AI-0200 (Ada 2012 feature) 21666 21667@noindent 21668 This AI plugs a gap in the RM which appeared to allow some obviously intended 21669 illegal instantiations. GNAT has never allowed these instantiations. 21670 21671@noindent 21672 RM References: 12.07 (16) 21673 21674 21675@item 21676@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} 21677@cindex AI-0112 (Ada 2012 feature) 21678 21679@noindent 21680 This AI concerns giving names to various representation aspects, but the 21681 practical effect is simply to make the use of duplicate 21682 @code{Atomic}[@code{_Components}], 21683 @code{Volatile}[@code{_Components}] and 21684 @code{Independent}[@code{_Components}] pragmas illegal, and GNAT 21685 now performs this required check. 21686 21687@noindent 21688 RM References: 13.01 (8) 21689 21690@item 21691@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} 21692@cindex AI-0106 (Ada 2012 feature) 21693 21694@noindent 21695 The RM appeared to allow representation pragmas on generic formal parameters, 21696 but this was not intended, and GNAT has never permitted this usage. 21697 21698@noindent 21699 RM References: 13.01 (9.1/1) 21700 21701 21702@item 21703@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} 21704@cindex AI-0012 (Ada 2012 feature) 21705 21706@noindent 21707 It is now illegal to give an inappropriate component size or a pragma 21708 @code{Pack} that attempts to change the component size in the case of atomic 21709 or aliased components. Previously GNAT ignored such an attempt with a 21710 warning. 21711 21712@noindent 21713 RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) 21714 21715 21716@item 21717@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} 21718@cindex AI-0039 (Ada 2012 feature) 21719 21720@noindent 21721 The RM permitted the use of dynamic expressions (such as @code{ptr.@b{all})} 21722 for stream attributes, but these were never useful and are now illegal. GNAT 21723 has always regarded such expressions as illegal. 21724 21725@noindent 21726 RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) 21727 21728 21729@item 21730@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} 21731@cindex AI-0095 (Ada 2012 feature) 21732 21733@noindent 21734 The prefix of @code{'Address} cannot statically denote a subprogram with 21735 convention @code{Intrinsic}. The use of the @code{Address} attribute raises 21736 @code{Program_Error} if the prefix denotes a subprogram with convention 21737 @code{Intrinsic}. 21738 21739@noindent 21740 RM References: 13.03 (11/1) 21741 21742 21743@item 21744@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} 21745@cindex AI-0116 (Ada 2012 feature) 21746 21747@noindent 21748 This AI requires that the alignment of a class-wide object be no greater 21749 than the alignment of any type in the class. GNAT has always followed this 21750 recommendation. 21751 21752@noindent 21753 RM References: 13.03 (29) 13.11 (16) 21754 21755 21756@item 21757@emph{AI-0146 Type invariants (2009-09-21)} 21758@cindex AI-0146 (Ada 2012 feature) 21759 21760@noindent 21761 Type invariants may be specified for private types using the aspect notation. 21762 Aspect @code{Type_Invariant} may be specified for any private type, 21763 @code{Type_Invariant'Class} can 21764 only be specified for tagged types, and is inherited by any descendent of the 21765 tagged types. The invariant is a boolean expression that is tested for being 21766 true in the following situations: conversions to the private type, object 21767 declarations for the private type that are default initialized, and 21768 [@b{in}] @b{out} 21769 parameters and returned result on return from any primitive operation for 21770 the type that is visible to a client. 21771 GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and 21772 @code{Invariant'Class} for @code{Type_Invariant'Class}. 21773 21774@noindent 21775 RM References: 13.03.03 (00) 21776 21777@item 21778@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} 21779@cindex AI-0078 (Ada 2012 feature) 21780 21781@noindent 21782 In Ada 2012, compilers are required to support unchecked conversion where the 21783 target alignment is a multiple of the source alignment. GNAT always supported 21784 this case (and indeed all cases of differing alignments, doing copies where 21785 required if the alignment was reduced). 21786 21787@noindent 21788 RM References: 13.09 (7) 21789 21790 21791@item 21792@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} 21793@cindex AI-0195 (Ada 2012 feature) 21794 21795@noindent 21796 The handling of invalid values is now designated to be implementation 21797 defined. This is a documentation change only, requiring Annex M in the GNAT 21798 Reference Manual to document this handling. 21799 In GNAT, checks for invalid values are made 21800 only when necessary to avoid erroneous behavior. Operations like assignments 21801 which cannot cause erroneous behavior ignore the possibility of invalid 21802 values and do not do a check. The date given above applies only to the 21803 documentation change, this behavior has always been implemented by GNAT. 21804 21805@noindent 21806 RM References: 13.09.01 (10) 21807 21808@item 21809@emph{AI-0193 Alignment of allocators (2010-09-16)} 21810@cindex AI-0193 (Ada 2012 feature) 21811 21812@noindent 21813 This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, 21814 analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead 21815 of size. 21816 21817@noindent 21818 RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) 21819 13.11.01 (2) 13.11.01 (3) 21820 21821 21822@item 21823@emph{AI-0177 Parameterized expressions (2010-07-10)} 21824@cindex AI-0177 (Ada 2012 feature) 21825 21826@noindent 21827 The new Ada 2012 notion of parameterized expressions is implemented. The form 21828 is: 21829@smallexample 21830 @i{function specification} @b{is} (@i{expression}) 21831@end smallexample 21832 21833@noindent 21834 This is exactly equivalent to the 21835 corresponding function body that returns the expression, but it can appear 21836 in a package spec. Note that the expression must be parenthesized. 21837 21838@noindent 21839 RM References: 13.11.01 (3/2) 21840 21841@item 21842@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} 21843@cindex AI-0033 (Ada 2012 feature) 21844 21845@noindent 21846 Neither of these two pragmas may appear within a generic template, because 21847 the generic might be instantiated at other than the library level. 21848 21849@noindent 21850 RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) 21851 21852 21853@item 21854@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} 21855@cindex AI-0161 (Ada 2012 feature) 21856 21857@noindent 21858 A new restriction @code{No_Default_Stream_Attributes} prevents the use of any 21859 of the default stream attributes for elementary types. If this restriction is 21860 in force, then it is necessary to provide explicit subprograms for any 21861 stream attributes used. 21862 21863@noindent 21864 RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) 21865 21866@item 21867@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} 21868@cindex AI-0194 (Ada 2012 feature) 21869 21870@noindent 21871 The @code{Stream_Size} attribute returns the default number of bits in the 21872 stream representation of the given type. 21873 This value is not affected by the presence 21874 of stream subprogram attributes for the type. GNAT has always implemented 21875 this interpretation. 21876 21877@noindent 21878 RM References: 13.13.02 (1.2/2) 21879 21880@item 21881@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)} 21882@cindex AI-0109 (Ada 2012 feature) 21883 21884@noindent 21885 This AI is an editorial change only. It removes the need for a tag check 21886 that can never fail. 21887 21888@noindent 21889 RM References: 13.13.02 (34/2) 21890 21891@item 21892@emph{AI-0007 Stream read and private scalar types (0000-00-00)} 21893@cindex AI-0007 (Ada 2012 feature) 21894 21895@noindent 21896 The RM as written appeared to limit the possibilities of declaring read 21897 attribute procedures for private scalar types. This limitation was not 21898 intended, and has never been enforced by GNAT. 21899 21900@noindent 21901 RM References: 13.13.02 (50/2) 13.13.02 (51/2) 21902 21903 21904@item 21905@emph{AI-0065 Remote access types and external streaming (0000-00-00)} 21906@cindex AI-0065 (Ada 2012 feature) 21907 21908@noindent 21909 This AI clarifies the fact that all remote access types support external 21910 streaming. This fixes an obvious oversight in the definition of the 21911 language, and GNAT always implemented the intended correct rules. 21912 21913@noindent 21914 RM References: 13.13.02 (52/2) 21915 21916@item 21917@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} 21918@cindex AI-0019 (Ada 2012 feature) 21919 21920@noindent 21921 The RM suggests that primitive subprograms of a specific tagged type are 21922 frozen when the tagged type is frozen. This would be an incompatible change 21923 and is not intended. GNAT has never attempted this kind of freezing and its 21924 behavior is consistent with the recommendation of this AI. 21925 21926@noindent 21927 RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) 21928 21929@item 21930@emph{AI-0017 Freezing and incomplete types (0000-00-00)} 21931@cindex AI-0017 (Ada 2012 feature) 21932 21933@noindent 21934 So-called ``Taft-amendment types'' (i.e., types that are completed in package 21935 bodies) are not frozen by the occurrence of bodies in the 21936 enclosing declarative part. GNAT always implemented this properly. 21937 21938@noindent 21939 RM References: 13.14 (3/1) 21940 21941 21942@item 21943@emph{AI-0060 Extended definition of remote access types (0000-00-00)} 21944@cindex AI-0060 (Ada 2012 feature) 21945 21946@noindent 21947 This AI extends the definition of remote access types to include access 21948 to limited, synchronized, protected or task class-wide interface types. 21949 GNAT already implemented this extension. 21950 21951@noindent 21952 RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) 21953 21954@item 21955@emph{AI-0114 Classification of letters (0000-00-00)} 21956@cindex AI-0114 (Ada 2012 feature) 21957 21958@noindent 21959 The code points 170 (@code{FEMININE ORDINAL INDICATOR}), 21960 181 (@code{MICRO SIGN}), and 21961 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered 21962 lower case letters by Unicode. 21963 However, they are not allowed in identifiers, and they 21964 return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. 21965 This behavior is consistent with that defined in Ada 95. 21966 21967@noindent 21968 RM References: A.03.02 (59) A.04.06 (7) 21969 21970 21971@item 21972@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} 21973@cindex AI-0185 (Ada 2012 feature) 21974 21975@noindent 21976 Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide 21977 classification functions for @code{Wide_Character} and 21978 @code{Wide_Wide_Character}, as well as providing 21979 case folding routines for @code{Wide_[Wide_]Character} and 21980 @code{Wide_[Wide_]String}. 21981 21982@noindent 21983 RM References: A.03.05 (0) A.03.06 (0) 21984 21985 21986@item 21987@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} 21988@cindex AI-0031 (Ada 2012 feature) 21989 21990@noindent 21991 A new version of @code{Find_Token} is added to all relevant string packages, 21992 with an extra parameter @code{From}. Instead of starting at the first 21993 character of the string, the search for a matching Token starts at the 21994 character indexed by the value of @code{From}. 21995 These procedures are available in all versions of Ada 21996 but if used in versions earlier than Ada 2012 they will generate a warning 21997 that an Ada 2012 subprogram is being used. 21998 21999@noindent 22000 RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) 22001 A.04.05 (46) 22002 22003 22004@item 22005@emph{AI-0056 Index on null string returns zero (0000-00-00)} 22006@cindex AI-0056 (Ada 2012 feature) 22007 22008@noindent 22009 The wording in the Ada 2005 RM implied an incompatible handling of the 22010 @code{Index} functions, resulting in raising an exception instead of 22011 returning zero in some situations. 22012 This was not intended and has been corrected. 22013 GNAT always returned zero, and is thus consistent with this AI. 22014 22015@noindent 22016 RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) 22017 22018 22019@item 22020@emph{AI-0137 String encoding package (2010-03-25)} 22021@cindex AI-0137 (Ada 2012 feature) 22022 22023@noindent 22024 The packages @code{Ada.Strings.UTF_Encoding}, together with its child 22025 packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, 22026 and @code{Wide_Wide_Strings} have been 22027 implemented. These packages (whose documentation can be found in the spec 22028 files @file{a-stuten.ads}, @file{a-suenco.ads}, @file{a-suenst.ads}, 22029 @file{a-suewst.ads}, @file{a-suezst.ads}) allow encoding and decoding of 22030 @code{String}, @code{Wide_String}, and @code{Wide_Wide_String} 22031 values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and 22032 UTF-16), as well as conversions between the different UTF encodings. With 22033 the exception of @code{Wide_Wide_Strings}, these packages are available in 22034 Ada 95 and Ada 2005 mode as well as Ada 2012 mode. 22035 The @code{Wide_Wide_Strings package} 22036 is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 22037 mode since it uses @code{Wide_Wide_Character}). 22038 22039@noindent 22040 RM References: A.04.11 22041 22042@item 22043@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} 22044@cindex AI-0038 (Ada 2012 feature) 22045 22046@noindent 22047 These are minor errors in the description on three points. The intent on 22048 all these points has always been clear, and GNAT has always implemented the 22049 correct intended semantics. 22050 22051@noindent 22052 RM 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) 22053 22054@item 22055@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} 22056@cindex AI-0044 (Ada 2012 feature) 22057 22058@noindent 22059 This AI places restrictions on allowed instantiations of generic containers. 22060 These restrictions are not checked by the compiler, so there is nothing to 22061 change in the implementation. This affects only the RM documentation. 22062 22063@noindent 22064 RM 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) 22065 22066@item 22067@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} 22068@cindex AI-0127 (Ada 2012 feature) 22069 22070@noindent 22071 This package provides an interface for identifying the current locale. 22072 22073@noindent 22074 RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 22075 A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 22076 22077 22078 22079@item 22080@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} 22081@cindex AI-0002 (Ada 2012 feature) 22082 22083@noindent 22084 The compiler is not required to support exporting an Ada subprogram with 22085 convention C if there are parameters or a return type of an unconstrained 22086 array type (such as @code{String}). GNAT allows such declarations but 22087 generates warnings. It is possible, but complicated, to write the 22088 corresponding C code and certainly such code would be specific to GNAT and 22089 non-portable. 22090 22091@noindent 22092 RM References: B.01 (17) B.03 (62) B.03 (71.1/2) 22093 22094 22095@item 22096@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} 22097@cindex AI05-0216 (Ada 2012 feature) 22098 22099@noindent 22100 It is clearly the intention that @code{No_Task_Hierarchy} is intended to 22101 forbid tasks declared locally within subprograms, or functions returning task 22102 objects, and that is the implementation that GNAT has always provided. 22103 However the language in the RM was not sufficiently clear on this point. 22104 Thus this is a documentation change in the RM only. 22105 22106@noindent 22107 RM References: D.07 (3/3) 22108 22109@item 22110@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} 22111@cindex AI-0211 (Ada 2012 feature) 22112 22113@noindent 22114 The restriction @code{No_Relative_Delays} forbids any calls to the subprogram 22115 @code{Ada.Real_Time.Timing_Events.Set_Handler}. 22116 22117@noindent 22118 RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) 22119 22120@item 22121@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} 22122@cindex AI-0190 (Ada 2012 feature) 22123 22124@noindent 22125 This AI introduces a new pragma @code{Default_Storage_Pool}, which can be 22126 used to control storage pools globally. 22127 In particular, you can force every access 22128 type that is used for allocation (@b{new}) to have an explicit storage pool, 22129 or you can declare a pool globally to be used for all access types that lack 22130 an explicit one. 22131 22132@noindent 22133 RM References: D.07 (8) 22134 22135@item 22136@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} 22137@cindex AI-0189 (Ada 2012 feature) 22138 22139@noindent 22140 This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, 22141 which says that no dynamic allocation will occur once elaboration is 22142 completed. 22143 In general this requires a run-time check, which is not required, and which 22144 GNAT does not attempt. But the static cases of allocators in a task body or 22145 in the body of the main program are detected and flagged at compile or bind 22146 time. 22147 22148@noindent 22149 RM References: D.07 (19.1/2) H.04 (23.3/2) 22150 22151@item 22152@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} 22153@cindex AI-0171 (Ada 2012 feature) 22154 22155@noindent 22156 A new package @code{System.Multiprocessors} is added, together with the 22157 definition of pragma @code{CPU} for controlling task affinity. A new no 22158 dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, 22159 is added to the Ravenscar profile. 22160 22161@noindent 22162 RM References: D.13.01 (4/2) D.16 22163 22164 22165@item 22166@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} 22167@cindex AI-0210 (Ada 2012 feature) 22168 22169@noindent 22170 This is a documentation only issue regarding wording of metric requirements, 22171 that does not affect the implementation of the compiler. 22172 22173@noindent 22174 RM References: D.15 (24/2) 22175 22176 22177@item 22178@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} 22179@cindex AI-0206 (Ada 2012 feature) 22180 22181@noindent 22182 Remote types packages are now allowed to depend on preelaborated packages. 22183 This was formerly considered illegal. 22184 22185@noindent 22186 RM References: E.02.02 (6) 22187 22188 22189 22190@item 22191@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} 22192@cindex AI-0152 (Ada 2012 feature) 22193 22194@noindent 22195 Restriction @code{No_Anonymous_Allocators} prevents the use of allocators 22196 where the type of the returned value is an anonymous access type. 22197 22198@noindent 22199 RM References: H.04 (8/1) 22200@end itemize 22201 22202 22203@node Obsolescent Features 22204@chapter Obsolescent Features 22205 22206@noindent 22207This chapter describes features that are provided by GNAT, but are 22208considered obsolescent since there are preferred ways of achieving 22209the same effect. These features are provided solely for historical 22210compatibility purposes. 22211 22212@menu 22213* pragma No_Run_Time:: 22214* pragma Ravenscar:: 22215* pragma Restricted_Run_Time:: 22216@end menu 22217 22218@node pragma No_Run_Time 22219@section pragma No_Run_Time 22220 22221The pragma @code{No_Run_Time} is used to achieve an affect similar 22222to the use of the "Zero Foot Print" configurable run time, but without 22223requiring a specially configured run time. The result of using this 22224pragma, which must be used for all units in a partition, is to restrict 22225the use of any language features requiring run-time support code. The 22226preferred usage is to use an appropriately configured run-time that 22227includes just those features that are to be made accessible. 22228 22229@node pragma Ravenscar 22230@section pragma Ravenscar 22231 22232The pragma @code{Ravenscar} has exactly the same effect as pragma 22233@code{Profile (Ravenscar)}. The latter usage is preferred since it 22234is part of the new Ada 2005 standard. 22235 22236@node pragma Restricted_Run_Time 22237@section pragma Restricted_Run_Time 22238 22239The pragma @code{Restricted_Run_Time} has exactly the same effect as 22240pragma @code{Profile (Restricted)}. The latter usage is 22241preferred since the Ada 2005 pragma @code{Profile} is intended for 22242this kind of implementation dependent addition. 22243 22244@include fdl.texi 22245@c GNU Free Documentation License 22246 22247@node Index,,GNU Free Documentation License, Top 22248@unnumbered Index 22249 22250@printindex cp 22251 22252@contents 22253 22254@bye 22255tablishes the following set of restrictions: 22256Pragma Shared 22257