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@set DEFAULTLANGUAGEVERSION Ada 2005 30@set NONDEFAULTLANGUAGEVERSION Ada 95 31 32@settitle GNAT Reference Manual 33 34@setchapternewpage odd 35@syncodeindex fn cp 36 37@include gcc-common.texi 38 39@dircategory GNU Ada tools 40@direntry 41* GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools. 42@end direntry 43 44@titlepage 45@title GNAT Reference Manual 46@subtitle GNAT, The GNU Ada Compiler 47@versionsubtitle 48@author AdaCore 49@page 50@vskip 0pt plus 1filll 51 52@insertcopying 53 54@end titlepage 55 56@ifnottex 57@node Top, About This Guide, (dir), (dir) 58@top GNAT Reference Manual 59 60@noindent 61GNAT Reference Manual 62 63@noindent 64GNAT, The GNU Ada Compiler@* 65GCC version @value{version-GCC}@* 66 67@noindent 68AdaCore 69 70@menu 71* About This Guide:: 72* Implementation Defined Pragmas:: 73* Implementation Defined Attributes:: 74* Standard and Implementation Defined Restrictions:: 75* Implementation Advice:: 76* Implementation Defined Characteristics:: 77* Intrinsic Subprograms:: 78* Representation Clauses and Pragmas:: 79* Standard Library Routines:: 80* The Implementation of Standard I/O:: 81* The GNAT Library:: 82* Interfacing to Other Languages:: 83* Specialized Needs Annexes:: 84* Implementation of Specific Ada Features:: 85* Implementation of Ada 2012 Features:: 86* Obsolescent Features:: 87* GNU Free Documentation License:: 88* Index:: 89 90 --- The Detailed Node Listing --- 91 92About This Guide 93 94* What This Reference Manual Contains:: 95* Related Information:: 96 97Implementation Defined Pragmas 98 99* Pragma Abort_Defer:: 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 Annotate:: 107* Pragma Assert:: 108* Pragma Assertion_Policy:: 109* Pragma Assume_No_Invalid_Values:: 110* Pragma Attribute_Definition:: 111* Pragma Ast_Entry:: 112* Pragma C_Pass_By_Copy:: 113* Pragma Check:: 114* Pragma Check_Float_Overflow:: 115* Pragma Check_Name:: 116* Pragma Check_Policy:: 117* Pragma Comment:: 118* Pragma Common_Object:: 119* Pragma Compile_Time_Error:: 120* Pragma Compile_Time_Warning:: 121* Pragma Compiler_Unit:: 122* Pragma Complete_Representation:: 123* Pragma Complex_Representation:: 124* Pragma Component_Alignment:: 125* Pragma Contract_Case:: 126* Pragma Convention_Identifier:: 127* Pragma CPP_Class:: 128* Pragma CPP_Constructor:: 129* Pragma CPP_Virtual:: 130* Pragma CPP_Vtable:: 131* Pragma CPU:: 132* Pragma Debug:: 133* Pragma Debug_Policy:: 134* Pragma Default_Storage_Pool:: 135* Pragma Detect_Blocking:: 136* Pragma Dispatching_Domain:: 137* Pragma Elaboration_Checks:: 138* Pragma Eliminate:: 139* Pragma Export_Exception:: 140* Pragma Export_Function:: 141* Pragma Export_Object:: 142* Pragma Export_Procedure:: 143* Pragma Export_Value:: 144* Pragma Export_Valued_Procedure:: 145* Pragma Extend_System:: 146* Pragma Extensions_Allowed:: 147* Pragma External:: 148* Pragma External_Name_Casing:: 149* Pragma Fast_Math:: 150* Pragma Favor_Top_Level:: 151* Pragma Finalize_Storage_Only:: 152* Pragma Float_Representation:: 153* Pragma Ident:: 154* Pragma Implementation_Defined:: 155* Pragma Implemented:: 156* Pragma Implicit_Packing:: 157* Pragma Import_Exception:: 158* Pragma Import_Function:: 159* Pragma Import_Object:: 160* Pragma Import_Procedure:: 161* Pragma Import_Valued_Procedure:: 162* Pragma Independent:: 163* Pragma Independent_Components:: 164* Pragma Initialize_Scalars:: 165* Pragma Inline_Always:: 166* Pragma Inline_Generic:: 167* Pragma Interface:: 168* Pragma Interface_Name:: 169* Pragma Interrupt_Handler:: 170* Pragma Interrupt_State:: 171* Pragma Invariant:: 172* Pragma Keep_Names:: 173* Pragma License:: 174* Pragma Link_With:: 175* Pragma Linker_Alias:: 176* Pragma Linker_Constructor:: 177* Pragma Linker_Destructor:: 178* Pragma Linker_Section:: 179* Pragma Long_Float:: 180* Pragma Loop_Optimize:: 181* Pragma Machine_Attribute:: 182* Pragma Main:: 183* Pragma Main_Storage:: 184* Pragma No_Body:: 185* Pragma No_Inline:: 186* Pragma No_Return:: 187* Pragma No_Strict_Aliasing :: 188* Pragma Normalize_Scalars:: 189* Pragma Obsolescent:: 190* Pragma Optimize_Alignment:: 191* Pragma Ordered:: 192* Pragma Overflow_Mode:: 193* Pragma Partition_Elaboration_Policy:: 194* Pragma Passive:: 195* Pragma Persistent_BSS:: 196* Pragma Polling:: 197* Pragma Postcondition:: 198* Pragma Precondition:: 199* Pragma Preelaborable_Initialization:: 200* Pragma Priority_Specific_Dispatching:: 201* Pragma Profile (Ravenscar):: 202* Pragma Profile (Restricted):: 203* Pragma Profile (Rational):: 204* Pragma Psect_Object:: 205* Pragma Pure_Function:: 206* Pragma Relative_Deadline:: 207* Pragma Remote_Access_Type:: 208* Pragma Restriction_Warnings:: 209* Pragma Shared:: 210* Pragma Short_Circuit_And_Or:: 211* Pragma Short_Descriptors:: 212* Pragma Simple_Storage_Pool_Type:: 213* Pragma Source_File_Name:: 214* Pragma Source_File_Name_Project:: 215* Pragma Source_Reference:: 216* Pragma Static_Elaboration_Desired:: 217* Pragma Stream_Convert:: 218* Pragma Style_Checks:: 219* Pragma Subtitle:: 220* Pragma Suppress:: 221* Pragma Suppress_All:: 222* Pragma Suppress_Exception_Locations:: 223* Pragma Suppress_Initialization:: 224* Pragma Task_Info:: 225* Pragma Task_Name:: 226* Pragma Task_Storage:: 227* Pragma Test_Case:: 228* Pragma Thread_Local_Storage:: 229* Pragma Time_Slice:: 230* Pragma Title:: 231* Pragma Unchecked_Union:: 232* Pragma Unimplemented_Unit:: 233* Pragma Universal_Aliasing :: 234* Pragma Universal_Data:: 235* Pragma Unmodified:: 236* Pragma Unreferenced:: 237* Pragma Unreferenced_Objects:: 238* Pragma Unreserve_All_Interrupts:: 239* Pragma Unsuppress:: 240* Pragma Use_VADS_Size:: 241* Pragma Validity_Checks:: 242* Pragma Volatile:: 243* Pragma Warnings:: 244* Pragma Weak_External:: 245* Pragma Wide_Character_Encoding:: 246 247Implementation Defined Attributes 248 249* Abort_Signal:: 250* Address_Size:: 251* Asm_Input:: 252* Asm_Output:: 253* AST_Entry:: 254* Bit:: 255* Bit_Position:: 256* Compiler_Version:: 257* Code_Address:: 258* Default_Bit_Order:: 259* Descriptor_Size:: 260* Elaborated:: 261* Elab_Body:: 262* Elab_Spec:: 263* Elab_Subp_Body:: 264* Emax:: 265* Enabled:: 266* Enum_Rep:: 267* Enum_Val:: 268* Epsilon:: 269* Fixed_Value:: 270* Has_Access_Values:: 271* Has_Discriminants:: 272* Img:: 273* Integer_Value:: 274* Invalid_Value:: 275* Large:: 276* Machine_Size:: 277* Mantissa:: 278* Max_Interrupt_Priority:: 279* Max_Priority:: 280* Maximum_Alignment:: 281* Mechanism_Code:: 282* Null_Parameter:: 283* Object_Size:: 284* Passed_By_Reference:: 285* Pool_Address:: 286* Range_Length:: 287* Result:: 288* Safe_Emax:: 289* Safe_Large:: 290* Scalar_Storage_Order:: 291* Simple_Storage_Pool:: 292* Small:: 293* Storage_Unit:: 294* Stub_Type:: 295* System_Allocator_Alignment:: 296* Target_Name:: 297* Tick:: 298* To_Address:: 299* Type_Class:: 300* UET_Address:: 301* Unconstrained_Array:: 302* Universal_Literal_String:: 303* Unrestricted_Access:: 304* Valid_Scalars:: 305* VADS_Size:: 306* Value_Size:: 307* Wchar_T_Size:: 308* Word_Size:: 309 310Standard and Implementation Defined Restrictions 311 312* Partition-Wide Restrictions:: 313* Program Unit Level Restrictions:: 314 315Partition-Wide Restrictions 316 317* Immediate_Reclamation:: 318* Max_Asynchronous_Select_Nesting:: 319* Max_Entry_Queue_Length:: 320* Max_Protected_Entries:: 321* Max_Select_Alternatives:: 322* Max_Storage_At_Blocking:: 323* Max_Task_Entries:: 324* Max_Tasks:: 325* No_Abort_Statements:: 326* No_Access_Parameter_Allocators:: 327* No_Access_Subprograms:: 328* No_Allocators:: 329* No_Anonymous_Allocators:: 330* No_Calendar:: 331* No_Coextensions:: 332* No_Default_Initialization:: 333* No_Delay:: 334* No_Dependence:: 335* No_Direct_Boolean_Operators:: 336* No_Dispatch:: 337* No_Dispatching_Calls:: 338* No_Dynamic_Attachment:: 339* No_Dynamic_Priorities:: 340* No_Entry_Calls_In_Elaboration_Code:: 341* No_Enumeration_Maps:: 342* No_Exception_Handlers:: 343* No_Exception_Propagation:: 344* No_Exception_Registration:: 345* No_Exceptions:: 346* No_Finalization:: 347* No_Fixed_Point:: 348* No_Floating_Point:: 349* No_Implicit_Conditionals:: 350* No_Implicit_Dynamic_Code:: 351* No_Implicit_Heap_Allocations:: 352* No_Implicit_Loops:: 353* No_Initialize_Scalars:: 354* No_IO:: 355* No_Local_Allocators:: 356* No_Local_Protected_Objects:: 357* No_Local_Timing_Events:: 358* No_Nested_Finalization:: 359* No_Protected_Type_Allocators:: 360* No_Protected_Types:: 361* No_Recursion:: 362* No_Reentrancy:: 363* No_Relative_Delay:: 364* No_Requeue_Statements:: 365* No_Secondary_Stack:: 366* No_Select_Statements:: 367* No_Specific_Termination_Handlers:: 368* No_Specification_of_Aspect:: 369* No_Standard_Allocators_After_Elaboration:: 370* No_Standard_Storage_Pools:: 371* No_Stream_Optimizations:: 372* No_Streams:: 373* No_Task_Allocators:: 374* No_Task_Attributes_Package:: 375* No_Task_Hierarchy:: 376* No_Task_Termination:: 377* No_Tasking:: 378* No_Terminate_Alternatives:: 379* No_Unchecked_Access:: 380* Simple_Barriers:: 381* Static_Priorities:: 382* Static_Storage_Size:: 383 384Program Unit Level Restrictions 385 386* No_Elaboration_Code:: 387* No_Entry_Queue:: 388* No_Implementation_Aspect_Specifications:: 389* No_Implementation_Attributes:: 390* No_Implementation_Identifiers:: 391* No_Implementation_Pragmas:: 392* No_Implementation_Restrictions:: 393* No_Implementation_Units:: 394* No_Implicit_Aliasing:: 395* No_Obsolescent_Features:: 396* No_Wide_Characters:: 397* SPARK:: 398 399The Implementation of Standard I/O 400 401* Standard I/O Packages:: 402* FORM Strings:: 403* Direct_IO:: 404* Sequential_IO:: 405* Text_IO:: 406* Wide_Text_IO:: 407* Wide_Wide_Text_IO:: 408* Stream_IO:: 409* Text Translation:: 410* Shared Files:: 411* Filenames encoding:: 412* Open Modes:: 413* Operations on C Streams:: 414* Interfacing to C Streams:: 415 416The GNAT Library 417 418* Ada.Characters.Latin_9 (a-chlat9.ads):: 419* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: 420* Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: 421* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads):: 422* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads):: 423* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads):: 424* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads):: 425* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads):: 426* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads):: 427* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads):: 428* Ada.Containers.Formal_Vectors (a-cofove.ads):: 429* Ada.Command_Line.Environment (a-colien.ads):: 430* Ada.Command_Line.Remove (a-colire.ads):: 431* Ada.Command_Line.Response_File (a-clrefi.ads):: 432* Ada.Direct_IO.C_Streams (a-diocst.ads):: 433* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: 434* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads):: 435* Ada.Exceptions.Traceback (a-exctra.ads):: 436* Ada.Sequential_IO.C_Streams (a-siocst.ads):: 437* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: 438* Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: 439* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: 440* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads):: 441* Ada.Text_IO.C_Streams (a-tiocst.ads):: 442* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads):: 443* Ada.Wide_Characters.Unicode (a-wichun.ads):: 444* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: 445* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads):: 446* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads):: 447* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: 448* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads):: 449* GNAT.Altivec (g-altive.ads):: 450* GNAT.Altivec.Conversions (g-altcon.ads):: 451* GNAT.Altivec.Vector_Operations (g-alveop.ads):: 452* GNAT.Altivec.Vector_Types (g-alvety.ads):: 453* GNAT.Altivec.Vector_Views (g-alvevi.ads):: 454* GNAT.Array_Split (g-arrspl.ads):: 455* GNAT.AWK (g-awk.ads):: 456* GNAT.Bounded_Buffers (g-boubuf.ads):: 457* GNAT.Bounded_Mailboxes (g-boumai.ads):: 458* GNAT.Bubble_Sort (g-bubsor.ads):: 459* GNAT.Bubble_Sort_A (g-busora.ads):: 460* GNAT.Bubble_Sort_G (g-busorg.ads):: 461* GNAT.Byte_Order_Mark (g-byorma.ads):: 462* GNAT.Byte_Swapping (g-bytswa.ads):: 463* GNAT.Calendar (g-calend.ads):: 464* GNAT.Calendar.Time_IO (g-catiio.ads):: 465* GNAT.Case_Util (g-casuti.ads):: 466* GNAT.CGI (g-cgi.ads):: 467* GNAT.CGI.Cookie (g-cgicoo.ads):: 468* GNAT.CGI.Debug (g-cgideb.ads):: 469* GNAT.Command_Line (g-comlin.ads):: 470* GNAT.Compiler_Version (g-comver.ads):: 471* GNAT.Ctrl_C (g-ctrl_c.ads):: 472* GNAT.CRC32 (g-crc32.ads):: 473* GNAT.Current_Exception (g-curexc.ads):: 474* GNAT.Debug_Pools (g-debpoo.ads):: 475* GNAT.Debug_Utilities (g-debuti.ads):: 476* GNAT.Decode_String (g-decstr.ads):: 477* GNAT.Decode_UTF8_String (g-deutst.ads):: 478* GNAT.Directory_Operations (g-dirope.ads):: 479* GNAT.Directory_Operations.Iteration (g-diopit.ads):: 480* GNAT.Dynamic_HTables (g-dynhta.ads):: 481* GNAT.Dynamic_Tables (g-dyntab.ads):: 482* GNAT.Encode_String (g-encstr.ads):: 483* GNAT.Encode_UTF8_String (g-enutst.ads):: 484* GNAT.Exception_Actions (g-excact.ads):: 485* GNAT.Exception_Traces (g-exctra.ads):: 486* GNAT.Exceptions (g-except.ads):: 487* GNAT.Expect (g-expect.ads):: 488* GNAT.Expect.TTY (g-exptty.ads):: 489* GNAT.Float_Control (g-flocon.ads):: 490* GNAT.Heap_Sort (g-heasor.ads):: 491* GNAT.Heap_Sort_A (g-hesora.ads):: 492* GNAT.Heap_Sort_G (g-hesorg.ads):: 493* GNAT.HTable (g-htable.ads):: 494* GNAT.IO (g-io.ads):: 495* GNAT.IO_Aux (g-io_aux.ads):: 496* GNAT.Lock_Files (g-locfil.ads):: 497* GNAT.MBBS_Discrete_Random (g-mbdira.ads):: 498* GNAT.MBBS_Float_Random (g-mbflra.ads):: 499* GNAT.MD5 (g-md5.ads):: 500* GNAT.Memory_Dump (g-memdum.ads):: 501* GNAT.Most_Recent_Exception (g-moreex.ads):: 502* GNAT.OS_Lib (g-os_lib.ads):: 503* GNAT.Perfect_Hash_Generators (g-pehage.ads):: 504* GNAT.Random_Numbers (g-rannum.ads):: 505* GNAT.Regexp (g-regexp.ads):: 506* GNAT.Registry (g-regist.ads):: 507* GNAT.Regpat (g-regpat.ads):: 508* GNAT.Secondary_Stack_Info (g-sestin.ads):: 509* GNAT.Semaphores (g-semaph.ads):: 510* GNAT.Serial_Communications (g-sercom.ads):: 511* GNAT.SHA1 (g-sha1.ads):: 512* GNAT.SHA224 (g-sha224.ads):: 513* GNAT.SHA256 (g-sha256.ads):: 514* GNAT.SHA384 (g-sha384.ads):: 515* GNAT.SHA512 (g-sha512.ads):: 516* GNAT.Signals (g-signal.ads):: 517* GNAT.Sockets (g-socket.ads):: 518* GNAT.Source_Info (g-souinf.ads):: 519* GNAT.Spelling_Checker (g-speche.ads):: 520* GNAT.Spelling_Checker_Generic (g-spchge.ads):: 521* GNAT.Spitbol.Patterns (g-spipat.ads):: 522* GNAT.Spitbol (g-spitbo.ads):: 523* GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: 524* GNAT.Spitbol.Table_Integer (g-sptain.ads):: 525* GNAT.Spitbol.Table_VString (g-sptavs.ads):: 526* GNAT.SSE (g-sse.ads):: 527* GNAT.SSE.Vector_Types (g-ssvety.ads):: 528* GNAT.Strings (g-string.ads):: 529* GNAT.String_Split (g-strspl.ads):: 530* GNAT.Table (g-table.ads):: 531* GNAT.Task_Lock (g-tasloc.ads):: 532* GNAT.Threads (g-thread.ads):: 533* GNAT.Time_Stamp (g-timsta.ads):: 534* GNAT.Traceback (g-traceb.ads):: 535* GNAT.Traceback.Symbolic (g-trasym.ads):: 536* GNAT.UTF_32 (g-utf_32.ads):: 537* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads):: 538* GNAT.Wide_Spelling_Checker (g-wispch.ads):: 539* GNAT.Wide_String_Split (g-wistsp.ads):: 540* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads):: 541* GNAT.Wide_Wide_String_Split (g-zistsp.ads):: 542* Interfaces.C.Extensions (i-cexten.ads):: 543* Interfaces.C.Streams (i-cstrea.ads):: 544* Interfaces.CPP (i-cpp.ads):: 545* Interfaces.Packed_Decimal (i-pacdec.ads):: 546* Interfaces.VxWorks (i-vxwork.ads):: 547* Interfaces.VxWorks.IO (i-vxwoio.ads):: 548* System.Address_Image (s-addima.ads):: 549* System.Assertions (s-assert.ads):: 550* System.Memory (s-memory.ads):: 551* System.Partition_Interface (s-parint.ads):: 552* System.Pool_Global (s-pooglo.ads):: 553* System.Pool_Local (s-pooloc.ads):: 554* System.Restrictions (s-restri.ads):: 555* System.Rident (s-rident.ads):: 556* System.Strings.Stream_Ops (s-ststop.ads):: 557* System.Task_Info (s-tasinf.ads):: 558* System.Wch_Cnv (s-wchcnv.ads):: 559* System.Wch_Con (s-wchcon.ads):: 560 561Text_IO 562 563* Text_IO Stream Pointer Positioning:: 564* Text_IO Reading and Writing Non-Regular Files:: 565* Get_Immediate:: 566* Treating Text_IO Files as Streams:: 567* Text_IO Extensions:: 568* Text_IO Facilities for Unbounded Strings:: 569 570Wide_Text_IO 571 572* Wide_Text_IO Stream Pointer Positioning:: 573* Wide_Text_IO Reading and Writing Non-Regular Files:: 574 575Wide_Wide_Text_IO 576 577* Wide_Wide_Text_IO Stream Pointer Positioning:: 578* Wide_Wide_Text_IO Reading and Writing Non-Regular Files:: 579 580Interfacing to Other Languages 581 582* Interfacing to C:: 583* Interfacing to C++:: 584* Interfacing to COBOL:: 585* Interfacing to Fortran:: 586* Interfacing to non-GNAT Ada code:: 587 588Specialized Needs Annexes 589 590Implementation of Specific Ada Features 591* Machine Code Insertions:: 592* GNAT Implementation of Tasking:: 593* GNAT Implementation of Shared Passive Packages:: 594* Code Generation for Array Aggregates:: 595* The Size of Discriminated Records with Default Discriminants:: 596* Strict Conformance to the Ada Reference Manual:: 597 598Implementation of Ada 2012 Features 599 600Obsolescent Features 601 602GNU Free Documentation License 603 604Index 605@end menu 606 607@end ifnottex 608 609@node About This Guide 610@unnumbered About This Guide 611 612@noindent 613This manual contains useful information in writing programs using the 614@value{EDITION} compiler. It includes information on implementation dependent 615characteristics of @value{EDITION}, including all the information required by 616Annex M of the Ada language standard. 617 618@value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in 619Ada 83 compatibility mode. 620By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION}, 621but you can override with a compiler switch 622to explicitly specify the language version. 623(Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn, 624@value{EDITION} User's Guide}, for details on these switches.) 625Throughout this manual, references to ``Ada'' without a year suffix 626apply to both the Ada 95 and Ada 2005 versions of the language. 627 628Ada is designed to be highly portable. 629In general, a program will have the same effect even when compiled by 630different compilers on different platforms. 631However, since Ada is designed to be used in a 632wide variety of applications, it also contains a number of system 633dependent features to be used in interfacing to the external world. 634@cindex Implementation-dependent features 635@cindex Portability 636 637Note: Any program that makes use of implementation-dependent features 638may be non-portable. You should follow good programming practice and 639isolate and clearly document any sections of your program that make use 640of these features in a non-portable manner. 641 642@ifset PROEDITION 643For ease of exposition, ``@value{EDITION}'' will be referred to simply as 644``GNAT'' in the remainder of this document. 645@end ifset 646 647@menu 648* What This Reference Manual Contains:: 649* Conventions:: 650* Related Information:: 651@end menu 652 653@node What This Reference Manual Contains 654@unnumberedsec What This Reference Manual Contains 655 656@noindent 657This reference manual contains the following chapters: 658 659@itemize @bullet 660@item 661@ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent 662pragmas, which can be used to extend and enhance the functionality of the 663compiler. 664 665@item 666@ref{Implementation Defined Attributes}, lists GNAT 667implementation-dependent attributes, which can be used to extend and 668enhance the functionality of the compiler. 669 670@item 671@ref{Standard and Implementation Defined Restrictions}, lists GNAT 672implementation-dependent restrictions, which can be used to extend and 673enhance the functionality of the compiler. 674 675@item 676@ref{Implementation Advice}, provides information on generally 677desirable behavior which are not requirements that all compilers must 678follow since it cannot be provided on all systems, or which may be 679undesirable on some systems. 680 681@item 682@ref{Implementation Defined Characteristics}, provides a guide to 683minimizing implementation dependent features. 684 685@item 686@ref{Intrinsic Subprograms}, describes the intrinsic subprograms 687implemented by GNAT, and how they can be imported into user 688application programs. 689 690@item 691@ref{Representation Clauses and Pragmas}, describes in detail the 692way that GNAT represents data, and in particular the exact set 693of representation clauses and pragmas that is accepted. 694 695@item 696@ref{Standard Library Routines}, provides a listing of packages and a 697brief description of the functionality that is provided by Ada's 698extensive set of standard library routines as implemented by GNAT@. 699 700@item 701@ref{The Implementation of Standard I/O}, details how the GNAT 702implementation of the input-output facilities. 703 704@item 705@ref{The GNAT Library}, is a catalog of packages that complement 706the Ada predefined library. 707 708@item 709@ref{Interfacing to Other Languages}, describes how programs 710written in Ada using GNAT can be interfaced to other programming 711languages. 712 713@ref{Specialized Needs Annexes}, describes the GNAT implementation of all 714of the specialized needs annexes. 715 716@item 717@ref{Implementation of Specific Ada Features}, discusses issues related 718to GNAT's implementation of machine code insertions, tasking, and several 719other features. 720 721@item 722@ref{Implementation of Ada 2012 Features}, describes the status of the 723GNAT implementation of the Ada 2012 language standard. 724 725@item 726@ref{Obsolescent Features} documents implementation dependent features, 727including pragmas and attributes, which are considered obsolescent, since 728there are other preferred ways of achieving the same results. These 729obsolescent forms are retained for backwards compatibility. 730 731@end itemize 732 733@cindex Ada 95 Language Reference Manual 734@cindex Ada 2005 Language Reference Manual 735@noindent 736This reference manual assumes a basic familiarity with the Ada 95 language, as 737described in the International Standard ANSI/ISO/IEC-8652:1995, 738January 1995. 739It does not require knowledge of the new features introduced by Ada 2005, 740(officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1 741and Amendment 1). 742Both reference manuals are included in the GNAT documentation 743package. 744 745@node Conventions 746@unnumberedsec Conventions 747@cindex Conventions, typographical 748@cindex Typographical conventions 749 750@noindent 751Following are examples of the typographical and graphic conventions used 752in this guide: 753 754@itemize @bullet 755@item 756@code{Functions}, @code{utility program names}, @code{standard names}, 757and @code{classes}. 758 759@item 760@code{Option flags} 761 762@item 763@file{File names}, @samp{button names}, and @samp{field names}. 764 765@item 766@code{Variables}, @env{environment variables}, and @var{metasyntactic 767variables}. 768 769@item 770@emph{Emphasis}. 771 772@item 773[optional information or parameters] 774 775@item 776Examples are described by text 777@smallexample 778and then shown this way. 779@end smallexample 780@end itemize 781 782@noindent 783Commands that are entered by the user are preceded in this manual by the 784characters @samp{$ } (dollar sign followed by space). If your system uses this 785sequence as a prompt, then the commands will appear exactly as you see them 786in the manual. If your system uses some other prompt, then the command will 787appear with the @samp{$} replaced by whatever prompt character you are using. 788 789@node Related Information 790@unnumberedsec Related Information 791@noindent 792See the following documents for further information on GNAT: 793 794@itemize @bullet 795@item 796@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn, 797@value{EDITION} User's Guide}, which provides information on how to use the 798GNAT compiler system. 799 800@item 801@cite{Ada 95 Reference Manual}, which contains all reference 802material for the Ada 95 programming language. 803 804@item 805@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 806of the Ada 95 standard. The annotations describe 807detailed aspects of the design decision, and in particular contain useful 808sections on Ada 83 compatibility. 809 810@item 811@cite{Ada 2005 Reference Manual}, which contains all reference 812material for the Ada 2005 programming language. 813 814@item 815@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version 816of the Ada 2005 standard. The annotations describe 817detailed aspects of the design decision, and in particular contain useful 818sections on Ada 83 and Ada 95 compatibility. 819 820@item 821@cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms}, 822which contains specific information on compatibility between GNAT and 823DEC Ada 83 systems. 824 825@item 826@cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which 827describes in detail the pragmas and attributes provided by the DEC Ada 83 828compiler system. 829 830@end itemize 831 832@node Implementation Defined Pragmas 833@chapter Implementation Defined Pragmas 834 835@noindent 836Ada defines a set of pragmas that can be used to supply additional 837information to the compiler. These language defined pragmas are 838implemented in GNAT and work as described in the Ada Reference Manual. 839 840In addition, Ada allows implementations to define additional pragmas 841whose meaning is defined by the implementation. GNAT provides a number 842of these implementation-defined pragmas, which can be used to extend 843and enhance the functionality of the compiler. This section of the GNAT 844Reference Manual describes these additional pragmas. 845 846Note that any program using these pragmas might not be portable to other 847compilers (although GNAT implements this set of pragmas on all 848platforms). Therefore if portability to other compilers is an important 849consideration, the use of these pragmas should be minimized. 850 851@menu 852* Pragma Abort_Defer:: 853* Pragma Ada_83:: 854* Pragma Ada_95:: 855* Pragma Ada_05:: 856* Pragma Ada_2005:: 857* Pragma Ada_12:: 858* Pragma Ada_2012:: 859* Pragma Annotate:: 860* Pragma Assert:: 861* Pragma Assertion_Policy:: 862* Pragma Assume_No_Invalid_Values:: 863* Pragma Attribute_Definition:: 864* Pragma Ast_Entry:: 865* Pragma C_Pass_By_Copy:: 866* Pragma Check:: 867* Pragma Check_Float_Overflow:: 868* Pragma Check_Name:: 869* Pragma Check_Policy:: 870* Pragma Comment:: 871* Pragma Common_Object:: 872* Pragma Compile_Time_Error:: 873* Pragma Compile_Time_Warning:: 874* Pragma Compiler_Unit:: 875* Pragma Complete_Representation:: 876* Pragma Complex_Representation:: 877* Pragma Component_Alignment:: 878* Pragma Contract_Case:: 879* Pragma Convention_Identifier:: 880* Pragma CPP_Class:: 881* Pragma CPP_Constructor:: 882* Pragma CPP_Virtual:: 883* Pragma CPP_Vtable:: 884* Pragma CPU:: 885* Pragma Debug:: 886* Pragma Debug_Policy:: 887* Pragma Default_Storage_Pool:: 888* Pragma Detect_Blocking:: 889* Pragma Dispatching_Domain:: 890* Pragma Elaboration_Checks:: 891* Pragma Eliminate:: 892* Pragma Export_Exception:: 893* Pragma Export_Function:: 894* Pragma Export_Object:: 895* Pragma Export_Procedure:: 896* Pragma Export_Value:: 897* Pragma Export_Valued_Procedure:: 898* Pragma Extend_System:: 899* Pragma Extensions_Allowed:: 900* Pragma External:: 901* Pragma External_Name_Casing:: 902* Pragma Fast_Math:: 903* Pragma Favor_Top_Level:: 904* Pragma Finalize_Storage_Only:: 905* Pragma Float_Representation:: 906* Pragma Ident:: 907* Pragma Implementation_Defined:: 908* Pragma Implemented:: 909* Pragma Implicit_Packing:: 910* Pragma Import_Exception:: 911* Pragma Import_Function:: 912* Pragma Import_Object:: 913* Pragma Import_Procedure:: 914* Pragma Import_Valued_Procedure:: 915* Pragma Independent:: 916* Pragma Independent_Components:: 917* Pragma Initialize_Scalars:: 918* Pragma Inline_Always:: 919* Pragma Inline_Generic:: 920* Pragma Interface:: 921* Pragma Interface_Name:: 922* Pragma Interrupt_Handler:: 923* Pragma Interrupt_State:: 924* Pragma Invariant:: 925* Pragma Keep_Names:: 926* Pragma License:: 927* Pragma Link_With:: 928* Pragma Linker_Alias:: 929* Pragma Linker_Constructor:: 930* Pragma Linker_Destructor:: 931* Pragma Linker_Section:: 932* Pragma Long_Float:: 933* Pragma Loop_Optimize:: 934* Pragma Machine_Attribute:: 935* Pragma Main:: 936* Pragma Main_Storage:: 937* Pragma No_Body:: 938* Pragma No_Inline:: 939* Pragma No_Return:: 940* Pragma No_Strict_Aliasing:: 941* Pragma Normalize_Scalars:: 942* Pragma Obsolescent:: 943* Pragma Optimize_Alignment:: 944* Pragma Ordered:: 945* Pragma Overflow_Mode:: 946* Pragma Partition_Elaboration_Policy:: 947* Pragma Passive:: 948* Pragma Persistent_BSS:: 949* Pragma Polling:: 950* Pragma Postcondition:: 951* Pragma Precondition:: 952* Pragma Preelaborable_Initialization:: 953* Pragma Priority_Specific_Dispatching:: 954* Pragma Profile (Ravenscar):: 955* Pragma Profile (Restricted):: 956* Pragma Profile (Rational):: 957* Pragma Psect_Object:: 958* Pragma Pure_Function:: 959* Pragma Relative_Deadline:: 960* Pragma Remote_Access_Type:: 961* Pragma Restriction_Warnings:: 962* Pragma Shared:: 963* Pragma Short_Circuit_And_Or:: 964* Pragma Short_Descriptors:: 965* Pragma Simple_Storage_Pool_Type:: 966* Pragma Source_File_Name:: 967* Pragma Source_File_Name_Project:: 968* Pragma Source_Reference:: 969* Pragma Static_Elaboration_Desired:: 970* Pragma Stream_Convert:: 971* Pragma Style_Checks:: 972* Pragma Subtitle:: 973* Pragma Suppress:: 974* Pragma Suppress_All:: 975* Pragma Suppress_Exception_Locations:: 976* Pragma Suppress_Initialization:: 977* Pragma Task_Info:: 978* Pragma Task_Name:: 979* Pragma Task_Storage:: 980* Pragma Test_Case:: 981* Pragma Thread_Local_Storage:: 982* Pragma Time_Slice:: 983* Pragma Title:: 984* Pragma Unchecked_Union:: 985* Pragma Unimplemented_Unit:: 986* Pragma Universal_Aliasing :: 987* Pragma Universal_Data:: 988* Pragma Unmodified:: 989* Pragma Unreferenced:: 990* Pragma Unreferenced_Objects:: 991* Pragma Unreserve_All_Interrupts:: 992* Pragma Unsuppress:: 993* Pragma Use_VADS_Size:: 994* Pragma Validity_Checks:: 995* Pragma Volatile:: 996* Pragma Warnings:: 997* Pragma Weak_External:: 998* Pragma Wide_Character_Encoding:: 999@end menu 1000 1001@node Pragma Abort_Defer 1002@unnumberedsec Pragma Abort_Defer 1003@findex Abort_Defer 1004@cindex Deferring aborts 1005@noindent 1006Syntax: 1007@smallexample 1008pragma Abort_Defer; 1009@end smallexample 1010 1011@noindent 1012This pragma must appear at the start of the statement sequence of a 1013handled sequence of statements (right after the @code{begin}). It has 1014the effect of deferring aborts for the sequence of statements (but not 1015for the declarations or handlers, if any, associated with this statement 1016sequence). 1017 1018@node Pragma Ada_83 1019@unnumberedsec Pragma Ada_83 1020@findex Ada_83 1021@noindent 1022Syntax: 1023@smallexample @c ada 1024pragma Ada_83; 1025@end smallexample 1026 1027@noindent 1028A configuration pragma that establishes Ada 83 mode for the unit to 1029which it applies, regardless of the mode set by the command line 1030switches. In Ada 83 mode, GNAT attempts to be as compatible with 1031the syntax and semantics of Ada 83, as defined in the original Ada 103283 Reference Manual as possible. In particular, the keywords added by Ada 95 1033and Ada 2005 are not recognized, optional package bodies are allowed, 1034and generics may name types with unknown discriminants without using 1035the @code{(<>)} notation. In addition, some but not all of the additional 1036restrictions of Ada 83 are enforced. 1037 1038Ada 83 mode is intended for two purposes. Firstly, it allows existing 1039Ada 83 code to be compiled and adapted to GNAT with less effort. 1040Secondly, it aids in keeping code backwards compatible with Ada 83. 1041However, there is no guarantee that code that is processed correctly 1042by GNAT in Ada 83 mode will in fact compile and execute with an Ada 104383 compiler, since GNAT does not enforce all the additional checks 1044required by Ada 83. 1045 1046@node Pragma Ada_95 1047@unnumberedsec Pragma Ada_95 1048@findex Ada_95 1049@noindent 1050Syntax: 1051@smallexample @c ada 1052pragma Ada_95; 1053@end smallexample 1054 1055@noindent 1056A configuration pragma that establishes Ada 95 mode for the unit to which 1057it applies, regardless of the mode set by the command line switches. 1058This mode is set automatically for the @code{Ada} and @code{System} 1059packages and their children, so you need not specify it in these 1060contexts. This pragma is useful when writing a reusable component that 1061itself uses Ada 95 features, but which is intended to be usable from 1062either Ada 83 or Ada 95 programs. 1063 1064@node Pragma Ada_05 1065@unnumberedsec Pragma Ada_05 1066@findex Ada_05 1067@noindent 1068Syntax: 1069@smallexample @c ada 1070pragma Ada_05; 1071@end smallexample 1072 1073@noindent 1074A configuration pragma that establishes Ada 2005 mode for the unit to which 1075it applies, regardless of the mode set by the command line switches. 1076This pragma is useful when writing a reusable component that 1077itself uses Ada 2005 features, but which is intended to be usable from 1078either Ada 83 or Ada 95 programs. 1079 1080@node Pragma Ada_2005 1081@unnumberedsec Pragma Ada_2005 1082@findex Ada_2005 1083@noindent 1084Syntax: 1085@smallexample @c ada 1086pragma Ada_2005; 1087@end smallexample 1088 1089@noindent 1090This configuration pragma is a synonym for pragma Ada_05 and has the 1091same syntax and effect. 1092 1093@node Pragma Ada_12 1094@unnumberedsec Pragma Ada_12 1095@findex Ada_12 1096@noindent 1097Syntax: 1098@smallexample @c ada 1099pragma Ada_12; 1100@end smallexample 1101 1102@noindent 1103A configuration pragma that establishes Ada 2012 mode for the unit to which 1104it applies, regardless of the mode set by the command line switches. 1105This mode is set automatically for the @code{Ada} and @code{System} 1106packages and their children, so you need not specify it in these 1107contexts. This pragma is useful when writing a reusable component that 1108itself uses Ada 2012 features, but which is intended to be usable from 1109Ada 83, Ada 95, or Ada 2005 programs. 1110 1111@node Pragma Ada_2012 1112@unnumberedsec Pragma Ada_2012 1113@findex Ada_2005 1114@noindent 1115Syntax: 1116@smallexample @c ada 1117pragma Ada_2012; 1118@end smallexample 1119 1120@noindent 1121This configuration pragma is a synonym for pragma Ada_12 and has the 1122same syntax and effect. 1123 1124@node Pragma Annotate 1125@unnumberedsec Pragma Annotate 1126@findex Annotate 1127@noindent 1128Syntax: 1129@smallexample @c ada 1130pragma Annotate (IDENTIFIER [,IDENTIFIER @{, ARG@}]); 1131 1132ARG ::= NAME | EXPRESSION 1133@end smallexample 1134 1135@noindent 1136This pragma is used to annotate programs. @var{identifier} identifies 1137the type of annotation. GNAT verifies that it is an identifier, but does 1138not otherwise analyze it. The second optional identifier is also left 1139unanalyzed, and by convention is used to control the action of the tool to 1140which the annotation is addressed. The remaining @var{arg} arguments 1141can be either string literals or more generally expressions. 1142String literals are assumed to be either of type 1143@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} 1144depending on the character literals they contain. 1145All other kinds of arguments are analyzed as expressions, and must be 1146unambiguous. 1147 1148The analyzed pragma is retained in the tree, but not otherwise processed 1149by any part of the GNAT compiler, except to generate corresponding note 1150lines in the generated ALI file. For the format of these note lines, see 1151the compiler source file lib-writ.ads. This pragma is intended for use by 1152external tools, including ASIS@. The use of pragma Annotate does not 1153affect the compilation process in any way. This pragma may be used as 1154a configuration pragma. 1155 1156@node Pragma Assert 1157@unnumberedsec Pragma Assert 1158@findex Assert 1159@noindent 1160Syntax: 1161@smallexample @c ada 1162pragma Assert ( 1163 boolean_EXPRESSION 1164 [, string_EXPRESSION]); 1165@end smallexample 1166 1167@noindent 1168The effect of this pragma depends on whether the corresponding command 1169line switch is set to activate assertions. The pragma expands into code 1170equivalent to the following: 1171 1172@smallexample @c ada 1173if assertions-enabled then 1174 if not boolean_EXPRESSION then 1175 System.Assertions.Raise_Assert_Failure 1176 (string_EXPRESSION); 1177 end if; 1178end if; 1179@end smallexample 1180 1181@noindent 1182The string argument, if given, is the message that will be associated 1183with the exception occurrence if the exception is raised. If no second 1184argument is given, the default message is @samp{@var{file}:@var{nnn}}, 1185where @var{file} is the name of the source file containing the assert, 1186and @var{nnn} is the line number of the assert. A pragma is not a 1187statement, so if a statement sequence contains nothing but a pragma 1188assert, then a null statement is required in addition, as in: 1189 1190@smallexample @c ada 1191@dots{} 1192if J > 3 then 1193 pragma Assert (K > 3, "Bad value for K"); 1194 null; 1195end if; 1196@end smallexample 1197 1198@noindent 1199Note that, as with the @code{if} statement to which it is equivalent, the 1200type of the expression is either @code{Standard.Boolean}, or any type derived 1201from this standard type. 1202 1203If assertions are disabled (switch @option{-gnata} not used), then there 1204is no run-time effect (and in particular, any side effects from the 1205expression will not occur at run time). (The expression is still 1206analyzed at compile time, and may cause types to be frozen if they are 1207mentioned here for the first time). 1208 1209If assertions are enabled, then the given expression is tested, and if 1210it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called 1211which results in the raising of @code{Assert_Failure} with the given message. 1212 1213You should generally avoid side effects in the expression arguments of 1214this pragma, because these side effects will turn on and off with the 1215setting of the assertions mode, resulting in assertions that have an 1216effect on the program. However, the expressions are analyzed for 1217semantic correctness whether or not assertions are enabled, so turning 1218assertions on and off cannot affect the legality of a program. 1219 1220Note that the implementation defined policy @code{DISABLE}, given in a 1221pragma Assertion_Policy, can be used to suppress this semantic analysis. 1222 1223Note: this is a standard language-defined pragma in versions 1224of Ada from 2005 on. In GNAT, it is implemented in all versions 1225of Ada, and the DISABLE policy is an implementation-defined 1226addition. 1227 1228@node Pragma Assertion_Policy 1229@unnumberedsec Pragma Assertion_Policy 1230@findex Debug_Policy 1231@noindent 1232Syntax: 1233 1234@smallexample @c ada 1235pragma Assertion_Policy (CHECK | DISABLE | IGNORE); 1236@end smallexample 1237 1238@noindent 1239This is a standard Ada 2005 pragma that is available as an 1240implementation-defined pragma in earlier versions of Ada. 1241 1242If the argument is @code{CHECK}, then assertions are enabled. 1243If the argument is @code{IGNORE}, then assertions are ignored. 1244This pragma overrides the effect of the @option{-gnata} switch on the 1245command line. 1246 1247Assertions are of three kinds: 1248 1249@itemize @bullet 1250@item 1251Pragma @code{Assert}. 1252@item 1253In Ada 2012, all assertions defined in the RM as aspects: preconditions, 1254postconditions, type invariants and (sub)type predicates. 1255@item 1256Corresponding pragmas for type invariants and (sub)type predicates. 1257@end itemize 1258 1259The implementation defined policy @code{DISABLE} is like 1260@code{IGNORE} except that it completely disables semantic 1261checking of the argument to @code{pragma Assert}. This may 1262be useful when the pragma argument references subprograms 1263in a with'ed package which is replaced by a dummy package 1264for the final build. 1265 1266Note: this is a standard language-defined pragma in versions 1267of Ada from 2005 on. In GNAT, it is implemented in all versions 1268of Ada, and the DISABLE policy is an implementation-defined 1269addition. 1270 1271@node Pragma Assume_No_Invalid_Values 1272@unnumberedsec Pragma Assume_No_Invalid_Values 1273@findex Assume_No_Invalid_Values 1274@cindex Invalid representations 1275@cindex Invalid values 1276@noindent 1277Syntax: 1278@smallexample @c ada 1279pragma Assume_No_Invalid_Values (On | Off); 1280@end smallexample 1281 1282@noindent 1283This is a configuration pragma that controls the assumptions made by the 1284compiler about the occurrence of invalid representations (invalid values) 1285in the code. 1286 1287The default behavior (corresponding to an Off argument for this pragma), is 1288to assume that values may in general be invalid unless the compiler can 1289prove they are valid. Consider the following example: 1290 1291@smallexample @c ada 1292V1 : Integer range 1 .. 10; 1293V2 : Integer range 11 .. 20; 1294... 1295for J in V2 .. V1 loop 1296 ... 1297end loop; 1298@end smallexample 1299 1300@noindent 1301if V1 and V2 have valid values, then the loop is known at compile 1302time not to execute since the lower bound must be greater than the 1303upper bound. However in default mode, no such assumption is made, 1304and the loop may execute. If @code{Assume_No_Invalid_Values (On)} 1305is given, the compiler will assume that any occurrence of a variable 1306other than in an explicit @code{'Valid} test always has a valid 1307value, and the loop above will be optimized away. 1308 1309The use of @code{Assume_No_Invalid_Values (On)} is appropriate if 1310you know your code is free of uninitialized variables and other 1311possible sources of invalid representations, and may result in 1312more efficient code. A program that accesses an invalid representation 1313with this pragma in effect is erroneous, so no guarantees can be made 1314about its behavior. 1315 1316It is peculiar though permissible to use this pragma in conjunction 1317with validity checking (-gnatVa). In such cases, accessing invalid 1318values will generally give an exception, though formally the program 1319is erroneous so there are no guarantees that this will always be the 1320case, and it is recommended that these two options not be used together. 1321 1322@node Pragma Ast_Entry 1323@unnumberedsec Pragma Ast_Entry 1324@cindex OpenVMS 1325@findex Ast_Entry 1326@noindent 1327Syntax: 1328@smallexample @c ada 1329pragma AST_Entry (entry_IDENTIFIER); 1330@end smallexample 1331 1332@noindent 1333This pragma is implemented only in the OpenVMS implementation of GNAT@. The 1334argument is the simple name of a single entry; at most one @code{AST_Entry} 1335pragma is allowed for any given entry. This pragma must be used in 1336conjunction with the @code{AST_Entry} attribute, and is only allowed after 1337the entry declaration and in the same task type specification or single task 1338as the entry to which it applies. This pragma specifies that the given entry 1339may be used to handle an OpenVMS asynchronous system trap (@code{AST}) 1340resulting from an OpenVMS system service call. The pragma does not affect 1341normal use of the entry. For further details on this pragma, see the 1342DEC Ada Language Reference Manual, section 9.12a. 1343 1344@node Pragma Attribute_Definition 1345@unnumberedsec Pragma Attribute_Definition 1346@findex Attribute_Definition 1347@noindent 1348Syntax: 1349@smallexample @c ada 1350pragma Attribute_Definition 1351 ([Attribute =>] ATTRIBUTE_DESIGNATOR, 1352 [Entity =>] LOCAL_NAME, 1353 [Expression =>] EXPRESSION | NAME); 1354@end smallexample 1355 1356@noindent 1357If @code{Attribute} is a known attribute name, this pragma is equivalent to 1358the attribute definition clause: 1359 1360@smallexample @c ada 1361 for Entity'Attribute use Expression; 1362@end smallexample 1363 1364If @code{Attribute} is not a recognized attribute name, the pragma is 1365ignored, and a warning is emitted. This allows source 1366code to be written that takes advantage of some new attribute, while remaining 1367compilable with earlier compilers. 1368 1369@node Pragma C_Pass_By_Copy 1370@unnumberedsec Pragma C_Pass_By_Copy 1371@cindex Passing by copy 1372@findex C_Pass_By_Copy 1373@noindent 1374Syntax: 1375@smallexample @c ada 1376pragma C_Pass_By_Copy 1377 ([Max_Size =>] static_integer_EXPRESSION); 1378@end smallexample 1379 1380@noindent 1381Normally the default mechanism for passing C convention records to C 1382convention subprograms is to pass them by reference, as suggested by RM 1383B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change 1384this default, by requiring that record formal parameters be passed by 1385copy if all of the following conditions are met: 1386 1387@itemize @bullet 1388@item 1389The size of the record type does not exceed the value specified for 1390@code{Max_Size}. 1391@item 1392The record type has @code{Convention C}. 1393@item 1394The formal parameter has this record type, and the subprogram has a 1395foreign (non-Ada) convention. 1396@end itemize 1397 1398@noindent 1399If these conditions are met the argument is passed by copy, i.e.@: in a 1400manner consistent with what C expects if the corresponding formal in the 1401C prototype is a struct (rather than a pointer to a struct). 1402 1403You can also pass records by copy by specifying the convention 1404@code{C_Pass_By_Copy} for the record type, or by using the extended 1405@code{Import} and @code{Export} pragmas, which allow specification of 1406passing mechanisms on a parameter by parameter basis. 1407 1408@node Pragma Check 1409@unnumberedsec Pragma Check 1410@cindex Assertions 1411@cindex Named assertions 1412@findex Check 1413@noindent 1414Syntax: 1415@smallexample @c ada 1416pragma Check ( 1417 [Name =>] Identifier, 1418 [Check =>] Boolean_EXPRESSION 1419 [, [Message =>] string_EXPRESSION] ); 1420@end smallexample 1421 1422@noindent 1423This pragma is similar to the predefined pragma @code{Assert} except that an 1424extra identifier argument is present. In conjunction with pragma 1425@code{Check_Policy}, this can be used to define groups of assertions that can 1426be independently controlled. The identifier @code{Assertion} is special, it 1427refers to the normal set of pragma @code{Assert} statements. The identifiers 1428@code{Precondition} and @code{Postcondition} correspond to the pragmas of these 1429names, so these three names would normally not be used directly in a pragma 1430@code{Check}. 1431 1432Checks introduced by this pragma are normally deactivated by default. They can 1433be activated either by the command line option @option{-gnata}, which turns on 1434all checks, or individually controlled using pragma @code{Check_Policy}. 1435 1436@node Pragma Check_Float_Overflow 1437@unnumberedsec Pragma Check_Float_Overflow 1438@cindex Floating-point overflow 1439@findex Check_Float_Overflow 1440@noindent 1441Syntax: 1442@smallexample @c ada 1443pragma Check_Float_Overflow; 1444@end smallexample 1445 1446@noindent 1447In Ada, the predefined floating-point types (@code{Short_Float}, 1448@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are 1449defined to be @emph{unconstrained}. This means that even though each 1450has a well-defined base range, an operation that delivers a result 1451outside this base range is not required to raise an exception. 1452This implementation permission accommodates the notion 1453of infinities in IEEE floating-point, and corresponds to the 1454efficient execution mode on most machines. GNAT will not raise 1455overflow exceptions on these machines; instead it will generate 1456infinities and NaN's as defined in the IEEE standard. 1457 1458Generating infinities, although efficient, is not always desirable. 1459Often the preferable approach is to check for overflow, even at the 1460(perhaps considerable) expense of run-time performance. 1461This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit 1462range constraints -- and indeed such a subtype 1463can have the same base range as its base type. For example: 1464 1465@smallexample @c ada 1466subtype My_Float is Float range Float'Range; 1467@end smallexample 1468 1469@noindent 1470Here @code{My_Float} has the same range as 1471@code{Float} but is constrained, so operations on 1472@code{My_Float} values will be checked for overflow 1473against this range. 1474 1475This style will achieve the desired goal, but 1476it is often more convenient to be able to simply use 1477the standard predefined floating-point types as long 1478as overflow checking could be guaranteed. 1479The @code{Check_Float_Overflow} 1480configuration pragma achieves this effect. If a unit is compiled 1481subject to this configuration pragma, then all operations 1482on predefined floating-point types will be treated as 1483though those types were constrained, and overflow checks 1484will be generated. The @code{Constraint_Error} 1485exception is raised if the result is out of range. 1486 1487This mode can also be set by use of the compiler 1488switch @option{-gnateF}. 1489 1490@node Pragma Check_Name 1491@unnumberedsec Pragma Check_Name 1492@cindex Defining check names 1493@cindex Check names, defining 1494@findex Check_Name 1495@noindent 1496Syntax: 1497@smallexample @c ada 1498pragma Check_Name (check_name_IDENTIFIER); 1499@end smallexample 1500 1501@noindent 1502This is a configuration pragma that defines a new implementation 1503defined check name (unless IDENTIFIER matches one of the predefined 1504check names, in which case the pragma has no effect). Check names 1505are global to a partition, so if two or more configuration pragmas 1506are present in a partition mentioning the same name, only one new 1507check name is introduced. 1508 1509An implementation defined check name introduced with this pragma may 1510be used in only three contexts: @code{pragma Suppress}, 1511@code{pragma Unsuppress}, 1512and as the prefix of a @code{Check_Name'Enabled} attribute reference. For 1513any of these three cases, the check name must be visible. A check 1514name is visible if it is in the configuration pragmas applying to 1515the current unit, or if it appears at the start of any unit that 1516is part of the dependency set of the current unit (e.g., units that 1517are mentioned in @code{with} clauses). 1518 1519@node Pragma Check_Policy 1520@unnumberedsec Pragma Check_Policy 1521@cindex Controlling assertions 1522@cindex Assertions, control 1523@cindex Check pragma control 1524@cindex Named assertions 1525@findex Check 1526@noindent 1527Syntax: 1528@smallexample @c ada 1529pragma Check_Policy 1530 ([Name =>] Identifier, 1531 [Policy =>] POLICY_IDENTIFIER); 1532 1533POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE 1534@end smallexample 1535 1536@noindent 1537This pragma is similar to the predefined pragma @code{Assertion_Policy}, 1538except that it controls sets of named assertions introduced using the 1539@code{Check} pragmas. It can be used as a configuration pragma or (unlike 1540@code{Assertion_Policy}) can be used within a declarative part, in which case 1541it controls the status to the end of the corresponding construct (in a manner 1542identical to pragma @code{Suppress)}. 1543 1544The identifier given as the first argument corresponds to a name used in 1545associated @code{Check} pragmas. For example, if the pragma: 1546 1547@smallexample @c ada 1548pragma Check_Policy (Critical_Error, OFF); 1549@end smallexample 1550 1551@noindent 1552is given, then subsequent @code{Check} pragmas whose first argument is also 1553@code{Critical_Error} will be disabled. The special identifier @code{Assertion} 1554controls the behavior of normal assertions (thus a pragma 1555@code{Check_Policy} with this identifier is similar to the normal 1556@code{Assertion_Policy} pragma except that it can appear within a 1557declarative part). 1558 1559The special identifiers @code{Precondition} and @code{Postcondition} control 1560the status of preconditions and postconditions given as pragmas. 1561If a @code{Precondition} pragma 1562is encountered, it is ignored if turned off by a @code{Check_Policy} specifying 1563that @code{Precondition} checks are @code{Off} or @code{Ignored}. Similarly use 1564of the name @code{Postcondition} controls whether @code{Postcondition} pragmas 1565are recognized. Note that preconditions and postconditions given as aspects 1566are controlled differently, either by the @code{Assertion_Policy} pragma or 1567by the @code{Check_Policy} pragma with identifier @code{Assertion}. 1568 1569The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} 1570to turn on corresponding checks. The default for a set of checks for which no 1571@code{Check_Policy} is given is @code{OFF} unless the compiler switch 1572@option{-gnata} is given, which turns on all checks by default. 1573 1574The check policy settings @code{CHECK} and @code{IGNORE} are also recognized 1575as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for 1576compatibility with the standard @code{Assertion_Policy} pragma. 1577 1578The implementation defined policy @code{DISABLE} is like 1579@code{OFF} except that it completely disables semantic 1580checking of the argument to the corresponding class of 1581pragmas. This may be useful when the pragma arguments reference 1582subprograms in a with'ed package which is replaced by a dummy package 1583for the final build. 1584 1585@node Pragma Comment 1586@unnumberedsec Pragma Comment 1587@findex Comment 1588@noindent 1589Syntax: 1590 1591@smallexample @c ada 1592pragma Comment (static_string_EXPRESSION); 1593@end smallexample 1594 1595@noindent 1596This is almost identical in effect to pragma @code{Ident}. It allows the 1597placement of a comment into the object file and hence into the 1598executable file if the operating system permits such usage. The 1599difference is that @code{Comment}, unlike @code{Ident}, has 1600no limitations on placement of the pragma (it can be placed 1601anywhere in the main source unit), and if more than one pragma 1602is used, all comments are retained. 1603 1604@node Pragma Common_Object 1605@unnumberedsec Pragma Common_Object 1606@findex Common_Object 1607@noindent 1608Syntax: 1609 1610@smallexample @c ada 1611pragma Common_Object ( 1612 [Internal =>] LOCAL_NAME 1613 [, [External =>] EXTERNAL_SYMBOL] 1614 [, [Size =>] EXTERNAL_SYMBOL] ); 1615 1616EXTERNAL_SYMBOL ::= 1617 IDENTIFIER 1618| static_string_EXPRESSION 1619@end smallexample 1620 1621@noindent 1622This pragma enables the shared use of variables stored in overlaid 1623linker areas corresponding to the use of @code{COMMON} 1624in Fortran. The single 1625object @var{LOCAL_NAME} is assigned to the area designated by 1626the @var{External} argument. 1627You may define a record to correspond to a series 1628of fields. The @var{Size} argument 1629is syntax checked in GNAT, but otherwise ignored. 1630 1631@code{Common_Object} is not supported on all platforms. If no 1632support is available, then the code generator will issue a message 1633indicating that the necessary attribute for implementation of this 1634pragma is not available. 1635 1636@node Pragma Compile_Time_Error 1637@unnumberedsec Pragma Compile_Time_Error 1638@findex Compile_Time_Error 1639@noindent 1640Syntax: 1641 1642@smallexample @c ada 1643pragma Compile_Time_Error 1644 (boolean_EXPRESSION, static_string_EXPRESSION); 1645@end smallexample 1646 1647@noindent 1648This pragma can be used to generate additional compile time 1649error messages. It 1650is particularly useful in generics, where errors can be issued for 1651specific problematic instantiations. The first parameter is a boolean 1652expression. The pragma is effective only if the value of this expression 1653is known at compile time, and has the value True. The set of expressions 1654whose values are known at compile time includes all static boolean 1655expressions, and also other values which the compiler can determine 1656at compile time (e.g., the size of a record type set by an explicit 1657size representation clause, or the value of a variable which was 1658initialized to a constant and is known not to have been modified). 1659If these conditions are met, an error message is generated using 1660the value given as the second argument. This string value may contain 1661embedded ASCII.LF characters to break the message into multiple lines. 1662 1663@node Pragma Compile_Time_Warning 1664@unnumberedsec Pragma Compile_Time_Warning 1665@findex Compile_Time_Warning 1666@noindent 1667Syntax: 1668 1669@smallexample @c ada 1670pragma Compile_Time_Warning 1671 (boolean_EXPRESSION, static_string_EXPRESSION); 1672@end smallexample 1673 1674@noindent 1675Same as pragma Compile_Time_Error, except a warning is issued instead 1676of an error message. Note that if this pragma is used in a package that 1677is with'ed by a client, the client will get the warning even though it 1678is issued by a with'ed package (normally warnings in with'ed units are 1679suppressed, but this is a special exception to that rule). 1680 1681One typical use is within a generic where compile time known characteristics 1682of formal parameters are tested, and warnings given appropriately. Another use 1683with a first parameter of True is to warn a client about use of a package, 1684for example that it is not fully implemented. 1685 1686@node Pragma Compiler_Unit 1687@unnumberedsec Pragma Compiler_Unit 1688@findex Compiler_Unit 1689@noindent 1690Syntax: 1691 1692@smallexample @c ada 1693pragma Compiler_Unit; 1694@end smallexample 1695 1696@noindent 1697This pragma is intended only for internal use in the GNAT run-time library. 1698It indicates that the unit is used as part of the compiler build. The effect 1699is to disallow constructs (raise with message, conditional expressions etc) 1700that would cause trouble when bootstrapping using an older version of GNAT. 1701For the exact list of restrictions, see the compiler sources and references 1702to Is_Compiler_Unit. 1703 1704@node Pragma Complete_Representation 1705@unnumberedsec Pragma Complete_Representation 1706@findex Complete_Representation 1707@noindent 1708Syntax: 1709 1710@smallexample @c ada 1711pragma Complete_Representation; 1712@end smallexample 1713 1714@noindent 1715This pragma must appear immediately within a record representation 1716clause. Typical placements are before the first component clause 1717or after the last component clause. The effect is to give an error 1718message if any component is missing a component clause. This pragma 1719may be used to ensure that a record representation clause is 1720complete, and that this invariant is maintained if fields are 1721added to the record in the future. 1722 1723@node Pragma Complex_Representation 1724@unnumberedsec Pragma Complex_Representation 1725@findex Complex_Representation 1726@noindent 1727Syntax: 1728 1729@smallexample @c ada 1730pragma Complex_Representation 1731 ([Entity =>] LOCAL_NAME); 1732@end smallexample 1733 1734@noindent 1735The @var{Entity} argument must be the name of a record type which has 1736two fields of the same floating-point type. The effect of this pragma is 1737to force gcc to use the special internal complex representation form for 1738this record, which may be more efficient. Note that this may result in 1739the code for this type not conforming to standard ABI (application 1740binary interface) requirements for the handling of record types. For 1741example, in some environments, there is a requirement for passing 1742records by pointer, and the use of this pragma may result in passing 1743this type in floating-point registers. 1744 1745@node Pragma Component_Alignment 1746@unnumberedsec Pragma Component_Alignment 1747@cindex Alignments of components 1748@findex Component_Alignment 1749@noindent 1750Syntax: 1751 1752@smallexample @c ada 1753pragma Component_Alignment ( 1754 [Form =>] ALIGNMENT_CHOICE 1755 [, [Name =>] type_LOCAL_NAME]); 1756 1757ALIGNMENT_CHOICE ::= 1758 Component_Size 1759| Component_Size_4 1760| Storage_Unit 1761| Default 1762@end smallexample 1763 1764@noindent 1765Specifies the alignment of components in array or record types. 1766The meaning of the @var{Form} argument is as follows: 1767 1768@table @code 1769@findex Component_Size 1770@item Component_Size 1771Aligns scalar components and subcomponents of the array or record type 1772on boundaries appropriate to their inherent size (naturally 1773aligned). For example, 1-byte components are aligned on byte boundaries, 17742-byte integer components are aligned on 2-byte boundaries, 4-byte 1775integer components are aligned on 4-byte boundaries and so on. These 1776alignment rules correspond to the normal rules for C compilers on all 1777machines except the VAX@. 1778 1779@findex Component_Size_4 1780@item Component_Size_4 1781Naturally aligns components with a size of four or fewer 1782bytes. Components that are larger than 4 bytes are placed on the next 17834-byte boundary. 1784 1785@findex Storage_Unit 1786@item Storage_Unit 1787Specifies that array or record components are byte aligned, i.e.@: 1788aligned on boundaries determined by the value of the constant 1789@code{System.Storage_Unit}. 1790 1791@cindex OpenVMS 1792@item Default 1793Specifies that array or record components are aligned on default 1794boundaries, appropriate to the underlying hardware or operating system or 1795both. For OpenVMS VAX systems, the @code{Default} choice is the same as 1796the @code{Storage_Unit} choice (byte alignment). For all other systems, 1797the @code{Default} choice is the same as @code{Component_Size} (natural 1798alignment). 1799@end table 1800 1801@noindent 1802If the @code{Name} parameter is present, @var{type_LOCAL_NAME} must 1803refer to a local record or array type, and the specified alignment 1804choice applies to the specified type. The use of 1805@code{Component_Alignment} together with a pragma @code{Pack} causes the 1806@code{Component_Alignment} pragma to be ignored. The use of 1807@code{Component_Alignment} together with a record representation clause 1808is only effective for fields not specified by the representation clause. 1809 1810If the @code{Name} parameter is absent, the pragma can be used as either 1811a configuration pragma, in which case it applies to one or more units in 1812accordance with the normal rules for configuration pragmas, or it can be 1813used within a declarative part, in which case it applies to types that 1814are declared within this declarative part, or within any nested scope 1815within this declarative part. In either case it specifies the alignment 1816to be applied to any record or array type which has otherwise standard 1817representation. 1818 1819If the alignment for a record or array type is not specified (using 1820pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep 1821clause), the GNAT uses the default alignment as described previously. 1822 1823@node Pragma Contract_Case 1824@unnumberedsec Pragma Contract_Case 1825@cindex Contract cases 1826@findex Contract_Case 1827@noindent 1828Syntax: 1829 1830@smallexample @c ada 1831pragma Contract_Case ( 1832 [Name =>] static_string_Expression 1833 ,[Mode =>] (Nominal | Robustness) 1834 [, Requires => Boolean_Expression] 1835 [, Ensures => Boolean_Expression]); 1836@end smallexample 1837 1838@noindent 1839The @code{Contract_Case} pragma allows defining fine-grain specifications 1840that can complement or replace the contract given by a precondition and a 1841postcondition. Additionally, the @code{Contract_Case} pragma can be used 1842by testing and formal verification tools. The compiler checks its validity and, 1843depending on the assertion policy at the point of declaration of the pragma, 1844it may insert a check in the executable. For code generation, the contract 1845case 1846 1847@smallexample @c ada 1848pragma Contract_Case ( 1849 Name => ... 1850 Mode => ... 1851 Requires => R, 1852 Ensures => E); 1853@end smallexample 1854 1855@noindent 1856is equivalent to 1857 1858@smallexample @c ada 1859pragma Postcondition (not R'Old or else E); 1860@end smallexample 1861 1862@noindent 1863which is also equivalent to (in Ada 2012) 1864 1865@smallexample @c ada 1866pragma Postcondition (if R'Old then E); 1867@end smallexample 1868 1869@noindent 1870expressing that, whenever condition @code{R} is satisfied on entry to the 1871subprogram, condition @code{E} should be fulfilled on exit to the subprogram. 1872 1873A precondition @code{P} and postcondition @code{Q} can also be 1874expressed as contract cases: 1875 1876@smallexample @c ada 1877pragma Contract_Case ( 1878 Name => "Replace precondition", 1879 Mode => Nominal, 1880 Requires => not P, 1881 Ensures => False); 1882pragma Contract_Case ( 1883 Name => "Replace postcondition", 1884 Mode => Nominal, 1885 Requires => P, 1886 Ensures => Q); 1887@end smallexample 1888 1889@code{Contract_Case} pragmas may only appear immediately following the 1890(separate) declaration of a subprogram in a package declaration, inside 1891a package spec unit. Only other pragmas may intervene (that is appear 1892between the subprogram declaration and a contract case). 1893 1894The compiler checks that boolean expressions given in @code{Requires} and 1895@code{Ensures} are valid, where the rules for @code{Requires} are the 1896same as the rule for an expression in @code{Precondition} and the rules 1897for @code{Ensures} are the same as the rule for an expression in 1898@code{Postcondition}. In particular, attributes @code{'Old} and 1899@code{'Result} can only be used within the @code{Ensures} 1900expression. The following is an example of use within a package spec: 1901 1902@smallexample @c ada 1903package Math_Functions is 1904 ... 1905 function Sqrt (Arg : Float) return Float; 1906 pragma Contract_Case (Name => "Small argument", 1907 Mode => Nominal, 1908 Requires => Arg < 100, 1909 Ensures => Sqrt'Result < 10); 1910 ... 1911end Math_Functions; 1912@end smallexample 1913 1914@noindent 1915The meaning of a contract case is that, whenever the associated subprogram is 1916executed in a context where @code{Requires} holds, then @code{Ensures} 1917should hold when the subprogram returns. Mode @code{Nominal} indicates 1918that the input context should also satisfy the precondition of the 1919subprogram, and the output context should also satisfy its 1920postcondition. More @code{Robustness} indicates that the precondition and 1921postcondition of the subprogram should be ignored for this contract case, 1922which is mostly useful when testing such a contract using a testing tool 1923that understands contract cases. 1924 1925@node Pragma Convention_Identifier 1926@unnumberedsec Pragma Convention_Identifier 1927@findex Convention_Identifier 1928@cindex Conventions, synonyms 1929@noindent 1930Syntax: 1931 1932@smallexample @c ada 1933pragma Convention_Identifier ( 1934 [Name =>] IDENTIFIER, 1935 [Convention =>] convention_IDENTIFIER); 1936@end smallexample 1937 1938@noindent 1939This pragma provides a mechanism for supplying synonyms for existing 1940convention identifiers. The @code{Name} identifier can subsequently 1941be used as a synonym for the given convention in other pragmas (including 1942for example pragma @code{Import} or another @code{Convention_Identifier} 1943pragma). As an example of the use of this, suppose you had legacy code 1944which used Fortran77 as the identifier for Fortran. Then the pragma: 1945 1946@smallexample @c ada 1947pragma Convention_Identifier (Fortran77, Fortran); 1948@end smallexample 1949 1950@noindent 1951would allow the use of the convention identifier @code{Fortran77} in 1952subsequent code, avoiding the need to modify the sources. As another 1953example, you could use this to parameterize convention requirements 1954according to systems. Suppose you needed to use @code{Stdcall} on 1955windows systems, and @code{C} on some other system, then you could 1956define a convention identifier @code{Library} and use a single 1957@code{Convention_Identifier} pragma to specify which convention 1958would be used system-wide. 1959 1960@node Pragma CPP_Class 1961@unnumberedsec Pragma CPP_Class 1962@findex CPP_Class 1963@cindex Interfacing with C++ 1964@noindent 1965Syntax: 1966 1967@smallexample @c ada 1968pragma CPP_Class ([Entity =>] LOCAL_NAME); 1969@end smallexample 1970 1971@noindent 1972The argument denotes an entity in the current declarative region that is 1973declared as a record type. It indicates that the type corresponds to an 1974externally declared C++ class type, and is to be laid out the same way 1975that C++ would lay out the type. If the C++ class has virtual primitives 1976then the record must be declared as a tagged record type. 1977 1978Types for which @code{CPP_Class} is specified do not have assignment or 1979equality operators defined (such operations can be imported or declared 1980as subprograms as required). Initialization is allowed only by constructor 1981functions (see pragma @code{CPP_Constructor}). Such types are implicitly 1982limited if not explicitly declared as limited or derived from a limited 1983type, and an error is issued in that case. 1984 1985See @ref{Interfacing to C++} for related information. 1986 1987Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 1988for backward compatibility but its functionality is available 1989using pragma @code{Import} with @code{Convention} = @code{CPP}. 1990 1991@node Pragma CPP_Constructor 1992@unnumberedsec Pragma CPP_Constructor 1993@cindex Interfacing with C++ 1994@findex CPP_Constructor 1995@noindent 1996Syntax: 1997 1998@smallexample @c ada 1999pragma CPP_Constructor ([Entity =>] LOCAL_NAME 2000 [, [External_Name =>] static_string_EXPRESSION ] 2001 [, [Link_Name =>] static_string_EXPRESSION ]); 2002@end smallexample 2003 2004@noindent 2005This pragma identifies an imported function (imported in the usual way 2006with pragma @code{Import}) as corresponding to a C++ constructor. If 2007@code{External_Name} and @code{Link_Name} are not specified then the 2008@code{Entity} argument is a name that must have been previously mentioned 2009in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name 2010must be of one of the following forms: 2011 2012@itemize @bullet 2013@item 2014@code{function @var{Fname} return @var{T}} 2015 2016@itemize @bullet 2017@item 2018@code{function @var{Fname} return @var{T}'Class} 2019 2020@item 2021@code{function @var{Fname} (@dots{}) return @var{T}} 2022@end itemize 2023 2024@item 2025@code{function @var{Fname} (@dots{}) return @var{T}'Class} 2026@end itemize 2027 2028@noindent 2029where @var{T} is a limited record type imported from C++ with pragma 2030@code{Import} and @code{Convention} = @code{CPP}. 2031 2032The first two forms import the default constructor, used when an object 2033of type @var{T} is created on the Ada side with no explicit constructor. 2034The latter two forms cover all the non-default constructors of the type. 2035See the @value{EDITION} User's Guide for details. 2036 2037If no constructors are imported, it is impossible to create any objects 2038on the Ada side and the type is implicitly declared abstract. 2039 2040Pragma @code{CPP_Constructor} is intended primarily for automatic generation 2041using an automatic binding generator tool (such as the @code{-fdump-ada-spec} 2042GCC switch). 2043See @ref{Interfacing to C++} for more related information. 2044 2045Note: The use of functions returning class-wide types for constructors is 2046currently obsolete. They are supported for backward compatibility. The 2047use of functions returning the type T leave the Ada sources more clear 2048because the imported C++ constructors always return an object of type T; 2049that is, they never return an object whose type is a descendant of type T. 2050 2051@node Pragma CPP_Virtual 2052@unnumberedsec Pragma CPP_Virtual 2053@cindex Interfacing to C++ 2054@findex CPP_Virtual 2055@noindent 2056This pragma is now obsolete has has no effect because GNAT generates 2057the same object layout than the G++ compiler. 2058 2059See @ref{Interfacing to C++} for related information. 2060 2061@node Pragma CPP_Vtable 2062@unnumberedsec Pragma CPP_Vtable 2063@cindex Interfacing with C++ 2064@findex CPP_Vtable 2065@noindent 2066This pragma is now obsolete has has no effect because GNAT generates 2067the same object layout than the G++ compiler. 2068 2069See @ref{Interfacing to C++} for related information. 2070 2071@node Pragma CPU 2072@unnumberedsec Pragma CPU 2073@findex CPU 2074@noindent 2075Syntax: 2076 2077@smallexample @c ada 2078pragma CPU (EXPRESSSION); 2079@end smallexample 2080 2081@noindent 2082This pragma is standard in Ada 2012, but is available in all earlier 2083versions of Ada as an implementation-defined pragma. 2084See Ada 2012 Reference Manual for details. 2085 2086@node Pragma Debug 2087@unnumberedsec Pragma Debug 2088@findex Debug 2089@noindent 2090Syntax: 2091 2092@smallexample @c ada 2093pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); 2094 2095PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 2096 PROCEDURE_NAME 2097| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 2098@end smallexample 2099 2100@noindent 2101The procedure call argument has the syntactic form of an expression, meeting 2102the syntactic requirements for pragmas. 2103 2104If debug pragmas are not enabled or if the condition is present and evaluates 2105to False, this pragma has no effect. If debug pragmas are enabled, the 2106semantics of the pragma is exactly equivalent to the procedure call statement 2107corresponding to the argument with a terminating semicolon. Pragmas are 2108permitted in sequences of declarations, so you can use pragma @code{Debug} to 2109intersperse calls to debug procedures in the middle of declarations. Debug 2110pragmas can be enabled either by use of the command line switch @option{-gnata} 2111or by use of the configuration pragma @code{Debug_Policy}. 2112 2113@node Pragma Debug_Policy 2114@unnumberedsec Pragma Debug_Policy 2115@findex Debug_Policy 2116@noindent 2117Syntax: 2118 2119@smallexample @c ada 2120pragma Debug_Policy (CHECK | DISABLE | IGNORE); 2121@end smallexample 2122 2123@noindent 2124If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled. 2125If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored. 2126This pragma overrides the effect of the @option{-gnata} switch on the 2127command line. 2128 2129The implementation defined policy @code{DISABLE} is like 2130@code{IGNORE} except that it completely disables semantic 2131checking of the argument to @code{pragma Debug}. This may 2132be useful when the pragma argument references subprograms 2133in a with'ed package which is replaced by a dummy package 2134for the final build. 2135 2136@node Pragma Default_Storage_Pool 2137@unnumberedsec Pragma Default_Storage_Pool 2138@findex Default_Storage_Pool 2139@noindent 2140Syntax: 2141 2142@smallexample @c ada 2143pragma Default_Storage_Pool (storage_pool_NAME | null); 2144@end smallexample 2145 2146@noindent 2147This pragma is standard in Ada 2012, but is available in all earlier 2148versions of Ada as an implementation-defined pragma. 2149See Ada 2012 Reference Manual for details. 2150 2151@node Pragma Detect_Blocking 2152@unnumberedsec Pragma Detect_Blocking 2153@findex Detect_Blocking 2154@noindent 2155Syntax: 2156 2157@smallexample @c ada 2158pragma Detect_Blocking; 2159@end smallexample 2160 2161@noindent 2162This is a standard pragma in Ada 2005, that is available in all earlier 2163versions of Ada as an implementation-defined pragma. 2164 2165This is a configuration pragma that forces the detection of potentially 2166blocking operations within a protected operation, and to raise Program_Error 2167if that happens. 2168 2169@node Pragma Dispatching_Domain 2170@unnumberedsec Pragma Dispatching_Domain 2171@findex Dispatching_Domain 2172@noindent 2173Syntax: 2174 2175@smallexample @c ada 2176pragma Dispatching_Domain (EXPRESSION); 2177@end smallexample 2178 2179@noindent 2180This pragma is standard in Ada 2012, but is available in all earlier 2181versions of Ada as an implementation-defined pragma. 2182See Ada 2012 Reference Manual for details. 2183 2184@node Pragma Elaboration_Checks 2185@unnumberedsec Pragma Elaboration_Checks 2186@cindex Elaboration control 2187@findex Elaboration_Checks 2188@noindent 2189Syntax: 2190 2191@smallexample @c ada 2192pragma Elaboration_Checks (Dynamic | Static); 2193@end smallexample 2194 2195@noindent 2196This is a configuration pragma that provides control over the 2197elaboration model used by the compilation affected by the 2198pragma. If the parameter is @code{Dynamic}, 2199then the dynamic elaboration 2200model described in the Ada Reference Manual is used, as though 2201the @option{-gnatE} switch had been specified on the command 2202line. If the parameter is @code{Static}, then the default GNAT static 2203model is used. This configuration pragma overrides the setting 2204of the command line. For full details on the elaboration models 2205used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,, 2206gnat_ugn, @value{EDITION} User's Guide}. 2207 2208@node Pragma Eliminate 2209@unnumberedsec Pragma Eliminate 2210@cindex Elimination of unused subprograms 2211@findex Eliminate 2212@noindent 2213Syntax: 2214 2215@smallexample @c ada 2216pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR, 2217 [Source_Location =>] STRING_LITERAL); 2218@end smallexample 2219 2220@noindent 2221The string literal given for the source location is a string which 2222specifies the line number of the occurrence of the entity, using 2223the syntax for SOURCE_TRACE given below: 2224 2225@smallexample @c ada 2226 SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET] 2227 2228 LBRACKET ::= [ 2229 RBRACKET ::= ] 2230 2231 SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER 2232 2233 LINE_NUMBER ::= DIGIT @{DIGIT@} 2234@end smallexample 2235 2236@noindent 2237Spaces around the colon in a @code{Source_Reference} are optional. 2238 2239The @code{DEFINING_DESIGNATOR} matches the defining designator used in an 2240explicit subprogram declaration, where the @code{entity} name in this 2241designator appears on the source line specified by the source location. 2242 2243The source trace that is given as the @code{Source_Location} shall obey the 2244following rules. The @code{FILE_NAME} is the short name (with no directory 2245information) of an Ada source file, given using exactly the required syntax 2246for the underlying file system (e.g. case is important if the underlying 2247operating system is case sensitive). @code{LINE_NUMBER} gives the line 2248number of the occurrence of the @code{entity} 2249as a decimal literal without an exponent or point. If an @code{entity} is not 2250declared in a generic instantiation (this includes generic subprogram 2251instances), the source trace includes only one source reference. If an entity 2252is declared inside a generic instantiation, its source trace (when parsing 2253from left to right) starts with the source location of the declaration of the 2254entity in the generic unit and ends with the source location of the 2255instantiation (it is given in square brackets). This approach is recursively 2256used in case of nested instantiations: the rightmost (nested most deeply in 2257square brackets) element of the source trace is the location of the outermost 2258instantiation, the next to left element is the location of the next (first 2259nested) instantiation in the code of the corresponding generic unit, and so 2260on, and the leftmost element (that is out of any square brackets) is the 2261location of the declaration of the entity to eliminate in a generic unit. 2262 2263Note that the @code{Source_Location} argument specifies which of a set of 2264similarly named entities is being eliminated, dealing both with overloading, 2265and also appearence of the same entity name in different scopes. 2266 2267This pragma indicates that the given entity is not used in the program to be 2268compiled and built. The effect of the pragma is to allow the compiler to 2269eliminate the code or data associated with the named entity. Any reference to 2270an eliminated entity causes a compile-time or link-time error. 2271 2272The intention of pragma @code{Eliminate} is to allow a program to be compiled 2273in a system-independent manner, with unused entities eliminated, without 2274needing to modify the source text. Normally the required set of 2275@code{Eliminate} pragmas is constructed automatically using the gnatelim tool. 2276 2277Any source file change that removes, splits, or 2278adds lines may make the set of Eliminate pragmas invalid because their 2279@code{Source_Location} argument values may get out of date. 2280 2281Pragma @code{Eliminate} may be used where the referenced entity is a dispatching 2282operation. In this case all the subprograms to which the given operation can 2283dispatch are considered to be unused (are never called as a result of a direct 2284or a dispatching call). 2285 2286@node Pragma Export_Exception 2287@unnumberedsec Pragma Export_Exception 2288@cindex OpenVMS 2289@findex Export_Exception 2290@noindent 2291Syntax: 2292 2293@smallexample @c ada 2294pragma Export_Exception ( 2295 [Internal =>] LOCAL_NAME 2296 [, [External =>] EXTERNAL_SYMBOL] 2297 [, [Form =>] Ada | VMS] 2298 [, [Code =>] static_integer_EXPRESSION]); 2299 2300EXTERNAL_SYMBOL ::= 2301 IDENTIFIER 2302| static_string_EXPRESSION 2303@end smallexample 2304 2305@noindent 2306This pragma is implemented only in the OpenVMS implementation of GNAT@. It 2307causes the specified exception to be propagated outside of the Ada program, 2308so that it can be handled by programs written in other OpenVMS languages. 2309This pragma establishes an external name for an Ada exception and makes the 2310name available to the OpenVMS Linker as a global symbol. For further details 2311on this pragma, see the 2312DEC Ada Language Reference Manual, section 13.9a3.2. 2313 2314@node Pragma Export_Function 2315@unnumberedsec Pragma Export_Function 2316@cindex Argument passing mechanisms 2317@findex Export_Function 2318 2319@noindent 2320Syntax: 2321 2322@smallexample @c ada 2323pragma Export_Function ( 2324 [Internal =>] LOCAL_NAME 2325 [, [External =>] EXTERNAL_SYMBOL] 2326 [, [Parameter_Types =>] PARAMETER_TYPES] 2327 [, [Result_Type =>] result_SUBTYPE_MARK] 2328 [, [Mechanism =>] MECHANISM] 2329 [, [Result_Mechanism =>] MECHANISM_NAME]); 2330 2331EXTERNAL_SYMBOL ::= 2332 IDENTIFIER 2333| static_string_EXPRESSION 2334| "" 2335 2336PARAMETER_TYPES ::= 2337 null 2338| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 2339 2340TYPE_DESIGNATOR ::= 2341 subtype_NAME 2342| subtype_Name ' Access 2343 2344MECHANISM ::= 2345 MECHANISM_NAME 2346| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 2347 2348MECHANISM_ASSOCIATION ::= 2349 [formal_parameter_NAME =>] MECHANISM_NAME 2350 2351MECHANISM_NAME ::= 2352 Value 2353| Reference 2354| Descriptor [([Class =>] CLASS_NAME)] 2355| Short_Descriptor [([Class =>] CLASS_NAME)] 2356 2357CLASS_NAME ::= ubs | ubsb | uba | s | sb | a 2358@end smallexample 2359 2360@noindent 2361Use this pragma to make a function externally callable and optionally 2362provide information on mechanisms to be used for passing parameter and 2363result values. We recommend, for the purposes of improving portability, 2364this pragma always be used in conjunction with a separate pragma 2365@code{Export}, which must precede the pragma @code{Export_Function}. 2366GNAT does not require a separate pragma @code{Export}, but if none is 2367present, @code{Convention Ada} is assumed, which is usually 2368not what is wanted, so it is usually appropriate to use this 2369pragma in conjunction with a @code{Export} or @code{Convention} 2370pragma that specifies the desired foreign convention. 2371Pragma @code{Export_Function} 2372(and @code{Export}, if present) must appear in the same declarative 2373region as the function to which they apply. 2374 2375@var{internal_name} must uniquely designate the function to which the 2376pragma applies. If more than one function name exists of this name in 2377the declarative part you must use the @code{Parameter_Types} and 2378@code{Result_Type} parameters is mandatory to achieve the required 2379unique designation. @var{subtype_mark}s in these parameters must 2380exactly match the subtypes in the corresponding function specification, 2381using positional notation to match parameters with subtype marks. 2382The form with an @code{'Access} attribute can be used to match an 2383anonymous access parameter. 2384 2385@cindex OpenVMS 2386@cindex Passing by descriptor 2387Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 2388The default behavior for Export_Function is to accept either 64bit or 238932bit descriptors unless short_descriptor is specified, then only 32bit 2390descriptors are accepted. 2391 2392@cindex Suppressing external name 2393Special treatment is given if the EXTERNAL is an explicit null 2394string or a static string expressions that evaluates to the null 2395string. In this case, no external name is generated. This form 2396still allows the specification of parameter mechanisms. 2397 2398@node Pragma Export_Object 2399@unnumberedsec Pragma Export_Object 2400@findex Export_Object 2401@noindent 2402Syntax: 2403 2404@smallexample @c ada 2405pragma Export_Object 2406 [Internal =>] LOCAL_NAME 2407 [, [External =>] EXTERNAL_SYMBOL] 2408 [, [Size =>] EXTERNAL_SYMBOL] 2409 2410EXTERNAL_SYMBOL ::= 2411 IDENTIFIER 2412| static_string_EXPRESSION 2413@end smallexample 2414 2415@noindent 2416This pragma designates an object as exported, and apart from the 2417extended rules for external symbols, is identical in effect to the use of 2418the normal @code{Export} pragma applied to an object. You may use a 2419separate Export pragma (and you probably should from the point of view 2420of portability), but it is not required. @var{Size} is syntax checked, 2421but otherwise ignored by GNAT@. 2422 2423@node Pragma Export_Procedure 2424@unnumberedsec Pragma Export_Procedure 2425@findex Export_Procedure 2426@noindent 2427Syntax: 2428 2429@smallexample @c ada 2430pragma Export_Procedure ( 2431 [Internal =>] LOCAL_NAME 2432 [, [External =>] EXTERNAL_SYMBOL] 2433 [, [Parameter_Types =>] PARAMETER_TYPES] 2434 [, [Mechanism =>] MECHANISM]); 2435 2436EXTERNAL_SYMBOL ::= 2437 IDENTIFIER 2438| static_string_EXPRESSION 2439| "" 2440 2441PARAMETER_TYPES ::= 2442 null 2443| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 2444 2445TYPE_DESIGNATOR ::= 2446 subtype_NAME 2447| subtype_Name ' Access 2448 2449MECHANISM ::= 2450 MECHANISM_NAME 2451| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 2452 2453MECHANISM_ASSOCIATION ::= 2454 [formal_parameter_NAME =>] MECHANISM_NAME 2455 2456MECHANISM_NAME ::= 2457 Value 2458| Reference 2459| Descriptor [([Class =>] CLASS_NAME)] 2460| Short_Descriptor [([Class =>] CLASS_NAME)] 2461 2462CLASS_NAME ::= ubs | ubsb | uba | s | sb | a 2463@end smallexample 2464 2465@noindent 2466This pragma is identical to @code{Export_Function} except that it 2467applies to a procedure rather than a function and the parameters 2468@code{Result_Type} and @code{Result_Mechanism} are not permitted. 2469GNAT does not require a separate pragma @code{Export}, but if none is 2470present, @code{Convention Ada} is assumed, which is usually 2471not what is wanted, so it is usually appropriate to use this 2472pragma in conjunction with a @code{Export} or @code{Convention} 2473pragma that specifies the desired foreign convention. 2474 2475@cindex OpenVMS 2476@cindex Passing by descriptor 2477Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 2478The default behavior for Export_Procedure is to accept either 64bit or 247932bit descriptors unless short_descriptor is specified, then only 32bit 2480descriptors are accepted. 2481 2482@cindex Suppressing external name 2483Special treatment is given if the EXTERNAL is an explicit null 2484string or a static string expressions that evaluates to the null 2485string. In this case, no external name is generated. This form 2486still allows the specification of parameter mechanisms. 2487 2488@node Pragma Export_Value 2489@unnumberedsec Pragma Export_Value 2490@findex Export_Value 2491@noindent 2492Syntax: 2493 2494@smallexample @c ada 2495pragma Export_Value ( 2496 [Value =>] static_integer_EXPRESSION, 2497 [Link_Name =>] static_string_EXPRESSION); 2498@end smallexample 2499 2500@noindent 2501This pragma serves to export a static integer value for external use. 2502The first argument specifies the value to be exported. The Link_Name 2503argument specifies the symbolic name to be associated with the integer 2504value. This pragma is useful for defining a named static value in Ada 2505that can be referenced in assembly language units to be linked with 2506the application. This pragma is currently supported only for the 2507AAMP target and is ignored for other targets. 2508 2509@node Pragma Export_Valued_Procedure 2510@unnumberedsec Pragma Export_Valued_Procedure 2511@findex Export_Valued_Procedure 2512@noindent 2513Syntax: 2514 2515@smallexample @c ada 2516pragma Export_Valued_Procedure ( 2517 [Internal =>] LOCAL_NAME 2518 [, [External =>] EXTERNAL_SYMBOL] 2519 [, [Parameter_Types =>] PARAMETER_TYPES] 2520 [, [Mechanism =>] MECHANISM]); 2521 2522EXTERNAL_SYMBOL ::= 2523 IDENTIFIER 2524| static_string_EXPRESSION 2525| "" 2526 2527PARAMETER_TYPES ::= 2528 null 2529| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 2530 2531TYPE_DESIGNATOR ::= 2532 subtype_NAME 2533| subtype_Name ' Access 2534 2535MECHANISM ::= 2536 MECHANISM_NAME 2537| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 2538 2539MECHANISM_ASSOCIATION ::= 2540 [formal_parameter_NAME =>] MECHANISM_NAME 2541 2542MECHANISM_NAME ::= 2543 Value 2544| Reference 2545| Descriptor [([Class =>] CLASS_NAME)] 2546| Short_Descriptor [([Class =>] CLASS_NAME)] 2547 2548CLASS_NAME ::= ubs | ubsb | uba | s | sb | a 2549@end smallexample 2550 2551@noindent 2552This pragma is identical to @code{Export_Procedure} except that the 2553first parameter of @var{LOCAL_NAME}, which must be present, must be of 2554mode @code{OUT}, and externally the subprogram is treated as a function 2555with this parameter as the result of the function. GNAT provides for 2556this capability to allow the use of @code{OUT} and @code{IN OUT} 2557parameters in interfacing to external functions (which are not permitted 2558in Ada functions). 2559GNAT does not require a separate pragma @code{Export}, but if none is 2560present, @code{Convention Ada} is assumed, which is almost certainly 2561not what is wanted since the whole point of this pragma is to interface 2562with foreign language functions, so it is usually appropriate to use this 2563pragma in conjunction with a @code{Export} or @code{Convention} 2564pragma that specifies the desired foreign convention. 2565 2566@cindex OpenVMS 2567@cindex Passing by descriptor 2568Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 2569The default behavior for Export_Valued_Procedure is to accept either 64bit or 257032bit descriptors unless short_descriptor is specified, then only 32bit 2571descriptors are accepted. 2572 2573@cindex Suppressing external name 2574Special treatment is given if the EXTERNAL is an explicit null 2575string or a static string expressions that evaluates to the null 2576string. In this case, no external name is generated. This form 2577still allows the specification of parameter mechanisms. 2578 2579@node Pragma Extend_System 2580@unnumberedsec Pragma Extend_System 2581@cindex @code{system}, extending 2582@cindex Dec Ada 83 2583@findex Extend_System 2584@noindent 2585Syntax: 2586 2587@smallexample @c ada 2588pragma Extend_System ([Name =>] IDENTIFIER); 2589@end smallexample 2590 2591@noindent 2592This pragma is used to provide backwards compatibility with other 2593implementations that extend the facilities of package @code{System}. In 2594GNAT, @code{System} contains only the definitions that are present in 2595the Ada RM@. However, other implementations, notably the DEC Ada 83 2596implementation, provide many extensions to package @code{System}. 2597 2598For each such implementation accommodated by this pragma, GNAT provides a 2599package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83 2600implementation, which provides the required additional definitions. You 2601can use this package in two ways. You can @code{with} it in the normal 2602way and access entities either by selection or using a @code{use} 2603clause. In this case no special processing is required. 2604 2605However, if existing code contains references such as 2606@code{System.@var{xxx}} where @var{xxx} is an entity in the extended 2607definitions provided in package @code{System}, you may use this pragma 2608to extend visibility in @code{System} in a non-standard way that 2609provides greater compatibility with the existing code. Pragma 2610@code{Extend_System} is a configuration pragma whose single argument is 2611the name of the package containing the extended definition 2612(e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under 2613control of this pragma will be processed using special visibility 2614processing that looks in package @code{System.Aux_@var{xxx}} where 2615@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in 2616package @code{System}, but not found in package @code{System}. 2617 2618You can use this pragma either to access a predefined @code{System} 2619extension supplied with the compiler, for example @code{Aux_DEC} or 2620you can construct your own extension unit following the above 2621definition. Note that such a package is a child of @code{System} 2622and thus is considered part of the implementation. To compile 2623it you will have to use the appropriate switch for compiling 2624system units. 2625@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn, @value{EDITION} User's Guide}, 2626for details. 2627 2628@node Pragma Extensions_Allowed 2629@unnumberedsec Pragma Extensions_Allowed 2630@cindex Ada Extensions 2631@cindex GNAT Extensions 2632@findex Extensions_Allowed 2633@noindent 2634Syntax: 2635 2636@smallexample @c ada 2637pragma Extensions_Allowed (On | Off); 2638@end smallexample 2639 2640@noindent 2641This configuration pragma enables or disables the implementation 2642extension mode (the use of Off as a parameter cancels the effect 2643of the @option{-gnatX} command switch). 2644 2645In extension mode, the latest version of the Ada language is 2646implemented (currently Ada 2012), and in addition a small number 2647of GNAT specific extensions are recognized as follows: 2648 2649@table @asis 2650@item Constrained attribute for generic objects 2651The @code{Constrained} attribute is permitted for objects of 2652generic types. The result indicates if the corresponding actual 2653is constrained. 2654 2655@end table 2656 2657@node Pragma External 2658@unnumberedsec Pragma External 2659@findex External 2660@noindent 2661Syntax: 2662 2663@smallexample @c ada 2664pragma External ( 2665 [ Convention =>] convention_IDENTIFIER, 2666 [ Entity =>] LOCAL_NAME 2667 [, [External_Name =>] static_string_EXPRESSION ] 2668 [, [Link_Name =>] static_string_EXPRESSION ]); 2669@end smallexample 2670 2671@noindent 2672This pragma is identical in syntax and semantics to pragma 2673@code{Export} as defined in the Ada Reference Manual. It is 2674provided for compatibility with some Ada 83 compilers that 2675used this pragma for exactly the same purposes as pragma 2676@code{Export} before the latter was standardized. 2677 2678@node Pragma External_Name_Casing 2679@unnumberedsec Pragma External_Name_Casing 2680@cindex Dec Ada 83 casing compatibility 2681@cindex External Names, casing 2682@cindex Casing of External names 2683@findex External_Name_Casing 2684@noindent 2685Syntax: 2686 2687@smallexample @c ada 2688pragma External_Name_Casing ( 2689 Uppercase | Lowercase 2690 [, Uppercase | Lowercase | As_Is]); 2691@end smallexample 2692 2693@noindent 2694This pragma provides control over the casing of external names associated 2695with Import and Export pragmas. There are two cases to consider: 2696 2697@table @asis 2698@item Implicit external names 2699Implicit external names are derived from identifiers. The most common case 2700arises when a standard Ada Import or Export pragma is used with only two 2701arguments, as in: 2702 2703@smallexample @c ada 2704 pragma Import (C, C_Routine); 2705@end smallexample 2706 2707@noindent 2708Since Ada is a case-insensitive language, the spelling of the identifier in 2709the Ada source program does not provide any information on the desired 2710casing of the external name, and so a convention is needed. In GNAT the 2711default treatment is that such names are converted to all lower case 2712letters. This corresponds to the normal C style in many environments. 2713The first argument of pragma @code{External_Name_Casing} can be used to 2714control this treatment. If @code{Uppercase} is specified, then the name 2715will be forced to all uppercase letters. If @code{Lowercase} is specified, 2716then the normal default of all lower case letters will be used. 2717 2718This same implicit treatment is also used in the case of extended DEC Ada 83 2719compatible Import and Export pragmas where an external name is explicitly 2720specified using an identifier rather than a string. 2721 2722@item Explicit external names 2723Explicit external names are given as string literals. The most common case 2724arises when a standard Ada Import or Export pragma is used with three 2725arguments, as in: 2726 2727@smallexample @c ada 2728pragma Import (C, C_Routine, "C_routine"); 2729@end smallexample 2730 2731@noindent 2732In this case, the string literal normally provides the exact casing required 2733for the external name. The second argument of pragma 2734@code{External_Name_Casing} may be used to modify this behavior. 2735If @code{Uppercase} is specified, then the name 2736will be forced to all uppercase letters. If @code{Lowercase} is specified, 2737then the name will be forced to all lowercase letters. A specification of 2738@code{As_Is} provides the normal default behavior in which the casing is 2739taken from the string provided. 2740@end table 2741 2742@noindent 2743This pragma may appear anywhere that a pragma is valid. In particular, it 2744can be used as a configuration pragma in the @file{gnat.adc} file, in which 2745case it applies to all subsequent compilations, or it can be used as a program 2746unit pragma, in which case it only applies to the current unit, or it can 2747be used more locally to control individual Import/Export pragmas. 2748 2749It is primarily intended for use with OpenVMS systems, where many 2750compilers convert all symbols to upper case by default. For interfacing to 2751such compilers (e.g.@: the DEC C compiler), it may be convenient to use 2752the pragma: 2753 2754@smallexample @c ada 2755pragma External_Name_Casing (Uppercase, Uppercase); 2756@end smallexample 2757 2758@noindent 2759to enforce the upper casing of all external symbols. 2760 2761@node Pragma Fast_Math 2762@unnumberedsec Pragma Fast_Math 2763@findex Fast_Math 2764@noindent 2765Syntax: 2766 2767@smallexample @c ada 2768pragma Fast_Math; 2769@end smallexample 2770 2771@noindent 2772This is a configuration pragma which activates a mode in which speed is 2773considered more important for floating-point operations than absolutely 2774accurate adherence to the requirements of the standard. Currently the 2775following operations are affected: 2776 2777@table @asis 2778@item Complex Multiplication 2779The normal simple formula for complex multiplication can result in intermediate 2780overflows for numbers near the end of the range. The Ada standard requires that 2781this situation be detected and corrected by scaling, but in Fast_Math mode such 2782cases will simply result in overflow. Note that to take advantage of this you 2783must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} 2784under control of the pragma, rather than use the preinstantiated versions. 2785@end table 2786 2787@node Pragma Favor_Top_Level 2788@unnumberedsec Pragma Favor_Top_Level 2789@findex Favor_Top_Level 2790@noindent 2791Syntax: 2792 2793@smallexample @c ada 2794pragma Favor_Top_Level (type_NAME); 2795@end smallexample 2796 2797@noindent 2798The named type must be an access-to-subprogram type. This pragma is an 2799efficiency hint to the compiler, regarding the use of 'Access or 2800'Unrestricted_Access on nested (non-library-level) subprograms. The 2801pragma means that nested subprograms are not used with this type, or 2802are rare, so that the generated code should be efficient in the 2803top-level case. When this pragma is used, dynamically generated 2804trampolines may be used on some targets for nested subprograms. 2805See also the No_Implicit_Dynamic_Code restriction. 2806 2807@node Pragma Finalize_Storage_Only 2808@unnumberedsec Pragma Finalize_Storage_Only 2809@findex Finalize_Storage_Only 2810@noindent 2811Syntax: 2812 2813@smallexample @c ada 2814pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 2815@end smallexample 2816 2817@noindent 2818This pragma allows the compiler not to emit a Finalize call for objects 2819defined at the library level. This is mostly useful for types where 2820finalization is only used to deal with storage reclamation since in most 2821environments it is not necessary to reclaim memory just before terminating 2822execution, hence the name. 2823 2824@node Pragma Float_Representation 2825@unnumberedsec Pragma Float_Representation 2826@cindex OpenVMS 2827@findex Float_Representation 2828@noindent 2829Syntax: 2830 2831@smallexample @c ada 2832pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); 2833 2834FLOAT_REP ::= VAX_Float | IEEE_Float 2835@end smallexample 2836 2837@noindent 2838In the one argument form, this pragma is a configuration pragma which 2839allows control over the internal representation chosen for the predefined 2840floating point types declared in the packages @code{Standard} and 2841@code{System}. On all systems other than OpenVMS, the argument must 2842be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the 2843argument may be @code{VAX_Float} to specify the use of the VAX float 2844format for the floating-point types in Standard. This requires that 2845the standard runtime libraries be recompiled. 2846 2847The two argument form specifies the representation to be used for 2848the specified floating-point type. On all systems other than OpenVMS, 2849the argument must 2850be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the 2851argument may be @code{VAX_Float} to specify the use of the VAX float 2852format, as follows: 2853 2854@itemize @bullet 2855@item 2856For digits values up to 6, F float format will be used. 2857@item 2858For digits values from 7 to 9, D float format will be used. 2859@item 2860For digits values from 10 to 15, G float format will be used. 2861@item 2862Digits values above 15 are not allowed. 2863@end itemize 2864 2865@node Pragma Ident 2866@unnumberedsec Pragma Ident 2867@findex Ident 2868@noindent 2869Syntax: 2870 2871@smallexample @c ada 2872pragma Ident (static_string_EXPRESSION); 2873@end smallexample 2874 2875@noindent 2876This pragma provides a string identification in the generated object file, 2877if the system supports the concept of this kind of identification string. 2878This pragma is allowed only in the outermost declarative part or 2879declarative items of a compilation unit. If more than one @code{Ident} 2880pragma is given, only the last one processed is effective. 2881@cindex OpenVMS 2882On OpenVMS systems, the effect of the pragma is identical to the effect of 2883the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the 2884maximum allowed length is 31 characters, so if it is important to 2885maintain compatibility with this compiler, you should obey this length 2886limit. 2887 2888@node Pragma Implementation_Defined 2889@unnumberedsec Pragma Implementation_Defined 2890@findex Implementation_Defined 2891@noindent 2892Syntax: 2893 2894@smallexample @c ada 2895pragma Implementation_Defined (local_NAME); 2896@end smallexample 2897 2898@noindent 2899This pragma marks a previously declared entioty as implementation-defined. 2900For an overloaded entity, applies to the most recent homonym. 2901 2902@smallexample @c ada 2903pragma Implementation_Defined; 2904@end smallexample 2905 2906@noindent 2907The form with no arguments appears anywhere within a scope, most 2908typically a package spec, and indicates that all entities that are 2909defined within the package spec are Implementation_Defined. 2910 2911This pragma is used within the GNAT runtime library to identify 2912implementation-defined entities introduced in language-defined units, 2913for the purpose of implementing the No_Implementation_Identifiers 2914restriction. 2915 2916@node Pragma Implemented 2917@unnumberedsec Pragma Implemented 2918@findex Implemented 2919@noindent 2920Syntax: 2921 2922@smallexample @c ada 2923pragma Implemented (procedure_LOCAL_NAME, implementation_kind); 2924 2925implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any 2926@end smallexample 2927 2928@noindent 2929This is an Ada 2012 representation pragma which applies to protected, task 2930and synchronized interface primitives. The use of pragma Implemented provides 2931a way to impose a static requirement on the overriding operation by adhering 2932to one of the three implementation kinds: entry, protected procedure or any of 2933the above. This pragma is available in all earlier versions of Ada as an 2934implementation-defined pragma. 2935 2936@smallexample @c ada 2937type Synch_Iface is synchronized interface; 2938procedure Prim_Op (Obj : in out Iface) is abstract; 2939pragma Implemented (Prim_Op, By_Protected_Procedure); 2940 2941protected type Prot_1 is new Synch_Iface with 2942 procedure Prim_Op; -- Legal 2943end Prot_1; 2944 2945protected type Prot_2 is new Synch_Iface with 2946 entry Prim_Op; -- Illegal 2947end Prot_2; 2948 2949task type Task_Typ is new Synch_Iface with 2950 entry Prim_Op; -- Illegal 2951end Task_Typ; 2952@end smallexample 2953 2954@noindent 2955When applied to the procedure_or_entry_NAME of a requeue statement, pragma 2956Implemented determines the runtime behavior of the requeue. Implementation kind 2957By_Entry guarantees that the action of requeueing will proceed from an entry to 2958another entry. Implementation kind By_Protected_Procedure transforms the 2959requeue into a dispatching call, thus eliminating the chance of blocking. Kind 2960By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on 2961the target's overriding subprogram kind. 2962 2963@node Pragma Implicit_Packing 2964@unnumberedsec Pragma Implicit_Packing 2965@findex Implicit_Packing 2966@cindex Rational Profile 2967@noindent 2968Syntax: 2969 2970@smallexample @c ada 2971pragma Implicit_Packing; 2972@end smallexample 2973 2974@noindent 2975This is a configuration pragma that requests implicit packing for packed 2976arrays for which a size clause is given but no explicit pragma Pack or 2977specification of Component_Size is present. It also applies to records 2978where no record representation clause is present. Consider this example: 2979 2980@smallexample @c ada 2981type R is array (0 .. 7) of Boolean; 2982for R'Size use 8; 2983@end smallexample 2984 2985@noindent 2986In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause 2987does not change the layout of a composite object. So the Size clause in the 2988above example is normally rejected, since the default layout of the array uses 29898-bit components, and thus the array requires a minimum of 64 bits. 2990 2991If this declaration is compiled in a region of code covered by an occurrence 2992of the configuration pragma Implicit_Packing, then the Size clause in this 2993and similar examples will cause implicit packing and thus be accepted. For 2994this implicit packing to occur, the type in question must be an array of small 2995components whose size is known at compile time, and the Size clause must 2996specify the exact size that corresponds to the length of the array multiplied 2997by the size in bits of the component type. 2998@cindex Array packing 2999 3000Similarly, the following example shows the use in the record case 3001 3002@smallexample @c ada 3003type r is record 3004 a, b, c, d, e, f, g, h : boolean; 3005 chr : character; 3006end record; 3007for r'size use 16; 3008@end smallexample 3009 3010@noindent 3011Without a pragma Pack, each Boolean field requires 8 bits, so the 3012minimum size is 72 bits, but with a pragma Pack, 16 bits would be 3013sufficient. The use of pragma Implicit_Packing allows this record 3014declaration to compile without an explicit pragma Pack. 3015@node Pragma Import_Exception 3016@unnumberedsec Pragma Import_Exception 3017@cindex OpenVMS 3018@findex Import_Exception 3019@noindent 3020Syntax: 3021 3022@smallexample @c ada 3023pragma Import_Exception ( 3024 [Internal =>] LOCAL_NAME 3025 [, [External =>] EXTERNAL_SYMBOL] 3026 [, [Form =>] Ada | VMS] 3027 [, [Code =>] static_integer_EXPRESSION]); 3028 3029EXTERNAL_SYMBOL ::= 3030 IDENTIFIER 3031| static_string_EXPRESSION 3032@end smallexample 3033 3034@noindent 3035This pragma is implemented only in the OpenVMS implementation of GNAT@. 3036It allows OpenVMS conditions (for example, from OpenVMS system services or 3037other OpenVMS languages) to be propagated to Ada programs as Ada exceptions. 3038The pragma specifies that the exception associated with an exception 3039declaration in an Ada program be defined externally (in non-Ada code). 3040For further details on this pragma, see the 3041DEC Ada Language Reference Manual, section 13.9a.3.1. 3042 3043@node Pragma Import_Function 3044@unnumberedsec Pragma Import_Function 3045@findex Import_Function 3046@noindent 3047Syntax: 3048 3049@smallexample @c ada 3050pragma Import_Function ( 3051 [Internal =>] LOCAL_NAME, 3052 [, [External =>] EXTERNAL_SYMBOL] 3053 [, [Parameter_Types =>] PARAMETER_TYPES] 3054 [, [Result_Type =>] SUBTYPE_MARK] 3055 [, [Mechanism =>] MECHANISM] 3056 [, [Result_Mechanism =>] MECHANISM_NAME] 3057 [, [First_Optional_Parameter =>] IDENTIFIER]); 3058 3059EXTERNAL_SYMBOL ::= 3060 IDENTIFIER 3061| static_string_EXPRESSION 3062 3063PARAMETER_TYPES ::= 3064 null 3065| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3066 3067TYPE_DESIGNATOR ::= 3068 subtype_NAME 3069| subtype_Name ' Access 3070 3071MECHANISM ::= 3072 MECHANISM_NAME 3073| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3074 3075MECHANISM_ASSOCIATION ::= 3076 [formal_parameter_NAME =>] MECHANISM_NAME 3077 3078MECHANISM_NAME ::= 3079 Value 3080| Reference 3081| Descriptor [([Class =>] CLASS_NAME)] 3082| Short_Descriptor [([Class =>] CLASS_NAME)] 3083 3084CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 3085@end smallexample 3086 3087@noindent 3088This pragma is used in conjunction with a pragma @code{Import} to 3089specify additional information for an imported function. The pragma 3090@code{Import} (or equivalent pragma @code{Interface}) must precede the 3091@code{Import_Function} pragma and both must appear in the same 3092declarative part as the function specification. 3093 3094The @var{Internal} argument must uniquely designate 3095the function to which the 3096pragma applies. If more than one function name exists of this name in 3097the declarative part you must use the @code{Parameter_Types} and 3098@var{Result_Type} parameters to achieve the required unique 3099designation. Subtype marks in these parameters must exactly match the 3100subtypes in the corresponding function specification, using positional 3101notation to match parameters with subtype marks. 3102The form with an @code{'Access} attribute can be used to match an 3103anonymous access parameter. 3104 3105You may optionally use the @var{Mechanism} and @var{Result_Mechanism} 3106parameters to specify passing mechanisms for the 3107parameters and result. If you specify a single mechanism name, it 3108applies to all parameters. Otherwise you may specify a mechanism on a 3109parameter by parameter basis using either positional or named 3110notation. If the mechanism is not specified, the default mechanism 3111is used. 3112 3113@cindex OpenVMS 3114@cindex Passing by descriptor 3115Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 3116The default behavior for Import_Function is to pass a 64bit descriptor 3117unless short_descriptor is specified, then a 32bit descriptor is passed. 3118 3119@code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@. 3120It specifies that the designated parameter and all following parameters 3121are optional, meaning that they are not passed at the generated code 3122level (this is distinct from the notion of optional parameters in Ada 3123where the parameters are passed anyway with the designated optional 3124parameters). All optional parameters must be of mode @code{IN} and have 3125default parameter values that are either known at compile time 3126expressions, or uses of the @code{'Null_Parameter} attribute. 3127 3128@node Pragma Import_Object 3129@unnumberedsec Pragma Import_Object 3130@findex Import_Object 3131@noindent 3132Syntax: 3133 3134@smallexample @c ada 3135pragma Import_Object 3136 [Internal =>] LOCAL_NAME 3137 [, [External =>] EXTERNAL_SYMBOL] 3138 [, [Size =>] EXTERNAL_SYMBOL]); 3139 3140EXTERNAL_SYMBOL ::= 3141 IDENTIFIER 3142| static_string_EXPRESSION 3143@end smallexample 3144 3145@noindent 3146This pragma designates an object as imported, and apart from the 3147extended rules for external symbols, is identical in effect to the use of 3148the normal @code{Import} pragma applied to an object. Unlike the 3149subprogram case, you need not use a separate @code{Import} pragma, 3150although you may do so (and probably should do so from a portability 3151point of view). @var{size} is syntax checked, but otherwise ignored by 3152GNAT@. 3153 3154@node Pragma Import_Procedure 3155@unnumberedsec Pragma Import_Procedure 3156@findex Import_Procedure 3157@noindent 3158Syntax: 3159 3160@smallexample @c ada 3161pragma Import_Procedure ( 3162 [Internal =>] LOCAL_NAME 3163 [, [External =>] EXTERNAL_SYMBOL] 3164 [, [Parameter_Types =>] PARAMETER_TYPES] 3165 [, [Mechanism =>] MECHANISM] 3166 [, [First_Optional_Parameter =>] IDENTIFIER]); 3167 3168EXTERNAL_SYMBOL ::= 3169 IDENTIFIER 3170| static_string_EXPRESSION 3171 3172PARAMETER_TYPES ::= 3173 null 3174| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3175 3176TYPE_DESIGNATOR ::= 3177 subtype_NAME 3178| subtype_Name ' Access 3179 3180MECHANISM ::= 3181 MECHANISM_NAME 3182| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3183 3184MECHANISM_ASSOCIATION ::= 3185 [formal_parameter_NAME =>] MECHANISM_NAME 3186 3187MECHANISM_NAME ::= 3188 Value 3189| Reference 3190| Descriptor [([Class =>] CLASS_NAME)] 3191| Short_Descriptor [([Class =>] CLASS_NAME)] 3192 3193CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 3194@end smallexample 3195 3196@noindent 3197This pragma is identical to @code{Import_Function} except that it 3198applies to a procedure rather than a function and the parameters 3199@code{Result_Type} and @code{Result_Mechanism} are not permitted. 3200 3201@node Pragma Import_Valued_Procedure 3202@unnumberedsec Pragma Import_Valued_Procedure 3203@findex Import_Valued_Procedure 3204@noindent 3205Syntax: 3206 3207@smallexample @c ada 3208pragma Import_Valued_Procedure ( 3209 [Internal =>] LOCAL_NAME 3210 [, [External =>] EXTERNAL_SYMBOL] 3211 [, [Parameter_Types =>] PARAMETER_TYPES] 3212 [, [Mechanism =>] MECHANISM] 3213 [, [First_Optional_Parameter =>] IDENTIFIER]); 3214 3215EXTERNAL_SYMBOL ::= 3216 IDENTIFIER 3217| static_string_EXPRESSION 3218 3219PARAMETER_TYPES ::= 3220 null 3221| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 3222 3223TYPE_DESIGNATOR ::= 3224 subtype_NAME 3225| subtype_Name ' Access 3226 3227MECHANISM ::= 3228 MECHANISM_NAME 3229| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 3230 3231MECHANISM_ASSOCIATION ::= 3232 [formal_parameter_NAME =>] MECHANISM_NAME 3233 3234MECHANISM_NAME ::= 3235 Value 3236| Reference 3237| Descriptor [([Class =>] CLASS_NAME)] 3238| Short_Descriptor [([Class =>] CLASS_NAME)] 3239 3240CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 3241@end smallexample 3242 3243@noindent 3244This pragma is identical to @code{Import_Procedure} except that the 3245first parameter of @var{LOCAL_NAME}, which must be present, must be of 3246mode @code{OUT}, and externally the subprogram is treated as a function 3247with this parameter as the result of the function. The purpose of this 3248capability is to allow the use of @code{OUT} and @code{IN OUT} 3249parameters in interfacing to external functions (which are not permitted 3250in Ada functions). You may optionally use the @code{Mechanism} 3251parameters to specify passing mechanisms for the parameters. 3252If you specify a single mechanism name, it applies to all parameters. 3253Otherwise you may specify a mechanism on a parameter by parameter 3254basis using either positional or named notation. If the mechanism is not 3255specified, the default mechanism is used. 3256 3257Note that it is important to use this pragma in conjunction with a separate 3258pragma Import that specifies the desired convention, since otherwise the 3259default convention is Ada, which is almost certainly not what is required. 3260 3261@node Pragma Independent 3262@unnumberedsec Pragma Independent 3263@findex Independent 3264@noindent 3265Syntax: 3266 3267@smallexample @c ada 3268pragma Independent (Local_NAME); 3269@end smallexample 3270 3271@noindent 3272This pragma is standard in Ada 2012 mode (which also provides an aspect 3273of the same name). It is also available as an implementation-defined 3274pragma in all earlier versions. It specifies that the 3275designated object or all objects of the designated type must be 3276independently addressable. This means that separate tasks can safely 3277manipulate such objects. For example, if two components of a record are 3278independent, then two separate tasks may access these two components. 3279This may place 3280constraints on the representation of the object (for instance prohibiting 3281tight packing). 3282 3283@node Pragma Independent_Components 3284@unnumberedsec Pragma Independent_Components 3285@findex Independent_Components 3286@noindent 3287Syntax: 3288 3289@smallexample @c ada 3290pragma Independent_Components (Local_NAME); 3291@end smallexample 3292 3293@noindent 3294This pragma is standard in Ada 2012 mode (which also provides an aspect 3295of the same name). It is also available as an implementation-defined 3296pragma in all earlier versions. It specifies that the components of the 3297designated object, or the components of each object of the designated 3298type, must be 3299independently addressable. This means that separate tasks can safely 3300manipulate separate components in the composite object. This may place 3301constraints on the representation of the object (for instance prohibiting 3302tight packing). 3303 3304@node Pragma Initialize_Scalars 3305@unnumberedsec Pragma Initialize_Scalars 3306@findex Initialize_Scalars 3307@cindex debugging with Initialize_Scalars 3308@noindent 3309Syntax: 3310 3311@smallexample @c ada 3312pragma Initialize_Scalars; 3313@end smallexample 3314 3315@noindent 3316This pragma is similar to @code{Normalize_Scalars} conceptually but has 3317two important differences. First, there is no requirement for the pragma 3318to be used uniformly in all units of a partition, in particular, it is fine 3319to use this just for some or all of the application units of a partition, 3320without needing to recompile the run-time library. 3321 3322In the case where some units are compiled with the pragma, and some without, 3323then a declaration of a variable where the type is defined in package 3324Standard or is locally declared will always be subject to initialization, 3325as will any declaration of a scalar variable. For composite variables, 3326whether the variable is initialized may also depend on whether the package 3327in which the type of the variable is declared is compiled with the pragma. 3328 3329The other important difference is that you can control the value used 3330for initializing scalar objects. At bind time, you can select several 3331options for initialization. You can 3332initialize with invalid values (similar to Normalize_Scalars, though for 3333Initialize_Scalars it is not always possible to determine the invalid 3334values in complex cases like signed component fields with non-standard 3335sizes). You can also initialize with high or 3336low values, or with a specified bit pattern. See the @value{EDITION} 3337User's Guide for binder options for specifying these cases. 3338 3339This means that you can compile a program, and then without having to 3340recompile the program, you can run it with different values being used 3341for initializing otherwise uninitialized values, to test if your program 3342behavior depends on the choice. Of course the behavior should not change, 3343and if it does, then most likely you have an erroneous reference to an 3344uninitialized value. 3345 3346It is even possible to change the value at execution time eliminating even 3347the need to rebind with a different switch using an environment variable. 3348See the @value{EDITION} User's Guide for details. 3349 3350Note that pragma @code{Initialize_Scalars} is particularly useful in 3351conjunction with the enhanced validity checking that is now provided 3352in GNAT, which checks for invalid values under more conditions. 3353Using this feature (see description of the @option{-gnatV} flag in the 3354@value{EDITION} User's Guide) in conjunction with 3355pragma @code{Initialize_Scalars} 3356provides a powerful new tool to assist in the detection of problems 3357caused by uninitialized variables. 3358 3359Note: the use of @code{Initialize_Scalars} has a fairly extensive 3360effect on the generated code. This may cause your code to be 3361substantially larger. It may also cause an increase in the amount 3362of stack required, so it is probably a good idea to turn on stack 3363checking (see description of stack checking in the @value{EDITION} 3364User's Guide) when using this pragma. 3365 3366@node Pragma Inline_Always 3367@unnumberedsec Pragma Inline_Always 3368@findex Inline_Always 3369@noindent 3370Syntax: 3371 3372@smallexample @c ada 3373pragma Inline_Always (NAME [, NAME]); 3374@end smallexample 3375 3376@noindent 3377Similar to pragma @code{Inline} except that inlining is not subject to 3378the use of option @option{-gnatn} or @option{-gnatN} and the inlining 3379happens regardless of whether these options are used. 3380 3381@node Pragma Inline_Generic 3382@unnumberedsec Pragma Inline_Generic 3383@findex Inline_Generic 3384@noindent 3385Syntax: 3386 3387@smallexample @c ada 3388pragma Inline_Generic (generic_package_NAME); 3389@end smallexample 3390 3391@noindent 3392This is implemented for compatibility with DEC Ada 83 and is recognized, 3393but otherwise ignored, by GNAT@. All generic instantiations are inlined 3394by default when using GNAT@. 3395 3396@node Pragma Interface 3397@unnumberedsec Pragma Interface 3398@findex Interface 3399@noindent 3400Syntax: 3401 3402@smallexample @c ada 3403pragma Interface ( 3404 [Convention =>] convention_identifier, 3405 [Entity =>] local_NAME 3406 [, [External_Name =>] static_string_expression] 3407 [, [Link_Name =>] static_string_expression]); 3408@end smallexample 3409 3410@noindent 3411This pragma is identical in syntax and semantics to 3412the standard Ada pragma @code{Import}. It is provided for compatibility 3413with Ada 83. The definition is upwards compatible both with pragma 3414@code{Interface} as defined in the Ada 83 Reference Manual, and also 3415with some extended implementations of this pragma in certain Ada 83 3416implementations. The only difference between pragma @code{Interface} 3417and pragma @code{Import} is that there is special circuitry to allow 3418both pragmas to appear for the same subprogram entity (normally it 3419is illegal to have multiple @code{Import} pragmas. This is useful in 3420maintaining Ada 83/Ada 95 compatibility and is compatible with other 3421Ada 83 compilers. 3422 3423@node Pragma Interface_Name 3424@unnumberedsec Pragma Interface_Name 3425@findex Interface_Name 3426@noindent 3427Syntax: 3428 3429@smallexample @c ada 3430pragma Interface_Name ( 3431 [Entity =>] LOCAL_NAME 3432 [, [External_Name =>] static_string_EXPRESSION] 3433 [, [Link_Name =>] static_string_EXPRESSION]); 3434@end smallexample 3435 3436@noindent 3437This pragma provides an alternative way of specifying the interface name 3438for an interfaced subprogram, and is provided for compatibility with Ada 343983 compilers that use the pragma for this purpose. You must provide at 3440least one of @var{External_Name} or @var{Link_Name}. 3441 3442@node Pragma Interrupt_Handler 3443@unnumberedsec Pragma Interrupt_Handler 3444@findex Interrupt_Handler 3445@noindent 3446Syntax: 3447 3448@smallexample @c ada 3449pragma Interrupt_Handler (procedure_LOCAL_NAME); 3450@end smallexample 3451 3452@noindent 3453This program unit pragma is supported for parameterless protected procedures 3454as described in Annex C of the Ada Reference Manual. On the AAMP target 3455the pragma can also be specified for nonprotected parameterless procedures 3456that are declared at the library level (which includes procedures 3457declared at the top level of a library package). In the case of AAMP, 3458when this pragma is applied to a nonprotected procedure, the instruction 3459@code{IERET} is generated for returns from the procedure, enabling 3460maskable interrupts, in place of the normal return instruction. 3461 3462@node Pragma Interrupt_State 3463@unnumberedsec Pragma Interrupt_State 3464@findex Interrupt_State 3465@noindent 3466Syntax: 3467 3468@smallexample @c ada 3469pragma Interrupt_State 3470 ([Name =>] value, 3471 [State =>] SYSTEM | RUNTIME | USER); 3472@end smallexample 3473 3474@noindent 3475Normally certain interrupts are reserved to the implementation. Any attempt 3476to attach an interrupt causes Program_Error to be raised, as described in 3477RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 3478many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is 3479reserved to the implementation, so that @kbd{Ctrl-C} can be used to 3480interrupt execution. Additionally, signals such as @code{SIGSEGV}, 3481@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific 3482Ada exceptions, or used to implement run-time functions such as the 3483@code{abort} statement and stack overflow checking. 3484 3485Pragma @code{Interrupt_State} provides a general mechanism for overriding 3486such uses of interrupts. It subsumes the functionality of pragma 3487@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not 3488available on Windows or VMS. On all other platforms than VxWorks, 3489it applies to signals; on VxWorks, it applies to vectored hardware interrupts 3490and may be used to mark interrupts required by the board support package 3491as reserved. 3492 3493Interrupts can be in one of three states: 3494@itemize @bullet 3495@item System 3496 3497The interrupt is reserved (no Ada handler can be installed), and the 3498Ada run-time may not install a handler. As a result you are guaranteed 3499standard system default action if this interrupt is raised. 3500 3501@item Runtime 3502 3503The interrupt is reserved (no Ada handler can be installed). The run time 3504is allowed to install a handler for internal control purposes, but is 3505not required to do so. 3506 3507@item User 3508 3509The interrupt is unreserved. The user may install a handler to provide 3510some other action. 3511@end itemize 3512 3513@noindent 3514These states are the allowed values of the @code{State} parameter of the 3515pragma. The @code{Name} parameter is a value of the type 3516@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 3517@code{Ada.Interrupts.Names}. 3518 3519This is a configuration pragma, and the binder will check that there 3520are no inconsistencies between different units in a partition in how a 3521given interrupt is specified. It may appear anywhere a pragma is legal. 3522 3523The effect is to move the interrupt to the specified state. 3524 3525By declaring interrupts to be SYSTEM, you guarantee the standard system 3526action, such as a core dump. 3527 3528By declaring interrupts to be USER, you guarantee that you can install 3529a handler. 3530 3531Note that certain signals on many operating systems cannot be caught and 3532handled by applications. In such cases, the pragma is ignored. See the 3533operating system documentation, or the value of the array @code{Reserved} 3534declared in the spec of package @code{System.OS_Interface}. 3535 3536Overriding the default state of signals used by the Ada runtime may interfere 3537with an application's runtime behavior in the cases of the synchronous signals, 3538and in the case of the signal used to implement the @code{abort} statement. 3539 3540@node Pragma Invariant 3541@unnumberedsec Pragma Invariant 3542@findex Invariant 3543@noindent 3544Syntax: 3545 3546@smallexample @c ada 3547pragma Invariant 3548 ([Entity =>] private_type_LOCAL_NAME, 3549 [Check =>] EXPRESSION 3550 [,[Message =>] String_Expression]); 3551@end smallexample 3552 3553@noindent 3554This pragma provides exactly the same capabilities as the Type_Invariant aspect 3555defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The 3556Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it 3557requires the use of the aspect syntax, which is not available except in 2012 3558mode, it is not possible to use the Type_Invariant aspect in earlier versions 3559of Ada. However the Invariant pragma may be used in any version of Ada. Also 3560note that the aspect Invariant is a synonym in GNAT for the aspect 3561Type_Invariant, but there is no pragma Type_Invariant. 3562 3563The pragma must appear within the visible part of the package specification, 3564after the type to which its Entity argument appears. As with the Invariant 3565aspect, the Check expression is not analyzed until the end of the visible 3566part of the package, so it may contain forward references. The Message 3567argument, if present, provides the exception message used if the invariant 3568is violated. If no Message parameter is provided, a default message that 3569identifies the line on which the pragma appears is used. 3570 3571It is permissible to have multiple Invariants for the same type entity, in 3572which case they are and'ed together. It is permissible to use this pragma 3573in Ada 2012 mode, but you cannot have both an invariant aspect and an 3574invariant pragma for the same entity. 3575 3576For further details on the use of this pragma, see the Ada 2012 documentation 3577of the Type_Invariant aspect. 3578 3579@node Pragma Keep_Names 3580@unnumberedsec Pragma Keep_Names 3581@findex Keep_Names 3582@noindent 3583Syntax: 3584 3585@smallexample @c ada 3586pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 3587@end smallexample 3588 3589@noindent 3590The @var{LOCAL_NAME} argument 3591must refer to an enumeration first subtype 3592in the current declarative part. The effect is to retain the enumeration 3593literal names for use by @code{Image} and @code{Value} even if a global 3594@code{Discard_Names} pragma applies. This is useful when you want to 3595generally suppress enumeration literal names and for example you therefore 3596use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you 3597want to retain the names for specific enumeration types. 3598 3599@node Pragma License 3600@unnumberedsec Pragma License 3601@findex License 3602@cindex License checking 3603@noindent 3604Syntax: 3605 3606@smallexample @c ada 3607pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 3608@end smallexample 3609 3610@noindent 3611This pragma is provided to allow automated checking for appropriate license 3612conditions with respect to the standard and modified GPL@. A pragma 3613@code{License}, which is a configuration pragma that typically appears at 3614the start of a source file or in a separate @file{gnat.adc} file, specifies 3615the licensing conditions of a unit as follows: 3616 3617@itemize @bullet 3618@item Unrestricted 3619This is used for a unit that can be freely used with no license restrictions. 3620Examples of such units are public domain units, and units from the Ada 3621Reference Manual. 3622 3623@item GPL 3624This is used for a unit that is licensed under the unmodified GPL, and which 3625therefore cannot be @code{with}'ed by a restricted unit. 3626 3627@item Modified_GPL 3628This is used for a unit licensed under the GNAT modified GPL that includes 3629a special exception paragraph that specifically permits the inclusion of 3630the unit in programs without requiring the entire program to be released 3631under the GPL@. 3632 3633@item Restricted 3634This is used for a unit that is restricted in that it is not permitted to 3635depend on units that are licensed under the GPL@. Typical examples are 3636proprietary code that is to be released under more restrictive license 3637conditions. Note that restricted units are permitted to @code{with} units 3638which are licensed under the modified GPL (this is the whole point of the 3639modified GPL). 3640 3641@end itemize 3642 3643@noindent 3644Normally a unit with no @code{License} pragma is considered to have an 3645unknown license, and no checking is done. However, standard GNAT headers 3646are recognized, and license information is derived from them as follows. 3647 3648@itemize @bullet 3649 3650A GNAT license header starts with a line containing 78 hyphens. The following 3651comment text is searched for the appearance of any of the following strings. 3652 3653If the string ``GNU General Public License'' is found, then the unit is assumed 3654to have GPL license, unless the string ``As a special exception'' follows, in 3655which case the license is assumed to be modified GPL@. 3656 3657If one of the strings 3658``This specification is adapted from the Ada Semantic Interface'' or 3659``This specification is derived from the Ada Reference Manual'' is found 3660then the unit is assumed to be unrestricted. 3661@end itemize 3662 3663@noindent 3664These default actions means that a program with a restricted license pragma 3665will automatically get warnings if a GPL unit is inappropriately 3666@code{with}'ed. For example, the program: 3667 3668@smallexample @c ada 3669with Sem_Ch3; 3670with GNAT.Sockets; 3671procedure Secret_Stuff is 3672 @dots{} 3673end Secret_Stuff 3674@end smallexample 3675 3676@noindent 3677if compiled with pragma @code{License} (@code{Restricted}) in a 3678@file{gnat.adc} file will generate the warning: 3679 3680@smallexample 36811. with Sem_Ch3; 3682 | 3683 >>> license of withed unit "Sem_Ch3" is incompatible 3684 36852. with GNAT.Sockets; 36863. procedure Secret_Stuff is 3687@end smallexample 3688 3689@noindent 3690Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT 3691compiler and is licensed under the 3692GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 3693run time, and is therefore licensed under the modified GPL@. 3694 3695@node Pragma Link_With 3696@unnumberedsec Pragma Link_With 3697@findex Link_With 3698@noindent 3699Syntax: 3700 3701@smallexample @c ada 3702pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 3703@end smallexample 3704 3705@noindent 3706This pragma is provided for compatibility with certain Ada 83 compilers. 3707It has exactly the same effect as pragma @code{Linker_Options} except 3708that spaces occurring within one of the string expressions are treated 3709as separators. For example, in the following case: 3710 3711@smallexample @c ada 3712pragma Link_With ("-labc -ldef"); 3713@end smallexample 3714 3715@noindent 3716results in passing the strings @code{-labc} and @code{-ldef} as two 3717separate arguments to the linker. In addition pragma Link_With allows 3718multiple arguments, with the same effect as successive pragmas. 3719 3720@node Pragma Linker_Alias 3721@unnumberedsec Pragma Linker_Alias 3722@findex Linker_Alias 3723@noindent 3724Syntax: 3725 3726@smallexample @c ada 3727pragma Linker_Alias ( 3728 [Entity =>] LOCAL_NAME, 3729 [Target =>] static_string_EXPRESSION); 3730@end smallexample 3731 3732@noindent 3733@var{LOCAL_NAME} must refer to an object that is declared at the library 3734level. This pragma establishes the given entity as a linker alias for the 3735given target. It is equivalent to @code{__attribute__((alias))} in GNU C 3736and causes @var{LOCAL_NAME} to be emitted as an alias for the symbol 3737@var{static_string_EXPRESSION} in the object file, that is to say no space 3738is reserved for @var{LOCAL_NAME} by the assembler and it will be resolved 3739to the same address as @var{static_string_EXPRESSION} by the linker. 3740 3741The actual linker name for the target must be used (e.g.@: the fully 3742encoded name with qualification in Ada, or the mangled name in C++), 3743or it must be declared using the C convention with @code{pragma Import} 3744or @code{pragma Export}. 3745 3746Not all target machines support this pragma. On some of them it is accepted 3747only if @code{pragma Weak_External} has been applied to @var{LOCAL_NAME}. 3748 3749@smallexample @c ada 3750-- Example of the use of pragma Linker_Alias 3751 3752package p is 3753 i : Integer := 1; 3754 pragma Export (C, i); 3755 3756 new_name_for_i : Integer; 3757 pragma Linker_Alias (new_name_for_i, "i"); 3758end p; 3759@end smallexample 3760 3761@node Pragma Linker_Constructor 3762@unnumberedsec Pragma Linker_Constructor 3763@findex Linker_Constructor 3764@noindent 3765Syntax: 3766 3767@smallexample @c ada 3768pragma Linker_Constructor (procedure_LOCAL_NAME); 3769@end smallexample 3770 3771@noindent 3772@var{procedure_LOCAL_NAME} must refer to a parameterless procedure that 3773is declared at the library level. A procedure to which this pragma is 3774applied will be treated as an initialization routine by the linker. 3775It is equivalent to @code{__attribute__((constructor))} in GNU C and 3776causes @var{procedure_LOCAL_NAME} to be invoked before the entry point 3777of the executable is called (or immediately after the shared library is 3778loaded if the procedure is linked in a shared library), in particular 3779before the Ada run-time environment is set up. 3780 3781Because of these specific contexts, the set of operations such a procedure 3782can perform is very limited and the type of objects it can manipulate is 3783essentially restricted to the elementary types. In particular, it must only 3784contain code to which pragma Restrictions (No_Elaboration_Code) applies. 3785 3786This pragma is used by GNAT to implement auto-initialization of shared Stand 3787Alone Libraries, which provides a related capability without the restrictions 3788listed above. Where possible, the use of Stand Alone Libraries is preferable 3789to the use of this pragma. 3790 3791@node Pragma Linker_Destructor 3792@unnumberedsec Pragma Linker_Destructor 3793@findex Linker_Destructor 3794@noindent 3795Syntax: 3796 3797@smallexample @c ada 3798pragma Linker_Destructor (procedure_LOCAL_NAME); 3799@end smallexample 3800 3801@noindent 3802@var{procedure_LOCAL_NAME} must refer to a parameterless procedure that 3803is declared at the library level. A procedure to which this pragma is 3804applied will be treated as a finalization routine by the linker. 3805It is equivalent to @code{__attribute__((destructor))} in GNU C and 3806causes @var{procedure_LOCAL_NAME} to be invoked after the entry point 3807of the executable has exited (or immediately before the shared library 3808is unloaded if the procedure is linked in a shared library), in particular 3809after the Ada run-time environment is shut down. 3810 3811See @code{pragma Linker_Constructor} for the set of restrictions that apply 3812because of these specific contexts. 3813 3814@node Pragma Linker_Section 3815@unnumberedsec Pragma Linker_Section 3816@findex Linker_Section 3817@noindent 3818Syntax: 3819 3820@smallexample @c ada 3821pragma Linker_Section ( 3822 [Entity =>] LOCAL_NAME, 3823 [Section =>] static_string_EXPRESSION); 3824@end smallexample 3825 3826@noindent 3827@var{LOCAL_NAME} must refer to an object that is declared at the library 3828level. This pragma specifies the name of the linker section for the given 3829entity. It is equivalent to @code{__attribute__((section))} in GNU C and 3830causes @var{LOCAL_NAME} to be placed in the @var{static_string_EXPRESSION} 3831section of the executable (assuming the linker doesn't rename the section). 3832 3833The compiler normally places library-level objects in standard sections 3834depending on their type: procedures and functions generally go in the 3835@code{.text} section, initialized variables in the @code{.data} section 3836and uninitialized variables in the @code{.bss} section. 3837 3838Other, special sections may exist on given target machines to map special 3839hardware, for example I/O ports or flash memory. This pragma is a means to 3840defer the final layout of the executable to the linker, thus fully working 3841at the symbolic level with the compiler. 3842 3843Some file formats do not support arbitrary sections so not all target 3844machines support this pragma. The use of this pragma may cause a program 3845execution to be erroneous if it is used to place an entity into an 3846inappropriate section (e.g.@: a modified variable into the @code{.text} 3847section). See also @code{pragma Persistent_BSS}. 3848 3849@smallexample @c ada 3850-- Example of the use of pragma Linker_Section 3851 3852package IO_Card is 3853 Port_A : Integer; 3854 pragma Volatile (Port_A); 3855 pragma Linker_Section (Port_A, ".bss.port_a"); 3856 3857 Port_B : Integer; 3858 pragma Volatile (Port_B); 3859 pragma Linker_Section (Port_B, ".bss.port_b"); 3860end IO_Card; 3861@end smallexample 3862 3863@node Pragma Long_Float 3864@unnumberedsec Pragma Long_Float 3865@cindex OpenVMS 3866@findex Long_Float 3867@noindent 3868Syntax: 3869 3870@smallexample @c ada 3871pragma Long_Float (FLOAT_FORMAT); 3872 3873FLOAT_FORMAT ::= D_Float | G_Float 3874@end smallexample 3875 3876@noindent 3877This pragma is implemented only in the OpenVMS implementation of GNAT@. 3878It allows control over the internal representation chosen for the predefined 3879type @code{Long_Float} and for floating point type representations with 3880@code{digits} specified in the range 7 through 15. 3881For further details on this pragma, see the 3882@cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use 3883this pragma, the standard runtime libraries must be recompiled. 3884 3885@node Pragma Loop_Optimize 3886@unnumberedsec Pragma Loop_Optimize 3887@findex Loop_Optimize 3888@noindent 3889Syntax: 3890 3891@smallexample @c ada 3892pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); 3893 3894OPTIMIZATION_HINT ::= No_Unroll | Unroll | No_Vector | Vector 3895@end smallexample 3896 3897@noindent 3898This pragma must appear immediately within a loop statement. It allows the 3899programmer to specify optimization hints for the enclosing loop. The hints 3900are not mutually exclusive and can be freely mixed, but not all combinations 3901will yield a sensible outcome. 3902 3903There are four supported optimization hints for a loop: 3904@itemize @bullet 3905@item No_Unroll 3906 3907The loop must not be unrolled. This is a strong hint: the compiler will not 3908unroll a loop marked with this hint. 3909 3910@item Unroll 3911 3912The loop should be unrolled. This is a weak hint: the compiler will try to 3913apply unrolling to this loop preferably to other optimizations, notably 3914vectorization, but there is no guarantee that the loop will be unrolled. 3915 3916@item No_Vector 3917 3918The loop must not be vectorized. This is a strong hint: the compiler will not 3919vectorize a loop marked with this hint. 3920 3921@item Vector 3922 3923The loop should be vectorized. This is a weak hint: the compiler will try to 3924apply vectorization to this loop preferably to other optimizations, notably 3925unrolling, but there is no guarantee that the loop will be vectorized. 3926 3927@end itemize 3928 3929These hints do not void the need to pass the appropriate switches to the 3930compiler in order to enable the relevant optimizations, that is to say 3931@option{-funroll-loops} for unrolling and @option{-ftree-vectorize} for 3932vectorization. 3933 3934@node Pragma Machine_Attribute 3935@unnumberedsec Pragma Machine_Attribute 3936@findex Machine_Attribute 3937@noindent 3938Syntax: 3939 3940@smallexample @c ada 3941pragma Machine_Attribute ( 3942 [Entity =>] LOCAL_NAME, 3943 [Attribute_Name =>] static_string_EXPRESSION 3944 [, [Info =>] static_EXPRESSION] ); 3945@end smallexample 3946 3947@noindent 3948Machine-dependent attributes can be specified for types and/or 3949declarations. This pragma is semantically equivalent to 3950@code{__attribute__((@var{attribute_name}))} (if @var{info} is not 3951specified) or @code{__attribute__((@var{attribute_name}(@var{info})))} 3952in GNU C, where @code{@var{attribute_name}} is recognized by the 3953compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine 3954specific macro. A string literal for the optional parameter @var{info} 3955is transformed into an identifier, which may make this pragma unusable 3956for some attributes. @xref{Target Attributes,, Defining target-specific 3957uses of @code{__attribute__}, gccint, GNU Compiler Collection (GCC) 3958Internals}, further information. 3959 3960@node Pragma Main 3961@unnumberedsec Pragma Main 3962@cindex OpenVMS 3963@findex Main 3964@noindent 3965Syntax: 3966 3967@smallexample @c ada 3968pragma Main 3969 (MAIN_OPTION [, MAIN_OPTION]); 3970 3971MAIN_OPTION ::= 3972 [Stack_Size =>] static_integer_EXPRESSION 3973| [Task_Stack_Size_Default =>] static_integer_EXPRESSION 3974| [Time_Slicing_Enabled =>] static_boolean_EXPRESSION 3975@end smallexample 3976 3977@noindent 3978This pragma is provided for compatibility with OpenVMS VAX Systems. It has 3979no effect in GNAT, other than being syntax checked. 3980 3981@node Pragma Main_Storage 3982@unnumberedsec Pragma Main_Storage 3983@cindex OpenVMS 3984@findex Main_Storage 3985@noindent 3986Syntax: 3987 3988@smallexample @c ada 3989pragma Main_Storage 3990 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 3991 3992MAIN_STORAGE_OPTION ::= 3993 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 3994| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 3995@end smallexample 3996 3997@noindent 3998This pragma is provided for compatibility with OpenVMS VAX Systems. It has 3999no effect in GNAT, other than being syntax checked. Note that the pragma 4000also has no effect in DEC Ada 83 for OpenVMS Alpha Systems. 4001 4002@node Pragma No_Body 4003@unnumberedsec Pragma No_Body 4004@findex No_Body 4005@noindent 4006Syntax: 4007 4008@smallexample @c ada 4009pragma No_Body; 4010@end smallexample 4011 4012@noindent 4013There are a number of cases in which a package spec does not require a body, 4014and in fact a body is not permitted. GNAT will not permit the spec to be 4015compiled if there is a body around. The pragma No_Body allows you to provide 4016a body file, even in a case where no body is allowed. The body file must 4017contain only comments and a single No_Body pragma. This is recognized by 4018the compiler as indicating that no body is logically present. 4019 4020This is particularly useful during maintenance when a package is modified in 4021such a way that a body needed before is no longer needed. The provision of a 4022dummy body with a No_Body pragma ensures that there is no interference from 4023earlier versions of the package body. 4024 4025@node Pragma No_Inline 4026@unnumberedsec Pragma No_Inline 4027@findex No_Inline 4028@noindent 4029Syntax: 4030 4031@smallexample @c ada 4032pragma No_Inline (NAME [, NAME]); 4033@end smallexample 4034 4035@noindent 4036This pragma suppresses inlining for the callable entity or the instances of 4037the generic subprogram designated by @var{NAME}, including inlining that 4038results from the use of pragma @code{Inline}. This pragma is always active, 4039in particular it is not subject to the use of option @option{-gnatn} or 4040@option{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and 4041pragma @code{Inline_Always} for the same @var{NAME}. 4042 4043@node Pragma No_Return 4044@unnumberedsec Pragma No_Return 4045@findex No_Return 4046@noindent 4047Syntax: 4048 4049@smallexample @c ada 4050pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); 4051@end smallexample 4052 4053@noindent 4054Each @var{procedure_LOCAL_NAME} argument must refer to one or more procedure 4055declarations in the current declarative part. A procedure to which this 4056pragma is applied may not contain any explicit @code{return} statements. 4057In addition, if the procedure contains any implicit returns from falling 4058off the end of a statement sequence, then execution of that implicit 4059return will cause Program_Error to be raised. 4060 4061One use of this pragma is to identify procedures whose only purpose is to raise 4062an exception. Another use of this pragma is to suppress incorrect warnings 4063about missing returns in functions, where the last statement of a function 4064statement sequence is a call to such a procedure. 4065 4066Note that in Ada 2005 mode, this pragma is part of the language. It is 4067available in all earlier versions of Ada as an implementation-defined 4068pragma. 4069 4070@node Pragma No_Strict_Aliasing 4071@unnumberedsec Pragma No_Strict_Aliasing 4072@findex No_Strict_Aliasing 4073@noindent 4074Syntax: 4075 4076@smallexample @c ada 4077pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; 4078@end smallexample 4079 4080@noindent 4081@var{type_LOCAL_NAME} must refer to an access type 4082declaration in the current declarative part. The effect is to inhibit 4083strict aliasing optimization for the given type. The form with no 4084arguments is a configuration pragma which applies to all access types 4085declared in units to which the pragma applies. For a detailed 4086description of the strict aliasing optimization, and the situations 4087in which it must be suppressed, see @ref{Optimization and Strict 4088Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}. 4089 4090This pragma currently has no effects on access to unconstrained array types. 4091 4092@node Pragma Normalize_Scalars 4093@unnumberedsec Pragma Normalize_Scalars 4094@findex Normalize_Scalars 4095@noindent 4096Syntax: 4097 4098@smallexample @c ada 4099pragma Normalize_Scalars; 4100@end smallexample 4101 4102@noindent 4103This is a language defined pragma which is fully implemented in GNAT@. The 4104effect is to cause all scalar objects that are not otherwise initialized 4105to be initialized. The initial values are implementation dependent and 4106are as follows: 4107 4108@table @code 4109@item Standard.Character 4110@noindent 4111Objects whose root type is Standard.Character are initialized to 4112Character'Last unless the subtype range excludes NUL (in which case 4113NUL is used). This choice will always generate an invalid value if 4114one exists. 4115 4116@item Standard.Wide_Character 4117@noindent 4118Objects whose root type is Standard.Wide_Character are initialized to 4119Wide_Character'Last unless the subtype range excludes NUL (in which case 4120NUL is used). This choice will always generate an invalid value if 4121one exists. 4122 4123@item Standard.Wide_Wide_Character 4124@noindent 4125Objects whose root type is Standard.Wide_Wide_Character are initialized to 4126the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in 4127which case NUL is used). This choice will always generate an invalid value if 4128one exists. 4129 4130@item Integer types 4131@noindent 4132Objects of an integer type are treated differently depending on whether 4133negative values are present in the subtype. If no negative values are 4134present, then all one bits is used as the initial value except in the 4135special case where zero is excluded from the subtype, in which case 4136all zero bits are used. This choice will always generate an invalid 4137value if one exists. 4138 4139For subtypes with negative values present, the largest negative number 4140is used, except in the unusual case where this largest negative number 4141is in the subtype, and the largest positive number is not, in which case 4142the largest positive value is used. This choice will always generate 4143an invalid value if one exists. 4144 4145@item Floating-Point Types 4146Objects of all floating-point types are initialized to all 1-bits. For 4147standard IEEE format, this corresponds to a NaN (not a number) which is 4148indeed an invalid value. 4149 4150@item Fixed-Point Types 4151Objects of all fixed-point types are treated as described above for integers, 4152with the rules applying to the underlying integer value used to represent 4153the fixed-point value. 4154 4155@item Modular types 4156Objects of a modular type are initialized to all one bits, except in 4157the special case where zero is excluded from the subtype, in which 4158case all zero bits are used. This choice will always generate an 4159invalid value if one exists. 4160 4161@item Enumeration types 4162Objects of an enumeration type are initialized to all one-bits, i.e.@: to 4163the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal 4164whose Pos value is zero, in which case a code of zero is used. This choice 4165will always generate an invalid value if one exists. 4166 4167@end table 4168 4169@node Pragma Obsolescent 4170@unnumberedsec Pragma Obsolescent 4171@findex Obsolescent 4172@noindent 4173Syntax: 4174 4175@smallexample @c ada 4176pragma Obsolescent; 4177 4178pragma Obsolescent ( 4179 [Message =>] static_string_EXPRESSION 4180[,[Version =>] Ada_05]]); 4181 4182pragma Obsolescent ( 4183 [Entity =>] NAME 4184[,[Message =>] static_string_EXPRESSION 4185[,[Version =>] Ada_05]] ); 4186@end smallexample 4187 4188@noindent 4189This pragma can occur immediately following a declaration of an entity, 4190including the case of a record component. If no Entity argument is present, 4191then this declaration is the one to which the pragma applies. If an Entity 4192parameter is present, it must either match the name of the entity in this 4193declaration, or alternatively, the pragma can immediately follow an enumeration 4194type declaration, where the Entity argument names one of the enumeration 4195literals. 4196 4197This pragma is used to indicate that the named entity 4198is considered obsolescent and should not be used. Typically this is 4199used when an API must be modified by eventually removing or modifying 4200existing subprograms or other entities. The pragma can be used at an 4201intermediate stage when the entity is still present, but will be 4202removed later. 4203 4204The effect of this pragma is to output a warning message on a reference to 4205an entity thus marked that the subprogram is obsolescent if the appropriate 4206warning option in the compiler is activated. If the Message parameter is 4207present, then a second warning message is given containing this text. In 4208addition, a reference to the entity is considered to be a violation of pragma 4209Restrictions (No_Obsolescent_Features). 4210 4211This pragma can also be used as a program unit pragma for a package, 4212in which case the entity name is the name of the package, and the 4213pragma indicates that the entire package is considered 4214obsolescent. In this case a client @code{with}'ing such a package 4215violates the restriction, and the @code{with} statement is 4216flagged with warnings if the warning option is set. 4217 4218If the Version parameter is present (which must be exactly 4219the identifier Ada_05, no other argument is allowed), then the 4220indication of obsolescence applies only when compiling in Ada 2005 4221mode. This is primarily intended for dealing with the situations 4222in the predefined library where subprograms or packages 4223have become defined as obsolescent in Ada 2005 4224(e.g.@: in Ada.Characters.Handling), but may be used anywhere. 4225 4226The following examples show typical uses of this pragma: 4227 4228@smallexample @c ada 4229package p is 4230 pragma Obsolescent (p, Message => "use pp instead of p"); 4231end p; 4232 4233package q is 4234 procedure q2; 4235 pragma Obsolescent ("use q2new instead"); 4236 4237 type R is new integer; 4238 pragma Obsolescent 4239 (Entity => R, 4240 Message => "use RR in Ada 2005", 4241 Version => Ada_05); 4242 4243 type M is record 4244 F1 : Integer; 4245 F2 : Integer; 4246 pragma Obsolescent; 4247 F3 : Integer; 4248 end record; 4249 4250 type E is (a, bc, 'd', quack); 4251 pragma Obsolescent (Entity => bc) 4252 pragma Obsolescent (Entity => 'd') 4253 4254 function "+" 4255 (a, b : character) return character; 4256 pragma Obsolescent (Entity => "+"); 4257end; 4258@end smallexample 4259 4260@noindent 4261Note that, as for all pragmas, if you use a pragma argument identifier, 4262then all subsequent parameters must also use a pragma argument identifier. 4263So if you specify "Entity =>" for the Entity argument, and a Message 4264argument is present, it must be preceded by "Message =>". 4265 4266@node Pragma Optimize_Alignment 4267@unnumberedsec Pragma Optimize_Alignment 4268@findex Optimize_Alignment 4269@cindex Alignment, default settings 4270@noindent 4271Syntax: 4272 4273@smallexample @c ada 4274pragma Optimize_Alignment (TIME | SPACE | OFF); 4275@end smallexample 4276 4277@noindent 4278This is a configuration pragma which affects the choice of default alignments 4279for types where no alignment is explicitly specified. There is a time/space 4280trade-off in the selection of these values. Large alignments result in more 4281efficient code, at the expense of larger data space, since sizes have to be 4282increased to match these alignments. Smaller alignments save space, but the 4283access code is slower. The normal choice of default alignments (which is what 4284you get if you do not use this pragma, or if you use an argument of OFF), 4285tries to balance these two requirements. 4286 4287Specifying SPACE causes smaller default alignments to be chosen in two cases. 4288First any packed record is given an alignment of 1. Second, if a size is given 4289for the type, then the alignment is chosen to avoid increasing this size. For 4290example, consider: 4291 4292@smallexample @c ada 4293 type R is record 4294 X : Integer; 4295 Y : Character; 4296 end record; 4297 4298 for R'Size use 5*8; 4299@end smallexample 4300 4301@noindent 4302In the default mode, this type gets an alignment of 4, so that access to the 4303Integer field X are efficient. But this means that objects of the type end up 4304with a size of 8 bytes. This is a valid choice, since sizes of objects are 4305allowed to be bigger than the size of the type, but it can waste space if for 4306example fields of type R appear in an enclosing record. If the above type is 4307compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. 4308 4309However, there is one case in which SPACE is ignored. If a variable length 4310record (that is a discriminated record with a component which is an array 4311whose length depends on a discriminant), has a pragma Pack, then it is not 4312in general possible to set the alignment of such a record to one, so the 4313pragma is ignored in this case (with a warning). 4314 4315Specifying TIME causes larger default alignments to be chosen in the case of 4316small types with sizes that are not a power of 2. For example, consider: 4317 4318@smallexample @c ada 4319 type R is record 4320 A : Character; 4321 B : Character; 4322 C : Boolean; 4323 end record; 4324 4325 pragma Pack (R); 4326 for R'Size use 17; 4327@end smallexample 4328 4329@noindent 4330The default alignment for this record is normally 1, but if this type is 4331compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set 4332to 4, which wastes space for objects of the type, since they are now 4 bytes 4333long, but results in more efficient access when the whole record is referenced. 4334 4335As noted above, this is a configuration pragma, and there is a requirement 4336that all units in a partition be compiled with a consistent setting of the 4337optimization setting. This would normally be achieved by use of a configuration 4338pragma file containing the appropriate setting. The exception to this rule is 4339that units with an explicit configuration pragma in the same file as the source 4340unit are excluded from the consistency check, as are all predefined units. The 4341latter are compiled by default in pragma Optimize_Alignment (Off) mode if no 4342pragma appears at the start of the file. 4343 4344@node Pragma Ordered 4345@unnumberedsec Pragma Ordered 4346@findex Ordered 4347@findex pragma @code{Ordered} 4348@noindent 4349Syntax: 4350 4351@smallexample @c ada 4352pragma Ordered (enumeration_first_subtype_LOCAL_NAME); 4353@end smallexample 4354 4355@noindent 4356Most enumeration types are from a conceptual point of view unordered. 4357For example, consider: 4358 4359@smallexample @c ada 4360type Color is (Red, Blue, Green, Yellow); 4361@end smallexample 4362 4363@noindent 4364By Ada semantics @code{Blue > Red} and @code{Green > Blue}, 4365but really these relations make no sense; the enumeration type merely 4366specifies a set of possible colors, and the order is unimportant. 4367 4368For unordered enumeration types, it is generally a good idea if 4369clients avoid comparisons (other than equality or inequality) and 4370explicit ranges. (A @emph{client} is a unit where the type is referenced, 4371other than the unit where the type is declared, its body, and its subunits.) 4372For example, if code buried in some client says: 4373 4374@smallexample @c ada 4375if Current_Color < Yellow then ... 4376if Current_Color in Blue .. Green then ... 4377@end smallexample 4378 4379@noindent 4380then the client code is relying on the order, which is undesirable. 4381It makes the code hard to read and creates maintenance difficulties if 4382entries have to be added to the enumeration type. Instead, 4383the code in the client should list the possibilities, or an 4384appropriate subtype should be declared in the unit that declares 4385the original enumeration type. E.g., the following subtype could 4386be declared along with the type @code{Color}: 4387 4388@smallexample @c ada 4389subtype RBG is Color range Red .. Green; 4390@end smallexample 4391 4392@noindent 4393and then the client could write: 4394 4395@smallexample @c ada 4396if Current_Color in RBG then ... 4397if Current_Color = Blue or Current_Color = Green then ... 4398@end smallexample 4399 4400@noindent 4401However, some enumeration types are legitimately ordered from a conceptual 4402point of view. For example, if you declare: 4403 4404@smallexample @c ada 4405type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); 4406@end smallexample 4407 4408@noindent 4409then the ordering imposed by the language is reasonable, and 4410clients can depend on it, writing for example: 4411 4412@smallexample @c ada 4413if D in Mon .. Fri then ... 4414if D < Wed then ... 4415@end smallexample 4416 4417@noindent 4418The pragma @option{Ordered} is provided to mark enumeration types that 4419are conceptually ordered, alerting the reader that clients may depend 4420on the ordering. GNAT provides a pragma to mark enumerations as ordered 4421rather than one to mark them as unordered, since in our experience, 4422the great majority of enumeration types are conceptually unordered. 4423 4424The types @code{Boolean}, @code{Character}, @code{Wide_Character}, 4425and @code{Wide_Wide_Character} 4426are considered to be ordered types, so each is declared with a 4427pragma @code{Ordered} in package @code{Standard}. 4428 4429Normally pragma @code{Ordered} serves only as documentation and a guide for 4430coding standards, but GNAT provides a warning switch @option{-gnatw.u} that 4431requests warnings for inappropriate uses (comparisons and explicit 4432subranges) for unordered types. If this switch is used, then any 4433enumeration type not marked with pragma @code{Ordered} will be considered 4434as unordered, and will generate warnings for inappropriate uses. 4435 4436For additional information please refer to the description of the 4437@option{-gnatw.u} switch in the @value{EDITION} User's Guide. 4438 4439@node Pragma Overflow_Mode 4440@unnumberedsec Pragma Overflow_Mode 4441@findex Overflow checks 4442@findex Overflow mode 4443@findex pragma @code{Overflow_Mode} 4444@noindent 4445Syntax: 4446 4447@smallexample @c ada 4448pragma Overflow_Mode 4449 ( [General =>] MODE 4450 [,[Assertions =>] MODE]); 4451 4452MODE ::= STRICT | MINIMIZED | ELIMINATED 4453@end smallexample 4454 4455@noindent 4456This pragma sets the current overflow mode to the given setting. For details 4457of the meaning of these modes, please refer to the 4458``Overflow Check Handling in GNAT'' appendix in the 4459@value{EDITION} User's Guide. If only the @code{General} parameter is present, 4460the given mode applies to all expressions. If both parameters are present, 4461the @code{General} mode applies to expressions outside assertions, and 4462the @code{Eliminated} mode applies to expressions within assertions. 4463 4464The case of the @code{MODE} parameter is ignored, 4465so @code{MINIMIZED}, @code{Minimized} and 4466@code{minimized} all have the same effect. 4467 4468The @code{Overflow_Mode} pragma has the same scoping and placement 4469rules as pragma @code{Suppress}, so it can occur either as a 4470configuration pragma, specifying a default for the whole 4471program, or in a declarative scope, where it applies to the 4472remaining declarations and statements in that scope. 4473 4474The pragma @code{Suppress (Overflow_Check)} suppresses 4475overflow checking, but does not affect the overflow mode. 4476 4477The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) 4478overflow checking, but does not affect the overflow mode. 4479 4480@node Pragma Partition_Elaboration_Policy 4481@unnumberedsec Pragma Partition_Elaboration_Policy 4482@findex Partition_Elaboration_Policy 4483@noindent 4484Syntax: 4485 4486@smallexample @c ada 4487pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); 4488 4489POLICY_IDENTIFIER ::= Concurrent | Sequential 4490@end smallexample 4491 4492@noindent 4493This pragma is standard in Ada 2005, but is available in all earlier 4494versions of Ada as an implementation-defined pragma. 4495See Ada 2012 Reference Manual for details. 4496 4497@node Pragma Passive 4498@unnumberedsec Pragma Passive 4499@findex Passive 4500@noindent 4501Syntax: 4502 4503@smallexample @c ada 4504pragma Passive [(Semaphore | No)]; 4505@end smallexample 4506 4507@noindent 4508Syntax checked, but otherwise ignored by GNAT@. This is recognized for 4509compatibility with DEC Ada 83 implementations, where it is used within a 4510task definition to request that a task be made passive. If the argument 4511@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 4512treats the pragma as an assertion that the containing task is passive 4513and that optimization of context switch with this task is permitted and 4514desired. If the argument @code{No} is present, the task must not be 4515optimized. GNAT does not attempt to optimize any tasks in this manner 4516(since protected objects are available in place of passive tasks). 4517 4518@node Pragma Persistent_BSS 4519@unnumberedsec Pragma Persistent_BSS 4520@findex Persistent_BSS 4521@noindent 4522Syntax: 4523 4524@smallexample @c ada 4525pragma Persistent_BSS [(LOCAL_NAME)] 4526@end smallexample 4527 4528@noindent 4529This pragma allows selected objects to be placed in the @code{.persistent_bss} 4530section. On some targets the linker and loader provide for special 4531treatment of this section, allowing a program to be reloaded without 4532affecting the contents of this data (hence the name persistent). 4533 4534There are two forms of usage. If an argument is given, it must be the 4535local name of a library level object, with no explicit initialization 4536and whose type is potentially persistent. If no argument is given, then 4537the pragma is a configuration pragma, and applies to all library level 4538objects with no explicit initialization of potentially persistent types. 4539 4540A potentially persistent type is a scalar type, or a non-tagged, 4541non-discriminated record, all of whose components have no explicit 4542initialization and are themselves of a potentially persistent type, 4543or an array, all of whose constraints are static, and whose component 4544type is potentially persistent. 4545 4546If this pragma is used on a target where this feature is not supported, 4547then the pragma will be ignored. See also @code{pragma Linker_Section}. 4548 4549@node Pragma Polling 4550@unnumberedsec Pragma Polling 4551@findex Polling 4552@noindent 4553Syntax: 4554 4555@smallexample @c ada 4556pragma Polling (ON | OFF); 4557@end smallexample 4558 4559@noindent 4560This pragma controls the generation of polling code. This is normally off. 4561If @code{pragma Polling (ON)} is used then periodic calls are generated to 4562the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the 4563runtime library, and can be found in file @file{a-excpol.adb}. 4564 4565Pragma @code{Polling} can appear as a configuration pragma (for example it 4566can be placed in the @file{gnat.adc} file) to enable polling globally, or it 4567can be used in the statement or declaration sequence to control polling 4568more locally. 4569 4570A call to the polling routine is generated at the start of every loop and 4571at the start of every subprogram call. This guarantees that the @code{Poll} 4572routine is called frequently, and places an upper bound (determined by 4573the complexity of the code) on the period between two @code{Poll} calls. 4574 4575The primary purpose of the polling interface is to enable asynchronous 4576aborts on targets that cannot otherwise support it (for example Windows 4577NT), but it may be used for any other purpose requiring periodic polling. 4578The standard version is null, and can be replaced by a user program. This 4579will require re-compilation of the @code{Ada.Exceptions} package that can 4580be found in files @file{a-except.ads} and @file{a-except.adb}. 4581 4582A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT 4583distribution) is used to enable the asynchronous abort capability on 4584targets that do not normally support the capability. The version of 4585@code{Poll} in this file makes a call to the appropriate runtime routine 4586to test for an abort condition. 4587 4588Note that polling can also be enabled by use of the @option{-gnatP} switch. 4589@xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for 4590details. 4591 4592@node Pragma Postcondition 4593@unnumberedsec Pragma Postcondition 4594@cindex Postconditions 4595@cindex Checks, postconditions 4596@findex Postconditions 4597@noindent 4598Syntax: 4599 4600@smallexample @c ada 4601pragma Postcondition ( 4602 [Check =>] Boolean_Expression 4603 [,[Message =>] String_Expression]); 4604@end smallexample 4605 4606@noindent 4607The @code{Postcondition} pragma allows specification of automatic 4608postcondition checks for subprograms. These checks are similar to 4609assertions, but are automatically inserted just prior to the return 4610statements of the subprogram with which they are associated (including 4611implicit returns at the end of procedure bodies and associated 4612exception handlers). 4613 4614In addition, the boolean expression which is the condition which 4615must be true may contain references to function'Result in the case 4616of a function to refer to the returned value. 4617 4618@code{Postcondition} pragmas may appear either immediately following the 4619(separate) declaration of a subprogram, or at the start of the 4620declarations of a subprogram body. Only other pragmas may intervene 4621(that is appear between the subprogram declaration and its 4622postconditions, or appear before the postcondition in the 4623declaration sequence in a subprogram body). In the case of a 4624postcondition appearing after a subprogram declaration, the 4625formal arguments of the subprogram are visible, and can be 4626referenced in the postcondition expressions. 4627 4628The postconditions are collected and automatically tested just 4629before any return (implicit or explicit) in the subprogram body. 4630A postcondition is only recognized if postconditions are active 4631at the time the pragma is encountered. The compiler switch @option{gnata} 4632turns on all postconditions by default, and pragma @code{Check_Policy} 4633with an identifier of @code{Postcondition} can also be used to 4634control whether postconditions are active. 4635 4636The general approach is that postconditions are placed in the spec 4637if they represent functional aspects which make sense to the client. 4638For example we might have: 4639 4640@smallexample @c ada 4641 function Direction return Integer; 4642 pragma Postcondition 4643 (Direction'Result = +1 4644 or else 4645 Direction'Result = -1); 4646@end smallexample 4647 4648@noindent 4649which serves to document that the result must be +1 or -1, and 4650will test that this is the case at run time if postcondition 4651checking is active. 4652 4653Postconditions within the subprogram body can be used to 4654check that some internal aspect of the implementation, 4655not visible to the client, is operating as expected. 4656For instance if a square root routine keeps an internal 4657counter of the number of times it is called, then we 4658might have the following postcondition: 4659 4660@smallexample @c ada 4661 Sqrt_Calls : Natural := 0; 4662 4663 function Sqrt (Arg : Float) return Float is 4664 pragma Postcondition 4665 (Sqrt_Calls = Sqrt_Calls'Old + 1); 4666 ... 4667 end Sqrt 4668@end smallexample 4669 4670@noindent 4671As this example, shows, the use of the @code{Old} attribute 4672is often useful in postconditions to refer to the state on 4673entry to the subprogram. 4674 4675Note that postconditions are only checked on normal returns 4676from the subprogram. If an abnormal return results from 4677raising an exception, then the postconditions are not checked. 4678 4679If a postcondition fails, then the exception 4680@code{System.Assertions.Assert_Failure} is raised. If 4681a message argument was supplied, then the given string 4682will be used as the exception message. If no message 4683argument was supplied, then the default message has 4684the form "Postcondition failed at file:line". The 4685exception is raised in the context of the subprogram 4686body, so it is possible to catch postcondition failures 4687within the subprogram body itself. 4688 4689Within a package spec, normal visibility rules 4690in Ada would prevent forward references within a 4691postcondition pragma to functions defined later in 4692the same package. This would introduce undesirable 4693ordering constraints. To avoid this problem, all 4694postcondition pragmas are analyzed at the end of 4695the package spec, allowing forward references. 4696 4697The following example shows that this even allows 4698mutually recursive postconditions as in: 4699 4700@smallexample @c ada 4701package Parity_Functions is 4702 function Odd (X : Natural) return Boolean; 4703 pragma Postcondition 4704 (Odd'Result = 4705 (x = 1 4706 or else 4707 (x /= 0 and then Even (X - 1)))); 4708 4709 function Even (X : Natural) return Boolean; 4710 pragma Postcondition 4711 (Even'Result = 4712 (x = 0 4713 or else 4714 (x /= 1 and then Odd (X - 1)))); 4715 4716end Parity_Functions; 4717@end smallexample 4718 4719@noindent 4720There are no restrictions on the complexity or form of 4721conditions used within @code{Postcondition} pragmas. 4722The following example shows that it is even possible 4723to verify performance behavior. 4724 4725@smallexample @c ada 4726package Sort is 4727 4728 Performance : constant Float; 4729 -- Performance constant set by implementation 4730 -- to match target architecture behavior. 4731 4732 procedure Treesort (Arg : String); 4733 -- Sorts characters of argument using N*logN sort 4734 pragma Postcondition 4735 (Float (Clock - Clock'Old) <= 4736 Float (Arg'Length) * 4737 log (Float (Arg'Length)) * 4738 Performance); 4739end Sort; 4740@end smallexample 4741 4742@noindent 4743Note: postcondition pragmas associated with subprograms that are 4744marked as Inline_Always, or those marked as Inline with front-end 4745inlining (-gnatN option set) are accepted and legality-checked 4746by the compiler, but are ignored at run-time even if postcondition 4747checking is enabled. 4748 4749@node Pragma Preelaborable_Initialization 4750@unnumberedsec Pragma Preelaborable_Initialization 4751@findex Preelaborable_Initialization 4752@noindent 4753Syntax: 4754 4755@smallexample @c ada 4756pragma Preelaborable_Initialization (DIRECT_NAME); 4757@end smallexample 4758 4759@noindent 4760This pragma is standard in Ada 2005, but is available in all earlier 4761versions of Ada as an implementation-defined pragma. 4762See Ada 2012 Reference Manual for details. 4763 4764@node Pragma Priority_Specific_Dispatching 4765@unnumberedsec Pragma Priority_Specific_Dispatching 4766@findex Priority_Specific_Dispatching 4767@noindent 4768Syntax: 4769 4770@smallexample @c ada 4771pragma Priority_Specific_Dispatching ( 4772 POLICY_IDENTIFIER, 4773 first_priority_EXPRESSION, 4774 last_priority_EXPRESSION) 4775 4776POLICY_IDENTIFIER ::= 4777 EDF_Across_Priorities | 4778 FIFO_Within_Priorities | 4779 Non_Preemptive_Within_Priorities | 4780 Round_Robin_Within_Priorities 4781@end smallexample 4782 4783@noindent 4784This pragma is standard in Ada 2005, but is available in all earlier 4785versions of Ada as an implementation-defined pragma. 4786See Ada 2012 Reference Manual for details. 4787 4788@node Pragma Precondition 4789@unnumberedsec Pragma Precondition 4790@cindex Preconditions 4791@cindex Checks, preconditions 4792@findex Preconditions 4793@noindent 4794Syntax: 4795 4796@smallexample @c ada 4797pragma Precondition ( 4798 [Check =>] Boolean_Expression 4799 [,[Message =>] String_Expression]); 4800@end smallexample 4801 4802@noindent 4803The @code{Precondition} pragma is similar to @code{Postcondition} 4804except that the corresponding checks take place immediately upon 4805entry to the subprogram, and if a precondition fails, the exception 4806is raised in the context of the caller, and the attribute 'Result 4807cannot be used within the precondition expression. 4808 4809Otherwise, the placement and visibility rules are identical to those 4810described for postconditions. The following is an example of use 4811within a package spec: 4812 4813@smallexample @c ada 4814package Math_Functions is 4815 ... 4816 function Sqrt (Arg : Float) return Float; 4817 pragma Precondition (Arg >= 0.0) 4818 ... 4819end Math_Functions; 4820@end smallexample 4821 4822@noindent 4823@code{Precondition} pragmas may appear either immediately following the 4824(separate) declaration of a subprogram, or at the start of the 4825declarations of a subprogram body. Only other pragmas may intervene 4826(that is appear between the subprogram declaration and its 4827postconditions, or appear before the postcondition in the 4828declaration sequence in a subprogram body). 4829 4830Note: postcondition pragmas associated with subprograms that are 4831marked as Inline_Always, or those marked as Inline with front-end 4832inlining (-gnatN option set) are accepted and legality-checked 4833by the compiler, but are ignored at run-time even if postcondition 4834checking is enabled. 4835 4836@node Pragma Profile (Ravenscar) 4837@unnumberedsec Pragma Profile (Ravenscar) 4838@findex Ravenscar 4839@noindent 4840Syntax: 4841 4842@smallexample @c ada 4843pragma Profile (Ravenscar | Restricted); 4844@end smallexample 4845 4846@noindent 4847This pragma is standard in Ada 2005, but is available in all earlier 4848versions of Ada as an implementation-defined pragma. This is a 4849configuration pragma that establishes the following set of configuration 4850pragmas: 4851 4852@table @code 4853@item Task_Dispatching_Policy (FIFO_Within_Priorities) 4854[RM D.2.2] Tasks are dispatched following a preemptive 4855priority-ordered scheduling policy. 4856 4857@item Locking_Policy (Ceiling_Locking) 4858[RM D.3] While tasks and interrupts execute a protected action, they inherit 4859the ceiling priority of the corresponding protected object. 4860@c 4861@c @item Detect_Blocking 4862@c This pragma forces the detection of potentially blocking operations within a 4863@c protected operation, and to raise Program_Error if that happens. 4864@end table 4865@noindent 4866 4867plus the following set of restrictions: 4868 4869@table @code 4870@item Max_Entry_Queue_Length => 1 4871No task can be queued on a protected entry. 4872@item Max_Protected_Entries => 1 4873@item Max_Task_Entries => 0 4874No rendezvous statements are allowed. 4875@item No_Abort_Statements 4876@item No_Dynamic_Attachment 4877@item No_Dynamic_Priorities 4878@item No_Implicit_Heap_Allocations 4879@item No_Local_Protected_Objects 4880@item No_Local_Timing_Events 4881@item No_Protected_Type_Allocators 4882@item No_Relative_Delay 4883@item No_Requeue_Statements 4884@item No_Select_Statements 4885@item No_Specific_Termination_Handlers 4886@item No_Task_Allocators 4887@item No_Task_Hierarchy 4888@item No_Task_Termination 4889@item Simple_Barriers 4890@end table 4891@noindent 4892 4893The Ravenscar profile also includes the following restrictions that specify 4894that there are no semantic dependences on the corresponding predefined 4895packages: 4896 4897@table @code 4898@item No_Dependence => Ada.Asynchronous_Task_Control 4899@item No_Dependence => Ada.Calendar 4900@item No_Dependence => Ada.Execution_Time.Group_Budget 4901@item No_Dependence => Ada.Execution_Time.Timers 4902@item No_Dependence => Ada.Task_Attributes 4903@item No_Dependence => System.Multiprocessors.Dispatching_Domains 4904@end table 4905 4906@noindent 4907 4908This set of configuration pragmas and restrictions correspond to the 4909definition of the ``Ravenscar Profile'' for limited tasking, devised and 4910published by the @cite{International Real-Time Ada Workshop}, 1997, 4911and whose most recent description is available at 4912@url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. 4913 4914The original definition of the profile was revised at subsequent IRTAW 4915meetings. It has been included in the ISO 4916@cite{Guide for the Use of the Ada Programming Language in High 4917Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in 4918the next revision of the standard. The formal definition given by 4919the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and 4920AI-305) available at 4921@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and 4922@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. 4923 4924The above set is a superset of the restrictions provided by pragma 4925@code{Profile (Restricted)}, it includes six additional restrictions 4926(@code{Simple_Barriers}, @code{No_Select_Statements}, 4927@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, 4928@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 4929that pragma @code{Profile (Ravenscar)}, like the pragma 4930@code{Profile (Restricted)}, 4931automatically causes the use of a simplified, 4932more efficient version of the tasking run-time system. 4933 4934@node Pragma Profile (Restricted) 4935@unnumberedsec Pragma Profile (Restricted) 4936@findex Restricted Run Time 4937@noindent 4938Syntax: 4939 4940@smallexample @c ada 4941pragma Profile (Restricted); 4942@end smallexample 4943 4944@noindent 4945This is an implementation-defined version of the standard pragma defined 4946in Ada 2005. It is available in all versions of Ada. It is a 4947configuration pragma that establishes the following set of restrictions: 4948 4949@itemize @bullet 4950@item No_Abort_Statements 4951@item No_Entry_Queue 4952@item No_Task_Hierarchy 4953@item No_Task_Allocators 4954@item No_Dynamic_Priorities 4955@item No_Terminate_Alternatives 4956@item No_Dynamic_Attachment 4957@item No_Protected_Type_Allocators 4958@item No_Local_Protected_Objects 4959@item No_Requeue_Statements 4960@item No_Task_Attributes_Package 4961@item Max_Asynchronous_Select_Nesting = 0 4962@item Max_Task_Entries = 0 4963@item Max_Protected_Entries = 1 4964@item Max_Select_Alternatives = 0 4965@end itemize 4966 4967@noindent 4968This set of restrictions causes the automatic selection of a simplified 4969version of the run time that provides improved performance for the 4970limited set of tasking functionality permitted by this set of restrictions. 4971 4972@node Pragma Profile (Rational) 4973@unnumberedsec Pragma Profile (Rational) 4974@findex Rational compatibility mode 4975@noindent 4976Syntax: 4977 4978@smallexample @c ada 4979pragma Profile (Rational); 4980@end smallexample 4981 4982@noindent 4983The Rational profile is intended to facilitate porting legacy code that 4984compiles with the Rational APEX compiler, even when the code includes non- 4985conforming Ada constructs. The profile enables the following three pragmas: 4986 4987@itemize @bullet 4988pragma Implicit_Packing; 4989pragma Overriding_Renamings; 4990pragma Use_VADS_Size; 4991@end itemize 4992 4993@noindent 4994@node Pragma Psect_Object 4995@unnumberedsec Pragma Psect_Object 4996@findex Psect_Object 4997@noindent 4998Syntax: 4999 5000@smallexample @c ada 5001pragma Psect_Object ( 5002 [Internal =>] LOCAL_NAME, 5003 [, [External =>] EXTERNAL_SYMBOL] 5004 [, [Size =>] EXTERNAL_SYMBOL]); 5005 5006EXTERNAL_SYMBOL ::= 5007 IDENTIFIER 5008| static_string_EXPRESSION 5009@end smallexample 5010 5011@noindent 5012This pragma is identical in effect to pragma @code{Common_Object}. 5013 5014@node Pragma Pure_Function 5015@unnumberedsec Pragma Pure_Function 5016@findex Pure_Function 5017@noindent 5018Syntax: 5019 5020@smallexample @c ada 5021pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 5022@end smallexample 5023 5024@noindent 5025This pragma appears in the same declarative part as a function 5026declaration (or a set of function declarations if more than one 5027overloaded declaration exists, in which case the pragma applies 5028to all entities). It specifies that the function @code{Entity} is 5029to be considered pure for the purposes of code generation. This means 5030that the compiler can assume that there are no side effects, and 5031in particular that two calls with identical arguments produce the 5032same result. It also means that the function can be used in an 5033address clause. 5034 5035Note that, quite deliberately, there are no static checks to try 5036to ensure that this promise is met, so @code{Pure_Function} can be used 5037with functions that are conceptually pure, even if they do modify 5038global variables. For example, a square root function that is 5039instrumented to count the number of times it is called is still 5040conceptually pure, and can still be optimized, even though it 5041modifies a global variable (the count). Memo functions are another 5042example (where a table of previous calls is kept and consulted to 5043avoid re-computation). 5044 5045Note also that the normal rules excluding optimization of subprograms 5046in pure units (when parameter types are descended from System.Address, 5047or when the full view of a parameter type is limited), do not apply 5048for the Pure_Function case. If you explicitly specify Pure_Function, 5049the compiler may optimize away calls with identical arguments, and 5050if that results in unexpected behavior, the proper action is not to 5051use the pragma for subprograms that are not (conceptually) pure. 5052 5053@findex Pure 5054Note: Most functions in a @code{Pure} package are automatically pure, and 5055there is no need to use pragma @code{Pure_Function} for such functions. One 5056exception is any function that has at least one formal of type 5057@code{System.Address} or a type derived from it. Such functions are not 5058considered pure by default, since the compiler assumes that the 5059@code{Address} parameter may be functioning as a pointer and that the 5060referenced data may change even if the address value does not. 5061Similarly, imported functions are not considered to be pure by default, 5062since there is no way of checking that they are in fact pure. The use 5063of pragma @code{Pure_Function} for such a function will override these default 5064assumption, and cause the compiler to treat a designated subprogram as pure 5065in these cases. 5066 5067Note: If pragma @code{Pure_Function} is applied to a renamed function, it 5068applies to the underlying renamed function. This can be used to 5069disambiguate cases of overloading where some but not all functions 5070in a set of overloaded functions are to be designated as pure. 5071 5072If pragma @code{Pure_Function} is applied to a library level function, the 5073function is also considered pure from an optimization point of view, but the 5074unit is not a Pure unit in the categorization sense. So for example, a function 5075thus marked is free to @code{with} non-pure units. 5076 5077@node Pragma Relative_Deadline 5078@unnumberedsec Pragma Relative_Deadline 5079@findex Relative_Deadline 5080@noindent 5081Syntax: 5082 5083@smallexample @c ada 5084pragma Relative_Deadline (time_span_EXPRESSSION); 5085@end smallexample 5086 5087@noindent 5088This pragma is standard in Ada 2005, but is available in all earlier 5089versions of Ada as an implementation-defined pragma. 5090See Ada 2012 Reference Manual for details. 5091 5092@node Pragma Remote_Access_Type 5093@unnumberedsec Pragma Remote_Access_Type 5094@findex Remote_Access_Type 5095@noindent 5096Syntax: 5097 5098@smallexample @c ada 5099pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); 5100@end smallexample 5101 5102@noindent 5103This pragma appears in the formal part of a generic declaration. 5104It specifies an exception to the RM rule from E.2.2(17/2), which forbids 5105the use of a remote access to class-wide type as actual for a formal 5106access type. 5107 5108When this pragma applies to a formal access type @code{Entity}, that 5109type is treated as a remote access to class-wide type in the generic. 5110It must be a formal general access type, and its designated type must 5111be the class-wide type of a formal tagged limited private type from the 5112same generic declaration. 5113 5114In the generic unit, the formal type is subject to all restrictions 5115pertaining to remote access to class-wide types. At instantiation, the 5116actual type must be a remote access to class-wide type. 5117 5118@node Pragma Restriction_Warnings 5119@unnumberedsec Pragma Restriction_Warnings 5120@findex Restriction_Warnings 5121@noindent 5122Syntax: 5123 5124@smallexample @c ada 5125pragma Restriction_Warnings 5126 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 5127@end smallexample 5128 5129@noindent 5130This pragma allows a series of restriction identifiers to be 5131specified (the list of allowed identifiers is the same as for 5132pragma @code{Restrictions}). For each of these identifiers 5133the compiler checks for violations of the restriction, but 5134generates a warning message rather than an error message 5135if the restriction is violated. 5136 5137@node Pragma Shared 5138@unnumberedsec Pragma Shared 5139@findex Shared 5140 5141@noindent 5142This pragma is provided for compatibility with Ada 83. The syntax and 5143semantics are identical to pragma Atomic. 5144 5145@node Pragma Short_Circuit_And_Or 5146@unnumberedsec Pragma Short_Circuit_And_Or 5147@findex Short_Circuit_And_Or 5148 5149@noindent 5150This configuration pragma causes any occurrence of the AND operator applied to 5151operands of type Standard.Boolean to be short-circuited (i.e. the AND operator 5152is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This 5153may be useful in the context of certification protocols requiring the use of 5154short-circuited logical operators. If this configuration pragma occurs locally 5155within the file being compiled, it applies only to the file being compiled. 5156There is no requirement that all units in a partition use this option. 5157 5158@node Pragma Short_Descriptors 5159@unnumberedsec Pragma Short_Descriptors 5160@findex Short_Descriptors 5161@noindent 5162Syntax: 5163 5164@smallexample @c ada 5165pragma Short_Descriptors 5166@end smallexample 5167 5168@noindent 5169In VMS versions of the compiler, this configuration pragma causes all 5170occurrences of the mechanism types Descriptor[_xxx] to be treated as 5171Short_Descriptor[_xxx]. This is helpful in porting legacy applications from a 517232-bit environment to a 64-bit environment. This pragma is ignored for non-VMS 5173versions. 5174 5175@node Pragma Simple_Storage_Pool_Type 5176@unnumberedsec Pragma Simple_Storage_Pool_Type 5177@findex Simple_Storage_Pool_Type 5178@cindex Storage pool, simple 5179@cindex Simple storage pool 5180@noindent 5181Syntax: 5182 5183@smallexample @c ada 5184pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); 5185@end smallexample 5186 5187@noindent 5188A type can be established as a ``simple storage pool type'' by applying 5189the representation pragma @code{Simple_Storage_Pool_Type} to the type. 5190A type named in the pragma must be a library-level immutably limited record 5191type or limited tagged type declared immediately within a package declaration. 5192The type can also be a limited private type whose full type is allowed as 5193a simple storage pool type. 5194 5195For a simple storage pool type @var{SSP}, nonabstract primitive subprograms 5196@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that 5197are subtype conformant with the following subprogram declarations: 5198 5199@smallexample @c ada 5200procedure Allocate 5201 (Pool : in out SSP; 5202 Storage_Address : out System.Address; 5203 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 5204 Alignment : System.Storage_Elements.Storage_Count); 5205 5206procedure Deallocate 5207 (Pool : in out SSP; 5208 Storage_Address : System.Address; 5209 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; 5210 Alignment : System.Storage_Elements.Storage_Count); 5211 5212function Storage_Size (Pool : SSP) 5213 return System.Storage_Elements.Storage_Count; 5214@end smallexample 5215 5216@noindent 5217Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and 5218@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then 5219applying an unchecked deallocation has no effect other than to set its actual 5220parameter to null. If @code{Storage_Size} is not declared, then the 5221@code{Storage_Size} attribute applied to an access type associated with 5222a pool object of type SSP returns zero. Additional operations can be declared 5223for a simple storage pool type (such as for supporting a mark/release 5224storage-management discipline). 5225 5226An object of a simple storage pool type can be associated with an access 5227type by specifying the attribute @code{Simple_Storage_Pool}. For example: 5228 5229@smallexample @c ada 5230 5231My_Pool : My_Simple_Storage_Pool_Type; 5232 5233type Acc is access My_Data_Type; 5234 5235for Acc'Simple_Storage_Pool use My_Pool; 5236 5237@end smallexample 5238 5239@noindent 5240See attribute @code{Simple_Storage_Pool} for further details. 5241 5242@node Pragma Source_File_Name 5243@unnumberedsec Pragma Source_File_Name 5244@findex Source_File_Name 5245@noindent 5246Syntax: 5247 5248@smallexample @c ada 5249pragma Source_File_Name ( 5250 [Unit_Name =>] unit_NAME, 5251 Spec_File_Name => STRING_LITERAL, 5252 [Index => INTEGER_LITERAL]); 5253 5254pragma Source_File_Name ( 5255 [Unit_Name =>] unit_NAME, 5256 Body_File_Name => STRING_LITERAL, 5257 [Index => INTEGER_LITERAL]); 5258@end smallexample 5259 5260@noindent 5261Use this to override the normal naming convention. It is a configuration 5262pragma, and so has the usual applicability of configuration pragmas 5263(i.e.@: it applies to either an entire partition, or to all units in a 5264compilation, or to a single unit, depending on how it is used. 5265@var{unit_name} is mapped to @var{file_name_literal}. The identifier for 5266the second argument is required, and indicates whether this is the file 5267name for the spec or for the body. 5268 5269The optional Index argument should be used when a file contains multiple 5270units, and when you do not want to use @code{gnatchop} to separate then 5271into multiple files (which is the recommended procedure to limit the 5272number of recompilations that are needed when some sources change). 5273For instance, if the source file @file{source.ada} contains 5274 5275@smallexample @c ada 5276package B is 5277... 5278end B; 5279 5280with B; 5281procedure A is 5282begin 5283 .. 5284end A; 5285@end smallexample 5286 5287you could use the following configuration pragmas: 5288 5289@smallexample @c ada 5290pragma Source_File_Name 5291 (B, Spec_File_Name => "source.ada", Index => 1); 5292pragma Source_File_Name 5293 (A, Body_File_Name => "source.ada", Index => 2); 5294@end smallexample 5295 5296Note that the @code{gnatname} utility can also be used to generate those 5297configuration pragmas. 5298 5299Another form of the @code{Source_File_Name} pragma allows 5300the specification of patterns defining alternative file naming schemes 5301to apply to all files. 5302 5303@smallexample @c ada 5304pragma Source_File_Name 5305 ( [Spec_File_Name =>] STRING_LITERAL 5306 [,[Casing =>] CASING_SPEC] 5307 [,[Dot_Replacement =>] STRING_LITERAL]); 5308 5309pragma Source_File_Name 5310 ( [Body_File_Name =>] STRING_LITERAL 5311 [,[Casing =>] CASING_SPEC] 5312 [,[Dot_Replacement =>] STRING_LITERAL]); 5313 5314pragma Source_File_Name 5315 ( [Subunit_File_Name =>] STRING_LITERAL 5316 [,[Casing =>] CASING_SPEC] 5317 [,[Dot_Replacement =>] STRING_LITERAL]); 5318 5319CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 5320@end smallexample 5321 5322@noindent 5323The first argument is a pattern that contains a single asterisk indicating 5324the point at which the unit name is to be inserted in the pattern string 5325to form the file name. The second argument is optional. If present it 5326specifies the casing of the unit name in the resulting file name string. 5327The default is lower case. Finally the third argument allows for systematic 5328replacement of any dots in the unit name by the specified string literal. 5329 5330Note that Source_File_Name pragmas should not be used if you are using 5331project files. The reason for this rule is that the project manager is not 5332aware of these pragmas, and so other tools that use the projet file would not 5333be aware of the intended naming conventions. If you are using project files, 5334file naming is controlled by Source_File_Name_Project pragmas, which are 5335usually supplied automatically by the project manager. A pragma 5336Source_File_Name cannot appear after a @ref{Pragma Source_File_Name_Project}. 5337 5338For more details on the use of the @code{Source_File_Name} pragma, 5339@xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide}, 5340and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION} 5341User's Guide}. 5342 5343@node Pragma Source_File_Name_Project 5344@unnumberedsec Pragma Source_File_Name_Project 5345@findex Source_File_Name_Project 5346@noindent 5347 5348This pragma has the same syntax and semantics as pragma Source_File_Name. 5349It is only allowed as a stand alone configuration pragma. 5350It cannot appear after a @ref{Pragma Source_File_Name}, and 5351most importantly, once pragma Source_File_Name_Project appears, 5352no further Source_File_Name pragmas are allowed. 5353 5354The intention is that Source_File_Name_Project pragmas are always 5355generated by the Project Manager in a manner consistent with the naming 5356specified in a project file, and when naming is controlled in this manner, 5357it is not permissible to attempt to modify this naming scheme using 5358Source_File_Name or Source_File_Name_Project pragmas (which would not be 5359known to the project manager). 5360 5361@node Pragma Source_Reference 5362@unnumberedsec Pragma Source_Reference 5363@findex Source_Reference 5364@noindent 5365Syntax: 5366 5367@smallexample @c ada 5368pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 5369@end smallexample 5370 5371@noindent 5372This pragma must appear as the first line of a source file. 5373@var{integer_literal} is the logical line number of the line following 5374the pragma line (for use in error messages and debugging 5375information). @var{string_literal} is a static string constant that 5376specifies the file name to be used in error messages and debugging 5377information. This is most notably used for the output of @code{gnatchop} 5378with the @option{-r} switch, to make sure that the original unchopped 5379source file is the one referred to. 5380 5381The second argument must be a string literal, it cannot be a static 5382string expression other than a string literal. This is because its value 5383is needed for error messages issued by all phases of the compiler. 5384 5385@node Pragma Static_Elaboration_Desired 5386@unnumberedsec Pragma Static_Elaboration_Desired 5387@findex Static_Elaboration_Desired 5388@noindent 5389Syntax: 5390 5391@smallexample @c ada 5392pragma Static_Elaboration_Desired; 5393@end smallexample 5394 5395@noindent 5396This pragma is used to indicate that the compiler should attempt to initialize 5397statically the objects declared in the library unit to which the pragma applies, 5398when these objects are initialized (explicitly or implicitly) by an aggregate. 5399In the absence of this pragma, aggregates in object declarations are expanded 5400into assignments and loops, even when the aggregate components are static 5401constants. When the aggregate is present the compiler builds a static expression 5402that requires no run-time code, so that the initialized object can be placed in 5403read-only data space. If the components are not static, or the aggregate has 5404more that 100 components, the compiler emits a warning that the pragma cannot 5405be obeyed. (See also the restriction No_Implicit_Loops, which supports static 5406construction of larger aggregates with static components that include an others 5407choice.) 5408 5409@node Pragma Stream_Convert 5410@unnumberedsec Pragma Stream_Convert 5411@findex Stream_Convert 5412@noindent 5413Syntax: 5414 5415@smallexample @c ada 5416pragma Stream_Convert ( 5417 [Entity =>] type_LOCAL_NAME, 5418 [Read =>] function_NAME, 5419 [Write =>] function_NAME); 5420@end smallexample 5421 5422@noindent 5423This pragma provides an efficient way of providing stream functions for 5424types defined in packages. Not only is it simpler to use than declaring 5425the necessary functions with attribute representation clauses, but more 5426significantly, it allows the declaration to made in such a way that the 5427stream packages are not loaded unless they are needed. The use of 5428the Stream_Convert pragma adds no overhead at all, unless the stream 5429attributes are actually used on the designated type. 5430 5431The first argument specifies the type for which stream functions are 5432provided. The second parameter provides a function used to read values 5433of this type. It must name a function whose argument type may be any 5434subtype, and whose returned type must be the type given as the first 5435argument to the pragma. 5436 5437The meaning of the @var{Read} 5438parameter is that if a stream attribute directly 5439or indirectly specifies reading of the type given as the first parameter, 5440then a value of the type given as the argument to the Read function is 5441read from the stream, and then the Read function is used to convert this 5442to the required target type. 5443 5444Similarly the @var{Write} parameter specifies how to treat write attributes 5445that directly or indirectly apply to the type given as the first parameter. 5446It must have an input parameter of the type specified by the first parameter, 5447and the return type must be the same as the input type of the Read function. 5448The effect is to first call the Write function to convert to the given stream 5449type, and then write the result type to the stream. 5450 5451The Read and Write functions must not be overloaded subprograms. If necessary 5452renamings can be supplied to meet this requirement. 5453The usage of this attribute is best illustrated by a simple example, taken 5454from the GNAT implementation of package Ada.Strings.Unbounded: 5455 5456@smallexample @c ada 5457function To_Unbounded (S : String) 5458 return Unbounded_String 5459 renames To_Unbounded_String; 5460 5461pragma Stream_Convert 5462 (Unbounded_String, To_Unbounded, To_String); 5463@end smallexample 5464 5465@noindent 5466The specifications of the referenced functions, as given in the Ada 5467Reference Manual are: 5468 5469@smallexample @c ada 5470function To_Unbounded_String (Source : String) 5471 return Unbounded_String; 5472 5473function To_String (Source : Unbounded_String) 5474 return String; 5475@end smallexample 5476 5477@noindent 5478The effect is that if the value of an unbounded string is written to a stream, 5479then the representation of the item in the stream is in the same format that 5480would be used for @code{Standard.String'Output}, and this same representation 5481is expected when a value of this type is read from the stream. Note that the 5482value written always includes the bounds, even for Unbounded_String'Write, 5483since Unbounded_String is not an array type. 5484 5485@node Pragma Style_Checks 5486@unnumberedsec Pragma Style_Checks 5487@findex Style_Checks 5488@noindent 5489Syntax: 5490 5491@smallexample @c ada 5492pragma Style_Checks (string_LITERAL | ALL_CHECKS | 5493 On | Off [, LOCAL_NAME]); 5494@end smallexample 5495 5496@noindent 5497This pragma is used in conjunction with compiler switches to control the 5498built in style checking provided by GNAT@. The compiler switches, if set, 5499provide an initial setting for the switches, and this pragma may be used 5500to modify these settings, or the settings may be provided entirely by 5501the use of the pragma. This pragma can be used anywhere that a pragma 5502is legal, including use as a configuration pragma (including use in 5503the @file{gnat.adc} file). 5504 5505The form with a string literal specifies which style options are to be 5506activated. These are additive, so they apply in addition to any previously 5507set style check options. The codes for the options are the same as those 5508used in the @option{-gnaty} switch to @command{gcc} or @command{gnatmake}. 5509For example the following two methods can be used to enable 5510layout checking: 5511 5512@itemize @bullet 5513@item 5514@smallexample @c ada 5515pragma Style_Checks ("l"); 5516@end smallexample 5517 5518@item 5519@smallexample 5520gcc -c -gnatyl @dots{} 5521@end smallexample 5522@end itemize 5523 5524@noindent 5525The form ALL_CHECKS activates all standard checks (its use is equivalent 5526to the use of the @code{gnaty} switch with no options. @xref{Top, 5527@value{EDITION} User's Guide, About This Guide, gnat_ugn, 5528@value{EDITION} User's Guide}, for details.) 5529 5530Note: the behavior is slightly different in GNAT mode (@option{-gnatg} used). 5531In this case, ALL_CHECKS implies the standard set of GNAT mode style check 5532options (i.e. equivalent to -gnatyg). 5533 5534The forms with @code{Off} and @code{On} 5535can be used to temporarily disable style checks 5536as shown in the following example: 5537 5538@smallexample @c ada 5539@iftex 5540@leftskip=0cm 5541@end iftex 5542pragma Style_Checks ("k"); -- requires keywords in lower case 5543pragma Style_Checks (Off); -- turn off style checks 5544NULL; -- this will not generate an error message 5545pragma Style_Checks (On); -- turn style checks back on 5546NULL; -- this will generate an error message 5547@end smallexample 5548 5549@noindent 5550Finally the two argument form is allowed only if the first argument is 5551@code{On} or @code{Off}. The effect is to turn of semantic style checks 5552for the specified entity, as shown in the following example: 5553 5554@smallexample @c ada 5555@iftex 5556@leftskip=0cm 5557@end iftex 5558pragma Style_Checks ("r"); -- require consistency of identifier casing 5559Arg : Integer; 5560Rf1 : Integer := ARG; -- incorrect, wrong case 5561pragma Style_Checks (Off, Arg); 5562Rf2 : Integer := ARG; -- OK, no error 5563@end smallexample 5564 5565@node Pragma Subtitle 5566@unnumberedsec Pragma Subtitle 5567@findex Subtitle 5568@noindent 5569Syntax: 5570 5571@smallexample @c ada 5572pragma Subtitle ([Subtitle =>] STRING_LITERAL); 5573@end smallexample 5574 5575@noindent 5576This pragma is recognized for compatibility with other Ada compilers 5577but is ignored by GNAT@. 5578 5579@node Pragma Suppress 5580@unnumberedsec Pragma Suppress 5581@findex Suppress 5582@noindent 5583Syntax: 5584 5585@smallexample @c ada 5586pragma Suppress (Identifier [, [On =>] Name]); 5587@end smallexample 5588 5589@noindent 5590This is a standard pragma, and supports all the check names required in 5591the RM. It is included here because GNAT recognizes one additional check 5592name: @code{Alignment_Check} which can be used to suppress alignment checks 5593on addresses used in address clauses. Such checks can also be suppressed 5594by suppressing range checks, but the specific use of @code{Alignment_Check} 5595allows suppression of alignment checks without suppressing other range checks. 5596 5597Note that pragma Suppress gives the compiler permission to omit 5598checks, but does not require the compiler to omit checks. The compiler 5599will generate checks if they are essentially free, even when they are 5600suppressed. In particular, if the compiler can prove that a certain 5601check will necessarily fail, it will generate code to do an 5602unconditional ``raise'', even if checks are suppressed. The compiler 5603warns in this case. 5604 5605Of course, run-time checks are omitted whenever the compiler can prove 5606that they will not fail, whether or not checks are suppressed. 5607 5608@node Pragma Suppress_All 5609@unnumberedsec Pragma Suppress_All 5610@findex Suppress_All 5611@noindent 5612Syntax: 5613 5614@smallexample @c ada 5615pragma Suppress_All; 5616@end smallexample 5617 5618@noindent 5619This pragma can appear anywhere within a unit. 5620The effect is to apply @code{Suppress (All_Checks)} to the unit 5621in which it appears. This pragma is implemented for compatibility with DEC 5622Ada 83 usage where it appears at the end of a unit, and for compatibility 5623with Rational Ada, where it appears as a program unit pragma. 5624The use of the standard Ada pragma @code{Suppress (All_Checks)} 5625as a normal configuration pragma is the preferred usage in GNAT@. 5626 5627@node Pragma Suppress_Exception_Locations 5628@unnumberedsec Pragma Suppress_Exception_Locations 5629@findex Suppress_Exception_Locations 5630@noindent 5631Syntax: 5632 5633@smallexample @c ada 5634pragma Suppress_Exception_Locations; 5635@end smallexample 5636 5637@noindent 5638In normal mode, a raise statement for an exception by default generates 5639an exception message giving the file name and line number for the location 5640of the raise. This is useful for debugging and logging purposes, but this 5641entails extra space for the strings for the messages. The configuration 5642pragma @code{Suppress_Exception_Locations} can be used to suppress the 5643generation of these strings, with the result that space is saved, but the 5644exception message for such raises is null. This configuration pragma may 5645appear in a global configuration pragma file, or in a specific unit as 5646usual. It is not required that this pragma be used consistently within 5647a partition, so it is fine to have some units within a partition compiled 5648with this pragma and others compiled in normal mode without it. 5649 5650@node Pragma Suppress_Initialization 5651@unnumberedsec Pragma Suppress_Initialization 5652@findex Suppress_Initialization 5653@cindex Suppressing initialization 5654@cindex Initialization, suppression of 5655@noindent 5656Syntax: 5657 5658@smallexample @c ada 5659pragma Suppress_Initialization ([Entity =>] subtype_Name); 5660@end smallexample 5661 5662@noindent 5663Here subtype_Name is the name introduced by a type declaration 5664or subtype declaration. 5665This pragma suppresses any implicit or explicit initialization 5666for all variables of the given type or subtype, 5667including initialization resulting from the use of pragmas 5668Normalize_Scalars or Initialize_Scalars. 5669 5670This is considered a representation item, so it cannot be given after 5671the type is frozen. It applies to all subsequent object declarations, 5672and also any allocator that creates objects of the type. 5673 5674If the pragma is given for the first subtype, then it is considered 5675to apply to the base type and all its subtypes. If the pragma is given 5676for other than a first subtype, then it applies only to the given subtype. 5677The pragma may not be given after the type is frozen. 5678 5679@node Pragma Task_Info 5680@unnumberedsec Pragma Task_Info 5681@findex Task_Info 5682@noindent 5683Syntax 5684 5685@smallexample @c ada 5686pragma Task_Info (EXPRESSION); 5687@end smallexample 5688 5689@noindent 5690This pragma appears within a task definition (like pragma 5691@code{Priority}) and applies to the task in which it appears. The 5692argument must be of type @code{System.Task_Info.Task_Info_Type}. 5693The @code{Task_Info} pragma provides system dependent control over 5694aspects of tasking implementation, for example, the ability to map 5695tasks to specific processors. For details on the facilities available 5696for the version of GNAT that you are using, see the documentation 5697in the spec of package System.Task_Info in the runtime 5698library. 5699 5700@node Pragma Task_Name 5701@unnumberedsec Pragma Task_Name 5702@findex Task_Name 5703@noindent 5704Syntax 5705 5706@smallexample @c ada 5707pragma Task_Name (string_EXPRESSION); 5708@end smallexample 5709 5710@noindent 5711This pragma appears within a task definition (like pragma 5712@code{Priority}) and applies to the task in which it appears. The 5713argument must be of type String, and provides a name to be used for 5714the task instance when the task is created. Note that this expression 5715is not required to be static, and in particular, it can contain 5716references to task discriminants. This facility can be used to 5717provide different names for different tasks as they are created, 5718as illustrated in the example below. 5719 5720The task name is recorded internally in the run-time structures 5721and is accessible to tools like the debugger. In addition the 5722routine @code{Ada.Task_Identification.Image} will return this 5723string, with a unique task address appended. 5724 5725@smallexample @c ada 5726-- Example of the use of pragma Task_Name 5727 5728with Ada.Task_Identification; 5729use Ada.Task_Identification; 5730with Text_IO; use Text_IO; 5731procedure t3 is 5732 5733 type Astring is access String; 5734 5735 task type Task_Typ (Name : access String) is 5736 pragma Task_Name (Name.all); 5737 end Task_Typ; 5738 5739 task body Task_Typ is 5740 Nam : constant String := Image (Current_Task); 5741 begin 5742 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 5743 end Task_Typ; 5744 5745 type Ptr_Task is access Task_Typ; 5746 Task_Var : Ptr_Task; 5747 5748begin 5749 Task_Var := 5750 new Task_Typ (new String'("This is task 1")); 5751 Task_Var := 5752 new Task_Typ (new String'("This is task 2")); 5753end; 5754@end smallexample 5755 5756@node Pragma Task_Storage 5757@unnumberedsec Pragma Task_Storage 5758@findex Task_Storage 5759Syntax: 5760 5761@smallexample @c ada 5762pragma Task_Storage ( 5763 [Task_Type =>] LOCAL_NAME, 5764 [Top_Guard =>] static_integer_EXPRESSION); 5765@end smallexample 5766 5767@noindent 5768This pragma specifies the length of the guard area for tasks. The guard 5769area is an additional storage area allocated to a task. A value of zero 5770means that either no guard area is created or a minimal guard area is 5771created, depending on the target. This pragma can appear anywhere a 5772@code{Storage_Size} attribute definition clause is allowed for a task 5773type. 5774 5775@node Pragma Test_Case 5776@unnumberedsec Pragma Test_Case 5777@cindex Test cases 5778@findex Test_Case 5779@noindent 5780Syntax: 5781 5782@smallexample @c ada 5783pragma Test_Case ( 5784 [Name =>] static_string_Expression 5785 ,[Mode =>] (Nominal | Robustness) 5786 [, Requires => Boolean_Expression] 5787 [, Ensures => Boolean_Expression]); 5788@end smallexample 5789 5790@noindent 5791The @code{Test_Case} pragma allows defining fine-grain specifications 5792for use by testing tools. Its syntax is similar to the syntax of the 5793@code{Contract_Case} pragma, which is used for both testing and 5794formal verification. 5795The compiler checks the validity of the @code{Test_Case} pragma, but its 5796presence does not lead to any modification of the code generated by the 5797compiler, contrary to the treatment of the @code{Contract_Case} pragma. 5798 5799@code{Test_Case} pragmas may only appear immediately following the 5800(separate) declaration of a subprogram in a package declaration, inside 5801a package spec unit. Only other pragmas may intervene (that is appear 5802between the subprogram declaration and a test case). 5803 5804The compiler checks that boolean expressions given in @code{Requires} and 5805@code{Ensures} are valid, where the rules for @code{Requires} are the 5806same as the rule for an expression in @code{Precondition} and the rules 5807for @code{Ensures} are the same as the rule for an expression in 5808@code{Postcondition}. In particular, attributes @code{'Old} and 5809@code{'Result} can only be used within the @code{Ensures} 5810expression. The following is an example of use within a package spec: 5811 5812@smallexample @c ada 5813package Math_Functions is 5814 ... 5815 function Sqrt (Arg : Float) return Float; 5816 pragma Test_Case (Name => "Test 1", 5817 Mode => Nominal, 5818 Requires => Arg < 10000, 5819 Ensures => Sqrt'Result < 10); 5820 ... 5821end Math_Functions; 5822@end smallexample 5823 5824@noindent 5825The meaning of a test case is that there is at least one context where 5826@code{Requires} holds such that, if the associated subprogram is executed in 5827that context, then @code{Ensures} holds when the subprogram returns. 5828Mode @code{Nominal} indicates that the input context should also satisfy the 5829precondition of the subprogram, and the output context should also satisfy its 5830postcondition. More @code{Robustness} indicates that the precondition and 5831postcondition of the subprogram should be ignored for this test case. 5832 5833@node Pragma Thread_Local_Storage 5834@unnumberedsec Pragma Thread_Local_Storage 5835@findex Thread_Local_Storage 5836@cindex Task specific storage 5837@cindex TLS (Thread Local Storage) 5838Syntax: 5839 5840@smallexample @c ada 5841pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); 5842@end smallexample 5843 5844@noindent 5845This pragma specifies that the specified entity, which must be 5846a variable declared in a library level package, is to be marked as 5847"Thread Local Storage" (@code{TLS}). On systems supporting this (which 5848include Solaris, GNU/Linux and VxWorks 6), this causes each thread 5849(and hence each Ada task) to see a distinct copy of the variable. 5850 5851The variable may not have default initialization, and if there is 5852an explicit initialization, it must be either @code{null} for an 5853access variable, or a static expression for a scalar variable. 5854This provides a low level mechanism similar to that provided by 5855the @code{Ada.Task_Attributes} package, but much more efficient 5856and is also useful in writing interface code that will interact 5857with foreign threads. 5858 5859If this pragma is used on a system where @code{TLS} is not supported, 5860then an error message will be generated and the program will be rejected. 5861 5862@node Pragma Time_Slice 5863@unnumberedsec Pragma Time_Slice 5864@findex Time_Slice 5865@noindent 5866Syntax: 5867 5868@smallexample @c ada 5869pragma Time_Slice (static_duration_EXPRESSION); 5870@end smallexample 5871 5872@noindent 5873For implementations of GNAT on operating systems where it is possible 5874to supply a time slice value, this pragma may be used for this purpose. 5875It is ignored if it is used in a system that does not allow this control, 5876or if it appears in other than the main program unit. 5877@cindex OpenVMS 5878Note that the effect of this pragma is identical to the effect of the 5879DEC Ada 83 pragma of the same name when operating under OpenVMS systems. 5880 5881@node Pragma Title 5882@unnumberedsec Pragma Title 5883@findex Title 5884@noindent 5885Syntax: 5886 5887@smallexample @c ada 5888pragma Title (TITLING_OPTION [, TITLING OPTION]); 5889 5890TITLING_OPTION ::= 5891 [Title =>] STRING_LITERAL, 5892| [Subtitle =>] STRING_LITERAL 5893@end smallexample 5894 5895@noindent 5896Syntax checked but otherwise ignored by GNAT@. This is a listing control 5897pragma used in DEC Ada 83 implementations to provide a title and/or 5898subtitle for the program listing. The program listing generated by GNAT 5899does not have titles or subtitles. 5900 5901Unlike other pragmas, the full flexibility of named notation is allowed 5902for this pragma, i.e.@: the parameters may be given in any order if named 5903notation is used, and named and positional notation can be mixed 5904following the normal rules for procedure calls in Ada. 5905 5906@node Pragma Unchecked_Union 5907@unnumberedsec Pragma Unchecked_Union 5908@cindex Unions in C 5909@findex Unchecked_Union 5910@noindent 5911Syntax: 5912 5913@smallexample @c ada 5914pragma Unchecked_Union (first_subtype_LOCAL_NAME); 5915@end smallexample 5916 5917@noindent 5918This pragma is used to specify a representation of a record type that is 5919equivalent to a C union. It was introduced as a GNAT implementation defined 5920pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this 5921pragma, making it language defined, and GNAT fully implements this extended 5922version in all language modes (Ada 83, Ada 95, and Ada 2005). For full 5923details, consult the Ada 2012 Reference Manual, section B.3.3. 5924 5925@node Pragma Unimplemented_Unit 5926@unnumberedsec Pragma Unimplemented_Unit 5927@findex Unimplemented_Unit 5928@noindent 5929Syntax: 5930 5931@smallexample @c ada 5932pragma Unimplemented_Unit; 5933@end smallexample 5934 5935@noindent 5936If this pragma occurs in a unit that is processed by the compiler, GNAT 5937aborts with the message @samp{@var{xxx} not implemented}, where 5938@var{xxx} is the name of the current compilation unit. This pragma is 5939intended to allow the compiler to handle unimplemented library units in 5940a clean manner. 5941 5942The abort only happens if code is being generated. Thus you can use 5943specs of unimplemented packages in syntax or semantic checking mode. 5944 5945@node Pragma Universal_Aliasing 5946@unnumberedsec Pragma Universal_Aliasing 5947@findex Universal_Aliasing 5948@noindent 5949Syntax: 5950 5951@smallexample @c ada 5952pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; 5953@end smallexample 5954 5955@noindent 5956@var{type_LOCAL_NAME} must refer to a type declaration in the current 5957declarative part. The effect is to inhibit strict type-based aliasing 5958optimization for the given type. In other words, the effect is as though 5959access types designating this type were subject to pragma No_Strict_Aliasing. 5960For a detailed description of the strict aliasing optimization, and the 5961situations in which it must be suppressed, @xref{Optimization and Strict 5962Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}. 5963 5964@node Pragma Universal_Data 5965@unnumberedsec Pragma Universal_Data 5966@findex Universal_Data 5967@noindent 5968Syntax: 5969 5970@smallexample @c ada 5971pragma Universal_Data [(library_unit_Name)]; 5972@end smallexample 5973 5974@noindent 5975This pragma is supported only for the AAMP target and is ignored for 5976other targets. The pragma specifies that all library-level objects 5977(Counter 0 data) associated with the library unit are to be accessed 5978and updated using universal addressing (24-bit addresses for AAMP5) 5979rather than the default of 16-bit Data Environment (DENV) addressing. 5980Use of this pragma will generally result in less efficient code for 5981references to global data associated with the library unit, but 5982allows such data to be located anywhere in memory. This pragma is 5983a library unit pragma, but can also be used as a configuration pragma 5984(including use in the @file{gnat.adc} file). The functionality 5985of this pragma is also available by applying the -univ switch on the 5986compilations of units where universal addressing of the data is desired. 5987 5988@node Pragma Unmodified 5989@unnumberedsec Pragma Unmodified 5990@findex Unmodified 5991@cindex Warnings, unmodified 5992@noindent 5993Syntax: 5994 5995@smallexample @c ada 5996pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); 5997@end smallexample 5998 5999@noindent 6000This pragma signals that the assignable entities (variables, 6001@code{out} parameters, @code{in out} parameters) whose names are listed are 6002deliberately not assigned in the current source unit. This 6003suppresses warnings about the 6004entities being referenced but not assigned, and in addition a warning will be 6005generated if one of these entities is in fact assigned in the 6006same unit as the pragma (or in the corresponding body, or one 6007of its subunits). 6008 6009This is particularly useful for clearly signaling that a particular 6010parameter is not modified, even though the spec suggests that it might 6011be. 6012 6013@node Pragma Unreferenced 6014@unnumberedsec Pragma Unreferenced 6015@findex Unreferenced 6016@cindex Warnings, unreferenced 6017@noindent 6018Syntax: 6019 6020@smallexample @c ada 6021pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); 6022pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); 6023@end smallexample 6024 6025@noindent 6026This pragma signals that the entities whose names are listed are 6027deliberately not referenced in the current source unit. This 6028suppresses warnings about the 6029entities being unreferenced, and in addition a warning will be 6030generated if one of these entities is in fact subsequently referenced in the 6031same unit as the pragma (or in the corresponding body, or one 6032of its subunits). 6033 6034This is particularly useful for clearly signaling that a particular 6035parameter is not referenced in some particular subprogram implementation 6036and that this is deliberate. It can also be useful in the case of 6037objects declared only for their initialization or finalization side 6038effects. 6039 6040If @code{LOCAL_NAME} identifies more than one matching homonym in the 6041current scope, then the entity most recently declared is the one to which 6042the pragma applies. Note that in the case of accept formals, the pragma 6043Unreferenced may appear immediately after the keyword @code{do} which 6044allows the indication of whether or not accept formals are referenced 6045or not to be given individually for each accept statement. 6046 6047The left hand side of an assignment does not count as a reference for the 6048purpose of this pragma. Thus it is fine to assign to an entity for which 6049pragma Unreferenced is given. 6050 6051Note that if a warning is desired for all calls to a given subprogram, 6052regardless of whether they occur in the same unit as the subprogram 6053declaration, then this pragma should not be used (calls from another 6054unit would not be flagged); pragma Obsolescent can be used instead 6055for this purpose, see @xref{Pragma Obsolescent}. 6056 6057The second form of pragma @code{Unreferenced} is used within a context 6058clause. In this case the arguments must be unit names of units previously 6059mentioned in @code{with} clauses (similar to the usage of pragma 6060@code{Elaborate_All}. The effect is to suppress warnings about unreferenced 6061units and unreferenced entities within these units. 6062 6063@node Pragma Unreferenced_Objects 6064@unnumberedsec Pragma Unreferenced_Objects 6065@findex Unreferenced_Objects 6066@cindex Warnings, unreferenced 6067@noindent 6068Syntax: 6069 6070@smallexample @c ada 6071pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); 6072@end smallexample 6073 6074@noindent 6075This pragma signals that for the types or subtypes whose names are 6076listed, objects which are declared with one of these types or subtypes may 6077not be referenced, and if no references appear, no warnings are given. 6078 6079This is particularly useful for objects which are declared solely for their 6080initialization and finalization effect. Such variables are sometimes referred 6081to as RAII variables (Resource Acquisition Is Initialization). Using this 6082pragma on the relevant type (most typically a limited controlled type), the 6083compiler will automatically suppress unwanted warnings about these variables 6084not being referenced. 6085 6086@node Pragma Unreserve_All_Interrupts 6087@unnumberedsec Pragma Unreserve_All_Interrupts 6088@findex Unreserve_All_Interrupts 6089@noindent 6090Syntax: 6091 6092@smallexample @c ada 6093pragma Unreserve_All_Interrupts; 6094@end smallexample 6095 6096@noindent 6097Normally certain interrupts are reserved to the implementation. Any attempt 6098to attach an interrupt causes Program_Error to be raised, as described in 6099RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 6100many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is 6101reserved to the implementation, so that @kbd{Ctrl-C} can be used to 6102interrupt execution. 6103 6104If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in 6105a program, then all such interrupts are unreserved. This allows the 6106program to handle these interrupts, but disables their standard 6107functions. For example, if this pragma is used, then pressing 6108@kbd{Ctrl-C} will not automatically interrupt execution. However, 6109a program can then handle the @code{SIGINT} interrupt as it chooses. 6110 6111For a full list of the interrupts handled in a specific implementation, 6112see the source code for the spec of @code{Ada.Interrupts.Names} in 6113file @file{a-intnam.ads}. This is a target dependent file that contains the 6114list of interrupts recognized for a given target. The documentation in 6115this file also specifies what interrupts are affected by the use of 6116the @code{Unreserve_All_Interrupts} pragma. 6117 6118For a more general facility for controlling what interrupts can be 6119handled, see pragma @code{Interrupt_State}, which subsumes the functionality 6120of the @code{Unreserve_All_Interrupts} pragma. 6121 6122@node Pragma Unsuppress 6123@unnumberedsec Pragma Unsuppress 6124@findex Unsuppress 6125@noindent 6126Syntax: 6127 6128@smallexample @c ada 6129pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 6130@end smallexample 6131 6132@noindent 6133This pragma undoes the effect of a previous pragma @code{Suppress}. If 6134there is no corresponding pragma @code{Suppress} in effect, it has no 6135effect. The range of the effect is the same as for pragma 6136@code{Suppress}. The meaning of the arguments is identical to that used 6137in pragma @code{Suppress}. 6138 6139One important application is to ensure that checks are on in cases where 6140code depends on the checks for its correct functioning, so that the code 6141will compile correctly even if the compiler switches are set to suppress 6142checks. 6143 6144This pragma is standard in Ada 2005. It is available in all earlier versions 6145of Ada as an implementation-defined pragma. 6146 6147@node Pragma Use_VADS_Size 6148@unnumberedsec Pragma Use_VADS_Size 6149@cindex @code{Size}, VADS compatibility 6150@cindex Rational profile 6151@findex Use_VADS_Size 6152@noindent 6153Syntax: 6154 6155@smallexample @c ada 6156pragma Use_VADS_Size; 6157@end smallexample 6158 6159@noindent 6160This is a configuration pragma. In a unit to which it applies, any use 6161of the 'Size attribute is automatically interpreted as a use of the 6162'VADS_Size attribute. Note that this may result in incorrect semantic 6163processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in 6164the handling of existing code which depends on the interpretation of Size 6165as implemented in the VADS compiler. See description of the VADS_Size 6166attribute for further details. 6167 6168@node Pragma Validity_Checks 6169@unnumberedsec Pragma Validity_Checks 6170@findex Validity_Checks 6171@noindent 6172Syntax: 6173 6174@smallexample @c ada 6175pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 6176@end smallexample 6177 6178@noindent 6179This pragma is used in conjunction with compiler switches to control the 6180built-in validity checking provided by GNAT@. The compiler switches, if set 6181provide an initial setting for the switches, and this pragma may be used 6182to modify these settings, or the settings may be provided entirely by 6183the use of the pragma. This pragma can be used anywhere that a pragma 6184is legal, including use as a configuration pragma (including use in 6185the @file{gnat.adc} file). 6186 6187The form with a string literal specifies which validity options are to be 6188activated. The validity checks are first set to include only the default 6189reference manual settings, and then a string of letters in the string 6190specifies the exact set of options required. The form of this string 6191is exactly as described for the @option{-gnatVx} compiler switch (see the 6192@value{EDITION} User's Guide for details). For example the following two 6193methods can be used to enable validity checking for mode @code{in} and 6194@code{in out} subprogram parameters: 6195 6196@itemize @bullet 6197@item 6198@smallexample @c ada 6199pragma Validity_Checks ("im"); 6200@end smallexample 6201 6202@item 6203@smallexample 6204gcc -c -gnatVim @dots{} 6205@end smallexample 6206@end itemize 6207 6208@noindent 6209The form ALL_CHECKS activates all standard checks (its use is equivalent 6210to the use of the @code{gnatva} switch. 6211 6212The forms with @code{Off} and @code{On} 6213can be used to temporarily disable validity checks 6214as shown in the following example: 6215 6216@smallexample @c ada 6217@iftex 6218@leftskip=0cm 6219@end iftex 6220pragma Validity_Checks ("c"); -- validity checks for copies 6221pragma Validity_Checks (Off); -- turn off validity checks 6222A := B; -- B will not be validity checked 6223pragma Validity_Checks (On); -- turn validity checks back on 6224A := C; -- C will be validity checked 6225@end smallexample 6226 6227@node Pragma Volatile 6228@unnumberedsec Pragma Volatile 6229@findex Volatile 6230@noindent 6231Syntax: 6232 6233@smallexample @c ada 6234pragma Volatile (LOCAL_NAME); 6235@end smallexample 6236 6237@noindent 6238This pragma is defined by the Ada Reference Manual, and the GNAT 6239implementation is fully conformant with this definition. The reason it 6240is mentioned in this section is that a pragma of the same name was supplied 6241in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 6242implementation of pragma Volatile is upwards compatible with the 6243implementation in DEC Ada 83. 6244 6245@node Pragma Warnings 6246@unnumberedsec Pragma Warnings 6247@findex Warnings 6248@noindent 6249Syntax: 6250 6251@smallexample @c ada 6252pragma Warnings (On | Off); 6253pragma Warnings (On | Off, LOCAL_NAME); 6254pragma Warnings (static_string_EXPRESSION); 6255pragma Warnings (On | Off, static_string_EXPRESSION); 6256@end smallexample 6257 6258@noindent 6259Normally warnings are enabled, with the output being controlled by 6260the command line switch. Warnings (@code{Off}) turns off generation of 6261warnings until a Warnings (@code{On}) is encountered or the end of the 6262current unit. If generation of warnings is turned off using this 6263pragma, then no warning messages are output, regardless of the 6264setting of the command line switches. 6265 6266The form with a single argument may be used as a configuration pragma. 6267 6268If the @var{LOCAL_NAME} parameter is present, warnings are suppressed for 6269the specified entity. This suppression is effective from the point where 6270it occurs till the end of the extended scope of the variable (similar to 6271the scope of @code{Suppress}). 6272 6273The form with a single static_string_EXPRESSION argument provides more precise 6274control over which warnings are active. The string is a list of letters 6275specifying which warnings are to be activated and which deactivated. The 6276code for these letters is the same as the string used in the command 6277line switch controlling warnings. For a brief summary, use the gnatmake 6278command with no arguments, which will generate usage information containing 6279the list of warnings switches supported. For 6280full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION} 6281User's Guide}. 6282 6283@noindent 6284The warnings controlled by the `-gnatw' switch are generated by the front end 6285of the compiler. The `GCC' back end can provide additional warnings and they 6286are controlled by the `-W' switch. 6287The form with a single static_string_EXPRESSION argument also works for the 6288latters, but the string must be a single full `-W' switch in this case. 6289The above reference lists a few examples of these additional warnings. 6290 6291@noindent 6292The specified warnings will be in effect until the end of the program 6293or another pragma Warnings is encountered. The effect of the pragma is 6294cumulative. Initially the set of warnings is the standard default set 6295as possibly modified by compiler switches. Then each pragma Warning 6296modifies this set of warnings as specified. This form of the pragma may 6297also be used as a configuration pragma. 6298 6299The fourth form, with an @code{On|Off} parameter and a string, is used to 6300control individual messages, based on their text. The string argument 6301is a pattern that is used to match against the text of individual 6302warning messages (not including the initial "warning: " tag). 6303 6304The pattern may contain asterisks, which match zero or more characters in 6305the message. For example, you can use 6306@code{pragma Warnings (Off, "*bits of*unused")} to suppress the warning 6307message @code{warning: 960 bits of "a" unused}. No other regular 6308expression notations are permitted. All characters other than asterisk in 6309these three specific cases are treated as literal characters in the match. 6310 6311The above use of patterns to match the message applies only to warning 6312messages generated by the front end. This form of the pragma with a 6313string argument can also be used to control back end warnings controlled 6314by a "-Wxxx" switch. Such warnings can be identified by the appearence 6315of a string of the form "[-Wxxx]" in the message which identifies the 6316"-W" switch that controls the message. By using the text of the 6317"-W" switch in the pragma, such back end warnings can be turned on and off. 6318 6319There are two ways to use the pragma in this form. The OFF form can be used as a 6320configuration pragma. The effect is to suppress all warnings (if any) 6321that match the pattern string throughout the compilation (or match the 6322-W switch in the back end case). 6323 6324The second usage is to suppress a warning locally, and in this case, two 6325pragmas must appear in sequence: 6326 6327@smallexample @c ada 6328pragma Warnings (Off, Pattern); 6329@dots{} code where given warning is to be suppressed 6330pragma Warnings (On, Pattern); 6331@end smallexample 6332 6333@noindent 6334In this usage, the pattern string must match in the Off and On pragmas, 6335and at least one matching warning must be suppressed. 6336 6337Note: to write a string that will match any warning, use the string 6338@code{"***"}. It will not work to use a single asterisk or two asterisks 6339since this looks like an operator name. This form with three asterisks 6340is similar in effect to specifying @code{pragma Warnings (Off)} except that a 6341matching @code{pragma Warnings (On, "***")} will be required. This can be 6342helpful in avoiding forgetting to turn warnings back on. 6343 6344Note: the debug flag -gnatd.i (@code{/NOWARNINGS_PRAGMAS} in VMS) can be 6345used to cause the compiler to entirely ignore all WARNINGS pragmas. This can 6346be useful in checking whether obsolete pragmas in existing programs are hiding 6347real problems. 6348 6349Note: pragma Warnings does not affect the processing of style messages. See 6350separate entry for pragma Style_Checks for control of style messages. 6351 6352@node Pragma Weak_External 6353@unnumberedsec Pragma Weak_External 6354@findex Weak_External 6355@noindent 6356Syntax: 6357 6358@smallexample @c ada 6359pragma Weak_External ([Entity =>] LOCAL_NAME); 6360@end smallexample 6361 6362@noindent 6363@var{LOCAL_NAME} must refer to an object that is declared at the library 6364level. This pragma specifies that the given entity should be marked as a 6365weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} 6366in GNU C and causes @var{LOCAL_NAME} to be emitted as a weak symbol instead 6367of a regular symbol, that is to say a symbol that does not have to be 6368resolved by the linker if used in conjunction with a pragma Import. 6369 6370When a weak symbol is not resolved by the linker, its address is set to 6371zero. This is useful in writing interfaces to external modules that may 6372or may not be linked in the final executable, for example depending on 6373configuration settings. 6374 6375If a program references at run time an entity to which this pragma has been 6376applied, and the corresponding symbol was not resolved at link time, then 6377the execution of the program is erroneous. It is not erroneous to take the 6378Address of such an entity, for example to guard potential references, 6379as shown in the example below. 6380 6381Some file formats do not support weak symbols so not all target machines 6382support this pragma. 6383 6384@smallexample @c ada 6385-- Example of the use of pragma Weak_External 6386 6387package External_Module is 6388 key : Integer; 6389 pragma Import (C, key); 6390 pragma Weak_External (key); 6391 function Present return boolean; 6392end External_Module; 6393 6394with System; use System; 6395package body External_Module is 6396 function Present return boolean is 6397 begin 6398 return key'Address /= System.Null_Address; 6399 end Present; 6400end External_Module; 6401@end smallexample 6402 6403@node Pragma Wide_Character_Encoding 6404@unnumberedsec Pragma Wide_Character_Encoding 6405@findex Wide_Character_Encoding 6406@noindent 6407Syntax: 6408 6409@smallexample @c ada 6410pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); 6411@end smallexample 6412 6413@noindent 6414This pragma specifies the wide character encoding to be used in program 6415source text appearing subsequently. It is a configuration pragma, but may 6416also be used at any point that a pragma is allowed, and it is permissible 6417to have more than one such pragma in a file, allowing multiple encodings 6418to appear within the same file. 6419 6420The argument can be an identifier or a character literal. In the identifier 6421case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, 6422@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal 6423case it is correspondingly one of the characters @samp{h}, @samp{u}, 6424@samp{s}, @samp{e}, @samp{8}, or @samp{b}. 6425 6426Note that when the pragma is used within a file, it affects only the 6427encoding within that file, and does not affect withed units, specs, 6428or subunits. 6429 6430@node Implementation Defined Attributes 6431@chapter Implementation Defined Attributes 6432Ada defines (throughout the Ada reference manual, 6433summarized in Annex K), 6434a set of attributes that provide useful additional functionality in all 6435areas of the language. These language defined attributes are implemented 6436in GNAT and work as described in the Ada Reference Manual. 6437 6438In addition, Ada allows implementations to define additional 6439attributes whose meaning is defined by the implementation. GNAT provides 6440a number of these implementation-dependent attributes which can be used 6441to extend and enhance the functionality of the compiler. This section of 6442the GNAT reference manual describes these additional attributes. 6443 6444Note that any program using these attributes may not be portable to 6445other compilers (although GNAT implements this set of attributes on all 6446platforms). Therefore if portability to other compilers is an important 6447consideration, you should minimize the use of these attributes. 6448 6449@menu 6450* Abort_Signal:: 6451* Address_Size:: 6452* Asm_Input:: 6453* Asm_Output:: 6454* AST_Entry:: 6455* Bit:: 6456* Bit_Position:: 6457* Compiler_Version:: 6458* Code_Address:: 6459* Default_Bit_Order:: 6460* Descriptor_Size:: 6461* Elaborated:: 6462* Elab_Body:: 6463* Elab_Spec:: 6464* Elab_Subp_Body:: 6465* Emax:: 6466* Enabled:: 6467* Enum_Rep:: 6468* Enum_Val:: 6469* Epsilon:: 6470* Fixed_Value:: 6471* Has_Access_Values:: 6472* Has_Discriminants:: 6473* Img:: 6474* Integer_Value:: 6475* Invalid_Value:: 6476* Large:: 6477* Machine_Size:: 6478* Mantissa:: 6479* Max_Interrupt_Priority:: 6480* Max_Priority:: 6481* Maximum_Alignment:: 6482* Mechanism_Code:: 6483* Null_Parameter:: 6484* Object_Size:: 6485* Passed_By_Reference:: 6486* Pool_Address:: 6487* Range_Length:: 6488* Ref:: 6489* Result:: 6490* Safe_Emax:: 6491* Safe_Large:: 6492* Scalar_Storage_Order:: 6493* Simple_Storage_Pool:: 6494* Small:: 6495* Storage_Unit:: 6496* Stub_Type:: 6497* System_Allocator_Alignment:: 6498* Target_Name:: 6499* Tick:: 6500* To_Address:: 6501* Type_Class:: 6502* UET_Address:: 6503* Unconstrained_Array:: 6504* Universal_Literal_String:: 6505* Unrestricted_Access:: 6506* Valid_Scalars:: 6507* VADS_Size:: 6508* Value_Size:: 6509* Wchar_T_Size:: 6510* Word_Size:: 6511@end menu 6512 6513@node Abort_Signal 6514@unnumberedsec Abort_Signal 6515@findex Abort_Signal 6516@noindent 6517@code{Standard'Abort_Signal} (@code{Standard} is the only allowed 6518prefix) provides the entity for the special exception used to signal 6519task abort or asynchronous transfer of control. Normally this attribute 6520should only be used in the tasking runtime (it is highly peculiar, and 6521completely outside the normal semantics of Ada, for a user program to 6522intercept the abort exception). 6523 6524@node Address_Size 6525@unnumberedsec Address_Size 6526@cindex Size of @code{Address} 6527@findex Address_Size 6528@noindent 6529@code{Standard'Address_Size} (@code{Standard} is the only allowed 6530prefix) is a static constant giving the number of bits in an 6531@code{Address}. It is the same value as System.Address'Size, 6532but has the advantage of being static, while a direct 6533reference to System.Address'Size is non-static because Address 6534is a private type. 6535 6536@node Asm_Input 6537@unnumberedsec Asm_Input 6538@findex Asm_Input 6539@noindent 6540The @code{Asm_Input} attribute denotes a function that takes two 6541parameters. The first is a string, the second is an expression of the 6542type designated by the prefix. The first (string) argument is required 6543to be a static expression, and is the constraint for the parameter, 6544(e.g.@: what kind of register is required). The second argument is the 6545value to be used as the input argument. The possible values for the 6546constant are the same as those used in the RTL, and are dependent on 6547the configuration file used to built the GCC back end. 6548@ref{Machine Code Insertions} 6549 6550@node Asm_Output 6551@unnumberedsec Asm_Output 6552@findex Asm_Output 6553@noindent 6554The @code{Asm_Output} attribute denotes a function that takes two 6555parameters. The first is a string, the second is the name of a variable 6556of the type designated by the attribute prefix. The first (string) 6557argument is required to be a static expression and designates the 6558constraint for the parameter (e.g.@: what kind of register is 6559required). The second argument is the variable to be updated with the 6560result. The possible values for constraint are the same as those used in 6561the RTL, and are dependent on the configuration file used to build the 6562GCC back end. If there are no output operands, then this argument may 6563either be omitted, or explicitly given as @code{No_Output_Operands}. 6564@ref{Machine Code Insertions} 6565 6566@node AST_Entry 6567@unnumberedsec AST_Entry 6568@cindex OpenVMS 6569@findex AST_Entry 6570@noindent 6571This attribute is implemented only in OpenVMS versions of GNAT@. Applied to 6572the name of an entry, it yields a value of the predefined type AST_Handler 6573(declared in the predefined package System, as extended by the use of 6574pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to 6575be called when an AST occurs. For further details, refer to the @cite{DEC Ada 6576Language Reference Manual}, section 9.12a. 6577 6578@node Bit 6579@unnumberedsec Bit 6580@findex Bit 6581@code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit 6582offset within the storage unit (byte) that contains the first bit of 6583storage allocated for the object. The value of this attribute is of the 6584type @code{Universal_Integer}, and is always a non-negative number not 6585exceeding the value of @code{System.Storage_Unit}. 6586 6587For an object that is a variable or a constant allocated in a register, 6588the value is zero. (The use of this attribute does not force the 6589allocation of a variable to memory). 6590 6591For an object that is a formal parameter, this attribute applies 6592to either the matching actual parameter or to a copy of the 6593matching actual parameter. 6594 6595For an access object the value is zero. Note that 6596@code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the 6597designated object. Similarly for a record component 6598@code{@var{X}.@var{C}'Bit} is subject to a discriminant check and 6599@code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit} 6600are subject to index checks. 6601 6602This attribute is designed to be compatible with the DEC Ada 83 definition 6603and implementation of the @code{Bit} attribute. 6604 6605@node Bit_Position 6606@unnumberedsec Bit_Position 6607@findex Bit_Position 6608@noindent 6609@code{@var{R.C}'Bit_Position}, where @var{R} is a record object and C is one 6610of the fields of the record type, yields the bit 6611offset within the record contains the first bit of 6612storage allocated for the object. The value of this attribute is of the 6613type @code{Universal_Integer}. The value depends only on the field 6614@var{C} and is independent of the alignment of 6615the containing record @var{R}. 6616 6617@node Compiler_Version 6618@unnumberedsec Compiler_Version 6619@findex Compiler_Version 6620@noindent 6621@code{Standard'Compiler_Version} (@code{Standard} is the only allowed 6622prefix) yields a static string identifying the version of the compiler 6623being used to compile the unit containing the attribute reference. A 6624typical result would be something like "@value{EDITION} @i{version} (20090221)". 6625 6626@node Code_Address 6627@unnumberedsec Code_Address 6628@findex Code_Address 6629@cindex Subprogram address 6630@cindex Address of subprogram code 6631@noindent 6632The @code{'Address} 6633attribute may be applied to subprograms in Ada 95 and Ada 2005, but the 6634intended effect seems to be to provide 6635an address value which can be used to call the subprogram by means of 6636an address clause as in the following example: 6637 6638@smallexample @c ada 6639procedure K is @dots{} 6640 6641procedure L; 6642for L'Address use K'Address; 6643pragma Import (Ada, L); 6644@end smallexample 6645 6646@noindent 6647A call to @code{L} is then expected to result in a call to @code{K}@. 6648In Ada 83, where there were no access-to-subprogram values, this was 6649a common work-around for getting the effect of an indirect call. 6650GNAT implements the above use of @code{Address} and the technique 6651illustrated by the example code works correctly. 6652 6653However, for some purposes, it is useful to have the address of the start 6654of the generated code for the subprogram. On some architectures, this is 6655not necessarily the same as the @code{Address} value described above. 6656For example, the @code{Address} value may reference a subprogram 6657descriptor rather than the subprogram itself. 6658 6659The @code{'Code_Address} attribute, which can only be applied to 6660subprogram entities, always returns the address of the start of the 6661generated code of the specified subprogram, which may or may not be 6662the same value as is returned by the corresponding @code{'Address} 6663attribute. 6664 6665@node Default_Bit_Order 6666@unnumberedsec Default_Bit_Order 6667@cindex Big endian 6668@cindex Little endian 6669@findex Default_Bit_Order 6670@noindent 6671@code{Standard'Default_Bit_Order} (@code{Standard} is the only 6672permissible prefix), provides the value @code{System.Default_Bit_Order} 6673as a @code{Pos} value (0 for @code{High_Order_First}, 1 for 6674@code{Low_Order_First}). This is used to construct the definition of 6675@code{Default_Bit_Order} in package @code{System}. 6676 6677@node Descriptor_Size 6678@unnumberedsec Descriptor_Size 6679@cindex Descriptor 6680@cindex Dope vector 6681@findex Descriptor_Size 6682@noindent 6683Non-static attribute @code{Descriptor_Size} returns the size in bits of the 6684descriptor allocated for a type. The result is non-zero only for unconstrained 6685array types and the returned value is of type universal integer. In GNAT, an 6686array descriptor contains bounds information and is located immediately before 6687the first element of the array. 6688 6689@smallexample @c ada 6690type Unconstr_Array is array (Positive range <>) of Boolean; 6691Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); 6692@end smallexample 6693 6694@noindent 6695The attribute takes into account any additional padding due to type alignment. 6696In the example above, the descriptor contains two values of type 6697@code{Positive} representing the low and high bound. Since @code{Positive} has 6698a size of 31 bits and an alignment of 4, the descriptor size is @code{2 * 6699Positive'Size + 2} or 64 bits. 6700 6701@node Elaborated 6702@unnumberedsec Elaborated 6703@findex Elaborated 6704@noindent 6705The prefix of the @code{'Elaborated} attribute must be a unit name. The 6706value is a Boolean which indicates whether or not the given unit has been 6707elaborated. This attribute is primarily intended for internal use by the 6708generated code for dynamic elaboration checking, but it can also be used 6709in user programs. The value will always be True once elaboration of all 6710units has been completed. An exception is for units which need no 6711elaboration, the value is always False for such units. 6712 6713@node Elab_Body 6714@unnumberedsec Elab_Body 6715@findex Elab_Body 6716@noindent 6717This attribute can only be applied to a program unit name. It returns 6718the entity for the corresponding elaboration procedure for elaborating 6719the body of the referenced unit. This is used in the main generated 6720elaboration procedure by the binder and is not normally used in any 6721other context. However, there may be specialized situations in which it 6722is useful to be able to call this elaboration procedure from Ada code, 6723e.g.@: if it is necessary to do selective re-elaboration to fix some 6724error. 6725 6726@node Elab_Spec 6727@unnumberedsec Elab_Spec 6728@findex Elab_Spec 6729@noindent 6730This attribute can only be applied to a program unit name. It returns 6731the entity for the corresponding elaboration procedure for elaborating 6732the spec of the referenced unit. This is used in the main 6733generated elaboration procedure by the binder and is not normally used 6734in any other context. However, there may be specialized situations in 6735which it is useful to be able to call this elaboration procedure from 6736Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix 6737some error. 6738 6739@node Elab_Subp_Body 6740@unnumberedsec Elab_Subp_Body 6741@findex Elab_Subp_Body 6742@noindent 6743This attribute can only be applied to a library level subprogram 6744name and is only allowed in CodePeer mode. It returns the entity 6745for the corresponding elaboration procedure for elaborating the body 6746of the referenced subprogram unit. This is used in the main generated 6747elaboration procedure by the binder in CodePeer mode only and is unrecognized 6748otherwise. 6749 6750@node Emax 6751@unnumberedsec Emax 6752@cindex Ada 83 attributes 6753@findex Emax 6754@noindent 6755The @code{Emax} attribute is provided for compatibility with Ada 83. See 6756the Ada 83 reference manual for an exact description of the semantics of 6757this attribute. 6758 6759@node Enabled 6760@unnumberedsec Enabled 6761@findex Enabled 6762@noindent 6763The @code{Enabled} attribute allows an application program to check at compile 6764time to see if the designated check is currently enabled. The prefix is a 6765simple identifier, referencing any predefined check name (other than 6766@code{All_Checks}) or a check name introduced by pragma Check_Name. If 6767no argument is given for the attribute, the check is for the general state 6768of the check, if an argument is given, then it is an entity name, and the 6769check indicates whether an @code{Suppress} or @code{Unsuppress} has been 6770given naming the entity (if not, then the argument is ignored). 6771 6772Note that instantiations inherit the check status at the point of the 6773instantiation, so a useful idiom is to have a library package that 6774introduces a check name with @code{pragma Check_Name}, and then contains 6775generic packages or subprograms which use the @code{Enabled} attribute 6776to see if the check is enabled. A user of this package can then issue 6777a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating 6778the package or subprogram, controlling whether the check will be present. 6779 6780@node Enum_Rep 6781@unnumberedsec Enum_Rep 6782@cindex Representation of enums 6783@findex Enum_Rep 6784@noindent 6785For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a 6786function with the following spec: 6787 6788@smallexample @c ada 6789function @var{S}'Enum_Rep (Arg : @var{S}'Base) 6790 return @i{Universal_Integer}; 6791@end smallexample 6792 6793@noindent 6794It is also allowable to apply @code{Enum_Rep} directly to an object of an 6795enumeration type or to a non-overloaded enumeration 6796literal. In this case @code{@var{S}'Enum_Rep} is equivalent to 6797@code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the 6798enumeration literal or object. 6799 6800The function returns the representation value for the given enumeration 6801value. This will be equal to value of the @code{Pos} attribute in the 6802absence of an enumeration representation clause. This is a static 6803attribute (i.e.@: the result is static if the argument is static). 6804 6805@code{@var{S}'Enum_Rep} can also be used with integer types and objects, 6806in which case it simply returns the integer value. The reason for this 6807is to allow it to be used for @code{(<>)} discrete formal arguments in 6808a generic unit that can be instantiated with either enumeration types 6809or integer types. Note that if @code{Enum_Rep} is used on a modular 6810type whose upper bound exceeds the upper bound of the largest signed 6811integer type, and the argument is a variable, so that the universal 6812integer calculation is done at run time, then the call to @code{Enum_Rep} 6813may raise @code{Constraint_Error}. 6814 6815@node Enum_Val 6816@unnumberedsec Enum_Val 6817@cindex Representation of enums 6818@findex Enum_Val 6819@noindent 6820For every enumeration subtype @var{S}, @code{@var{S}'Enum_Val} denotes a 6821function with the following spec: 6822 6823@smallexample @c ada 6824function @var{S}'Enum_Val (Arg : @i{Universal_Integer) 6825 return @var{S}'Base}; 6826@end smallexample 6827 6828@noindent 6829The function returns the enumeration value whose representation matches the 6830argument, or raises Constraint_Error if no enumeration literal of the type 6831has the matching value. 6832This will be equal to value of the @code{Val} attribute in the 6833absence of an enumeration representation clause. This is a static 6834attribute (i.e.@: the result is static if the argument is static). 6835 6836@node Epsilon 6837@unnumberedsec Epsilon 6838@cindex Ada 83 attributes 6839@findex Epsilon 6840@noindent 6841The @code{Epsilon} attribute is provided for compatibility with Ada 83. See 6842the Ada 83 reference manual for an exact description of the semantics of 6843this attribute. 6844 6845@node Fixed_Value 6846@unnumberedsec Fixed_Value 6847@findex Fixed_Value 6848@noindent 6849For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a 6850function with the following specification: 6851 6852@smallexample @c ada 6853function @var{S}'Fixed_Value (Arg : @i{Universal_Integer}) 6854 return @var{S}; 6855@end smallexample 6856 6857@noindent 6858The value returned is the fixed-point value @var{V} such that 6859 6860@smallexample @c ada 6861@var{V} = Arg * @var{S}'Small 6862@end smallexample 6863 6864@noindent 6865The effect is thus similar to first converting the argument to the 6866integer type used to represent @var{S}, and then doing an unchecked 6867conversion to the fixed-point type. The difference is 6868that there are full range checks, to ensure that the result is in range. 6869This attribute is primarily intended for use in implementation of the 6870input-output functions for fixed-point values. 6871 6872@node Has_Access_Values 6873@unnumberedsec Has_Access_Values 6874@cindex Access values, testing for 6875@findex Has_Access_Values 6876@noindent 6877The prefix of the @code{Has_Access_Values} attribute is a type. The result 6878is a Boolean value which is True if the is an access type, or is a composite 6879type with a component (at any nesting depth) that is an access type, and is 6880False otherwise. 6881The intended use of this attribute is in conjunction with generic 6882definitions. If the attribute is applied to a generic private type, it 6883indicates whether or not the corresponding actual type has access values. 6884 6885@node Has_Discriminants 6886@unnumberedsec Has_Discriminants 6887@cindex Discriminants, testing for 6888@findex Has_Discriminants 6889@noindent 6890The prefix of the @code{Has_Discriminants} attribute is a type. The result 6891is a Boolean value which is True if the type has discriminants, and False 6892otherwise. The intended use of this attribute is in conjunction with generic 6893definitions. If the attribute is applied to a generic private type, it 6894indicates whether or not the corresponding actual type has discriminants. 6895 6896@node Img 6897@unnumberedsec Img 6898@findex Img 6899@noindent 6900The @code{Img} attribute differs from @code{Image} in that it may be 6901applied to objects as well as types, in which case it gives the 6902@code{Image} for the subtype of the object. This is convenient for 6903debugging: 6904 6905@smallexample @c ada 6906Put_Line ("X = " & X'Img); 6907@end smallexample 6908 6909@noindent 6910has the same meaning as the more verbose: 6911 6912@smallexample @c ada 6913Put_Line ("X = " & @var{T}'Image (X)); 6914@end smallexample 6915 6916@noindent 6917where @var{T} is the (sub)type of the object @code{X}. 6918 6919@node Integer_Value 6920@unnumberedsec Integer_Value 6921@findex Integer_Value 6922@noindent 6923For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a 6924function with the following spec: 6925 6926@smallexample @c ada 6927function @var{S}'Integer_Value (Arg : @i{Universal_Fixed}) 6928 return @var{S}; 6929@end smallexample 6930 6931@noindent 6932The value returned is the integer value @var{V}, such that 6933 6934@smallexample @c ada 6935Arg = @var{V} * @var{T}'Small 6936@end smallexample 6937 6938@noindent 6939where @var{T} is the type of @code{Arg}. 6940The effect is thus similar to first doing an unchecked conversion from 6941the fixed-point type to its corresponding implementation type, and then 6942converting the result to the target integer type. The difference is 6943that there are full range checks, to ensure that the result is in range. 6944This attribute is primarily intended for use in implementation of the 6945standard input-output functions for fixed-point values. 6946 6947@node Invalid_Value 6948@unnumberedsec Invalid_Value 6949@findex Invalid_Value 6950@noindent 6951For every scalar type S, S'Invalid_Value returns an undefined value of the 6952type. If possible this value is an invalid representation for the type. The 6953value returned is identical to the value used to initialize an otherwise 6954uninitialized value of the type if pragma Initialize_Scalars is used, 6955including the ability to modify the value with the binder -Sxx flag and 6956relevant environment variables at run time. 6957 6958@node Large 6959@unnumberedsec Large 6960@cindex Ada 83 attributes 6961@findex Large 6962@noindent 6963The @code{Large} attribute is provided for compatibility with Ada 83. See 6964the Ada 83 reference manual for an exact description of the semantics of 6965this attribute. 6966 6967@node Machine_Size 6968@unnumberedsec Machine_Size 6969@findex Machine_Size 6970@noindent 6971This attribute is identical to the @code{Object_Size} attribute. It is 6972provided for compatibility with the DEC Ada 83 attribute of this name. 6973 6974@node Mantissa 6975@unnumberedsec Mantissa 6976@cindex Ada 83 attributes 6977@findex Mantissa 6978@noindent 6979The @code{Mantissa} attribute is provided for compatibility with Ada 83. See 6980the Ada 83 reference manual for an exact description of the semantics of 6981this attribute. 6982 6983@node Max_Interrupt_Priority 6984@unnumberedsec Max_Interrupt_Priority 6985@cindex Interrupt priority, maximum 6986@findex Max_Interrupt_Priority 6987@noindent 6988@code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only 6989permissible prefix), provides the same value as 6990@code{System.Max_Interrupt_Priority}. 6991 6992@node Max_Priority 6993@unnumberedsec Max_Priority 6994@cindex Priority, maximum 6995@findex Max_Priority 6996@noindent 6997@code{Standard'Max_Priority} (@code{Standard} is the only permissible 6998prefix) provides the same value as @code{System.Max_Priority}. 6999 7000@node Maximum_Alignment 7001@unnumberedsec Maximum_Alignment 7002@cindex Alignment, maximum 7003@findex Maximum_Alignment 7004@noindent 7005@code{Standard'Maximum_Alignment} (@code{Standard} is the only 7006permissible prefix) provides the maximum useful alignment value for the 7007target. This is a static value that can be used to specify the alignment 7008for an object, guaranteeing that it is properly aligned in all 7009cases. 7010 7011@node Mechanism_Code 7012@unnumberedsec Mechanism_Code 7013@cindex Return values, passing mechanism 7014@cindex Parameters, passing mechanism 7015@findex Mechanism_Code 7016@noindent 7017@code{@var{function}'Mechanism_Code} yields an integer code for the 7018mechanism used for the result of function, and 7019@code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism 7020used for formal parameter number @var{n} (a static integer value with 1 7021meaning the first parameter) of @var{subprogram}. The code returned is: 7022 7023@table @asis 7024@item 1 7025by copy (value) 7026@item 2 7027by reference 7028@item 3 7029by descriptor (default descriptor class) 7030@item 4 7031by descriptor (UBS: unaligned bit string) 7032@item 5 7033by descriptor (UBSB: aligned bit string with arbitrary bounds) 7034@item 6 7035by descriptor (UBA: unaligned bit array) 7036@item 7 7037by descriptor (S: string, also scalar access type parameter) 7038@item 8 7039by descriptor (SB: string with arbitrary bounds) 7040@item 9 7041by descriptor (A: contiguous array) 7042@item 10 7043by descriptor (NCA: non-contiguous array) 7044@end table 7045 7046@noindent 7047Values from 3 through 10 are only relevant to Digital OpenVMS implementations. 7048@cindex OpenVMS 7049 7050@node Null_Parameter 7051@unnumberedsec Null_Parameter 7052@cindex Zero address, passing 7053@findex Null_Parameter 7054@noindent 7055A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of 7056type or subtype @var{T} allocated at machine address zero. The attribute 7057is allowed only as the default expression of a formal parameter, or as 7058an actual expression of a subprogram call. In either case, the 7059subprogram must be imported. 7060 7061The identity of the object is represented by the address zero in the 7062argument list, independent of the passing mechanism (explicit or 7063default). 7064 7065This capability is needed to specify that a zero address should be 7066passed for a record or other composite object passed by reference. 7067There is no way of indicating this without the @code{Null_Parameter} 7068attribute. 7069 7070@node Object_Size 7071@unnumberedsec Object_Size 7072@cindex Size, used for objects 7073@findex Object_Size 7074@noindent 7075The size of an object is not necessarily the same as the size of the type 7076of an object. This is because by default object sizes are increased to be 7077a multiple of the alignment of the object. For example, 7078@code{Natural'Size} is 707931, but by default objects of type @code{Natural} will have a size of 32 bits. 7080Similarly, a record containing an integer and a character: 7081 7082@smallexample @c ada 7083type Rec is record 7084 I : Integer; 7085 C : Character; 7086end record; 7087@end smallexample 7088 7089@noindent 7090will have a size of 40 (that is @code{Rec'Size} will be 40). The 7091alignment will be 4, because of the 7092integer field, and so the default size of record objects for this type 7093will be 64 (8 bytes). 7094 7095@node Passed_By_Reference 7096@unnumberedsec Passed_By_Reference 7097@cindex Parameters, when passed by reference 7098@findex Passed_By_Reference 7099@noindent 7100@code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns 7101a value of type @code{Boolean} value that is @code{True} if the type is 7102normally passed by reference and @code{False} if the type is normally 7103passed by copy in calls. For scalar types, the result is always @code{False} 7104and is static. For non-scalar types, the result is non-static. 7105 7106@node Pool_Address 7107@unnumberedsec Pool_Address 7108@cindex Parameters, when passed by reference 7109@findex Pool_Address 7110@noindent 7111@code{@var{X}'Pool_Address} for any object @var{X} returns the address 7112of X within its storage pool. This is the same as 7113@code{@var{X}'Address}, except that for an unconstrained array whose 7114bounds are allocated just before the first component, 7115@code{@var{X}'Pool_Address} returns the address of those bounds, 7116whereas @code{@var{X}'Address} returns the address of the first 7117component. 7118 7119Here, we are interpreting ``storage pool'' broadly to mean ``wherever 7120the object is allocated'', which could be a user-defined storage pool, 7121the global heap, on the stack, or in a static memory area. For an 7122object created by @code{new}, @code{@var{Ptr.all}'Pool_Address} is 7123what is passed to @code{Allocate} and returned from @code{Deallocate}. 7124 7125@node Range_Length 7126@unnumberedsec Range_Length 7127@findex Range_Length 7128@noindent 7129@code{@var{type}'Range_Length} for any discrete type @var{type} yields 7130the number of values represented by the subtype (zero for a null 7131range). The result is static for static subtypes. @code{Range_Length} 7132applied to the index subtype of a one dimensional array always gives the 7133same result as @code{Range} applied to the array itself. 7134 7135@node Ref 7136@unnumberedsec Ref 7137@findex Ref 7138@noindent 7139The @code{System.Address'Ref} 7140(@code{System.Address} is the only permissible prefix) 7141denotes a function identical to 7142@code{System.Storage_Elements.To_Address} except that 7143it is a static attribute. See @ref{To_Address} for more details. 7144 7145@node Result 7146@unnumberedsec Result 7147@findex Result 7148@noindent 7149@code{@var{function}'Result} can only be used with in a Postcondition pragma 7150for a function. The prefix must be the name of the corresponding function. This 7151is used to refer to the result of the function in the postcondition expression. 7152For a further discussion of the use of this attribute and examples of its use, 7153see the description of pragma Postcondition. 7154 7155@node Safe_Emax 7156@unnumberedsec Safe_Emax 7157@cindex Ada 83 attributes 7158@findex Safe_Emax 7159@noindent 7160The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See 7161the Ada 83 reference manual for an exact description of the semantics of 7162this attribute. 7163 7164@node Safe_Large 7165@unnumberedsec Safe_Large 7166@cindex Ada 83 attributes 7167@findex Safe_Large 7168@noindent 7169The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See 7170the Ada 83 reference manual for an exact description of the semantics of 7171this attribute. 7172 7173@node Scalar_Storage_Order 7174@unnumberedsec Scalar_Storage_Order 7175@cindex Endianness 7176@cindex Scalar storage order 7177@findex Scalar_Storage_Order 7178@noindent 7179For every array or record type @var{S}, the representation attribute 7180@code{Scalar_Storage_Order} denotes the order in which storage elements 7181that make up scalar components are ordered within S: 7182 7183@smallexample @c ada 7184 -- Component type definitions 7185 7186 subtype Yr_Type is Natural range 0 .. 127; 7187 subtype Mo_Type is Natural range 1 .. 12; 7188 subtype Da_Type is Natural range 1 .. 31; 7189 7190 -- Record declaration 7191 7192 type Date is record 7193 Years_Since_1980 : Yr_Type; 7194 Month : Mo_Type; 7195 Day_Of_Month : Da_Type; 7196 end record; 7197 7198 -- Record representation clause 7199 7200 for Date use record 7201 Years_Since_1980 at 0 range 0 .. 6; 7202 Month at 0 range 7 .. 10; 7203 Day_Of_Month at 0 range 11 .. 15; 7204 end record; 7205 7206 -- Attribute definition clauses 7207 7208 for Date'Bit_Order use System.High_Order_First; 7209 for Date'Scalar_Storage_Order use System.High_Order_First; 7210 -- If Scalar_Storage_Order is specified, it must be consistent with 7211 -- Bit_Order, so it's best to always define the latter explicitly if 7212 -- the former is used. 7213@end smallexample 7214 7215Other properties are 7216as for standard representation attribute @code{Bit_Order}, as defined by 7217Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. 7218 7219For a record type @var{S}, if @code{@var{S}'Scalar_Storage_Order} is 7220specified explicitly, it shall be equal to @code{@var{S}'Bit_Order}. Note: 7221this means that if a @code{Scalar_Storage_Order} attribute definition 7222clause is not confirming, then the type's @code{Bit_Order} shall be 7223specified explicitly and set to the same value. 7224 7225For a record extension, the derived type shall have the same scalar storage 7226order as the parent type. 7227 7228If a component of @var{S} has itself a record or array type, then it shall also 7229have a @code{Scalar_Storage_Order} attribute definition clause. In addition, 7230if the component does not start on a byte boundary, then the scalar storage 7231order specified for S and for the nested component type shall be identical. 7232 7233No component of a type that has a @code{Scalar_Storage_Order} attribute 7234definition may be aliased. 7235 7236A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. 7237with a value equal to @code{System.Default_Bit_Order}) has no effect. 7238 7239If the opposite storage order is specified, then whenever the value of 7240a scalar component of an object of type @var{S} is read, the storage 7241elements of the enclosing machine scalar are first reversed (before 7242retrieving the component value, possibly applying some shift and mask 7243operatings on the enclosing machine scalar), and the opposite operation 7244is done for writes. 7245 7246In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components 7247are relaxed. Instead, the following rules apply: 7248 7249@itemize @bullet 7250@item the underlying storage elements are those at positions 7251 @code{(position + first_bit / storage_element_size) .. 7252 (position + (last_bit + storage_element_size - 1) / 7253 storage_element_size)} 7254@item the sequence of underlying storage elements shall have 7255 a size no greater than the largest machine scalar 7256@item the enclosing machine scalar is defined as the smallest machine 7257 scalar starting at a position no greater than 7258 @code{position + first_bit / storage_element_size} and covering 7259 storage elements at least up to @code{position + (last_bit + 7260 storage_element_size - 1) / storage_element_size} 7261@item the position of the component is interpreted relative to that machine 7262 scalar. 7263 7264@end itemize 7265 7266@node Simple_Storage_Pool 7267@unnumberedsec Simple_Storage_Pool 7268@cindex Storage pool, simple 7269@cindex Simple storage pool 7270@findex Simple_Storage_Pool 7271@noindent 7272For every nonformal, nonderived access-to-object type @var{Acc}, the 7273representation attribute @code{Simple_Storage_Pool} may be specified 7274via an attribute_definition_clause (or by specifying the equivalent aspect): 7275 7276@smallexample @c ada 7277 7278My_Pool : My_Simple_Storage_Pool_Type; 7279 7280type Acc is access My_Data_Type; 7281 7282for Acc'Simple_Storage_Pool use My_Pool; 7283 7284@end smallexample 7285 7286@noindent 7287The name given in an attribute_definition_clause for the 7288@code{Simple_Storage_Pool} attribute shall denote a variable of 7289a ``simple storage pool type'' (see pragma @code{Simple_Storage_Pool_Type}). 7290 7291The use of this attribute is only allowed for a prefix denoting a type 7292for which it has been specified. The type of the attribute is the type 7293of the variable specified as the simple storage pool of the access type, 7294and the attribute denotes that variable. 7295 7296It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} 7297for the same access type. 7298 7299If the @code{Simple_Storage_Pool} attribute has been specified for an access 7300type, then applying the @code{Storage_Pool} attribute to the type is flagged 7301with a warning and its evaluation raises the exception @code{Program_Error}. 7302 7303If the Simple_Storage_Pool attribute has been specified for an access 7304type @var{S}, then the evaluation of the attribute @code{@var{S}'Storage_Size} 7305returns the result of calling @code{Storage_Size (@var{S}'Simple_Storage_Pool)}, 7306which is intended to indicate the number of storage elements reserved for 7307the simple storage pool. If the Storage_Size function has not been defined 7308for the simple storage pool type, then this attribute returns zero. 7309 7310If an access type @var{S} has a specified simple storage pool of type 7311@var{SSP}, then the evaluation of an allocator for that access type calls 7312the primitive @code{Allocate} procedure for type @var{SSP}, passing 7313@code{@var{S}'Simple_Storage_Pool} as the pool parameter. The detailed 7314semantics of such allocators is the same as those defined for allocators 7315in section 13.11 of the Ada Reference Manual, with the term 7316``simple storage pool'' substituted for ``storage pool''. 7317 7318If an access type @var{S} has a specified simple storage pool of type 7319@var{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} 7320for that access type invokes the primitive @code{Deallocate} procedure 7321for type @var{SSP}, passing @code{@var{S}'Simple_Storage_Pool} as the pool 7322parameter. The detailed semantics of such unchecked deallocations is the same 7323as defined in section 13.11.2 of the Ada Reference Manual, except that the 7324term ``simple storage pool'' is substituted for ``storage pool''. 7325 7326@node Small 7327@unnumberedsec Small 7328@cindex Ada 83 attributes 7329@findex Small 7330@noindent 7331The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for 7332fixed-point types. 7333GNAT also allows this attribute to be applied to floating-point types 7334for compatibility with Ada 83. See 7335the Ada 83 reference manual for an exact description of the semantics of 7336this attribute when applied to floating-point types. 7337 7338@node Storage_Unit 7339@unnumberedsec Storage_Unit 7340@findex Storage_Unit 7341@noindent 7342@code{Standard'Storage_Unit} (@code{Standard} is the only permissible 7343prefix) provides the same value as @code{System.Storage_Unit}. 7344 7345@node Stub_Type 7346@unnumberedsec Stub_Type 7347@findex Stub_Type 7348@noindent 7349The GNAT implementation of remote access-to-classwide types is 7350organized as described in AARM section E.4 (20.t): a value of an RACW type 7351(designating a remote object) is represented as a normal access 7352value, pointing to a "stub" object which in turn contains the 7353necessary information to contact the designated remote object. A 7354call on any dispatching operation of such a stub object does the 7355remote call, if necessary, using the information in the stub object 7356to locate the target partition, etc. 7357 7358For a prefix @code{T} that denotes a remote access-to-classwide type, 7359@code{T'Stub_Type} denotes the type of the corresponding stub objects. 7360 7361By construction, the layout of @code{T'Stub_Type} is identical to that of 7362type @code{RACW_Stub_Type} declared in the internal implementation-defined 7363unit @code{System.Partition_Interface}. Use of this attribute will create 7364an implicit dependency on this unit. 7365 7366@node System_Allocator_Alignment 7367@unnumberedsec System_Allocator_Alignment 7368@cindex Alignment, allocator 7369@findex System_Allocator_Alignment 7370@noindent 7371@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only 7372permissible prefix) provides the observable guaranted to be honored by 7373the system allocator (malloc). This is a static value that can be used 7374in user storage pools based on malloc either to reject allocation 7375with alignment too large or to enable a realignment circuitry if the 7376alignment request is larger than this value. 7377 7378@node Target_Name 7379@unnumberedsec Target_Name 7380@findex Target_Name 7381@noindent 7382@code{Standard'Target_Name} (@code{Standard} is the only permissible 7383prefix) provides a static string value that identifies the target 7384for the current compilation. For GCC implementations, this is the 7385standard gcc target name without the terminating slash (for 7386example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 7387 7388@node Tick 7389@unnumberedsec Tick 7390@findex Tick 7391@noindent 7392@code{Standard'Tick} (@code{Standard} is the only permissible prefix) 7393provides the same value as @code{System.Tick}, 7394 7395@node To_Address 7396@unnumberedsec To_Address 7397@findex To_Address 7398@noindent 7399The @code{System'To_Address} 7400(@code{System} is the only permissible prefix) 7401denotes a function identical to 7402@code{System.Storage_Elements.To_Address} except that 7403it is a static attribute. This means that if its argument is 7404a static expression, then the result of the attribute is a 7405static expression. The result is that such an expression can be 7406used in contexts (e.g.@: preelaborable packages) which require a 7407static expression and where the function call could not be used 7408(since the function call is always non-static, even if its 7409argument is static). 7410 7411@node Type_Class 7412@unnumberedsec Type_Class 7413@findex Type_Class 7414@noindent 7415@code{@var{type}'Type_Class} for any type or subtype @var{type} yields 7416the value of the type class for the full type of @var{type}. If 7417@var{type} is a generic formal type, the value is the value for the 7418corresponding actual subtype. The value of this attribute is of type 7419@code{System.Aux_DEC.Type_Class}, which has the following definition: 7420 7421@smallexample @c ada 7422 type Type_Class is 7423 (Type_Class_Enumeration, 7424 Type_Class_Integer, 7425 Type_Class_Fixed_Point, 7426 Type_Class_Floating_Point, 7427 Type_Class_Array, 7428 Type_Class_Record, 7429 Type_Class_Access, 7430 Type_Class_Task, 7431 Type_Class_Address); 7432@end smallexample 7433 7434@noindent 7435Protected types yield the value @code{Type_Class_Task}, which thus 7436applies to all concurrent types. This attribute is designed to 7437be compatible with the DEC Ada 83 attribute of the same name. 7438 7439@node UET_Address 7440@unnumberedsec UET_Address 7441@findex UET_Address 7442@noindent 7443The @code{UET_Address} attribute can only be used for a prefix which 7444denotes a library package. It yields the address of the unit exception 7445table when zero cost exception handling is used. This attribute is 7446intended only for use within the GNAT implementation. See the unit 7447@code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb} 7448for details on how this attribute is used in the implementation. 7449 7450@node Unconstrained_Array 7451@unnumberedsec Unconstrained_Array 7452@findex Unconstrained_Array 7453@noindent 7454The @code{Unconstrained_Array} attribute can be used with a prefix that 7455denotes any type or subtype. It is a static attribute that yields 7456@code{True} if the prefix designates an unconstrained array, 7457and @code{False} otherwise. In a generic instance, the result is 7458still static, and yields the result of applying this test to the 7459generic actual. 7460 7461@node Universal_Literal_String 7462@unnumberedsec Universal_Literal_String 7463@cindex Named numbers, representation of 7464@findex Universal_Literal_String 7465@noindent 7466The prefix of @code{Universal_Literal_String} must be a named 7467number. The static result is the string consisting of the characters of 7468the number as defined in the original source. This allows the user 7469program to access the actual text of named numbers without intermediate 7470conversions and without the need to enclose the strings in quotes (which 7471would preclude their use as numbers). 7472 7473For example, the following program prints the first 50 digits of pi: 7474 7475@smallexample @c ada 7476with Text_IO; use Text_IO; 7477with Ada.Numerics; 7478procedure Pi is 7479begin 7480 Put (Ada.Numerics.Pi'Universal_Literal_String); 7481end; 7482@end smallexample 7483 7484@node Unrestricted_Access 7485@unnumberedsec Unrestricted_Access 7486@cindex @code{Access}, unrestricted 7487@findex Unrestricted_Access 7488@noindent 7489The @code{Unrestricted_Access} attribute is similar to @code{Access} 7490except that all accessibility and aliased view checks are omitted. This 7491is a user-beware attribute. It is similar to 7492@code{Address}, for which it is a desirable replacement where the value 7493desired is an access type. In other words, its effect is identical to 7494first applying the @code{Address} attribute and then doing an unchecked 7495conversion to a desired access type. In GNAT, but not necessarily in 7496other implementations, the use of static chains for inner level 7497subprograms means that @code{Unrestricted_Access} applied to a 7498subprogram yields a value that can be called as long as the subprogram 7499is in scope (normal Ada accessibility rules restrict this usage). 7500 7501It is possible to use @code{Unrestricted_Access} for any type, but care 7502must be exercised if it is used to create pointers to unconstrained 7503objects. In this case, the resulting pointer has the same scope as the 7504context of the attribute, and may not be returned to some enclosing 7505scope. For instance, a function cannot use @code{Unrestricted_Access} 7506to create a unconstrained pointer and then return that value to the 7507caller. 7508 7509@node Valid_Scalars 7510@unnumberedsec Valid_Scalars 7511@findex Valid_Scalars 7512@noindent 7513The @code{'Valid_Scalars} attribute is intended to make it easier to 7514check the validity of scalar subcomponents of composite objects. It 7515is defined for any prefix @code{X} that denotes an object. 7516The value of this attribute is of the predefined type Boolean. 7517@code{X'Valid_Scalars} yields True if and only if evaluation of 7518@code{P'Valid} yields True for every scalar part P of X or if X has 7519no scalar parts. It is not specified in what order the scalar parts 7520are checked, nor whether any more are checked after any one of them 7521is determined to be invalid. If the prefix @code{X} is of a class-wide 7522type @code{T'Class} (where @code{T} is the associated specific type), 7523or if the prefix @code{X} is of a specific tagged type @code{T}, then 7524only the scalar parts of components of @code{T} are traversed; in other 7525words, components of extensions of @code{T} are not traversed even if 7526@code{T'Class (X)'Tag /= T'Tag} . The compiler will issue a warning if it can 7527be determined at compile time that the prefix of the attribute has no 7528scalar parts (e.g., if the prefix is of an access type, an interface type, 7529an undiscriminated task type, or an undiscriminated protected type). 7530 7531@node VADS_Size 7532@unnumberedsec VADS_Size 7533@cindex @code{Size}, VADS compatibility 7534@findex VADS_Size 7535@noindent 7536The @code{'VADS_Size} attribute is intended to make it easier to port 7537legacy code which relies on the semantics of @code{'Size} as implemented 7538by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 7539same semantic interpretation. In particular, @code{'VADS_Size} applied 7540to a predefined or other primitive type with no Size clause yields the 7541Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on 7542typical machines). In addition @code{'VADS_Size} applied to an object 7543gives the result that would be obtained by applying the attribute to 7544the corresponding type. 7545 7546@node Value_Size 7547@unnumberedsec Value_Size 7548@cindex @code{Size}, setting for not-first subtype 7549@findex Value_Size 7550@code{@var{type}'Value_Size} is the number of bits required to represent 7551a value of the given subtype. It is the same as @code{@var{type}'Size}, 7552but, unlike @code{Size}, may be set for non-first subtypes. 7553 7554@node Wchar_T_Size 7555@unnumberedsec Wchar_T_Size 7556@findex Wchar_T_Size 7557@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible 7558prefix) provides the size in bits of the C @code{wchar_t} type 7559primarily for constructing the definition of this type in 7560package @code{Interfaces.C}. 7561 7562@node Word_Size 7563@unnumberedsec Word_Size 7564@findex Word_Size 7565@code{Standard'Word_Size} (@code{Standard} is the only permissible 7566prefix) provides the value @code{System.Word_Size}. 7567 7568@node Standard and Implementation Defined Restrictions 7569@chapter Standard and Implementation Defined Restrictions 7570 7571@noindent 7572All RM defined Restriction identifiers are implemented: 7573 7574@itemize @bullet 7575@item language-defined restrictions (see 13.12.1) 7576@item tasking restrictions (see D.7) 7577@item high integrity restrictions (see H.4) 7578@end itemize 7579 7580@noindent 7581GNAT implements additional restriction identifiers. All restrictions, whether 7582language defined or GNAT-specific, are listed in the following. 7583 7584@menu 7585* Partition-Wide Restrictions:: 7586* Program Unit Level Restrictions:: 7587@end menu 7588 7589@node Partition-Wide Restrictions 7590@section Partition-Wide Restrictions 7591 7592There are two separate lists of restriction identifiers. The first 7593set requires consistency throughout a partition (in other words, if the 7594restriction identifier is used for any compilation unit in the partition, 7595then all compilation units in the partition must obey the restriction). 7596 7597@menu 7598* Immediate_Reclamation:: 7599* Max_Asynchronous_Select_Nesting:: 7600* Max_Entry_Queue_Length:: 7601* Max_Protected_Entries:: 7602* Max_Select_Alternatives:: 7603* Max_Storage_At_Blocking:: 7604* Max_Task_Entries:: 7605* Max_Tasks:: 7606* No_Abort_Statements:: 7607* No_Access_Parameter_Allocators:: 7608* No_Access_Subprograms:: 7609* No_Allocators:: 7610* No_Anonymous_Allocators:: 7611* No_Calendar:: 7612* No_Coextensions:: 7613* No_Default_Initialization:: 7614* No_Delay:: 7615* No_Dependence:: 7616* No_Direct_Boolean_Operators:: 7617* No_Dispatch:: 7618* No_Dispatching_Calls:: 7619* No_Dynamic_Attachment:: 7620* No_Dynamic_Priorities:: 7621* No_Entry_Calls_In_Elaboration_Code:: 7622* No_Enumeration_Maps:: 7623* No_Exception_Handlers:: 7624* No_Exception_Propagation:: 7625* No_Exception_Registration:: 7626* No_Exceptions:: 7627* No_Finalization:: 7628* No_Fixed_Point:: 7629* No_Floating_Point:: 7630* No_Implicit_Conditionals:: 7631* No_Implicit_Dynamic_Code:: 7632* No_Implicit_Heap_Allocations:: 7633* No_Implicit_Loops:: 7634* No_Initialize_Scalars:: 7635* No_IO:: 7636* No_Local_Allocators:: 7637* No_Local_Protected_Objects:: 7638* No_Local_Timing_Events:: 7639* No_Nested_Finalization:: 7640* No_Protected_Type_Allocators:: 7641* No_Protected_Types:: 7642* No_Recursion:: 7643* No_Reentrancy:: 7644* No_Relative_Delay:: 7645* No_Requeue_Statements:: 7646* No_Secondary_Stack:: 7647* No_Select_Statements:: 7648* No_Specific_Termination_Handlers:: 7649* No_Specification_of_Aspect:: 7650* No_Standard_Allocators_After_Elaboration:: 7651* No_Standard_Storage_Pools:: 7652* No_Stream_Optimizations:: 7653* No_Streams:: 7654* No_Task_Allocators:: 7655* No_Task_Attributes_Package:: 7656* No_Task_Hierarchy:: 7657* No_Task_Termination:: 7658* No_Tasking:: 7659* No_Terminate_Alternatives:: 7660* No_Unchecked_Access:: 7661* Simple_Barriers:: 7662* Static_Priorities:: 7663* Static_Storage_Size:: 7664@end menu 7665 7666@node Immediate_Reclamation 7667@unnumberedsubsec Immediate_Reclamation 7668@findex Immediate_Reclamation 7669[RM H.4] This restriction ensures that, except for storage occupied by 7670objects created by allocators and not deallocated via unchecked 7671deallocation, any storage reserved at run time for an object is 7672immediately reclaimed when the object no longer exists. 7673 7674@node Max_Asynchronous_Select_Nesting 7675@unnumberedsubsec Max_Asynchronous_Select_Nesting 7676@findex Max_Asynchronous_Select_Nesting 7677[RM D.7] Specifies the maximum dynamic nesting level of asynchronous 7678selects. Violations of this restriction with a value of zero are 7679detected at compile time. Violations of this restriction with values 7680other than zero cause Storage_Error to be raised. 7681 7682@node Max_Entry_Queue_Length 7683@unnumberedsubsec Max_Entry_Queue_Length 7684@findex Max_Entry_Queue_Length 7685[RM D.7] This restriction is a declaration that any protected entry compiled in 7686the scope of the restriction has at most the specified number of 7687tasks waiting on the entry at any one time, and so no queue is required. 7688Note that this restriction is checked at run time. Violation of this 7689restriction results in the raising of Program_Error exception at the point of 7690the call. 7691 7692@node Max_Protected_Entries 7693@unnumberedsubsec Max_Protected_Entries 7694@findex Max_Protected_Entries 7695[RM D.7] Specifies the maximum number of entries per protected type. The 7696bounds of every entry family of a protected unit shall be static, or shall be 7697defined by a discriminant of a subtype whose corresponding bound is static. 7698 7699@node Max_Select_Alternatives 7700@unnumberedsubsec Max_Select_Alternatives 7701@findex Max_Select_Alternatives 7702[RM D.7] Specifies the maximum number of alternatives in a selective accept. 7703 7704@node Max_Storage_At_Blocking 7705@unnumberedsubsec Max_Storage_At_Blocking 7706@findex Max_Storage_At_Blocking 7707[RM D.7] Specifies the maximum portion (in storage elements) of a task's 7708Storage_Size that can be retained by a blocked task. A violation of this 7709restriction causes Storage_Error to be raised. 7710 7711@node Max_Task_Entries 7712@unnumberedsubsec Max_Task_Entries 7713@findex Max_Task_Entries 7714[RM D.7] Specifies the maximum number of entries 7715per task. The bounds of every entry family 7716of a task unit shall be static, or shall be 7717defined by a discriminant of a subtype whose 7718corresponding bound is static. 7719 7720@node Max_Tasks 7721@unnumberedsubsec Max_Tasks 7722@findex Max_Tasks 7723[RM D.7] Specifies the maximum number of task that may be created, not 7724counting the creation of the environment task. Violations of this 7725restriction with a value of zero are detected at compile 7726time. Violations of this restriction with values other than zero cause 7727Storage_Error to be raised. 7728 7729@node No_Abort_Statements 7730@unnumberedsubsec No_Abort_Statements 7731@findex No_Abort_Statements 7732[RM D.7] There are no abort_statements, and there are 7733no calls to Task_Identification.Abort_Task. 7734 7735@node No_Access_Parameter_Allocators 7736@unnumberedsubsec No_Access_Parameter_Allocators 7737@findex No_Access_Parameter_Allocators 7738[RM H.4] This restriction ensures at compile time that there are no 7739occurrences of an allocator as the actual parameter to an access 7740parameter. 7741 7742@node No_Access_Subprograms 7743@unnumberedsubsec No_Access_Subprograms 7744@findex No_Access_Subprograms 7745[RM H.4] This restriction ensures at compile time that there are no 7746declarations of access-to-subprogram types. 7747 7748@node No_Allocators 7749@unnumberedsubsec No_Allocators 7750@findex No_Allocators 7751[RM H.4] This restriction ensures at compile time that there are no 7752occurrences of an allocator. 7753 7754@node No_Anonymous_Allocators 7755@unnumberedsubsec No_Anonymous_Allocators 7756@findex No_Anonymous_Allocators 7757[RM H.4] This restriction ensures at compile time that there are no 7758occurrences of an allocator of anonymous access type. 7759 7760@node No_Calendar 7761@unnumberedsubsec No_Calendar 7762@findex No_Calendar 7763[GNAT] This restriction ensures at compile time that there is no implicit or 7764explicit dependence on the package @code{Ada.Calendar}. 7765 7766@node No_Coextensions 7767@unnumberedsubsec No_Coextensions 7768@findex No_Coextensions 7769[RM H.4] This restriction ensures at compile time that there are no 7770coextensions. See 3.10.2. 7771 7772@node No_Default_Initialization 7773@unnumberedsubsec No_Default_Initialization 7774@findex No_Default_Initialization 7775 7776[GNAT] This restriction prohibits any instance of default initialization 7777of variables. The binder implements a consistency rule which prevents 7778any unit compiled without the restriction from with'ing a unit with the 7779restriction (this allows the generation of initialization procedures to 7780be skipped, since you can be sure that no call is ever generated to an 7781initialization procedure in a unit with the restriction active). If used 7782in conjunction with Initialize_Scalars or Normalize_Scalars, the effect 7783is to prohibit all cases of variables declared without a specific 7784initializer (including the case of OUT scalar parameters). 7785 7786@node No_Delay 7787@unnumberedsubsec No_Delay 7788@findex No_Delay 7789[RM H.4] This restriction ensures at compile time that there are no 7790delay statements and no dependences on package Calendar. 7791 7792@node No_Dependence 7793@unnumberedsubsec No_Dependence 7794@findex No_Dependence 7795[RM 13.12.1] This restriction checks at compile time that there are no 7796dependence on a library unit. 7797 7798@node No_Direct_Boolean_Operators 7799@unnumberedsubsec No_Direct_Boolean_Operators 7800@findex No_Direct_Boolean_Operators 7801[GNAT] This restriction ensures that no logical (and/or/xor) are used on 7802operands of type Boolean (or any type derived 7803from Boolean). This is intended for use in safety critical programs 7804where the certification protocol requires the use of short-circuit 7805(and then, or else) forms for all composite boolean operations. 7806 7807@node No_Dispatch 7808@unnumberedsubsec No_Dispatch 7809@findex No_Dispatch 7810[RM H.4] This restriction ensures at compile time that there are no 7811occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. 7812 7813@node No_Dispatching_Calls 7814@unnumberedsubsec No_Dispatching_Calls 7815@findex No_Dispatching_Calls 7816[GNAT] This restriction ensures at compile time that the code generated by the 7817compiler involves no dispatching calls. The use of this restriction allows the 7818safe use of record extensions, classwide membership tests and other classwide 7819features not involving implicit dispatching. This restriction ensures that 7820the code contains no indirect calls through a dispatching mechanism. Note that 7821this includes internally-generated calls created by the compiler, for example 7822in the implementation of class-wide objects assignments. The 7823membership test is allowed in the presence of this restriction, because its 7824implementation requires no dispatching. 7825This restriction is comparable to the official Ada restriction 7826@code{No_Dispatch} except that it is a bit less restrictive in that it allows 7827all classwide constructs that do not imply dispatching. 7828The following example indicates constructs that violate this restriction. 7829 7830@smallexample 7831package Pkg is 7832 type T is tagged record 7833 Data : Natural; 7834 end record; 7835 procedure P (X : T); 7836 7837 type DT is new T with record 7838 More_Data : Natural; 7839 end record; 7840 procedure Q (X : DT); 7841end Pkg; 7842 7843with Pkg; use Pkg; 7844procedure Example is 7845 procedure Test (O : T'Class) is 7846 N : Natural := O'Size;-- Error: Dispatching call 7847 C : T'Class := O; -- Error: implicit Dispatching Call 7848 begin 7849 if O in DT'Class then -- OK : Membership test 7850 Q (DT (O)); -- OK : Type conversion plus direct call 7851 else 7852 P (O); -- Error: Dispatching call 7853 end if; 7854 end Test; 7855 7856 Obj : DT; 7857begin 7858 P (Obj); -- OK : Direct call 7859 P (T (Obj)); -- OK : Type conversion plus direct call 7860 P (T'Class (Obj)); -- Error: Dispatching call 7861 7862 Test (Obj); -- OK : Type conversion 7863 7864 if Obj in T'Class then -- OK : Membership test 7865 null; 7866 end if; 7867end Example; 7868@end smallexample 7869 7870@node No_Dynamic_Attachment 7871@unnumberedsubsec No_Dynamic_Attachment 7872@findex No_Dynamic_Attachment 7873[RM D.7] This restriction ensures that there is no call to any of the 7874operations defined in package Ada.Interrupts 7875(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, 7876Detach_Handler, and Reference). 7877 7878@node No_Dynamic_Priorities 7879@unnumberedsubsec No_Dynamic_Priorities 7880@findex No_Dynamic_Priorities 7881[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 7882 7883@node No_Entry_Calls_In_Elaboration_Code 7884@unnumberedsubsec No_Entry_Calls_In_Elaboration_Code 7885@findex No_Entry_Calls_In_Elaboration_Code 7886[GNAT] This restriction ensures at compile time that no task or protected entry 7887calls are made during elaboration code. As a result of the use of this 7888restriction, the compiler can assume that no code past an accept statement 7889in a task can be executed at elaboration time. 7890 7891@node No_Enumeration_Maps 7892@unnumberedsubsec No_Enumeration_Maps 7893@findex No_Enumeration_Maps 7894[GNAT] This restriction ensures at compile time that no operations requiring 7895enumeration maps are used (that is Image and Value attributes applied 7896to enumeration types). 7897 7898@node No_Exception_Handlers 7899@unnumberedsubsec No_Exception_Handlers 7900@findex No_Exception_Handlers 7901[GNAT] This restriction ensures at compile time that there are no explicit 7902exception handlers. It also indicates that no exception propagation will 7903be provided. In this mode, exceptions may be raised but will result in 7904an immediate call to the last chance handler, a routine that the user 7905must define with the following profile: 7906 7907@smallexample @c ada 7908procedure Last_Chance_Handler 7909 (Source_Location : System.Address; Line : Integer); 7910pragma Export (C, Last_Chance_Handler, 7911 "__gnat_last_chance_handler"); 7912@end smallexample 7913 7914The parameter is a C null-terminated string representing a message to be 7915associated with the exception (typically the source location of the raise 7916statement generated by the compiler). The Line parameter when nonzero 7917represents the line number in the source program where the raise occurs. 7918 7919@node No_Exception_Propagation 7920@unnumberedsubsec No_Exception_Propagation 7921@findex No_Exception_Propagation 7922[GNAT] This restriction guarantees that exceptions are never propagated 7923to an outer subprogram scope. The only case in which an exception may 7924be raised is when the handler is statically in the same subprogram, so 7925that the effect of a raise is essentially like a goto statement. Any 7926other raise statement (implicit or explicit) will be considered 7927unhandled. Exception handlers are allowed, but may not contain an 7928exception occurrence identifier (exception choice). In addition, use of 7929the package GNAT.Current_Exception is not permitted, and reraise 7930statements (raise with no operand) are not permitted. 7931 7932@node No_Exception_Registration 7933@unnumberedsubsec No_Exception_Registration 7934@findex No_Exception_Registration 7935[GNAT] This restriction ensures at compile time that no stream operations for 7936types Exception_Id or Exception_Occurrence are used. This also makes it 7937impossible to pass exceptions to or from a partition with this restriction 7938in a distributed environment. If this exception is active, then the generated 7939code is simplified by omitting the otherwise-required global registration 7940of exceptions when they are declared. 7941 7942@node No_Exceptions 7943@unnumberedsubsec No_Exceptions 7944@findex No_Exceptions 7945[RM H.4] This restriction ensures at compile time that there are no 7946raise statements and no exception handlers. 7947 7948@node No_Finalization 7949@unnumberedsubsec No_Finalization 7950@findex No_Finalization 7951[GNAT] This restriction disables the language features described in 7952chapter 7.6 of the Ada 2005 RM as well as all form of code generation 7953performed by the compiler to support these features. The following types 7954are no longer considered controlled when this restriction is in effect: 7955@itemize @bullet 7956@item 7957@code{Ada.Finalization.Controlled} 7958@item 7959@code{Ada.Finalization.Limited_Controlled} 7960@item 7961Derivations from @code{Controlled} or @code{Limited_Controlled} 7962@item 7963Class-wide types 7964@item 7965Protected types 7966@item 7967Task types 7968@item 7969Array and record types with controlled components 7970@end itemize 7971The compiler no longer generates code to initialize, finalize or adjust an 7972object or a nested component, either declared on the stack or on the heap. The 7973deallocation of a controlled object no longer finalizes its contents. 7974 7975@node No_Fixed_Point 7976@unnumberedsubsec No_Fixed_Point 7977@findex No_Fixed_Point 7978[RM H.4] This restriction ensures at compile time that there are no 7979occurrences of fixed point types and operations. 7980 7981@node No_Floating_Point 7982@unnumberedsubsec No_Floating_Point 7983@findex No_Floating_Point 7984[RM H.4] This restriction ensures at compile time that there are no 7985occurrences of floating point types and operations. 7986 7987@node No_Implicit_Conditionals 7988@unnumberedsubsec No_Implicit_Conditionals 7989@findex No_Implicit_Conditionals 7990[GNAT] This restriction ensures that the generated code does not contain any 7991implicit conditionals, either by modifying the generated code where possible, 7992or by rejecting any construct that would otherwise generate an implicit 7993conditional. Note that this check does not include run time constraint 7994checks, which on some targets may generate implicit conditionals as 7995well. To control the latter, constraint checks can be suppressed in the 7996normal manner. Constructs generating implicit conditionals include comparisons 7997of composite objects and the Max/Min attributes. 7998 7999@node No_Implicit_Dynamic_Code 8000@unnumberedsubsec No_Implicit_Dynamic_Code 8001@findex No_Implicit_Dynamic_Code 8002@cindex trampoline 8003[GNAT] This restriction prevents the compiler from building ``trampolines''. 8004This is a structure that is built on the stack and contains dynamic 8005code to be executed at run time. On some targets, a trampoline is 8006built for the following features: @code{Access}, 8007@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; 8008nested task bodies; primitive operations of nested tagged types. 8009Trampolines do not work on machines that prevent execution of stack 8010data. For example, on windows systems, enabling DEP (data execution 8011protection) will cause trampolines to raise an exception. 8012Trampolines are also quite slow at run time. 8013 8014On many targets, trampolines have been largely eliminated. Look at the 8015version of system.ads for your target --- if it has 8016Always_Compatible_Rep equal to False, then trampolines are largely 8017eliminated. In particular, a trampoline is built for the following 8018features: @code{Address} of a nested subprogram; 8019@code{Access} or @code{Unrestricted_Access} of a nested subprogram, 8020but only if pragma Favor_Top_Level applies, or the access type has a 8021foreign-language convention; primitive operations of nested tagged 8022types. 8023 8024@node No_Implicit_Heap_Allocations 8025@unnumberedsubsec No_Implicit_Heap_Allocations 8026@findex No_Implicit_Heap_Allocations 8027[RM D.7] No constructs are allowed to cause implicit heap allocation. 8028 8029@node No_Implicit_Loops 8030@unnumberedsubsec No_Implicit_Loops 8031@findex No_Implicit_Loops 8032[GNAT] This restriction ensures that the generated code does not contain any 8033implicit @code{for} loops, either by modifying 8034the generated code where possible, 8035or by rejecting any construct that would otherwise generate an implicit 8036@code{for} loop. If this restriction is active, it is possible to build 8037large array aggregates with all static components without generating an 8038intermediate temporary, and without generating a loop to initialize individual 8039components. Otherwise, a loop is created for arrays larger than about 5000 8040scalar components. 8041 8042@node No_Initialize_Scalars 8043@unnumberedsubsec No_Initialize_Scalars 8044@findex No_Initialize_Scalars 8045[GNAT] This restriction ensures that no unit in the partition is compiled with 8046pragma Initialize_Scalars. This allows the generation of more efficient 8047code, and in particular eliminates dummy null initialization routines that 8048are otherwise generated for some record and array types. 8049 8050@node No_IO 8051@unnumberedsubsec No_IO 8052@findex No_IO 8053[RM H.4] This restriction ensures at compile time that there are no 8054dependences on any of the library units Sequential_IO, Direct_IO, 8055Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. 8056 8057@node No_Local_Allocators 8058@unnumberedsubsec No_Local_Allocators 8059@findex No_Local_Allocators 8060[RM H.4] This restriction ensures at compile time that there are no 8061occurrences of an allocator in subprograms, generic subprograms, tasks, 8062and entry bodies. 8063 8064@node No_Local_Protected_Objects 8065@unnumberedsubsec No_Local_Protected_Objects 8066@findex No_Local_Protected_Objects 8067[RM D.7] This restriction ensures at compile time that protected objects are 8068only declared at the library level. 8069 8070@node No_Local_Timing_Events 8071@unnumberedsubsec No_Local_Timing_Events 8072@findex No_Local_Timing_Events 8073[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are 8074declared at the library level. 8075 8076@node No_Nested_Finalization 8077@unnumberedsubsec No_Nested_Finalization 8078@findex No_Nested_Finalization 8079[RM D.7] All objects requiring finalization are declared at the library level. 8080 8081@node No_Protected_Type_Allocators 8082@unnumberedsubsec No_Protected_Type_Allocators 8083@findex No_Protected_Type_Allocators 8084[RM D.7] This restriction ensures at compile time that there are no allocator 8085expressions that attempt to allocate protected objects. 8086 8087@node No_Protected_Types 8088@unnumberedsubsec No_Protected_Types 8089@findex No_Protected_Types 8090[RM H.4] This restriction ensures at compile time that there are no 8091declarations of protected types or protected objects. 8092 8093@node No_Recursion 8094@unnumberedsubsec No_Recursion 8095@findex No_Recursion 8096[RM H.4] A program execution is erroneous if a subprogram is invoked as 8097part of its execution. 8098 8099@node No_Reentrancy 8100@unnumberedsubsec No_Reentrancy 8101@findex No_Reentrancy 8102[RM H.4] A program execution is erroneous if a subprogram is executed by 8103two tasks at the same time. 8104 8105@node No_Relative_Delay 8106@unnumberedsubsec No_Relative_Delay 8107@findex No_Relative_Delay 8108[RM D.7] This restriction ensures at compile time that there are no delay 8109relative statements and prevents expressions such as @code{delay 1.23;} from 8110appearing in source code. 8111 8112@node No_Requeue_Statements 8113@unnumberedsubsec No_Requeue_Statements 8114@findex No_Requeue_Statements 8115[RM D.7] This restriction ensures at compile time that no requeue statements 8116are permitted and prevents keyword @code{requeue} from being used in source 8117code. 8118 8119@node No_Secondary_Stack 8120@unnumberedsubsec No_Secondary_Stack 8121@findex No_Secondary_Stack 8122[GNAT] This restriction ensures at compile time that the generated code 8123does not contain any reference to the secondary stack. The secondary 8124stack is used to implement functions returning unconstrained objects 8125(arrays or records) on some targets. 8126 8127@node No_Select_Statements 8128@unnumberedsubsec No_Select_Statements 8129@findex No_Select_Statements 8130[RM D.7] This restriction ensures at compile time no select statements of any 8131kind are permitted, that is the keyword @code{select} may not appear. 8132 8133@node No_Specific_Termination_Handlers 8134@unnumberedsubsec No_Specific_Termination_Handlers 8135@findex No_Specific_Termination_Handlers 8136[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler 8137or to Ada.Task_Termination.Specific_Handler. 8138 8139@node No_Specification_of_Aspect 8140@unnumberedsubsec No_Specification_of_Aspect 8141@findex No_Specification_of_Aspect 8142[RM 13.12.1] This restriction checks at compile time that no aspect 8143specification, attribute definition clause, or pragma is given for a 8144given aspect. 8145 8146@node No_Standard_Allocators_After_Elaboration 8147@unnumberedsubsec No_Standard_Allocators_After_Elaboration 8148@findex No_Standard_Allocators_After_Elaboration 8149[RM D.7] Specifies that an allocator using a standard storage pool 8150should never be evaluated at run time after the elaboration of the 8151library items of the partition has completed. Otherwise, Storage_Error 8152is raised. 8153 8154@node No_Standard_Storage_Pools 8155@unnumberedsubsec No_Standard_Storage_Pools 8156@findex No_Standard_Storage_Pools 8157[GNAT] This restriction ensures at compile time that no access types 8158use the standard default storage pool. Any access type declared must 8159have an explicit Storage_Pool attribute defined specifying a 8160user-defined storage pool. 8161 8162@node No_Stream_Optimizations 8163@unnumberedsubsec No_Stream_Optimizations 8164@findex No_Stream_Optimizations 8165[GNAT] This restriction affects the performance of stream operations on types 8166@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the 8167compiler uses block reads and writes when manipulating @code{String} objects 8168due to their supperior performance. When this restriction is in effect, the 8169compiler performs all IO operations on a per-character basis. 8170 8171@node No_Streams 8172@unnumberedsubsec No_Streams 8173@findex No_Streams 8174[GNAT] This restriction ensures at compile/bind time that there are no 8175stream objects created and no use of stream attributes. 8176This restriction does not forbid dependences on the package 8177@code{Ada.Streams}. So it is permissible to with 8178@code{Ada.Streams} (or another package that does so itself) 8179as long as no actual stream objects are created and no 8180stream attributes are used. 8181 8182Note that the use of restriction allows optimization of tagged types, 8183since they do not need to worry about dispatching stream operations. 8184To take maximum advantage of this space-saving optimization, any 8185unit declaring a tagged type should be compiled with the restriction, 8186though this is not required. 8187 8188@node No_Task_Allocators 8189@unnumberedsubsec No_Task_Allocators 8190@findex No_Task_Allocators 8191[RM D.7] There are no allocators for task types 8192or types containing task subcomponents. 8193 8194@node No_Task_Attributes_Package 8195@unnumberedsubsec No_Task_Attributes_Package 8196@findex No_Task_Attributes_Package 8197[GNAT] This restriction ensures at compile time that there are no implicit or 8198explicit dependencies on the package @code{Ada.Task_Attributes}. 8199 8200@node No_Task_Hierarchy 8201@unnumberedsubsec No_Task_Hierarchy 8202@findex No_Task_Hierarchy 8203[RM D.7] All (non-environment) tasks depend 8204directly on the environment task of the partition. 8205 8206@node No_Task_Termination 8207@unnumberedsubsec No_Task_Termination 8208@findex No_Task_Termination 8209[RM D.7] Tasks which terminate are erroneous. 8210 8211@node No_Tasking 8212@unnumberedsubsec No_Tasking 8213@findex No_Tasking 8214[GNAT] This restriction prevents the declaration of tasks or task types 8215throughout the partition. It is similar in effect to the use of 8216@code{Max_Tasks => 0} except that violations are caught at compile time 8217and cause an error message to be output either by the compiler or 8218binder. 8219 8220@node No_Terminate_Alternatives 8221@unnumberedsubsec No_Terminate_Alternatives 8222@findex No_Terminate_Alternatives 8223[RM D.7] There are no selective accepts with terminate alternatives. 8224 8225@node No_Unchecked_Access 8226@unnumberedsubsec No_Unchecked_Access 8227@findex No_Unchecked_Access 8228[RM H.4] This restriction ensures at compile time that there are no 8229occurrences of the Unchecked_Access attribute. 8230 8231@node Simple_Barriers 8232@unnumberedsubsec Simple_Barriers 8233@findex Simple_Barriers 8234[RM D.7] This restriction ensures at compile time that barriers in entry 8235declarations for protected types are restricted to either static boolean 8236expressions or references to simple boolean variables defined in the private 8237part of the protected type. No other form of entry barriers is permitted. 8238 8239@node Static_Priorities 8240@unnumberedsubsec Static_Priorities 8241@findex Static_Priorities 8242[GNAT] This restriction ensures at compile time that all priority expressions 8243are static, and that there are no dependences on the package 8244@code{Ada.Dynamic_Priorities}. 8245 8246@node Static_Storage_Size 8247@unnumberedsubsec Static_Storage_Size 8248@findex Static_Storage_Size 8249[GNAT] This restriction ensures at compile time that any expression appearing 8250in a Storage_Size pragma or attribute definition clause is static. 8251 8252@node Program Unit Level Restrictions 8253@section Program Unit Level Restrictions 8254 8255@noindent 8256The second set of restriction identifiers 8257does not require partition-wide consistency. 8258The restriction may be enforced for a single 8259compilation unit without any effect on any of the 8260other compilation units in the partition. 8261 8262@menu 8263* No_Elaboration_Code:: 8264* No_Entry_Queue:: 8265* No_Implementation_Aspect_Specifications:: 8266* No_Implementation_Attributes:: 8267* No_Implementation_Identifiers:: 8268* No_Implementation_Pragmas:: 8269* No_Implementation_Restrictions:: 8270* No_Implementation_Units:: 8271* No_Implicit_Aliasing:: 8272* No_Obsolescent_Features:: 8273* No_Wide_Characters:: 8274* SPARK:: 8275@end menu 8276 8277@node No_Elaboration_Code 8278@unnumberedsubsec No_Elaboration_Code 8279@findex No_Elaboration_Code 8280[GNAT] This restriction ensures at compile time that no elaboration code is 8281generated. Note that this is not the same condition as is enforced 8282by pragma @code{Preelaborate}. There are cases in which pragma 8283@code{Preelaborate} still permits code to be generated (e.g.@: code 8284to initialize a large array to all zeroes), and there are cases of units 8285which do not meet the requirements for pragma @code{Preelaborate}, 8286but for which no elaboration code is generated. Generally, it is 8287the case that preelaborable units will meet the restrictions, with 8288the exception of large aggregates initialized with an others_clause, 8289and exception declarations (which generate calls to a run-time 8290registry procedure). This restriction is enforced on 8291a unit by unit basis, it need not be obeyed consistently 8292throughout a partition. 8293 8294In the case of aggregates with others, if the aggregate has a dynamic 8295size, there is no way to eliminate the elaboration code (such dynamic 8296bounds would be incompatible with @code{Preelaborate} in any case). If 8297the bounds are static, then use of this restriction actually modifies 8298the code choice of the compiler to avoid generating a loop, and instead 8299generate the aggregate statically if possible, no matter how many times 8300the data for the others clause must be repeatedly generated. 8301 8302It is not possible to precisely document 8303the constructs which are compatible with this restriction, since, 8304unlike most other restrictions, this is not a restriction on the 8305source code, but a restriction on the generated object code. For 8306example, if the source contains a declaration: 8307 8308@smallexample 8309 Val : constant Integer := X; 8310@end smallexample 8311 8312@noindent 8313where X is not a static constant, it may be possible, depending 8314on complex optimization circuitry, for the compiler to figure 8315out the value of X at compile time, in which case this initialization 8316can be done by the loader, and requires no initialization code. It 8317is not possible to document the precise conditions under which the 8318optimizer can figure this out. 8319 8320Note that this the implementation of this restriction requires full 8321code generation. If it is used in conjunction with "semantics only" 8322checking, then some cases of violations may be missed. 8323 8324@node No_Entry_Queue 8325@unnumberedsubsec No_Entry_Queue 8326@findex No_Entry_Queue 8327[GNAT] This restriction is a declaration that any protected entry compiled in 8328the scope of the restriction has at most one task waiting on the entry 8329at any one time, and so no queue is required. This restriction is not 8330checked at compile time. A program execution is erroneous if an attempt 8331is made to queue a second task on such an entry. 8332 8333@node No_Implementation_Aspect_Specifications 8334@unnumberedsubsec No_Implementation_Aspect_Specifications 8335@findex No_Implementation_Aspect_Specifications 8336[RM 13.12.1] This restriction checks at compile time that no 8337GNAT-defined aspects are present. With this restriction, the only 8338aspects that can be used are those defined in the Ada Reference Manual. 8339 8340@node No_Implementation_Attributes 8341@unnumberedsubsec No_Implementation_Attributes 8342@findex No_Implementation_Attributes 8343[RM 13.12.1] This restriction checks at compile time that no 8344GNAT-defined attributes are present. With this restriction, the only 8345attributes that can be used are those defined in the Ada Reference 8346Manual. 8347 8348@node No_Implementation_Identifiers 8349@unnumberedsubsec No_Implementation_Identifiers 8350@findex No_Implementation_Identifiers 8351[RM 13.12.1] This restriction checks at compile time that no 8352implementation-defined identifiers (marked with pragma Implementation_Defined) 8353occur within language-defined packages. 8354 8355@node No_Implementation_Pragmas 8356@unnumberedsubsec No_Implementation_Pragmas 8357@findex No_Implementation_Pragmas 8358[RM 13.12.1] This restriction checks at compile time that no 8359GNAT-defined pragmas are present. With this restriction, the only 8360pragmas that can be used are those defined in the Ada Reference Manual. 8361 8362@node No_Implementation_Restrictions 8363@unnumberedsubsec No_Implementation_Restrictions 8364@findex No_Implementation_Restrictions 8365[GNAT] This restriction checks at compile time that no GNAT-defined restriction 8366identifiers (other than @code{No_Implementation_Restrictions} itself) 8367are present. With this restriction, the only other restriction identifiers 8368that can be used are those defined in the Ada Reference Manual. 8369 8370@node No_Implementation_Units 8371@unnumberedsubsec No_Implementation_Units 8372@findex No_Implementation_Units 8373[RM 13.12.1] This restriction checks at compile time that there is no 8374mention in the context clause of any implementation-defined descendants 8375of packages Ada, Interfaces, or System. 8376 8377@node No_Implicit_Aliasing 8378@unnumberedsubsec No_Implicit_Aliasing 8379@findex No_Implicit_Aliasing 8380[GNAT] This restriction, which is not required to be partition-wide consistent, 8381requires an explicit aliased keyword for an object to which 'Access, 8382'Unchecked_Access, or 'Address is applied, and forbids entirely the use of 8383the 'Unrestricted_Access attribute for objects. Note: the reason that 8384Unrestricted_Access is forbidden is that it would require the prefix 8385to be aliased, and in such cases, it can always be replaced by 8386the standard attribute Unchecked_Access which is preferable. 8387 8388@node No_Obsolescent_Features 8389@unnumberedsubsec No_Obsolescent_Features 8390@findex No_Obsolescent_Features 8391[RM 13.12.1] This restriction checks at compile time that no obsolescent 8392features are used, as defined in Annex J of the Ada Reference Manual. 8393 8394@node No_Wide_Characters 8395@unnumberedsubsec No_Wide_Characters 8396@findex No_Wide_Characters 8397[GNAT] This restriction ensures at compile time that no uses of the types 8398@code{Wide_Character} or @code{Wide_String} or corresponding wide 8399wide types 8400appear, and that no wide or wide wide string or character literals 8401appear in the program (that is literals representing characters not in 8402type @code{Character}). 8403 8404@node SPARK 8405@unnumberedsubsec SPARK 8406@findex SPARK 8407[GNAT] This restriction checks at compile time that some constructs 8408forbidden in SPARK are not present. The SPARK version used as a 8409reference is the same as the Ada mode for the unit, so a unit compiled 8410in Ada 95 mode with SPARK restrictions will be checked for constructs 8411forbidden in SPARK 95. Error messages related to SPARK restriction have 8412the form: 8413 8414@smallexample 8415violation of restriction "SPARK" at <file> 8416 <error message> 8417@end smallexample 8418 8419This is not a replacement for the semantic checks performed by the 8420SPARK Examiner tool, as the compiler only deals currently with code, 8421not at all with SPARK annotations and does not guarantee catching all 8422cases of constructs forbidden by SPARK. 8423 8424Thus it may well be the case that code which 8425passes the compiler in SPARK mode is rejected by the SPARK Examiner, 8426e.g. due to the different visibility rules of the Examiner based on 8427SPARK @code{inherit} annotations. 8428 8429This restriction can be useful in providing an initial filter for 8430code developed using SPARK, or in examining legacy code to see how far 8431it is from meeting SPARK restrictions. 8432 8433@c ------------------------ 8434@node Implementation Advice 8435@chapter Implementation Advice 8436@noindent 8437The main text of the Ada Reference Manual describes the required 8438behavior of all Ada compilers, and the GNAT compiler conforms to 8439these requirements. 8440 8441In addition, there are sections throughout the Ada Reference Manual headed 8442by the phrase ``Implementation advice''. These sections are not normative, 8443i.e., they do not specify requirements that all compilers must 8444follow. Rather they provide advice on generally desirable behavior. You 8445may wonder why they are not requirements. The most typical answer is 8446that they describe behavior that seems generally desirable, but cannot 8447be provided on all systems, or which may be undesirable on some systems. 8448 8449As far as practical, GNAT follows the implementation advice sections in 8450the Ada Reference Manual. This chapter contains a table giving the 8451reference manual section number, paragraph number and several keywords 8452for each advice. Each entry consists of the text of the advice followed 8453by the GNAT interpretation of this advice. Most often, this simply says 8454``followed'', which means that GNAT follows the advice. However, in a 8455number of cases, GNAT deliberately deviates from this advice, in which 8456case the text describes what GNAT does and why. 8457 8458@cindex Error detection 8459@unnumberedsec 1.1.3(20): Error Detection 8460@sp 1 8461@cartouche 8462If an implementation detects the use of an unsupported Specialized Needs 8463Annex feature at run time, it should raise @code{Program_Error} if 8464feasible. 8465@end cartouche 8466Not relevant. All specialized needs annex features are either supported, 8467or diagnosed at compile time. 8468 8469@cindex Child Units 8470@unnumberedsec 1.1.3(31): Child Units 8471@sp 1 8472@cartouche 8473If an implementation wishes to provide implementation-defined 8474extensions to the functionality of a language-defined library unit, it 8475should normally do so by adding children to the library unit. 8476@end cartouche 8477Followed. 8478 8479@cindex Bounded errors 8480@unnumberedsec 1.1.5(12): Bounded Errors 8481@sp 1 8482@cartouche 8483If an implementation detects a bounded error or erroneous 8484execution, it should raise @code{Program_Error}. 8485@end cartouche 8486Followed in all cases in which the implementation detects a bounded 8487error or erroneous execution. Not all such situations are detected at 8488runtime. 8489 8490@cindex Pragmas 8491@unnumberedsec 2.8(16): Pragmas 8492@sp 1 8493@cartouche 8494Normally, implementation-defined pragmas should have no semantic effect 8495for error-free programs; that is, if the implementation-defined pragmas 8496are removed from a working program, the program should still be legal, 8497and should still have the same semantics. 8498@end cartouche 8499The following implementation defined pragmas are exceptions to this 8500rule: 8501 8502@table @code 8503@item Abort_Defer 8504Affects semantics 8505@item Ada_83 8506Affects legality 8507@item Assert 8508Affects semantics 8509@item CPP_Class 8510Affects semantics 8511@item CPP_Constructor 8512Affects semantics 8513@item Debug 8514Affects semantics 8515@item Interface_Name 8516Affects semantics 8517@item Machine_Attribute 8518Affects semantics 8519@item Unimplemented_Unit 8520Affects legality 8521@item Unchecked_Union 8522Affects semantics 8523@end table 8524 8525@noindent 8526In each of the above cases, it is essential to the purpose of the pragma 8527that this advice not be followed. For details see the separate section 8528on implementation defined pragmas. 8529 8530@unnumberedsec 2.8(17-19): Pragmas 8531@sp 1 8532@cartouche 8533Normally, an implementation should not define pragmas that can 8534make an illegal program legal, except as follows: 8535@end cartouche 8536@sp 1 8537@cartouche 8538A pragma used to complete a declaration, such as a pragma @code{Import}; 8539@end cartouche 8540@sp 1 8541@cartouche 8542A pragma used to configure the environment by adding, removing, or 8543replacing @code{library_items}. 8544@end cartouche 8545See response to paragraph 16 of this same section. 8546 8547@cindex Character Sets 8548@cindex Alternative Character Sets 8549@unnumberedsec 3.5.2(5): Alternative Character Sets 8550@sp 1 8551@cartouche 8552If an implementation supports a mode with alternative interpretations 8553for @code{Character} and @code{Wide_Character}, the set of graphic 8554characters of @code{Character} should nevertheless remain a proper 8555subset of the set of graphic characters of @code{Wide_Character}. Any 8556character set ``localizations'' should be reflected in the results of 8557the subprograms defined in the language-defined package 8558@code{Characters.Handling} (see A.3) available in such a mode. In a mode with 8559an alternative interpretation of @code{Character}, the implementation should 8560also support a corresponding change in what is a legal 8561@code{identifier_letter}. 8562@end cartouche 8563Not all wide character modes follow this advice, in particular the JIS 8564and IEC modes reflect standard usage in Japan, and in these encoding, 8565the upper half of the Latin-1 set is not part of the wide-character 8566subset, since the most significant bit is used for wide character 8567encoding. However, this only applies to the external forms. Internally 8568there is no such restriction. 8569 8570@cindex Integer types 8571@unnumberedsec 3.5.4(28): Integer Types 8572 8573@sp 1 8574@cartouche 8575An implementation should support @code{Long_Integer} in addition to 8576@code{Integer} if the target machine supports 32-bit (or longer) 8577arithmetic. No other named integer subtypes are recommended for package 8578@code{Standard}. Instead, appropriate named integer subtypes should be 8579provided in the library package @code{Interfaces} (see B.2). 8580@end cartouche 8581@code{Long_Integer} is supported. Other standard integer types are supported 8582so this advice is not fully followed. These types 8583are supported for convenient interface to C, and so that all hardware 8584types of the machine are easily available. 8585@unnumberedsec 3.5.4(29): Integer Types 8586 8587@sp 1 8588@cartouche 8589An implementation for a two's complement machine should support 8590modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 8591implementation should support a non-binary modules up to @code{Integer'Last}. 8592@end cartouche 8593Followed. 8594 8595@cindex Enumeration values 8596@unnumberedsec 3.5.5(8): Enumeration Values 8597@sp 1 8598@cartouche 8599For the evaluation of a call on @code{@var{S}'Pos} for an enumeration 8600subtype, if the value of the operand does not correspond to the internal 8601code for any enumeration literal of its type (perhaps due to an 8602un-initialized variable), then the implementation should raise 8603@code{Program_Error}. This is particularly important for enumeration 8604types with noncontiguous internal codes specified by an 8605enumeration_representation_clause. 8606@end cartouche 8607Followed. 8608 8609@cindex Float types 8610@unnumberedsec 3.5.7(17): Float Types 8611@sp 1 8612@cartouche 8613An implementation should support @code{Long_Float} in addition to 8614@code{Float} if the target machine supports 11 or more digits of 8615precision. No other named floating point subtypes are recommended for 8616package @code{Standard}. Instead, appropriate named floating point subtypes 8617should be provided in the library package @code{Interfaces} (see B.2). 8618@end cartouche 8619@code{Short_Float} and @code{Long_Long_Float} are also provided. The 8620former provides improved compatibility with other implementations 8621supporting this type. The latter corresponds to the highest precision 8622floating-point type supported by the hardware. On most machines, this 8623will be the same as @code{Long_Float}, but on some machines, it will 8624correspond to the IEEE extended form. The notable case is all ia32 8625(x86) implementations, where @code{Long_Long_Float} corresponds to 8626the 80-bit extended precision format supported in hardware on this 8627processor. Note that the 128-bit format on SPARC is not supported, 8628since this is a software rather than a hardware format. 8629 8630@cindex Multidimensional arrays 8631@cindex Arrays, multidimensional 8632@unnumberedsec 3.6.2(11): Multidimensional Arrays 8633@sp 1 8634@cartouche 8635An implementation should normally represent multidimensional arrays in 8636row-major order, consistent with the notation used for multidimensional 8637array aggregates (see 4.3.3). However, if a pragma @code{Convention} 8638(@code{Fortran}, @dots{}) applies to a multidimensional array type, then 8639column-major order should be used instead (see B.5, ``Interfacing with 8640Fortran''). 8641@end cartouche 8642Followed. 8643 8644@findex Duration'Small 8645@unnumberedsec 9.6(30-31): Duration'Small 8646@sp 1 8647@cartouche 8648Whenever possible in an implementation, the value of @code{Duration'Small} 8649should be no greater than 100 microseconds. 8650@end cartouche 8651Followed. (@code{Duration'Small} = 10**(@minus{}9)). 8652 8653@sp 1 8654@cartouche 8655The time base for @code{delay_relative_statements} should be monotonic; 8656it need not be the same time base as used for @code{Calendar.Clock}. 8657@end cartouche 8658Followed. 8659 8660@unnumberedsec 10.2.1(12): Consistent Representation 8661@sp 1 8662@cartouche 8663In an implementation, a type declared in a pre-elaborated package should 8664have the same representation in every elaboration of a given version of 8665the package, whether the elaborations occur in distinct executions of 8666the same program, or in executions of distinct programs or partitions 8667that include the given version. 8668@end cartouche 8669Followed, except in the case of tagged types. Tagged types involve 8670implicit pointers to a local copy of a dispatch table, and these pointers 8671have representations which thus depend on a particular elaboration of the 8672package. It is not easy to see how it would be possible to follow this 8673advice without severely impacting efficiency of execution. 8674 8675@cindex Exception information 8676@unnumberedsec 11.4.1(19): Exception Information 8677@sp 1 8678@cartouche 8679@code{Exception_Message} by default and @code{Exception_Information} 8680should produce information useful for 8681debugging. @code{Exception_Message} should be short, about one 8682line. @code{Exception_Information} can be long. @code{Exception_Message} 8683should not include the 8684@code{Exception_Name}. @code{Exception_Information} should include both 8685the @code{Exception_Name} and the @code{Exception_Message}. 8686@end cartouche 8687Followed. For each exception that doesn't have a specified 8688@code{Exception_Message}, the compiler generates one containing the location 8689of the raise statement. This location has the form ``file:line'', where 8690file is the short file name (without path information) and line is the line 8691number in the file. Note that in the case of the Zero Cost Exception 8692mechanism, these messages become redundant with the Exception_Information that 8693contains a full backtrace of the calling sequence, so they are disabled. 8694To disable explicitly the generation of the source location message, use the 8695Pragma @code{Discard_Names}. 8696 8697@cindex Suppression of checks 8698@cindex Checks, suppression of 8699@unnumberedsec 11.5(28): Suppression of Checks 8700@sp 1 8701@cartouche 8702The implementation should minimize the code executed for checks that 8703have been suppressed. 8704@end cartouche 8705Followed. 8706 8707@cindex Representation clauses 8708@unnumberedsec 13.1 (21-24): Representation Clauses 8709@sp 1 8710@cartouche 8711The recommended level of support for all representation items is 8712qualified as follows: 8713@end cartouche 8714@sp 1 8715@cartouche 8716An implementation need not support representation items containing 8717non-static expressions, except that an implementation should support a 8718representation item for a given entity if each non-static expression in 8719the representation item is a name that statically denotes a constant 8720declared before the entity. 8721@end cartouche 8722Followed. In fact, GNAT goes beyond the recommended level of support 8723by allowing nonstatic expressions in some representation clauses even 8724without the need to declare constants initialized with the values of 8725such expressions. 8726For example: 8727 8728@smallexample @c ada 8729 X : Integer; 8730 Y : Float; 8731 for Y'Address use X'Address;>> 8732@end smallexample 8733 8734@sp 1 8735@cartouche 8736An implementation need not support a specification for the @code{Size} 8737for a given composite subtype, nor the size or storage place for an 8738object (including a component) of a given composite subtype, unless the 8739constraints on the subtype and its composite subcomponents (if any) are 8740all static constraints. 8741@end cartouche 8742Followed. Size Clauses are not permitted on non-static components, as 8743described above. 8744 8745@sp 1 8746@cartouche 8747An aliased component, or a component whose type is by-reference, should 8748always be allocated at an addressable location. 8749@end cartouche 8750Followed. 8751 8752@cindex Packed types 8753@unnumberedsec 13.2(6-8): Packed Types 8754@sp 1 8755@cartouche 8756If a type is packed, then the implementation should try to minimize 8757storage allocated to objects of the type, possibly at the expense of 8758speed of accessing components, subject to reasonable complexity in 8759addressing calculations. 8760@end cartouche 8761@sp 1 8762@cartouche 8763The recommended level of support pragma @code{Pack} is: 8764 8765For a packed record type, the components should be packed as tightly as 8766possible subject to the Sizes of the component subtypes, and subject to 8767any @code{record_representation_clause} that applies to the type; the 8768implementation may, but need not, reorder components or cross aligned 8769word boundaries to improve the packing. A component whose @code{Size} is 8770greater than the word size may be allocated an integral number of words. 8771@end cartouche 8772Followed. Tight packing of arrays is supported for all component sizes 8773up to 64-bits. If the array component size is 1 (that is to say, if 8774the component is a boolean type or an enumeration type with two values) 8775then values of the type are implicitly initialized to zero. This 8776happens both for objects of the packed type, and for objects that have a 8777subcomponent of the packed type. 8778 8779@sp 1 8780@cartouche 8781An implementation should support Address clauses for imported 8782subprograms. 8783@end cartouche 8784Followed. 8785@cindex @code{Address} clauses 8786@unnumberedsec 13.3(14-19): Address Clauses 8787 8788@sp 1 8789@cartouche 8790For an array @var{X}, @code{@var{X}'Address} should point at the first 8791component of the array, and not at the array bounds. 8792@end cartouche 8793Followed. 8794 8795@sp 1 8796@cartouche 8797The recommended level of support for the @code{Address} attribute is: 8798 8799@code{@var{X}'Address} should produce a useful result if @var{X} is an 8800object that is aliased or of a by-reference type, or is an entity whose 8801@code{Address} has been specified. 8802@end cartouche 8803Followed. A valid address will be produced even if none of those 8804conditions have been met. If necessary, the object is forced into 8805memory to ensure the address is valid. 8806 8807@sp 1 8808@cartouche 8809An implementation should support @code{Address} clauses for imported 8810subprograms. 8811@end cartouche 8812Followed. 8813 8814@sp 1 8815@cartouche 8816Objects (including subcomponents) that are aliased or of a by-reference 8817type should be allocated on storage element boundaries. 8818@end cartouche 8819Followed. 8820 8821@sp 1 8822@cartouche 8823If the @code{Address} of an object is specified, or it is imported or exported, 8824then the implementation should not perform optimizations based on 8825assumptions of no aliases. 8826@end cartouche 8827Followed. 8828 8829@cindex @code{Alignment} clauses 8830@unnumberedsec 13.3(29-35): Alignment Clauses 8831@sp 1 8832@cartouche 8833The recommended level of support for the @code{Alignment} attribute for 8834subtypes is: 8835 8836An implementation should support specified Alignments that are factors 8837and multiples of the number of storage elements per word, subject to the 8838following: 8839@end cartouche 8840Followed. 8841 8842@sp 1 8843@cartouche 8844An implementation need not support specified @code{Alignment}s for 8845combinations of @code{Size}s and @code{Alignment}s that cannot be easily 8846loaded and stored by available machine instructions. 8847@end cartouche 8848Followed. 8849 8850@sp 1 8851@cartouche 8852An implementation need not support specified @code{Alignment}s that are 8853greater than the maximum @code{Alignment} the implementation ever returns by 8854default. 8855@end cartouche 8856Followed. 8857 8858@sp 1 8859@cartouche 8860The recommended level of support for the @code{Alignment} attribute for 8861objects is: 8862 8863Same as above, for subtypes, but in addition: 8864@end cartouche 8865Followed. 8866 8867@sp 1 8868@cartouche 8869For stand-alone library-level objects of statically constrained 8870subtypes, the implementation should support all @code{Alignment}s 8871supported by the target linker. For example, page alignment is likely to 8872be supported for such objects, but not for subtypes. 8873@end cartouche 8874Followed. 8875 8876@cindex @code{Size} clauses 8877@unnumberedsec 13.3(42-43): Size Clauses 8878@sp 1 8879@cartouche 8880The recommended level of support for the @code{Size} attribute of 8881objects is: 8882 8883A @code{Size} clause should be supported for an object if the specified 8884@code{Size} is at least as large as its subtype's @code{Size}, and 8885corresponds to a size in storage elements that is a multiple of the 8886object's @code{Alignment} (if the @code{Alignment} is nonzero). 8887@end cartouche 8888Followed. 8889 8890@unnumberedsec 13.3(50-56): Size Clauses 8891@sp 1 8892@cartouche 8893If the @code{Size} of a subtype is specified, and allows for efficient 8894independent addressability (see 9.10) on the target architecture, then 8895the @code{Size} of the following objects of the subtype should equal the 8896@code{Size} of the subtype: 8897 8898Aliased objects (including components). 8899@end cartouche 8900Followed. 8901 8902@sp 1 8903@cartouche 8904@code{Size} clause on a composite subtype should not affect the 8905internal layout of components. 8906@end cartouche 8907Followed. But note that this can be overridden by use of the implementation 8908pragma Implicit_Packing in the case of packed arrays. 8909 8910@sp 1 8911@cartouche 8912The recommended level of support for the @code{Size} attribute of subtypes is: 8913@end cartouche 8914@sp 1 8915@cartouche 8916The @code{Size} (if not specified) of a static discrete or fixed point 8917subtype should be the number of bits needed to represent each value 8918belonging to the subtype using an unbiased representation, leaving space 8919for a sign bit only if the subtype contains negative values. If such a 8920subtype is a first subtype, then an implementation should support a 8921specified @code{Size} for it that reflects this representation. 8922@end cartouche 8923Followed. 8924 8925@sp 1 8926@cartouche 8927For a subtype implemented with levels of indirection, the @code{Size} 8928should include the size of the pointers, but not the size of what they 8929point at. 8930@end cartouche 8931Followed. 8932 8933@cindex @code{Component_Size} clauses 8934@unnumberedsec 13.3(71-73): Component Size Clauses 8935@sp 1 8936@cartouche 8937The recommended level of support for the @code{Component_Size} 8938attribute is: 8939@end cartouche 8940@sp 1 8941@cartouche 8942An implementation need not support specified @code{Component_Sizes} that are 8943less than the @code{Size} of the component subtype. 8944@end cartouche 8945Followed. 8946 8947@sp 1 8948@cartouche 8949An implementation should support specified @code{Component_Size}s that 8950are factors and multiples of the word size. For such 8951@code{Component_Size}s, the array should contain no gaps between 8952components. For other @code{Component_Size}s (if supported), the array 8953should contain no gaps between components when packing is also 8954specified; the implementation should forbid this combination in cases 8955where it cannot support a no-gaps representation. 8956@end cartouche 8957Followed. 8958 8959@cindex Enumeration representation clauses 8960@cindex Representation clauses, enumeration 8961@unnumberedsec 13.4(9-10): Enumeration Representation Clauses 8962@sp 1 8963@cartouche 8964The recommended level of support for enumeration representation clauses 8965is: 8966 8967An implementation need not support enumeration representation clauses 8968for boolean types, but should at minimum support the internal codes in 8969the range @code{System.Min_Int.System.Max_Int}. 8970@end cartouche 8971Followed. 8972 8973@cindex Record representation clauses 8974@cindex Representation clauses, records 8975@unnumberedsec 13.5.1(17-22): Record Representation Clauses 8976@sp 1 8977@cartouche 8978The recommended level of support for 8979@*@code{record_representation_clauses} is: 8980 8981An implementation should support storage places that can be extracted 8982with a load, mask, shift sequence of machine code, and set with a load, 8983shift, mask, store sequence, given the available machine instructions 8984and run-time model. 8985@end cartouche 8986Followed. 8987 8988@sp 1 8989@cartouche 8990A storage place should be supported if its size is equal to the 8991@code{Size} of the component subtype, and it starts and ends on a 8992boundary that obeys the @code{Alignment} of the component subtype. 8993@end cartouche 8994Followed. 8995 8996@sp 1 8997@cartouche 8998If the default bit ordering applies to the declaration of a given type, 8999then for a component whose subtype's @code{Size} is less than the word 9000size, any storage place that does not cross an aligned word boundary 9001should be supported. 9002@end cartouche 9003Followed. 9004 9005@sp 1 9006@cartouche 9007An implementation may reserve a storage place for the tag field of a 9008tagged type, and disallow other components from overlapping that place. 9009@end cartouche 9010Followed. The storage place for the tag field is the beginning of the tagged 9011record, and its size is Address'Size. GNAT will reject an explicit component 9012clause for the tag field. 9013 9014@sp 1 9015@cartouche 9016An implementation need not support a @code{component_clause} for a 9017component of an extension part if the storage place is not after the 9018storage places of all components of the parent type, whether or not 9019those storage places had been specified. 9020@end cartouche 9021Followed. The above advice on record representation clauses is followed, 9022and all mentioned features are implemented. 9023 9024@cindex Storage place attributes 9025@unnumberedsec 13.5.2(5): Storage Place Attributes 9026@sp 1 9027@cartouche 9028If a component is represented using some form of pointer (such as an 9029offset) to the actual data of the component, and this data is contiguous 9030with the rest of the object, then the storage place attributes should 9031reflect the place of the actual data, not the pointer. If a component is 9032allocated discontinuously from the rest of the object, then a warning 9033should be generated upon reference to one of its storage place 9034attributes. 9035@end cartouche 9036Followed. There are no such components in GNAT@. 9037 9038@cindex Bit ordering 9039@unnumberedsec 13.5.3(7-8): Bit Ordering 9040@sp 1 9041@cartouche 9042The recommended level of support for the non-default bit ordering is: 9043@end cartouche 9044@sp 1 9045@cartouche 9046If @code{Word_Size} = @code{Storage_Unit}, then the implementation 9047should support the non-default bit ordering in addition to the default 9048bit ordering. 9049@end cartouche 9050Followed. Word size does not equal storage size in this implementation. 9051Thus non-default bit ordering is not supported. 9052 9053@cindex @code{Address}, as private type 9054@unnumberedsec 13.7(37): Address as Private 9055@sp 1 9056@cartouche 9057@code{Address} should be of a private type. 9058@end cartouche 9059Followed. 9060 9061@cindex Operations, on @code{Address} 9062@cindex @code{Address}, operations of 9063@unnumberedsec 13.7.1(16): Address Operations 9064@sp 1 9065@cartouche 9066Operations in @code{System} and its children should reflect the target 9067environment semantics as closely as is reasonable. For example, on most 9068machines, it makes sense for address arithmetic to ``wrap around''. 9069Operations that do not make sense should raise @code{Program_Error}. 9070@end cartouche 9071Followed. Address arithmetic is modular arithmetic that wraps around. No 9072operation raises @code{Program_Error}, since all operations make sense. 9073 9074@cindex Unchecked conversion 9075@unnumberedsec 13.9(14-17): Unchecked Conversion 9076@sp 1 9077@cartouche 9078The @code{Size} of an array object should not include its bounds; hence, 9079the bounds should not be part of the converted data. 9080@end cartouche 9081Followed. 9082 9083@sp 1 9084@cartouche 9085The implementation should not generate unnecessary run-time checks to 9086ensure that the representation of @var{S} is a representation of the 9087target type. It should take advantage of the permission to return by 9088reference when possible. Restrictions on unchecked conversions should be 9089avoided unless required by the target environment. 9090@end cartouche 9091Followed. There are no restrictions on unchecked conversion. A warning is 9092generated if the source and target types do not have the same size since 9093the semantics in this case may be target dependent. 9094 9095@sp 1 9096@cartouche 9097The recommended level of support for unchecked conversions is: 9098@end cartouche 9099@sp 1 9100@cartouche 9101Unchecked conversions should be supported and should be reversible in 9102the cases where this clause defines the result. To enable meaningful use 9103of unchecked conversion, a contiguous representation should be used for 9104elementary subtypes, for statically constrained array subtypes whose 9105component subtype is one of the subtypes described in this paragraph, 9106and for record subtypes without discriminants whose component subtypes 9107are described in this paragraph. 9108@end cartouche 9109Followed. 9110 9111@cindex Heap usage, implicit 9112@unnumberedsec 13.11(23-25): Implicit Heap Usage 9113@sp 1 9114@cartouche 9115An implementation should document any cases in which it dynamically 9116allocates heap storage for a purpose other than the evaluation of an 9117allocator. 9118@end cartouche 9119Followed, the only other points at which heap storage is dynamically 9120allocated are as follows: 9121 9122@itemize @bullet 9123@item 9124At initial elaboration time, to allocate dynamically sized global 9125objects. 9126 9127@item 9128To allocate space for a task when a task is created. 9129 9130@item 9131To extend the secondary stack dynamically when needed. The secondary 9132stack is used for returning variable length results. 9133@end itemize 9134 9135@sp 1 9136@cartouche 9137A default (implementation-provided) storage pool for an 9138access-to-constant type should not have overhead to support deallocation of 9139individual objects. 9140@end cartouche 9141Followed. 9142 9143@sp 1 9144@cartouche 9145A storage pool for an anonymous access type should be created at the 9146point of an allocator for the type, and be reclaimed when the designated 9147object becomes inaccessible. 9148@end cartouche 9149Followed. 9150 9151@cindex Unchecked deallocation 9152@unnumberedsec 13.11.2(17): Unchecked De-allocation 9153@sp 1 9154@cartouche 9155For a standard storage pool, @code{Free} should actually reclaim the 9156storage. 9157@end cartouche 9158Followed. 9159 9160@cindex Stream oriented attributes 9161@unnumberedsec 13.13.2(17): Stream Oriented Attributes 9162@sp 1 9163@cartouche 9164If a stream element is the same size as a storage element, then the 9165normal in-memory representation should be used by @code{Read} and 9166@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write} 9167should use the smallest number of stream elements needed to represent 9168all values in the base range of the scalar type. 9169@end cartouche 9170 9171Followed. By default, GNAT uses the interpretation suggested by AI-195, 9172which specifies using the size of the first subtype. 9173However, such an implementation is based on direct binary 9174representations and is therefore target- and endianness-dependent. 9175To address this issue, GNAT also supplies an alternate implementation 9176of the stream attributes @code{Read} and @code{Write}, 9177which uses the target-independent XDR standard representation 9178for scalar types. 9179@cindex XDR representation 9180@cindex @code{Read} attribute 9181@cindex @code{Write} attribute 9182@cindex Stream oriented attributes 9183The XDR implementation is provided as an alternative body of the 9184@code{System.Stream_Attributes} package, in the file 9185@file{s-stratt-xdr.adb} in the GNAT library. 9186There is no @file{s-stratt-xdr.ads} file. 9187In order to install the XDR implementation, do the following: 9188@enumerate 9189@item Replace the default implementation of the 9190@code{System.Stream_Attributes} package with the XDR implementation. 9191For example on a Unix platform issue the commands: 9192@smallexample 9193$ mv s-stratt.adb s-stratt-default.adb 9194$ mv s-stratt-xdr.adb s-stratt.adb 9195@end smallexample 9196 9197@item 9198Rebuild the GNAT run-time library as documented in 9199@ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} User's Guide}. 9200@end enumerate 9201 9202@unnumberedsec A.1(52): Names of Predefined Numeric Types 9203@sp 1 9204@cartouche 9205If an implementation provides additional named predefined integer types, 9206then the names should end with @samp{Integer} as in 9207@samp{Long_Integer}. If an implementation provides additional named 9208predefined floating point types, then the names should end with 9209@samp{Float} as in @samp{Long_Float}. 9210@end cartouche 9211Followed. 9212 9213@findex Ada.Characters.Handling 9214@unnumberedsec A.3.2(49): @code{Ada.Characters.Handling} 9215@sp 1 9216@cartouche 9217If an implementation provides a localized definition of @code{Character} 9218or @code{Wide_Character}, then the effects of the subprograms in 9219@code{Characters.Handling} should reflect the localizations. See also 92203.5.2. 9221@end cartouche 9222Followed. GNAT provides no such localized definitions. 9223 9224@cindex Bounded-length strings 9225@unnumberedsec A.4.4(106): Bounded-Length String Handling 9226@sp 1 9227@cartouche 9228Bounded string objects should not be implemented by implicit pointers 9229and dynamic allocation. 9230@end cartouche 9231Followed. No implicit pointers or dynamic allocation are used. 9232 9233@cindex Random number generation 9234@unnumberedsec A.5.2(46-47): Random Number Generation 9235@sp 1 9236@cartouche 9237Any storage associated with an object of type @code{Generator} should be 9238reclaimed on exit from the scope of the object. 9239@end cartouche 9240Followed. 9241 9242@sp 1 9243@cartouche 9244If the generator period is sufficiently long in relation to the number 9245of distinct initiator values, then each possible value of 9246@code{Initiator} passed to @code{Reset} should initiate a sequence of 9247random numbers that does not, in a practical sense, overlap the sequence 9248initiated by any other value. If this is not possible, then the mapping 9249between initiator values and generator states should be a rapidly 9250varying function of the initiator value. 9251@end cartouche 9252Followed. The generator period is sufficiently long for the first 9253condition here to hold true. 9254 9255@findex Get_Immediate 9256@unnumberedsec A.10.7(23): @code{Get_Immediate} 9257@sp 1 9258@cartouche 9259The @code{Get_Immediate} procedures should be implemented with 9260unbuffered input. For a device such as a keyboard, input should be 9261@dfn{available} if a key has already been typed, whereas for a disk 9262file, input should always be available except at end of file. For a file 9263associated with a keyboard-like device, any line-editing features of the 9264underlying operating system should be disabled during the execution of 9265@code{Get_Immediate}. 9266@end cartouche 9267Followed on all targets except VxWorks. For VxWorks, there is no way to 9268provide this functionality that does not result in the input buffer being 9269flushed before the @code{Get_Immediate} call. A special unit 9270@code{Interfaces.Vxworks.IO} is provided that contains routines to enable 9271this functionality. 9272 9273@findex Export 9274@unnumberedsec B.1(39-41): Pragma @code{Export} 9275@sp 1 9276@cartouche 9277If an implementation supports pragma @code{Export} to a given language, 9278then it should also allow the main subprogram to be written in that 9279language. It should support some mechanism for invoking the elaboration 9280of the Ada library units included in the system, and for invoking the 9281finalization of the environment task. On typical systems, the 9282recommended mechanism is to provide two subprograms whose link names are 9283@code{adainit} and @code{adafinal}. @code{adainit} should contain the 9284elaboration code for library units. @code{adafinal} should contain the 9285finalization code. These subprograms should have no effect the second 9286and subsequent time they are called. 9287@end cartouche 9288Followed. 9289 9290@sp 1 9291@cartouche 9292Automatic elaboration of pre-elaborated packages should be 9293provided when pragma @code{Export} is supported. 9294@end cartouche 9295Followed when the main program is in Ada. If the main program is in a 9296foreign language, then 9297@code{adainit} must be called to elaborate pre-elaborated 9298packages. 9299 9300@sp 1 9301@cartouche 9302For each supported convention @var{L} other than @code{Intrinsic}, an 9303implementation should support @code{Import} and @code{Export} pragmas 9304for objects of @var{L}-compatible types and for subprograms, and pragma 9305@code{Convention} for @var{L}-eligible types and for subprograms, 9306presuming the other language has corresponding features. Pragma 9307@code{Convention} need not be supported for scalar types. 9308@end cartouche 9309Followed. 9310 9311@cindex Package @code{Interfaces} 9312@findex Interfaces 9313@unnumberedsec B.2(12-13): Package @code{Interfaces} 9314@sp 1 9315@cartouche 9316For each implementation-defined convention identifier, there should be a 9317child package of package Interfaces with the corresponding name. This 9318package should contain any declarations that would be useful for 9319interfacing to the language (implementation) represented by the 9320convention. Any declarations useful for interfacing to any language on 9321the given hardware architecture should be provided directly in 9322@code{Interfaces}. 9323@end cartouche 9324Followed. An additional package not defined 9325in the Ada Reference Manual is @code{Interfaces.CPP}, used 9326for interfacing to C++. 9327 9328@sp 1 9329@cartouche 9330An implementation supporting an interface to C, COBOL, or Fortran should 9331provide the corresponding package or packages described in the following 9332clauses. 9333@end cartouche 9334Followed. GNAT provides all the packages described in this section. 9335 9336@cindex C, interfacing with 9337@unnumberedsec B.3(63-71): Interfacing with C 9338@sp 1 9339@cartouche 9340An implementation should support the following interface correspondences 9341between Ada and C@. 9342@end cartouche 9343Followed. 9344 9345@sp 1 9346@cartouche 9347An Ada procedure corresponds to a void-returning C function. 9348@end cartouche 9349Followed. 9350 9351@sp 1 9352@cartouche 9353An Ada function corresponds to a non-void C function. 9354@end cartouche 9355Followed. 9356 9357@sp 1 9358@cartouche 9359An Ada @code{in} scalar parameter is passed as a scalar argument to a C 9360function. 9361@end cartouche 9362Followed. 9363 9364@sp 1 9365@cartouche 9366An Ada @code{in} parameter of an access-to-object type with designated 9367type @var{T} is passed as a @code{@var{t}*} argument to a C function, 9368where @var{t} is the C type corresponding to the Ada type @var{T}. 9369@end cartouche 9370Followed. 9371 9372@sp 1 9373@cartouche 9374An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out} 9375parameter of an elementary type @var{T}, is passed as a @code{@var{t}*} 9376argument to a C function, where @var{t} is the C type corresponding to 9377the Ada type @var{T}. In the case of an elementary @code{out} or 9378@code{in out} parameter, a pointer to a temporary copy is used to 9379preserve by-copy semantics. 9380@end cartouche 9381Followed. 9382 9383@sp 1 9384@cartouche 9385An Ada parameter of a record type @var{T}, of any mode, is passed as a 9386@code{@var{t}*} argument to a C function, where @var{t} is the C 9387structure corresponding to the Ada type @var{T}. 9388@end cartouche 9389Followed. This convention may be overridden by the use of the C_Pass_By_Copy 9390pragma, or Convention, or by explicitly specifying the mechanism for a given 9391call using an extended import or export pragma. 9392 9393@sp 1 9394@cartouche 9395An Ada parameter of an array type with component type @var{T}, of any 9396mode, is passed as a @code{@var{t}*} argument to a C function, where 9397@var{t} is the C type corresponding to the Ada type @var{T}. 9398@end cartouche 9399Followed. 9400 9401@sp 1 9402@cartouche 9403An Ada parameter of an access-to-subprogram type is passed as a pointer 9404to a C function whose prototype corresponds to the designated 9405subprogram's specification. 9406@end cartouche 9407Followed. 9408 9409@cindex COBOL, interfacing with 9410@unnumberedsec B.4(95-98): Interfacing with COBOL 9411@sp 1 9412@cartouche 9413An Ada implementation should support the following interface 9414correspondences between Ada and COBOL@. 9415@end cartouche 9416Followed. 9417 9418@sp 1 9419@cartouche 9420An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of 9421the COBOL type corresponding to @var{T}. 9422@end cartouche 9423Followed. 9424 9425@sp 1 9426@cartouche 9427An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of 9428the corresponding COBOL type. 9429@end cartouche 9430Followed. 9431 9432@sp 1 9433@cartouche 9434Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the 9435COBOL type corresponding to the Ada parameter type; for scalars, a local 9436copy is used if necessary to ensure by-copy semantics. 9437@end cartouche 9438Followed. 9439 9440@cindex Fortran, interfacing with 9441@unnumberedsec B.5(22-26): Interfacing with Fortran 9442@sp 1 9443@cartouche 9444An Ada implementation should support the following interface 9445correspondences between Ada and Fortran: 9446@end cartouche 9447Followed. 9448 9449@sp 1 9450@cartouche 9451An Ada procedure corresponds to a Fortran subroutine. 9452@end cartouche 9453Followed. 9454 9455@sp 1 9456@cartouche 9457An Ada function corresponds to a Fortran function. 9458@end cartouche 9459Followed. 9460 9461@sp 1 9462@cartouche 9463An Ada parameter of an elementary, array, or record type @var{T} is 9464passed as a @var{T} argument to a Fortran procedure, where @var{T} is 9465the Fortran type corresponding to the Ada type @var{T}, and where the 9466INTENT attribute of the corresponding dummy argument matches the Ada 9467formal parameter mode; the Fortran implementation's parameter passing 9468conventions are used. For elementary types, a local copy is used if 9469necessary to ensure by-copy semantics. 9470@end cartouche 9471Followed. 9472 9473@sp 1 9474@cartouche 9475An Ada parameter of an access-to-subprogram type is passed as a 9476reference to a Fortran procedure whose interface corresponds to the 9477designated subprogram's specification. 9478@end cartouche 9479Followed. 9480 9481@cindex Machine operations 9482@unnumberedsec C.1(3-5): Access to Machine Operations 9483@sp 1 9484@cartouche 9485The machine code or intrinsic support should allow access to all 9486operations normally available to assembly language programmers for the 9487target environment, including privileged instructions, if any. 9488@end cartouche 9489Followed. 9490 9491@sp 1 9492@cartouche 9493The interfacing pragmas (see Annex B) should support interface to 9494assembler; the default assembler should be associated with the 9495convention identifier @code{Assembler}. 9496@end cartouche 9497Followed. 9498 9499@sp 1 9500@cartouche 9501If an entity is exported to assembly language, then the implementation 9502should allocate it at an addressable location, and should ensure that it 9503is retained by the linking process, even if not otherwise referenced 9504from the Ada code. The implementation should assume that any call to a 9505machine code or assembler subprogram is allowed to read or update every 9506object that is specified as exported. 9507@end cartouche 9508Followed. 9509 9510@unnumberedsec C.1(10-16): Access to Machine Operations 9511@sp 1 9512@cartouche 9513The implementation should ensure that little or no overhead is 9514associated with calling intrinsic and machine-code subprograms. 9515@end cartouche 9516Followed for both intrinsics and machine-code subprograms. 9517 9518@sp 1 9519@cartouche 9520It is recommended that intrinsic subprograms be provided for convenient 9521access to any machine operations that provide special capabilities or 9522efficiency and that are not otherwise available through the language 9523constructs. 9524@end cartouche 9525Followed. A full set of machine operation intrinsic subprograms is provided. 9526 9527@sp 1 9528@cartouche 9529Atomic read-modify-write operations---e.g.@:, test and set, compare and 9530swap, decrement and test, enqueue/dequeue. 9531@end cartouche 9532Followed on any target supporting such operations. 9533 9534@sp 1 9535@cartouche 9536Standard numeric functions---e.g.@:, sin, log. 9537@end cartouche 9538Followed on any target supporting such operations. 9539 9540@sp 1 9541@cartouche 9542String manipulation operations---e.g.@:, translate and test. 9543@end cartouche 9544Followed on any target supporting such operations. 9545 9546@sp 1 9547@cartouche 9548Vector operations---e.g.@:, compare vector against thresholds. 9549@end cartouche 9550Followed on any target supporting such operations. 9551 9552@sp 1 9553@cartouche 9554Direct operations on I/O ports. 9555@end cartouche 9556Followed on any target supporting such operations. 9557 9558@cindex Interrupt support 9559@unnumberedsec C.3(28): Interrupt Support 9560@sp 1 9561@cartouche 9562If the @code{Ceiling_Locking} policy is not in effect, the 9563implementation should provide means for the application to specify which 9564interrupts are to be blocked during protected actions, if the underlying 9565system allows for a finer-grain control of interrupt blocking. 9566@end cartouche 9567Followed. The underlying system does not allow for finer-grain control 9568of interrupt blocking. 9569 9570@cindex Protected procedure handlers 9571@unnumberedsec C.3.1(20-21): Protected Procedure Handlers 9572@sp 1 9573@cartouche 9574Whenever possible, the implementation should allow interrupt handlers to 9575be called directly by the hardware. 9576@end cartouche 9577Followed on any target where the underlying operating system permits 9578such direct calls. 9579 9580@sp 1 9581@cartouche 9582Whenever practical, violations of any 9583implementation-defined restrictions should be detected before run time. 9584@end cartouche 9585Followed. Compile time warnings are given when possible. 9586 9587@cindex Package @code{Interrupts} 9588@findex Interrupts 9589@unnumberedsec C.3.2(25): Package @code{Interrupts} 9590 9591@sp 1 9592@cartouche 9593If implementation-defined forms of interrupt handler procedures are 9594supported, such as protected procedures with parameters, then for each 9595such form of a handler, a type analogous to @code{Parameterless_Handler} 9596should be specified in a child package of @code{Interrupts}, with the 9597same operations as in the predefined package Interrupts. 9598@end cartouche 9599Followed. 9600 9601@cindex Pre-elaboration requirements 9602@unnumberedsec C.4(14): Pre-elaboration Requirements 9603@sp 1 9604@cartouche 9605It is recommended that pre-elaborated packages be implemented in such a 9606way that there should be little or no code executed at run time for the 9607elaboration of entities not already covered by the Implementation 9608Requirements. 9609@end cartouche 9610Followed. Executable code is generated in some cases, e.g.@: loops 9611to initialize large arrays. 9612 9613@unnumberedsec C.5(8): Pragma @code{Discard_Names} 9614@sp 1 9615@cartouche 9616If the pragma applies to an entity, then the implementation should 9617reduce the amount of storage used for storing names associated with that 9618entity. 9619@end cartouche 9620Followed. 9621 9622@cindex Package @code{Task_Attributes} 9623@findex Task_Attributes 9624@unnumberedsec C.7.2(30): The Package Task_Attributes 9625@sp 1 9626@cartouche 9627Some implementations are targeted to domains in which memory use at run 9628time must be completely deterministic. For such implementations, it is 9629recommended that the storage for task attributes will be pre-allocated 9630statically and not from the heap. This can be accomplished by either 9631placing restrictions on the number and the size of the task's 9632attributes, or by using the pre-allocated storage for the first @var{N} 9633attribute objects, and the heap for the others. In the latter case, 9634@var{N} should be documented. 9635@end cartouche 9636Not followed. This implementation is not targeted to such a domain. 9637 9638@cindex Locking Policies 9639@unnumberedsec D.3(17): Locking Policies 9640 9641@sp 1 9642@cartouche 9643The implementation should use names that end with @samp{_Locking} for 9644locking policies defined by the implementation. 9645@end cartouche 9646Followed. Two implementation-defined locking policies are defined, 9647whose names (@code{Inheritance_Locking} and 9648@code{Concurrent_Readers_Locking}) follow this suggestion. 9649 9650@cindex Entry queuing policies 9651@unnumberedsec D.4(16): Entry Queuing Policies 9652@sp 1 9653@cartouche 9654Names that end with @samp{_Queuing} should be used 9655for all implementation-defined queuing policies. 9656@end cartouche 9657Followed. No such implementation-defined queuing policies exist. 9658 9659@cindex Preemptive abort 9660@unnumberedsec D.6(9-10): Preemptive Abort 9661@sp 1 9662@cartouche 9663Even though the @code{abort_statement} is included in the list of 9664potentially blocking operations (see 9.5.1), it is recommended that this 9665statement be implemented in a way that never requires the task executing 9666the @code{abort_statement} to block. 9667@end cartouche 9668Followed. 9669 9670@sp 1 9671@cartouche 9672On a multi-processor, the delay associated with aborting a task on 9673another processor should be bounded; the implementation should use 9674periodic polling, if necessary, to achieve this. 9675@end cartouche 9676Followed. 9677 9678@cindex Tasking restrictions 9679@unnumberedsec D.7(21): Tasking Restrictions 9680@sp 1 9681@cartouche 9682When feasible, the implementation should take advantage of the specified 9683restrictions to produce a more efficient implementation. 9684@end cartouche 9685GNAT currently takes advantage of these restrictions by providing an optimized 9686run time when the Ravenscar profile and the GNAT restricted run time set 9687of restrictions are specified. See pragma @code{Profile (Ravenscar)} and 9688pragma @code{Profile (Restricted)} for more details. 9689 9690@cindex Time, monotonic 9691@unnumberedsec D.8(47-49): Monotonic Time 9692@sp 1 9693@cartouche 9694When appropriate, implementations should provide configuration 9695mechanisms to change the value of @code{Tick}. 9696@end cartouche 9697Such configuration mechanisms are not appropriate to this implementation 9698and are thus not supported. 9699 9700@sp 1 9701@cartouche 9702It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} 9703be implemented as transformations of the same time base. 9704@end cartouche 9705Followed. 9706 9707@sp 1 9708@cartouche 9709It is recommended that the @dfn{best} time base which exists in 9710the underlying system be available to the application through 9711@code{Clock}. @dfn{Best} may mean highest accuracy or largest range. 9712@end cartouche 9713Followed. 9714 9715@cindex Partition communication subsystem 9716@cindex PCS 9717@unnumberedsec E.5(28-29): Partition Communication Subsystem 9718@sp 1 9719@cartouche 9720Whenever possible, the PCS on the called partition should allow for 9721multiple tasks to call the RPC-receiver with different messages and 9722should allow them to block until the corresponding subprogram body 9723returns. 9724@end cartouche 9725Followed by GLADE, a separately supplied PCS that can be used with 9726GNAT. 9727 9728@sp 1 9729@cartouche 9730The @code{Write} operation on a stream of type @code{Params_Stream_Type} 9731should raise @code{Storage_Error} if it runs out of space trying to 9732write the @code{Item} into the stream. 9733@end cartouche 9734Followed by GLADE, a separately supplied PCS that can be used with 9735GNAT@. 9736 9737@cindex COBOL support 9738@unnumberedsec F(7): COBOL Support 9739@sp 1 9740@cartouche 9741If COBOL (respectively, C) is widely supported in the target 9742environment, implementations supporting the Information Systems Annex 9743should provide the child package @code{Interfaces.COBOL} (respectively, 9744@code{Interfaces.C}) specified in Annex B and should support a 9745@code{convention_identifier} of COBOL (respectively, C) in the interfacing 9746pragmas (see Annex B), thus allowing Ada programs to interface with 9747programs written in that language. 9748@end cartouche 9749Followed. 9750 9751@cindex Decimal radix support 9752@unnumberedsec F.1(2): Decimal Radix Support 9753@sp 1 9754@cartouche 9755Packed decimal should be used as the internal representation for objects 9756of subtype @var{S} when @var{S}'Machine_Radix = 10. 9757@end cartouche 9758Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary 9759representations. 9760 9761@cindex Numerics 9762@unnumberedsec G: Numerics 9763@sp 2 9764@cartouche 9765If Fortran (respectively, C) is widely supported in the target 9766environment, implementations supporting the Numerics Annex 9767should provide the child package @code{Interfaces.Fortran} (respectively, 9768@code{Interfaces.C}) specified in Annex B and should support a 9769@code{convention_identifier} of Fortran (respectively, C) in the interfacing 9770pragmas (see Annex B), thus allowing Ada programs to interface with 9771programs written in that language. 9772@end cartouche 9773Followed. 9774 9775@cindex Complex types 9776@unnumberedsec G.1.1(56-58): Complex Types 9777@sp 2 9778@cartouche 9779Because the usual mathematical meaning of multiplication of a complex 9780operand and a real operand is that of the scaling of both components of 9781the former by the latter, an implementation should not perform this 9782operation by first promoting the real operand to complex type and then 9783performing a full complex multiplication. In systems that, in the 9784future, support an Ada binding to IEC 559:1989, the latter technique 9785will not generate the required result when one of the components of the 9786complex operand is infinite. (Explicit multiplication of the infinite 9787component by the zero component obtained during promotion yields a NaN 9788that propagates into the final result.) Analogous advice applies in the 9789case of multiplication of a complex operand and a pure-imaginary 9790operand, and in the case of division of a complex operand by a real or 9791pure-imaginary operand. 9792@end cartouche 9793Not followed. 9794 9795@sp 1 9796@cartouche 9797Similarly, because the usual mathematical meaning of addition of a 9798complex operand and a real operand is that the imaginary operand remains 9799unchanged, an implementation should not perform this operation by first 9800promoting the real operand to complex type and then performing a full 9801complex addition. In implementations in which the @code{Signed_Zeros} 9802attribute of the component type is @code{True} (and which therefore 9803conform to IEC 559:1989 in regard to the handling of the sign of zero in 9804predefined arithmetic operations), the latter technique will not 9805generate the required result when the imaginary component of the complex 9806operand is a negatively signed zero. (Explicit addition of the negative 9807zero to the zero obtained during promotion yields a positive zero.) 9808Analogous advice applies in the case of addition of a complex operand 9809and a pure-imaginary operand, and in the case of subtraction of a 9810complex operand and a real or pure-imaginary operand. 9811@end cartouche 9812Not followed. 9813 9814@sp 1 9815@cartouche 9816Implementations in which @code{Real'Signed_Zeros} is @code{True} should 9817attempt to provide a rational treatment of the signs of zero results and 9818result components. As one example, the result of the @code{Argument} 9819function should have the sign of the imaginary component of the 9820parameter @code{X} when the point represented by that parameter lies on 9821the positive real axis; as another, the sign of the imaginary component 9822of the @code{Compose_From_Polar} function should be the same as 9823(respectively, the opposite of) that of the @code{Argument} parameter when that 9824parameter has a value of zero and the @code{Modulus} parameter has a 9825nonnegative (respectively, negative) value. 9826@end cartouche 9827Followed. 9828 9829@cindex Complex elementary functions 9830@unnumberedsec G.1.2(49): Complex Elementary Functions 9831@sp 1 9832@cartouche 9833Implementations in which @code{Complex_Types.Real'Signed_Zeros} is 9834@code{True} should attempt to provide a rational treatment of the signs 9835of zero results and result components. For example, many of the complex 9836elementary functions have components that are odd functions of one of 9837the parameter components; in these cases, the result component should 9838have the sign of the parameter component at the origin. Other complex 9839elementary functions have zero components whose sign is opposite that of 9840a parameter component at the origin, or is always positive or always 9841negative. 9842@end cartouche 9843Followed. 9844 9845@cindex Accuracy requirements 9846@unnumberedsec G.2.4(19): Accuracy Requirements 9847@sp 1 9848@cartouche 9849The versions of the forward trigonometric functions without a 9850@code{Cycle} parameter should not be implemented by calling the 9851corresponding version with a @code{Cycle} parameter of 9852@code{2.0*Numerics.Pi}, since this will not provide the required 9853accuracy in some portions of the domain. For the same reason, the 9854version of @code{Log} without a @code{Base} parameter should not be 9855implemented by calling the corresponding version with a @code{Base} 9856parameter of @code{Numerics.e}. 9857@end cartouche 9858Followed. 9859 9860@cindex Complex arithmetic accuracy 9861@cindex Accuracy, complex arithmetic 9862@unnumberedsec G.2.6(15): Complex Arithmetic Accuracy 9863 9864@sp 1 9865@cartouche 9866The version of the @code{Compose_From_Polar} function without a 9867@code{Cycle} parameter should not be implemented by calling the 9868corresponding version with a @code{Cycle} parameter of 9869@code{2.0*Numerics.Pi}, since this will not provide the required 9870accuracy in some portions of the domain. 9871@end cartouche 9872Followed. 9873 9874@cindex Sequential elaboration policy 9875@unnumberedsec H.6(15/2): Pragma Partition_Elaboration_Policy 9876 9877@sp 1 9878@cartouche 9879If the partition elaboration policy is @code{Sequential} and the 9880Environment task becomes permanently blocked during elaboration then the 9881partition is deadlocked and it is recommended that the partition be 9882immediately terminated. 9883@end cartouche 9884Not followed. 9885 9886@c ----------------------------------------- 9887@node Implementation Defined Characteristics 9888@chapter Implementation Defined Characteristics 9889 9890@noindent 9891In addition to the implementation dependent pragmas and attributes, and the 9892implementation advice, there are a number of other Ada features that are 9893potentially implementation dependent and are designated as 9894implementation-defined. These are mentioned throughout the Ada Reference 9895Manual, and are summarized in Annex M@. 9896 9897A requirement for conforming Ada compilers is that they provide 9898documentation describing how the implementation deals with each of these 9899issues. In this chapter, you will find each point in Annex M listed 9900followed by a description in italic font of how GNAT 9901handles the implementation dependence. 9902 9903You can use this chapter as a guide to minimizing implementation 9904dependent features in your programs if portability to other compilers 9905and other operating systems is an important consideration. The numbers 9906in each section below correspond to the paragraph number in the Ada 9907Reference Manual. 9908 9909@sp 1 9910@cartouche 9911@noindent 9912@strong{2}. Whether or not each recommendation given in Implementation 9913Advice is followed. See 1.1.2(37). 9914@end cartouche 9915@noindent 9916@xref{Implementation Advice}. 9917 9918@sp 1 9919@cartouche 9920@noindent 9921@strong{3}. Capacity limitations of the implementation. See 1.1.3(3). 9922@end cartouche 9923@noindent 9924The complexity of programs that can be processed is limited only by the 9925total amount of available virtual memory, and disk space for the 9926generated object files. 9927 9928@sp 1 9929@cartouche 9930@noindent 9931@strong{4}. Variations from the standard that are impractical to avoid 9932given the implementation's execution environment. See 1.1.3(6). 9933@end cartouche 9934@noindent 9935There are no variations from the standard. 9936 9937@sp 1 9938@cartouche 9939@noindent 9940@strong{5}. Which @code{code_statement}s cause external 9941interactions. See 1.1.3(10). 9942@end cartouche 9943@noindent 9944Any @code{code_statement} can potentially cause external interactions. 9945 9946@sp 1 9947@cartouche 9948@noindent 9949@strong{6}. The coded representation for the text of an Ada 9950program. See 2.1(4). 9951@end cartouche 9952@noindent 9953See separate section on source representation. 9954 9955@sp 1 9956@cartouche 9957@noindent 9958@strong{7}. The control functions allowed in comments. See 2.1(14). 9959@end cartouche 9960@noindent 9961See separate section on source representation. 9962 9963@sp 1 9964@cartouche 9965@noindent 9966@strong{8}. The representation for an end of line. See 2.2(2). 9967@end cartouche 9968@noindent 9969See separate section on source representation. 9970 9971@sp 1 9972@cartouche 9973@noindent 9974@strong{9}. Maximum supported line length and lexical element 9975length. See 2.2(15). 9976@end cartouche 9977@noindent 9978The maximum line length is 255 characters and the maximum length of 9979a lexical element is also 255 characters. This is the default setting 9980if not overridden by the use of compiler switch @option{-gnaty} (which 9981sets the maximum to 79) or @option{-gnatyMnn} which allows the maximum 9982line length to be specified to be any value up to 32767. The maximum 9983length of a lexical element is the same as the maximum line length. 9984 9985@sp 1 9986@cartouche 9987@noindent 9988@strong{10}. Implementation defined pragmas. See 2.8(14). 9989@end cartouche 9990@noindent 9991 9992@xref{Implementation Defined Pragmas}. 9993 9994@sp 1 9995@cartouche 9996@noindent 9997@strong{11}. Effect of pragma @code{Optimize}. See 2.8(27). 9998@end cartouche 9999@noindent 10000Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} 10001parameter, checks that the optimization flag is set, and aborts if it is 10002not. 10003 10004@sp 1 10005@cartouche 10006@noindent 10007@strong{12}. The sequence of characters of the value returned by 10008@code{@var{S}'Image} when some of the graphic characters of 10009@code{@var{S}'Wide_Image} are not defined in @code{Character}. See 100103.5(37). 10011@end cartouche 10012@noindent 10013The sequence of characters is as defined by the wide character encoding 10014method used for the source. See section on source representation for 10015further details. 10016 10017@sp 1 10018@cartouche 10019@noindent 10020@strong{13}. The predefined integer types declared in 10021@code{Standard}. See 3.5.4(25). 10022@end cartouche 10023@noindent 10024@table @code 10025@item Short_Short_Integer 100268 bit signed 10027@item Short_Integer 10028(Short) 16 bit signed 10029@item Integer 1003032 bit signed 10031@item Long_Integer 1003264 bit signed (on most 64 bit targets, depending on the C definition of long). 1003332 bit signed (all other targets) 10034@item Long_Long_Integer 1003564 bit signed 10036@end table 10037 10038@sp 1 10039@cartouche 10040@noindent 10041@strong{14}. Any nonstandard integer types and the operators defined 10042for them. See 3.5.4(26). 10043@end cartouche 10044@noindent 10045There are no nonstandard integer types. 10046 10047@sp 1 10048@cartouche 10049@noindent 10050@strong{15}. Any nonstandard real types and the operators defined for 10051them. See 3.5.6(8). 10052@end cartouche 10053@noindent 10054There are no nonstandard real types. 10055 10056@sp 1 10057@cartouche 10058@noindent 10059@strong{16}. What combinations of requested decimal precision and range 10060are supported for floating point types. See 3.5.7(7). 10061@end cartouche 10062@noindent 10063The precision and range is as defined by the IEEE standard. 10064 10065@sp 1 10066@cartouche 10067@noindent 10068@strong{17}. The predefined floating point types declared in 10069@code{Standard}. See 3.5.7(16). 10070@end cartouche 10071@noindent 10072@table @code 10073@item Short_Float 1007432 bit IEEE short 10075@item Float 10076(Short) 32 bit IEEE short 10077@item Long_Float 1007864 bit IEEE long 10079@item Long_Long_Float 1008064 bit IEEE long (80 bit IEEE long on x86 processors) 10081@end table 10082 10083@sp 1 10084@cartouche 10085@noindent 10086@strong{18}. The small of an ordinary fixed point type. See 3.5.9(8). 10087@end cartouche 10088@noindent 10089@code{Fine_Delta} is 2**(@minus{}63) 10090 10091@sp 1 10092@cartouche 10093@noindent 10094@strong{19}. What combinations of small, range, and digits are 10095supported for fixed point types. See 3.5.9(10). 10096@end cartouche 10097@noindent 10098Any combinations are permitted that do not result in a small less than 10099@code{Fine_Delta} and do not result in a mantissa larger than 63 bits. 10100If the mantissa is larger than 53 bits on machines where Long_Long_Float 10101is 64 bits (true of all architectures except ia32), then the output from 10102Text_IO is accurate to only 53 bits, rather than the full mantissa. This 10103is because floating-point conversions are used to convert fixed point. 10104 10105@sp 1 10106@cartouche 10107@noindent 10108@strong{20}. The result of @code{Tags.Expanded_Name} for types declared 10109within an unnamed @code{block_statement}. See 3.9(10). 10110@end cartouche 10111@noindent 10112Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a 10113decimal integer are allocated. 10114 10115@sp 1 10116@cartouche 10117@noindent 10118@strong{21}. Implementation-defined attributes. See 4.1.4(12). 10119@end cartouche 10120@noindent 10121@xref{Implementation Defined Attributes}. 10122 10123@sp 1 10124@cartouche 10125@noindent 10126@strong{22}. Any implementation-defined time types. See 9.6(6). 10127@end cartouche 10128@noindent 10129There are no implementation-defined time types. 10130 10131@sp 1 10132@cartouche 10133@noindent 10134@strong{23}. The time base associated with relative delays. 10135@end cartouche 10136@noindent 10137See 9.6(20). The time base used is that provided by the C library 10138function @code{gettimeofday}. 10139 10140@sp 1 10141@cartouche 10142@noindent 10143@strong{24}. The time base of the type @code{Calendar.Time}. See 101449.6(23). 10145@end cartouche 10146@noindent 10147The time base used is that provided by the C library function 10148@code{gettimeofday}. 10149 10150@sp 1 10151@cartouche 10152@noindent 10153@strong{25}. The time zone used for package @code{Calendar} 10154operations. See 9.6(24). 10155@end cartouche 10156@noindent 10157The time zone used by package @code{Calendar} is the current system time zone 10158setting for local time, as accessed by the C library function 10159@code{localtime}. 10160 10161@sp 1 10162@cartouche 10163@noindent 10164@strong{26}. Any limit on @code{delay_until_statements} of 10165@code{select_statements}. See 9.6(29). 10166@end cartouche 10167@noindent 10168There are no such limits. 10169 10170@sp 1 10171@cartouche 10172@noindent 10173@strong{27}. Whether or not two non-overlapping parts of a composite 10174object are independently addressable, in the case where packing, record 10175layout, or @code{Component_Size} is specified for the object. See 101769.10(1). 10177@end cartouche 10178@noindent 10179Separate components are independently addressable if they do not share 10180overlapping storage units. 10181 10182@sp 1 10183@cartouche 10184@noindent 10185@strong{28}. The representation for a compilation. See 10.1(2). 10186@end cartouche 10187@noindent 10188A compilation is represented by a sequence of files presented to the 10189compiler in a single invocation of the @command{gcc} command. 10190 10191@sp 1 10192@cartouche 10193@noindent 10194@strong{29}. Any restrictions on compilations that contain multiple 10195compilation_units. See 10.1(4). 10196@end cartouche 10197@noindent 10198No single file can contain more than one compilation unit, but any 10199sequence of files can be presented to the compiler as a single 10200compilation. 10201 10202@sp 1 10203@cartouche 10204@noindent 10205@strong{30}. The mechanisms for creating an environment and for adding 10206and replacing compilation units. See 10.1.4(3). 10207@end cartouche 10208@noindent 10209See separate section on compilation model. 10210 10211@sp 1 10212@cartouche 10213@noindent 10214@strong{31}. The manner of explicitly assigning library units to a 10215partition. See 10.2(2). 10216@end cartouche 10217@noindent 10218If a unit contains an Ada main program, then the Ada units for the partition 10219are determined by recursive application of the rules in the Ada Reference 10220Manual section 10.2(2-6). In other words, the Ada units will be those that 10221are needed by the main program, and then this definition of need is applied 10222recursively to those units, and the partition contains the transitive 10223closure determined by this relationship. In short, all the necessary units 10224are included, with no need to explicitly specify the list. If additional 10225units are required, e.g.@: by foreign language units, then all units must be 10226mentioned in the context clause of one of the needed Ada units. 10227 10228If the partition contains no main program, or if the main program is in 10229a language other than Ada, then GNAT 10230provides the binder options @option{-z} and @option{-n} respectively, and in 10231this case a list of units can be explicitly supplied to the binder for 10232inclusion in the partition (all units needed by these units will also 10233be included automatically). For full details on the use of these 10234options, refer to @ref{The GNAT Make Program gnatmake,,, gnat_ugn, 10235@value{EDITION} User's Guide}. 10236 10237@sp 1 10238@cartouche 10239@noindent 10240@strong{32}. The implementation-defined means, if any, of specifying 10241which compilation units are needed by a given compilation unit. See 1024210.2(2). 10243@end cartouche 10244@noindent 10245The units needed by a given compilation unit are as defined in 10246the Ada Reference Manual section 10.2(2-6). There are no 10247implementation-defined pragmas or other implementation-defined 10248means for specifying needed units. 10249 10250@sp 1 10251@cartouche 10252@noindent 10253@strong{33}. The manner of designating the main subprogram of a 10254partition. See 10.2(7). 10255@end cartouche 10256@noindent 10257The main program is designated by providing the name of the 10258corresponding @file{ALI} file as the input parameter to the binder. 10259 10260@sp 1 10261@cartouche 10262@noindent 10263@strong{34}. The order of elaboration of @code{library_items}. See 1026410.2(18). 10265@end cartouche 10266@noindent 10267The first constraint on ordering is that it meets the requirements of 10268Chapter 10 of the Ada Reference Manual. This still leaves some 10269implementation dependent choices, which are resolved by first 10270elaborating bodies as early as possible (i.e., in preference to specs 10271where there is a choice), and second by evaluating the immediate with 10272clauses of a unit to determine the probably best choice, and 10273third by elaborating in alphabetical order of unit names 10274where a choice still remains. 10275 10276@sp 1 10277@cartouche 10278@noindent 10279@strong{35}. Parameter passing and function return for the main 10280subprogram. See 10.2(21). 10281@end cartouche 10282@noindent 10283The main program has no parameters. It may be a procedure, or a function 10284returning an integer type. In the latter case, the returned integer 10285value is the return code of the program (overriding any value that 10286may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). 10287 10288@sp 1 10289@cartouche 10290@noindent 10291@strong{36}. The mechanisms for building and running partitions. See 1029210.2(24). 10293@end cartouche 10294@noindent 10295GNAT itself supports programs with only a single partition. The GNATDIST 10296tool provided with the GLADE package (which also includes an implementation 10297of the PCS) provides a completely flexible method for building and running 10298programs consisting of multiple partitions. See the separate GLADE manual 10299for details. 10300 10301@sp 1 10302@cartouche 10303@noindent 10304@strong{37}. The details of program execution, including program 10305termination. See 10.2(25). 10306@end cartouche 10307@noindent 10308See separate section on compilation model. 10309 10310@sp 1 10311@cartouche 10312@noindent 10313@strong{38}. The semantics of any non-active partitions supported by the 10314implementation. See 10.2(28). 10315@end cartouche 10316@noindent 10317Passive partitions are supported on targets where shared memory is 10318provided by the operating system. See the GLADE reference manual for 10319further details. 10320 10321@sp 1 10322@cartouche 10323@noindent 10324@strong{39}. The information returned by @code{Exception_Message}. See 1032511.4.1(10). 10326@end cartouche 10327@noindent 10328Exception message returns the null string unless a specific message has 10329been passed by the program. 10330 10331@sp 1 10332@cartouche 10333@noindent 10334@strong{40}. The result of @code{Exceptions.Exception_Name} for types 10335declared within an unnamed @code{block_statement}. See 11.4.1(12). 10336@end cartouche 10337@noindent 10338Blocks have implementation defined names of the form @code{B@var{nnn}} 10339where @var{nnn} is an integer. 10340 10341@sp 1 10342@cartouche 10343@noindent 10344@strong{41}. The information returned by 10345@code{Exception_Information}. See 11.4.1(13). 10346@end cartouche 10347@noindent 10348@code{Exception_Information} returns a string in the following format: 10349 10350@smallexample 10351@emph{Exception_Name:} nnnnn 10352@emph{Message:} mmmmm 10353@emph{PID:} ppp 10354@emph{Call stack traceback locations:} 103550xhhhh 0xhhhh 0xhhhh ... 0xhhh 10356@end smallexample 10357 10358@noindent 10359where 10360 10361@itemize @bullet 10362@item 10363@code{nnnn} is the fully qualified name of the exception in all upper 10364case letters. This line is always present. 10365 10366@item 10367@code{mmmm} is the message (this line present only if message is non-null) 10368 10369@item 10370@code{ppp} is the Process Id value as a decimal integer (this line is 10371present only if the Process Id is nonzero). Currently we are 10372not making use of this field. 10373 10374@item 10375The Call stack traceback locations line and the following values 10376are present only if at least one traceback location was recorded. 10377The values are given in C style format, with lower case letters 10378for a-f, and only as many digits present as are necessary. 10379@end itemize 10380 10381@noindent 10382The line terminator sequence at the end of each line, including 10383the last line is a single @code{LF} character (@code{16#0A#}). 10384 10385@sp 1 10386@cartouche 10387@noindent 10388@strong{42}. Implementation-defined check names. See 11.5(27). 10389@end cartouche 10390@noindent 10391The implementation defined check name Alignment_Check controls checking of 10392address clause values for proper alignment (that is, the address supplied 10393must be consistent with the alignment of the type). 10394 10395In addition, a user program can add implementation-defined check names 10396by means of the pragma Check_Name. 10397 10398@sp 1 10399@cartouche 10400@noindent 10401@strong{43}. The interpretation of each aspect of representation. See 1040213.1(20). 10403@end cartouche 10404@noindent 10405See separate section on data representations. 10406 10407@sp 1 10408@cartouche 10409@noindent 10410@strong{44}. Any restrictions placed upon representation items. See 1041113.1(20). 10412@end cartouche 10413@noindent 10414See separate section on data representations. 10415 10416@sp 1 10417@cartouche 10418@noindent 10419@strong{45}. The meaning of @code{Size} for indefinite subtypes. See 1042013.3(48). 10421@end cartouche 10422@noindent 10423Size for an indefinite subtype is the maximum possible size, except that 10424for the case of a subprogram parameter, the size of the parameter object 10425is the actual size. 10426 10427@sp 1 10428@cartouche 10429@noindent 10430@strong{46}. The default external representation for a type tag. See 1043113.3(75). 10432@end cartouche 10433@noindent 10434The default external representation for a type tag is the fully expanded 10435name of the type in upper case letters. 10436 10437@sp 1 10438@cartouche 10439@noindent 10440@strong{47}. What determines whether a compilation unit is the same in 10441two different partitions. See 13.3(76). 10442@end cartouche 10443@noindent 10444A compilation unit is the same in two different partitions if and only 10445if it derives from the same source file. 10446 10447@sp 1 10448@cartouche 10449@noindent 10450@strong{48}. Implementation-defined components. See 13.5.1(15). 10451@end cartouche 10452@noindent 10453The only implementation defined component is the tag for a tagged type, 10454which contains a pointer to the dispatching table. 10455 10456@sp 1 10457@cartouche 10458@noindent 10459@strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit 10460ordering. See 13.5.3(5). 10461@end cartouche 10462@noindent 10463@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this 10464implementation, so no non-default bit ordering is supported. The default 10465bit ordering corresponds to the natural endianness of the target architecture. 10466 10467@sp 1 10468@cartouche 10469@noindent 10470@strong{50}. The contents of the visible part of package @code{System} 10471and its language-defined children. See 13.7(2). 10472@end cartouche 10473@noindent 10474See the definition of these packages in files @file{system.ads} and 10475@file{s-stoele.ads}. 10476 10477@sp 1 10478@cartouche 10479@noindent 10480@strong{51}. The contents of the visible part of package 10481@code{System.Machine_Code}, and the meaning of 10482@code{code_statements}. See 13.8(7). 10483@end cartouche 10484@noindent 10485See the definition and documentation in file @file{s-maccod.ads}. 10486 10487@sp 1 10488@cartouche 10489@noindent 10490@strong{52}. The effect of unchecked conversion. See 13.9(11). 10491@end cartouche 10492@noindent 10493Unchecked conversion between types of the same size 10494results in an uninterpreted transmission of the bits from one type 10495to the other. If the types are of unequal sizes, then in the case of 10496discrete types, a shorter source is first zero or sign extended as 10497necessary, and a shorter target is simply truncated on the left. 10498For all non-discrete types, the source is first copied if necessary 10499to ensure that the alignment requirements of the target are met, then 10500a pointer is constructed to the source value, and the result is obtained 10501by dereferencing this pointer after converting it to be a pointer to the 10502target type. Unchecked conversions where the target subtype is an 10503unconstrained array are not permitted. If the target alignment is 10504greater than the source alignment, then a copy of the result is 10505made with appropriate alignment 10506 10507@sp 1 10508@cartouche 10509@noindent 10510@strong{53}. The semantics of operations on invalid representations. 10511See 13.9.2(10-11). 10512@end cartouche 10513@noindent 10514For assignments and other operations where the use of invalid values cannot 10515result in erroneous behavior, the compiler ignores the possibility of invalid 10516values. An exception is raised at the point where an invalid value would 10517result in erroneous behavior. For example executing: 10518 10519@smallexample @c ada 10520procedure invalidvals is 10521 X : Integer := -1; 10522 Y : Natural range 1 .. 10; 10523 for Y'Address use X'Address; 10524 Z : Natural range 1 .. 10; 10525 A : array (Natural range 1 .. 10) of Integer; 10526begin 10527 Z := Y; -- no exception 10528 A (Z) := 3; -- exception raised; 10529end; 10530@end smallexample 10531 10532@noindent 10533As indicated, an exception is raised on the array assignment, but not 10534on the simple assignment of the invalid negative value from Y to Z. 10535 10536@sp 1 10537@cartouche 10538@noindent 10539@strong{53}. The manner of choosing a storage pool for an access type 10540when @code{Storage_Pool} is not specified for the type. See 13.11(17). 10541@end cartouche 10542@noindent 10543There are 3 different standard pools used by the compiler when 10544@code{Storage_Pool} is not specified depending whether the type is local 10545to a subprogram or defined at the library level and whether 10546@code{Storage_Size}is specified or not. See documentation in the runtime 10547library units @code{System.Pool_Global}, @code{System.Pool_Size} and 10548@code{System.Pool_Local} in files @file{s-poosiz.ads}, 10549@file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the 10550default pools used. 10551 10552@sp 1 10553@cartouche 10554@noindent 10555@strong{54}. Whether or not the implementation provides user-accessible 10556names for the standard pool type(s). See 13.11(17). 10557@end cartouche 10558@noindent 10559 10560See documentation in the sources of the run time mentioned in paragraph 10561@strong{53} . All these pools are accessible by means of @code{with}'ing 10562these units. 10563 10564@sp 1 10565@cartouche 10566@noindent 10567@strong{55}. The meaning of @code{Storage_Size}. See 13.11(18). 10568@end cartouche 10569@noindent 10570@code{Storage_Size} is measured in storage units, and refers to the 10571total space available for an access type collection, or to the primary 10572stack space for a task. 10573 10574@sp 1 10575@cartouche 10576@noindent 10577@strong{56}. Implementation-defined aspects of storage pools. See 1057813.11(22). 10579@end cartouche 10580@noindent 10581See documentation in the sources of the run time mentioned in paragraph 10582@strong{53} for details on GNAT-defined aspects of storage pools. 10583 10584@sp 1 10585@cartouche 10586@noindent 10587@strong{57}. The set of restrictions allowed in a pragma 10588@code{Restrictions}. See 13.12(7). 10589@end cartouche 10590@noindent 10591@xref{Standard and Implementation Defined Restrictions}. 10592 10593@sp 1 10594@cartouche 10595@noindent 10596@strong{58}. The consequences of violating limitations on 10597@code{Restrictions} pragmas. See 13.12(9). 10598@end cartouche 10599@noindent 10600Restrictions that can be checked at compile time result in illegalities 10601if violated. Currently there are no other consequences of violating 10602restrictions. 10603 10604@sp 1 10605@cartouche 10606@noindent 10607@strong{59}. The representation used by the @code{Read} and 10608@code{Write} attributes of elementary types in terms of stream 10609elements. See 13.13.2(9). 10610@end cartouche 10611@noindent 10612The representation is the in-memory representation of the base type of 10613the type, using the number of bits corresponding to the 10614@code{@var{type}'Size} value, and the natural ordering of the machine. 10615 10616@sp 1 10617@cartouche 10618@noindent 10619@strong{60}. The names and characteristics of the numeric subtypes 10620declared in the visible part of package @code{Standard}. See A.1(3). 10621@end cartouche 10622@noindent 10623See items describing the integer and floating-point types supported. 10624 10625@sp 1 10626@cartouche 10627@noindent 10628@strong{61}. The accuracy actually achieved by the elementary 10629functions. See A.5.1(1). 10630@end cartouche 10631@noindent 10632The elementary functions correspond to the functions available in the C 10633library. Only fast math mode is implemented. 10634 10635@sp 1 10636@cartouche 10637@noindent 10638@strong{62}. The sign of a zero result from some of the operators or 10639functions in @code{Numerics.Generic_Elementary_Functions}, when 10640@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46). 10641@end cartouche 10642@noindent 10643The sign of zeroes follows the requirements of the IEEE 754 standard on 10644floating-point. 10645 10646@sp 1 10647@cartouche 10648@noindent 10649@strong{63}. The value of 10650@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27). 10651@end cartouche 10652@noindent 10653Maximum image width is 6864, see library file @file{s-rannum.ads}. 10654 10655@sp 1 10656@cartouche 10657@noindent 10658@strong{64}. The value of 10659@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27). 10660@end cartouche 10661@noindent 10662Maximum image width is 6864, see library file @file{s-rannum.ads}. 10663 10664@sp 1 10665@cartouche 10666@noindent 10667@strong{65}. The algorithms for random number generation. See 10668A.5.2(32). 10669@end cartouche 10670@noindent 10671The algorithm is the Mersenne Twister, as documented in the source file 10672@file{s-rannum.adb}. This version of the algorithm has a period of 106732**19937-1. 10674 10675@sp 1 10676@cartouche 10677@noindent 10678@strong{66}. The string representation of a random number generator's 10679state. See A.5.2(38). 10680@end cartouche 10681@noindent 10682The value returned by the Image function is the concatenation of 10683the fixed-width decimal representations of the 624 32-bit integers 10684of the state vector. 10685 10686@sp 1 10687@cartouche 10688@noindent 10689@strong{67}. The minimum time interval between calls to the 10690time-dependent Reset procedure that are guaranteed to initiate different 10691random number sequences. See A.5.2(45). 10692@end cartouche 10693@noindent 10694The minimum period between reset calls to guarantee distinct series of 10695random numbers is one microsecond. 10696 10697@sp 1 10698@cartouche 10699@noindent 10700@strong{68}. The values of the @code{Model_Mantissa}, 10701@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, 10702@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics 10703Annex is not supported. See A.5.3(72). 10704@end cartouche 10705@noindent 10706Run the compiler with @option{-gnatS} to produce a listing of package 10707@code{Standard}, has the values of all numeric attributes. 10708 10709@sp 1 10710@cartouche 10711@noindent 10712@strong{69}. Any implementation-defined characteristics of the 10713input-output packages. See A.7(14). 10714@end cartouche 10715@noindent 10716There are no special implementation defined characteristics for these 10717packages. 10718 10719@sp 1 10720@cartouche 10721@noindent 10722@strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See 10723A.9(10). 10724@end cartouche 10725@noindent 10726All type representations are contiguous, and the @code{Buffer_Size} is 10727the value of @code{@var{type}'Size} rounded up to the next storage unit 10728boundary. 10729 10730@sp 1 10731@cartouche 10732@noindent 10733@strong{71}. External files for standard input, standard output, and 10734standard error See A.10(5). 10735@end cartouche 10736@noindent 10737These files are mapped onto the files provided by the C streams 10738libraries. See source file @file{i-cstrea.ads} for further details. 10739 10740@sp 1 10741@cartouche 10742@noindent 10743@strong{72}. The accuracy of the value produced by @code{Put}. See 10744A.10.9(36). 10745@end cartouche 10746@noindent 10747If more digits are requested in the output than are represented by the 10748precision of the value, zeroes are output in the corresponding least 10749significant digit positions. 10750 10751@sp 1 10752@cartouche 10753@noindent 10754@strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and 10755@code{Command_Name}. See A.15(1). 10756@end cartouche 10757@noindent 10758These are mapped onto the @code{argv} and @code{argc} parameters of the 10759main program in the natural manner. 10760 10761@sp 1 10762@cartouche 10763@noindent 10764@strong{74}. The interpretation of the @code{Form} parameter in procedure 10765@code{Create_Directory}. See A.16(56). 10766@end cartouche 10767@noindent 10768The @code{Form} parameter is not used. 10769 10770@sp 1 10771@cartouche 10772@noindent 10773@strong{75}. The interpretation of the @code{Form} parameter in procedure 10774@code{Create_Path}. See A.16(60). 10775@end cartouche 10776@noindent 10777The @code{Form} parameter is not used. 10778 10779@sp 1 10780@cartouche 10781@noindent 10782@strong{76}. The interpretation of the @code{Form} parameter in procedure 10783@code{Copy_File}. See A.16(68). 10784@end cartouche 10785@noindent 10786The @code{Form} parameter is case-insensitive. 10787 10788Two fields are recognized in the @code{Form} parameter: 10789 10790@table @code 10791 10792@item preserve=<value> 10793 10794@item mode=<value> 10795 10796@end table 10797 10798@noindent 10799<value> starts immediately after the character '=' and ends with the 10800character immediately preceding the next comma (',') or with the last 10801character of the parameter. 10802 10803The only possible values for preserve= are: 10804 10805@table @code 10806 10807@item no_attributes 10808Do not try to preserve any file attributes. This is the default if no 10809preserve= is found in Form. 10810 10811@item all_attributes 10812Try to preserve all file attributes (timestamps, access rights). 10813 10814@item timestamps 10815Preserve the timestamp of the copied file, but not the other file attributes. 10816 10817@end table 10818 10819@noindent 10820The only possible values for mode= are: 10821 10822@table @code 10823 10824@item copy 10825Only do the copy if the destination file does not already exist. If it already 10826exists, Copy_File fails. 10827 10828@item overwrite 10829Copy the file in all cases. Overwrite an already existing destination file. 10830 10831@item append 10832Append the original file to the destination file. If the destination file does 10833not exist, the destination file is a copy of the source file. When mode=append, 10834the field preserve=, if it exists, is not taken into account. 10835 10836@end table 10837 10838@noindent 10839If the Form parameter includes one or both of the fields and the value or 10840values are incorrect, Copy_file fails with Use_Error. 10841 10842Examples of correct Forms: 10843 10844@smallexample 10845Form => "preserve=no_attributes,mode=overwrite" (the default) 10846Form => "mode=append" 10847Form => "mode=copy, preserve=all_attributes" 10848@end smallexample 10849 10850@noindent 10851Examples of incorrect Forms 10852 10853@smallexample 10854Form => "preserve=junk" 10855Form => "mode=internal, preserve=timestamps" 10856@end smallexample 10857 10858@sp 1 10859@cartouche 10860@noindent 10861@strong{77}. Implementation-defined convention names. See B.1(11). 10862@end cartouche 10863@noindent 10864The following convention names are supported 10865 10866@table @code 10867@item Ada 10868Ada 10869@item Ada_Pass_By_Copy 10870Allowed for any types except by-reference types such as limited 10871records. Compatible with convention Ada, but causes any parameters 10872with this convention to be passed by copy. 10873@item Ada_Pass_By_Reference 10874Allowed for any types except by-copy types such as scalars. 10875Compatible with convention Ada, but causes any parameters 10876with this convention to be passed by reference. 10877@item Assembler 10878Assembly language 10879@item Asm 10880Synonym for Assembler 10881@item Assembly 10882Synonym for Assembler 10883@item C 10884C 10885@item C_Pass_By_Copy 10886Allowed only for record types, like C, but also notes that record 10887is to be passed by copy rather than reference. 10888@item COBOL 10889COBOL 10890@item C_Plus_Plus (or CPP) 10891C++ 10892@item Default 10893Treated the same as C 10894@item External 10895Treated the same as C 10896@item Fortran 10897Fortran 10898@item Intrinsic 10899For support of pragma @code{Import} with convention Intrinsic, see 10900separate section on Intrinsic Subprograms. 10901@item Stdcall 10902Stdcall (used for Windows implementations only). This convention correspond 10903to the WINAPI (previously called Pascal convention) C/C++ convention under 10904Windows. A routine with this convention cleans the stack before 10905exit. This pragma cannot be applied to a dispatching call. 10906@item DLL 10907Synonym for Stdcall 10908@item Win32 10909Synonym for Stdcall 10910@item Stubbed 10911Stubbed is a special convention used to indicate that the body of the 10912subprogram will be entirely ignored. Any call to the subprogram 10913is converted into a raise of the @code{Program_Error} exception. If a 10914pragma @code{Import} specifies convention @code{stubbed} then no body need 10915be present at all. This convention is useful during development for the 10916inclusion of subprograms whose body has not yet been written. 10917 10918@end table 10919@noindent 10920In addition, all otherwise unrecognized convention names are also 10921treated as being synonymous with convention C@. In all implementations 10922except for VMS, use of such other names results in a warning. In VMS 10923implementations, these names are accepted silently. 10924 10925@sp 1 10926@cartouche 10927@noindent 10928@strong{78}. The meaning of link names. See B.1(36). 10929@end cartouche 10930@noindent 10931Link names are the actual names used by the linker. 10932 10933@sp 1 10934@cartouche 10935@noindent 10936@strong{79}. The manner of choosing link names when neither the link 10937name nor the address of an imported or exported entity is specified. See 10938B.1(36). 10939@end cartouche 10940@noindent 10941The default linker name is that which would be assigned by the relevant 10942external language, interpreting the Ada name as being in all lower case 10943letters. 10944 10945@sp 1 10946@cartouche 10947@noindent 10948@strong{80}. The effect of pragma @code{Linker_Options}. See B.1(37). 10949@end cartouche 10950@noindent 10951The string passed to @code{Linker_Options} is presented uninterpreted as 10952an argument to the link command, unless it contains ASCII.NUL characters. 10953NUL characters if they appear act as argument separators, so for example 10954 10955@smallexample @c ada 10956pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); 10957@end smallexample 10958 10959@noindent 10960causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the 10961linker. The order of linker options is preserved for a given unit. The final 10962list of options passed to the linker is in reverse order of the elaboration 10963order. For example, linker options for a body always appear before the options 10964from the corresponding package spec. 10965 10966@sp 1 10967@cartouche 10968@noindent 10969@strong{81}. The contents of the visible part of package 10970@code{Interfaces} and its language-defined descendants. See B.2(1). 10971@end cartouche 10972@noindent 10973See files with prefix @file{i-} in the distributed library. 10974 10975@sp 1 10976@cartouche 10977@noindent 10978@strong{82}. Implementation-defined children of package 10979@code{Interfaces}. The contents of the visible part of package 10980@code{Interfaces}. See B.2(11). 10981@end cartouche 10982@noindent 10983See files with prefix @file{i-} in the distributed library. 10984 10985@sp 1 10986@cartouche 10987@noindent 10988@strong{83}. The types @code{Floating}, @code{Long_Floating}, 10989@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and 10990@code{COBOL_Character}; and the initialization of the variables 10991@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in 10992@code{Interfaces.COBOL}. See B.4(50). 10993@end cartouche 10994@noindent 10995@table @code 10996@item Floating 10997Float 10998@item Long_Floating 10999(Floating) Long_Float 11000@item Binary 11001Integer 11002@item Long_Binary 11003Long_Long_Integer 11004@item Decimal_Element 11005Character 11006@item COBOL_Character 11007Character 11008@end table 11009 11010@noindent 11011For initialization, see the file @file{i-cobol.ads} in the distributed library. 11012 11013@sp 1 11014@cartouche 11015@noindent 11016@strong{84}. Support for access to machine instructions. See C.1(1). 11017@end cartouche 11018@noindent 11019See documentation in file @file{s-maccod.ads} in the distributed library. 11020 11021@sp 1 11022@cartouche 11023@noindent 11024@strong{85}. Implementation-defined aspects of access to machine 11025operations. See C.1(9). 11026@end cartouche 11027@noindent 11028See documentation in file @file{s-maccod.ads} in the distributed library. 11029 11030@sp 1 11031@cartouche 11032@noindent 11033@strong{86}. Implementation-defined aspects of interrupts. See C.3(2). 11034@end cartouche 11035@noindent 11036Interrupts are mapped to signals or conditions as appropriate. See 11037definition of unit 11038@code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details 11039on the interrupts supported on a particular target. 11040 11041@sp 1 11042@cartouche 11043@noindent 11044@strong{87}. Implementation-defined aspects of pre-elaboration. See 11045C.4(13). 11046@end cartouche 11047@noindent 11048GNAT does not permit a partition to be restarted without reloading, 11049except under control of the debugger. 11050 11051@sp 1 11052@cartouche 11053@noindent 11054@strong{88}. The semantics of pragma @code{Discard_Names}. See C.5(7). 11055@end cartouche 11056@noindent 11057Pragma @code{Discard_Names} causes names of enumeration literals to 11058be suppressed. In the presence of this pragma, the Image attribute 11059provides the image of the Pos of the literal, and Value accepts 11060Pos values. 11061 11062@sp 1 11063@cartouche 11064@noindent 11065@strong{89}. The result of the @code{Task_Identification.Image} 11066attribute. See C.7.1(7). 11067@end cartouche 11068@noindent 11069The result of this attribute is a string that identifies 11070the object or component that denotes a given task. If a variable @code{Var} 11071has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}}, 11072where the suffix 11073is the hexadecimal representation of the virtual address of the corresponding 11074task control block. If the variable is an array of tasks, the image of each 11075task will have the form of an indexed component indicating the position of a 11076given task in the array, e.g.@: @code{Group(5)_@var{XXXXXXX}}. If the task is a 11077component of a record, the image of the task will have the form of a selected 11078component. These rules are fully recursive, so that the image of a task that 11079is a subcomponent of a composite object corresponds to the expression that 11080designates this task. 11081@noindent 11082If a task is created by an allocator, its image depends on the context. If the 11083allocator is part of an object declaration, the rules described above are used 11084to construct its image, and this image is not affected by subsequent 11085assignments. If the allocator appears within an expression, the image 11086includes only the name of the task type. 11087@noindent 11088If the configuration pragma Discard_Names is present, or if the restriction 11089No_Implicit_Heap_Allocation is in effect, the image reduces to 11090the numeric suffix, that is to say the hexadecimal representation of the 11091virtual address of the control block of the task. 11092@sp 1 11093@cartouche 11094@noindent 11095@strong{90}. The value of @code{Current_Task} when in a protected entry 11096or interrupt handler. See C.7.1(17). 11097@end cartouche 11098@noindent 11099Protected entries or interrupt handlers can be executed by any 11100convenient thread, so the value of @code{Current_Task} is undefined. 11101 11102@sp 1 11103@cartouche 11104@noindent 11105@strong{91}. The effect of calling @code{Current_Task} from an entry 11106body or interrupt handler. See C.7.1(19). 11107@end cartouche 11108@noindent 11109The effect of calling @code{Current_Task} from an entry body or 11110interrupt handler is to return the identification of the task currently 11111executing the code. 11112 11113@sp 1 11114@cartouche 11115@noindent 11116@strong{92}. Implementation-defined aspects of 11117@code{Task_Attributes}. See C.7.2(19). 11118@end cartouche 11119@noindent 11120There are no implementation-defined aspects of @code{Task_Attributes}. 11121 11122@sp 1 11123@cartouche 11124@noindent 11125@strong{93}. Values of all @code{Metrics}. See D(2). 11126@end cartouche 11127@noindent 11128The metrics information for GNAT depends on the performance of the 11129underlying operating system. The sources of the run-time for tasking 11130implementation, together with the output from @option{-gnatG} can be 11131used to determine the exact sequence of operating systems calls made 11132to implement various tasking constructs. Together with appropriate 11133information on the performance of the underlying operating system, 11134on the exact target in use, this information can be used to determine 11135the required metrics. 11136 11137@sp 1 11138@cartouche 11139@noindent 11140@strong{94}. The declarations of @code{Any_Priority} and 11141@code{Priority}. See D.1(11). 11142@end cartouche 11143@noindent 11144See declarations in file @file{system.ads}. 11145 11146@sp 1 11147@cartouche 11148@noindent 11149@strong{95}. Implementation-defined execution resources. See D.1(15). 11150@end cartouche 11151@noindent 11152There are no implementation-defined execution resources. 11153 11154@sp 1 11155@cartouche 11156@noindent 11157@strong{96}. Whether, on a multiprocessor, a task that is waiting for 11158access to a protected object keeps its processor busy. See D.2.1(3). 11159@end cartouche 11160@noindent 11161On a multi-processor, a task that is waiting for access to a protected 11162object does not keep its processor busy. 11163 11164@sp 1 11165@cartouche 11166@noindent 11167@strong{97}. The affect of implementation defined execution resources 11168on task dispatching. See D.2.1(9). 11169@end cartouche 11170@noindent 11171Tasks map to threads in the threads package used by GNAT@. Where possible 11172and appropriate, these threads correspond to native threads of the 11173underlying operating system. 11174 11175@sp 1 11176@cartouche 11177@noindent 11178@strong{98}. Implementation-defined @code{policy_identifiers} allowed 11179in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3). 11180@end cartouche 11181@noindent 11182There are no implementation-defined policy-identifiers allowed in this 11183pragma. 11184 11185@sp 1 11186@cartouche 11187@noindent 11188@strong{99}. Implementation-defined aspects of priority inversion. See 11189D.2.2(16). 11190@end cartouche 11191@noindent 11192Execution of a task cannot be preempted by the implementation processing 11193of delay expirations for lower priority tasks. 11194 11195@sp 1 11196@cartouche 11197@noindent 11198@strong{100}. Implementation-defined task dispatching. See D.2.2(18). 11199@end cartouche 11200@noindent 11201The policy is the same as that of the underlying threads implementation. 11202 11203@sp 1 11204@cartouche 11205@noindent 11206@strong{101}. Implementation-defined @code{policy_identifiers} allowed 11207in a pragma @code{Locking_Policy}. See D.3(4). 11208@end cartouche 11209@noindent 11210The two implementation defined policies permitted in GNAT are 11211@code{Inheritance_Locking} and @code{Conccurent_Readers_Locking}. On 11212targets that support the @code{Inheritance_Locking} policy, locking is 11213implemented by inheritance, i.e.@: the task owning the lock operates 11214at a priority equal to the highest priority of any task currently 11215requesting the lock. On targets that support the 11216@code{Conccurent_Readers_Locking} policy, locking is implemented with a 11217read/write lock allowing multiple propected object functions to enter 11218concurrently. 11219 11220@sp 1 11221@cartouche 11222@noindent 11223@strong{102}. Default ceiling priorities. See D.3(10). 11224@end cartouche 11225@noindent 11226The ceiling priority of protected objects of the type 11227@code{System.Interrupt_Priority'Last} as described in the Ada 11228Reference Manual D.3(10), 11229 11230@sp 1 11231@cartouche 11232@noindent 11233@strong{103}. The ceiling of any protected object used internally by 11234the implementation. See D.3(16). 11235@end cartouche 11236@noindent 11237The ceiling priority of internal protected objects is 11238@code{System.Priority'Last}. 11239 11240@sp 1 11241@cartouche 11242@noindent 11243@strong{104}. Implementation-defined queuing policies. See D.4(1). 11244@end cartouche 11245@noindent 11246There are no implementation-defined queuing policies. 11247 11248@sp 1 11249@cartouche 11250@noindent 11251@strong{105}. On a multiprocessor, any conditions that cause the 11252completion of an aborted construct to be delayed later than what is 11253specified for a single processor. See D.6(3). 11254@end cartouche 11255@noindent 11256The semantics for abort on a multi-processor is the same as on a single 11257processor, there are no further delays. 11258 11259@sp 1 11260@cartouche 11261@noindent 11262@strong{106}. Any operations that implicitly require heap storage 11263allocation. See D.7(8). 11264@end cartouche 11265@noindent 11266The only operation that implicitly requires heap storage allocation is 11267task creation. 11268 11269@sp 1 11270@cartouche 11271@noindent 11272@strong{107}. Implementation-defined aspects of pragma 11273@code{Restrictions}. See D.7(20). 11274@end cartouche 11275@noindent 11276There are no such implementation-defined aspects. 11277 11278@sp 1 11279@cartouche 11280@noindent 11281@strong{108}. Implementation-defined aspects of package 11282@code{Real_Time}. See D.8(17). 11283@end cartouche 11284@noindent 11285There are no implementation defined aspects of package @code{Real_Time}. 11286 11287@sp 1 11288@cartouche 11289@noindent 11290@strong{109}. Implementation-defined aspects of 11291@code{delay_statements}. See D.9(8). 11292@end cartouche 11293@noindent 11294Any difference greater than one microsecond will cause the task to be 11295delayed (see D.9(7)). 11296 11297@sp 1 11298@cartouche 11299@noindent 11300@strong{110}. The upper bound on the duration of interrupt blocking 11301caused by the implementation. See D.12(5). 11302@end cartouche 11303@noindent 11304The upper bound is determined by the underlying operating system. In 11305no cases is it more than 10 milliseconds. 11306 11307@sp 1 11308@cartouche 11309@noindent 11310@strong{111}. The means for creating and executing distributed 11311programs. See E(5). 11312@end cartouche 11313@noindent 11314The GLADE package provides a utility GNATDIST for creating and executing 11315distributed programs. See the GLADE reference manual for further details. 11316 11317@sp 1 11318@cartouche 11319@noindent 11320@strong{112}. Any events that can result in a partition becoming 11321inaccessible. See E.1(7). 11322@end cartouche 11323@noindent 11324See the GLADE reference manual for full details on such events. 11325 11326@sp 1 11327@cartouche 11328@noindent 11329@strong{113}. The scheduling policies, treatment of priorities, and 11330management of shared resources between partitions in certain cases. See 11331E.1(11). 11332@end cartouche 11333@noindent 11334See the GLADE reference manual for full details on these aspects of 11335multi-partition execution. 11336 11337@sp 1 11338@cartouche 11339@noindent 11340@strong{114}. Events that cause the version of a compilation unit to 11341change. See E.3(5). 11342@end cartouche 11343@noindent 11344Editing the source file of a compilation unit, or the source files of 11345any units on which it is dependent in a significant way cause the version 11346to change. No other actions cause the version number to change. All changes 11347are significant except those which affect only layout, capitalization or 11348comments. 11349 11350@sp 1 11351@cartouche 11352@noindent 11353@strong{115}. Whether the execution of the remote subprogram is 11354immediately aborted as a result of cancellation. See E.4(13). 11355@end cartouche 11356@noindent 11357See the GLADE reference manual for details on the effect of abort in 11358a distributed application. 11359 11360@sp 1 11361@cartouche 11362@noindent 11363@strong{116}. Implementation-defined aspects of the PCS@. See E.5(25). 11364@end cartouche 11365@noindent 11366See the GLADE reference manual for a full description of all implementation 11367defined aspects of the PCS@. 11368 11369@sp 1 11370@cartouche 11371@noindent 11372@strong{117}. Implementation-defined interfaces in the PCS@. See 11373E.5(26). 11374@end cartouche 11375@noindent 11376See the GLADE reference manual for a full description of all 11377implementation defined interfaces. 11378 11379@sp 1 11380@cartouche 11381@noindent 11382@strong{118}. The values of named numbers in the package 11383@code{Decimal}. See F.2(7). 11384@end cartouche 11385@noindent 11386@table @code 11387@item Max_Scale 11388+18 11389@item Min_Scale 11390-18 11391@item Min_Delta 113921.0E-18 11393@item Max_Delta 113941.0E+18 11395@item Max_Decimal_Digits 1139618 11397@end table 11398 11399@sp 1 11400@cartouche 11401@noindent 11402@strong{119}. The value of @code{Max_Picture_Length} in the package 11403@code{Text_IO.Editing}. See F.3.3(16). 11404@end cartouche 11405@noindent 1140664 11407 11408@sp 1 11409@cartouche 11410@noindent 11411@strong{120}. The value of @code{Max_Picture_Length} in the package 11412@code{Wide_Text_IO.Editing}. See F.3.4(5). 11413@end cartouche 11414@noindent 1141564 11416 11417@sp 1 11418@cartouche 11419@noindent 11420@strong{121}. The accuracy actually achieved by the complex elementary 11421functions and by other complex arithmetic operations. See G.1(1). 11422@end cartouche 11423@noindent 11424Standard library functions are used for the complex arithmetic 11425operations. Only fast math mode is currently supported. 11426 11427@sp 1 11428@cartouche 11429@noindent 11430@strong{122}. The sign of a zero result (or a component thereof) from 11431any operator or function in @code{Numerics.Generic_Complex_Types}, when 11432@code{Real'Signed_Zeros} is True. See G.1.1(53). 11433@end cartouche 11434@noindent 11435The signs of zero values are as recommended by the relevant 11436implementation advice. 11437 11438@sp 1 11439@cartouche 11440@noindent 11441@strong{123}. The sign of a zero result (or a component thereof) from 11442any operator or function in 11443@code{Numerics.Generic_Complex_Elementary_Functions}, when 11444@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45). 11445@end cartouche 11446@noindent 11447The signs of zero values are as recommended by the relevant 11448implementation advice. 11449 11450@sp 1 11451@cartouche 11452@noindent 11453@strong{124}. Whether the strict mode or the relaxed mode is the 11454default. See G.2(2). 11455@end cartouche 11456@noindent 11457The strict mode is the default. There is no separate relaxed mode. GNAT 11458provides a highly efficient implementation of strict mode. 11459 11460@sp 1 11461@cartouche 11462@noindent 11463@strong{125}. The result interval in certain cases of fixed-to-float 11464conversion. See G.2.1(10). 11465@end cartouche 11466@noindent 11467For cases where the result interval is implementation dependent, the 11468accuracy is that provided by performing all operations in 64-bit IEEE 11469floating-point format. 11470 11471@sp 1 11472@cartouche 11473@noindent 11474@strong{126}. The result of a floating point arithmetic operation in 11475overflow situations, when the @code{Machine_Overflows} attribute of the 11476result type is @code{False}. See G.2.1(13). 11477@end cartouche 11478@noindent 11479Infinite and NaN values are produced as dictated by the IEEE 11480floating-point standard. 11481 11482Note that on machines that are not fully compliant with the IEEE 11483floating-point standard, such as Alpha, the @option{-mieee} compiler flag 11484must be used for achieving IEEE conforming behavior (although at the cost 11485of a significant performance penalty), so infinite and NaN values are 11486properly generated. 11487 11488@sp 1 11489@cartouche 11490@noindent 11491@strong{127}. The result interval for division (or exponentiation by a 11492negative exponent), when the floating point hardware implements division 11493as multiplication by a reciprocal. See G.2.1(16). 11494@end cartouche 11495@noindent 11496Not relevant, division is IEEE exact. 11497 11498@sp 1 11499@cartouche 11500@noindent 11501@strong{128}. The definition of close result set, which determines the 11502accuracy of certain fixed point multiplications and divisions. See 11503G.2.3(5). 11504@end cartouche 11505@noindent 11506Operations in the close result set are performed using IEEE long format 11507floating-point arithmetic. The input operands are converted to 11508floating-point, the operation is done in floating-point, and the result 11509is converted to the target type. 11510 11511@sp 1 11512@cartouche 11513@noindent 11514@strong{129}. Conditions on a @code{universal_real} operand of a fixed 11515point multiplication or division for which the result shall be in the 11516perfect result set. See G.2.3(22). 11517@end cartouche 11518@noindent 11519The result is only defined to be in the perfect result set if the result 11520can be computed by a single scaling operation involving a scale factor 11521representable in 64-bits. 11522 11523@sp 1 11524@cartouche 11525@noindent 11526@strong{130}. The result of a fixed point arithmetic operation in 11527overflow situations, when the @code{Machine_Overflows} attribute of the 11528result type is @code{False}. See G.2.3(27). 11529@end cartouche 11530@noindent 11531Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point 11532types. 11533 11534@sp 1 11535@cartouche 11536@noindent 11537@strong{131}. The result of an elementary function reference in 11538overflow situations, when the @code{Machine_Overflows} attribute of the 11539result type is @code{False}. See G.2.4(4). 11540@end cartouche 11541@noindent 11542IEEE infinite and Nan values are produced as appropriate. 11543 11544@sp 1 11545@cartouche 11546@noindent 11547@strong{132}. The value of the angle threshold, within which certain 11548elementary functions, complex arithmetic operations, and complex 11549elementary functions yield results conforming to a maximum relative 11550error bound. See G.2.4(10). 11551@end cartouche 11552@noindent 11553Information on this subject is not yet available. 11554 11555@sp 1 11556@cartouche 11557@noindent 11558@strong{133}. The accuracy of certain elementary functions for 11559parameters beyond the angle threshold. See G.2.4(10). 11560@end cartouche 11561@noindent 11562Information on this subject is not yet available. 11563 11564@sp 1 11565@cartouche 11566@noindent 11567@strong{134}. The result of a complex arithmetic operation or complex 11568elementary function reference in overflow situations, when the 11569@code{Machine_Overflows} attribute of the corresponding real type is 11570@code{False}. See G.2.6(5). 11571@end cartouche 11572@noindent 11573IEEE infinite and Nan values are produced as appropriate. 11574 11575@sp 1 11576@cartouche 11577@noindent 11578@strong{135}. The accuracy of certain complex arithmetic operations and 11579certain complex elementary functions for parameters (or components 11580thereof) beyond the angle threshold. See G.2.6(8). 11581@end cartouche 11582@noindent 11583Information on those subjects is not yet available. 11584 11585@sp 1 11586@cartouche 11587@noindent 11588@strong{136}. Information regarding bounded errors and erroneous 11589execution. See H.2(1). 11590@end cartouche 11591@noindent 11592Information on this subject is not yet available. 11593 11594@sp 1 11595@cartouche 11596@noindent 11597@strong{137}. Implementation-defined aspects of pragma 11598@code{Inspection_Point}. See H.3.2(8). 11599@end cartouche 11600@noindent 11601Pragma @code{Inspection_Point} ensures that the variable is live and can 11602be examined by the debugger at the inspection point. 11603 11604@sp 1 11605@cartouche 11606@noindent 11607@strong{138}. Implementation-defined aspects of pragma 11608@code{Restrictions}. See H.4(25). 11609@end cartouche 11610@noindent 11611There are no implementation-defined aspects of pragma @code{Restrictions}. The 11612use of pragma @code{Restrictions [No_Exceptions]} has no effect on the 11613generated code. Checks must suppressed by use of pragma @code{Suppress}. 11614 11615@sp 1 11616@cartouche 11617@noindent 11618@strong{139}. Any restrictions on pragma @code{Restrictions}. See 11619H.4(27). 11620@end cartouche 11621@noindent 11622There are no restrictions on pragma @code{Restrictions}. 11623 11624@node Intrinsic Subprograms 11625@chapter Intrinsic Subprograms 11626@cindex Intrinsic Subprograms 11627 11628@menu 11629* Intrinsic Operators:: 11630* Enclosing_Entity:: 11631* Exception_Information:: 11632* Exception_Message:: 11633* Exception_Name:: 11634* File:: 11635* Line:: 11636* Shifts and Rotates:: 11637* Source_Location:: 11638@end menu 11639 11640@noindent 11641GNAT allows a user application program to write the declaration: 11642 11643@smallexample @c ada 11644 pragma Import (Intrinsic, name); 11645@end smallexample 11646 11647@noindent 11648providing that the name corresponds to one of the implemented intrinsic 11649subprograms in GNAT, and that the parameter profile of the referenced 11650subprogram meets the requirements. This chapter describes the set of 11651implemented intrinsic subprograms, and the requirements on parameter profiles. 11652Note that no body is supplied; as with other uses of pragma Import, the 11653body is supplied elsewhere (in this case by the compiler itself). Note 11654that any use of this feature is potentially non-portable, since the 11655Ada standard does not require Ada compilers to implement this feature. 11656 11657@node Intrinsic Operators 11658@section Intrinsic Operators 11659@cindex Intrinsic operator 11660 11661@noindent 11662All the predefined numeric operators in package Standard 11663in @code{pragma Import (Intrinsic,..)} 11664declarations. In the binary operator case, the operands must have the same 11665size. The operand or operands must also be appropriate for 11666the operator. For example, for addition, the operands must 11667both be floating-point or both be fixed-point, and the 11668right operand for @code{"**"} must have a root type of 11669@code{Standard.Integer'Base}. 11670You can use an intrinsic operator declaration as in the following example: 11671 11672@smallexample @c ada 11673 type Int1 is new Integer; 11674 type Int2 is new Integer; 11675 11676 function "+" (X1 : Int1; X2 : Int2) return Int1; 11677 function "+" (X1 : Int1; X2 : Int2) return Int2; 11678 pragma Import (Intrinsic, "+"); 11679@end smallexample 11680 11681@noindent 11682This declaration would permit ``mixed mode'' arithmetic on items 11683of the differing types @code{Int1} and @code{Int2}. 11684It is also possible to specify such operators for private types, if the 11685full views are appropriate arithmetic types. 11686 11687@node Enclosing_Entity 11688@section Enclosing_Entity 11689@cindex Enclosing_Entity 11690@noindent 11691This intrinsic subprogram is used in the implementation of the 11692library routine @code{GNAT.Source_Info}. The only useful use of the 11693intrinsic import in this case is the one in this unit, so an 11694application program should simply call the function 11695@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 11696the current subprogram, package, task, entry, or protected subprogram. 11697 11698@node Exception_Information 11699@section Exception_Information 11700@cindex Exception_Information' 11701@noindent 11702This intrinsic subprogram is used in the implementation of the 11703library routine @code{GNAT.Current_Exception}. The only useful 11704use of the intrinsic import in this case is the one in this unit, 11705so an application program should simply call the function 11706@code{GNAT.Current_Exception.Exception_Information} to obtain 11707the exception information associated with the current exception. 11708 11709@node Exception_Message 11710@section Exception_Message 11711@cindex Exception_Message 11712@noindent 11713This intrinsic subprogram is used in the implementation of the 11714library routine @code{GNAT.Current_Exception}. The only useful 11715use of the intrinsic import in this case is the one in this unit, 11716so an application program should simply call the function 11717@code{GNAT.Current_Exception.Exception_Message} to obtain 11718the message associated with the current exception. 11719 11720@node Exception_Name 11721@section Exception_Name 11722@cindex Exception_Name 11723@noindent 11724This intrinsic subprogram is used in the implementation of the 11725library routine @code{GNAT.Current_Exception}. The only useful 11726use of the intrinsic import in this case is the one in this unit, 11727so an application program should simply call the function 11728@code{GNAT.Current_Exception.Exception_Name} to obtain 11729the name of the current exception. 11730 11731@node File 11732@section File 11733@cindex File 11734@noindent 11735This intrinsic subprogram is used in the implementation of the 11736library routine @code{GNAT.Source_Info}. The only useful use of the 11737intrinsic import in this case is the one in this unit, so an 11738application program should simply call the function 11739@code{GNAT.Source_Info.File} to obtain the name of the current 11740file. 11741 11742@node Line 11743@section Line 11744@cindex Line 11745@noindent 11746This intrinsic subprogram is used in the implementation of the 11747library routine @code{GNAT.Source_Info}. The only useful use of the 11748intrinsic import in this case is the one in this unit, so an 11749application program should simply call the function 11750@code{GNAT.Source_Info.Line} to obtain the number of the current 11751source line. 11752 11753@node Shifts and Rotates 11754@section Shifts and Rotates 11755@cindex Shift_Left 11756@cindex Shift_Right 11757@cindex Shift_Right_Arithmetic 11758@cindex Rotate_Left 11759@cindex Rotate_Right 11760@noindent 11761In standard Ada, the shift and rotate functions are available only 11762for the predefined modular types in package @code{Interfaces}. However, in 11763GNAT it is possible to define these functions for any integer 11764type (signed or modular), as in this example: 11765 11766@smallexample @c ada 11767 function Shift_Left 11768 (Value : T; 11769 Amount : Natural) 11770 return T; 11771@end smallexample 11772 11773@noindent 11774The function name must be one of 11775Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or 11776Rotate_Right. T must be an integer type. T'Size must be 117778, 16, 32 or 64 bits; if T is modular, the modulus 11778must be 2**8, 2**16, 2**32 or 2**64. 11779The result type must be the same as the type of @code{Value}. 11780The shift amount must be Natural. 11781The formal parameter names can be anything. 11782 11783@node Source_Location 11784@section Source_Location 11785@cindex Source_Location 11786@noindent 11787This intrinsic subprogram is used in the implementation of the 11788library routine @code{GNAT.Source_Info}. The only useful use of the 11789intrinsic import in this case is the one in this unit, so an 11790application program should simply call the function 11791@code{GNAT.Source_Info.Source_Location} to obtain the current 11792source file location. 11793 11794@node Representation Clauses and Pragmas 11795@chapter Representation Clauses and Pragmas 11796@cindex Representation Clauses 11797 11798@menu 11799* Alignment Clauses:: 11800* Size Clauses:: 11801* Storage_Size Clauses:: 11802* Size of Variant Record Objects:: 11803* Biased Representation :: 11804* Value_Size and Object_Size Clauses:: 11805* Component_Size Clauses:: 11806* Bit_Order Clauses:: 11807* Effect of Bit_Order on Byte Ordering:: 11808* Pragma Pack for Arrays:: 11809* Pragma Pack for Records:: 11810* Record Representation Clauses:: 11811* Enumeration Clauses:: 11812* Address Clauses:: 11813* Effect of Convention on Representation:: 11814* Determining the Representations chosen by GNAT:: 11815@end menu 11816 11817@noindent 11818@cindex Representation Clause 11819@cindex Representation Pragma 11820@cindex Pragma, representation 11821This section describes the representation clauses accepted by GNAT, and 11822their effect on the representation of corresponding data objects. 11823 11824GNAT fully implements Annex C (Systems Programming). This means that all 11825the implementation advice sections in chapter 13 are fully implemented. 11826However, these sections only require a minimal level of support for 11827representation clauses. GNAT provides much more extensive capabilities, 11828and this section describes the additional capabilities provided. 11829 11830@node Alignment Clauses 11831@section Alignment Clauses 11832@cindex Alignment Clause 11833 11834@noindent 11835GNAT requires that all alignment clauses specify a power of 2, and all 11836default alignments are always a power of 2. The default alignment 11837values are as follows: 11838 11839@itemize @bullet 11840@item @emph{Primitive Types}. 11841For primitive types, the alignment is the minimum of the actual size of 11842objects of the type divided by @code{Storage_Unit}, 11843and the maximum alignment supported by the target. 11844(This maximum alignment is given by the GNAT-specific attribute 11845@code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.) 11846@cindex @code{Maximum_Alignment} attribute 11847For example, for type @code{Long_Float}, the object size is 8 bytes, and the 11848default alignment will be 8 on any target that supports alignments 11849this large, but on some targets, the maximum alignment may be smaller 11850than 8, in which case objects of type @code{Long_Float} will be maximally 11851aligned. 11852 11853@item @emph{Arrays}. 11854For arrays, the alignment is equal to the alignment of the component type 11855for the normal case where no packing or component size is given. If the 11856array is packed, and the packing is effective (see separate section on 11857packed arrays), then the alignment will be one for long packed arrays, 11858or arrays whose length is not known at compile time. For short packed 11859arrays, which are handled internally as modular types, the alignment 11860will be as described for primitive types, e.g.@: a packed array of length 1186131 bits will have an object size of four bytes, and an alignment of 4. 11862 11863@item @emph{Records}. 11864For the normal non-packed case, the alignment of a record is equal to 11865the maximum alignment of any of its components. For tagged records, this 11866includes the implicit access type used for the tag. If a pragma @code{Pack} 11867is used and all components are packable (see separate section on pragma 11868@code{Pack}), then the resulting alignment is 1, unless the layout of the 11869record makes it profitable to increase it. 11870 11871A special case is when: 11872@itemize @bullet 11873@item 11874the size of the record is given explicitly, or a 11875full record representation clause is given, and 11876@item 11877the size of the record is 2, 4, or 8 bytes. 11878@end itemize 11879@noindent 11880In this case, an alignment is chosen to match the 11881size of the record. For example, if we have: 11882 11883@smallexample @c ada 11884 type Small is record 11885 A, B : Character; 11886 end record; 11887 for Small'Size use 16; 11888@end smallexample 11889 11890@noindent 11891then the default alignment of the record type @code{Small} is 2, not 1. This 11892leads to more efficient code when the record is treated as a unit, and also 11893allows the type to specified as @code{Atomic} on architectures requiring 11894strict alignment. 11895 11896@end itemize 11897 11898@noindent 11899An alignment clause may specify a larger alignment than the default value 11900up to some maximum value dependent on the target (obtainable by using the 11901attribute reference @code{Standard'Maximum_Alignment}). It may also specify 11902a smaller alignment than the default value for enumeration, integer and 11903fixed point types, as well as for record types, for example 11904 11905@smallexample @c ada 11906 type V is record 11907 A : Integer; 11908 end record; 11909 11910 for V'alignment use 1; 11911@end smallexample 11912 11913@noindent 11914@cindex Alignment, default 11915The default alignment for the type @code{V} is 4, as a result of the 11916Integer field in the record, but it is permissible, as shown, to 11917override the default alignment of the record with a smaller value. 11918 11919@cindex Alignment, subtypes 11920Note that according to the Ada standard, an alignment clause applies only 11921to the first named subtype. If additional subtypes are declared, then the 11922compiler is allowed to choose any alignment it likes, and there is no way 11923to control this choice. Consider: 11924 11925@smallexample @c ada 11926 type R is range 1 .. 10_000; 11927 for R'Alignment use 1; 11928 subtype RS is R range 1 .. 1000; 11929@end smallexample 11930 11931@noindent 11932The alignment clause specifies an alignment of 1 for the first named subtype 11933@code{R} but this does not necessarily apply to @code{RS}. When writing 11934portable Ada code, you should avoid writing code that explicitly or 11935implicitly relies on the alignment of such subtypes. 11936 11937For the GNAT compiler, if an explicit alignment clause is given, this 11938value is also used for any subsequent subtypes. So for GNAT, in the 11939above example, you can count on the alignment of @code{RS} being 1. But this 11940assumption is non-portable, and other compilers may choose different 11941alignments for the subtype @code{RS}. 11942 11943@node Size Clauses 11944@section Size Clauses 11945@cindex Size Clause 11946 11947@noindent 11948The default size for a type @code{T} is obtainable through the 11949language-defined attribute @code{T'Size} and also through the 11950equivalent GNAT-defined attribute @code{T'Value_Size}. 11951For objects of type @code{T}, GNAT will generally increase the type size 11952so that the object size (obtainable through the GNAT-defined attribute 11953@code{T'Object_Size}) 11954is a multiple of @code{T'Alignment * Storage_Unit}. 11955For example 11956 11957@smallexample @c ada 11958 type Smallint is range 1 .. 6; 11959 11960 type Rec is record 11961 Y1 : integer; 11962 Y2 : boolean; 11963 end record; 11964@end smallexample 11965 11966@noindent 11967In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, 11968as specified by the RM rules, 11969but objects of this type will have a size of 8 11970(@code{Smallint'Object_Size} = 8), 11971since objects by default occupy an integral number 11972of storage units. On some targets, notably older 11973versions of the Digital Alpha, the size of stand 11974alone objects of this type may be 32, reflecting 11975the inability of the hardware to do byte load/stores. 11976 11977Similarly, the size of type @code{Rec} is 40 bits 11978(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but 11979the alignment is 4, so objects of this type will have 11980their size increased to 64 bits so that it is a multiple 11981of the alignment (in bits). This decision is 11982in accordance with the specific Implementation Advice in RM 13.3(43): 11983 11984@quotation 11985A @code{Size} clause should be supported for an object if the specified 11986@code{Size} is at least as large as its subtype's @code{Size}, and corresponds 11987to a size in storage elements that is a multiple of the object's 11988@code{Alignment} (if the @code{Alignment} is nonzero). 11989@end quotation 11990 11991@noindent 11992An explicit size clause may be used to override the default size by 11993increasing it. For example, if we have: 11994 11995@smallexample @c ada 11996 type My_Boolean is new Boolean; 11997 for My_Boolean'Size use 32; 11998@end smallexample 11999 12000@noindent 12001then values of this type will always be 32 bits long. In the case of 12002discrete types, the size can be increased up to 64 bits, with the effect 12003that the entire specified field is used to hold the value, sign- or 12004zero-extended as appropriate. If more than 64 bits is specified, then 12005padding space is allocated after the value, and a warning is issued that 12006there are unused bits. 12007 12008Similarly the size of records and arrays may be increased, and the effect 12009is to add padding bits after the value. This also causes a warning message 12010to be generated. 12011 12012The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a 12013Size in bits, this corresponds to an object of size 256 megabytes (minus 12014one). This limitation is true on all targets. The reason for this 12015limitation is that it improves the quality of the code in many cases 12016if it is known that a Size value can be accommodated in an object of 12017type Integer. 12018 12019@node Storage_Size Clauses 12020@section Storage_Size Clauses 12021@cindex Storage_Size Clause 12022 12023@noindent 12024For tasks, the @code{Storage_Size} clause specifies the amount of space 12025to be allocated for the task stack. This cannot be extended, and if the 12026stack is exhausted, then @code{Storage_Error} will be raised (if stack 12027checking is enabled). Use a @code{Storage_Size} attribute definition clause, 12028or a @code{Storage_Size} pragma in the task definition to set the 12029appropriate required size. A useful technique is to include in every 12030task definition a pragma of the form: 12031 12032@smallexample @c ada 12033 pragma Storage_Size (Default_Stack_Size); 12034@end smallexample 12035 12036@noindent 12037Then @code{Default_Stack_Size} can be defined in a global package, and 12038modified as required. Any tasks requiring stack sizes different from the 12039default can have an appropriate alternative reference in the pragma. 12040 12041You can also use the @option{-d} binder switch to modify the default stack 12042size. 12043 12044For access types, the @code{Storage_Size} clause specifies the maximum 12045space available for allocation of objects of the type. If this space is 12046exceeded then @code{Storage_Error} will be raised by an allocation attempt. 12047In the case where the access type is declared local to a subprogram, the 12048use of a @code{Storage_Size} clause triggers automatic use of a special 12049predefined storage pool (@code{System.Pool_Size}) that ensures that all 12050space for the pool is automatically reclaimed on exit from the scope in 12051which the type is declared. 12052 12053A special case recognized by the compiler is the specification of a 12054@code{Storage_Size} of zero for an access type. This means that no 12055items can be allocated from the pool, and this is recognized at compile 12056time, and all the overhead normally associated with maintaining a fixed 12057size storage pool is eliminated. Consider the following example: 12058 12059@smallexample @c ada 12060 procedure p is 12061 type R is array (Natural) of Character; 12062 type P is access all R; 12063 for P'Storage_Size use 0; 12064 -- Above access type intended only for interfacing purposes 12065 12066 y : P; 12067 12068 procedure g (m : P); 12069 pragma Import (C, g); 12070 12071 -- @dots{} 12072 12073 begin 12074 -- @dots{} 12075 y := new R; 12076 end; 12077@end smallexample 12078 12079@noindent 12080As indicated in this example, these dummy storage pools are often useful in 12081connection with interfacing where no object will ever be allocated. If you 12082compile the above example, you get the warning: 12083 12084@smallexample 12085 p.adb:16:09: warning: allocation from empty storage pool 12086 p.adb:16:09: warning: Storage_Error will be raised at run time 12087@end smallexample 12088 12089@noindent 12090Of course in practice, there will not be any explicit allocators in the 12091case of such an access declaration. 12092 12093@node Size of Variant Record Objects 12094@section Size of Variant Record Objects 12095@cindex Size, variant record objects 12096@cindex Variant record objects, size 12097 12098@noindent 12099In the case of variant record objects, there is a question whether Size gives 12100information about a particular variant, or the maximum size required 12101for any variant. Consider the following program 12102 12103@smallexample @c ada 12104with Text_IO; use Text_IO; 12105procedure q is 12106 type R1 (A : Boolean := False) is record 12107 case A is 12108 when True => X : Character; 12109 when False => null; 12110 end case; 12111 end record; 12112 12113 V1 : R1 (False); 12114 V2 : R1; 12115 12116begin 12117 Put_Line (Integer'Image (V1'Size)); 12118 Put_Line (Integer'Image (V2'Size)); 12119end q; 12120@end smallexample 12121 12122@noindent 12123Here we are dealing with a variant record, where the True variant 12124requires 16 bits, and the False variant requires 8 bits. 12125In the above example, both V1 and V2 contain the False variant, 12126which is only 8 bits long. However, the result of running the 12127program is: 12128 12129@smallexample 121308 1213116 12132@end smallexample 12133 12134@noindent 12135The reason for the difference here is that the discriminant value of 12136V1 is fixed, and will always be False. It is not possible to assign 12137a True variant value to V1, therefore 8 bits is sufficient. On the 12138other hand, in the case of V2, the initial discriminant value is 12139False (from the default), but it is possible to assign a True 12140variant value to V2, therefore 16 bits must be allocated for V2 12141in the general case, even fewer bits may be needed at any particular 12142point during the program execution. 12143 12144As can be seen from the output of this program, the @code{'Size} 12145attribute applied to such an object in GNAT gives the actual allocated 12146size of the variable, which is the largest size of any of the variants. 12147The Ada Reference Manual is not completely clear on what choice should 12148be made here, but the GNAT behavior seems most consistent with the 12149language in the RM@. 12150 12151In some cases, it may be desirable to obtain the size of the current 12152variant, rather than the size of the largest variant. This can be 12153achieved in GNAT by making use of the fact that in the case of a 12154subprogram parameter, GNAT does indeed return the size of the current 12155variant (because a subprogram has no way of knowing how much space 12156is actually allocated for the actual). 12157 12158Consider the following modified version of the above program: 12159 12160@smallexample @c ada 12161with Text_IO; use Text_IO; 12162procedure q is 12163 type R1 (A : Boolean := False) is record 12164 case A is 12165 when True => X : Character; 12166 when False => null; 12167 end case; 12168 end record; 12169 12170 V2 : R1; 12171 12172 function Size (V : R1) return Integer is 12173 begin 12174 return V'Size; 12175 end Size; 12176 12177begin 12178 Put_Line (Integer'Image (V2'Size)); 12179 Put_Line (Integer'IMage (Size (V2))); 12180 V2 := (True, 'x'); 12181 Put_Line (Integer'Image (V2'Size)); 12182 Put_Line (Integer'IMage (Size (V2))); 12183end q; 12184@end smallexample 12185 12186@noindent 12187The output from this program is 12188 12189@smallexample 1219016 121918 1219216 1219316 12194@end smallexample 12195 12196@noindent 12197Here we see that while the @code{'Size} attribute always returns 12198the maximum size, regardless of the current variant value, the 12199@code{Size} function does indeed return the size of the current 12200variant value. 12201 12202@node Biased Representation 12203@section Biased Representation 12204@cindex Size for biased representation 12205@cindex Biased representation 12206 12207@noindent 12208In the case of scalars with a range starting at other than zero, it is 12209possible in some cases to specify a size smaller than the default minimum 12210value, and in such cases, GNAT uses an unsigned biased representation, 12211in which zero is used to represent the lower bound, and successive values 12212represent successive values of the type. 12213 12214For example, suppose we have the declaration: 12215 12216@smallexample @c ada 12217 type Small is range -7 .. -4; 12218 for Small'Size use 2; 12219@end smallexample 12220 12221@noindent 12222Although the default size of type @code{Small} is 4, the @code{Size} 12223clause is accepted by GNAT and results in the following representation 12224scheme: 12225 12226@smallexample 12227 -7 is represented as 2#00# 12228 -6 is represented as 2#01# 12229 -5 is represented as 2#10# 12230 -4 is represented as 2#11# 12231@end smallexample 12232 12233@noindent 12234Biased representation is only used if the specified @code{Size} clause 12235cannot be accepted in any other manner. These reduced sizes that force 12236biased representation can be used for all discrete types except for 12237enumeration types for which a representation clause is given. 12238 12239@node Value_Size and Object_Size Clauses 12240@section Value_Size and Object_Size Clauses 12241@findex Value_Size 12242@findex Object_Size 12243@cindex Size, of objects 12244 12245@noindent 12246In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum 12247number of bits required to hold values of type @code{T}. 12248Although this interpretation was allowed in Ada 83, it was not required, 12249and this requirement in practice can cause some significant difficulties. 12250For example, in most Ada 83 compilers, @code{Natural'Size} was 32. 12251However, in Ada 95 and Ada 2005, 12252@code{Natural'Size} is 12253typically 31. This means that code may change in behavior when moving 12254from Ada 83 to Ada 95 or Ada 2005. For example, consider: 12255 12256@smallexample @c ada 12257 type Rec is record; 12258 A : Natural; 12259 B : Natural; 12260 end record; 12261 12262 for Rec use record 12263 at 0 range 0 .. Natural'Size - 1; 12264 at 0 range Natural'Size .. 2 * Natural'Size - 1; 12265 end record; 12266@end smallexample 12267 12268@noindent 12269In the above code, since the typical size of @code{Natural} objects 12270is 32 bits and @code{Natural'Size} is 31, the above code can cause 12271unexpected inefficient packing in Ada 95 and Ada 2005, and in general 12272there are cases where the fact that the object size can exceed the 12273size of the type causes surprises. 12274 12275To help get around this problem GNAT provides two implementation 12276defined attributes, @code{Value_Size} and @code{Object_Size}. When 12277applied to a type, these attributes yield the size of the type 12278(corresponding to the RM defined size attribute), and the size of 12279objects of the type respectively. 12280 12281The @code{Object_Size} is used for determining the default size of 12282objects and components. This size value can be referred to using the 12283@code{Object_Size} attribute. The phrase ``is used'' here means that it is 12284the basis of the determination of the size. The backend is free to 12285pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone 12286character might be stored in 32 bits on a machine with no efficient 12287byte access instructions such as the Alpha. 12288 12289The default rules for the value of @code{Object_Size} for 12290discrete types are as follows: 12291 12292@itemize @bullet 12293@item 12294The @code{Object_Size} for base subtypes reflect the natural hardware 12295size in bits (run the compiler with @option{-gnatS} to find those values 12296for numeric types). Enumeration types and fixed-point base subtypes have 122978, 16, 32 or 64 bits for this size, depending on the range of values 12298to be stored. 12299 12300@item 12301The @code{Object_Size} of a subtype is the same as the 12302@code{Object_Size} of 12303the type from which it is obtained. 12304 12305@item 12306The @code{Object_Size} of a derived base type is copied from the parent 12307base type, and the @code{Object_Size} of a derived first subtype is copied 12308from the parent first subtype. 12309@end itemize 12310 12311@noindent 12312The @code{Value_Size} attribute 12313is the (minimum) number of bits required to store a value 12314of the type. 12315This value is used to determine how tightly to pack 12316records or arrays with components of this type, and also affects 12317the semantics of unchecked conversion (unchecked conversions where 12318the @code{Value_Size} values differ generate a warning, and are potentially 12319target dependent). 12320 12321The default rules for the value of @code{Value_Size} are as follows: 12322 12323@itemize @bullet 12324@item 12325The @code{Value_Size} for a base subtype is the minimum number of bits 12326required to store all values of the type (including the sign bit 12327only if negative values are possible). 12328 12329@item 12330If a subtype statically matches the first subtype of a given type, then it has 12331by default the same @code{Value_Size} as the first subtype. This is a 12332consequence of RM 13.1(14) (``if two subtypes statically match, 12333then their subtype-specific aspects are the same''.) 12334 12335@item 12336All other subtypes have a @code{Value_Size} corresponding to the minimum 12337number of bits required to store all values of the subtype. For 12338dynamic bounds, it is assumed that the value can range down or up 12339to the corresponding bound of the ancestor 12340@end itemize 12341 12342@noindent 12343The RM defined attribute @code{Size} corresponds to the 12344@code{Value_Size} attribute. 12345 12346The @code{Size} attribute may be defined for a first-named subtype. This sets 12347the @code{Value_Size} of 12348the first-named subtype to the given value, and the 12349@code{Object_Size} of this first-named subtype to the given value padded up 12350to an appropriate boundary. It is a consequence of the default rules 12351above that this @code{Object_Size} will apply to all further subtypes. On the 12352other hand, @code{Value_Size} is affected only for the first subtype, any 12353dynamic subtypes obtained from it directly, and any statically matching 12354subtypes. The @code{Value_Size} of any other static subtypes is not affected. 12355 12356@code{Value_Size} and 12357@code{Object_Size} may be explicitly set for any subtype using 12358an attribute definition clause. Note that the use of these attributes 12359can cause the RM 13.1(14) rule to be violated. If two access types 12360reference aliased objects whose subtypes have differing @code{Object_Size} 12361values as a result of explicit attribute definition clauses, then it 12362is erroneous to convert from one access subtype to the other. 12363 12364At the implementation level, Esize stores the Object_Size and the 12365RM_Size field stores the @code{Value_Size} (and hence the value of the 12366@code{Size} attribute, 12367which, as noted above, is equivalent to @code{Value_Size}). 12368 12369To get a feel for the difference, consider the following examples (note 12370that in each case the base is @code{Short_Short_Integer} with a size of 8): 12371 12372@smallexample 12373 Object_Size Value_Size 12374 12375type x1 is range 0 .. 5; 8 3 12376 12377type x2 is range 0 .. 5; 12378for x2'size use 12; 16 12 12379 12380subtype x3 is x2 range 0 .. 3; 16 2 12381 12382subtype x4 is x2'base range 0 .. 10; 8 4 12383 12384subtype x5 is x2 range 0 .. dynamic; 16 3* 12385 12386subtype x6 is x2'base range 0 .. dynamic; 8 3* 12387 12388@end smallexample 12389 12390@noindent 12391Note: the entries marked ``3*'' are not actually specified by the Ada 12392Reference Manual, but it seems in the spirit of the RM rules to allocate 12393the minimum number of bits (here 3, given the range for @code{x2}) 12394known to be large enough to hold the given range of values. 12395 12396So far, so good, but GNAT has to obey the RM rules, so the question is 12397under what conditions must the RM @code{Size} be used. 12398The following is a list 12399of the occasions on which the RM @code{Size} must be used: 12400 12401@itemize @bullet 12402@item 12403Component size for packed arrays or records 12404 12405@item 12406Value of the attribute @code{Size} for a type 12407 12408@item 12409Warning about sizes not matching for unchecked conversion 12410@end itemize 12411 12412@noindent 12413For record types, the @code{Object_Size} is always a multiple of the 12414alignment of the type (this is true for all types). In some cases the 12415@code{Value_Size} can be smaller. Consider: 12416 12417@smallexample 12418 type R is record 12419 X : Integer; 12420 Y : Character; 12421 end record; 12422@end smallexample 12423 12424@noindent 12425On a typical 32-bit architecture, the X component will be four bytes, and 12426require four-byte alignment, and the Y component will be one byte. In this 12427case @code{R'Value_Size} will be 40 (bits) since this is the minimum size 12428required to store a value of this type, and for example, it is permissible 12429to have a component of type R in an outer array whose component size is 12430specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits), 12431since it must be rounded up so that this value is a multiple of the 12432alignment (4 bytes = 32 bits). 12433 12434@noindent 12435For all other types, the @code{Object_Size} 12436and Value_Size are the same (and equivalent to the RM attribute @code{Size}). 12437Only @code{Size} may be specified for such types. 12438 12439@node Component_Size Clauses 12440@section Component_Size Clauses 12441@cindex Component_Size Clause 12442 12443@noindent 12444Normally, the value specified in a component size clause must be consistent 12445with the subtype of the array component with regard to size and alignment. 12446In other words, the value specified must be at least equal to the size 12447of this subtype, and must be a multiple of the alignment value. 12448 12449In addition, component size clauses are allowed which cause the array 12450to be packed, by specifying a smaller value. A first case is for 12451component size values in the range 1 through 63. The value specified 12452must not be smaller than the Size of the subtype. GNAT will accurately 12453honor all packing requests in this range. For example, if we have: 12454 12455@smallexample @c ada 12456type r is array (1 .. 8) of Natural; 12457for r'Component_Size use 31; 12458@end smallexample 12459 12460@noindent 12461then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 12462Of course access to the components of such an array is considerably 12463less efficient than if the natural component size of 32 is used. 12464A second case is when the subtype of the component is a record type 12465padded because of its default alignment. For example, if we have: 12466 12467@smallexample @c ada 12468type r is record 12469 i : Integer; 12470 j : Integer; 12471 b : Boolean; 12472end record; 12473 12474type a is array (1 .. 8) of r; 12475for a'Component_Size use 72; 12476@end smallexample 12477 12478@noindent 12479then the resulting array has a length of 72 bytes, instead of 96 bytes 12480if the alignment of the record (4) was obeyed. 12481 12482Note that there is no point in giving both a component size clause 12483and a pragma Pack for the same array type. if such duplicate 12484clauses are given, the pragma Pack will be ignored. 12485 12486@node Bit_Order Clauses 12487@section Bit_Order Clauses 12488@cindex Bit_Order Clause 12489@cindex bit ordering 12490@cindex ordering, of bits 12491 12492@noindent 12493For record subtypes, GNAT permits the specification of the @code{Bit_Order} 12494attribute. The specification may either correspond to the default bit 12495order for the target, in which case the specification has no effect and 12496places no additional restrictions, or it may be for the non-standard 12497setting (that is the opposite of the default). 12498 12499In the case where the non-standard value is specified, the effect is 12500to renumber bits within each byte, but the ordering of bytes is not 12501affected. There are certain 12502restrictions placed on component clauses as follows: 12503 12504@itemize @bullet 12505 12506@item Components fitting within a single storage unit. 12507@noindent 12508These are unrestricted, and the effect is merely to renumber bits. For 12509example if we are on a little-endian machine with @code{Low_Order_First} 12510being the default, then the following two declarations have exactly 12511the same effect: 12512 12513@smallexample @c ada 12514 type R1 is record 12515 A : Boolean; 12516 B : Integer range 1 .. 120; 12517 end record; 12518 12519 for R1 use record 12520 A at 0 range 0 .. 0; 12521 B at 0 range 1 .. 7; 12522 end record; 12523 12524 type R2 is record 12525 A : Boolean; 12526 B : Integer range 1 .. 120; 12527 end record; 12528 12529 for R2'Bit_Order use High_Order_First; 12530 12531 for R2 use record 12532 A at 0 range 7 .. 7; 12533 B at 0 range 0 .. 6; 12534 end record; 12535@end smallexample 12536 12537@noindent 12538The useful application here is to write the second declaration with the 12539@code{Bit_Order} attribute definition clause, and know that it will be treated 12540the same, regardless of whether the target is little-endian or big-endian. 12541 12542@item Components occupying an integral number of bytes. 12543@noindent 12544These are components that exactly fit in two or more bytes. Such component 12545declarations are allowed, but have no effect, since it is important to realize 12546that the @code{Bit_Order} specification does not affect the ordering of bytes. 12547In particular, the following attempt at getting an endian-independent integer 12548does not work: 12549 12550@smallexample @c ada 12551 type R2 is record 12552 A : Integer; 12553 end record; 12554 12555 for R2'Bit_Order use High_Order_First; 12556 12557 for R2 use record 12558 A at 0 range 0 .. 31; 12559 end record; 12560@end smallexample 12561 12562@noindent 12563This declaration will result in a little-endian integer on a 12564little-endian machine, and a big-endian integer on a big-endian machine. 12565If byte flipping is required for interoperability between big- and 12566little-endian machines, this must be explicitly programmed. This capability 12567is not provided by @code{Bit_Order}. 12568 12569@item Components that are positioned across byte boundaries 12570@noindent 12571but do not occupy an integral number of bytes. Given that bytes are not 12572reordered, such fields would occupy a non-contiguous sequence of bits 12573in memory, requiring non-trivial code to reassemble. They are for this 12574reason not permitted, and any component clause specifying such a layout 12575will be flagged as illegal by GNAT@. 12576 12577@end itemize 12578 12579@noindent 12580Since the misconception that Bit_Order automatically deals with all 12581endian-related incompatibilities is a common one, the specification of 12582a component field that is an integral number of bytes will always 12583generate a warning. This warning may be suppressed using @code{pragma 12584Warnings (Off)} if desired. The following section contains additional 12585details regarding the issue of byte ordering. 12586 12587@node Effect of Bit_Order on Byte Ordering 12588@section Effect of Bit_Order on Byte Ordering 12589@cindex byte ordering 12590@cindex ordering, of bytes 12591 12592@noindent 12593In this section we will review the effect of the @code{Bit_Order} attribute 12594definition clause on byte ordering. Briefly, it has no effect at all, but 12595a detailed example will be helpful. Before giving this 12596example, let us review the precise 12597definition of the effect of defining @code{Bit_Order}. The effect of a 12598non-standard bit order is described in section 15.5.3 of the Ada 12599Reference Manual: 12600 12601@quotation 126022 A bit ordering is a method of interpreting the meaning of 12603the storage place attributes. 12604@end quotation 12605 12606@noindent 12607To understand the precise definition of storage place attributes in 12608this context, we visit section 13.5.1 of the manual: 12609 12610@quotation 1261113 A record_representation_clause (without the mod_clause) 12612specifies the layout. The storage place attributes (see 13.5.2) 12613are taken from the values of the position, first_bit, and last_bit 12614expressions after normalizing those values so that first_bit is 12615less than Storage_Unit. 12616@end quotation 12617 12618@noindent 12619The critical point here is that storage places are taken from 12620the values after normalization, not before. So the @code{Bit_Order} 12621interpretation applies to normalized values. The interpretation 12622is described in the later part of the 15.5.3 paragraph: 12623 12624@quotation 126252 A bit ordering is a method of interpreting the meaning of 12626the storage place attributes. High_Order_First (known in the 12627vernacular as ``big endian'') means that the first bit of a 12628storage element (bit 0) is the most significant bit (interpreting 12629the sequence of bits that represent a component as an unsigned 12630integer value). Low_Order_First (known in the vernacular as 12631``little endian'') means the opposite: the first bit is the 12632least significant. 12633@end quotation 12634 12635@noindent 12636Note that the numbering is with respect to the bits of a storage 12637unit. In other words, the specification affects only the numbering 12638of bits within a single storage unit. 12639 12640We can make the effect clearer by giving an example. 12641 12642Suppose that we have an external device which presents two bytes, the first 12643byte presented, which is the first (low addressed byte) of the two byte 12644record is called Master, and the second byte is called Slave. 12645 12646The left most (most significant bit is called Control for each byte, and 12647the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost 12648(least significant) bit. 12649 12650On a big-endian machine, we can write the following representation clause 12651 12652@smallexample @c ada 12653 type Data is record 12654 Master_Control : Bit; 12655 Master_V1 : Bit; 12656 Master_V2 : Bit; 12657 Master_V3 : Bit; 12658 Master_V4 : Bit; 12659 Master_V5 : Bit; 12660 Master_V6 : Bit; 12661 Master_V7 : Bit; 12662 Slave_Control : Bit; 12663 Slave_V1 : Bit; 12664 Slave_V2 : Bit; 12665 Slave_V3 : Bit; 12666 Slave_V4 : Bit; 12667 Slave_V5 : Bit; 12668 Slave_V6 : Bit; 12669 Slave_V7 : Bit; 12670 end record; 12671 12672 for Data use record 12673 Master_Control at 0 range 0 .. 0; 12674 Master_V1 at 0 range 1 .. 1; 12675 Master_V2 at 0 range 2 .. 2; 12676 Master_V3 at 0 range 3 .. 3; 12677 Master_V4 at 0 range 4 .. 4; 12678 Master_V5 at 0 range 5 .. 5; 12679 Master_V6 at 0 range 6 .. 6; 12680 Master_V7 at 0 range 7 .. 7; 12681 Slave_Control at 1 range 0 .. 0; 12682 Slave_V1 at 1 range 1 .. 1; 12683 Slave_V2 at 1 range 2 .. 2; 12684 Slave_V3 at 1 range 3 .. 3; 12685 Slave_V4 at 1 range 4 .. 4; 12686 Slave_V5 at 1 range 5 .. 5; 12687 Slave_V6 at 1 range 6 .. 6; 12688 Slave_V7 at 1 range 7 .. 7; 12689 end record; 12690@end smallexample 12691 12692@noindent 12693Now if we move this to a little endian machine, then the bit ordering within 12694the byte is backwards, so we have to rewrite the record rep clause as: 12695 12696@smallexample @c ada 12697 for Data use record 12698 Master_Control at 0 range 7 .. 7; 12699 Master_V1 at 0 range 6 .. 6; 12700 Master_V2 at 0 range 5 .. 5; 12701 Master_V3 at 0 range 4 .. 4; 12702 Master_V4 at 0 range 3 .. 3; 12703 Master_V5 at 0 range 2 .. 2; 12704 Master_V6 at 0 range 1 .. 1; 12705 Master_V7 at 0 range 0 .. 0; 12706 Slave_Control at 1 range 7 .. 7; 12707 Slave_V1 at 1 range 6 .. 6; 12708 Slave_V2 at 1 range 5 .. 5; 12709 Slave_V3 at 1 range 4 .. 4; 12710 Slave_V4 at 1 range 3 .. 3; 12711 Slave_V5 at 1 range 2 .. 2; 12712 Slave_V6 at 1 range 1 .. 1; 12713 Slave_V7 at 1 range 0 .. 0; 12714 end record; 12715@end smallexample 12716 12717@noindent 12718It is a nuisance to have to rewrite the clause, especially if 12719the code has to be maintained on both machines. However, 12720this is a case that we can handle with the 12721@code{Bit_Order} attribute if it is implemented. 12722Note that the implementation is not required on byte addressed 12723machines, but it is indeed implemented in GNAT. 12724This means that we can simply use the 12725first record clause, together with the declaration 12726 12727@smallexample @c ada 12728 for Data'Bit_Order use High_Order_First; 12729@end smallexample 12730 12731@noindent 12732and the effect is what is desired, namely the layout is exactly the same, 12733independent of whether the code is compiled on a big-endian or little-endian 12734machine. 12735 12736The important point to understand is that byte ordering is not affected. 12737A @code{Bit_Order} attribute definition never affects which byte a field 12738ends up in, only where it ends up in that byte. 12739To make this clear, let us rewrite the record rep clause of the previous 12740example as: 12741 12742@smallexample @c ada 12743 for Data'Bit_Order use High_Order_First; 12744 for Data use record 12745 Master_Control at 0 range 0 .. 0; 12746 Master_V1 at 0 range 1 .. 1; 12747 Master_V2 at 0 range 2 .. 2; 12748 Master_V3 at 0 range 3 .. 3; 12749 Master_V4 at 0 range 4 .. 4; 12750 Master_V5 at 0 range 5 .. 5; 12751 Master_V6 at 0 range 6 .. 6; 12752 Master_V7 at 0 range 7 .. 7; 12753 Slave_Control at 0 range 8 .. 8; 12754 Slave_V1 at 0 range 9 .. 9; 12755 Slave_V2 at 0 range 10 .. 10; 12756 Slave_V3 at 0 range 11 .. 11; 12757 Slave_V4 at 0 range 12 .. 12; 12758 Slave_V5 at 0 range 13 .. 13; 12759 Slave_V6 at 0 range 14 .. 14; 12760 Slave_V7 at 0 range 15 .. 15; 12761 end record; 12762@end smallexample 12763 12764@noindent 12765This is exactly equivalent to saying (a repeat of the first example): 12766 12767@smallexample @c ada 12768 for Data'Bit_Order use High_Order_First; 12769 for Data use record 12770 Master_Control at 0 range 0 .. 0; 12771 Master_V1 at 0 range 1 .. 1; 12772 Master_V2 at 0 range 2 .. 2; 12773 Master_V3 at 0 range 3 .. 3; 12774 Master_V4 at 0 range 4 .. 4; 12775 Master_V5 at 0 range 5 .. 5; 12776 Master_V6 at 0 range 6 .. 6; 12777 Master_V7 at 0 range 7 .. 7; 12778 Slave_Control at 1 range 0 .. 0; 12779 Slave_V1 at 1 range 1 .. 1; 12780 Slave_V2 at 1 range 2 .. 2; 12781 Slave_V3 at 1 range 3 .. 3; 12782 Slave_V4 at 1 range 4 .. 4; 12783 Slave_V5 at 1 range 5 .. 5; 12784 Slave_V6 at 1 range 6 .. 6; 12785 Slave_V7 at 1 range 7 .. 7; 12786 end record; 12787@end smallexample 12788 12789@noindent 12790Why are they equivalent? Well take a specific field, the @code{Slave_V2} 12791field. The storage place attributes are obtained by normalizing the 12792values given so that the @code{First_Bit} value is less than 8. After 12793normalizing the values (0,10,10) we get (1,2,2) which is exactly what 12794we specified in the other case. 12795 12796Now one might expect that the @code{Bit_Order} attribute might affect 12797bit numbering within the entire record component (two bytes in this 12798case, thus affecting which byte fields end up in), but that is not 12799the way this feature is defined, it only affects numbering of bits, 12800not which byte they end up in. 12801 12802Consequently it never makes sense to specify a starting bit number 12803greater than 7 (for a byte addressable field) if an attribute 12804definition for @code{Bit_Order} has been given, and indeed it 12805may be actively confusing to specify such a value, so the compiler 12806generates a warning for such usage. 12807 12808If you do need to control byte ordering then appropriate conditional 12809values must be used. If in our example, the slave byte came first on 12810some machines we might write: 12811 12812@smallexample @c ada 12813 Master_Byte_First constant Boolean := @dots{}; 12814 12815 Master_Byte : constant Natural := 12816 1 - Boolean'Pos (Master_Byte_First); 12817 Slave_Byte : constant Natural := 12818 Boolean'Pos (Master_Byte_First); 12819 12820 for Data'Bit_Order use High_Order_First; 12821 for Data use record 12822 Master_Control at Master_Byte range 0 .. 0; 12823 Master_V1 at Master_Byte range 1 .. 1; 12824 Master_V2 at Master_Byte range 2 .. 2; 12825 Master_V3 at Master_Byte range 3 .. 3; 12826 Master_V4 at Master_Byte range 4 .. 4; 12827 Master_V5 at Master_Byte range 5 .. 5; 12828 Master_V6 at Master_Byte range 6 .. 6; 12829 Master_V7 at Master_Byte range 7 .. 7; 12830 Slave_Control at Slave_Byte range 0 .. 0; 12831 Slave_V1 at Slave_Byte range 1 .. 1; 12832 Slave_V2 at Slave_Byte range 2 .. 2; 12833 Slave_V3 at Slave_Byte range 3 .. 3; 12834 Slave_V4 at Slave_Byte range 4 .. 4; 12835 Slave_V5 at Slave_Byte range 5 .. 5; 12836 Slave_V6 at Slave_Byte range 6 .. 6; 12837 Slave_V7 at Slave_Byte range 7 .. 7; 12838 end record; 12839@end smallexample 12840 12841@noindent 12842Now to switch between machines, all that is necessary is 12843to set the boolean constant @code{Master_Byte_First} in 12844an appropriate manner. 12845 12846@node Pragma Pack for Arrays 12847@section Pragma Pack for Arrays 12848@cindex Pragma Pack (for arrays) 12849 12850@noindent 12851Pragma @code{Pack} applied to an array has no effect unless the component type 12852is packable. For a component type to be packable, it must be one of the 12853following cases: 12854 12855@itemize @bullet 12856@item 12857Any scalar type 12858@item 12859Any type whose size is specified with a size clause 12860@item 12861Any packed array type with a static size 12862@item 12863Any record type padded because of its default alignment 12864@end itemize 12865 12866@noindent 12867For all these cases, if the component subtype size is in the range 128681 through 63, then the effect of the pragma @code{Pack} is exactly as though a 12869component size were specified giving the component subtype size. 12870For example if we have: 12871 12872@smallexample @c ada 12873 type r is range 0 .. 17; 12874 12875 type ar is array (1 .. 8) of r; 12876 pragma Pack (ar); 12877@end smallexample 12878 12879@noindent 12880Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size}, 12881and the size of the array @code{ar} will be exactly 40 bits. 12882 12883Note that in some cases this rather fierce approach to packing can produce 12884unexpected effects. For example, in Ada 95 and Ada 2005, 12885subtype @code{Natural} typically has a size of 31, meaning that if you 12886pack an array of @code{Natural}, you get 31-bit 12887close packing, which saves a few bits, but results in far less efficient 12888access. Since many other Ada compilers will ignore such a packing request, 12889GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses 12890might not be what is intended. You can easily remove this warning by 12891using an explicit @code{Component_Size} setting instead, which never generates 12892a warning, since the intention of the programmer is clear in this case. 12893 12894GNAT treats packed arrays in one of two ways. If the size of the array is 12895known at compile time and is less than 64 bits, then internally the array 12896is represented as a single modular type, of exactly the appropriate number 12897of bits. If the length is greater than 63 bits, or is not known at compile 12898time, then the packed array is represented as an array of bytes, and the 12899length is always a multiple of 8 bits. 12900 12901Note that to represent a packed array as a modular type, the alignment must 12902be suitable for the modular type involved. For example, on typical machines 12903a 32-bit packed array will be represented by a 32-bit modular integer with 12904an alignment of four bytes. If you explicitly override the default alignment 12905with an alignment clause that is too small, the modular representation 12906cannot be used. For example, consider the following set of declarations: 12907 12908@smallexample @c ada 12909 type R is range 1 .. 3; 12910 type S is array (1 .. 31) of R; 12911 for S'Component_Size use 2; 12912 for S'Size use 62; 12913 for S'Alignment use 1; 12914@end smallexample 12915 12916@noindent 12917If the alignment clause were not present, then a 62-bit modular 12918representation would be chosen (typically with an alignment of 4 or 8 12919bytes depending on the target). But the default alignment is overridden 12920with the explicit alignment clause. This means that the modular 12921representation cannot be used, and instead the array of bytes 12922representation must be used, meaning that the length must be a multiple 12923of 8. Thus the above set of declarations will result in a diagnostic 12924rejecting the size clause and noting that the minimum size allowed is 64. 12925 12926@cindex Pragma Pack (for type Natural) 12927@cindex Pragma Pack warning 12928 12929One special case that is worth noting occurs when the base type of the 12930component size is 8/16/32 and the subtype is one bit less. Notably this 12931occurs with subtype @code{Natural}. Consider: 12932 12933@smallexample @c ada 12934 type Arr is array (1 .. 32) of Natural; 12935 pragma Pack (Arr); 12936@end smallexample 12937 12938@noindent 12939In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 12940since typically @code{Natural'Size} is 32 in Ada 83, and in any case most 12941Ada 83 compilers did not attempt 31 bit packing. 12942 12943In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, 12944GNAT really does pack 31-bit subtype to 31 bits. This may result in a 12945substantial unintended performance penalty when porting legacy Ada 83 code. 12946To help prevent this, GNAT generates a warning in such cases. If you really 12947want 31 bit packing in a case like this, you can set the component size 12948explicitly: 12949 12950@smallexample @c ada 12951 type Arr is array (1 .. 32) of Natural; 12952 for Arr'Component_Size use 31; 12953@end smallexample 12954 12955@noindent 12956Here 31-bit packing is achieved as required, and no warning is generated, 12957since in this case the programmer intention is clear. 12958 12959@node Pragma Pack for Records 12960@section Pragma Pack for Records 12961@cindex Pragma Pack (for records) 12962 12963@noindent 12964Pragma @code{Pack} applied to a record will pack the components to reduce 12965wasted space from alignment gaps and by reducing the amount of space 12966taken by components. We distinguish between @emph{packable} components and 12967@emph{non-packable} components. 12968Components of the following types are considered packable: 12969@itemize @bullet 12970@item 12971All primitive types are packable. 12972 12973@item 12974Small packed arrays, whose size does not exceed 64 bits, and where the 12975size is statically known at compile time, are represented internally 12976as modular integers, and so they are also packable. 12977 12978@end itemize 12979 12980@noindent 12981All packable components occupy the exact number of bits corresponding to 12982their @code{Size} value, and are packed with no padding bits, i.e.@: they 12983can start on an arbitrary bit boundary. 12984 12985All other types are non-packable, they occupy an integral number of 12986storage units, and 12987are placed at a boundary corresponding to their alignment requirements. 12988 12989For example, consider the record 12990 12991@smallexample @c ada 12992 type Rb1 is array (1 .. 13) of Boolean; 12993 pragma Pack (rb1); 12994 12995 type Rb2 is array (1 .. 65) of Boolean; 12996 pragma Pack (rb2); 12997 12998 type x2 is record 12999 l1 : Boolean; 13000 l2 : Duration; 13001 l3 : Float; 13002 l4 : Boolean; 13003 l5 : Rb1; 13004 l6 : Rb2; 13005 end record; 13006 pragma Pack (x2); 13007@end smallexample 13008 13009@noindent 13010The representation for the record x2 is as follows: 13011 13012@smallexample @c ada 13013for x2'Size use 224; 13014for x2 use record 13015 l1 at 0 range 0 .. 0; 13016 l2 at 0 range 1 .. 64; 13017 l3 at 12 range 0 .. 31; 13018 l4 at 16 range 0 .. 0; 13019 l5 at 16 range 1 .. 13; 13020 l6 at 18 range 0 .. 71; 13021end record; 13022@end smallexample 13023 13024@noindent 13025Studying this example, we see that the packable fields @code{l1} 13026and @code{l2} are 13027of length equal to their sizes, and placed at specific bit boundaries (and 13028not byte boundaries) to 13029eliminate padding. But @code{l3} is of a non-packable float type, so 13030it is on the next appropriate alignment boundary. 13031 13032The next two fields are fully packable, so @code{l4} and @code{l5} are 13033minimally packed with no gaps. However, type @code{Rb2} is a packed 13034array that is longer than 64 bits, so it is itself non-packable. Thus 13035the @code{l6} field is aligned to the next byte boundary, and takes an 13036integral number of bytes, i.e.@: 72 bits. 13037 13038@node Record Representation Clauses 13039@section Record Representation Clauses 13040@cindex Record Representation Clause 13041 13042@noindent 13043Record representation clauses may be given for all record types, including 13044types obtained by record extension. Component clauses are allowed for any 13045static component. The restrictions on component clauses depend on the type 13046of the component. 13047 13048@cindex Component Clause 13049For all components of an elementary type, the only restriction on component 13050clauses is that the size must be at least the 'Size value of the type 13051(actually the Value_Size). There are no restrictions due to alignment, 13052and such components may freely cross storage boundaries. 13053 13054Packed arrays with a size up to and including 64 bits are represented 13055internally using a modular type with the appropriate number of bits, and 13056thus the same lack of restriction applies. For example, if you declare: 13057 13058@smallexample @c ada 13059 type R is array (1 .. 49) of Boolean; 13060 pragma Pack (R); 13061 for R'Size use 49; 13062@end smallexample 13063 13064@noindent 13065then a component clause for a component of type R may start on any 13066specified bit boundary, and may specify a value of 49 bits or greater. 13067 13068For packed bit arrays that are longer than 64 bits, there are two 13069cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), 13070including the important case of single bits or boolean values, then 13071there are no limitations on placement of such components, and they 13072may start and end at arbitrary bit boundaries. 13073 13074If the component size is not a power of 2 (e.g.@: 3 or 5), then 13075an array of this type longer than 64 bits must always be placed on 13076on a storage unit (byte) boundary and occupy an integral number 13077of storage units (bytes). Any component clause that does not 13078meet this requirement will be rejected. 13079 13080Any aliased component, or component of an aliased type, must 13081have its normal alignment and size. A component clause that 13082does not meet this requirement will be rejected. 13083 13084The tag field of a tagged type always occupies an address sized field at 13085the start of the record. No component clause may attempt to overlay this 13086tag. When a tagged type appears as a component, the tag field must have 13087proper alignment 13088 13089In the case of a record extension T1, of a type T, no component clause applied 13090to the type T1 can specify a storage location that would overlap the first 13091T'Size bytes of the record. 13092 13093For all other component types, including non-bit-packed arrays, 13094the component can be placed at an arbitrary bit boundary, 13095so for example, the following is permitted: 13096 13097@smallexample @c ada 13098 type R is array (1 .. 10) of Boolean; 13099 for R'Size use 80; 13100 13101 type Q is record 13102 G, H : Boolean; 13103 L, M : R; 13104 end record; 13105 13106 for Q use record 13107 G at 0 range 0 .. 0; 13108 H at 0 range 1 .. 1; 13109 L at 0 range 2 .. 81; 13110 R at 0 range 82 .. 161; 13111 end record; 13112@end smallexample 13113 13114@noindent 13115Note: the above rules apply to recent releases of GNAT 5. 13116In GNAT 3, there are more severe restrictions on larger components. 13117For non-primitive types, including packed arrays with a size greater than 1311864 bits, component clauses must respect the alignment requirement of the 13119type, in particular, always starting on a byte boundary, and the length 13120must be a multiple of the storage unit. 13121 13122@node Enumeration Clauses 13123@section Enumeration Clauses 13124 13125The only restriction on enumeration clauses is that the range of values 13126must be representable. For the signed case, if one or more of the 13127representation values are negative, all values must be in the range: 13128 13129@smallexample @c ada 13130 System.Min_Int .. System.Max_Int 13131@end smallexample 13132 13133@noindent 13134For the unsigned case, where all values are nonnegative, the values must 13135be in the range: 13136 13137@smallexample @c ada 13138 0 .. System.Max_Binary_Modulus; 13139@end smallexample 13140 13141@noindent 13142A @emph{confirming} representation clause is one in which the values range 13143from 0 in sequence, i.e.@: a clause that confirms the default representation 13144for an enumeration type. 13145Such a confirming representation 13146is permitted by these rules, and is specially recognized by the compiler so 13147that no extra overhead results from the use of such a clause. 13148 13149If an array has an index type which is an enumeration type to which an 13150enumeration clause has been applied, then the array is stored in a compact 13151manner. Consider the declarations: 13152 13153@smallexample @c ada 13154 type r is (A, B, C); 13155 for r use (A => 1, B => 5, C => 10); 13156 type t is array (r) of Character; 13157@end smallexample 13158 13159@noindent 13160The array type t corresponds to a vector with exactly three elements and 13161has a default size equal to @code{3*Character'Size}. This ensures efficient 13162use of space, but means that accesses to elements of the array will incur 13163the overhead of converting representation values to the corresponding 13164positional values, (i.e.@: the value delivered by the @code{Pos} attribute). 13165 13166@node Address Clauses 13167@section Address Clauses 13168@cindex Address Clause 13169 13170The reference manual allows a general restriction on representation clauses, 13171as found in RM 13.1(22): 13172 13173@quotation 13174An implementation need not support representation 13175items containing nonstatic expressions, except that 13176an implementation should support a representation item 13177for a given entity if each nonstatic expression in the 13178representation item is a name that statically denotes 13179a constant declared before the entity. 13180@end quotation 13181 13182@noindent 13183In practice this is applicable only to address clauses, since this is the 13184only case in which a non-static expression is permitted by the syntax. As 13185the AARM notes in sections 13.1 (22.a-22.h): 13186 13187@display 13188 22.a Reason: This is to avoid the following sort of thing: 13189 13190 22.b X : Integer := F(@dots{}); 13191 Y : Address := G(@dots{}); 13192 for X'Address use Y; 13193 13194 22.c In the above, we have to evaluate the 13195 initialization expression for X before we 13196 know where to put the result. This seems 13197 like an unreasonable implementation burden. 13198 13199 22.d The above code should instead be written 13200 like this: 13201 13202 22.e Y : constant Address := G(@dots{}); 13203 X : Integer := F(@dots{}); 13204 for X'Address use Y; 13205 13206 22.f This allows the expression ``Y'' to be safely 13207 evaluated before X is created. 13208 13209 22.g The constant could be a formal parameter of mode in. 13210 13211 22.h An implementation can support other nonstatic 13212 expressions if it wants to. Expressions of type 13213 Address are hardly ever static, but their value 13214 might be known at compile time anyway in many 13215 cases. 13216@end display 13217 13218@noindent 13219GNAT does indeed permit many additional cases of non-static expressions. In 13220particular, if the type involved is elementary there are no restrictions 13221(since in this case, holding a temporary copy of the initialization value, 13222if one is present, is inexpensive). In addition, if there is no implicit or 13223explicit initialization, then there are no restrictions. GNAT will reject 13224only the case where all three of these conditions hold: 13225 13226@itemize @bullet 13227 13228@item 13229The type of the item is non-elementary (e.g.@: a record or array). 13230 13231@item 13232There is explicit or implicit initialization required for the object. 13233Note that access values are always implicitly initialized. 13234 13235@item 13236The address value is non-static. Here GNAT is more permissive than the 13237RM, and allows the address value to be the address of a previously declared 13238stand-alone variable, as long as it does not itself have an address clause. 13239 13240@smallexample @c ada 13241 Anchor : Some_Initialized_Type; 13242 Overlay : Some_Initialized_Type; 13243 for Overlay'Address use Anchor'Address; 13244@end smallexample 13245 13246@noindent 13247However, the prefix of the address clause cannot be an array component, or 13248a component of a discriminated record. 13249 13250@end itemize 13251 13252@noindent 13253As noted above in section 22.h, address values are typically non-static. In 13254particular the To_Address function, even if applied to a literal value, is 13255a non-static function call. To avoid this minor annoyance, GNAT provides 13256the implementation defined attribute 'To_Address. The following two 13257expressions have identical values: 13258 13259@findex Attribute 13260@findex To_Address 13261@smallexample @c ada 13262 To_Address (16#1234_0000#) 13263 System'To_Address (16#1234_0000#); 13264@end smallexample 13265 13266@noindent 13267except that the second form is considered to be a static expression, and 13268thus when used as an address clause value is always permitted. 13269 13270@noindent 13271Additionally, GNAT treats as static an address clause that is an 13272unchecked_conversion of a static integer value. This simplifies the porting 13273of legacy code, and provides a portable equivalent to the GNAT attribute 13274@code{To_Address}. 13275 13276Another issue with address clauses is the interaction with alignment 13277requirements. When an address clause is given for an object, the address 13278value must be consistent with the alignment of the object (which is usually 13279the same as the alignment of the type of the object). If an address clause 13280is given that specifies an inappropriately aligned address value, then the 13281program execution is erroneous. 13282 13283Since this source of erroneous behavior can have unfortunate effects, GNAT 13284checks (at compile time if possible, generating a warning, or at execution 13285time with a run-time check) that the alignment is appropriate. If the 13286run-time check fails, then @code{Program_Error} is raised. This run-time 13287check is suppressed if range checks are suppressed, or if the special GNAT 13288check Alignment_Check is suppressed, or if 13289@code{pragma Restrictions (No_Elaboration_Code)} is in effect. 13290 13291Finally, GNAT does not permit overlaying of objects of controlled types or 13292composite types containing a controlled component. In most cases, the compiler 13293can detect an attempt at such overlays and will generate a warning at compile 13294time and a Program_Error exception at run time. 13295 13296@findex Export 13297An address clause cannot be given for an exported object. More 13298understandably the real restriction is that objects with an address 13299clause cannot be exported. This is because such variables are not 13300defined by the Ada program, so there is no external object to export. 13301 13302@findex Import 13303It is permissible to give an address clause and a pragma Import for the 13304same object. In this case, the variable is not really defined by the 13305Ada program, so there is no external symbol to be linked. The link name 13306and the external name are ignored in this case. The reason that we allow this 13307combination is that it provides a useful idiom to avoid unwanted 13308initializations on objects with address clauses. 13309 13310When an address clause is given for an object that has implicit or 13311explicit initialization, then by default initialization takes place. This 13312means that the effect of the object declaration is to overwrite the 13313memory at the specified address. This is almost always not what the 13314programmer wants, so GNAT will output a warning: 13315 13316@smallexample 13317 with System; 13318 package G is 13319 type R is record 13320 M : Integer := 0; 13321 end record; 13322 13323 Ext : R; 13324 for Ext'Address use System'To_Address (16#1234_1234#); 13325 | 13326 >>> warning: implicit initialization of "Ext" may 13327 modify overlaid storage 13328 >>> warning: use pragma Import for "Ext" to suppress 13329 initialization (RM B(24)) 13330 13331 end G; 13332@end smallexample 13333 13334@noindent 13335As indicated by the warning message, the solution is to use a (dummy) pragma 13336Import to suppress this initialization. The pragma tell the compiler that the 13337object is declared and initialized elsewhere. The following package compiles 13338without warnings (and the initialization is suppressed): 13339 13340@smallexample @c ada 13341 with System; 13342 package G is 13343 type R is record 13344 M : Integer := 0; 13345 end record; 13346 13347 Ext : R; 13348 for Ext'Address use System'To_Address (16#1234_1234#); 13349 pragma Import (Ada, Ext); 13350 end G; 13351@end smallexample 13352 13353@noindent 13354A final issue with address clauses involves their use for overlaying 13355variables, as in the following example: 13356@cindex Overlaying of objects 13357 13358@smallexample @c ada 13359 A : Integer; 13360 B : Integer; 13361 for B'Address use A'Address; 13362@end smallexample 13363 13364@noindent 13365or alternatively, using the form recommended by the RM: 13366 13367@smallexample @c ada 13368 A : Integer; 13369 Addr : constant Address := A'Address; 13370 B : Integer; 13371 for B'Address use Addr; 13372@end smallexample 13373 13374@noindent 13375In both of these cases, @code{A} 13376and @code{B} become aliased to one another via the 13377address clause. This use of address clauses to overlay 13378variables, achieving an effect similar to unchecked 13379conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005 13380the effect is implementation defined. Furthermore, the 13381Ada RM specifically recommends that in a situation 13382like this, @code{B} should be subject to the following 13383implementation advice (RM 13.3(19)): 13384 13385@quotation 1338619 If the Address of an object is specified, or it is imported 13387 or exported, then the implementation should not perform 13388 optimizations based on assumptions of no aliases. 13389@end quotation 13390 13391@noindent 13392GNAT follows this recommendation, and goes further by also applying 13393this recommendation to the overlaid variable (@code{A} 13394in the above example) in this case. This means that the overlay 13395works "as expected", in that a modification to one of the variables 13396will affect the value of the other. 13397 13398@node Effect of Convention on Representation 13399@section Effect of Convention on Representation 13400@cindex Convention, effect on representation 13401 13402@noindent 13403Normally the specification of a foreign language convention for a type or 13404an object has no effect on the chosen representation. In particular, the 13405representation chosen for data in GNAT generally meets the standard system 13406conventions, and for example records are laid out in a manner that is 13407consistent with C@. This means that specifying convention C (for example) 13408has no effect. 13409 13410There are four exceptions to this general rule: 13411 13412@itemize @bullet 13413 13414@item Convention Fortran and array subtypes 13415If pragma Convention Fortran is specified for an array subtype, then in 13416accordance with the implementation advice in section 3.6.2(11) of the 13417Ada Reference Manual, the array will be stored in a Fortran-compatible 13418column-major manner, instead of the normal default row-major order. 13419 13420@item Convention C and enumeration types 13421GNAT normally stores enumeration types in 8, 16, or 32 bits as required 13422to accommodate all values of the type. For example, for the enumeration 13423type declared by: 13424 13425@smallexample @c ada 13426 type Color is (Red, Green, Blue); 13427@end smallexample 13428 13429@noindent 134308 bits is sufficient to store all values of the type, so by default, objects 13431of type @code{Color} will be represented using 8 bits. However, normal C 13432convention is to use 32 bits for all enum values in C, since enum values 13433are essentially of type int. If pragma @code{Convention C} is specified for an 13434Ada enumeration type, then the size is modified as necessary (usually to 1343532 bits) to be consistent with the C convention for enum values. 13436 13437Note that this treatment applies only to types. If Convention C is given for 13438an enumeration object, where the enumeration type is not Convention C, then 13439Object_Size bits are allocated. For example, for a normal enumeration type, 13440with less than 256 elements, only 8 bits will be allocated for the object. 13441Since this may be a surprise in terms of what C expects, GNAT will issue a 13442warning in this situation. The warning can be suppressed by giving an explicit 13443size clause specifying the desired size. 13444 13445@item Convention C/Fortran and Boolean types 13446In C, the usual convention for boolean values, that is values used for 13447conditions, is that zero represents false, and nonzero values represent 13448true. In Ada, the normal convention is that two specific values, typically 134490/1, are used to represent false/true respectively. 13450 13451Fortran has a similar convention for @code{LOGICAL} values (any nonzero 13452value represents true). 13453 13454To accommodate the Fortran and C conventions, if a pragma Convention specifies 13455C or Fortran convention for a derived Boolean, as in the following example: 13456 13457@smallexample @c ada 13458 type C_Switch is new Boolean; 13459 pragma Convention (C, C_Switch); 13460@end smallexample 13461 13462@noindent 13463then the GNAT generated code will treat any nonzero value as true. For truth 13464values generated by GNAT, the conventional value 1 will be used for True, but 13465when one of these values is read, any nonzero value is treated as True. 13466 13467@item Access types on OpenVMS 13468For 64-bit OpenVMS systems, access types (other than those for unconstrained 13469arrays) are 64-bits long. An exception to this rule is for the case of 13470C-convention access types where there is no explicit size clause present (or 13471inherited for derived types). In this case, GNAT chooses to make these 13472pointers 32-bits, which provides an easier path for migration of 32-bit legacy 13473code. size clause specifying 64-bits must be used to obtain a 64-bit pointer. 13474 13475@end itemize 13476 13477@node Determining the Representations chosen by GNAT 13478@section Determining the Representations chosen by GNAT 13479@cindex Representation, determination of 13480@cindex @option{-gnatR} switch 13481 13482@noindent 13483Although the descriptions in this section are intended to be complete, it is 13484often easier to simply experiment to see what GNAT accepts and what the 13485effect is on the layout of types and objects. 13486 13487As required by the Ada RM, if a representation clause is not accepted, then 13488it must be rejected as illegal by the compiler. However, when a 13489representation clause or pragma is accepted, there can still be questions 13490of what the compiler actually does. For example, if a partial record 13491representation clause specifies the location of some components and not 13492others, then where are the non-specified components placed? Or if pragma 13493@code{Pack} is used on a record, then exactly where are the resulting 13494fields placed? The section on pragma @code{Pack} in this chapter can be 13495used to answer the second question, but it is often easier to just see 13496what the compiler does. 13497 13498For this purpose, GNAT provides the option @option{-gnatR}. If you compile 13499with this option, then the compiler will output information on the actual 13500representations chosen, in a format similar to source representation 13501clauses. For example, if we compile the package: 13502 13503@smallexample @c ada 13504package q is 13505 type r (x : boolean) is tagged record 13506 case x is 13507 when True => S : String (1 .. 100); 13508 when False => null; 13509 end case; 13510 end record; 13511 13512 type r2 is new r (false) with record 13513 y2 : integer; 13514 end record; 13515 13516 for r2 use record 13517 y2 at 16 range 0 .. 31; 13518 end record; 13519 13520 type x is record 13521 y : character; 13522 end record; 13523 13524 type x1 is array (1 .. 10) of x; 13525 for x1'component_size use 11; 13526 13527 type ia is access integer; 13528 13529 type Rb1 is array (1 .. 13) of Boolean; 13530 pragma Pack (rb1); 13531 13532 type Rb2 is array (1 .. 65) of Boolean; 13533 pragma Pack (rb2); 13534 13535 type x2 is record 13536 l1 : Boolean; 13537 l2 : Duration; 13538 l3 : Float; 13539 l4 : Boolean; 13540 l5 : Rb1; 13541 l6 : Rb2; 13542 end record; 13543 pragma Pack (x2); 13544end q; 13545@end smallexample 13546 13547@noindent 13548using the switch @option{-gnatR} we obtain the following output: 13549 13550@smallexample 13551Representation information for unit q 13552------------------------------------- 13553 13554for r'Size use ??; 13555for r'Alignment use 4; 13556for r use record 13557 x at 4 range 0 .. 7; 13558 _tag at 0 range 0 .. 31; 13559 s at 5 range 0 .. 799; 13560end record; 13561 13562for r2'Size use 160; 13563for r2'Alignment use 4; 13564for r2 use record 13565 x at 4 range 0 .. 7; 13566 _tag at 0 range 0 .. 31; 13567 _parent at 0 range 0 .. 63; 13568 y2 at 16 range 0 .. 31; 13569end record; 13570 13571for x'Size use 8; 13572for x'Alignment use 1; 13573for x use record 13574 y at 0 range 0 .. 7; 13575end record; 13576 13577for x1'Size use 112; 13578for x1'Alignment use 1; 13579for x1'Component_Size use 11; 13580 13581for rb1'Size use 13; 13582for rb1'Alignment use 2; 13583for rb1'Component_Size use 1; 13584 13585for rb2'Size use 72; 13586for rb2'Alignment use 1; 13587for rb2'Component_Size use 1; 13588 13589for x2'Size use 224; 13590for x2'Alignment use 4; 13591for x2 use record 13592 l1 at 0 range 0 .. 0; 13593 l2 at 0 range 1 .. 64; 13594 l3 at 12 range 0 .. 31; 13595 l4 at 16 range 0 .. 0; 13596 l5 at 16 range 1 .. 13; 13597 l6 at 18 range 0 .. 71; 13598end record; 13599@end smallexample 13600 13601@noindent 13602The Size values are actually the Object_Size, i.e.@: the default size that 13603will be allocated for objects of the type. 13604The ?? size for type r indicates that we have a variant record, and the 13605actual size of objects will depend on the discriminant value. 13606 13607The Alignment values show the actual alignment chosen by the compiler 13608for each record or array type. 13609 13610The record representation clause for type r shows where all fields 13611are placed, including the compiler generated tag field (whose location 13612cannot be controlled by the programmer). 13613 13614The record representation clause for the type extension r2 shows all the 13615fields present, including the parent field, which is a copy of the fields 13616of the parent type of r2, i.e.@: r1. 13617 13618The component size and size clauses for types rb1 and rb2 show 13619the exact effect of pragma @code{Pack} on these arrays, and the record 13620representation clause for type x2 shows how pragma @code{Pack} affects 13621this record type. 13622 13623In some cases, it may be useful to cut and paste the representation clauses 13624generated by the compiler into the original source to fix and guarantee 13625the actual representation to be used. 13626 13627@node Standard Library Routines 13628@chapter Standard Library Routines 13629 13630@noindent 13631The Ada Reference Manual contains in Annex A a full description of an 13632extensive set of standard library routines that can be used in any Ada 13633program, and which must be provided by all Ada compilers. They are 13634analogous to the standard C library used by C programs. 13635 13636GNAT implements all of the facilities described in annex A, and for most 13637purposes the description in the Ada Reference Manual, or appropriate Ada 13638text book, will be sufficient for making use of these facilities. 13639 13640In the case of the input-output facilities, 13641@xref{The Implementation of Standard I/O}, 13642gives details on exactly how GNAT interfaces to the 13643file system. For the remaining packages, the Ada Reference Manual 13644should be sufficient. The following is a list of the packages included, 13645together with a brief description of the functionality that is provided. 13646 13647For completeness, references are included to other predefined library 13648routines defined in other sections of the Ada Reference Manual (these are 13649cross-indexed from Annex A). 13650 13651@table @code 13652@item Ada (A.2) 13653This is a parent package for all the standard library packages. It is 13654usually included implicitly in your program, and itself contains no 13655useful data or routines. 13656 13657@item Ada.Calendar (9.6) 13658@code{Calendar} provides time of day access, and routines for 13659manipulating times and durations. 13660 13661@item Ada.Characters (A.3.1) 13662This is a dummy parent package that contains no useful entities 13663 13664@item Ada.Characters.Handling (A.3.2) 13665This package provides some basic character handling capabilities, 13666including classification functions for classes of characters (e.g.@: test 13667for letters, or digits). 13668 13669@item Ada.Characters.Latin_1 (A.3.3) 13670This package includes a complete set of definitions of the characters 13671that appear in type CHARACTER@. It is useful for writing programs that 13672will run in international environments. For example, if you want an 13673upper case E with an acute accent in a string, it is often better to use 13674the definition of @code{UC_E_Acute} in this package. Then your program 13675will print in an understandable manner even if your environment does not 13676support these extended characters. 13677 13678@item Ada.Command_Line (A.15) 13679This package provides access to the command line parameters and the name 13680of the current program (analogous to the use of @code{argc} and @code{argv} 13681in C), and also allows the exit status for the program to be set in a 13682system-independent manner. 13683 13684@item Ada.Decimal (F.2) 13685This package provides constants describing the range of decimal numbers 13686implemented, and also a decimal divide routine (analogous to the COBOL 13687verb DIVIDE @dots{} GIVING @dots{} REMAINDER @dots{}) 13688 13689@item Ada.Direct_IO (A.8.4) 13690This package provides input-output using a model of a set of records of 13691fixed-length, containing an arbitrary definite Ada type, indexed by an 13692integer record number. 13693 13694@item Ada.Dynamic_Priorities (D.5) 13695This package allows the priorities of a task to be adjusted dynamically 13696as the task is running. 13697 13698@item Ada.Exceptions (11.4.1) 13699This package provides additional information on exceptions, and also 13700contains facilities for treating exceptions as data objects, and raising 13701exceptions with associated messages. 13702 13703@item Ada.Finalization (7.6) 13704This package contains the declarations and subprograms to support the 13705use of controlled types, providing for automatic initialization and 13706finalization (analogous to the constructors and destructors of C++) 13707 13708@item Ada.Interrupts (C.3.2) 13709This package provides facilities for interfacing to interrupts, which 13710includes the set of signals or conditions that can be raised and 13711recognized as interrupts. 13712 13713@item Ada.Interrupts.Names (C.3.2) 13714This package provides the set of interrupt names (actually signal 13715or condition names) that can be handled by GNAT@. 13716 13717@item Ada.IO_Exceptions (A.13) 13718This package defines the set of exceptions that can be raised by use of 13719the standard IO packages. 13720 13721@item Ada.Numerics 13722This package contains some standard constants and exceptions used 13723throughout the numerics packages. Note that the constants pi and e are 13724defined here, and it is better to use these definitions than rolling 13725your own. 13726 13727@item Ada.Numerics.Complex_Elementary_Functions 13728Provides the implementation of standard elementary functions (such as 13729log and trigonometric functions) operating on complex numbers using the 13730standard @code{Float} and the @code{Complex} and @code{Imaginary} types 13731created by the package @code{Numerics.Complex_Types}. 13732 13733@item Ada.Numerics.Complex_Types 13734This is a predefined instantiation of 13735@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to 13736build the type @code{Complex} and @code{Imaginary}. 13737 13738@item Ada.Numerics.Discrete_Random 13739This generic package provides a random number generator suitable for generating 13740uniformly distributed values of a specified discrete subtype. 13741 13742@item Ada.Numerics.Float_Random 13743This package provides a random number generator suitable for generating 13744uniformly distributed floating point values in the unit interval. 13745 13746@item Ada.Numerics.Generic_Complex_Elementary_Functions 13747This is a generic version of the package that provides the 13748implementation of standard elementary functions (such as log and 13749trigonometric functions) for an arbitrary complex type. 13750 13751The following predefined instantiations of this package are provided: 13752 13753@table @code 13754@item Short_Float 13755@code{Ada.Numerics.Short_Complex_Elementary_Functions} 13756@item Float 13757@code{Ada.Numerics.Complex_Elementary_Functions} 13758@item Long_Float 13759@code{Ada.Numerics.Long_Complex_Elementary_Functions} 13760@end table 13761 13762@item Ada.Numerics.Generic_Complex_Types 13763This is a generic package that allows the creation of complex types, 13764with associated complex arithmetic operations. 13765 13766The following predefined instantiations of this package exist 13767@table @code 13768@item Short_Float 13769@code{Ada.Numerics.Short_Complex_Complex_Types} 13770@item Float 13771@code{Ada.Numerics.Complex_Complex_Types} 13772@item Long_Float 13773@code{Ada.Numerics.Long_Complex_Complex_Types} 13774@end table 13775 13776@item Ada.Numerics.Generic_Elementary_Functions 13777This is a generic package that provides the implementation of standard 13778elementary functions (such as log an trigonometric functions) for an 13779arbitrary float type. 13780 13781The following predefined instantiations of this package exist 13782 13783@table @code 13784@item Short_Float 13785@code{Ada.Numerics.Short_Elementary_Functions} 13786@item Float 13787@code{Ada.Numerics.Elementary_Functions} 13788@item Long_Float 13789@code{Ada.Numerics.Long_Elementary_Functions} 13790@end table 13791 13792@item Ada.Real_Time (D.8) 13793This package provides facilities similar to those of @code{Calendar}, but 13794operating with a finer clock suitable for real time control. Note that 13795annex D requires that there be no backward clock jumps, and GNAT generally 13796guarantees this behavior, but of course if the external clock on which 13797the GNAT runtime depends is deliberately reset by some external event, 13798then such a backward jump may occur. 13799 13800@item Ada.Sequential_IO (A.8.1) 13801This package provides input-output facilities for sequential files, 13802which can contain a sequence of values of a single type, which can be 13803any Ada type, including indefinite (unconstrained) types. 13804 13805@item Ada.Storage_IO (A.9) 13806This package provides a facility for mapping arbitrary Ada types to and 13807from a storage buffer. It is primarily intended for the creation of new 13808IO packages. 13809 13810@item Ada.Streams (13.13.1) 13811This is a generic package that provides the basic support for the 13812concept of streams as used by the stream attributes (@code{Input}, 13813@code{Output}, @code{Read} and @code{Write}). 13814 13815@item Ada.Streams.Stream_IO (A.12.1) 13816This package is a specialization of the type @code{Streams} defined in 13817package @code{Streams} together with a set of operations providing 13818Stream_IO capability. The Stream_IO model permits both random and 13819sequential access to a file which can contain an arbitrary set of values 13820of one or more Ada types. 13821 13822@item Ada.Strings (A.4.1) 13823This package provides some basic constants used by the string handling 13824packages. 13825 13826@item Ada.Strings.Bounded (A.4.4) 13827This package provides facilities for handling variable length 13828strings. The bounded model requires a maximum length. It is thus 13829somewhat more limited than the unbounded model, but avoids the use of 13830dynamic allocation or finalization. 13831 13832@item Ada.Strings.Fixed (A.4.3) 13833This package provides facilities for handling fixed length strings. 13834 13835@item Ada.Strings.Maps (A.4.2) 13836This package provides facilities for handling character mappings and 13837arbitrarily defined subsets of characters. For instance it is useful in 13838defining specialized translation tables. 13839 13840@item Ada.Strings.Maps.Constants (A.4.6) 13841This package provides a standard set of predefined mappings and 13842predefined character sets. For example, the standard upper to lower case 13843conversion table is found in this package. Note that upper to lower case 13844conversion is non-trivial if you want to take the entire set of 13845characters, including extended characters like E with an acute accent, 13846into account. You should use the mappings in this package (rather than 13847adding 32 yourself) to do case mappings. 13848 13849@item Ada.Strings.Unbounded (A.4.5) 13850This package provides facilities for handling variable length 13851strings. The unbounded model allows arbitrary length strings, but 13852requires the use of dynamic allocation and finalization. 13853 13854@item Ada.Strings.Wide_Bounded (A.4.7) 13855@itemx Ada.Strings.Wide_Fixed (A.4.7) 13856@itemx Ada.Strings.Wide_Maps (A.4.7) 13857@itemx Ada.Strings.Wide_Maps.Constants (A.4.7) 13858@itemx Ada.Strings.Wide_Unbounded (A.4.7) 13859These packages provide analogous capabilities to the corresponding 13860packages without @samp{Wide_} in the name, but operate with the types 13861@code{Wide_String} and @code{Wide_Character} instead of @code{String} 13862and @code{Character}. 13863 13864@item Ada.Strings.Wide_Wide_Bounded (A.4.7) 13865@itemx Ada.Strings.Wide_Wide_Fixed (A.4.7) 13866@itemx Ada.Strings.Wide_Wide_Maps (A.4.7) 13867@itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7) 13868@itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7) 13869These packages provide analogous capabilities to the corresponding 13870packages without @samp{Wide_} in the name, but operate with the types 13871@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead 13872of @code{String} and @code{Character}. 13873 13874@item Ada.Synchronous_Task_Control (D.10) 13875This package provides some standard facilities for controlling task 13876communication in a synchronous manner. 13877 13878@item Ada.Tags 13879This package contains definitions for manipulation of the tags of tagged 13880values. 13881 13882@item Ada.Task_Attributes 13883This package provides the capability of associating arbitrary 13884task-specific data with separate tasks. 13885 13886@item Ada.Text_IO 13887This package provides basic text input-output capabilities for 13888character, string and numeric data. The subpackages of this 13889package are listed next. 13890 13891@item Ada.Text_IO.Decimal_IO 13892Provides input-output facilities for decimal fixed-point types 13893 13894@item Ada.Text_IO.Enumeration_IO 13895Provides input-output facilities for enumeration types. 13896 13897@item Ada.Text_IO.Fixed_IO 13898Provides input-output facilities for ordinary fixed-point types. 13899 13900@item Ada.Text_IO.Float_IO 13901Provides input-output facilities for float types. The following 13902predefined instantiations of this generic package are available: 13903 13904@table @code 13905@item Short_Float 13906@code{Short_Float_Text_IO} 13907@item Float 13908@code{Float_Text_IO} 13909@item Long_Float 13910@code{Long_Float_Text_IO} 13911@end table 13912 13913@item Ada.Text_IO.Integer_IO 13914Provides input-output facilities for integer types. The following 13915predefined instantiations of this generic package are available: 13916 13917@table @code 13918@item Short_Short_Integer 13919@code{Ada.Short_Short_Integer_Text_IO} 13920@item Short_Integer 13921@code{Ada.Short_Integer_Text_IO} 13922@item Integer 13923@code{Ada.Integer_Text_IO} 13924@item Long_Integer 13925@code{Ada.Long_Integer_Text_IO} 13926@item Long_Long_Integer 13927@code{Ada.Long_Long_Integer_Text_IO} 13928@end table 13929 13930@item Ada.Text_IO.Modular_IO 13931Provides input-output facilities for modular (unsigned) types 13932 13933@item Ada.Text_IO.Complex_IO (G.1.3) 13934This package provides basic text input-output capabilities for complex 13935data. 13936 13937@item Ada.Text_IO.Editing (F.3.3) 13938This package contains routines for edited output, analogous to the use 13939of pictures in COBOL@. The picture formats used by this package are a 13940close copy of the facility in COBOL@. 13941 13942@item Ada.Text_IO.Text_Streams (A.12.2) 13943This package provides a facility that allows Text_IO files to be treated 13944as streams, so that the stream attributes can be used for writing 13945arbitrary data, including binary data, to Text_IO files. 13946 13947@item Ada.Unchecked_Conversion (13.9) 13948This generic package allows arbitrary conversion from one type to 13949another of the same size, providing for breaking the type safety in 13950special circumstances. 13951 13952If the types have the same Size (more accurately the same Value_Size), 13953then the effect is simply to transfer the bits from the source to the 13954target type without any modification. This usage is well defined, and 13955for simple types whose representation is typically the same across 13956all implementations, gives a portable method of performing such 13957conversions. 13958 13959If the types do not have the same size, then the result is implementation 13960defined, and thus may be non-portable. The following describes how GNAT 13961handles such unchecked conversion cases. 13962 13963If the types are of different sizes, and are both discrete types, then 13964the effect is of a normal type conversion without any constraint checking. 13965In particular if the result type has a larger size, the result will be 13966zero or sign extended. If the result type has a smaller size, the result 13967will be truncated by ignoring high order bits. 13968 13969If the types are of different sizes, and are not both discrete types, 13970then the conversion works as though pointers were created to the source 13971and target, and the pointer value is converted. The effect is that bits 13972are copied from successive low order storage units and bits of the source 13973up to the length of the target type. 13974 13975A warning is issued if the lengths differ, since the effect in this 13976case is implementation dependent, and the above behavior may not match 13977that of some other compiler. 13978 13979A pointer to one type may be converted to a pointer to another type using 13980unchecked conversion. The only case in which the effect is undefined is 13981when one or both pointers are pointers to unconstrained array types. In 13982this case, the bounds information may get incorrectly transferred, and in 13983particular, GNAT uses double size pointers for such types, and it is 13984meaningless to convert between such pointer types. GNAT will issue a 13985warning if the alignment of the target designated type is more strict 13986than the alignment of the source designated type (since the result may 13987be unaligned in this case). 13988 13989A pointer other than a pointer to an unconstrained array type may be 13990converted to and from System.Address. Such usage is common in Ada 83 13991programs, but note that Ada.Address_To_Access_Conversions is the 13992preferred method of performing such conversions in Ada 95 and Ada 2005. 13993Neither 13994unchecked conversion nor Ada.Address_To_Access_Conversions should be 13995used in conjunction with pointers to unconstrained objects, since 13996the bounds information cannot be handled correctly in this case. 13997 13998@item Ada.Unchecked_Deallocation (13.11.2) 13999This generic package allows explicit freeing of storage previously 14000allocated by use of an allocator. 14001 14002@item Ada.Wide_Text_IO (A.11) 14003This package is similar to @code{Ada.Text_IO}, except that the external 14004file supports wide character representations, and the internal types are 14005@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 14006and @code{String}. It contains generic subpackages listed next. 14007 14008@item Ada.Wide_Text_IO.Decimal_IO 14009Provides input-output facilities for decimal fixed-point types 14010 14011@item Ada.Wide_Text_IO.Enumeration_IO 14012Provides input-output facilities for enumeration types. 14013 14014@item Ada.Wide_Text_IO.Fixed_IO 14015Provides input-output facilities for ordinary fixed-point types. 14016 14017@item Ada.Wide_Text_IO.Float_IO 14018Provides input-output facilities for float types. The following 14019predefined instantiations of this generic package are available: 14020 14021@table @code 14022@item Short_Float 14023@code{Short_Float_Wide_Text_IO} 14024@item Float 14025@code{Float_Wide_Text_IO} 14026@item Long_Float 14027@code{Long_Float_Wide_Text_IO} 14028@end table 14029 14030@item Ada.Wide_Text_IO.Integer_IO 14031Provides input-output facilities for integer types. The following 14032predefined instantiations of this generic package are available: 14033 14034@table @code 14035@item Short_Short_Integer 14036@code{Ada.Short_Short_Integer_Wide_Text_IO} 14037@item Short_Integer 14038@code{Ada.Short_Integer_Wide_Text_IO} 14039@item Integer 14040@code{Ada.Integer_Wide_Text_IO} 14041@item Long_Integer 14042@code{Ada.Long_Integer_Wide_Text_IO} 14043@item Long_Long_Integer 14044@code{Ada.Long_Long_Integer_Wide_Text_IO} 14045@end table 14046 14047@item Ada.Wide_Text_IO.Modular_IO 14048Provides input-output facilities for modular (unsigned) types 14049 14050@item Ada.Wide_Text_IO.Complex_IO (G.1.3) 14051This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the 14052external file supports wide character representations. 14053 14054@item Ada.Wide_Text_IO.Editing (F.3.4) 14055This package is similar to @code{Ada.Text_IO.Editing}, except that the 14056types are @code{Wide_Character} and @code{Wide_String} instead of 14057@code{Character} and @code{String}. 14058 14059@item Ada.Wide_Text_IO.Streams (A.12.3) 14060This package is similar to @code{Ada.Text_IO.Streams}, except that the 14061types are @code{Wide_Character} and @code{Wide_String} instead of 14062@code{Character} and @code{String}. 14063 14064@item Ada.Wide_Wide_Text_IO (A.11) 14065This package is similar to @code{Ada.Text_IO}, except that the external 14066file supports wide character representations, and the internal types are 14067@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 14068and @code{String}. It contains generic subpackages listed next. 14069 14070@item Ada.Wide_Wide_Text_IO.Decimal_IO 14071Provides input-output facilities for decimal fixed-point types 14072 14073@item Ada.Wide_Wide_Text_IO.Enumeration_IO 14074Provides input-output facilities for enumeration types. 14075 14076@item Ada.Wide_Wide_Text_IO.Fixed_IO 14077Provides input-output facilities for ordinary fixed-point types. 14078 14079@item Ada.Wide_Wide_Text_IO.Float_IO 14080Provides input-output facilities for float types. The following 14081predefined instantiations of this generic package are available: 14082 14083@table @code 14084@item Short_Float 14085@code{Short_Float_Wide_Wide_Text_IO} 14086@item Float 14087@code{Float_Wide_Wide_Text_IO} 14088@item Long_Float 14089@code{Long_Float_Wide_Wide_Text_IO} 14090@end table 14091 14092@item Ada.Wide_Wide_Text_IO.Integer_IO 14093Provides input-output facilities for integer types. The following 14094predefined instantiations of this generic package are available: 14095 14096@table @code 14097@item Short_Short_Integer 14098@code{Ada.Short_Short_Integer_Wide_Wide_Text_IO} 14099@item Short_Integer 14100@code{Ada.Short_Integer_Wide_Wide_Text_IO} 14101@item Integer 14102@code{Ada.Integer_Wide_Wide_Text_IO} 14103@item Long_Integer 14104@code{Ada.Long_Integer_Wide_Wide_Text_IO} 14105@item Long_Long_Integer 14106@code{Ada.Long_Long_Integer_Wide_Wide_Text_IO} 14107@end table 14108 14109@item Ada.Wide_Wide_Text_IO.Modular_IO 14110Provides input-output facilities for modular (unsigned) types 14111 14112@item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3) 14113This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the 14114external file supports wide character representations. 14115 14116@item Ada.Wide_Wide_Text_IO.Editing (F.3.4) 14117This package is similar to @code{Ada.Text_IO.Editing}, except that the 14118types are @code{Wide_Character} and @code{Wide_String} instead of 14119@code{Character} and @code{String}. 14120 14121@item Ada.Wide_Wide_Text_IO.Streams (A.12.3) 14122This package is similar to @code{Ada.Text_IO.Streams}, except that the 14123types are @code{Wide_Character} and @code{Wide_String} instead of 14124@code{Character} and @code{String}. 14125@end table 14126 14127@node The Implementation of Standard I/O 14128@chapter The Implementation of Standard I/O 14129 14130@noindent 14131GNAT implements all the required input-output facilities described in 14132A.6 through A.14. These sections of the Ada Reference Manual describe the 14133required behavior of these packages from the Ada point of view, and if 14134you are writing a portable Ada program that does not need to know the 14135exact manner in which Ada maps to the outside world when it comes to 14136reading or writing external files, then you do not need to read this 14137chapter. As long as your files are all regular files (not pipes or 14138devices), and as long as you write and read the files only from Ada, the 14139description in the Ada Reference Manual is sufficient. 14140 14141However, if you want to do input-output to pipes or other devices, such 14142as the keyboard or screen, or if the files you are dealing with are 14143either generated by some other language, or to be read by some other 14144language, then you need to know more about the details of how the GNAT 14145implementation of these input-output facilities behaves. 14146 14147In this chapter we give a detailed description of exactly how GNAT 14148interfaces to the file system. As always, the sources of the system are 14149available to you for answering questions at an even more detailed level, 14150but for most purposes the information in this chapter will suffice. 14151 14152Another reason that you may need to know more about how input-output is 14153implemented arises when you have a program written in mixed languages 14154where, for example, files are shared between the C and Ada sections of 14155the same program. GNAT provides some additional facilities, in the form 14156of additional child library packages, that facilitate this sharing, and 14157these additional facilities are also described in this chapter. 14158 14159@menu 14160* Standard I/O Packages:: 14161* FORM Strings:: 14162* Direct_IO:: 14163* Sequential_IO:: 14164* Text_IO:: 14165* Wide_Text_IO:: 14166* Wide_Wide_Text_IO:: 14167* Stream_IO:: 14168* Text Translation:: 14169* Shared Files:: 14170* Filenames encoding:: 14171* Open Modes:: 14172* Operations on C Streams:: 14173* Interfacing to C Streams:: 14174@end menu 14175 14176@node Standard I/O Packages 14177@section Standard I/O Packages 14178 14179@noindent 14180The Standard I/O packages described in Annex A for 14181 14182@itemize @bullet 14183@item 14184Ada.Text_IO 14185@item 14186Ada.Text_IO.Complex_IO 14187@item 14188Ada.Text_IO.Text_Streams 14189@item 14190Ada.Wide_Text_IO 14191@item 14192Ada.Wide_Text_IO.Complex_IO 14193@item 14194Ada.Wide_Text_IO.Text_Streams 14195@item 14196Ada.Wide_Wide_Text_IO 14197@item 14198Ada.Wide_Wide_Text_IO.Complex_IO 14199@item 14200Ada.Wide_Wide_Text_IO.Text_Streams 14201@item 14202Ada.Stream_IO 14203@item 14204Ada.Sequential_IO 14205@item 14206Ada.Direct_IO 14207@end itemize 14208 14209@noindent 14210are implemented using the C 14211library streams facility; where 14212 14213@itemize @bullet 14214@item 14215All files are opened using @code{fopen}. 14216@item 14217All input/output operations use @code{fread}/@code{fwrite}. 14218@end itemize 14219 14220@noindent 14221There is no internal buffering of any kind at the Ada library level. The only 14222buffering is that provided at the system level in the implementation of the 14223library routines that support streams. This facilitates shared use of these 14224streams by mixed language programs. Note though that system level buffering is 14225explicitly enabled at elaboration of the standard I/O packages and that can 14226have an impact on mixed language programs, in particular those using I/O before 14227calling the Ada elaboration routine (e.g.@: adainit). It is recommended to call 14228the Ada elaboration routine before performing any I/O or when impractical, 14229flush the common I/O streams and in particular Standard_Output before 14230elaborating the Ada code. 14231 14232@node FORM Strings 14233@section FORM Strings 14234 14235@noindent 14236The format of a FORM string in GNAT is: 14237 14238@smallexample 14239"keyword=value,keyword=value,@dots{},keyword=value" 14240@end smallexample 14241 14242@noindent 14243where letters may be in upper or lower case, and there are no spaces 14244between values. The order of the entries is not important. Currently 14245the following keywords defined. 14246 14247@smallexample 14248TEXT_TRANSLATION=[YES|NO] 14249SHARED=[YES|NO] 14250WCEM=[n|h|u|s|e|8|b] 14251ENCODING=[UTF8|8BITS] 14252@end smallexample 14253 14254@noindent 14255The use of these parameters is described later in this section. If an 14256unrecognized keyword appears in a form string, it is silently ignored 14257and not considered invalid. 14258 14259@node Direct_IO 14260@section Direct_IO 14261 14262@noindent 14263Direct_IO can only be instantiated for definite types. This is a 14264restriction of the Ada language, which means that the records are fixed 14265length (the length being determined by @code{@var{type}'Size}, rounded 14266up to the next storage unit boundary if necessary). 14267 14268The records of a Direct_IO file are simply written to the file in index 14269sequence, with the first record starting at offset zero, and subsequent 14270records following. There is no control information of any kind. For 14271example, if 32-bit integers are being written, each record takes 142724-bytes, so the record at index @var{K} starts at offset 14273(@var{K}@minus{}1)*4. 14274 14275There is no limit on the size of Direct_IO files, they are expanded as 14276necessary to accommodate whatever records are written to the file. 14277 14278@node Sequential_IO 14279@section Sequential_IO 14280 14281@noindent 14282Sequential_IO may be instantiated with either a definite (constrained) 14283or indefinite (unconstrained) type. 14284 14285For the definite type case, the elements written to the file are simply 14286the memory images of the data values with no control information of any 14287kind. The resulting file should be read using the same type, no validity 14288checking is performed on input. 14289 14290For the indefinite type case, the elements written consist of two 14291parts. First is the size of the data item, written as the memory image 14292of a @code{Interfaces.C.size_t} value, followed by the memory image of 14293the data value. The resulting file can only be read using the same 14294(unconstrained) type. Normal assignment checks are performed on these 14295read operations, and if these checks fail, @code{Data_Error} is 14296raised. In particular, in the array case, the lengths must match, and in 14297the variant record case, if the variable for a particular read operation 14298is constrained, the discriminants must match. 14299 14300Note that it is not possible to use Sequential_IO to write variable 14301length array items, and then read the data back into different length 14302arrays. For example, the following will raise @code{Data_Error}: 14303 14304@smallexample @c ada 14305 package IO is new Sequential_IO (String); 14306 F : IO.File_Type; 14307 S : String (1..4); 14308 @dots{} 14309 IO.Create (F) 14310 IO.Write (F, "hello!") 14311 IO.Reset (F, Mode=>In_File); 14312 IO.Read (F, S); 14313 Put_Line (S); 14314 14315@end smallexample 14316 14317@noindent 14318On some Ada implementations, this will print @code{hell}, but the program is 14319clearly incorrect, since there is only one element in the file, and that 14320element is the string @code{hello!}. 14321 14322In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved 14323using Stream_IO, and this is the preferred mechanism. In particular, the 14324above program fragment rewritten to use Stream_IO will work correctly. 14325 14326@node Text_IO 14327@section Text_IO 14328 14329@noindent 14330Text_IO files consist of a stream of characters containing the following 14331special control characters: 14332 14333@smallexample 14334LF (line feed, 16#0A#) Line Mark 14335FF (form feed, 16#0C#) Page Mark 14336@end smallexample 14337 14338@noindent 14339A canonical Text_IO file is defined as one in which the following 14340conditions are met: 14341 14342@itemize @bullet 14343@item 14344The character @code{LF} is used only as a line mark, i.e.@: to mark the end 14345of the line. 14346 14347@item 14348The character @code{FF} is used only as a page mark, i.e.@: to mark the 14349end of a page and consequently can appear only immediately following a 14350@code{LF} (line mark) character. 14351 14352@item 14353The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF} 14354(line mark, page mark). In the former case, the page mark is implicitly 14355assumed to be present. 14356@end itemize 14357 14358@noindent 14359A file written using Text_IO will be in canonical form provided that no 14360explicit @code{LF} or @code{FF} characters are written using @code{Put} 14361or @code{Put_Line}. There will be no @code{FF} character at the end of 14362the file unless an explicit @code{New_Page} operation was performed 14363before closing the file. 14364 14365A canonical Text_IO file that is a regular file (i.e., not a device or a 14366pipe) can be read using any of the routines in Text_IO@. The 14367semantics in this case will be exactly as defined in the Ada Reference 14368Manual, and all the routines in Text_IO are fully implemented. 14369 14370A text file that does not meet the requirements for a canonical Text_IO 14371file has one of the following: 14372 14373@itemize @bullet 14374@item 14375The file contains @code{FF} characters not immediately following a 14376@code{LF} character. 14377 14378@item 14379The file contains @code{LF} or @code{FF} characters written by 14380@code{Put} or @code{Put_Line}, which are not logically considered to be 14381line marks or page marks. 14382 14383@item 14384The file ends in a character other than @code{LF} or @code{FF}, 14385i.e.@: there is no explicit line mark or page mark at the end of the file. 14386@end itemize 14387 14388@noindent 14389Text_IO can be used to read such non-standard text files but subprograms 14390to do with line or page numbers do not have defined meanings. In 14391particular, a @code{FF} character that does not follow a @code{LF} 14392character may or may not be treated as a page mark from the point of 14393view of page and line numbering. Every @code{LF} character is considered 14394to end a line, and there is an implied @code{LF} character at the end of 14395the file. 14396 14397@menu 14398* Text_IO Stream Pointer Positioning:: 14399* Text_IO Reading and Writing Non-Regular Files:: 14400* Get_Immediate:: 14401* Treating Text_IO Files as Streams:: 14402* Text_IO Extensions:: 14403* Text_IO Facilities for Unbounded Strings:: 14404@end menu 14405 14406@node Text_IO Stream Pointer Positioning 14407@subsection Stream Pointer Positioning 14408 14409@noindent 14410@code{Ada.Text_IO} has a definition of current position for a file that 14411is being read. No internal buffering occurs in Text_IO, and usually the 14412physical position in the stream used to implement the file corresponds 14413to this logical position defined by Text_IO@. There are two exceptions: 14414 14415@itemize @bullet 14416@item 14417After a call to @code{End_Of_Page} that returns @code{True}, the stream 14418is positioned past the @code{LF} (line mark) that precedes the page 14419mark. Text_IO maintains an internal flag so that subsequent read 14420operations properly handle the logical position which is unchanged by 14421the @code{End_Of_Page} call. 14422 14423@item 14424After a call to @code{End_Of_File} that returns @code{True}, if the 14425Text_IO file was positioned before the line mark at the end of file 14426before the call, then the logical position is unchanged, but the stream 14427is physically positioned right at the end of file (past the line mark, 14428and past a possible page mark following the line mark. Again Text_IO 14429maintains internal flags so that subsequent read operations properly 14430handle the logical position. 14431@end itemize 14432 14433@noindent 14434These discrepancies have no effect on the observable behavior of 14435Text_IO, but if a single Ada stream is shared between a C program and 14436Ada program, or shared (using @samp{shared=yes} in the form string) 14437between two Ada files, then the difference may be observable in some 14438situations. 14439 14440@node Text_IO Reading and Writing Non-Regular Files 14441@subsection Reading and Writing Non-Regular Files 14442 14443@noindent 14444A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 14445can be used for reading and writing. Writing is not affected and the 14446sequence of characters output is identical to the normal file case, but 14447for reading, the behavior of Text_IO is modified to avoid undesirable 14448look-ahead as follows: 14449 14450An input file that is not a regular file is considered to have no page 14451marks. Any @code{Ascii.FF} characters (the character normally used for a 14452page mark) appearing in the file are considered to be data 14453characters. In particular: 14454 14455@itemize @bullet 14456@item 14457@code{Get_Line} and @code{Skip_Line} do not test for a page mark 14458following a line mark. If a page mark appears, it will be treated as a 14459data character. 14460 14461@item 14462This avoids the need to wait for an extra character to be typed or 14463entered from the pipe to complete one of these operations. 14464 14465@item 14466@code{End_Of_Page} always returns @code{False} 14467 14468@item 14469@code{End_Of_File} will return @code{False} if there is a page mark at 14470the end of the file. 14471@end itemize 14472 14473@noindent 14474Output to non-regular files is the same as for regular files. Page marks 14475may be written to non-regular files using @code{New_Page}, but as noted 14476above they will not be treated as page marks on input if the output is 14477piped to another Ada program. 14478 14479Another important discrepancy when reading non-regular files is that the end 14480of file indication is not ``sticky''. If an end of file is entered, e.g.@: by 14481pressing the @key{EOT} key, 14482then end of file 14483is signaled once (i.e.@: the test @code{End_Of_File} 14484will yield @code{True}, or a read will 14485raise @code{End_Error}), but then reading can resume 14486to read data past that end of 14487file indication, until another end of file indication is entered. 14488 14489@node Get_Immediate 14490@subsection Get_Immediate 14491@cindex Get_Immediate 14492 14493@noindent 14494Get_Immediate returns the next character (including control characters) 14495from the input file. In particular, Get_Immediate will return LF or FF 14496characters used as line marks or page marks. Such operations leave the 14497file positioned past the control character, and it is thus not treated 14498as having its normal function. This means that page, line and column 14499counts after this kind of Get_Immediate call are set as though the mark 14500did not occur. In the case where a Get_Immediate leaves the file 14501positioned between the line mark and page mark (which is not normally 14502possible), it is undefined whether the FF character will be treated as a 14503page mark. 14504 14505@node Treating Text_IO Files as Streams 14506@subsection Treating Text_IO Files as Streams 14507@cindex Stream files 14508 14509@noindent 14510The package @code{Text_IO.Streams} allows a Text_IO file to be treated 14511as a stream. Data written to a Text_IO file in this stream mode is 14512binary data. If this binary data contains bytes 16#0A# (@code{LF}) or 1451316#0C# (@code{FF}), the resulting file may have non-standard 14514format. Similarly if read operations are used to read from a Text_IO 14515file treated as a stream, then @code{LF} and @code{FF} characters may be 14516skipped and the effect is similar to that described above for 14517@code{Get_Immediate}. 14518 14519@node Text_IO Extensions 14520@subsection Text_IO Extensions 14521@cindex Text_IO extensions 14522 14523@noindent 14524A package GNAT.IO_Aux in the GNAT library provides some useful extensions 14525to the standard @code{Text_IO} package: 14526 14527@itemize @bullet 14528@item function File_Exists (Name : String) return Boolean; 14529Determines if a file of the given name exists. 14530 14531@item function Get_Line return String; 14532Reads a string from the standard input file. The value returned is exactly 14533the length of the line that was read. 14534 14535@item function Get_Line (File : Ada.Text_IO.File_Type) return String; 14536Similar, except that the parameter File specifies the file from which 14537the string is to be read. 14538 14539@end itemize 14540 14541@node Text_IO Facilities for Unbounded Strings 14542@subsection Text_IO Facilities for Unbounded Strings 14543@cindex Text_IO for unbounded strings 14544@cindex Unbounded_String, Text_IO operations 14545 14546@noindent 14547The package @code{Ada.Strings.Unbounded.Text_IO} 14548in library files @code{a-suteio.ads/adb} contains some GNAT-specific 14549subprograms useful for Text_IO operations on unbounded strings: 14550 14551@itemize @bullet 14552 14553@item function Get_Line (File : File_Type) return Unbounded_String; 14554Reads a line from the specified file 14555and returns the result as an unbounded string. 14556 14557@item procedure Put (File : File_Type; U : Unbounded_String); 14558Writes the value of the given unbounded string to the specified file 14559Similar to the effect of 14560@code{Put (To_String (U))} except that an extra copy is avoided. 14561 14562@item procedure Put_Line (File : File_Type; U : Unbounded_String); 14563Writes the value of the given unbounded string to the specified file, 14564followed by a @code{New_Line}. 14565Similar to the effect of @code{Put_Line (To_String (U))} except 14566that an extra copy is avoided. 14567@end itemize 14568 14569@noindent 14570In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} 14571and is optional. If the parameter is omitted, then the standard input or 14572output file is referenced as appropriate. 14573 14574The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 14575files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended 14576@code{Wide_Text_IO} functionality for unbounded wide strings. 14577 14578The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library 14579files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended 14580@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. 14581 14582@node Wide_Text_IO 14583@section Wide_Text_IO 14584 14585@noindent 14586@code{Wide_Text_IO} is similar in most respects to Text_IO, except that 14587both input and output files may contain special sequences that represent 14588wide character values. The encoding scheme for a given file may be 14589specified using a FORM parameter: 14590 14591@smallexample 14592WCEM=@var{x} 14593@end smallexample 14594 14595@noindent 14596as part of the FORM string (WCEM = wide character encoding method), 14597where @var{x} is one of the following characters 14598 14599@table @samp 14600@item h 14601Hex ESC encoding 14602@item u 14603Upper half encoding 14604@item s 14605Shift-JIS encoding 14606@item e 14607EUC Encoding 14608@item 8 14609UTF-8 encoding 14610@item b 14611Brackets encoding 14612@end table 14613 14614@noindent 14615The encoding methods match those that 14616can be used in a source 14617program, but there is no requirement that the encoding method used for 14618the source program be the same as the encoding method used for files, 14619and different files may use different encoding methods. 14620 14621The default encoding method for the standard files, and for opened files 14622for which no WCEM parameter is given in the FORM string matches the 14623wide character encoding specified for the main program (the default 14624being brackets encoding if no coding method was specified with -gnatW). 14625 14626@table @asis 14627@item Hex Coding 14628In this encoding, a wide character is represented by a five character 14629sequence: 14630 14631@smallexample 14632ESC a b c d 14633@end smallexample 14634 14635@noindent 14636where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal 14637characters (using upper case letters) of the wide character code. For 14638example, ESC A345 is used to represent the wide character with code 1463916#A345#. This scheme is compatible with use of the full 14640@code{Wide_Character} set. 14641 14642@item Upper Half Coding 14643The wide character with encoding 16#abcd#, where the upper bit is on 14644(i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and 1464516#cd#. The second byte may never be a format control character, but is 14646not required to be in the upper half. This method can be also used for 14647shift-JIS or EUC where the internal coding matches the external coding. 14648 14649@item Shift JIS Coding 14650A wide character is represented by a two character sequence 16#ab# and 1465116#cd#, with the restrictions described for upper half encoding as 14652described above. The internal character code is the corresponding JIS 14653character according to the standard algorithm for Shift-JIS 14654conversion. Only characters defined in the JIS code set table can be 14655used with this encoding method. 14656 14657@item EUC Coding 14658A wide character is represented by a two character sequence 16#ab# and 1465916#cd#, with both characters being in the upper half. The internal 14660character code is the corresponding JIS character according to the EUC 14661encoding algorithm. Only characters defined in the JIS code set table 14662can be used with this encoding method. 14663 14664@item UTF-8 Coding 14665A wide character is represented using 14666UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 1466710646-1/Am.2. Depending on the character value, the representation 14668is a one, two, or three byte sequence: 14669 14670@smallexample 1467116#0000#-16#007f#: 2#0xxxxxxx# 1467216#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 1467316#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 14674@end smallexample 14675 14676@noindent 14677where the @var{xxx} bits correspond to the left-padded bits of the 1467816-bit character value. Note that all lower half ASCII characters 14679are represented as ASCII bytes and all upper half characters and 14680other wide characters are represented as sequences of upper-half 14681(The full UTF-8 scheme allows for encoding 31-bit characters as 146826-byte sequences, but in this implementation, all UTF-8 sequences 14683of four or more bytes length will raise a Constraint_Error, as 14684will all invalid UTF-8 sequences.) 14685 14686@item Brackets Coding 14687In this encoding, a wide character is represented by the following eight 14688character sequence: 14689 14690@smallexample 14691[ " a b c d " ] 14692@end smallexample 14693 14694@noindent 14695where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 14696characters (using uppercase letters) of the wide character code. For 14697example, @code{["A345"]} is used to represent the wide character with code 14698@code{16#A345#}. 14699This scheme is compatible with use of the full Wide_Character set. 14700On input, brackets coding can also be used for upper half characters, 14701e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation 14702is only used for wide characters with a code greater than @code{16#FF#}. 14703 14704Note that brackets coding is not normally used in the context of 14705Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as 14706a portable way of encoding source files. In the context of Wide_Text_IO 14707or Wide_Wide_Text_IO, it can only be used if the file does not contain 14708any instance of the left bracket character other than to encode wide 14709character values using the brackets encoding method. In practice it is 14710expected that some standard wide character encoding method such 14711as UTF-8 will be used for text input output. 14712 14713If brackets notation is used, then any occurrence of a left bracket 14714in the input file which is not the start of a valid wide character 14715sequence will cause Constraint_Error to be raised. It is possible to 14716encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO 14717input will interpret this as a left bracket. 14718 14719However, when a left bracket is output, it will be output as a left bracket 14720and not as ["5B"]. We make this decision because for normal use of 14721Wide_Text_IO for outputting messages, it is unpleasant to clobber left 14722brackets. For example, if we write: 14723 14724@smallexample 14725 Put_Line ("Start of output [first run]"); 14726@end smallexample 14727 14728@noindent 14729we really do not want to have the left bracket in this message clobbered so 14730that the output reads: 14731 14732@smallexample 14733 Start of output ["5B"]first run] 14734@end smallexample 14735 14736@noindent 14737In practice brackets encoding is reasonably useful for normal Put_Line use 14738since we won't get confused between left brackets and wide character 14739sequences in the output. But for input, or when files are written out 14740and read back in, it really makes better sense to use one of the standard 14741encoding methods such as UTF-8. 14742 14743@end table 14744 14745@noindent 14746For the coding schemes other than UTF-8, Hex, or Brackets encoding, 14747not all wide character 14748values can be represented. An attempt to output a character that cannot 14749be represented using the encoding scheme for the file causes 14750Constraint_Error to be raised. An invalid wide character sequence on 14751input also causes Constraint_Error to be raised. 14752 14753@menu 14754* Wide_Text_IO Stream Pointer Positioning:: 14755* Wide_Text_IO Reading and Writing Non-Regular Files:: 14756@end menu 14757 14758@node Wide_Text_IO Stream Pointer Positioning 14759@subsection Stream Pointer Positioning 14760 14761@noindent 14762@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 14763of stream pointer positioning (@pxref{Text_IO}). There is one additional 14764case: 14765 14766If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 14767normal lower ASCII set (i.e.@: a character in the range: 14768 14769@smallexample @c ada 14770Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 14771@end smallexample 14772 14773@noindent 14774then although the logical position of the file pointer is unchanged by 14775the @code{Look_Ahead} call, the stream is physically positioned past the 14776wide character sequence. Again this is to avoid the need for buffering 14777or backup, and all @code{Wide_Text_IO} routines check the internal 14778indication that this situation has occurred so that this is not visible 14779to a normal program using @code{Wide_Text_IO}. However, this discrepancy 14780can be observed if the wide text file shares a stream with another file. 14781 14782@node Wide_Text_IO Reading and Writing Non-Regular Files 14783@subsection Reading and Writing Non-Regular Files 14784 14785@noindent 14786As in the case of Text_IO, when a non-regular file is read, it is 14787assumed that the file contains no page marks (any form characters are 14788treated as data characters), and @code{End_Of_Page} always returns 14789@code{False}. Similarly, the end of file indication is not sticky, so 14790it is possible to read beyond an end of file. 14791 14792@node Wide_Wide_Text_IO 14793@section Wide_Wide_Text_IO 14794 14795@noindent 14796@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that 14797both input and output files may contain special sequences that represent 14798wide wide character values. The encoding scheme for a given file may be 14799specified using a FORM parameter: 14800 14801@smallexample 14802WCEM=@var{x} 14803@end smallexample 14804 14805@noindent 14806as part of the FORM string (WCEM = wide character encoding method), 14807where @var{x} is one of the following characters 14808 14809@table @samp 14810@item h 14811Hex ESC encoding 14812@item u 14813Upper half encoding 14814@item s 14815Shift-JIS encoding 14816@item e 14817EUC Encoding 14818@item 8 14819UTF-8 encoding 14820@item b 14821Brackets encoding 14822@end table 14823 14824@noindent 14825The encoding methods match those that 14826can be used in a source 14827program, but there is no requirement that the encoding method used for 14828the source program be the same as the encoding method used for files, 14829and different files may use different encoding methods. 14830 14831The default encoding method for the standard files, and for opened files 14832for which no WCEM parameter is given in the FORM string matches the 14833wide character encoding specified for the main program (the default 14834being brackets encoding if no coding method was specified with -gnatW). 14835 14836@table @asis 14837 14838@item UTF-8 Coding 14839A wide character is represented using 14840UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 1484110646-1/Am.2. Depending on the character value, the representation 14842is a one, two, three, or four byte sequence: 14843 14844@smallexample 1484516#000000#-16#00007f#: 2#0xxxxxxx# 1484616#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# 1484716#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 1484816#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# 14849@end smallexample 14850 14851@noindent 14852where the @var{xxx} bits correspond to the left-padded bits of the 1485321-bit character value. Note that all lower half ASCII characters 14854are represented as ASCII bytes and all upper half characters and 14855other wide characters are represented as sequences of upper-half 14856characters. 14857 14858@item Brackets Coding 14859In this encoding, a wide wide character is represented by the following eight 14860character sequence if is in wide character range 14861 14862@smallexample 14863[ " a b c d " ] 14864@end smallexample 14865 14866and by the following ten character sequence if not 14867 14868@smallexample 14869[ " a b c d e f " ] 14870@end smallexample 14871 14872@noindent 14873where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} 14874are the four or six hexadecimal 14875characters (using uppercase letters) of the wide wide character code. For 14876example, @code{["01A345"]} is used to represent the wide wide character 14877with code @code{16#01A345#}. 14878 14879This scheme is compatible with use of the full Wide_Wide_Character set. 14880On input, brackets coding can also be used for upper half characters, 14881e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation 14882is only used for wide characters with a code greater than @code{16#FF#}. 14883 14884@end table 14885 14886@noindent 14887If is also possible to use the other Wide_Character encoding methods, 14888such as Shift-JIS, but the other schemes cannot support the full range 14889of wide wide characters. 14890An attempt to output a character that cannot 14891be represented using the encoding scheme for the file causes 14892Constraint_Error to be raised. An invalid wide character sequence on 14893input also causes Constraint_Error to be raised. 14894 14895@menu 14896* Wide_Wide_Text_IO Stream Pointer Positioning:: 14897* Wide_Wide_Text_IO Reading and Writing Non-Regular Files:: 14898@end menu 14899 14900@node Wide_Wide_Text_IO Stream Pointer Positioning 14901@subsection Stream Pointer Positioning 14902 14903@noindent 14904@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 14905of stream pointer positioning (@pxref{Text_IO}). There is one additional 14906case: 14907 14908If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the 14909normal lower ASCII set (i.e.@: a character in the range: 14910 14911@smallexample @c ada 14912Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) 14913@end smallexample 14914 14915@noindent 14916then although the logical position of the file pointer is unchanged by 14917the @code{Look_Ahead} call, the stream is physically positioned past the 14918wide character sequence. Again this is to avoid the need for buffering 14919or backup, and all @code{Wide_Wide_Text_IO} routines check the internal 14920indication that this situation has occurred so that this is not visible 14921to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy 14922can be observed if the wide text file shares a stream with another file. 14923 14924@node Wide_Wide_Text_IO Reading and Writing Non-Regular Files 14925@subsection Reading and Writing Non-Regular Files 14926 14927@noindent 14928As in the case of Text_IO, when a non-regular file is read, it is 14929assumed that the file contains no page marks (any form characters are 14930treated as data characters), and @code{End_Of_Page} always returns 14931@code{False}. Similarly, the end of file indication is not sticky, so 14932it is possible to read beyond an end of file. 14933 14934@node Stream_IO 14935@section Stream_IO 14936 14937@noindent 14938A stream file is a sequence of bytes, where individual elements are 14939written to the file as described in the Ada Reference Manual. The type 14940@code{Stream_Element} is simply a byte. There are two ways to read or 14941write a stream file. 14942 14943@itemize @bullet 14944@item 14945The operations @code{Read} and @code{Write} directly read or write a 14946sequence of stream elements with no control information. 14947 14948@item 14949The stream attributes applied to a stream file transfer data in the 14950manner described for stream attributes. 14951@end itemize 14952 14953@node Text Translation 14954@section Text Translation 14955 14956@noindent 14957@samp{Text_Translation=@var{xxx}} may be used as the Form parameter 14958passed to Text_IO.Create and Text_IO.Open: 14959@samp{Text_Translation=@var{Yes}} is the default, which means to 14960translate LF to/from CR/LF on Windows systems. 14961@samp{Text_Translation=@var{No}} disables this translation; i.e. it 14962uses binary mode. For output files, @samp{Text_Translation=@var{No}} 14963may be used to create Unix-style files on 14964Windows. @samp{Text_Translation=@var{xxx}} has no effect on Unix 14965systems. 14966 14967@node Shared Files 14968@section Shared Files 14969 14970@noindent 14971Section A.14 of the Ada Reference Manual allows implementations to 14972provide a wide variety of behavior if an attempt is made to access the 14973same external file with two or more internal files. 14974 14975To provide a full range of functionality, while at the same time 14976minimizing the problems of portability caused by this implementation 14977dependence, GNAT handles file sharing as follows: 14978 14979@itemize @bullet 14980@item 14981In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt 14982to open two or more files with the same full name is considered an error 14983and is not supported. The exception @code{Use_Error} will be 14984raised. Note that a file that is not explicitly closed by the program 14985remains open until the program terminates. 14986 14987@item 14988If the form parameter @samp{shared=no} appears in the form string, the 14989file can be opened or created with its own separate stream identifier, 14990regardless of whether other files sharing the same external file are 14991opened. The exact effect depends on how the C stream routines handle 14992multiple accesses to the same external files using separate streams. 14993 14994@item 14995If the form parameter @samp{shared=yes} appears in the form string for 14996each of two or more files opened using the same full name, the same 14997stream is shared between these files, and the semantics are as described 14998in Ada Reference Manual, Section A.14. 14999@end itemize 15000 15001@noindent 15002When a program that opens multiple files with the same name is ported 15003from another Ada compiler to GNAT, the effect will be that 15004@code{Use_Error} is raised. 15005 15006The documentation of the original compiler and the documentation of the 15007program should then be examined to determine if file sharing was 15008expected, and @samp{shared=@var{xxx}} parameters added to @code{Open} 15009and @code{Create} calls as required. 15010 15011When a program is ported from GNAT to some other Ada compiler, no 15012special attention is required unless the @samp{shared=@var{xxx}} form 15013parameter is used in the program. In this case, you must examine the 15014documentation of the new compiler to see if it supports the required 15015file sharing semantics, and form strings modified appropriately. Of 15016course it may be the case that the program cannot be ported if the 15017target compiler does not support the required functionality. The best 15018approach in writing portable code is to avoid file sharing (and hence 15019the use of the @samp{shared=@var{xxx}} parameter in the form string) 15020completely. 15021 15022One common use of file sharing in Ada 83 is the use of instantiations of 15023Sequential_IO on the same file with different types, to achieve 15024heterogeneous input-output. Although this approach will work in GNAT if 15025@samp{shared=yes} is specified, it is preferable in Ada to use Stream_IO 15026for this purpose (using the stream attributes) 15027 15028@node Filenames encoding 15029@section Filenames encoding 15030 15031@noindent 15032An encoding form parameter can be used to specify the filename 15033encoding @samp{encoding=@var{xxx}}. 15034 15035@itemize @bullet 15036@item 15037If the form parameter @samp{encoding=utf8} appears in the form string, the 15038filename must be encoded in UTF-8. 15039 15040@item 15041If the form parameter @samp{encoding=8bits} appears in the form 15042string, the filename must be a standard 8bits string. 15043@end itemize 15044 15045In the absence of a @samp{encoding=@var{xxx}} form parameter, the 15046encoding is controlled by the @samp{GNAT_CODE_PAGE} environment 15047variable. And if not set @samp{utf8} is assumed. 15048 15049@table @samp 15050@item CP_ACP 15051The current system Windows ANSI code page. 15052@item CP_UTF8 15053UTF-8 encoding 15054@end table 15055 15056This encoding form parameter is only supported on the Windows 15057platform. On the other Operating Systems the run-time is supporting 15058UTF-8 natively. 15059 15060@node Open Modes 15061@section Open Modes 15062 15063@noindent 15064@code{Open} and @code{Create} calls result in a call to @code{fopen} 15065using the mode shown in the following table: 15066 15067@sp 2 15068@center @code{Open} and @code{Create} Call Modes 15069@smallexample 15070 @b{OPEN } @b{CREATE} 15071Append_File "r+" "w+" 15072In_File "r" "w+" 15073Out_File (Direct_IO) "r+" "w" 15074Out_File (all other cases) "w" "w" 15075Inout_File "r+" "w+" 15076@end smallexample 15077 15078@noindent 15079If text file translation is required, then either @samp{b} or @samp{t} 15080is added to the mode, depending on the setting of Text. Text file 15081translation refers to the mapping of CR/LF sequences in an external file 15082to LF characters internally. This mapping only occurs in DOS and 15083DOS-like systems, and is not relevant to other systems. 15084 15085A special case occurs with Stream_IO@. As shown in the above table, the 15086file is initially opened in @samp{r} or @samp{w} mode for the 15087@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation 15088subsequently requires switching from reading to writing or vice-versa, 15089then the file is reopened in @samp{r+} mode to permit the required operation. 15090 15091@node Operations on C Streams 15092@section Operations on C Streams 15093The package @code{Interfaces.C_Streams} provides an Ada program with direct 15094access to the C library functions for operations on C streams: 15095 15096@smallexample @c adanocomment 15097package Interfaces.C_Streams is 15098 -- Note: the reason we do not use the types that are in 15099 -- Interfaces.C is that we want to avoid dragging in the 15100 -- code in this unit if possible. 15101 subtype chars is System.Address; 15102 -- Pointer to null-terminated array of characters 15103 subtype FILEs is System.Address; 15104 -- Corresponds to the C type FILE* 15105 subtype voids is System.Address; 15106 -- Corresponds to the C type void* 15107 subtype int is Integer; 15108 subtype long is Long_Integer; 15109 -- Note: the above types are subtypes deliberately, and it 15110 -- is part of this spec that the above correspondences are 15111 -- guaranteed. This means that it is legitimate to, for 15112 -- example, use Integer instead of int. We provide these 15113 -- synonyms for clarity, but in some cases it may be 15114 -- convenient to use the underlying types (for example to 15115 -- avoid an unnecessary dependency of a spec on the spec 15116 -- of this unit). 15117 type size_t is mod 2 ** Standard'Address_Size; 15118 NULL_Stream : constant FILEs; 15119 -- Value returned (NULL in C) to indicate an 15120 -- fdopen/fopen/tmpfile error 15121 ---------------------------------- 15122 -- Constants Defined in stdio.h -- 15123 ---------------------------------- 15124 EOF : constant int; 15125 -- Used by a number of routines to indicate error or 15126 -- end of file 15127 IOFBF : constant int; 15128 IOLBF : constant int; 15129 IONBF : constant int; 15130 -- Used to indicate buffering mode for setvbuf call 15131 SEEK_CUR : constant int; 15132 SEEK_END : constant int; 15133 SEEK_SET : constant int; 15134 -- Used to indicate origin for fseek call 15135 function stdin return FILEs; 15136 function stdout return FILEs; 15137 function stderr return FILEs; 15138 -- Streams associated with standard files 15139 -------------------------- 15140 -- Standard C functions -- 15141 -------------------------- 15142 -- The functions selected below are ones that are 15143 -- available in UNIX (but not necessarily in ANSI C). 15144 -- These are very thin interfaces 15145 -- which copy exactly the C headers. For more 15146 -- documentation on these functions, see the Microsoft C 15147 -- "Run-Time Library Reference" (Microsoft Press, 1990, 15148 -- ISBN 1-55615-225-6), which includes useful information 15149 -- on system compatibility. 15150 procedure clearerr (stream : FILEs); 15151 function fclose (stream : FILEs) return int; 15152 function fdopen (handle : int; mode : chars) return FILEs; 15153 function feof (stream : FILEs) return int; 15154 function ferror (stream : FILEs) return int; 15155 function fflush (stream : FILEs) return int; 15156 function fgetc (stream : FILEs) return int; 15157 function fgets (strng : chars; n : int; stream : FILEs) 15158 return chars; 15159 function fileno (stream : FILEs) return int; 15160 function fopen (filename : chars; Mode : chars) 15161 return FILEs; 15162 -- Note: to maintain target independence, use 15163 -- text_translation_required, a boolean variable defined in 15164 -- a-sysdep.c to deal with the target dependent text 15165 -- translation requirement. If this variable is set, 15166 -- then b/t should be appended to the standard mode 15167 -- argument to set the text translation mode off or on 15168 -- as required. 15169 function fputc (C : int; stream : FILEs) return int; 15170 function fputs (Strng : chars; Stream : FILEs) return int; 15171 function fread 15172 (buffer : voids; 15173 size : size_t; 15174 count : size_t; 15175 stream : FILEs) 15176 return size_t; 15177 function freopen 15178 (filename : chars; 15179 mode : chars; 15180 stream : FILEs) 15181 return FILEs; 15182 function fseek 15183 (stream : FILEs; 15184 offset : long; 15185 origin : int) 15186 return int; 15187 function ftell (stream : FILEs) return long; 15188 function fwrite 15189 (buffer : voids; 15190 size : size_t; 15191 count : size_t; 15192 stream : FILEs) 15193 return size_t; 15194 function isatty (handle : int) return int; 15195 procedure mktemp (template : chars); 15196 -- The return value (which is just a pointer to template) 15197 -- is discarded 15198 procedure rewind (stream : FILEs); 15199 function rmtmp return int; 15200 function setvbuf 15201 (stream : FILEs; 15202 buffer : chars; 15203 mode : int; 15204 size : size_t) 15205 return int; 15206 15207 function tmpfile return FILEs; 15208 function ungetc (c : int; stream : FILEs) return int; 15209 function unlink (filename : chars) return int; 15210 --------------------- 15211 -- Extra functions -- 15212 --------------------- 15213 -- These functions supply slightly thicker bindings than 15214 -- those above. They are derived from functions in the 15215 -- C Run-Time Library, but may do a bit more work than 15216 -- just directly calling one of the Library functions. 15217 function is_regular_file (handle : int) return int; 15218 -- Tests if given handle is for a regular file (result 1) 15219 -- or for a non-regular file (pipe or device, result 0). 15220 --------------------------------- 15221 -- Control of Text/Binary Mode -- 15222 --------------------------------- 15223 -- If text_translation_required is true, then the following 15224 -- functions may be used to dynamically switch a file from 15225 -- binary to text mode or vice versa. These functions have 15226 -- no effect if text_translation_required is false (i.e.@: in 15227 -- normal UNIX mode). Use fileno to get a stream handle. 15228 procedure set_binary_mode (handle : int); 15229 procedure set_text_mode (handle : int); 15230 ---------------------------- 15231 -- Full Path Name support -- 15232 ---------------------------- 15233 procedure full_name (nam : chars; buffer : chars); 15234 -- Given a NUL terminated string representing a file 15235 -- name, returns in buffer a NUL terminated string 15236 -- representing the full path name for the file name. 15237 -- On systems where it is relevant the drive is also 15238 -- part of the full path name. It is the responsibility 15239 -- of the caller to pass an actual parameter for buffer 15240 -- that is big enough for any full path name. Use 15241 -- max_path_len given below as the size of buffer. 15242 max_path_len : integer; 15243 -- Maximum length of an allowable full path name on the 15244 -- system, including a terminating NUL character. 15245end Interfaces.C_Streams; 15246@end smallexample 15247 15248@node Interfacing to C Streams 15249@section Interfacing to C Streams 15250 15251@noindent 15252The packages in this section permit interfacing Ada files to C Stream 15253operations. 15254 15255@smallexample @c ada 15256 with Interfaces.C_Streams; 15257 package Ada.Sequential_IO.C_Streams is 15258 function C_Stream (F : File_Type) 15259 return Interfaces.C_Streams.FILEs; 15260 procedure Open 15261 (File : in out File_Type; 15262 Mode : in File_Mode; 15263 C_Stream : in Interfaces.C_Streams.FILEs; 15264 Form : in String := ""); 15265 end Ada.Sequential_IO.C_Streams; 15266 15267 with Interfaces.C_Streams; 15268 package Ada.Direct_IO.C_Streams is 15269 function C_Stream (F : File_Type) 15270 return Interfaces.C_Streams.FILEs; 15271 procedure Open 15272 (File : in out File_Type; 15273 Mode : in File_Mode; 15274 C_Stream : in Interfaces.C_Streams.FILEs; 15275 Form : in String := ""); 15276 end Ada.Direct_IO.C_Streams; 15277 15278 with Interfaces.C_Streams; 15279 package Ada.Text_IO.C_Streams is 15280 function C_Stream (F : File_Type) 15281 return Interfaces.C_Streams.FILEs; 15282 procedure Open 15283 (File : in out File_Type; 15284 Mode : in File_Mode; 15285 C_Stream : in Interfaces.C_Streams.FILEs; 15286 Form : in String := ""); 15287 end Ada.Text_IO.C_Streams; 15288 15289 with Interfaces.C_Streams; 15290 package Ada.Wide_Text_IO.C_Streams is 15291 function C_Stream (F : File_Type) 15292 return Interfaces.C_Streams.FILEs; 15293 procedure Open 15294 (File : in out File_Type; 15295 Mode : in File_Mode; 15296 C_Stream : in Interfaces.C_Streams.FILEs; 15297 Form : in String := ""); 15298 end Ada.Wide_Text_IO.C_Streams; 15299 15300 with Interfaces.C_Streams; 15301 package Ada.Wide_Wide_Text_IO.C_Streams is 15302 function C_Stream (F : File_Type) 15303 return Interfaces.C_Streams.FILEs; 15304 procedure Open 15305 (File : in out File_Type; 15306 Mode : in File_Mode; 15307 C_Stream : in Interfaces.C_Streams.FILEs; 15308 Form : in String := ""); 15309 end Ada.Wide_Wide_Text_IO.C_Streams; 15310 15311 with Interfaces.C_Streams; 15312 package Ada.Stream_IO.C_Streams is 15313 function C_Stream (F : File_Type) 15314 return Interfaces.C_Streams.FILEs; 15315 procedure Open 15316 (File : in out File_Type; 15317 Mode : in File_Mode; 15318 C_Stream : in Interfaces.C_Streams.FILEs; 15319 Form : in String := ""); 15320 end Ada.Stream_IO.C_Streams; 15321@end smallexample 15322 15323@noindent 15324In each of these six packages, the @code{C_Stream} function obtains the 15325@code{FILE} pointer from a currently opened Ada file. It is then 15326possible to use the @code{Interfaces.C_Streams} package to operate on 15327this stream, or the stream can be passed to a C program which can 15328operate on it directly. Of course the program is responsible for 15329ensuring that only appropriate sequences of operations are executed. 15330 15331One particular use of relevance to an Ada program is that the 15332@code{setvbuf} function can be used to control the buffering of the 15333stream used by an Ada file. In the absence of such a call the standard 15334default buffering is used. 15335 15336The @code{Open} procedures in these packages open a file giving an 15337existing C Stream instead of a file name. Typically this stream is 15338imported from a C program, allowing an Ada file to operate on an 15339existing C file. 15340 15341@node The GNAT Library 15342@chapter The GNAT Library 15343 15344@noindent 15345The GNAT library contains a number of general and special purpose packages. 15346It represents functionality that the GNAT developers have found useful, and 15347which is made available to GNAT users. The packages described here are fully 15348supported, and upwards compatibility will be maintained in future releases, 15349so you can use these facilities with the confidence that the same functionality 15350will be available in future releases. 15351 15352The chapter here simply gives a brief summary of the facilities available. 15353The full documentation is found in the spec file for the package. The full 15354sources of these library packages, including both spec and body, are provided 15355with all GNAT releases. For example, to find out the full specifications of 15356the SPITBOL pattern matching capability, including a full tutorial and 15357extensive examples, look in the @file{g-spipat.ads} file in the library. 15358 15359For each entry here, the package name (as it would appear in a @code{with} 15360clause) is given, followed by the name of the corresponding spec file in 15361parentheses. The packages are children in four hierarchies, @code{Ada}, 15362@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a 15363GNAT-specific hierarchy. 15364 15365Note that an application program should only use packages in one of these 15366four hierarchies if the package is defined in the Ada Reference Manual, 15367or is listed in this section of the GNAT Programmers Reference Manual. 15368All other units should be considered internal implementation units and 15369should not be directly @code{with}'ed by application code. The use of 15370a @code{with} statement that references one of these internal implementation 15371units makes an application potentially dependent on changes in versions 15372of GNAT, and will generate a warning message. 15373 15374@menu 15375* Ada.Characters.Latin_9 (a-chlat9.ads):: 15376* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: 15377* Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: 15378* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads):: 15379* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads):: 15380* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads):: 15381* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads):: 15382* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads):: 15383* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads):: 15384* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads):: 15385* Ada.Containers.Formal_Vectors (a-cofove.ads):: 15386* Ada.Command_Line.Environment (a-colien.ads):: 15387* Ada.Command_Line.Remove (a-colire.ads):: 15388* Ada.Command_Line.Response_File (a-clrefi.ads):: 15389* Ada.Direct_IO.C_Streams (a-diocst.ads):: 15390* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: 15391* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads):: 15392* Ada.Exceptions.Traceback (a-exctra.ads):: 15393* Ada.Sequential_IO.C_Streams (a-siocst.ads):: 15394* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: 15395* Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: 15396* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: 15397* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads):: 15398* Ada.Text_IO.C_Streams (a-tiocst.ads):: 15399* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads):: 15400* Ada.Wide_Characters.Unicode (a-wichun.ads):: 15401* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: 15402* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads):: 15403* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads):: 15404* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: 15405* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads):: 15406* GNAT.Altivec (g-altive.ads):: 15407* GNAT.Altivec.Conversions (g-altcon.ads):: 15408* GNAT.Altivec.Vector_Operations (g-alveop.ads):: 15409* GNAT.Altivec.Vector_Types (g-alvety.ads):: 15410* GNAT.Altivec.Vector_Views (g-alvevi.ads):: 15411* GNAT.Array_Split (g-arrspl.ads):: 15412* GNAT.AWK (g-awk.ads):: 15413* GNAT.Bounded_Buffers (g-boubuf.ads):: 15414* GNAT.Bounded_Mailboxes (g-boumai.ads):: 15415* GNAT.Bubble_Sort (g-bubsor.ads):: 15416* GNAT.Bubble_Sort_A (g-busora.ads):: 15417* GNAT.Bubble_Sort_G (g-busorg.ads):: 15418* GNAT.Byte_Order_Mark (g-byorma.ads):: 15419* GNAT.Byte_Swapping (g-bytswa.ads):: 15420* GNAT.Calendar (g-calend.ads):: 15421* GNAT.Calendar.Time_IO (g-catiio.ads):: 15422* GNAT.Case_Util (g-casuti.ads):: 15423* GNAT.CGI (g-cgi.ads):: 15424* GNAT.CGI.Cookie (g-cgicoo.ads):: 15425* GNAT.CGI.Debug (g-cgideb.ads):: 15426* GNAT.Command_Line (g-comlin.ads):: 15427* GNAT.Compiler_Version (g-comver.ads):: 15428* GNAT.Ctrl_C (g-ctrl_c.ads):: 15429* GNAT.CRC32 (g-crc32.ads):: 15430* GNAT.Current_Exception (g-curexc.ads):: 15431* GNAT.Debug_Pools (g-debpoo.ads):: 15432* GNAT.Debug_Utilities (g-debuti.ads):: 15433* GNAT.Decode_String (g-decstr.ads):: 15434* GNAT.Decode_UTF8_String (g-deutst.ads):: 15435* GNAT.Directory_Operations (g-dirope.ads):: 15436* GNAT.Directory_Operations.Iteration (g-diopit.ads):: 15437* GNAT.Dynamic_HTables (g-dynhta.ads):: 15438* GNAT.Dynamic_Tables (g-dyntab.ads):: 15439* GNAT.Encode_String (g-encstr.ads):: 15440* GNAT.Encode_UTF8_String (g-enutst.ads):: 15441* GNAT.Exception_Actions (g-excact.ads):: 15442* GNAT.Exception_Traces (g-exctra.ads):: 15443* GNAT.Exceptions (g-except.ads):: 15444* GNAT.Expect (g-expect.ads):: 15445* GNAT.Expect.TTY (g-exptty.ads):: 15446* GNAT.Float_Control (g-flocon.ads):: 15447* GNAT.Heap_Sort (g-heasor.ads):: 15448* GNAT.Heap_Sort_A (g-hesora.ads):: 15449* GNAT.Heap_Sort_G (g-hesorg.ads):: 15450* GNAT.HTable (g-htable.ads):: 15451* GNAT.IO (g-io.ads):: 15452* GNAT.IO_Aux (g-io_aux.ads):: 15453* GNAT.Lock_Files (g-locfil.ads):: 15454* GNAT.MBBS_Discrete_Random (g-mbdira.ads):: 15455* GNAT.MBBS_Float_Random (g-mbflra.ads):: 15456* GNAT.MD5 (g-md5.ads):: 15457* GNAT.Memory_Dump (g-memdum.ads):: 15458* GNAT.Most_Recent_Exception (g-moreex.ads):: 15459* GNAT.OS_Lib (g-os_lib.ads):: 15460* GNAT.Perfect_Hash_Generators (g-pehage.ads):: 15461* GNAT.Random_Numbers (g-rannum.ads):: 15462* GNAT.Regexp (g-regexp.ads):: 15463* GNAT.Registry (g-regist.ads):: 15464* GNAT.Regpat (g-regpat.ads):: 15465* GNAT.Secondary_Stack_Info (g-sestin.ads):: 15466* GNAT.Semaphores (g-semaph.ads):: 15467* GNAT.Serial_Communications (g-sercom.ads):: 15468* GNAT.SHA1 (g-sha1.ads):: 15469* GNAT.SHA224 (g-sha224.ads):: 15470* GNAT.SHA256 (g-sha256.ads):: 15471* GNAT.SHA384 (g-sha384.ads):: 15472* GNAT.SHA512 (g-sha512.ads):: 15473* GNAT.Signals (g-signal.ads):: 15474* GNAT.Sockets (g-socket.ads):: 15475* GNAT.Source_Info (g-souinf.ads):: 15476* GNAT.Spelling_Checker (g-speche.ads):: 15477* GNAT.Spelling_Checker_Generic (g-spchge.ads):: 15478* GNAT.Spitbol.Patterns (g-spipat.ads):: 15479* GNAT.Spitbol (g-spitbo.ads):: 15480* GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: 15481* GNAT.Spitbol.Table_Integer (g-sptain.ads):: 15482* GNAT.Spitbol.Table_VString (g-sptavs.ads):: 15483* GNAT.SSE (g-sse.ads):: 15484* GNAT.SSE.Vector_Types (g-ssvety.ads):: 15485* GNAT.Strings (g-string.ads):: 15486* GNAT.String_Split (g-strspl.ads):: 15487* GNAT.Table (g-table.ads):: 15488* GNAT.Task_Lock (g-tasloc.ads):: 15489* GNAT.Threads (g-thread.ads):: 15490* GNAT.Time_Stamp (g-timsta.ads):: 15491* GNAT.Traceback (g-traceb.ads):: 15492* GNAT.Traceback.Symbolic (g-trasym.ads):: 15493* GNAT.UTF_32 (g-utf_32.ads):: 15494* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads):: 15495* GNAT.Wide_Spelling_Checker (g-wispch.ads):: 15496* GNAT.Wide_String_Split (g-wistsp.ads):: 15497* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads):: 15498* GNAT.Wide_Wide_String_Split (g-zistsp.ads):: 15499* Interfaces.C.Extensions (i-cexten.ads):: 15500* Interfaces.C.Streams (i-cstrea.ads):: 15501* Interfaces.CPP (i-cpp.ads):: 15502* Interfaces.Packed_Decimal (i-pacdec.ads):: 15503* Interfaces.VxWorks (i-vxwork.ads):: 15504* Interfaces.VxWorks.IO (i-vxwoio.ads):: 15505* System.Address_Image (s-addima.ads):: 15506* System.Assertions (s-assert.ads):: 15507* System.Memory (s-memory.ads):: 15508* System.Partition_Interface (s-parint.ads):: 15509* System.Pool_Global (s-pooglo.ads):: 15510* System.Pool_Local (s-pooloc.ads):: 15511* System.Restrictions (s-restri.ads):: 15512* System.Rident (s-rident.ads):: 15513* System.Strings.Stream_Ops (s-ststop.ads):: 15514* System.Task_Info (s-tasinf.ads):: 15515* System.Wch_Cnv (s-wchcnv.ads):: 15516* System.Wch_Con (s-wchcon.ads):: 15517@end menu 15518 15519@node Ada.Characters.Latin_9 (a-chlat9.ads) 15520@section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) 15521@cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) 15522@cindex Latin_9 constants for Character 15523 15524@noindent 15525This child of @code{Ada.Characters} 15526provides a set of definitions corresponding to those in the 15527RM-defined package @code{Ada.Characters.Latin_1} but with the 15528few modifications required for @code{Latin-9} 15529The provision of such a package 15530is specifically authorized by the Ada Reference Manual 15531(RM A.3.3(27)). 15532 15533@node Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 15534@section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) 15535@cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) 15536@cindex Latin_1 constants for Wide_Character 15537 15538@noindent 15539This child of @code{Ada.Characters} 15540provides a set of definitions corresponding to those in the 15541RM-defined package @code{Ada.Characters.Latin_1} but with the 15542types of the constants being @code{Wide_Character} 15543instead of @code{Character}. The provision of such a package 15544is specifically authorized by the Ada Reference Manual 15545(RM A.3.3(27)). 15546 15547@node Ada.Characters.Wide_Latin_9 (a-cwila9.ads) 15548@section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) 15549@cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) 15550@cindex Latin_9 constants for Wide_Character 15551 15552@noindent 15553This child of @code{Ada.Characters} 15554provides a set of definitions corresponding to those in the 15555GNAT defined package @code{Ada.Characters.Latin_9} but with the 15556types of the constants being @code{Wide_Character} 15557instead of @code{Character}. The provision of such a package 15558is specifically authorized by the Ada Reference Manual 15559(RM A.3.3(27)). 15560 15561@node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) 15562@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads}) 15563@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads}) 15564@cindex Latin_1 constants for Wide_Wide_Character 15565 15566@noindent 15567This child of @code{Ada.Characters} 15568provides a set of definitions corresponding to those in the 15569RM-defined package @code{Ada.Characters.Latin_1} but with the 15570types of the constants being @code{Wide_Wide_Character} 15571instead of @code{Character}. The provision of such a package 15572is specifically authorized by the Ada Reference Manual 15573(RM A.3.3(27)). 15574 15575@node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) 15576@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads}) 15577@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads}) 15578@cindex Latin_9 constants for Wide_Wide_Character 15579 15580@noindent 15581This child of @code{Ada.Characters} 15582provides a set of definitions corresponding to those in the 15583GNAT defined package @code{Ada.Characters.Latin_9} but with the 15584types of the constants being @code{Wide_Wide_Character} 15585instead of @code{Character}. The provision of such a package 15586is specifically authorized by the Ada Reference Manual 15587(RM A.3.3(27)). 15588 15589@node Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) 15590@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads}) 15591@cindex @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads}) 15592@cindex Formal container for doubly linked lists 15593 15594@noindent 15595This child of @code{Ada.Containers} defines a modified version of the Ada 2005 15596container for doubly linked lists, meant to facilitate formal verification of 15597code using such containers. 15598 15599@node Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) 15600@section @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads}) 15601@cindex @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads}) 15602@cindex Formal container for hashed maps 15603 15604@noindent 15605This child of @code{Ada.Containers} defines a modified version of the Ada 2005 15606container for hashed maps, meant to facilitate formal verification of 15607code using such containers. 15608 15609@node Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) 15610@section @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads}) 15611@cindex @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads}) 15612@cindex Formal container for hashed sets 15613 15614@noindent 15615This child of @code{Ada.Containers} defines a modified version of the Ada 2005 15616container for hashed sets, meant to facilitate formal verification of 15617code using such containers. 15618 15619@node Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) 15620@section @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads}) 15621@cindex @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads}) 15622@cindex Formal container for ordered maps 15623 15624@noindent 15625This child of @code{Ada.Containers} defines a modified version of the Ada 2005 15626container for ordered maps, meant to facilitate formal verification of 15627code using such containers. 15628 15629@node Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) 15630@section @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads}) 15631@cindex @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads}) 15632@cindex Formal container for ordered sets 15633 15634@noindent 15635This child of @code{Ada.Containers} defines a modified version of the Ada 2005 15636container for ordered sets, meant to facilitate formal verification of 15637code using such containers. 15638 15639@node Ada.Containers.Formal_Vectors (a-cofove.ads) 15640@section @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads}) 15641@cindex @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads}) 15642@cindex Formal container for vectors 15643 15644@noindent 15645This child of @code{Ada.Containers} defines a modified version of the Ada 2005 15646container for vectors, meant to facilitate formal verification of 15647code using such containers. 15648 15649@node Ada.Command_Line.Environment (a-colien.ads) 15650@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) 15651@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) 15652@cindex Environment entries 15653 15654@noindent 15655This child of @code{Ada.Command_Line} 15656provides a mechanism for obtaining environment values on systems 15657where this concept makes sense. 15658 15659@node Ada.Command_Line.Remove (a-colire.ads) 15660@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) 15661@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) 15662@cindex Removing command line arguments 15663@cindex Command line, argument removal 15664 15665@noindent 15666This child of @code{Ada.Command_Line} 15667provides a mechanism for logically removing 15668arguments from the argument list. Once removed, an argument is not visible 15669to further calls on the subprograms in @code{Ada.Command_Line} will not 15670see the removed argument. 15671 15672@node Ada.Command_Line.Response_File (a-clrefi.ads) 15673@section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads}) 15674@cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads}) 15675@cindex Response file for command line 15676@cindex Command line, response file 15677@cindex Command line, handling long command lines 15678 15679@noindent 15680This child of @code{Ada.Command_Line} provides a mechanism facilities for 15681getting command line arguments from a text file, called a "response file". 15682Using a response file allow passing a set of arguments to an executable longer 15683than the maximum allowed by the system on the command line. 15684 15685@node Ada.Direct_IO.C_Streams (a-diocst.ads) 15686@section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) 15687@cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) 15688@cindex C Streams, Interfacing with Direct_IO 15689 15690@noindent 15691This package provides subprograms that allow interfacing between 15692C streams and @code{Direct_IO}. The stream identifier can be 15693extracted from a file opened on the Ada side, and an Ada file 15694can be constructed from a stream opened on the C side. 15695 15696@node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 15697@section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) 15698@cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) 15699@cindex Null_Occurrence, testing for 15700 15701@noindent 15702This child subprogram provides a way of testing for the null 15703exception occurrence (@code{Null_Occurrence}) without raising 15704an exception. 15705 15706@node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) 15707@section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads}) 15708@cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads}) 15709@cindex Null_Occurrence, testing for 15710 15711@noindent 15712This child subprogram is used for handling otherwise unhandled 15713exceptions (hence the name last chance), and perform clean ups before 15714terminating the program. Note that this subprogram never returns. 15715 15716@node Ada.Exceptions.Traceback (a-exctra.ads) 15717@section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) 15718@cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) 15719@cindex Traceback for Exception Occurrence 15720 15721@noindent 15722This child package provides the subprogram (@code{Tracebacks}) to 15723give a traceback array of addresses based on an exception 15724occurrence. 15725 15726@node Ada.Sequential_IO.C_Streams (a-siocst.ads) 15727@section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) 15728@cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) 15729@cindex C Streams, Interfacing with Sequential_IO 15730 15731@noindent 15732This package provides subprograms that allow interfacing between 15733C streams and @code{Sequential_IO}. The stream identifier can be 15734extracted from a file opened on the Ada side, and an Ada file 15735can be constructed from a stream opened on the C side. 15736 15737@node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 15738@section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) 15739@cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) 15740@cindex C Streams, Interfacing with Stream_IO 15741 15742@noindent 15743This package provides subprograms that allow interfacing between 15744C streams and @code{Stream_IO}. The stream identifier can be 15745extracted from a file opened on the Ada side, and an Ada file 15746can be constructed from a stream opened on the C side. 15747 15748@node Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 15749@section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) 15750@cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) 15751@cindex @code{Unbounded_String}, IO support 15752@cindex @code{Text_IO}, extensions for unbounded strings 15753 15754@noindent 15755This package provides subprograms for Text_IO for unbounded 15756strings, avoiding the necessity for an intermediate operation 15757with ordinary strings. 15758 15759@node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 15760@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) 15761@cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) 15762@cindex @code{Unbounded_Wide_String}, IO support 15763@cindex @code{Text_IO}, extensions for unbounded wide strings 15764 15765@noindent 15766This package provides subprograms for Text_IO for unbounded 15767wide strings, avoiding the necessity for an intermediate operation 15768with ordinary wide strings. 15769 15770@node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) 15771@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads}) 15772@cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads}) 15773@cindex @code{Unbounded_Wide_Wide_String}, IO support 15774@cindex @code{Text_IO}, extensions for unbounded wide wide strings 15775 15776@noindent 15777This package provides subprograms for Text_IO for unbounded 15778wide wide strings, avoiding the necessity for an intermediate operation 15779with ordinary wide wide strings. 15780 15781@node Ada.Text_IO.C_Streams (a-tiocst.ads) 15782@section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) 15783@cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) 15784@cindex C Streams, Interfacing with @code{Text_IO} 15785 15786@noindent 15787This package provides subprograms that allow interfacing between 15788C streams and @code{Text_IO}. The stream identifier can be 15789extracted from a file opened on the Ada side, and an Ada file 15790can be constructed from a stream opened on the C side. 15791 15792@node Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) 15793@section @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads}) 15794@cindex @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads}) 15795@cindex @code{Text_IO} resetting standard files 15796 15797@noindent 15798This procedure is used to reset the status of the standard files used 15799by Ada.Text_IO. This is useful in a situation (such as a restart in an 15800embedded application) where the status of the files may change during 15801execution (for example a standard input file may be redefined to be 15802interactive). 15803 15804@node Ada.Wide_Characters.Unicode (a-wichun.ads) 15805@section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads}) 15806@cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads}) 15807@cindex Unicode categorization, Wide_Character 15808 15809@noindent 15810This package provides subprograms that allow categorization of 15811Wide_Character values according to Unicode categories. 15812 15813@node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 15814@section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) 15815@cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) 15816@cindex C Streams, Interfacing with @code{Wide_Text_IO} 15817 15818@noindent 15819This package provides subprograms that allow interfacing between 15820C streams and @code{Wide_Text_IO}. The stream identifier can be 15821extracted from a file opened on the Ada side, and an Ada file 15822can be constructed from a stream opened on the C side. 15823 15824@node Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) 15825@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads}) 15826@cindex @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads}) 15827@cindex @code{Wide_Text_IO} resetting standard files 15828 15829@noindent 15830This procedure is used to reset the status of the standard files used 15831by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an 15832embedded application) where the status of the files may change during 15833execution (for example a standard input file may be redefined to be 15834interactive). 15835 15836@node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) 15837@section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads}) 15838@cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads}) 15839@cindex Unicode categorization, Wide_Wide_Character 15840 15841@noindent 15842This package provides subprograms that allow categorization of 15843Wide_Wide_Character values according to Unicode categories. 15844 15845@node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) 15846@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads}) 15847@cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads}) 15848@cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO} 15849 15850@noindent 15851This package provides subprograms that allow interfacing between 15852C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be 15853extracted from a file opened on the Ada side, and an Ada file 15854can be constructed from a stream opened on the C side. 15855 15856@node Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) 15857@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads}) 15858@cindex @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads}) 15859@cindex @code{Wide_Wide_Text_IO} resetting standard files 15860 15861@noindent 15862This procedure is used to reset the status of the standard files used 15863by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a 15864restart in an embedded application) where the status of the files may 15865change during execution (for example a standard input file may be 15866redefined to be interactive). 15867 15868@node GNAT.Altivec (g-altive.ads) 15869@section @code{GNAT.Altivec} (@file{g-altive.ads}) 15870@cindex @code{GNAT.Altivec} (@file{g-altive.ads}) 15871@cindex AltiVec 15872 15873@noindent 15874This is the root package of the GNAT AltiVec binding. It provides 15875definitions of constants and types common to all the versions of the 15876binding. 15877 15878@node GNAT.Altivec.Conversions (g-altcon.ads) 15879@section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads}) 15880@cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads}) 15881@cindex AltiVec 15882 15883@noindent 15884This package provides the Vector/View conversion routines. 15885 15886@node GNAT.Altivec.Vector_Operations (g-alveop.ads) 15887@section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads}) 15888@cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads}) 15889@cindex AltiVec 15890 15891@noindent 15892This package exposes the Ada interface to the AltiVec operations on 15893vector objects. A soft emulation is included by default in the GNAT 15894library. The hard binding is provided as a separate package. This unit 15895is common to both bindings. 15896 15897@node GNAT.Altivec.Vector_Types (g-alvety.ads) 15898@section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads}) 15899@cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads}) 15900@cindex AltiVec 15901 15902@noindent 15903This package exposes the various vector types part of the Ada binding 15904to AltiVec facilities. 15905 15906@node GNAT.Altivec.Vector_Views (g-alvevi.ads) 15907@section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads}) 15908@cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads}) 15909@cindex AltiVec 15910 15911@noindent 15912This package provides public 'View' data types from/to which private 15913vector representations can be converted via 15914GNAT.Altivec.Conversions. This allows convenient access to individual 15915vector elements and provides a simple way to initialize vector 15916objects. 15917 15918@node GNAT.Array_Split (g-arrspl.ads) 15919@section @code{GNAT.Array_Split} (@file{g-arrspl.ads}) 15920@cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads}) 15921@cindex Array splitter 15922 15923@noindent 15924Useful array-manipulation routines: given a set of separators, split 15925an array wherever the separators appear, and provide direct access 15926to the resulting slices. 15927 15928@node GNAT.AWK (g-awk.ads) 15929@section @code{GNAT.AWK} (@file{g-awk.ads}) 15930@cindex @code{GNAT.AWK} (@file{g-awk.ads}) 15931@cindex Parsing 15932@cindex AWK 15933 15934@noindent 15935Provides AWK-like parsing functions, with an easy interface for parsing one 15936or more files containing formatted data. The file is viewed as a database 15937where each record is a line and a field is a data element in this line. 15938 15939@node GNAT.Bounded_Buffers (g-boubuf.ads) 15940@section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) 15941@cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) 15942@cindex Parsing 15943@cindex Bounded Buffers 15944 15945@noindent 15946Provides a concurrent generic bounded buffer abstraction. Instances are 15947useful directly or as parts of the implementations of other abstractions, 15948such as mailboxes. 15949 15950@node GNAT.Bounded_Mailboxes (g-boumai.ads) 15951@section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) 15952@cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) 15953@cindex Parsing 15954@cindex Mailboxes 15955 15956@noindent 15957Provides a thread-safe asynchronous intertask mailbox communication facility. 15958 15959@node GNAT.Bubble_Sort (g-bubsor.ads) 15960@section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) 15961@cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) 15962@cindex Sorting 15963@cindex Bubble sort 15964 15965@noindent 15966Provides a general implementation of bubble sort usable for sorting arbitrary 15967data items. Exchange and comparison procedures are provided by passing 15968access-to-procedure values. 15969 15970@node GNAT.Bubble_Sort_A (g-busora.ads) 15971@section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) 15972@cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) 15973@cindex Sorting 15974@cindex Bubble sort 15975 15976@noindent 15977Provides a general implementation of bubble sort usable for sorting arbitrary 15978data items. Move and comparison procedures are provided by passing 15979access-to-procedure values. This is an older version, retained for 15980compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. 15981 15982@node GNAT.Bubble_Sort_G (g-busorg.ads) 15983@section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) 15984@cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) 15985@cindex Sorting 15986@cindex Bubble sort 15987 15988@noindent 15989Similar to @code{Bubble_Sort_A} except that the move and sorting procedures 15990are provided as generic parameters, this improves efficiency, especially 15991if the procedures can be inlined, at the expense of duplicating code for 15992multiple instantiations. 15993 15994@node GNAT.Byte_Order_Mark (g-byorma.ads) 15995@section @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads}) 15996@cindex @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads}) 15997@cindex UTF-8 representation 15998@cindex Wide characte representations 15999 16000@noindent 16001Provides a routine which given a string, reads the start of the string to 16002see whether it is one of the standard byte order marks (BOM's) which signal 16003the encoding of the string. The routine includes detection of special XML 16004sequences for various UCS input formats. 16005 16006@node GNAT.Byte_Swapping (g-bytswa.ads) 16007@section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads}) 16008@cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads}) 16009@cindex Byte swapping 16010@cindex Endianness 16011 16012@noindent 16013General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. 16014Machine-specific implementations are available in some cases. 16015 16016@node GNAT.Calendar (g-calend.ads) 16017@section @code{GNAT.Calendar} (@file{g-calend.ads}) 16018@cindex @code{GNAT.Calendar} (@file{g-calend.ads}) 16019@cindex @code{Calendar} 16020 16021@noindent 16022Extends the facilities provided by @code{Ada.Calendar} to include handling 16023of days of the week, an extended @code{Split} and @code{Time_Of} capability. 16024Also provides conversion of @code{Ada.Calendar.Time} values to and from the 16025C @code{timeval} format. 16026 16027@node GNAT.Calendar.Time_IO (g-catiio.ads) 16028@section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) 16029@cindex @code{Calendar} 16030@cindex Time 16031@cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) 16032 16033@node GNAT.CRC32 (g-crc32.ads) 16034@section @code{GNAT.CRC32} (@file{g-crc32.ads}) 16035@cindex @code{GNAT.CRC32} (@file{g-crc32.ads}) 16036@cindex CRC32 16037@cindex Cyclic Redundancy Check 16038 16039@noindent 16040This package implements the CRC-32 algorithm. For a full description 16041of this algorithm see 16042``Computation of Cyclic Redundancy Checks via Table Look-Up'', 16043@cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013, 16044Aug.@: 1988. Sarwate, D.V@. 16045 16046@node GNAT.Case_Util (g-casuti.ads) 16047@section @code{GNAT.Case_Util} (@file{g-casuti.ads}) 16048@cindex @code{GNAT.Case_Util} (@file{g-casuti.ads}) 16049@cindex Casing utilities 16050@cindex Character handling (@code{GNAT.Case_Util}) 16051 16052@noindent 16053A set of simple routines for handling upper and lower casing of strings 16054without the overhead of the full casing tables 16055in @code{Ada.Characters.Handling}. 16056 16057@node GNAT.CGI (g-cgi.ads) 16058@section @code{GNAT.CGI} (@file{g-cgi.ads}) 16059@cindex @code{GNAT.CGI} (@file{g-cgi.ads}) 16060@cindex CGI (Common Gateway Interface) 16061 16062@noindent 16063This is a package for interfacing a GNAT program with a Web server via the 16064Common Gateway Interface (CGI)@. Basically this package parses the CGI 16065parameters, which are a set of key/value pairs sent by the Web server. It 16066builds a table whose index is the key and provides some services to deal 16067with this table. 16068 16069@node GNAT.CGI.Cookie (g-cgicoo.ads) 16070@section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) 16071@cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) 16072@cindex CGI (Common Gateway Interface) cookie support 16073@cindex Cookie support in CGI 16074 16075@noindent 16076This is a package to interface a GNAT program with a Web server via the 16077Common Gateway Interface (CGI). It exports services to deal with Web 16078cookies (piece of information kept in the Web client software). 16079 16080@node GNAT.CGI.Debug (g-cgideb.ads) 16081@section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) 16082@cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) 16083@cindex CGI (Common Gateway Interface) debugging 16084 16085@noindent 16086This is a package to help debugging CGI (Common Gateway Interface) 16087programs written in Ada. 16088 16089@node GNAT.Command_Line (g-comlin.ads) 16090@section @code{GNAT.Command_Line} (@file{g-comlin.ads}) 16091@cindex @code{GNAT.Command_Line} (@file{g-comlin.ads}) 16092@cindex Command line 16093 16094@noindent 16095Provides a high level interface to @code{Ada.Command_Line} facilities, 16096including the ability to scan for named switches with optional parameters 16097and expand file names using wild card notations. 16098 16099@node GNAT.Compiler_Version (g-comver.ads) 16100@section @code{GNAT.Compiler_Version} (@file{g-comver.ads}) 16101@cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads}) 16102@cindex Compiler Version 16103@cindex Version, of compiler 16104 16105@noindent 16106Provides a routine for obtaining the version of the compiler used to 16107compile the program. More accurately this is the version of the binder 16108used to bind the program (this will normally be the same as the version 16109of the compiler if a consistent tool set is used to compile all units 16110of a partition). 16111 16112@node GNAT.Ctrl_C (g-ctrl_c.ads) 16113@section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) 16114@cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) 16115@cindex Interrupt 16116 16117@noindent 16118Provides a simple interface to handle Ctrl-C keyboard events. 16119 16120@node GNAT.Current_Exception (g-curexc.ads) 16121@section @code{GNAT.Current_Exception} (@file{g-curexc.ads}) 16122@cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads}) 16123@cindex Current exception 16124@cindex Exception retrieval 16125 16126@noindent 16127Provides access to information on the current exception that has been raised 16128without the need for using the Ada 95 / Ada 2005 exception choice parameter 16129specification syntax. 16130This is particularly useful in simulating typical facilities for 16131obtaining information about exceptions provided by Ada 83 compilers. 16132 16133@node GNAT.Debug_Pools (g-debpoo.ads) 16134@section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) 16135@cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) 16136@cindex Debugging 16137@cindex Debug pools 16138@cindex Memory corruption debugging 16139 16140@noindent 16141Provide a debugging storage pools that helps tracking memory corruption 16142problems. @xref{The GNAT Debug Pool Facility,,, gnat_ugn, 16143@value{EDITION} User's Guide}. 16144 16145@node GNAT.Debug_Utilities (g-debuti.ads) 16146@section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) 16147@cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) 16148@cindex Debugging 16149 16150@noindent 16151Provides a few useful utilities for debugging purposes, including conversion 16152to and from string images of address values. Supports both C and Ada formats 16153for hexadecimal literals. 16154 16155@node GNAT.Decode_String (g-decstr.ads) 16156@section @code{GNAT.Decode_String} (@file{g-decstr.ads}) 16157@cindex @code{GNAT.Decode_String} (@file{g-decstr.ads}) 16158@cindex Decoding strings 16159@cindex String decoding 16160@cindex Wide character encoding 16161@cindex UTF-8 16162@cindex Unicode 16163 16164@noindent 16165A generic package providing routines for decoding wide character and wide wide 16166character strings encoded as sequences of 8-bit characters using a specified 16167encoding method. Includes validation routines, and also routines for stepping 16168to next or previous encoded character in an encoded string. 16169Useful in conjunction with Unicode character coding. Note there is a 16170preinstantiation for UTF-8. See next entry. 16171 16172@node GNAT.Decode_UTF8_String (g-deutst.ads) 16173@section @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads}) 16174@cindex @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads}) 16175@cindex Decoding strings 16176@cindex Decoding UTF-8 strings 16177@cindex UTF-8 string decoding 16178@cindex Wide character decoding 16179@cindex UTF-8 16180@cindex Unicode 16181 16182@noindent 16183A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. 16184 16185@node GNAT.Directory_Operations (g-dirope.ads) 16186@section @code{GNAT.Directory_Operations} (@file{g-dirope.ads}) 16187@cindex @code{GNAT.Directory_Operations} (@file{g-dirope.ads}) 16188@cindex Directory operations 16189 16190@noindent 16191Provides a set of routines for manipulating directories, including changing 16192the current directory, making new directories, and scanning the files in a 16193directory. 16194 16195@node GNAT.Directory_Operations.Iteration (g-diopit.ads) 16196@section @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads}) 16197@cindex @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads}) 16198@cindex Directory operations iteration 16199 16200@noindent 16201A child unit of GNAT.Directory_Operations providing additional operations 16202for iterating through directories. 16203 16204@node GNAT.Dynamic_HTables (g-dynhta.ads) 16205@section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) 16206@cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) 16207@cindex Hash tables 16208 16209@noindent 16210A generic implementation of hash tables that can be used to hash arbitrary 16211data. Provided in two forms, a simple form with built in hash functions, 16212and a more complex form in which the hash function is supplied. 16213 16214@noindent 16215This package provides a facility similar to that of @code{GNAT.HTable}, 16216except that this package declares a type that can be used to define 16217dynamic instances of the hash table, while an instantiation of 16218@code{GNAT.HTable} creates a single instance of the hash table. 16219 16220@node GNAT.Dynamic_Tables (g-dyntab.ads) 16221@section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) 16222@cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) 16223@cindex Table implementation 16224@cindex Arrays, extendable 16225 16226@noindent 16227A generic package providing a single dimension array abstraction where the 16228length of the array can be dynamically modified. 16229 16230@noindent 16231This package provides a facility similar to that of @code{GNAT.Table}, 16232except that this package declares a type that can be used to define 16233dynamic instances of the table, while an instantiation of 16234@code{GNAT.Table} creates a single instance of the table type. 16235 16236@node GNAT.Encode_String (g-encstr.ads) 16237@section @code{GNAT.Encode_String} (@file{g-encstr.ads}) 16238@cindex @code{GNAT.Encode_String} (@file{g-encstr.ads}) 16239@cindex Encoding strings 16240@cindex String encoding 16241@cindex Wide character encoding 16242@cindex UTF-8 16243@cindex Unicode 16244 16245@noindent 16246A generic package providing routines for encoding wide character and wide 16247wide character strings as sequences of 8-bit characters using a specified 16248encoding method. Useful in conjunction with Unicode character coding. 16249Note there is a preinstantiation for UTF-8. See next entry. 16250 16251@node GNAT.Encode_UTF8_String (g-enutst.ads) 16252@section @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads}) 16253@cindex @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads}) 16254@cindex Encoding strings 16255@cindex Encoding UTF-8 strings 16256@cindex UTF-8 string encoding 16257@cindex Wide character encoding 16258@cindex UTF-8 16259@cindex Unicode 16260 16261@noindent 16262A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. 16263 16264@node GNAT.Exception_Actions (g-excact.ads) 16265@section @code{GNAT.Exception_Actions} (@file{g-excact.ads}) 16266@cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads}) 16267@cindex Exception actions 16268 16269@noindent 16270Provides callbacks when an exception is raised. Callbacks can be registered 16271for specific exceptions, or when any exception is raised. This 16272can be used for instance to force a core dump to ease debugging. 16273 16274@node GNAT.Exception_Traces (g-exctra.ads) 16275@section @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) 16276@cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) 16277@cindex Exception traces 16278@cindex Debugging 16279 16280@noindent 16281Provides an interface allowing to control automatic output upon exception 16282occurrences. 16283 16284@node GNAT.Exceptions (g-except.ads) 16285@section @code{GNAT.Exceptions} (@file{g-expect.ads}) 16286@cindex @code{GNAT.Exceptions} (@file{g-expect.ads}) 16287@cindex Exceptions, Pure 16288@cindex Pure packages, exceptions 16289 16290@noindent 16291Normally it is not possible to raise an exception with 16292a message from a subprogram in a pure package, since the 16293necessary types and subprograms are in @code{Ada.Exceptions} 16294which is not a pure unit. @code{GNAT.Exceptions} provides a 16295facility for getting around this limitation for a few 16296predefined exceptions, and for example allow raising 16297@code{Constraint_Error} with a message from a pure subprogram. 16298 16299@node GNAT.Expect (g-expect.ads) 16300@section @code{GNAT.Expect} (@file{g-expect.ads}) 16301@cindex @code{GNAT.Expect} (@file{g-expect.ads}) 16302 16303@noindent 16304Provides a set of subprograms similar to what is available 16305with the standard Tcl Expect tool. 16306It allows you to easily spawn and communicate with an external process. 16307You can send commands or inputs to the process, and compare the output 16308with some expected regular expression. Currently @code{GNAT.Expect} 16309is implemented on all native GNAT ports except for OpenVMS@. 16310It is not implemented for cross ports, and in particular is not 16311implemented for VxWorks or LynxOS@. 16312 16313@node GNAT.Expect.TTY (g-exptty.ads) 16314@section @code{GNAT.Expect.TTY} (@file{g-exptty.ads}) 16315@cindex @code{GNAT.Expect.TTY} (@file{g-exptty.ads}) 16316 16317@noindent 16318As GNAT.Expect but using pseudo-terminal. 16319Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT 16320ports except for OpenVMS@. It is not implemented for cross ports, and 16321in particular is not implemented for VxWorks or LynxOS@. 16322 16323@node GNAT.Float_Control (g-flocon.ads) 16324@section @code{GNAT.Float_Control} (@file{g-flocon.ads}) 16325@cindex @code{GNAT.Float_Control} (@file{g-flocon.ads}) 16326@cindex Floating-Point Processor 16327 16328@noindent 16329Provides an interface for resetting the floating-point processor into the 16330mode required for correct semantic operation in Ada. Some third party 16331library calls may cause this mode to be modified, and the Reset procedure 16332in this package can be used to reestablish the required mode. 16333 16334@node GNAT.Heap_Sort (g-heasor.ads) 16335@section @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) 16336@cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) 16337@cindex Sorting 16338 16339@noindent 16340Provides a general implementation of heap sort usable for sorting arbitrary 16341data items. Exchange and comparison procedures are provided by passing 16342access-to-procedure values. The algorithm used is a modified heap sort 16343that performs approximately N*log(N) comparisons in the worst case. 16344 16345@node GNAT.Heap_Sort_A (g-hesora.ads) 16346@section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) 16347@cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) 16348@cindex Sorting 16349 16350@noindent 16351Provides a general implementation of heap sort usable for sorting arbitrary 16352data items. Move and comparison procedures are provided by passing 16353access-to-procedure values. The algorithm used is a modified heap sort 16354that performs approximately N*log(N) comparisons in the worst case. 16355This differs from @code{GNAT.Heap_Sort} in having a less convenient 16356interface, but may be slightly more efficient. 16357 16358@node GNAT.Heap_Sort_G (g-hesorg.ads) 16359@section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) 16360@cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) 16361@cindex Sorting 16362 16363@noindent 16364Similar to @code{Heap_Sort_A} except that the move and sorting procedures 16365are provided as generic parameters, this improves efficiency, especially 16366if the procedures can be inlined, at the expense of duplicating code for 16367multiple instantiations. 16368 16369@node GNAT.HTable (g-htable.ads) 16370@section @code{GNAT.HTable} (@file{g-htable.ads}) 16371@cindex @code{GNAT.HTable} (@file{g-htable.ads}) 16372@cindex Hash tables 16373 16374@noindent 16375A generic implementation of hash tables that can be used to hash arbitrary 16376data. Provides two approaches, one a simple static approach, and the other 16377allowing arbitrary dynamic hash tables. 16378 16379@node GNAT.IO (g-io.ads) 16380@section @code{GNAT.IO} (@file{g-io.ads}) 16381@cindex @code{GNAT.IO} (@file{g-io.ads}) 16382@cindex Simple I/O 16383@cindex Input/Output facilities 16384 16385@noindent 16386A simple preelaborable input-output package that provides a subset of 16387simple Text_IO functions for reading characters and strings from 16388Standard_Input, and writing characters, strings and integers to either 16389Standard_Output or Standard_Error. 16390 16391@node GNAT.IO_Aux (g-io_aux.ads) 16392@section @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) 16393@cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) 16394@cindex Text_IO 16395@cindex Input/Output facilities 16396 16397Provides some auxiliary functions for use with Text_IO, including a test 16398for whether a file exists, and functions for reading a line of text. 16399 16400@node GNAT.Lock_Files (g-locfil.ads) 16401@section @code{GNAT.Lock_Files} (@file{g-locfil.ads}) 16402@cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads}) 16403@cindex File locking 16404@cindex Locking using files 16405 16406@noindent 16407Provides a general interface for using files as locks. Can be used for 16408providing program level synchronization. 16409 16410@node GNAT.MBBS_Discrete_Random (g-mbdira.ads) 16411@section @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads}) 16412@cindex @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads}) 16413@cindex Random number generation 16414 16415@noindent 16416The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses 16417a modified version of the Blum-Blum-Shub generator. 16418 16419@node GNAT.MBBS_Float_Random (g-mbflra.ads) 16420@section @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads}) 16421@cindex @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads}) 16422@cindex Random number generation 16423 16424@noindent 16425The original implementation of @code{Ada.Numerics.Float_Random}. Uses 16426a modified version of the Blum-Blum-Shub generator. 16427 16428@node GNAT.MD5 (g-md5.ads) 16429@section @code{GNAT.MD5} (@file{g-md5.ads}) 16430@cindex @code{GNAT.MD5} (@file{g-md5.ads}) 16431@cindex Message Digest MD5 16432 16433@noindent 16434Implements the MD5 Message-Digest Algorithm as described in RFC 1321. 16435 16436@node GNAT.Memory_Dump (g-memdum.ads) 16437@section @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) 16438@cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) 16439@cindex Dump Memory 16440 16441@noindent 16442Provides a convenient routine for dumping raw memory to either the 16443standard output or standard error files. Uses GNAT.IO for actual 16444output. 16445 16446@node GNAT.Most_Recent_Exception (g-moreex.ads) 16447@section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) 16448@cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) 16449@cindex Exception, obtaining most recent 16450 16451@noindent 16452Provides access to the most recently raised exception. Can be used for 16453various logging purposes, including duplicating functionality of some 16454Ada 83 implementation dependent extensions. 16455 16456@node GNAT.OS_Lib (g-os_lib.ads) 16457@section @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) 16458@cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) 16459@cindex Operating System interface 16460@cindex Spawn capability 16461 16462@noindent 16463Provides a range of target independent operating system interface functions, 16464including time/date management, file operations, subprocess management, 16465including a portable spawn procedure, and access to environment variables 16466and error return codes. 16467 16468@node GNAT.Perfect_Hash_Generators (g-pehage.ads) 16469@section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads}) 16470@cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads}) 16471@cindex Hash functions 16472 16473@noindent 16474Provides a generator of static minimal perfect hash functions. No 16475collisions occur and each item can be retrieved from the table in one 16476probe (perfect property). The hash table size corresponds to the exact 16477size of the key set and no larger (minimal property). The key set has to 16478be know in advance (static property). The hash functions are also order 16479preserving. If w2 is inserted after w1 in the generator, their 16480hashcode are in the same order. These hashing functions are very 16481convenient for use with realtime applications. 16482 16483@node GNAT.Random_Numbers (g-rannum.ads) 16484@section @code{GNAT.Random_Numbers} (@file{g-rannum.ads}) 16485@cindex @code{GNAT.Random_Numbers} (@file{g-rannum.ads}) 16486@cindex Random number generation 16487 16488@noindent 16489Provides random number capabilities which extend those available in the 16490standard Ada library and are more convenient to use. 16491 16492@node GNAT.Regexp (g-regexp.ads) 16493@section @code{GNAT.Regexp} (@file{g-regexp.ads}) 16494@cindex @code{GNAT.Regexp} (@file{g-regexp.ads}) 16495@cindex Regular expressions 16496@cindex Pattern matching 16497 16498@noindent 16499A simple implementation of regular expressions, using a subset of regular 16500expression syntax copied from familiar Unix style utilities. This is the 16501simples of the three pattern matching packages provided, and is particularly 16502suitable for ``file globbing'' applications. 16503 16504@node GNAT.Registry (g-regist.ads) 16505@section @code{GNAT.Registry} (@file{g-regist.ads}) 16506@cindex @code{GNAT.Registry} (@file{g-regist.ads}) 16507@cindex Windows Registry 16508 16509@noindent 16510This is a high level binding to the Windows registry. It is possible to 16511do simple things like reading a key value, creating a new key. For full 16512registry API, but at a lower level of abstraction, refer to the Win32.Winreg 16513package provided with the Win32Ada binding 16514 16515@node GNAT.Regpat (g-regpat.ads) 16516@section @code{GNAT.Regpat} (@file{g-regpat.ads}) 16517@cindex @code{GNAT.Regpat} (@file{g-regpat.ads}) 16518@cindex Regular expressions 16519@cindex Pattern matching 16520 16521@noindent 16522A complete implementation of Unix-style regular expression matching, copied 16523from the original V7 style regular expression library written in C by 16524Henry Spencer (and binary compatible with this C library). 16525 16526@node GNAT.Secondary_Stack_Info (g-sestin.ads) 16527@section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) 16528@cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) 16529@cindex Secondary Stack Info 16530 16531@noindent 16532Provide the capability to query the high water mark of the current task's 16533secondary stack. 16534 16535@node GNAT.Semaphores (g-semaph.ads) 16536@section @code{GNAT.Semaphores} (@file{g-semaph.ads}) 16537@cindex @code{GNAT.Semaphores} (@file{g-semaph.ads}) 16538@cindex Semaphores 16539 16540@noindent 16541Provides classic counting and binary semaphores using protected types. 16542 16543@node GNAT.Serial_Communications (g-sercom.ads) 16544@section @code{GNAT.Serial_Communications} (@file{g-sercom.ads}) 16545@cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads}) 16546@cindex Serial_Communications 16547 16548@noindent 16549Provides a simple interface to send and receive data over a serial 16550port. This is only supported on GNU/Linux and Windows. 16551 16552@node GNAT.SHA1 (g-sha1.ads) 16553@section @code{GNAT.SHA1} (@file{g-sha1.ads}) 16554@cindex @code{GNAT.SHA1} (@file{g-sha1.ads}) 16555@cindex Secure Hash Algorithm SHA-1 16556 16557@noindent 16558Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 16559and RFC 3174. 16560 16561@node GNAT.SHA224 (g-sha224.ads) 16562@section @code{GNAT.SHA224} (@file{g-sha224.ads}) 16563@cindex @code{GNAT.SHA224} (@file{g-sha224.ads}) 16564@cindex Secure Hash Algorithm SHA-224 16565 16566@noindent 16567Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3. 16568 16569@node GNAT.SHA256 (g-sha256.ads) 16570@section @code{GNAT.SHA256} (@file{g-sha256.ads}) 16571@cindex @code{GNAT.SHA256} (@file{g-sha256.ads}) 16572@cindex Secure Hash Algorithm SHA-256 16573 16574@noindent 16575Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3. 16576 16577@node GNAT.SHA384 (g-sha384.ads) 16578@section @code{GNAT.SHA384} (@file{g-sha384.ads}) 16579@cindex @code{GNAT.SHA384} (@file{g-sha384.ads}) 16580@cindex Secure Hash Algorithm SHA-384 16581 16582@noindent 16583Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3. 16584 16585@node GNAT.SHA512 (g-sha512.ads) 16586@section @code{GNAT.SHA512} (@file{g-sha512.ads}) 16587@cindex @code{GNAT.SHA512} (@file{g-sha512.ads}) 16588@cindex Secure Hash Algorithm SHA-512 16589 16590@noindent 16591Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3. 16592 16593@node GNAT.Signals (g-signal.ads) 16594@section @code{GNAT.Signals} (@file{g-signal.ads}) 16595@cindex @code{GNAT.Signals} (@file{g-signal.ads}) 16596@cindex Signals 16597 16598@noindent 16599Provides the ability to manipulate the blocked status of signals on supported 16600targets. 16601 16602@node GNAT.Sockets (g-socket.ads) 16603@section @code{GNAT.Sockets} (@file{g-socket.ads}) 16604@cindex @code{GNAT.Sockets} (@file{g-socket.ads}) 16605@cindex Sockets 16606 16607@noindent 16608A high level and portable interface to develop sockets based applications. 16609This package is based on the sockets thin binding found in 16610@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented 16611on all native GNAT ports except for OpenVMS@. It is not implemented 16612for the LynxOS@ cross port. 16613 16614@node GNAT.Source_Info (g-souinf.ads) 16615@section @code{GNAT.Source_Info} (@file{g-souinf.ads}) 16616@cindex @code{GNAT.Source_Info} (@file{g-souinf.ads}) 16617@cindex Source Information 16618 16619@noindent 16620Provides subprograms that give access to source code information known at 16621compile time, such as the current file name and line number. 16622 16623@node GNAT.Spelling_Checker (g-speche.ads) 16624@section @code{GNAT.Spelling_Checker} (@file{g-speche.ads}) 16625@cindex @code{GNAT.Spelling_Checker} (@file{g-speche.ads}) 16626@cindex Spell checking 16627 16628@noindent 16629Provides a function for determining whether one string is a plausible 16630near misspelling of another string. 16631 16632@node GNAT.Spelling_Checker_Generic (g-spchge.ads) 16633@section @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads}) 16634@cindex @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads}) 16635@cindex Spell checking 16636 16637@noindent 16638Provides a generic function that can be instantiated with a string type for 16639determining whether one string is a plausible near misspelling of another 16640string. 16641 16642@node GNAT.Spitbol.Patterns (g-spipat.ads) 16643@section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) 16644@cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) 16645@cindex SPITBOL pattern matching 16646@cindex Pattern matching 16647 16648@noindent 16649A complete implementation of SNOBOL4 style pattern matching. This is the 16650most elaborate of the pattern matching packages provided. It fully duplicates 16651the SNOBOL4 dynamic pattern construction and matching capabilities, using the 16652efficient algorithm developed by Robert Dewar for the SPITBOL system. 16653 16654@node GNAT.Spitbol (g-spitbo.ads) 16655@section @code{GNAT.Spitbol} (@file{g-spitbo.ads}) 16656@cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads}) 16657@cindex SPITBOL interface 16658 16659@noindent 16660The top level package of the collection of SPITBOL-style functionality, this 16661package provides basic SNOBOL4 string manipulation functions, such as 16662Pad, Reverse, Trim, Substr capability, as well as a generic table function 16663useful for constructing arbitrary mappings from strings in the style of 16664the SNOBOL4 TABLE function. 16665 16666@node GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 16667@section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) 16668@cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) 16669@cindex Sets of strings 16670@cindex SPITBOL Tables 16671 16672@noindent 16673A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 16674for type @code{Standard.Boolean}, giving an implementation of sets of 16675string values. 16676 16677@node GNAT.Spitbol.Table_Integer (g-sptain.ads) 16678@section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) 16679@cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) 16680@cindex Integer maps 16681@cindex Maps 16682@cindex SPITBOL Tables 16683 16684@noindent 16685A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 16686for type @code{Standard.Integer}, giving an implementation of maps 16687from string to integer values. 16688 16689@node GNAT.Spitbol.Table_VString (g-sptavs.ads) 16690@section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) 16691@cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) 16692@cindex String maps 16693@cindex Maps 16694@cindex SPITBOL Tables 16695 16696@noindent 16697A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for 16698a variable length string type, giving an implementation of general 16699maps from strings to strings. 16700 16701@node GNAT.SSE (g-sse.ads) 16702@section @code{GNAT.SSE} (@file{g-sse.ads}) 16703@cindex @code{GNAT.SSE} (@file{g-sse.ads}) 16704 16705@noindent 16706Root of a set of units aimed at offering Ada bindings to a subset of 16707the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of 16708targets. It exposes vector component types together with a general 16709introduction to the binding contents and use. 16710 16711@node GNAT.SSE.Vector_Types (g-ssvety.ads) 16712@section @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads}) 16713@cindex @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads}) 16714 16715@noindent 16716SSE vector types for use with SSE related intrinsics. 16717 16718@node GNAT.Strings (g-string.ads) 16719@section @code{GNAT.Strings} (@file{g-string.ads}) 16720@cindex @code{GNAT.Strings} (@file{g-string.ads}) 16721 16722@noindent 16723Common String access types and related subprograms. Basically it 16724defines a string access and an array of string access types. 16725 16726@node GNAT.String_Split (g-strspl.ads) 16727@section @code{GNAT.String_Split} (@file{g-strspl.ads}) 16728@cindex @code{GNAT.String_Split} (@file{g-strspl.ads}) 16729@cindex String splitter 16730 16731@noindent 16732Useful string manipulation routines: given a set of separators, split 16733a string wherever the separators appear, and provide direct access 16734to the resulting slices. This package is instantiated from 16735@code{GNAT.Array_Split}. 16736 16737@node GNAT.Table (g-table.ads) 16738@section @code{GNAT.Table} (@file{g-table.ads}) 16739@cindex @code{GNAT.Table} (@file{g-table.ads}) 16740@cindex Table implementation 16741@cindex Arrays, extendable 16742 16743@noindent 16744A generic package providing a single dimension array abstraction where the 16745length of the array can be dynamically modified. 16746 16747@noindent 16748This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, 16749except that this package declares a single instance of the table type, 16750while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be 16751used to define dynamic instances of the table. 16752 16753@node GNAT.Task_Lock (g-tasloc.ads) 16754@section @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) 16755@cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) 16756@cindex Task synchronization 16757@cindex Task locking 16758@cindex Locking 16759 16760@noindent 16761A very simple facility for locking and unlocking sections of code using a 16762single global task lock. Appropriate for use in situations where contention 16763between tasks is very rarely expected. 16764 16765@node GNAT.Time_Stamp (g-timsta.ads) 16766@section @code{GNAT.Time_Stamp} (@file{g-timsta.ads}) 16767@cindex @code{GNAT.Time_Stamp} (@file{g-timsta.ads}) 16768@cindex Time stamp 16769@cindex Current time 16770 16771@noindent 16772Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that 16773represents the current date and time in ISO 8601 format. This is a very simple 16774routine with minimal code and there are no dependencies on any other unit. 16775 16776@node GNAT.Threads (g-thread.ads) 16777@section @code{GNAT.Threads} (@file{g-thread.ads}) 16778@cindex @code{GNAT.Threads} (@file{g-thread.ads}) 16779@cindex Foreign threads 16780@cindex Threads, foreign 16781 16782@noindent 16783Provides facilities for dealing with foreign threads which need to be known 16784by the GNAT run-time system. Consult the documentation of this package for 16785further details if your program has threads that are created by a non-Ada 16786environment which then accesses Ada code. 16787 16788@node GNAT.Traceback (g-traceb.ads) 16789@section @code{GNAT.Traceback} (@file{g-traceb.ads}) 16790@cindex @code{GNAT.Traceback} (@file{g-traceb.ads}) 16791@cindex Trace back facilities 16792 16793@noindent 16794Provides a facility for obtaining non-symbolic traceback information, useful 16795in various debugging situations. 16796 16797@node GNAT.Traceback.Symbolic (g-trasym.ads) 16798@section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) 16799@cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) 16800@cindex Trace back facilities 16801 16802@node GNAT.UTF_32 (g-utf_32.ads) 16803@section @code{GNAT.UTF_32} (@file{g-table.ads}) 16804@cindex @code{GNAT.UTF_32} (@file{g-table.ads}) 16805@cindex Wide character codes 16806 16807@noindent 16808This is a package intended to be used in conjunction with the 16809@code{Wide_Character} type in Ada 95 and the 16810@code{Wide_Wide_Character} type in Ada 2005 (available 16811in @code{GNAT} in Ada 2005 mode). This package contains 16812Unicode categorization routines, as well as lexical 16813categorization routines corresponding to the Ada 2005 16814lexical rules for identifiers and strings, and also a 16815lower case to upper case fold routine corresponding to 16816the Ada 2005 rules for identifier equivalence. 16817 16818@node GNAT.UTF_32_Spelling_Checker (g-u3spch.ads) 16819@section @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads}) 16820@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads}) 16821@cindex Spell checking 16822 16823@noindent 16824Provides a function for determining whether one wide wide string is a plausible 16825near misspelling of another wide wide string, where the strings are represented 16826using the UTF_32_String type defined in System.Wch_Cnv. 16827 16828@node GNAT.Wide_Spelling_Checker (g-wispch.ads) 16829@section @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads}) 16830@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads}) 16831@cindex Spell checking 16832 16833@noindent 16834Provides a function for determining whether one wide string is a plausible 16835near misspelling of another wide string. 16836 16837@node GNAT.Wide_String_Split (g-wistsp.ads) 16838@section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) 16839@cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) 16840@cindex Wide_String splitter 16841 16842@noindent 16843Useful wide string manipulation routines: given a set of separators, split 16844a wide string wherever the separators appear, and provide direct access 16845to the resulting slices. This package is instantiated from 16846@code{GNAT.Array_Split}. 16847 16848@node GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) 16849@section @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads}) 16850@cindex @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads}) 16851@cindex Spell checking 16852 16853@noindent 16854Provides a function for determining whether one wide wide string is a plausible 16855near misspelling of another wide wide string. 16856 16857@node GNAT.Wide_Wide_String_Split (g-zistsp.ads) 16858@section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads}) 16859@cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads}) 16860@cindex Wide_Wide_String splitter 16861 16862@noindent 16863Useful wide wide string manipulation routines: given a set of separators, split 16864a wide wide string wherever the separators appear, and provide direct access 16865to the resulting slices. This package is instantiated from 16866@code{GNAT.Array_Split}. 16867 16868@node Interfaces.C.Extensions (i-cexten.ads) 16869@section @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) 16870@cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) 16871 16872@noindent 16873This package contains additional C-related definitions, intended 16874for use with either manually or automatically generated bindings 16875to C libraries. 16876 16877@node Interfaces.C.Streams (i-cstrea.ads) 16878@section @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) 16879@cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) 16880@cindex C streams, interfacing 16881 16882@noindent 16883This package is a binding for the most commonly used operations 16884on C streams. 16885 16886@node Interfaces.CPP (i-cpp.ads) 16887@section @code{Interfaces.CPP} (@file{i-cpp.ads}) 16888@cindex @code{Interfaces.CPP} (@file{i-cpp.ads}) 16889@cindex C++ interfacing 16890@cindex Interfacing, to C++ 16891 16892@noindent 16893This package provides facilities for use in interfacing to C++. It 16894is primarily intended to be used in connection with automated tools 16895for the generation of C++ interfaces. 16896 16897@node Interfaces.Packed_Decimal (i-pacdec.ads) 16898@section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) 16899@cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) 16900@cindex IBM Packed Format 16901@cindex Packed Decimal 16902 16903@noindent 16904This package provides a set of routines for conversions to and 16905from a packed decimal format compatible with that used on IBM 16906mainframes. 16907 16908@node Interfaces.VxWorks (i-vxwork.ads) 16909@section @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) 16910@cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) 16911@cindex Interfacing to VxWorks 16912@cindex VxWorks, interfacing 16913 16914@noindent 16915This package provides a limited binding to the VxWorks API. 16916In particular, it interfaces with the 16917VxWorks hardware interrupt facilities. 16918 16919@node Interfaces.VxWorks.IO (i-vxwoio.ads) 16920@section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) 16921@cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) 16922@cindex Interfacing to VxWorks' I/O 16923@cindex VxWorks, I/O interfacing 16924@cindex VxWorks, Get_Immediate 16925@cindex Get_Immediate, VxWorks 16926 16927@noindent 16928This package provides a binding to the ioctl (IO/Control) 16929function of VxWorks, defining a set of option values and 16930function codes. A particular use of this package is 16931to enable the use of Get_Immediate under VxWorks. 16932 16933@node System.Address_Image (s-addima.ads) 16934@section @code{System.Address_Image} (@file{s-addima.ads}) 16935@cindex @code{System.Address_Image} (@file{s-addima.ads}) 16936@cindex Address image 16937@cindex Image, of an address 16938 16939@noindent 16940This function provides a useful debugging 16941function that gives an (implementation dependent) 16942string which identifies an address. 16943 16944@node System.Assertions (s-assert.ads) 16945@section @code{System.Assertions} (@file{s-assert.ads}) 16946@cindex @code{System.Assertions} (@file{s-assert.ads}) 16947@cindex Assertions 16948@cindex Assert_Failure, exception 16949 16950@noindent 16951This package provides the declaration of the exception raised 16952by an run-time assertion failure, as well as the routine that 16953is used internally to raise this assertion. 16954 16955@node System.Memory (s-memory.ads) 16956@section @code{System.Memory} (@file{s-memory.ads}) 16957@cindex @code{System.Memory} (@file{s-memory.ads}) 16958@cindex Memory allocation 16959 16960@noindent 16961This package provides the interface to the low level routines used 16962by the generated code for allocation and freeing storage for the 16963default storage pool (analogous to the C routines malloc and free. 16964It also provides a reallocation interface analogous to the C routine 16965realloc. The body of this unit may be modified to provide alternative 16966allocation mechanisms for the default pool, and in addition, direct 16967calls to this unit may be made for low level allocation uses (for 16968example see the body of @code{GNAT.Tables}). 16969 16970@node System.Partition_Interface (s-parint.ads) 16971@section @code{System.Partition_Interface} (@file{s-parint.ads}) 16972@cindex @code{System.Partition_Interface} (@file{s-parint.ads}) 16973@cindex Partition interfacing functions 16974 16975@noindent 16976This package provides facilities for partition interfacing. It 16977is used primarily in a distribution context when using Annex E 16978with @code{GLADE}. 16979 16980@node System.Pool_Global (s-pooglo.ads) 16981@section @code{System.Pool_Global} (@file{s-pooglo.ads}) 16982@cindex @code{System.Pool_Global} (@file{s-pooglo.ads}) 16983@cindex Storage pool, global 16984@cindex Global storage pool 16985 16986@noindent 16987This package provides a storage pool that is equivalent to the default 16988storage pool used for access types for which no pool is specifically 16989declared. It uses malloc/free to allocate/free and does not attempt to 16990do any automatic reclamation. 16991 16992@node System.Pool_Local (s-pooloc.ads) 16993@section @code{System.Pool_Local} (@file{s-pooloc.ads}) 16994@cindex @code{System.Pool_Local} (@file{s-pooloc.ads}) 16995@cindex Storage pool, local 16996@cindex Local storage pool 16997 16998@noindent 16999This package provides a storage pool that is intended for use with locally 17000defined access types. It uses malloc/free for allocate/free, and maintains 17001a list of allocated blocks, so that all storage allocated for the pool can 17002be freed automatically when the pool is finalized. 17003 17004@node System.Restrictions (s-restri.ads) 17005@section @code{System.Restrictions} (@file{s-restri.ads}) 17006@cindex @code{System.Restrictions} (@file{s-restri.ads}) 17007@cindex Run-time restrictions access 17008 17009@noindent 17010This package provides facilities for accessing at run time 17011the status of restrictions specified at compile time for 17012the partition. Information is available both with regard 17013to actual restrictions specified, and with regard to 17014compiler determined information on which restrictions 17015are violated by one or more packages in the partition. 17016 17017@node System.Rident (s-rident.ads) 17018@section @code{System.Rident} (@file{s-rident.ads}) 17019@cindex @code{System.Rident} (@file{s-rident.ads}) 17020@cindex Restrictions definitions 17021 17022@noindent 17023This package provides definitions of the restrictions 17024identifiers supported by GNAT, and also the format of 17025the restrictions provided in package System.Restrictions. 17026It is not normally necessary to @code{with} this generic package 17027since the necessary instantiation is included in 17028package System.Restrictions. 17029 17030@node System.Strings.Stream_Ops (s-ststop.ads) 17031@section @code{System.Strings.Stream_Ops} (@file{s-ststop.ads}) 17032@cindex @code{System.Strings.Stream_Ops} (@file{s-ststop.ads}) 17033@cindex Stream operations 17034@cindex String stream operations 17035 17036@noindent 17037This package provides a set of stream subprograms for standard string types. 17038It is intended primarily to support implicit use of such subprograms when 17039stream attributes are applied to string types, but the subprograms in this 17040package can be used directly by application programs. 17041 17042@node System.Task_Info (s-tasinf.ads) 17043@section @code{System.Task_Info} (@file{s-tasinf.ads}) 17044@cindex @code{System.Task_Info} (@file{s-tasinf.ads}) 17045@cindex Task_Info pragma 17046 17047@noindent 17048This package provides target dependent functionality that is used 17049to support the @code{Task_Info} pragma 17050 17051@node System.Wch_Cnv (s-wchcnv.ads) 17052@section @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) 17053@cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) 17054@cindex Wide Character, Representation 17055@cindex Wide String, Conversion 17056@cindex Representation of wide characters 17057 17058@noindent 17059This package provides routines for converting between 17060wide and wide wide characters and a representation as a value of type 17061@code{Standard.String}, using a specified wide character 17062encoding method. It uses definitions in 17063package @code{System.Wch_Con}. 17064 17065@node System.Wch_Con (s-wchcon.ads) 17066@section @code{System.Wch_Con} (@file{s-wchcon.ads}) 17067@cindex @code{System.Wch_Con} (@file{s-wchcon.ads}) 17068 17069@noindent 17070This package provides definitions and descriptions of 17071the various methods used for encoding wide characters 17072in ordinary strings. These definitions are used by 17073the package @code{System.Wch_Cnv}. 17074 17075@node Interfacing to Other Languages 17076@chapter Interfacing to Other Languages 17077@noindent 17078The facilities in annex B of the Ada Reference Manual are fully 17079implemented in GNAT, and in addition, a full interface to C++ is 17080provided. 17081 17082@menu 17083* Interfacing to C:: 17084* Interfacing to C++:: 17085* Interfacing to COBOL:: 17086* Interfacing to Fortran:: 17087* Interfacing to non-GNAT Ada code:: 17088@end menu 17089 17090@node Interfacing to C 17091@section Interfacing to C 17092 17093@noindent 17094Interfacing to C with GNAT can use one of two approaches: 17095 17096@itemize @bullet 17097@item 17098The types in the package @code{Interfaces.C} may be used. 17099@item 17100Standard Ada types may be used directly. This may be less portable to 17101other compilers, but will work on all GNAT compilers, which guarantee 17102correspondence between the C and Ada types. 17103@end itemize 17104 17105@noindent 17106Pragma @code{Convention C} may be applied to Ada types, but mostly has no 17107effect, since this is the default. The following table shows the 17108correspondence between Ada scalar types and the corresponding C types. 17109 17110@table @code 17111@item Integer 17112@code{int} 17113@item Short_Integer 17114@code{short} 17115@item Short_Short_Integer 17116@code{signed char} 17117@item Long_Integer 17118@code{long} 17119@item Long_Long_Integer 17120@code{long long} 17121@item Short_Float 17122@code{float} 17123@item Float 17124@code{float} 17125@item Long_Float 17126@code{double} 17127@item Long_Long_Float 17128This is the longest floating-point type supported by the hardware. 17129@end table 17130 17131@noindent 17132Additionally, there are the following general correspondences between Ada 17133and C types: 17134@itemize @bullet 17135@item 17136Ada enumeration types map to C enumeration types directly if pragma 17137@code{Convention C} is specified, which causes them to have int 17138length. Without pragma @code{Convention C}, Ada enumeration types map to 171398, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short}, 17140@code{int}, respectively) depending on the number of values passed. 17141This is the only case in which pragma @code{Convention C} affects the 17142representation of an Ada type. 17143 17144@item 17145Ada access types map to C pointers, except for the case of pointers to 17146unconstrained types in Ada, which have no direct C equivalent. 17147 17148@item 17149Ada arrays map directly to C arrays. 17150 17151@item 17152Ada records map directly to C structures. 17153 17154@item 17155Packed Ada records map to C structures where all members are bit fields 17156of the length corresponding to the @code{@var{type}'Size} value in Ada. 17157@end itemize 17158 17159@node Interfacing to C++ 17160@section Interfacing to C++ 17161 17162@noindent 17163The interface to C++ makes use of the following pragmas, which are 17164primarily intended to be constructed automatically using a binding generator 17165tool, although it is possible to construct them by hand. 17166 17167Using these pragmas it is possible to achieve complete 17168inter-operability between Ada tagged types and C++ class definitions. 17169See @ref{Implementation Defined Pragmas}, for more details. 17170 17171@table @code 17172@item pragma CPP_Class ([Entity =>] @var{LOCAL_NAME}) 17173The argument denotes an entity in the current declarative region that is 17174declared as a tagged or untagged record type. It indicates that the type 17175corresponds to an externally declared C++ class type, and is to be laid 17176out the same way that C++ would lay out the type. 17177 17178Note: Pragma @code{CPP_Class} is currently obsolete. It is supported 17179for backward compatibility but its functionality is available 17180using pragma @code{Import} with @code{Convention} = @code{CPP}. 17181 17182@item pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME}) 17183This pragma identifies an imported function (imported in the usual way 17184with pragma @code{Import}) as corresponding to a C++ constructor. 17185@end table 17186 17187A few restrictions are placed on the use of the @code{Access} attribute 17188in conjunction with subprograms subject to convention @code{CPP}: the 17189attribute may be used neither on primitive operations of a tagged 17190record type with convention @code{CPP}, imported or not, nor on 17191subprograms imported with pragma @code{CPP_Constructor}. 17192 17193In addition, C++ exceptions are propagated and can be handled in an 17194@code{others} choice of an exception handler. The corresponding Ada 17195occurrence has no message, and the simple name of the exception identity 17196contains @samp{Foreign_Exception}. Finalization and awaiting dependent 17197tasks works properly when such foreign exceptions are propagated. 17198 17199@node Interfacing to COBOL 17200@section Interfacing to COBOL 17201 17202@noindent 17203Interfacing to COBOL is achieved as described in section B.4 of 17204the Ada Reference Manual. 17205 17206@node Interfacing to Fortran 17207@section Interfacing to Fortran 17208 17209@noindent 17210Interfacing to Fortran is achieved as described in section B.5 of the 17211Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a 17212multi-dimensional array causes the array to be stored in column-major 17213order as required for convenient interface to Fortran. 17214 17215@node Interfacing to non-GNAT Ada code 17216@section Interfacing to non-GNAT Ada code 17217 17218It is possible to specify the convention @code{Ada} in a pragma 17219@code{Import} or pragma @code{Export}. However this refers to 17220the calling conventions used by GNAT, which may or may not be 17221similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 17222compiler to allow interoperation. 17223 17224If arguments types are kept simple, and if the foreign compiler generally 17225follows system calling conventions, then it may be possible to integrate 17226files compiled by other Ada compilers, provided that the elaboration 17227issues are adequately addressed (for example by eliminating the 17228need for any load time elaboration). 17229 17230In particular, GNAT running on VMS is designed to 17231be highly compatible with the DEC Ada 83 compiler, so this is one 17232case in which it is possible to import foreign units of this type, 17233provided that the data items passed are restricted to simple scalar 17234values or simple record types without variants, or simple array 17235types with fixed bounds. 17236 17237@node Specialized Needs Annexes 17238@chapter Specialized Needs Annexes 17239 17240@noindent 17241Ada 95 and Ada 2005 define a number of Specialized Needs Annexes, which are not 17242required in all implementations. However, as described in this chapter, 17243GNAT implements all of these annexes: 17244 17245@table @asis 17246@item Systems Programming (Annex C) 17247The Systems Programming Annex is fully implemented. 17248 17249@item Real-Time Systems (Annex D) 17250The Real-Time Systems Annex is fully implemented. 17251 17252@item Distributed Systems (Annex E) 17253Stub generation is fully implemented in the GNAT compiler. In addition, 17254a complete compatible PCS is available as part of the GLADE system, 17255a separate product. When the two 17256products are used in conjunction, this annex is fully implemented. 17257 17258@item Information Systems (Annex F) 17259The Information Systems annex is fully implemented. 17260 17261@item Numerics (Annex G) 17262The Numerics Annex is fully implemented. 17263 17264@item Safety and Security / High-Integrity Systems (Annex H) 17265The Safety and Security Annex (termed the High-Integrity Systems Annex 17266in Ada 2005) is fully implemented. 17267@end table 17268 17269@node Implementation of Specific Ada Features 17270@chapter Implementation of Specific Ada Features 17271 17272@noindent 17273This chapter describes the GNAT implementation of several Ada language 17274facilities. 17275 17276@menu 17277* Machine Code Insertions:: 17278* GNAT Implementation of Tasking:: 17279* GNAT Implementation of Shared Passive Packages:: 17280* Code Generation for Array Aggregates:: 17281* The Size of Discriminated Records with Default Discriminants:: 17282* Strict Conformance to the Ada Reference Manual:: 17283@end menu 17284 17285@node Machine Code Insertions 17286@section Machine Code Insertions 17287@cindex Machine Code insertions 17288 17289@noindent 17290Package @code{Machine_Code} provides machine code support as described 17291in the Ada Reference Manual in two separate forms: 17292@itemize @bullet 17293@item 17294Machine code statements, consisting of qualified expressions that 17295fit the requirements of RM section 13.8. 17296@item 17297An intrinsic callable procedure, providing an alternative mechanism of 17298including machine instructions in a subprogram. 17299@end itemize 17300 17301@noindent 17302The two features are similar, and both are closely related to the mechanism 17303provided by the asm instruction in the GNU C compiler. Full understanding 17304and use of the facilities in this package requires understanding the asm 17305instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression 17306Operands, gcc, Using the GNU Compiler Collection (GCC)}. 17307 17308Calls to the function @code{Asm} and the procedure @code{Asm} have identical 17309semantic restrictions and effects as described below. Both are provided so 17310that the procedure call can be used as a statement, and the function call 17311can be used to form a code_statement. 17312 17313The first example given in the GCC documentation is the C @code{asm} 17314instruction: 17315@smallexample 17316 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 17317@end smallexample 17318 17319@noindent 17320The equivalent can be written for GNAT as: 17321 17322@smallexample @c ada 17323Asm ("fsinx %1 %0", 17324 My_Float'Asm_Output ("=f", result), 17325 My_Float'Asm_Input ("f", angle)); 17326@end smallexample 17327 17328@noindent 17329The first argument to @code{Asm} is the assembler template, and is 17330identical to what is used in GNU C@. This string must be a static 17331expression. The second argument is the output operand list. It is 17332either a single @code{Asm_Output} attribute reference, or a list of such 17333references enclosed in parentheses (technically an array aggregate of 17334such references). 17335 17336The @code{Asm_Output} attribute denotes a function that takes two 17337parameters. The first is a string, the second is the name of a variable 17338of the type designated by the attribute prefix. The first (string) 17339argument is required to be a static expression and designates the 17340constraint for the parameter (e.g.@: what kind of register is 17341required). The second argument is the variable to be updated with the 17342result. The possible values for constraint are the same as those used in 17343the RTL, and are dependent on the configuration file used to build the 17344GCC back end. If there are no output operands, then this argument may 17345either be omitted, or explicitly given as @code{No_Output_Operands}. 17346 17347The second argument of @code{@var{my_float}'Asm_Output} functions as 17348though it were an @code{out} parameter, which is a little curious, but 17349all names have the form of expressions, so there is no syntactic 17350irregularity, even though normally functions would not be permitted 17351@code{out} parameters. The third argument is the list of input 17352operands. It is either a single @code{Asm_Input} attribute reference, or 17353a list of such references enclosed in parentheses (technically an array 17354aggregate of such references). 17355 17356The @code{Asm_Input} attribute denotes a function that takes two 17357parameters. The first is a string, the second is an expression of the 17358type designated by the prefix. The first (string) argument is required 17359to be a static expression, and is the constraint for the parameter, 17360(e.g.@: what kind of register is required). The second argument is the 17361value to be used as the input argument. The possible values for the 17362constant are the same as those used in the RTL, and are dependent on 17363the configuration file used to built the GCC back end. 17364 17365If there are no input operands, this argument may either be omitted, or 17366explicitly given as @code{No_Input_Operands}. The fourth argument, not 17367present in the above example, is a list of register names, called the 17368@dfn{clobber} argument. This argument, if given, must be a static string 17369expression, and is a space or comma separated list of names of registers 17370that must be considered destroyed as a result of the @code{Asm} call. If 17371this argument is the null string (the default value), then the code 17372generator assumes that no additional registers are destroyed. 17373 17374The fifth argument, not present in the above example, called the 17375@dfn{volatile} argument, is by default @code{False}. It can be set to 17376the literal value @code{True} to indicate to the code generator that all 17377optimizations with respect to the instruction specified should be 17378suppressed, and that in particular, for an instruction that has outputs, 17379the instruction will still be generated, even if none of the outputs are 17380used. @xref{Extended Asm,, Assembler Instructions with C Expression Operands, 17381gcc, Using the GNU Compiler Collection (GCC)}, for the full description. 17382Generally it is strongly advisable to use Volatile for any ASM statement 17383that is missing either input or output operands, or when two or more ASM 17384statements appear in sequence, to avoid unwanted optimizations. A warning 17385is generated if this advice is not followed. 17386 17387The @code{Asm} subprograms may be used in two ways. First the procedure 17388forms can be used anywhere a procedure call would be valid, and 17389correspond to what the RM calls ``intrinsic'' routines. Such calls can 17390be used to intersperse machine instructions with other Ada statements. 17391Second, the function forms, which return a dummy value of the limited 17392private type @code{Asm_Insn}, can be used in code statements, and indeed 17393this is the only context where such calls are allowed. Code statements 17394appear as aggregates of the form: 17395 17396@smallexample @c ada 17397Asm_Insn'(Asm (@dots{})); 17398Asm_Insn'(Asm_Volatile (@dots{})); 17399@end smallexample 17400 17401@noindent 17402In accordance with RM rules, such code statements are allowed only 17403within subprograms whose entire body consists of such statements. It is 17404not permissible to intermix such statements with other Ada statements. 17405 17406Typically the form using intrinsic procedure calls is more convenient 17407and more flexible. The code statement form is provided to meet the RM 17408suggestion that such a facility should be made available. The following 17409is the exact syntax of the call to @code{Asm}. As usual, if named notation 17410is used, the arguments may be given in arbitrary order, following the 17411normal rules for use of positional and named arguments) 17412 17413@smallexample 17414ASM_CALL ::= Asm ( 17415 [Template =>] static_string_EXPRESSION 17416 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 17417 [,[Inputs =>] INPUT_OPERAND_LIST ] 17418 [,[Clobber =>] static_string_EXPRESSION ] 17419 [,[Volatile =>] static_boolean_EXPRESSION] ) 17420 17421OUTPUT_OPERAND_LIST ::= 17422 [PREFIX.]No_Output_Operands 17423| OUTPUT_OPERAND_ATTRIBUTE 17424| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 17425 17426OUTPUT_OPERAND_ATTRIBUTE ::= 17427 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 17428 17429INPUT_OPERAND_LIST ::= 17430 [PREFIX.]No_Input_Operands 17431| INPUT_OPERAND_ATTRIBUTE 17432| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 17433 17434INPUT_OPERAND_ATTRIBUTE ::= 17435 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 17436@end smallexample 17437 17438@noindent 17439The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} 17440are declared in the package @code{Machine_Code} and must be referenced 17441according to normal visibility rules. In particular if there is no 17442@code{use} clause for this package, then appropriate package name 17443qualification is required. 17444 17445@node GNAT Implementation of Tasking 17446@section GNAT Implementation of Tasking 17447 17448@noindent 17449This chapter outlines the basic GNAT approach to tasking (in particular, 17450a multi-layered library for portability) and discusses issues related 17451to compliance with the Real-Time Systems Annex. 17452 17453@menu 17454* Mapping Ada Tasks onto the Underlying Kernel Threads:: 17455* Ensuring Compliance with the Real-Time Annex:: 17456@end menu 17457 17458@node Mapping Ada Tasks onto the Underlying Kernel Threads 17459@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 17460 17461@noindent 17462GNAT's run-time support comprises two layers: 17463 17464@itemize @bullet 17465@item GNARL (GNAT Run-time Layer) 17466@item GNULL (GNAT Low-level Library) 17467@end itemize 17468 17469@noindent 17470In GNAT, Ada's tasking services rely on a platform and OS independent 17471layer known as GNARL@. This code is responsible for implementing the 17472correct semantics of Ada's task creation, rendezvous, protected 17473operations etc. 17474 17475GNARL decomposes Ada's tasking semantics into simpler lower level 17476operations such as create a thread, set the priority of a thread, 17477yield, create a lock, lock/unlock, etc. The spec for these low-level 17478operations constitutes GNULLI, the GNULL Interface. This interface is 17479directly inspired from the POSIX real-time API@. 17480 17481If the underlying executive or OS implements the POSIX standard 17482faithfully, the GNULL Interface maps as is to the services offered by 17483the underlying kernel. Otherwise, some target dependent glue code maps 17484the services offered by the underlying kernel to the semantics expected 17485by GNARL@. 17486 17487Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the 17488key point is that each Ada task is mapped on a thread in the underlying 17489kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 17490 17491In addition Ada task priorities map onto the underlying thread priorities. 17492Mapping Ada tasks onto the underlying kernel threads has several advantages: 17493 17494@itemize @bullet 17495@item 17496The underlying scheduler is used to schedule the Ada tasks. This 17497makes Ada tasks as efficient as kernel threads from a scheduling 17498standpoint. 17499 17500@item 17501Interaction with code written in C containing threads is eased 17502since at the lowest level Ada tasks and C threads map onto the same 17503underlying kernel concept. 17504 17505@item 17506When an Ada task is blocked during I/O the remaining Ada tasks are 17507able to proceed. 17508 17509@item 17510On multiprocessor systems Ada tasks can execute in parallel. 17511@end itemize 17512 17513@noindent 17514Some threads libraries offer a mechanism to fork a new process, with the 17515child process duplicating the threads from the parent. 17516GNAT does not 17517support this functionality when the parent contains more than one task. 17518@cindex Forking a new process 17519 17520@node Ensuring Compliance with the Real-Time Annex 17521@subsection Ensuring Compliance with the Real-Time Annex 17522@cindex Real-Time Systems Annex compliance 17523 17524@noindent 17525Although mapping Ada tasks onto 17526the underlying threads has significant advantages, it does create some 17527complications when it comes to respecting the scheduling semantics 17528specified in the real-time annex (Annex D). 17529 17530For instance the Annex D requirement for the @code{FIFO_Within_Priorities} 17531scheduling policy states: 17532 17533@quotation 17534@emph{When the active priority of a ready task that is not running 17535changes, or the setting of its base priority takes effect, the 17536task is removed from the ready queue for its old active priority 17537and is added at the tail of the ready queue for its new active 17538priority, except in the case where the active priority is lowered 17539due to the loss of inherited priority, in which case the task is 17540added at the head of the ready queue for its new active priority.} 17541@end quotation 17542 17543@noindent 17544While most kernels do put tasks at the end of the priority queue when 17545a task changes its priority, (which respects the main 17546FIFO_Within_Priorities requirement), almost none keep a thread at the 17547beginning of its priority queue when its priority drops from the loss 17548of inherited priority. 17549 17550As a result most vendors have provided incomplete Annex D implementations. 17551 17552The GNAT run-time, has a nice cooperative solution to this problem 17553which ensures that accurate FIFO_Within_Priorities semantics are 17554respected. 17555 17556The principle is as follows. When an Ada task T is about to start 17557running, it checks whether some other Ada task R with the same 17558priority as T has been suspended due to the loss of priority 17559inheritance. If this is the case, T yields and is placed at the end of 17560its priority queue. When R arrives at the front of the queue it 17561executes. 17562 17563Note that this simple scheme preserves the relative order of the tasks 17564that were ready to execute in the priority queue where R has been 17565placed at the end. 17566 17567@node GNAT Implementation of Shared Passive Packages 17568@section GNAT Implementation of Shared Passive Packages 17569@cindex Shared passive packages 17570 17571@noindent 17572GNAT fully implements the pragma @code{Shared_Passive} for 17573@cindex pragma @code{Shared_Passive} 17574the purpose of designating shared passive packages. 17575This allows the use of passive partitions in the 17576context described in the Ada Reference Manual; i.e., for communication 17577between separate partitions of a distributed application using the 17578features in Annex E. 17579@cindex Annex E 17580@cindex Distribution Systems Annex 17581 17582However, the implementation approach used by GNAT provides for more 17583extensive usage as follows: 17584 17585@table @emph 17586@item Communication between separate programs 17587 17588This allows separate programs to access the data in passive 17589partitions, using protected objects for synchronization where 17590needed. The only requirement is that the two programs have a 17591common shared file system. It is even possible for programs 17592running on different machines with different architectures 17593(e.g.@: different endianness) to communicate via the data in 17594a passive partition. 17595 17596@item Persistence between program runs 17597 17598The data in a passive package can persist from one run of a 17599program to another, so that a later program sees the final 17600values stored by a previous run of the same program. 17601 17602@end table 17603 17604@noindent 17605The implementation approach used is to store the data in files. A 17606separate stream file is created for each object in the package, and 17607an access to an object causes the corresponding file to be read or 17608written. 17609 17610The environment variable @code{SHARED_MEMORY_DIRECTORY} should be 17611@cindex @code{SHARED_MEMORY_DIRECTORY} environment variable 17612set to the directory to be used for these files. 17613The files in this directory 17614have names that correspond to their fully qualified names. For 17615example, if we have the package 17616 17617@smallexample @c ada 17618package X is 17619 pragma Shared_Passive (X); 17620 Y : Integer; 17621 Z : Float; 17622end X; 17623@end smallexample 17624 17625@noindent 17626and the environment variable is set to @code{/stemp/}, then the files created 17627will have the names: 17628 17629@smallexample 17630/stemp/x.y 17631/stemp/x.z 17632@end smallexample 17633 17634@noindent 17635These files are created when a value is initially written to the object, and 17636the files are retained until manually deleted. This provides the persistence 17637semantics. If no file exists, it means that no partition has assigned a value 17638to the variable; in this case the initial value declared in the package 17639will be used. This model ensures that there are no issues in synchronizing 17640the elaboration process, since elaboration of passive packages elaborates the 17641initial values, but does not create the files. 17642 17643The files are written using normal @code{Stream_IO} access. 17644If you want to be able 17645to communicate between programs or partitions running on different 17646architectures, then you should use the XDR versions of the stream attribute 17647routines, since these are architecture independent. 17648 17649If active synchronization is required for access to the variables in the 17650shared passive package, then as described in the Ada Reference Manual, the 17651package may contain protected objects used for this purpose. In this case 17652a lock file (whose name is @file{___lock} (three underscores) 17653is created in the shared memory directory. 17654@cindex @file{___lock} file (for shared passive packages) 17655This is used to provide the required locking 17656semantics for proper protected object synchronization. 17657 17658As of January 2003, GNAT supports shared passive packages on all platforms 17659except for OpenVMS. 17660 17661@node Code Generation for Array Aggregates 17662@section Code Generation for Array Aggregates 17663 17664@menu 17665* Static constant aggregates with static bounds:: 17666* Constant aggregates with unconstrained nominal types:: 17667* Aggregates with static bounds:: 17668* Aggregates with non-static bounds:: 17669* Aggregates in assignment statements:: 17670@end menu 17671 17672@noindent 17673Aggregates have a rich syntax and allow the user to specify the values of 17674complex data structures by means of a single construct. As a result, the 17675code generated for aggregates can be quite complex and involve loops, case 17676statements and multiple assignments. In the simplest cases, however, the 17677compiler will recognize aggregates whose components and constraints are 17678fully static, and in those cases the compiler will generate little or no 17679executable code. The following is an outline of the code that GNAT generates 17680for various aggregate constructs. For further details, you will find it 17681useful to examine the output produced by the -gnatG flag to see the expanded 17682source that is input to the code generator. You may also want to examine 17683the assembly code generated at various levels of optimization. 17684 17685The code generated for aggregates depends on the context, the component values, 17686and the type. In the context of an object declaration the code generated is 17687generally simpler than in the case of an assignment. As a general rule, static 17688component values and static subtypes also lead to simpler code. 17689 17690@node Static constant aggregates with static bounds 17691@subsection Static constant aggregates with static bounds 17692 17693@noindent 17694For the declarations: 17695@smallexample @c ada 17696 type One_Dim is array (1..10) of integer; 17697 ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 17698@end smallexample 17699 17700@noindent 17701GNAT generates no executable code: the constant ar0 is placed in static memory. 17702The same is true for constant aggregates with named associations: 17703 17704@smallexample @c ada 17705 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); 17706 Cr3 : constant One_Dim := (others => 7777); 17707@end smallexample 17708 17709@noindent 17710The same is true for multidimensional constant arrays such as: 17711 17712@smallexample @c ada 17713 type two_dim is array (1..3, 1..3) of integer; 17714 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 17715@end smallexample 17716 17717@noindent 17718The same is true for arrays of one-dimensional arrays: the following are 17719static: 17720 17721@smallexample @c ada 17722type ar1b is array (1..3) of boolean; 17723type ar_ar is array (1..3) of ar1b; 17724None : constant ar1b := (others => false); -- fully static 17725None2 : constant ar_ar := (1..3 => None); -- fully static 17726@end smallexample 17727 17728@noindent 17729However, for multidimensional aggregates with named associations, GNAT will 17730generate assignments and loops, even if all associations are static. The 17731following two declarations generate a loop for the first dimension, and 17732individual component assignments for the second dimension: 17733 17734@smallexample @c ada 17735Zero1: constant two_dim := (1..3 => (1..3 => 0)); 17736Zero2: constant two_dim := (others => (others => 0)); 17737@end smallexample 17738 17739@node Constant aggregates with unconstrained nominal types 17740@subsection Constant aggregates with unconstrained nominal types 17741 17742@noindent 17743In such cases the aggregate itself establishes the subtype, so that 17744associations with @code{others} cannot be used. GNAT determines the 17745bounds for the actual subtype of the aggregate, and allocates the 17746aggregate statically as well. No code is generated for the following: 17747 17748@smallexample @c ada 17749 type One_Unc is array (natural range <>) of integer; 17750 Cr_Unc : constant One_Unc := (12,24,36); 17751@end smallexample 17752 17753@node Aggregates with static bounds 17754@subsection Aggregates with static bounds 17755 17756@noindent 17757In all previous examples the aggregate was the initial (and immutable) value 17758of a constant. If the aggregate initializes a variable, then code is generated 17759for it as a combination of individual assignments and loops over the target 17760object. The declarations 17761 17762@smallexample @c ada 17763 Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); 17764 Cr_Var2 : One_Dim := (others > -1); 17765@end smallexample 17766 17767@noindent 17768generate the equivalent of 17769 17770@smallexample @c ada 17771 Cr_Var1 (1) := 2; 17772 Cr_Var1 (2) := 3; 17773 Cr_Var1 (3) := 5; 17774 Cr_Var1 (4) := 11; 17775 17776 for I in Cr_Var2'range loop 17777 Cr_Var2 (I) := -1; 17778 end loop; 17779@end smallexample 17780 17781@node Aggregates with non-static bounds 17782@subsection Aggregates with non-static bounds 17783 17784@noindent 17785If the bounds of the aggregate are not statically compatible with the bounds 17786of the nominal subtype of the target, then constraint checks have to be 17787generated on the bounds. For a multidimensional array, constraint checks may 17788have to be applied to sub-arrays individually, if they do not have statically 17789compatible subtypes. 17790 17791@node Aggregates in assignment statements 17792@subsection Aggregates in assignment statements 17793 17794@noindent 17795In general, aggregate assignment requires the construction of a temporary, 17796and a copy from the temporary to the target of the assignment. This is because 17797it is not always possible to convert the assignment into a series of individual 17798component assignments. For example, consider the simple case: 17799 17800@smallexample @c ada 17801 A := (A(2), A(1)); 17802@end smallexample 17803 17804@noindent 17805This cannot be converted into: 17806 17807@smallexample @c ada 17808 A(1) := A(2); 17809 A(2) := A(1); 17810@end smallexample 17811 17812@noindent 17813So the aggregate has to be built first in a separate location, and then 17814copied into the target. GNAT recognizes simple cases where this intermediate 17815step is not required, and the assignments can be performed in place, directly 17816into the target. The following sufficient criteria are applied: 17817 17818@itemize @bullet 17819@item 17820The bounds of the aggregate are static, and the associations are static. 17821@item 17822The components of the aggregate are static constants, names of 17823simple variables that are not renamings, or expressions not involving 17824indexed components whose operands obey these rules. 17825@end itemize 17826 17827@noindent 17828If any of these conditions are violated, the aggregate will be built in 17829a temporary (created either by the front-end or the code generator) and then 17830that temporary will be copied onto the target. 17831 17832@node The Size of Discriminated Records with Default Discriminants 17833@section The Size of Discriminated Records with Default Discriminants 17834 17835@noindent 17836If a discriminated type @code{T} has discriminants with default values, it is 17837possible to declare an object of this type without providing an explicit 17838constraint: 17839 17840@smallexample @c ada 17841@group 17842type Size is range 1..100; 17843 17844type Rec (D : Size := 15) is record 17845 Name : String (1..D); 17846end T; 17847 17848Word : Rec; 17849@end group 17850@end smallexample 17851 17852@noindent 17853Such an object is said to be @emph{unconstrained}. 17854The discriminant of the object 17855can be modified by a full assignment to the object, as long as it preserves the 17856relation between the value of the discriminant, and the value of the components 17857that depend on it: 17858 17859@smallexample @c ada 17860@group 17861Word := (3, "yes"); 17862 17863Word := (5, "maybe"); 17864 17865Word := (5, "no"); -- raises Constraint_Error 17866@end group 17867@end smallexample 17868 17869@noindent 17870In order to support this behavior efficiently, an unconstrained object is 17871given the maximum size that any value of the type requires. In the case 17872above, @code{Word} has storage for the discriminant and for 17873a @code{String} of length 100. 17874It is important to note that unconstrained objects do not require dynamic 17875allocation. It would be an improper implementation to place on the heap those 17876components whose size depends on discriminants. (This improper implementation 17877was used by some Ada83 compilers, where the @code{Name} component above 17878would have 17879been stored as a pointer to a dynamic string). Following the principle that 17880dynamic storage management should never be introduced implicitly, 17881an Ada compiler should reserve the full size for an unconstrained declared 17882object, and place it on the stack. 17883 17884This maximum size approach 17885has been a source of surprise to some users, who expect the default 17886values of the discriminants to determine the size reserved for an 17887unconstrained object: ``If the default is 15, why should the object occupy 17888a larger size?'' 17889The answer, of course, is that the discriminant may be later modified, 17890and its full range of values must be taken into account. This is why the 17891declaration: 17892 17893@smallexample 17894@group 17895type Rec (D : Positive := 15) is record 17896 Name : String (1..D); 17897end record; 17898 17899Too_Large : Rec; 17900@end group 17901@end smallexample 17902 17903@noindent 17904is flagged by the compiler with a warning: 17905an attempt to create @code{Too_Large} will raise @code{Storage_Error}, 17906because the required size includes @code{Positive'Last} 17907bytes. As the first example indicates, the proper approach is to declare an 17908index type of ``reasonable'' range so that unconstrained objects are not too 17909large. 17910 17911One final wrinkle: if the object is declared to be @code{aliased}, or if it is 17912created in the heap by means of an allocator, then it is @emph{not} 17913unconstrained: 17914it is constrained by the default values of the discriminants, and those values 17915cannot be modified by full assignment. This is because in the presence of 17916aliasing all views of the object (which may be manipulated by different tasks, 17917say) must be consistent, so it is imperative that the object, once created, 17918remain invariant. 17919 17920@node Strict Conformance to the Ada Reference Manual 17921@section Strict Conformance to the Ada Reference Manual 17922 17923@noindent 17924The dynamic semantics defined by the Ada Reference Manual impose a set of 17925run-time checks to be generated. By default, the GNAT compiler will insert many 17926run-time checks into the compiled code, including most of those required by the 17927Ada Reference Manual. However, there are three checks that are not enabled 17928in the default mode for efficiency reasons: arithmetic overflow checking for 17929integer operations (including division by zero), checks for access before 17930elaboration on subprogram calls, and stack overflow checking (most operating 17931systems do not perform this check by default). 17932 17933Strict conformance to the Ada Reference Manual can be achieved by adding 17934three compiler options for overflow checking for integer operations 17935(@option{-gnato}), dynamic checks for access-before-elaboration on subprogram 17936calls and generic instantiations (@option{-gnatE}), and stack overflow 17937checking (@option{-fstack-check}). 17938 17939Note that the result of a floating point arithmetic operation in overflow and 17940invalid situations, when the @code{Machine_Overflows} attribute of the result 17941type is @code{False}, is to generate IEEE NaN and infinite values. This is the 17942case for machines compliant with the IEEE floating-point standard, but on 17943machines that are not fully compliant with this standard, such as Alpha, the 17944@option{-mieee} compiler flag must be used for achieving IEEE confirming 17945behavior (although at the cost of a significant performance penalty), so 17946infinite and NaN values are properly generated. 17947 17948 17949@node Implementation of Ada 2012 Features 17950@chapter Implementation of Ada 2012 Features 17951@cindex Ada 2012 implementation status 17952 17953This chapter contains a complete list of Ada 2012 features that have been 17954implemented as of GNAT version 6.4. Generally, these features are only 17955available if the @option{-gnat12} (Ada 2012 features enabled) flag is set 17956@cindex @option{-gnat12} option 17957or if the configuration pragma @code{Ada_2012} is used. 17958@cindex pragma @code{Ada_2012} 17959@cindex configuration pragma @code{Ada_2012} 17960@cindex @code{Ada_2012} configuration pragma 17961However, new pragmas, attributes, and restrictions are 17962unconditionally available, since the Ada 95 standard allows the addition of 17963new pragmas, attributes, and restrictions (there are exceptions, which are 17964documented in the individual descriptions), and also certain packages 17965were made available in earlier versions of Ada. 17966 17967An ISO date (YYYY-MM-DD) appears in parentheses on the description line. 17968This date shows the implementation date of the feature. Any wavefront 17969subsequent to this date will contain the indicated feature, as will any 17970subsequent releases. A date of 0000-00-00 means that GNAT has always 17971implemented the feature, or implemented it as soon as it appeared as a 17972binding interpretation. 17973 17974Each feature corresponds to an Ada Issue (``AI'') approved by the Ada 17975standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. 17976The features are ordered based on the relevant sections of the Ada 17977Reference Manual (``RM''). When a given AI relates to multiple points 17978in the RM, the earliest is used. 17979 17980A complete description of the AIs may be found in 17981@url{www.ada-auth.org/ai05-summary.html}. 17982 17983@itemize @bullet 17984 17985@item 17986@emph{AI-0176 Quantified expressions (2010-09-29)} 17987@cindex AI-0176 (Ada 2012 feature) 17988 17989@noindent 17990 Both universally and existentially quantified expressions are implemented. 17991 They use the new syntax for iterators proposed in AI05-139-2, as well as 17992 the standard Ada loop syntax. 17993 17994@noindent 17995 RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) 17996 17997@item 17998@emph{AI-0079 Allow @i{other_format} characters in source (2010-07-10)} 17999@cindex AI-0079 (Ada 2012 feature) 18000 18001@noindent 18002 Wide characters in the unicode category @i{other_format} are now allowed in 18003 source programs between tokens, but not within a token such as an identifier. 18004 18005@noindent 18006 RM References: 2.01 (4/2) 2.02 (7) 18007 18008@item 18009@emph{AI-0091 Do not allow @i{other_format} in identifiers (0000-00-00)} 18010@cindex AI-0091 (Ada 2012 feature) 18011 18012@noindent 18013 Wide characters in the unicode category @i{other_format} are not permitted 18014 within an identifier, since this can be a security problem. The error 18015 message for this case has been improved to be more specific, but GNAT has 18016 never allowed such characters to appear in identifiers. 18017 18018@noindent 18019 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) 18020 18021@item 18022@emph{AI-0100 Placement of pragmas (2010-07-01)} 18023@cindex AI-0100 (Ada 2012 feature) 18024 18025@noindent 18026 This AI is an earlier version of AI-163. It simplifies the rules 18027 for legal placement of pragmas. In the case of lists that allow pragmas, if 18028 the list may have no elements, then the list may consist solely of pragmas. 18029 18030@noindent 18031 RM References: 2.08 (7) 18032 18033@item 18034@emph{AI-0163 Pragmas in place of null (2010-07-01)} 18035@cindex AI-0163 (Ada 2012 feature) 18036 18037@noindent 18038 A statement sequence may be composed entirely of pragmas. It is no longer 18039 necessary to add a dummy @code{null} statement to make the sequence legal. 18040 18041@noindent 18042 RM References: 2.08 (7) 2.08 (16) 18043 18044 18045@item 18046@emph{AI-0080 ``View of'' not needed if clear from context (0000-00-00)} 18047@cindex AI-0080 (Ada 2012 feature) 18048 18049@noindent 18050 This is an editorial change only, described as non-testable in the AI. 18051 18052@noindent 18053 RM References: 3.01 (7) 18054 18055 18056@item 18057@emph{AI-0183 Aspect specifications (2010-08-16)} 18058@cindex AI-0183 (Ada 2012 feature) 18059 18060@noindent 18061 Aspect specifications have been fully implemented except for pre and post- 18062 conditions, and type invariants, which have their own separate AI's. All 18063 forms of declarations listed in the AI are supported. The following is a 18064 list of the aspects supported (with GNAT implementation aspects marked) 18065 18066@multitable {@code{Preelaborable_Initialization}} {--GNAT} 18067@item @code{Ada_2005} @tab -- GNAT 18068@item @code{Ada_2012} @tab -- GNAT 18069@item @code{Address} @tab 18070@item @code{Alignment} @tab 18071@item @code{Atomic} @tab 18072@item @code{Atomic_Components} @tab 18073@item @code{Bit_Order} @tab 18074@item @code{Component_Size} @tab 18075@item @code{Contract_Case} @tab -- GNAT 18076@item @code{Discard_Names} @tab 18077@item @code{External_Tag} @tab 18078@item @code{Favor_Top_Level} @tab -- GNAT 18079@item @code{Inline} @tab 18080@item @code{Inline_Always} @tab -- GNAT 18081@item @code{Invariant} @tab -- GNAT 18082@item @code{Machine_Radix} @tab 18083@item @code{No_Return} @tab 18084@item @code{Object_Size} @tab -- GNAT 18085@item @code{Pack} @tab 18086@item @code{Persistent_BSS} @tab -- GNAT 18087@item @code{Post} @tab 18088@item @code{Pre} @tab 18089@item @code{Predicate} @tab 18090@item @code{Preelaborable_Initialization} @tab 18091@item @code{Pure_Function} @tab -- GNAT 18092@item @code{Remote_Access_Type} @tab -- GNAT 18093@item @code{Shared} @tab -- GNAT 18094@item @code{Size} @tab 18095@item @code{Storage_Pool} @tab 18096@item @code{Storage_Size} @tab 18097@item @code{Stream_Size} @tab 18098@item @code{Suppress} @tab 18099@item @code{Suppress_Debug_Info} @tab -- GNAT 18100@item @code{Test_Case} @tab -- GNAT 18101@item @code{Type_Invariant} @tab 18102@item @code{Unchecked_Union} @tab 18103@item @code{Universal_Aliasing} @tab -- GNAT 18104@item @code{Unmodified} @tab -- GNAT 18105@item @code{Unreferenced} @tab -- GNAT 18106@item @code{Unreferenced_Objects} @tab -- GNAT 18107@item @code{Unsuppress} @tab 18108@item @code{Value_Size} @tab -- GNAT 18109@item @code{Volatile} @tab 18110@item @code{Volatile_Components} 18111@item @code{Warnings} @tab -- GNAT 18112@end multitable 18113 18114@noindent 18115 Note that for aspects with an expression, e.g. @code{Size}, the expression is 18116 treated like a default expression (visibility is analyzed at the point of 18117 occurrence of the aspect, but evaluation of the expression occurs at the 18118 freeze point of the entity involved. 18119 18120@noindent 18121 RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) 18122 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 18123 (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) 18124 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) 18125 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) 18126 13.03.01 (0) 18127 18128 18129@item 18130@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} 18131@cindex AI-0128 (Ada 2012 feature) 18132 18133@noindent 18134 If an equality operator ("=") is declared for a type, then the implicitly 18135 declared inequality operator ("/=") is a primitive operation of the type. 18136 This is the only reasonable interpretation, and is the one always implemented 18137 by GNAT, but the RM was not entirely clear in making this point. 18138 18139@noindent 18140 RM References: 3.02.03 (6) 6.06 (6) 18141 18142@item 18143@emph{AI-0003 Qualified expressions as names (2010-07-11)} 18144@cindex AI-0003 (Ada 2012 feature) 18145 18146@noindent 18147 In Ada 2012, a qualified expression is considered to be syntactically a name, 18148 meaning that constructs such as @code{A'(F(X)).B} are now legal. This is 18149 useful in disambiguating some cases of overloading. 18150 18151@noindent 18152 RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) 18153 5.04 (7) 18154 18155@item 18156@emph{AI-0120 Constant instance of protected object (0000-00-00)} 18157@cindex AI-0120 (Ada 2012 feature) 18158 18159@noindent 18160 This is an RM editorial change only. The section that lists objects that are 18161 constant failed to include the current instance of a protected object 18162 within a protected function. This has always been treated as a constant 18163 in GNAT. 18164 18165@noindent 18166 RM References: 3.03 (21) 18167 18168@item 18169@emph{AI-0008 General access to constrained objects (0000-00-00)} 18170@cindex AI-0008 (Ada 2012 feature) 18171 18172@noindent 18173 The wording in the RM implied that if you have a general access to a 18174 constrained object, it could be used to modify the discriminants. This was 18175 obviously not intended. @code{Constraint_Error} should be raised, and GNAT 18176 has always done so in this situation. 18177 18178@noindent 18179 RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) 18180 18181 18182@item 18183@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} 18184@cindex AI-0093 (Ada 2012 feature) 18185 18186@noindent 18187 This is an editorial change only, to make more widespread use of the Ada 2012 18188 ``immutably limited''. 18189 18190@noindent 18191 RM References: 3.03 (23.4/3) 18192 18193 18194 18195@item 18196@emph{AI-0096 Deriving from formal private types (2010-07-20)} 18197@cindex AI-0096 (Ada 2012 feature) 18198 18199@noindent 18200 In general it is illegal for a type derived from a formal limited type to be 18201 nonlimited. This AI makes an exception to this rule: derivation is legal 18202 if it appears in the private part of the generic, and the formal type is not 18203 tagged. If the type is tagged, the legality check must be applied to the 18204 private part of the package. 18205 18206@noindent 18207 RM References: 3.04 (5.1/2) 6.02 (7) 18208 18209 18210@item 18211@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} 18212@cindex AI-0181 (Ada 2012 feature) 18213 18214@noindent 18215 From Ada 2005 on, soft hyphen is considered a non-graphic character, which 18216 means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the 18217 @code{Image} and @code{Value} attributes for the character types. Strictly 18218 speaking this is an inconsistency with Ada 95, but in practice the use of 18219 these attributes is so obscure that it will not cause problems. 18220 18221@noindent 18222 RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) 18223 18224 18225@item 18226@emph{AI-0182 Additional forms for @code{Character'Value} (0000-00-00)} 18227@cindex AI-0182 (Ada 2012 feature) 18228 18229@noindent 18230 This AI allows @code{Character'Value} to accept the string @code{'?'} where 18231 @code{?} is any character including non-graphic control characters. GNAT has 18232 always accepted such strings. It also allows strings such as 18233 @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this 18234 permission and raises @code{Constraint_Error}, as is certainly still 18235 permitted. 18236 18237@noindent 18238 RM References: 3.05 (56/2) 18239 18240 18241@item 18242@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} 18243@cindex AI-0214 (Ada 2012 feature) 18244 18245@noindent 18246 Ada 2012 relaxes the restriction that forbids discriminants of tagged types 18247 to have default expressions by allowing them when the type is limited. It 18248 is often useful to define a default value for a discriminant even though 18249 it can't be changed by assignment. 18250 18251@noindent 18252 RM References: 3.07 (9.1/2) 3.07.02 (3) 18253 18254 18255@item 18256@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} 18257@cindex AI-0102 (Ada 2012 feature) 18258 18259@noindent 18260 It is illegal to assign an anonymous access constant to an anonymous access 18261 variable. The RM did not have a clear rule to prevent this, but GNAT has 18262 always generated an error for this usage. 18263 18264@noindent 18265 RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) 18266 18267 18268@item 18269@emph{AI-0158 Generalizing membership tests (2010-09-16)} 18270@cindex AI-0158 (Ada 2012 feature) 18271 18272@noindent 18273 This AI extends the syntax of membership tests to simplify complex conditions 18274 that can be expressed as membership in a subset of values of any type. It 18275 introduces syntax for a list of expressions that may be used in loop contexts 18276 as well. 18277 18278@noindent 18279 RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) 18280 18281 18282@item 18283@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} 18284@cindex AI-0173 (Ada 2012 feature) 18285 18286@noindent 18287 The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked 18288 with the tag of an abstract type, and @code{False} otherwise. 18289 18290@noindent 18291 RM References: 3.09 (7.4/2) 3.09 (12.4/2) 18292 18293 18294 18295@item 18296@emph{AI-0076 function with controlling result (0000-00-00)} 18297@cindex AI-0076 (Ada 2012 feature) 18298 18299@noindent 18300 This is an editorial change only. The RM defines calls with controlling 18301 results, but uses the term ``function with controlling result'' without an 18302 explicit definition. 18303 18304@noindent 18305 RM References: 3.09.02 (2/2) 18306 18307 18308@item 18309@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} 18310@cindex AI-0126 (Ada 2012 feature) 18311 18312@noindent 18313 This AI clarifies dispatching rules, and simply confirms that dispatching 18314 executes the operation of the parent type when there is no explicitly or 18315 implicitly declared operation for the descendant type. This has always been 18316 the case in all versions of GNAT. 18317 18318@noindent 18319 RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) 18320 18321 18322@item 18323@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} 18324@cindex AI-0097 (Ada 2012 feature) 18325 18326@noindent 18327 The RM as written implied that in some cases it was possible to create an 18328 object of an abstract type, by having an abstract extension inherit a non- 18329 abstract constructor from its parent type. This mistake has been corrected 18330 in GNAT and in the RM, and this construct is now illegal. 18331 18332@noindent 18333 RM References: 3.09.03 (4/2) 18334 18335 18336@item 18337@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} 18338@cindex AI-0203 (Ada 2012 feature) 18339 18340@noindent 18341 A return_subtype_indication cannot denote an abstract subtype. GNAT has never 18342 permitted such usage. 18343 18344@noindent 18345 RM References: 3.09.03 (8/3) 18346 18347 18348@item 18349@emph{AI-0198 Inheriting abstract operators (0000-00-00)} 18350@cindex AI-0198 (Ada 2012 feature) 18351 18352@noindent 18353 This AI resolves a conflict between two rules involving inherited abstract 18354 operations and predefined operators. If a derived numeric type inherits 18355 an abstract operator, it overrides the predefined one. This interpretation 18356 was always the one implemented in GNAT. 18357 18358@noindent 18359 RM References: 3.09.03 (4/3) 18360 18361@item 18362@emph{AI-0073 Functions returning abstract types (2010-07-10)} 18363@cindex AI-0073 (Ada 2012 feature) 18364 18365@noindent 18366 This AI covers a number of issues regarding returning abstract types. In 18367 particular generic functions cannot have abstract result types or access 18368 result types designated an abstract type. There are some other cases which 18369 are detailed in the AI. Note that this binding interpretation has not been 18370 retrofitted to operate before Ada 2012 mode, since it caused a significant 18371 number of regressions. 18372 18373@noindent 18374 RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) 18375 18376 18377@item 18378@emph{AI-0070 Elaboration of interface types (0000-00-00)} 18379@cindex AI-0070 (Ada 2012 feature) 18380 18381@noindent 18382 This is an editorial change only, there are no testable consequences short of 18383 checking for the absence of generated code for an interface declaration. 18384 18385@noindent 18386 RM References: 3.09.04 (18/2) 18387 18388 18389@item 18390@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} 18391@cindex AI-0208 (Ada 2012 feature) 18392 18393@noindent 18394 The wording in the Ada 2005 RM concerning characteristics of incomplete views 18395 was incorrect and implied that some programs intended to be legal were now 18396 illegal. GNAT had never considered such programs illegal, so it has always 18397 implemented the intent of this AI. 18398 18399@noindent 18400 RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) 18401 18402 18403@item 18404@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} 18405@cindex AI-0162 (Ada 2012 feature) 18406 18407@noindent 18408 Incomplete types are made more useful by allowing them to be completed by 18409 private types and private extensions. 18410 18411@noindent 18412 RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) 18413 18414 18415 18416@item 18417@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} 18418@cindex AI-0098 (Ada 2012 feature) 18419 18420@noindent 18421 An unintentional omission in the RM implied some inconsistent restrictions on 18422 the use of anonymous access to subprogram values. These restrictions were not 18423 intentional, and have never been enforced by GNAT. 18424 18425@noindent 18426 RM References: 3.10.01 (6) 3.10.01 (9.2/2) 18427 18428 18429@item 18430@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} 18431@cindex AI-0199 (Ada 2012 feature) 18432 18433@noindent 18434 A choice list in a record aggregate can include several components of 18435 (distinct) anonymous access types as long as they have matching designated 18436 subtypes. 18437 18438@noindent 18439 RM References: 4.03.01 (16) 18440 18441 18442@item 18443@emph{AI-0220 Needed components for aggregates (0000-00-00)} 18444@cindex AI-0220 (Ada 2012 feature) 18445 18446@noindent 18447 This AI addresses a wording problem in the RM that appears to permit some 18448 complex cases of aggregates with non-static discriminants. GNAT has always 18449 implemented the intended semantics. 18450 18451@noindent 18452 RM References: 4.03.01 (17) 18453 18454@item 18455@emph{AI-0147 Conditional expressions (2009-03-29)} 18456@cindex AI-0147 (Ada 2012 feature) 18457 18458@noindent 18459 Conditional expressions are permitted. The form of such an expression is: 18460 18461@smallexample 18462 (@b{if} @i{expr} @b{then} @i{expr} @{@b{elsif} @i{expr} @b{then} @i{expr}@} [@b{else} @i{expr}]) 18463@end smallexample 18464 18465 The parentheses can be omitted in contexts where parentheses are present 18466 anyway, such as subprogram arguments and pragma arguments. If the @b{else} 18467 clause is omitted, @b{else True} is assumed; 18468 thus @code{(@b{if} A @b{then} B)} is a way to conveniently represent 18469 @emph{(A implies B)} in standard logic. 18470 18471@noindent 18472 RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) 18473 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) 18474 18475 18476@item 18477@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} 18478@cindex AI-0037 (Ada 2012 feature) 18479 18480@noindent 18481 This AI confirms that an association of the form @code{Indx => <>} in an 18482 array aggregate must raise @code{Constraint_Error} if @code{Indx} 18483 is out of range. The RM specified a range check on other associations, but 18484 not when the value of the association was defaulted. GNAT has always inserted 18485 a constraint check on the index value. 18486 18487@noindent 18488 RM References: 4.03.03 (29) 18489 18490 18491@item 18492@emph{AI-0123 Composability of equality (2010-04-13)} 18493@cindex AI-0123 (Ada 2012 feature) 18494 18495@noindent 18496 Equality of untagged record composes, so that the predefined equality for a 18497 composite type that includes a component of some untagged record type 18498 @code{R} uses the equality operation of @code{R} (which may be user-defined 18499 or predefined). This makes the behavior of untagged records identical to that 18500 of tagged types in this respect. 18501 18502 This change is an incompatibility with previous versions of Ada, but it 18503 corrects a non-uniformity that was often a source of confusion. Analysis of 18504 a large number of industrial programs indicates that in those rare cases 18505 where a composite type had an untagged record component with a user-defined 18506 equality, either there was no use of the composite equality, or else the code 18507 expected the same composability as for tagged types, and thus had a bug that 18508 would be fixed by this change. 18509 18510@noindent 18511 RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) 18512 8.05.04 (8) 18513 18514 18515@item 18516@emph{AI-0088 The value of exponentiation (0000-00-00)} 18517@cindex AI-0088 (Ada 2012 feature) 18518 18519@noindent 18520 This AI clarifies the equivalence rule given for the dynamic semantics of 18521 exponentiation: the value of the operation can be obtained by repeated 18522 multiplication, but the operation can be implemented otherwise (for example 18523 using the familiar divide-by-two-and-square algorithm, even if this is less 18524 accurate), and does not imply repeated reads of a volatile base. 18525 18526@noindent 18527 RM References: 4.05.06 (11) 18528 18529@item 18530@emph{AI-0188 Case expressions (2010-01-09)} 18531@cindex AI-0188 (Ada 2012 feature) 18532 18533@noindent 18534 Case expressions are permitted. This allows use of constructs such as: 18535@smallexample 18536 X := (@b{case} Y @b{is when} 1 => 2, @b{when} 2 => 3, @b{when others} => 31) 18537@end smallexample 18538 18539@noindent 18540 RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) 18541 18542@item 18543@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} 18544@cindex AI-0104 (Ada 2012 feature) 18545 18546@noindent 18547 The assignment @code{Ptr := @b{new not null} Some_Ptr;} will raise 18548 @code{Constraint_Error} because the default value of the allocated object is 18549 @b{null}. This useless construct is illegal in Ada 2012. 18550 18551@noindent 18552 RM References: 4.08 (2) 18553 18554@item 18555@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} 18556@cindex AI-0157 (Ada 2012 feature) 18557 18558@noindent 18559 Allocation and Deallocation from an empty storage pool (i.e. allocation or 18560 deallocation of a pointer for which a static storage size clause of zero 18561 has been given) is now illegal and is detected as such. GNAT 18562 previously gave a warning but not an error. 18563 18564@noindent 18565 RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) 18566 18567@item 18568@emph{AI-0179 Statement not required after label (2010-04-10)} 18569@cindex AI-0179 (Ada 2012 feature) 18570 18571@noindent 18572 It is not necessary to have a statement following a label, so a label 18573 can appear at the end of a statement sequence without the need for putting a 18574 null statement afterwards, but it is not allowable to have only labels and 18575 no real statements in a statement sequence. 18576 18577@noindent 18578 RM References: 5.01 (2) 18579 18580 18581@item 18582@emph{AI-139-2 Syntactic sugar for iterators (2010-09-29)} 18583@cindex AI-139-2 (Ada 2012 feature) 18584 18585@noindent 18586 The new syntax for iterating over arrays and containers is now implemented. 18587 Iteration over containers is for now limited to read-only iterators. Only 18588 default iterators are supported, with the syntax: @code{@b{for} Elem @b{of} C}. 18589 18590@noindent 18591 RM References: 5.05 18592 18593@item 18594@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} 18595@cindex AI-0134 (Ada 2012 feature) 18596 18597@noindent 18598 For full conformance, the profiles of anonymous-access-to-subprogram 18599 parameters must match. GNAT has always enforced this rule. 18600 18601@noindent 18602 RM References: 6.03.01 (18) 18603 18604@item 18605@emph{AI-0207 Mode conformance and access constant (0000-00-00)} 18606@cindex AI-0207 (Ada 2012 feature) 18607 18608@noindent 18609 This AI confirms that access_to_constant indication must match for mode 18610 conformance. This was implemented in GNAT when the qualifier was originally 18611 introduced in Ada 2005. 18612 18613@noindent 18614 RM References: 6.03.01 (16/2) 18615 18616 18617@item 18618@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} 18619@cindex AI-0046 (Ada 2012 feature) 18620 18621@noindent 18622 For full conformance, in the case of access parameters, the null exclusion 18623 must match (either both or neither must have @code{@b{not null}}). 18624 18625@noindent 18626 RM References: 6.03.02 (18) 18627 18628 18629@item 18630@emph{AI-0118 The association of parameter associations (0000-00-00)} 18631@cindex AI-0118 (Ada 2012 feature) 18632 18633@noindent 18634 This AI clarifies the rules for named associations in subprogram calls and 18635 generic instantiations. The rules have been in place since Ada 83. 18636 18637@noindent 18638 RM References: 6.04.01 (2) 12.03 (9) 18639 18640 18641@item 18642@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} 18643@cindex AI-0196 (Ada 2012 feature) 18644 18645@noindent 18646 Null exclusion checks are not made for @code{@b{out}} parameters when 18647 evaluating the actual parameters. GNAT has never generated these checks. 18648 18649@noindent 18650 RM References: 6.04.01 (13) 18651 18652@item 18653@emph{AI-0015 Constant return objects (0000-00-00)} 18654@cindex AI-0015 (Ada 2012 feature) 18655 18656@noindent 18657 The return object declared in an @i{extended_return_statement} may be 18658 declared constant. This was always intended, and GNAT has always allowed it. 18659 18660@noindent 18661 RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) 18662 6.05 (5.7/2) 18663 18664 18665@item 18666@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} 18667@cindex AI-0032 (Ada 2012 feature) 18668 18669@noindent 18670 If a function returns a class-wide type, the object of an extended return 18671 statement can be declared with a specific type that is covered by the class- 18672 wide type. This has been implemented in GNAT since the introduction of 18673 extended returns. Note AI-0103 complements this AI by imposing matching 18674 rules for constrained return types. 18675 18676@noindent 18677 RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) 18678 6.05 (8/2) 18679 18680@item 18681@emph{AI-0103 Static matching for extended return (2010-07-23)} 18682@cindex AI-0103 (Ada 2012 feature) 18683 18684@noindent 18685 If the return subtype of a function is an elementary type or a constrained 18686 type, the subtype indication in an extended return statement must match 18687 statically this return subtype. 18688 18689@noindent 18690 RM References: 6.05 (5.2/2) 18691 18692 18693@item 18694@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} 18695@cindex AI-0058 (Ada 2012 feature) 18696 18697@noindent 18698 The RM had some incorrect wording implying wrong treatment of abnormal 18699 completion in an extended return. GNAT has always implemented the intended 18700 correct semantics as described by this AI. 18701 18702@noindent 18703 RM References: 6.05 (22/2) 18704 18705 18706@item 18707@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} 18708@cindex AI-0050 (Ada 2012 feature) 18709 18710@noindent 18711 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 18712 not take advantage of these incorrect permissions in any case. 18713 18714@noindent 18715 RM References: 6.05 (24/2) 18716 18717 18718@item 18719@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} 18720@cindex AI-0125 (Ada 2012 feature) 18721 18722@noindent 18723 In Ada 2012, the declaration of a primitive operation of a type extension 18724 or private extension can also override an inherited primitive that is not 18725 visible at the point of this declaration. 18726 18727@noindent 18728 RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) 18729 18730@item 18731@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} 18732@cindex AI-0062 (Ada 2012 feature) 18733 18734@noindent 18735 A full constant may have a null exclusion even if its associated deferred 18736 constant does not. GNAT has always allowed this. 18737 18738@noindent 18739 RM References: 7.04 (6/2) 7.04 (7.1/2) 18740 18741 18742@item 18743@emph{AI-0178 Incomplete views are limited (0000-00-00)} 18744@cindex AI-0178 (Ada 2012 feature) 18745 18746@noindent 18747 This AI clarifies the role of incomplete views and plugs an omission in the 18748 RM. GNAT always correctly restricted the use of incomplete views and types. 18749 18750@noindent 18751 RM References: 7.05 (3/2) 7.05 (6/2) 18752 18753@item 18754@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} 18755@cindex AI-0087 (Ada 2012 feature) 18756 18757@noindent 18758 The actual for a formal nonlimited derived type cannot be limited. In 18759 particular, a formal derived type that extends a limited interface but which 18760 is not explicitly limited cannot be instantiated with a limited type. 18761 18762@noindent 18763 RM References: 7.05 (5/2) 12.05.01 (5.1/2) 18764 18765@item 18766@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} 18767@cindex AI-0099 (Ada 2012 feature) 18768 18769@noindent 18770 This AI clarifies that ``needs finalization'' is part of dynamic semantics, 18771 and therefore depends on the run-time characteristics of an object (i.e. its 18772 tag) and not on its nominal type. As the AI indicates: ``we do not expect 18773 this to affect any implementation''. 18774 18775@noindent 18776 RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) 18777 18778 18779 18780@item 18781@emph{AI-0064 Redundant finalization rule (0000-00-00)} 18782@cindex AI-0064 (Ada 2012 feature) 18783 18784@noindent 18785 This is an editorial change only. The intended behavior is already checked 18786 by an existing ACATS test, which GNAT has always executed correctly. 18787 18788@noindent 18789 RM References: 7.06.01 (17.1/1) 18790 18791@item 18792@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} 18793@cindex AI-0026 (Ada 2012 feature) 18794 18795@noindent 18796 Record representation clauses concerning Unchecked_Union types cannot mention 18797 the discriminant of the type. The type of a component declared in the variant 18798 part of an Unchecked_Union cannot be controlled, have controlled components, 18799 nor have protected or task parts. If an Unchecked_Union type is declared 18800 within the body of a generic unit or its descendants, then the type of a 18801 component declared in the variant part cannot be a formal private type or a 18802 formal private extension declared within the same generic unit. 18803 18804@noindent 18805 RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) 18806 18807 18808@item 18809@emph{AI-0205 Extended return declares visible name (0000-00-00)} 18810@cindex AI-0205 (Ada 2012 feature) 18811 18812@noindent 18813 This AI corrects a simple omission in the RM. Return objects have always 18814 been visible within an extended return statement. 18815 18816@noindent 18817 RM References: 8.03 (17) 18818 18819 18820@item 18821@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} 18822@cindex AI-0042 (Ada 2012 feature) 18823 18824@noindent 18825 This AI fixes a wording gap in the RM. An operation of a synchronized 18826 interface can be implemented by a protected or task entry, but the abstract 18827 operation is not being overridden in the usual sense, and it must be stated 18828 separately that this implementation is legal. This has always been the case 18829 in GNAT. 18830 18831@noindent 18832 RM References: 9.01 (9.2/2) 9.04 (11.1/2) 18833 18834@item 18835@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} 18836@cindex AI-0030 (Ada 2012 feature) 18837 18838@noindent 18839 Requeue is permitted to a protected, synchronized or task interface primitive 18840 providing it is known that the overriding operation is an entry. Otherwise 18841 the requeue statement has the same effect as a procedure call. Use of pragma 18842 @code{Implemented} provides a way to impose a static requirement on the 18843 overriding operation by adhering to one of the implementation kinds: entry, 18844 protected procedure or any of the above. 18845 18846@noindent 18847 RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) 18848 9.05.04 (6) 9.05.04 (7) 9.05.04 (12) 18849 18850 18851@item 18852@emph{AI-0201 Independence of atomic object components (2010-07-22)} 18853@cindex AI-0201 (Ada 2012 feature) 18854 18855@noindent 18856 If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} 18857 attribute, then individual components may not be addressable by independent 18858 tasks. However, if the representation clause has no effect (is confirming), 18859 then independence is not compromised. Furthermore, in GNAT, specification of 18860 other appropriately addressable component sizes (e.g. 16 for 8-bit 18861 characters) also preserves independence. GNAT now gives very clear warnings 18862 both for the declaration of such a type, and for any assignment to its components. 18863 18864@noindent 18865 RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) 18866 18867@item 18868@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} 18869@cindex AI-0009 (Ada 2012 feature) 18870 18871@noindent 18872 This AI introduces the new pragmas @code{Independent} and 18873 @code{Independent_Components}, 18874 which control guaranteeing independence of access to objects and components. 18875 The AI also requires independence not unaffected by confirming rep clauses. 18876 18877@noindent 18878 RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) 18879 C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) 18880 18881 18882@item 18883@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)} 18884@cindex AI-0072 (Ada 2012 feature) 18885 18886@noindent 18887 This AI clarifies that task signalling for reading @code{'Terminated} only 18888 occurs if the result is True. GNAT semantics has always been consistent with 18889 this notion of task signalling. 18890 18891@noindent 18892 RM References: 9.10 (6.1/1) 18893 18894@item 18895@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} 18896@cindex AI-0108 (Ada 2012 feature) 18897 18898@noindent 18899 This AI confirms that an incomplete type from a limited view does not have 18900 discriminants. This has always been the case in GNAT. 18901 18902@noindent 18903 RM References: 10.01.01 (12.3/2) 18904 18905@item 18906@emph{AI-0129 Limited views and incomplete types (0000-00-00)} 18907@cindex AI-0129 (Ada 2012 feature) 18908 18909@noindent 18910 This AI clarifies the description of limited views: a limited view of a 18911 package includes only one view of a type that has an incomplete declaration 18912 and a full declaration (there is no possible ambiguity in a client package). 18913 This AI also fixes an omission: a nested package in the private part has no 18914 limited view. GNAT always implemented this correctly. 18915 18916@noindent 18917 RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) 18918 18919 18920 18921@item 18922@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} 18923@cindex AI-0077 (Ada 2012 feature) 18924 18925@noindent 18926 This AI clarifies that a declaration does not include a context clause, 18927 and confirms that it is illegal to have a context in which both a limited 18928 and a nonlimited view of a package are accessible. Such double visibility 18929 was always rejected by GNAT. 18930 18931@noindent 18932 RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) 18933 18934@item 18935@emph{AI-0122 Private with and children of generics (0000-00-00)} 18936@cindex AI-0122 (Ada 2012 feature) 18937 18938@noindent 18939 This AI clarifies the visibility of private children of generic units within 18940 instantiations of a parent. GNAT has always handled this correctly. 18941 18942@noindent 18943 RM References: 10.01.02 (12/2) 18944 18945 18946 18947@item 18948@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} 18949@cindex AI-0040 (Ada 2012 feature) 18950 18951@noindent 18952 This AI confirms that a limited with clause in a child unit cannot name 18953 an ancestor of the unit. This has always been checked in GNAT. 18954 18955@noindent 18956 RM References: 10.01.02 (20/2) 18957 18958@item 18959@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} 18960@cindex AI-0132 (Ada 2012 feature) 18961 18962@noindent 18963 This AI fills a gap in the description of library unit pragmas. The pragma 18964 clearly must apply to a library unit, even if it does not carry the name 18965 of the enclosing unit. GNAT has always enforced the required check. 18966 18967@noindent 18968 RM References: 10.01.05 (7) 18969 18970 18971@item 18972@emph{AI-0034 Categorization of limited views (0000-00-00)} 18973@cindex AI-0034 (Ada 2012 feature) 18974 18975@noindent 18976 The RM makes certain limited with clauses illegal because of categorization 18977 considerations, when the corresponding normal with would be legal. This is 18978 not intended, and GNAT has always implemented the recommended behavior. 18979 18980@noindent 18981 RM References: 10.02.01 (11/1) 10.02.01 (17/2) 18982 18983 18984@item 18985@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} 18986@cindex AI-0035 (Ada 2012 feature) 18987 18988@noindent 18989 This AI remedies some inconsistencies in the legality rules for Pure units. 18990 Derived access types are legal in a pure unit (on the assumption that the 18991 rule for a zero storage pool size has been enforced on the ancestor type). 18992 The rules are enforced in generic instances and in subunits. GNAT has always 18993 implemented the recommended behavior. 18994 18995@noindent 18996 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) 18997 18998 18999@item 19000@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} 19001@cindex AI-0219 (Ada 2012 feature) 19002 19003@noindent 19004 This AI refines the rules for the cases with limited parameters which do not 19005 allow the implementations to omit ``redundant''. GNAT now properly conforms 19006 to the requirements of this binding interpretation. 19007 19008@noindent 19009 RM References: 10.02.01 (18/2) 19010 19011@item 19012@emph{AI-0043 Rules about raising exceptions (0000-00-00)} 19013@cindex AI-0043 (Ada 2012 feature) 19014 19015@noindent 19016 This AI covers various omissions in the RM regarding the raising of 19017 exceptions. GNAT has always implemented the intended semantics. 19018 19019@noindent 19020 RM References: 11.04.01 (10.1/2) 11 (2) 19021 19022 19023@item 19024@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} 19025@cindex AI-0200 (Ada 2012 feature) 19026 19027@noindent 19028 This AI plugs a gap in the RM which appeared to allow some obviously intended 19029 illegal instantiations. GNAT has never allowed these instantiations. 19030 19031@noindent 19032 RM References: 12.07 (16) 19033 19034 19035@item 19036@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} 19037@cindex AI-0112 (Ada 2012 feature) 19038 19039@noindent 19040 This AI concerns giving names to various representation aspects, but the 19041 practical effect is simply to make the use of duplicate 19042 @code{Atomic}[@code{_Components}], 19043 @code{Volatile}[@code{_Components}] and 19044 @code{Independent}[@code{_Components}] pragmas illegal, and GNAT 19045 now performs this required check. 19046 19047@noindent 19048 RM References: 13.01 (8) 19049 19050@item 19051@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} 19052@cindex AI-0106 (Ada 2012 feature) 19053 19054@noindent 19055 The RM appeared to allow representation pragmas on generic formal parameters, 19056 but this was not intended, and GNAT has never permitted this usage. 19057 19058@noindent 19059 RM References: 13.01 (9.1/1) 19060 19061 19062@item 19063@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} 19064@cindex AI-0012 (Ada 2012 feature) 19065 19066@noindent 19067 It is now illegal to give an inappropriate component size or a pragma 19068 @code{Pack} that attempts to change the component size in the case of atomic 19069 or aliased components. Previously GNAT ignored such an attempt with a 19070 warning. 19071 19072@noindent 19073 RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) 19074 19075 19076@item 19077@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} 19078@cindex AI-0039 (Ada 2012 feature) 19079 19080@noindent 19081 The RM permitted the use of dynamic expressions (such as @code{ptr.@b{all})} 19082 for stream attributes, but these were never useful and are now illegal. GNAT 19083 has always regarded such expressions as illegal. 19084 19085@noindent 19086 RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) 19087 19088 19089@item 19090@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} 19091@cindex AI-0095 (Ada 2012 feature) 19092 19093@noindent 19094 The prefix of @code{'Address} cannot statically denote a subprogram with 19095 convention @code{Intrinsic}. The use of the @code{Address} attribute raises 19096 @code{Program_Error} if the prefix denotes a subprogram with convention 19097 @code{Intrinsic}. 19098 19099@noindent 19100 RM References: 13.03 (11/1) 19101 19102 19103@item 19104@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} 19105@cindex AI-0116 (Ada 2012 feature) 19106 19107@noindent 19108 This AI requires that the alignment of a class-wide object be no greater 19109 than the alignment of any type in the class. GNAT has always followed this 19110 recommendation. 19111 19112@noindent 19113 RM References: 13.03 (29) 13.11 (16) 19114 19115 19116@item 19117@emph{AI-0146 Type invariants (2009-09-21)} 19118@cindex AI-0146 (Ada 2012 feature) 19119 19120@noindent 19121 Type invariants may be specified for private types using the aspect notation. 19122 Aspect @code{Type_Invariant} may be specified for any private type, 19123 @code{Type_Invariant'Class} can 19124 only be specified for tagged types, and is inherited by any descendent of the 19125 tagged types. The invariant is a boolean expression that is tested for being 19126 true in the following situations: conversions to the private type, object 19127 declarations for the private type that are default initialized, and 19128 [@b{in}] @b{out} 19129 parameters and returned result on return from any primitive operation for 19130 the type that is visible to a client. 19131 GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and 19132 @code{Invariant'Class} for @code{Type_Invariant'Class}. 19133 19134@noindent 19135 RM References: 13.03.03 (00) 19136 19137@item 19138@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} 19139@cindex AI-0078 (Ada 2012 feature) 19140 19141@noindent 19142 In Ada 2012, compilers are required to support unchecked conversion where the 19143 target alignment is a multiple of the source alignment. GNAT always supported 19144 this case (and indeed all cases of differing alignments, doing copies where 19145 required if the alignment was reduced). 19146 19147@noindent 19148 RM References: 13.09 (7) 19149 19150 19151@item 19152@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} 19153@cindex AI-0195 (Ada 2012 feature) 19154 19155@noindent 19156 The handling of invalid values is now designated to be implementation 19157 defined. This is a documentation change only, requiring Annex M in the GNAT 19158 Reference Manual to document this handling. 19159 In GNAT, checks for invalid values are made 19160 only when necessary to avoid erroneous behavior. Operations like assignments 19161 which cannot cause erroneous behavior ignore the possibility of invalid 19162 values and do not do a check. The date given above applies only to the 19163 documentation change, this behavior has always been implemented by GNAT. 19164 19165@noindent 19166 RM References: 13.09.01 (10) 19167 19168@item 19169@emph{AI-0193 Alignment of allocators (2010-09-16)} 19170@cindex AI-0193 (Ada 2012 feature) 19171 19172@noindent 19173 This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, 19174 analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead 19175 of size. 19176 19177@noindent 19178 RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) 19179 13.11.01 (2) 13.11.01 (3) 19180 19181 19182@item 19183@emph{AI-0177 Parameterized expressions (2010-07-10)} 19184@cindex AI-0177 (Ada 2012 feature) 19185 19186@noindent 19187 The new Ada 2012 notion of parameterized expressions is implemented. The form 19188 is: 19189@smallexample 19190 @i{function specification} @b{is} (@i{expression}) 19191@end smallexample 19192 19193@noindent 19194 This is exactly equivalent to the 19195 corresponding function body that returns the expression, but it can appear 19196 in a package spec. Note that the expression must be parenthesized. 19197 19198@noindent 19199 RM References: 13.11.01 (3/2) 19200 19201@item 19202@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} 19203@cindex AI-0033 (Ada 2012 feature) 19204 19205@noindent 19206 Neither of these two pragmas may appear within a generic template, because 19207 the generic might be instantiated at other than the library level. 19208 19209@noindent 19210 RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) 19211 19212 19213@item 19214@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} 19215@cindex AI-0161 (Ada 2012 feature) 19216 19217@noindent 19218 A new restriction @code{No_Default_Stream_Attributes} prevents the use of any 19219 of the default stream attributes for elementary types. If this restriction is 19220 in force, then it is necessary to provide explicit subprograms for any 19221 stream attributes used. 19222 19223@noindent 19224 RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) 19225 19226@item 19227@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} 19228@cindex AI-0194 (Ada 2012 feature) 19229 19230@noindent 19231 The @code{Stream_Size} attribute returns the default number of bits in the 19232 stream representation of the given type. 19233 This value is not affected by the presence 19234 of stream subprogram attributes for the type. GNAT has always implemented 19235 this interpretation. 19236 19237@noindent 19238 RM References: 13.13.02 (1.2/2) 19239 19240@item 19241@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)} 19242@cindex AI-0109 (Ada 2012 feature) 19243 19244@noindent 19245 This AI is an editorial change only. It removes the need for a tag check 19246 that can never fail. 19247 19248@noindent 19249 RM References: 13.13.02 (34/2) 19250 19251@item 19252@emph{AI-0007 Stream read and private scalar types (0000-00-00)} 19253@cindex AI-0007 (Ada 2012 feature) 19254 19255@noindent 19256 The RM as written appeared to limit the possibilities of declaring read 19257 attribute procedures for private scalar types. This limitation was not 19258 intended, and has never been enforced by GNAT. 19259 19260@noindent 19261 RM References: 13.13.02 (50/2) 13.13.02 (51/2) 19262 19263 19264@item 19265@emph{AI-0065 Remote access types and external streaming (0000-00-00)} 19266@cindex AI-0065 (Ada 2012 feature) 19267 19268@noindent 19269 This AI clarifies the fact that all remote access types support external 19270 streaming. This fixes an obvious oversight in the definition of the 19271 language, and GNAT always implemented the intended correct rules. 19272 19273@noindent 19274 RM References: 13.13.02 (52/2) 19275 19276@item 19277@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} 19278@cindex AI-0019 (Ada 2012 feature) 19279 19280@noindent 19281 The RM suggests that primitive subprograms of a specific tagged type are 19282 frozen when the tagged type is frozen. This would be an incompatible change 19283 and is not intended. GNAT has never attempted this kind of freezing and its 19284 behavior is consistent with the recommendation of this AI. 19285 19286@noindent 19287 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) 19288 19289@item 19290@emph{AI-0017 Freezing and incomplete types (0000-00-00)} 19291@cindex AI-0017 (Ada 2012 feature) 19292 19293@noindent 19294 So-called ``Taft-amendment types'' (i.e., types that are completed in package 19295 bodies) are not frozen by the occurrence of bodies in the 19296 enclosing declarative part. GNAT always implemented this properly. 19297 19298@noindent 19299 RM References: 13.14 (3/1) 19300 19301 19302@item 19303@emph{AI-0060 Extended definition of remote access types (0000-00-00)} 19304@cindex AI-0060 (Ada 2012 feature) 19305 19306@noindent 19307 This AI extends the definition of remote access types to include access 19308 to limited, synchronized, protected or task class-wide interface types. 19309 GNAT already implemented this extension. 19310 19311@noindent 19312 RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) 19313 19314@item 19315@emph{AI-0114 Classification of letters (0000-00-00)} 19316@cindex AI-0114 (Ada 2012 feature) 19317 19318@noindent 19319 The code points 170 (@code{FEMININE ORDINAL INDICATOR}), 19320 181 (@code{MICRO SIGN}), and 19321 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered 19322 lower case letters by Unicode. 19323 However, they are not allowed in identifiers, and they 19324 return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. 19325 This behavior is consistent with that defined in Ada 95. 19326 19327@noindent 19328 RM References: A.03.02 (59) A.04.06 (7) 19329 19330 19331@item 19332@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} 19333@cindex AI-0185 (Ada 2012 feature) 19334 19335@noindent 19336 Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide 19337 classification functions for @code{Wide_Character} and 19338 @code{Wide_Wide_Character}, as well as providing 19339 case folding routines for @code{Wide_[Wide_]Character} and 19340 @code{Wide_[Wide_]String}. 19341 19342@noindent 19343 RM References: A.03.05 (0) A.03.06 (0) 19344 19345 19346@item 19347@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} 19348@cindex AI-0031 (Ada 2012 feature) 19349 19350@noindent 19351 A new version of @code{Find_Token} is added to all relevant string packages, 19352 with an extra parameter @code{From}. Instead of starting at the first 19353 character of the string, the search for a matching Token starts at the 19354 character indexed by the value of @code{From}. 19355 These procedures are available in all versions of Ada 19356 but if used in versions earlier than Ada 2012 they will generate a warning 19357 that an Ada 2012 subprogram is being used. 19358 19359@noindent 19360 RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) 19361 A.04.05 (46) 19362 19363 19364@item 19365@emph{AI-0056 Index on null string returns zero (0000-00-00)} 19366@cindex AI-0056 (Ada 2012 feature) 19367 19368@noindent 19369 The wording in the Ada 2005 RM implied an incompatible handling of the 19370 @code{Index} functions, resulting in raising an exception instead of 19371 returning zero in some situations. 19372 This was not intended and has been corrected. 19373 GNAT always returned zero, and is thus consistent with this AI. 19374 19375@noindent 19376 RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) 19377 19378 19379@item 19380@emph{AI-0137 String encoding package (2010-03-25)} 19381@cindex AI-0137 (Ada 2012 feature) 19382 19383@noindent 19384 The packages @code{Ada.Strings.UTF_Encoding}, together with its child 19385 packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, 19386 and @code{Wide_Wide_Strings} have been 19387 implemented. These packages (whose documentation can be found in the spec 19388 files @file{a-stuten.ads}, @file{a-suenco.ads}, @file{a-suenst.ads}, 19389 @file{a-suewst.ads}, @file{a-suezst.ads}) allow encoding and decoding of 19390 @code{String}, @code{Wide_String}, and @code{Wide_Wide_String} 19391 values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and 19392 UTF-16), as well as conversions between the different UTF encodings. With 19393 the exception of @code{Wide_Wide_Strings}, these packages are available in 19394 Ada 95 and Ada 2005 mode as well as Ada 2012 mode. 19395 The @code{Wide_Wide_Strings package} 19396 is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 19397 mode since it uses @code{Wide_Wide_Character}). 19398 19399@noindent 19400 RM References: A.04.11 19401 19402@item 19403@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} 19404@cindex AI-0038 (Ada 2012 feature) 19405 19406@noindent 19407 These are minor errors in the description on three points. The intent on 19408 all these points has always been clear, and GNAT has always implemented the 19409 correct intended semantics. 19410 19411@noindent 19412 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) 19413 19414@item 19415@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} 19416@cindex AI-0044 (Ada 2012 feature) 19417 19418@noindent 19419 This AI places restrictions on allowed instantiations of generic containers. 19420 These restrictions are not checked by the compiler, so there is nothing to 19421 change in the implementation. This affects only the RM documentation. 19422 19423@noindent 19424 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) 19425 19426@item 19427@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} 19428@cindex AI-0127 (Ada 2012 feature) 19429 19430@noindent 19431 This package provides an interface for identifying the current locale. 19432 19433@noindent 19434 RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 19435 A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 19436 19437 19438 19439@item 19440@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} 19441@cindex AI-0002 (Ada 2012 feature) 19442 19443@noindent 19444 The compiler is not required to support exporting an Ada subprogram with 19445 convention C if there are parameters or a return type of an unconstrained 19446 array type (such as @code{String}). GNAT allows such declarations but 19447 generates warnings. It is possible, but complicated, to write the 19448 corresponding C code and certainly such code would be specific to GNAT and 19449 non-portable. 19450 19451@noindent 19452 RM References: B.01 (17) B.03 (62) B.03 (71.1/2) 19453 19454 19455@item 19456@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} 19457@cindex AI05-0216 (Ada 2012 feature) 19458 19459@noindent 19460 It is clearly the intention that @code{No_Task_Hierarchy} is intended to 19461 forbid tasks declared locally within subprograms, or functions returning task 19462 objects, and that is the implementation that GNAT has always provided. 19463 However the language in the RM was not sufficiently clear on this point. 19464 Thus this is a documentation change in the RM only. 19465 19466@noindent 19467 RM References: D.07 (3/3) 19468 19469@item 19470@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} 19471@cindex AI-0211 (Ada 2012 feature) 19472 19473@noindent 19474 The restriction @code{No_Relative_Delays} forbids any calls to the subprogram 19475 @code{Ada.Real_Time.Timing_Events.Set_Handler}. 19476 19477@noindent 19478 RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) 19479 19480@item 19481@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} 19482@cindex AI-0190 (Ada 2012 feature) 19483 19484@noindent 19485 This AI introduces a new pragma @code{Default_Storage_Pool}, which can be 19486 used to control storage pools globally. 19487 In particular, you can force every access 19488 type that is used for allocation (@b{new}) to have an explicit storage pool, 19489 or you can declare a pool globally to be used for all access types that lack 19490 an explicit one. 19491 19492@noindent 19493 RM References: D.07 (8) 19494 19495@item 19496@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} 19497@cindex AI-0189 (Ada 2012 feature) 19498 19499@noindent 19500 This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, 19501 which says that no dynamic allocation will occur once elaboration is 19502 completed. 19503 In general this requires a run-time check, which is not required, and which 19504 GNAT does not attempt. But the static cases of allocators in a task body or 19505 in the body of the main program are detected and flagged at compile or bind 19506 time. 19507 19508@noindent 19509 RM References: D.07 (19.1/2) H.04 (23.3/2) 19510 19511@item 19512@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} 19513@cindex AI-0171 (Ada 2012 feature) 19514 19515@noindent 19516 A new package @code{System.Multiprocessors} is added, together with the 19517 definition of pragma @code{CPU} for controlling task affinity. A new no 19518 dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, 19519 is added to the Ravenscar profile. 19520 19521@noindent 19522 RM References: D.13.01 (4/2) D.16 19523 19524 19525@item 19526@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} 19527@cindex AI-0210 (Ada 2012 feature) 19528 19529@noindent 19530 This is a documentation only issue regarding wording of metric requirements, 19531 that does not affect the implementation of the compiler. 19532 19533@noindent 19534 RM References: D.15 (24/2) 19535 19536 19537@item 19538@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} 19539@cindex AI-0206 (Ada 2012 feature) 19540 19541@noindent 19542 Remote types packages are now allowed to depend on preelaborated packages. 19543 This was formerly considered illegal. 19544 19545@noindent 19546 RM References: E.02.02 (6) 19547 19548 19549 19550@item 19551@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} 19552@cindex AI-0152 (Ada 2012 feature) 19553 19554@noindent 19555 Restriction @code{No_Anonymous_Allocators} prevents the use of allocators 19556 where the type of the returned value is an anonymous access type. 19557 19558@noindent 19559 RM References: H.04 (8/1) 19560@end itemize 19561 19562 19563@node Obsolescent Features 19564@chapter Obsolescent Features 19565 19566@noindent 19567This chapter describes features that are provided by GNAT, but are 19568considered obsolescent since there are preferred ways of achieving 19569the same effect. These features are provided solely for historical 19570compatibility purposes. 19571 19572@menu 19573* pragma No_Run_Time:: 19574* pragma Ravenscar:: 19575* pragma Restricted_Run_Time:: 19576@end menu 19577 19578@node pragma No_Run_Time 19579@section pragma No_Run_Time 19580 19581The pragma @code{No_Run_Time} is used to achieve an affect similar 19582to the use of the "Zero Foot Print" configurable run time, but without 19583requiring a specially configured run time. The result of using this 19584pragma, which must be used for all units in a partition, is to restrict 19585the use of any language features requiring run-time support code. The 19586preferred usage is to use an appropriately configured run-time that 19587includes just those features that are to be made accessible. 19588 19589@node pragma Ravenscar 19590@section pragma Ravenscar 19591 19592The pragma @code{Ravenscar} has exactly the same effect as pragma 19593@code{Profile (Ravenscar)}. The latter usage is preferred since it 19594is part of the new Ada 2005 standard. 19595 19596@node pragma Restricted_Run_Time 19597@section pragma Restricted_Run_Time 19598 19599The pragma @code{Restricted_Run_Time} has exactly the same effect as 19600pragma @code{Profile (Restricted)}. The latter usage is 19601preferred since the Ada 2005 pragma @code{Profile} is intended for 19602this kind of implementation dependent addition. 19603 19604@include fdl.texi 19605@c GNU Free Documentation License 19606 19607@node Index,,GNU Free Documentation License, Top 19608@unnumbered Index 19609 19610@printindex cp 19611 19612@contents 19613 19614@bye 19615