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 Copyright (C) 1995-2003 Free Software Foundation o 12@c o 13@c o 14@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o 15@c o 16@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo 17 18@setfilename gnat_rm.info 19@settitle GNAT Reference Manual 20@setchapternewpage odd 21@syncodeindex fn cp 22 23@include gcc-common.texi 24 25@dircategory GNU Ada tools 26@direntry 27* GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools. 28@end direntry 29 30@copying 31Copyright @copyright{} 1995-2004, Free Software Foundation 32 33Permission is granted to copy, distribute and/or modify this document 34under the terms of the GNU Free Documentation License, Version 1.2 35or any later version published by the Free Software Foundation; 36with the Invariant Sections being ``GNU Free Documentation License'', 37with the Front-Cover Texts being ``GNAT Reference Manual'', and with 38no Back-Cover Texts. A copy of the license is included in the section 39entitled ``GNU Free Documentation License''. 40@end copying 41 42@titlepage 43 44@title GNAT Reference Manual 45@subtitle GNAT, The GNU Ada 95 Compiler 46@subtitle GCC version @value{version-GCC} 47@author Ada Core Technologies, Inc. 48 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 95 Compiler@* 65Version @value{gnat_version}@* 66Document revision level $Revision: 1.13.16.1 $@* 67Date: $Date: 2004/06/09 09:20:43 $ 68 69@noindent 70Ada Core Technologies, Inc. 71 72@noindent 73Copyright @copyright{} 1995-2003, Free Software Foundation 74 75@noindent 76Permission is granted to copy, distribute and/or modify this document 77under the terms of the GNU Free Documentation License, Version 1.1 78or any later version published by the Free Software Foundation; 79with the Invariant Sections being ``GNU Free Documentation License'', with the 80Front-Cover Texts being ``GNAT Reference Manual'', and with no Back-Cover 81Texts. A copy of the license is included in the section entitled ``GNU 82Free Documentation License''. 83 84@menu 85* About This Guide:: 86* Implementation Defined Pragmas:: 87* Implementation Defined Attributes:: 88* Implementation Advice:: 89* Implementation Defined Characteristics:: 90* Intrinsic Subprograms:: 91* Representation Clauses and Pragmas:: 92* Standard Library Routines:: 93* The Implementation of Standard I/O:: 94* The GNAT Library:: 95* Interfacing to Other Languages:: 96* Specialized Needs Annexes:: 97* Implementation of Specific Ada Features:: 98* Project File Reference:: 99* GNU Free Documentation License:: 100* Index:: 101 102 --- The Detailed Node Listing --- 103 104About This Guide 105 106* What This Reference Manual Contains:: 107* Related Information:: 108 109Implementation Defined Pragmas 110 111* Pragma Abort_Defer:: 112* Pragma Ada_83:: 113* Pragma Ada_95:: 114* Pragma Annotate:: 115* Pragma Assert:: 116* Pragma Ast_Entry:: 117* Pragma C_Pass_By_Copy:: 118* Pragma Comment:: 119* Pragma Common_Object:: 120* Pragma Compile_Time_Warning:: 121* Pragma Complex_Representation:: 122* Pragma Component_Alignment:: 123* Pragma Convention_Identifier:: 124* Pragma CPP_Class:: 125* Pragma CPP_Constructor:: 126* Pragma CPP_Virtual:: 127* Pragma CPP_Vtable:: 128* Pragma Debug:: 129* Pragma Elaboration_Checks:: 130* Pragma Eliminate:: 131* Pragma Export_Exception:: 132* Pragma Export_Function:: 133* Pragma Export_Object:: 134* Pragma Export_Procedure:: 135* Pragma Export_Value:: 136* Pragma Export_Valued_Procedure:: 137* Pragma Extend_System:: 138* Pragma External:: 139* Pragma External_Name_Casing:: 140* Pragma Finalize_Storage_Only:: 141* Pragma Float_Representation:: 142* Pragma Ident:: 143* Pragma Import_Exception:: 144* Pragma Import_Function:: 145* Pragma Import_Object:: 146* Pragma Import_Procedure:: 147* Pragma Import_Valued_Procedure:: 148* Pragma Initialize_Scalars:: 149* Pragma Inline_Always:: 150* Pragma Inline_Generic:: 151* Pragma Interface:: 152* Pragma Interface_Name:: 153* Pragma Interrupt_Handler:: 154* Pragma Interrupt_State:: 155* Pragma Keep_Names:: 156* Pragma License:: 157* Pragma Link_With:: 158* Pragma Linker_Alias:: 159* Pragma Linker_Section:: 160* Pragma Long_Float:: 161* Pragma Machine_Attribute:: 162* Pragma Main_Storage:: 163* Pragma No_Return:: 164* Pragma Normalize_Scalars:: 165* Pragma Obsolescent:: 166* Pragma Passive:: 167* Pragma Polling:: 168* Pragma Propagate_Exceptions:: 169* Pragma Psect_Object:: 170* Pragma Pure_Function:: 171* Pragma Ravenscar:: 172* Pragma Restricted_Run_Time:: 173* Pragma Restriction_Warnings:: 174* Pragma Source_File_Name:: 175* Pragma Source_File_Name_Project:: 176* Pragma Source_Reference:: 177* Pragma Stream_Convert:: 178* Pragma Style_Checks:: 179* Pragma Subtitle:: 180* Pragma Suppress_All:: 181* Pragma Suppress_Exception_Locations:: 182* Pragma Suppress_Initialization:: 183* Pragma Task_Info:: 184* Pragma Task_Name:: 185* Pragma Task_Storage:: 186* Pragma Thread_Body:: 187* Pragma Time_Slice:: 188* Pragma Title:: 189* Pragma Unchecked_Union:: 190* Pragma Unimplemented_Unit:: 191* Pragma Universal_Data:: 192* Pragma Unreferenced:: 193* Pragma Unreserve_All_Interrupts:: 194* Pragma Unsuppress:: 195* Pragma Use_VADS_Size:: 196* Pragma Validity_Checks:: 197* Pragma Volatile:: 198* Pragma Warnings:: 199* Pragma Weak_External:: 200 201Implementation Defined Attributes 202 203* Abort_Signal:: 204* Address_Size:: 205* Asm_Input:: 206* Asm_Output:: 207* AST_Entry:: 208* Bit:: 209* Bit_Position:: 210* Code_Address:: 211* Default_Bit_Order:: 212* Elaborated:: 213* Elab_Body:: 214* Elab_Spec:: 215* Emax:: 216* Enum_Rep:: 217* Epsilon:: 218* Fixed_Value:: 219* Has_Discriminants:: 220* Img:: 221* Integer_Value:: 222* Large:: 223* Machine_Size:: 224* Mantissa:: 225* Max_Interrupt_Priority:: 226* Max_Priority:: 227* Maximum_Alignment:: 228* Mechanism_Code:: 229* Null_Parameter:: 230* Object_Size:: 231* Passed_By_Reference:: 232* Range_Length:: 233* Safe_Emax:: 234* Safe_Large:: 235* Small:: 236* Storage_Unit:: 237* Target_Name:: 238* Tick:: 239* To_Address:: 240* Type_Class:: 241* UET_Address:: 242* Unconstrained_Array:: 243* Universal_Literal_String:: 244* Unrestricted_Access:: 245* VADS_Size:: 246* Value_Size:: 247* Wchar_T_Size:: 248* Word_Size:: 249 250The Implementation of Standard I/O 251 252* Standard I/O Packages:: 253* FORM Strings:: 254* Direct_IO:: 255* Sequential_IO:: 256* Text_IO:: 257* Wide_Text_IO:: 258* Stream_IO:: 259* Shared Files:: 260* Open Modes:: 261* Operations on C Streams:: 262* Interfacing to C Streams:: 263 264The GNAT Library 265 266* Ada.Characters.Latin_9 (a-chlat9.ads):: 267* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: 268* Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: 269* Ada.Command_Line.Remove (a-colire.ads):: 270* Ada.Command_Line.Environment (a-colien.ads):: 271* Ada.Direct_IO.C_Streams (a-diocst.ads):: 272* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: 273* Ada.Exceptions.Traceback (a-exctra.ads):: 274* Ada.Sequential_IO.C_Streams (a-siocst.ads):: 275* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: 276* Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: 277* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: 278* Ada.Text_IO.C_Streams (a-tiocst.ads):: 279* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: 280* GNAT.Array_Split (g-arrspl.ads):: 281* GNAT.AWK (g-awk.ads):: 282* GNAT.Bounded_Buffers (g-boubuf.ads):: 283* GNAT.Bounded_Mailboxes (g-boumai.ads):: 284* GNAT.Bubble_Sort (g-bubsor.ads):: 285* GNAT.Bubble_Sort_A (g-busora.ads):: 286* GNAT.Bubble_Sort_G (g-busorg.ads):: 287* GNAT.Calendar (g-calend.ads):: 288* GNAT.Calendar.Time_IO (g-catiio.ads):: 289* GNAT.Case_Util (g-casuti.ads):: 290* GNAT.CGI (g-cgi.ads):: 291* GNAT.CGI.Cookie (g-cgicoo.ads):: 292* GNAT.CGI.Debug (g-cgideb.ads):: 293* GNAT.Command_Line (g-comlin.ads):: 294* GNAT.Compiler_Version (g-comver.ads):: 295* GNAT.Ctrl_C (g-ctrl_c.ads):: 296* GNAT.CRC32 (g-crc32.ads):: 297* GNAT.Current_Exception (g-curexc.ads):: 298* GNAT.Debug_Pools (g-debpoo.ads):: 299* GNAT.Debug_Utilities (g-debuti.ads):: 300* GNAT.Directory_Operations (g-dirope.ads):: 301* GNAT.Dynamic_HTables (g-dynhta.ads):: 302* GNAT.Dynamic_Tables (g-dyntab.ads):: 303* GNAT.Exception_Actions (g-excact.ads):: 304* GNAT.Exception_Traces (g-exctra.ads):: 305* GNAT.Exceptions (g-except.ads):: 306* GNAT.Expect (g-expect.ads):: 307* GNAT.Float_Control (g-flocon.ads):: 308* GNAT.Heap_Sort (g-heasor.ads):: 309* GNAT.Heap_Sort_A (g-hesora.ads):: 310* GNAT.Heap_Sort_G (g-hesorg.ads):: 311* GNAT.HTable (g-htable.ads):: 312* GNAT.IO (g-io.ads):: 313* GNAT.IO_Aux (g-io_aux.ads):: 314* GNAT.Lock_Files (g-locfil.ads):: 315* GNAT.MD5 (g-md5.ads):: 316* GNAT.Memory_Dump (g-memdum.ads):: 317* GNAT.Most_Recent_Exception (g-moreex.ads):: 318* GNAT.OS_Lib (g-os_lib.ads):: 319* GNAT.Perfect_Hash.Generators (g-pehage.ads):: 320* GNAT.Regexp (g-regexp.ads):: 321* GNAT.Registry (g-regist.ads):: 322* GNAT.Regpat (g-regpat.ads):: 323* GNAT.Secondary_Stack_Info (g-sestin.ads):: 324* GNAT.Semaphores (g-semaph.ads):: 325* GNAT.Signals (g-signal.ads):: 326* GNAT.Sockets (g-socket.ads):: 327* GNAT.Source_Info (g-souinf.ads):: 328* GNAT.Spell_Checker (g-speche.ads):: 329* GNAT.Spitbol.Patterns (g-spipat.ads):: 330* GNAT.Spitbol (g-spitbo.ads):: 331* GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: 332* GNAT.Spitbol.Table_Integer (g-sptain.ads):: 333* GNAT.Spitbol.Table_VString (g-sptavs.ads):: 334* GNAT.Strings (g-string.ads):: 335* GNAT.String_Split (g-strspl.ads):: 336* GNAT.Table (g-table.ads):: 337* GNAT.Task_Lock (g-tasloc.ads):: 338* GNAT.Threads (g-thread.ads):: 339* GNAT.Traceback (g-traceb.ads):: 340* GNAT.Traceback.Symbolic (g-trasym.ads):: 341* GNAT.Wide_String_Split (g-wistsp.ads):: 342* Interfaces.C.Extensions (i-cexten.ads):: 343* Interfaces.C.Streams (i-cstrea.ads):: 344* Interfaces.CPP (i-cpp.ads):: 345* Interfaces.Os2lib (i-os2lib.ads):: 346* Interfaces.Os2lib.Errors (i-os2err.ads):: 347* Interfaces.Os2lib.Synchronization (i-os2syn.ads):: 348* Interfaces.Os2lib.Threads (i-os2thr.ads):: 349* Interfaces.Packed_Decimal (i-pacdec.ads):: 350* Interfaces.VxWorks (i-vxwork.ads):: 351* Interfaces.VxWorks.IO (i-vxwoio.ads):: 352* System.Address_Image (s-addima.ads):: 353* System.Assertions (s-assert.ads):: 354* System.Memory (s-memory.ads):: 355* System.Partition_Interface (s-parint.ads):: 356* System.Task_Info (s-tasinf.ads):: 357* System.Wch_Cnv (s-wchcnv.ads):: 358* System.Wch_Con (s-wchcon.ads):: 359 360Text_IO 361 362* Text_IO Stream Pointer Positioning:: 363* Text_IO Reading and Writing Non-Regular Files:: 364* Get_Immediate:: 365* Treating Text_IO Files as Streams:: 366* Text_IO Extensions:: 367* Text_IO Facilities for Unbounded Strings:: 368 369Wide_Text_IO 370 371* Wide_Text_IO Stream Pointer Positioning:: 372* Wide_Text_IO Reading and Writing Non-Regular Files:: 373 374Interfacing to Other Languages 375 376* Interfacing to C:: 377* Interfacing to C++:: 378* Interfacing to COBOL:: 379* Interfacing to Fortran:: 380* Interfacing to non-GNAT Ada code:: 381 382Specialized Needs Annexes 383 384Implementation of Specific Ada Features 385* Machine Code Insertions:: 386* GNAT Implementation of Tasking:: 387* GNAT Implementation of Shared Passive Packages:: 388* Code Generation for Array Aggregates:: 389 390Project File Reference 391 392GNU Free Documentation License 393 394Index 395@end menu 396 397@end ifnottex 398 399@node About This Guide 400@unnumbered About This Guide 401 402@noindent 403This manual contains useful information in writing programs using the 404GNAT compiler. It includes information on implementation dependent 405characteristics of GNAT, including all the information required by Annex 406M of the standard. 407 408Ada 95 is designed to be highly portable. 409In general, a program will have the same effect even when compiled by 410different compilers on different platforms. 411However, since Ada 95 is designed to be used in a 412wide variety of applications, it also contains a number of system 413dependent features to be used in interfacing to the external world. 414@cindex Implementation-dependent features 415@cindex Portability 416 417Note: Any program that makes use of implementation-dependent features 418may be non-portable. You should follow good programming practice and 419isolate and clearly document any sections of your program that make use 420of these features in a non-portable manner. 421 422@menu 423* What This Reference Manual Contains:: 424* Conventions:: 425* Related Information:: 426@end menu 427 428@node What This Reference Manual Contains 429@unnumberedsec What This Reference Manual Contains 430 431@noindent 432This reference manual contains the following chapters: 433 434@itemize @bullet 435@item 436@ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent 437pragmas, which can be used to extend and enhance the functionality of the 438compiler. 439 440@item 441@ref{Implementation Defined Attributes}, lists GNAT 442implementation-dependent attributes which can be used to extend and 443enhance the functionality of the compiler. 444 445@item 446@ref{Implementation Advice}, provides information on generally 447desirable behavior which are not requirements that all compilers must 448follow since it cannot be provided on all systems, or which may be 449undesirable on some systems. 450 451@item 452@ref{Implementation Defined Characteristics}, provides a guide to 453minimizing implementation dependent features. 454 455@item 456@ref{Intrinsic Subprograms}, describes the intrinsic subprograms 457implemented by GNAT, and how they can be imported into user 458application programs. 459 460@item 461@ref{Representation Clauses and Pragmas}, describes in detail the 462way that GNAT represents data, and in particular the exact set 463of representation clauses and pragmas that is accepted. 464 465@item 466@ref{Standard Library Routines}, provides a listing of packages and a 467brief description of the functionality that is provided by Ada's 468extensive set of standard library routines as implemented by GNAT@. 469 470@item 471@ref{The Implementation of Standard I/O}, details how the GNAT 472implementation of the input-output facilities. 473 474@item 475@ref{The GNAT Library}, is a catalog of packages that complement 476the Ada predefined library. 477 478@item 479@ref{Interfacing to Other Languages}, describes how programs 480written in Ada using GNAT can be interfaced to other programming 481languages. 482 483@ref{Specialized Needs Annexes}, describes the GNAT implementation of all 484of the specialized needs annexes. 485 486@item 487@ref{Implementation of Specific Ada Features}, discusses issues related 488to GNAT's implementation of machine code insertions, tasking, and several 489other features. 490 491@item 492@ref{Project File Reference}, presents the syntax and semantics 493of project files. 494 495@end itemize 496 497@cindex Ada 95 ISO/ANSI Standard 498@noindent 499This reference manual assumes that you are familiar with Ada 95 500language, as described in the International Standard 501ANSI/ISO/IEC-8652:1995, Jan 1995. 502 503@node Conventions 504@unnumberedsec Conventions 505@cindex Conventions, typographical 506@cindex Typographical conventions 507 508@noindent 509Following are examples of the typographical and graphic conventions used 510in this guide: 511 512@itemize @bullet 513@item 514@code{Functions}, @code{utility program names}, @code{standard names}, 515and @code{classes}. 516 517@item 518@code{Option flags} 519 520@item 521@file{File Names}, @samp{button names}, and @samp{field names}. 522 523@item 524@code{Variables}. 525 526@item 527@emph{Emphasis}. 528 529@item 530[optional information or parameters] 531 532@item 533Examples are described by text 534@smallexample 535and then shown this way. 536@end smallexample 537@end itemize 538 539@noindent 540Commands that are entered by the user are preceded in this manual by the 541characters @samp{$ } (dollar sign followed by space). If your system uses this 542sequence as a prompt, then the commands will appear exactly as you see them 543in the manual. If your system uses some other prompt, then the command will 544appear with the @samp{$} replaced by whatever prompt character you are using. 545 546@node Related Information 547@unnumberedsec Related Information 548@noindent 549See the following documents for further information on GNAT: 550 551@itemize @bullet 552@item 553@cite{GNAT User's Guide}, which provides information on how to use 554the GNAT compiler system. 555 556@item 557@cite{Ada 95 Reference Manual}, which contains all reference 558material for the Ada 95 programming language. 559 560@item 561@cite{Ada 95 Annotated Reference Manual}, which is an annotated version 562of the standard reference manual cited above. The annotations describe 563detailed aspects of the design decision, and in particular contain useful 564sections on Ada 83 compatibility. 565 566@item 567@cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms}, 568which contains specific information on compatibility between GNAT and 569DEC Ada 83 systems. 570 571@item 572@cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which 573describes in detail the pragmas and attributes provided by the DEC Ada 83 574compiler system. 575 576@end itemize 577 578@node Implementation Defined Pragmas 579@chapter Implementation Defined Pragmas 580 581@noindent 582Ada 95 defines a set of pragmas that can be used to supply additional 583information to the compiler. These language defined pragmas are 584implemented in GNAT and work as described in the Ada 95 Reference 585Manual. 586 587In addition, Ada 95 allows implementations to define additional pragmas 588whose meaning is defined by the implementation. GNAT provides a number 589of these implementation-dependent pragmas which can be used to extend 590and enhance the functionality of the compiler. This section of the GNAT 591Reference Manual describes these additional pragmas. 592 593Note that any program using these pragmas may not be portable to other 594compilers (although GNAT implements this set of pragmas on all 595platforms). Therefore if portability to other compilers is an important 596consideration, the use of these pragmas should be minimized. 597 598@menu 599* Pragma Abort_Defer:: 600* Pragma Ada_83:: 601* Pragma Ada_95:: 602* Pragma Annotate:: 603* Pragma Assert:: 604* Pragma Ast_Entry:: 605* Pragma C_Pass_By_Copy:: 606* Pragma Comment:: 607* Pragma Common_Object:: 608* Pragma Compile_Time_Warning:: 609* Pragma Complex_Representation:: 610* Pragma Component_Alignment:: 611* Pragma Convention_Identifier:: 612* Pragma CPP_Class:: 613* Pragma CPP_Constructor:: 614* Pragma CPP_Virtual:: 615* Pragma CPP_Vtable:: 616* Pragma Debug:: 617* Pragma Elaboration_Checks:: 618* Pragma Eliminate:: 619* Pragma Export_Exception:: 620* Pragma Export_Function:: 621* Pragma Export_Object:: 622* Pragma Export_Procedure:: 623* Pragma Export_Value:: 624* Pragma Export_Valued_Procedure:: 625* Pragma Extend_System:: 626* Pragma External:: 627* Pragma External_Name_Casing:: 628* Pragma Finalize_Storage_Only:: 629* Pragma Float_Representation:: 630* Pragma Ident:: 631* Pragma Import_Exception:: 632* Pragma Import_Function:: 633* Pragma Import_Object:: 634* Pragma Import_Procedure:: 635* Pragma Import_Valued_Procedure:: 636* Pragma Initialize_Scalars:: 637* Pragma Inline_Always:: 638* Pragma Inline_Generic:: 639* Pragma Interface:: 640* Pragma Interface_Name:: 641* Pragma Interrupt_Handler:: 642* Pragma Interrupt_State:: 643* Pragma Keep_Names:: 644* Pragma License:: 645* Pragma Link_With:: 646* Pragma Linker_Alias:: 647* Pragma Linker_Section:: 648* Pragma Long_Float:: 649* Pragma Machine_Attribute:: 650* Pragma Main_Storage:: 651* Pragma No_Return:: 652* Pragma Normalize_Scalars:: 653* Pragma Obsolescent:: 654* Pragma Passive:: 655* Pragma Polling:: 656* Pragma Propagate_Exceptions:: 657* Pragma Psect_Object:: 658* Pragma Pure_Function:: 659* Pragma Ravenscar:: 660* Pragma Restricted_Run_Time:: 661* Pragma Restriction_Warnings:: 662* Pragma Source_File_Name:: 663* Pragma Source_File_Name_Project:: 664* Pragma Source_Reference:: 665* Pragma Stream_Convert:: 666* Pragma Style_Checks:: 667* Pragma Subtitle:: 668* Pragma Suppress_All:: 669* Pragma Suppress_Exception_Locations:: 670* Pragma Suppress_Initialization:: 671* Pragma Task_Info:: 672* Pragma Task_Name:: 673* Pragma Task_Storage:: 674* Pragma Thread_Body:: 675* Pragma Time_Slice:: 676* Pragma Title:: 677* Pragma Unchecked_Union:: 678* Pragma Unimplemented_Unit:: 679* Pragma Universal_Data:: 680* Pragma Unreferenced:: 681* Pragma Unreserve_All_Interrupts:: 682* Pragma Unsuppress:: 683* Pragma Use_VADS_Size:: 684* Pragma Validity_Checks:: 685* Pragma Volatile:: 686* Pragma Warnings:: 687* Pragma Weak_External:: 688@end menu 689 690@node Pragma Abort_Defer 691@unnumberedsec Pragma Abort_Defer 692@findex Abort_Defer 693@cindex Deferring aborts 694@noindent 695Syntax: 696@smallexample 697pragma Abort_Defer; 698@end smallexample 699 700@noindent 701This pragma must appear at the start of the statement sequence of a 702handled sequence of statements (right after the @code{begin}). It has 703the effect of deferring aborts for the sequence of statements (but not 704for the declarations or handlers, if any, associated with this statement 705sequence). 706 707@node Pragma Ada_83 708@unnumberedsec Pragma Ada_83 709@findex Ada_83 710@noindent 711Syntax: 712@smallexample @c ada 713pragma Ada_83; 714@end smallexample 715 716@noindent 717A configuration pragma that establishes Ada 83 mode for the unit to 718which it applies, regardless of the mode set by the command line 719switches. In Ada 83 mode, GNAT attempts to be as compatible with 720the syntax and semantics of Ada 83, as defined in the original Ada 72183 Reference Manual as possible. In particular, the new Ada 95 722keywords are not recognized, optional package bodies are allowed, 723and generics may name types with unknown discriminants without using 724the @code{(<>)} notation. In addition, some but not all of the additional 725restrictions of Ada 83 are enforced. 726 727Ada 83 mode is intended for two purposes. Firstly, it allows existing 728legacy Ada 83 code to be compiled and adapted to GNAT with less effort. 729Secondly, it aids in keeping code backwards compatible with Ada 83. 730However, there is no guarantee that code that is processed correctly 731by GNAT in Ada 83 mode will in fact compile and execute with an Ada 73283 compiler, since GNAT does not enforce all the additional checks 733required by Ada 83. 734 735@node Pragma Ada_95 736@unnumberedsec Pragma Ada_95 737@findex Ada_95 738@noindent 739Syntax: 740@smallexample @c ada 741pragma Ada_95; 742@end smallexample 743 744@noindent 745A configuration pragma that establishes Ada 95 mode for the unit to which 746it applies, regardless of the mode set by the command line switches. 747This mode is set automatically for the @code{Ada} and @code{System} 748packages and their children, so you need not specify it in these 749contexts. This pragma is useful when writing a reusable component that 750itself uses Ada 95 features, but which is intended to be usable from 751either Ada 83 or Ada 95 programs. 752 753@node Pragma Annotate 754@unnumberedsec Pragma Annotate 755@findex Annotate 756@noindent 757Syntax: 758@smallexample @c ada 759pragma Annotate (IDENTIFIER @{, ARG@}); 760 761ARG ::= NAME | EXPRESSION 762@end smallexample 763 764@noindent 765This pragma is used to annotate programs. @var{identifier} identifies 766the type of annotation. GNAT verifies this is an identifier, but does 767not otherwise analyze it. The @var{arg} argument 768can be either a string literal or an 769expression. String literals are assumed to be of type 770@code{Standard.String}. Names of entities are simply analyzed as entity 771names. All other expressions are analyzed as expressions, and must be 772unambiguous. 773 774The analyzed pragma is retained in the tree, but not otherwise processed 775by any part of the GNAT compiler. This pragma is intended for use by 776external tools, including ASIS@. 777 778@node Pragma Assert 779@unnumberedsec Pragma Assert 780@findex Assert 781@noindent 782Syntax: 783@smallexample @c ada 784pragma Assert ( 785 boolean_EXPRESSION 786 [, static_string_EXPRESSION]); 787@end smallexample 788 789@noindent 790The effect of this pragma depends on whether the corresponding command 791line switch is set to activate assertions. The pragma expands into code 792equivalent to the following: 793 794@smallexample @c ada 795if assertions-enabled then 796 if not boolean_EXPRESSION then 797 System.Assertions.Raise_Assert_Failure 798 (string_EXPRESSION); 799 end if; 800end if; 801@end smallexample 802 803@noindent 804The string argument, if given, is the message that will be associated 805with the exception occurrence if the exception is raised. If no second 806argument is given, the default message is @samp{@var{file}:@var{nnn}}, 807where @var{file} is the name of the source file containing the assert, 808and @var{nnn} is the line number of the assert. A pragma is not a 809statement, so if a statement sequence contains nothing but a pragma 810assert, then a null statement is required in addition, as in: 811 812@smallexample @c ada 813@dots{} 814if J > 3 then 815 pragma Assert (K > 3, "Bad value for K"); 816 null; 817end if; 818@end smallexample 819 820@noindent 821Note that, as with the @code{if} statement to which it is equivalent, the 822type of the expression is either @code{Standard.Boolean}, or any type derived 823from this standard type. 824 825If assertions are disabled (switch @code{-gnata} not used), then there 826is no effect (and in particular, any side effects from the expression 827are suppressed). More precisely it is not quite true that the pragma 828has no effect, since the expression is analyzed, and may cause types 829to be frozen if they are mentioned here for the first time. 830 831If assertions are enabled, then the given expression is tested, and if 832it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called 833which results in the raising of @code{Assert_Failure} with the given message. 834 835If the boolean expression has side effects, these side effects will turn 836on and off with the setting of the assertions mode, resulting in 837assertions that have an effect on the program. You should generally 838avoid side effects in the expression arguments of this pragma. However, 839the expressions are analyzed for semantic correctness whether or not 840assertions are enabled, so turning assertions on and off cannot affect 841the legality of a program. 842 843@node Pragma Ast_Entry 844@unnumberedsec Pragma Ast_Entry 845@cindex OpenVMS 846@findex Ast_Entry 847@noindent 848Syntax: 849@smallexample @c ada 850pragma AST_Entry (entry_IDENTIFIER); 851@end smallexample 852 853@noindent 854This pragma is implemented only in the OpenVMS implementation of GNAT@. The 855argument is the simple name of a single entry; at most one @code{AST_Entry} 856pragma is allowed for any given entry. This pragma must be used in 857conjunction with the @code{AST_Entry} attribute, and is only allowed after 858the entry declaration and in the same task type specification or single task 859as the entry to which it applies. This pragma specifies that the given entry 860may be used to handle an OpenVMS asynchronous system trap (@code{AST}) 861resulting from an OpenVMS system service call. The pragma does not affect 862normal use of the entry. For further details on this pragma, see the 863DEC Ada Language Reference Manual, section 9.12a. 864 865@node Pragma C_Pass_By_Copy 866@unnumberedsec Pragma C_Pass_By_Copy 867@cindex Passing by copy 868@findex C_Pass_By_Copy 869@noindent 870Syntax: 871@smallexample @c ada 872pragma C_Pass_By_Copy 873 ([Max_Size =>] static_integer_EXPRESSION); 874@end smallexample 875 876@noindent 877Normally the default mechanism for passing C convention records to C 878convention subprograms is to pass them by reference, as suggested by RM 879B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change 880this default, by requiring that record formal parameters be passed by 881copy if all of the following conditions are met: 882 883@itemize @bullet 884@item 885The size of the record type does not exceed@*@var{static_integer_expression}. 886@item 887The record type has @code{Convention C}. 888@item 889The formal parameter has this record type, and the subprogram has a 890foreign (non-Ada) convention. 891@end itemize 892 893@noindent 894If these conditions are met the argument is passed by copy, i.e.@: in a 895manner consistent with what C expects if the corresponding formal in the 896C prototype is a struct (rather than a pointer to a struct). 897 898You can also pass records by copy by specifying the convention 899@code{C_Pass_By_Copy} for the record type, or by using the extended 900@code{Import} and @code{Export} pragmas, which allow specification of 901passing mechanisms on a parameter by parameter basis. 902 903@node Pragma Comment 904@unnumberedsec Pragma Comment 905@findex Comment 906@noindent 907Syntax: 908 909@smallexample @c ada 910pragma Comment (static_string_EXPRESSION); 911@end smallexample 912 913@noindent 914This is almost identical in effect to pragma @code{Ident}. It allows the 915placement of a comment into the object file and hence into the 916executable file if the operating system permits such usage. The 917difference is that @code{Comment}, unlike @code{Ident}, has 918no limitations on placement of the pragma (it can be placed 919anywhere in the main source unit), and if more than one pragma 920is used, all comments are retained. 921 922@node Pragma Common_Object 923@unnumberedsec Pragma Common_Object 924@findex Common_Object 925@noindent 926Syntax: 927 928@smallexample @c ada 929pragma Common_Object ( 930 [Internal =>] LOCAL_NAME, 931 [, [External =>] EXTERNAL_SYMBOL] 932 [, [Size =>] EXTERNAL_SYMBOL] ); 933 934EXTERNAL_SYMBOL ::= 935 IDENTIFIER 936| static_string_EXPRESSION 937@end smallexample 938 939@noindent 940This pragma enables the shared use of variables stored in overlaid 941linker areas corresponding to the use of @code{COMMON} 942in Fortran. The single 943object @var{local_name} is assigned to the area designated by 944the @var{External} argument. 945You may define a record to correspond to a series 946of fields. The @var{size} argument 947is syntax checked in GNAT, but otherwise ignored. 948 949@code{Common_Object} is not supported on all platforms. If no 950support is available, then the code generator will issue a message 951indicating that the necessary attribute for implementation of this 952pragma is not available. 953 954@node Pragma Compile_Time_Warning 955@unnumberedsec Pragma Compile_Time_Warning 956@findex Compile_Time_Warning 957@noindent 958Syntax: 959 960@smallexample @c ada 961pragma Compile_Time_Warning 962 (boolean_EXPRESSION, static_string_EXPRESSION); 963@end smallexample 964 965@noindent 966This pragma can be used to generate additional compile time warnings. It 967is particularly useful in generics, where warnings can be issued for 968specific problematic instantiations. The first parameter is a boolean 969expression. The pragma is effective only if the value of this expression 970is known at compile time, and has the value True. The set of expressions 971whose values are known at compile time includes all static boolean 972expressions, and also other values which the compiler can determine 973at compile time (e.g. the size of a record type set by an explicit 974size representation clause, or the value of a variable which was 975initialized to a constant and is known not to have been modified). 976If these conditions are met, a warning message is generated using 977the value given as the second argument. This string value may contain 978embedded ASCII.LF characters to break the message into multiple lines. 979 980@node Pragma Complex_Representation 981@unnumberedsec Pragma Complex_Representation 982@findex Complex_Representation 983@noindent 984Syntax: 985 986@smallexample @c ada 987pragma Complex_Representation 988 ([Entity =>] LOCAL_NAME); 989@end smallexample 990 991@noindent 992The @var{Entity} argument must be the name of a record type which has 993two fields of the same floating-point type. The effect of this pragma is 994to force gcc to use the special internal complex representation form for 995this record, which may be more efficient. Note that this may result in 996the code for this type not conforming to standard ABI (application 997binary interface) requirements for the handling of record types. For 998example, in some environments, there is a requirement for passing 999records by pointer, and the use of this pragma may result in passing 1000this type in floating-point registers. 1001 1002@node Pragma Component_Alignment 1003@unnumberedsec Pragma Component_Alignment 1004@cindex Alignments of components 1005@findex Component_Alignment 1006@noindent 1007Syntax: 1008 1009@smallexample @c ada 1010pragma Component_Alignment ( 1011 [Form =>] ALIGNMENT_CHOICE 1012 [, [Name =>] type_LOCAL_NAME]); 1013 1014ALIGNMENT_CHOICE ::= 1015 Component_Size 1016| Component_Size_4 1017| Storage_Unit 1018| Default 1019@end smallexample 1020 1021@noindent 1022Specifies the alignment of components in array or record types. 1023The meaning of the @var{Form} argument is as follows: 1024 1025@table @code 1026@findex Component_Size 1027@item Component_Size 1028Aligns scalar components and subcomponents of the array or record type 1029on boundaries appropriate to their inherent size (naturally 1030aligned). For example, 1-byte components are aligned on byte boundaries, 10312-byte integer components are aligned on 2-byte boundaries, 4-byte 1032integer components are aligned on 4-byte boundaries and so on. These 1033alignment rules correspond to the normal rules for C compilers on all 1034machines except the VAX@. 1035 1036@findex Component_Size_4 1037@item Component_Size_4 1038Naturally aligns components with a size of four or fewer 1039bytes. Components that are larger than 4 bytes are placed on the next 10404-byte boundary. 1041 1042@findex Storage_Unit 1043@item Storage_Unit 1044Specifies that array or record components are byte aligned, i.e.@: 1045aligned on boundaries determined by the value of the constant 1046@code{System.Storage_Unit}. 1047 1048@cindex OpenVMS 1049@item Default 1050Specifies that array or record components are aligned on default 1051boundaries, appropriate to the underlying hardware or operating system or 1052both. For OpenVMS VAX systems, the @code{Default} choice is the same as 1053the @code{Storage_Unit} choice (byte alignment). For all other systems, 1054the @code{Default} choice is the same as @code{Component_Size} (natural 1055alignment). 1056@end table 1057 1058@noindent 1059If the @code{Name} parameter is present, @var{type_local_name} must 1060refer to a local record or array type, and the specified alignment 1061choice applies to the specified type. The use of 1062@code{Component_Alignment} together with a pragma @code{Pack} causes the 1063@code{Component_Alignment} pragma to be ignored. The use of 1064@code{Component_Alignment} together with a record representation clause 1065is only effective for fields not specified by the representation clause. 1066 1067If the @code{Name} parameter is absent, the pragma can be used as either 1068a configuration pragma, in which case it applies to one or more units in 1069accordance with the normal rules for configuration pragmas, or it can be 1070used within a declarative part, in which case it applies to types that 1071are declared within this declarative part, or within any nested scope 1072within this declarative part. In either case it specifies the alignment 1073to be applied to any record or array type which has otherwise standard 1074representation. 1075 1076If the alignment for a record or array type is not specified (using 1077pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep 1078clause), the GNAT uses the default alignment as described previously. 1079 1080@node Pragma Convention_Identifier 1081@unnumberedsec Pragma Convention_Identifier 1082@findex Convention_Identifier 1083@cindex Conventions, synonyms 1084@noindent 1085Syntax: 1086 1087@smallexample @c ada 1088pragma Convention_Identifier ( 1089 [Name =>] IDENTIFIER, 1090 [Convention =>] convention_IDENTIFIER); 1091@end smallexample 1092 1093@noindent 1094This pragma provides a mechanism for supplying synonyms for existing 1095convention identifiers. The @code{Name} identifier can subsequently 1096be used as a synonym for the given convention in other pragmas (including 1097for example pragma @code{Import} or another @code{Convention_Identifier} 1098pragma). As an example of the use of this, suppose you had legacy code 1099which used Fortran77 as the identifier for Fortran. Then the pragma: 1100 1101@smallexample @c ada 1102pragma Convention_Indentifier (Fortran77, Fortran); 1103@end smallexample 1104 1105@noindent 1106would allow the use of the convention identifier @code{Fortran77} in 1107subsequent code, avoiding the need to modify the sources. As another 1108example, you could use this to parametrize convention requirements 1109according to systems. Suppose you needed to use @code{Stdcall} on 1110windows systems, and @code{C} on some other system, then you could 1111define a convention identifier @code{Library} and use a single 1112@code{Convention_Identifier} pragma to specify which convention 1113would be used system-wide. 1114 1115@node Pragma CPP_Class 1116@unnumberedsec Pragma CPP_Class 1117@findex CPP_Class 1118@cindex Interfacing with C++ 1119@noindent 1120Syntax: 1121 1122@smallexample @c ada 1123pragma CPP_Class ([Entity =>] LOCAL_NAME); 1124@end smallexample 1125 1126@noindent 1127The argument denotes an entity in the current declarative region 1128that is declared as a tagged or untagged record type. It indicates that 1129the type corresponds to an externally declared C++ class type, and is to 1130be laid out the same way that C++ would lay out the type. 1131 1132If (and only if) the type is tagged, at least one component in the 1133record must be of type @code{Interfaces.CPP.Vtable_Ptr}, corresponding 1134to the C++ Vtable (or Vtables in the case of multiple inheritance) used 1135for dispatching. 1136 1137Types for which @code{CPP_Class} is specified do not have assignment or 1138equality operators defined (such operations can be imported or declared 1139as subprograms as required). Initialization is allowed only by 1140constructor functions (see pragma @code{CPP_Constructor}). 1141 1142Pragma @code{CPP_Class} is intended primarily for automatic generation 1143using an automatic binding generator tool. 1144See @ref{Interfacing to C++} for related information. 1145 1146@node Pragma CPP_Constructor 1147@unnumberedsec Pragma CPP_Constructor 1148@cindex Interfacing with C++ 1149@findex CPP_Constructor 1150@noindent 1151Syntax: 1152 1153@smallexample @c ada 1154pragma CPP_Constructor ([Entity =>] LOCAL_NAME); 1155@end smallexample 1156 1157@noindent 1158This pragma identifies an imported function (imported in the usual way 1159with pragma @code{Import}) as corresponding to a C++ 1160constructor. The argument is a name that must have been 1161previously mentioned in a pragma @code{Import} 1162with @code{Convention} = @code{CPP}, and must be of one of the following 1163forms: 1164 1165@itemize @bullet 1166@item 1167@code{function @var{Fname} return @var{T}'Class} 1168 1169@item 1170@code{function @var{Fname} (@dots{}) return @var{T}'Class} 1171@end itemize 1172 1173@noindent 1174where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies. 1175 1176The first form is the default constructor, used when an object of type 1177@var{T} is created on the Ada side with no explicit constructor. Other 1178constructors (including the copy constructor, which is simply a special 1179case of the second form in which the one and only argument is of type 1180@var{T}), can only appear in two contexts: 1181 1182@itemize @bullet 1183@item 1184On the right side of an initialization of an object of type @var{T}. 1185@item 1186In an extension aggregate for an object of a type derived from @var{T}. 1187@end itemize 1188 1189@noindent 1190Although the constructor is described as a function that returns a value 1191on the Ada side, it is typically a procedure with an extra implicit 1192argument (the object being initialized) at the implementation 1193level. GNAT issues the appropriate call, whatever it is, to get the 1194object properly initialized. 1195 1196In the case of derived objects, you may use one of two possible forms 1197for declaring and creating an object: 1198 1199@itemize @bullet 1200@item @code{New_Object : Derived_T} 1201@item @code{New_Object : Derived_T := (@var{constructor-call with} @dots{})} 1202@end itemize 1203 1204@noindent 1205In the first case the default constructor is called and extension fields 1206if any are initialized according to the default initialization 1207expressions in the Ada declaration. In the second case, the given 1208constructor is called and the extension aggregate indicates the explicit 1209values of the extension fields. 1210 1211If no constructors are imported, it is impossible to create any objects 1212on the Ada side. If no default constructor is imported, only the 1213initialization forms using an explicit call to a constructor are 1214permitted. 1215 1216Pragma @code{CPP_Constructor} is intended primarily for automatic generation 1217using an automatic binding generator tool. 1218See @ref{Interfacing to C++} for more related information. 1219 1220@node Pragma CPP_Virtual 1221@unnumberedsec Pragma CPP_Virtual 1222@cindex Interfacing to C++ 1223@findex CPP_Virtual 1224@noindent 1225Syntax: 1226 1227@smallexample @c ada 1228pragma CPP_Virtual 1229 [Entity =>] ENTITY, 1230 [, [Vtable_Ptr =>] vtable_ENTITY,] 1231 [, [Position =>] static_integer_EXPRESSION]); 1232@end smallexample 1233 1234@noindent 1235This pragma serves the same function as pragma @code{Import} in that 1236case of a virtual function imported from C++. The @var{Entity} argument 1237must be a 1238primitive subprogram of a tagged type to which pragma @code{CPP_Class} 1239applies. The @var{Vtable_Ptr} argument specifies 1240the Vtable_Ptr component which contains the 1241entry for this virtual function. The @var{Position} argument 1242is the sequential number 1243counting virtual functions for this Vtable starting at 1. 1244 1245The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if 1246there is one Vtable_Ptr present (single inheritance case) and all 1247virtual functions are imported. In that case the compiler can deduce both 1248these values. 1249 1250No @code{External_Name} or @code{Link_Name} arguments are required for a 1251virtual function, since it is always accessed indirectly via the 1252appropriate Vtable entry. 1253 1254Pragma @code{CPP_Virtual} is intended primarily for automatic generation 1255using an automatic binding generator tool. 1256See @ref{Interfacing to C++} for related information. 1257 1258@node Pragma CPP_Vtable 1259@unnumberedsec Pragma CPP_Vtable 1260@cindex Interfacing with C++ 1261@findex CPP_Vtable 1262@noindent 1263Syntax: 1264 1265@smallexample @c ada 1266pragma CPP_Vtable ( 1267 [Entity =>] ENTITY, 1268 [Vtable_Ptr =>] vtable_ENTITY, 1269 [Entry_Count =>] static_integer_EXPRESSION); 1270@end smallexample 1271 1272@noindent 1273Given a record to which the pragma @code{CPP_Class} applies, 1274this pragma can be specified for each component of type 1275@code{CPP.Interfaces.Vtable_Ptr}. 1276@var{Entity} is the tagged type, @var{Vtable_Ptr} 1277is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is 1278the number of virtual functions on the C++ side. Not all of these 1279functions need to be imported on the Ada side. 1280 1281You may omit the @code{CPP_Vtable} pragma if there is only one 1282@code{Vtable_Ptr} component in the record and all virtual functions are 1283imported on the Ada side (the default value for the entry count in this 1284case is simply the total number of virtual functions). 1285 1286Pragma @code{CPP_Vtable} is intended primarily for automatic generation 1287using an automatic binding generator tool. 1288See @ref{Interfacing to C++} for related information. 1289 1290@node Pragma Debug 1291@unnumberedsec Pragma Debug 1292@findex Debug 1293@noindent 1294Syntax: 1295 1296@smallexample @c ada 1297pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON); 1298 1299PROCEDURE_CALL_WITHOUT_SEMICOLON ::= 1300 PROCEDURE_NAME 1301| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART 1302@end smallexample 1303 1304@noindent 1305The argument has the syntactic form of an expression, meeting the 1306syntactic requirements for pragmas. 1307 1308If assertions are not enabled on the command line, this pragma has no 1309effect. If asserts are enabled, the semantics of the pragma is exactly 1310equivalent to the procedure call statement corresponding to the argument 1311with a terminating semicolon. Pragmas are permitted in sequences of 1312declarations, so you can use pragma @code{Debug} to intersperse calls to 1313debug procedures in the middle of declarations. 1314 1315@node Pragma Elaboration_Checks 1316@unnumberedsec Pragma Elaboration_Checks 1317@cindex Elaboration control 1318@findex Elaboration_Checks 1319@noindent 1320Syntax: 1321 1322@smallexample @c ada 1323pragma Elaboration_Checks (RM | Static); 1324@end smallexample 1325 1326@noindent 1327This is a configuration pragma that provides control over the 1328elaboration model used by the compilation affected by the 1329pragma. If the parameter is RM, then the dynamic elaboration 1330model described in the Ada Reference Manual is used, as though 1331the @code{-gnatE} switch had been specified on the command 1332line. If the parameter is Static, then the default GNAT static 1333model is used. This configuration pragma overrides the setting 1334of the command line. For full details on the elaboration models 1335used by the GNAT compiler, see section ``Elaboration Order 1336Handling in GNAT'' in the @cite{GNAT User's Guide}. 1337 1338@node Pragma Eliminate 1339@unnumberedsec Pragma Eliminate 1340@cindex Elimination of unused subprograms 1341@findex Eliminate 1342@noindent 1343Syntax: 1344 1345@smallexample @c ada 1346pragma Eliminate ( 1347 [Unit_Name =>] IDENTIFIER | 1348 SELECTED_COMPONENT); 1349 1350pragma Eliminate ( 1351 [Unit_Name =>] IDENTIFIER | 1352 SELECTED_COMPONENT, 1353 [Entity =>] IDENTIFIER | 1354 SELECTED_COMPONENT | 1355 STRING_LITERAL 1356 [,[Parameter_Types =>] PARAMETER_TYPES] 1357 [,[Result_Type =>] result_SUBTYPE_NAME] 1358 [,[Homonym_Number =>] INTEGER_LITERAL]); 1359 1360PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@}) 1361SUBTYPE_NAME ::= STRING_LITERAL 1362@end smallexample 1363 1364@noindent 1365This pragma indicates that the given entity is not used outside the 1366compilation unit it is defined in. The entity may be either a subprogram 1367or a variable. 1368 1369If the entity to be eliminated is a library level subprogram, then 1370the first form of pragma @code{Eliminate} is used with only a single argument. 1371In this form, the @code{Unit_Name} argument specifies the name of the 1372library level unit to be eliminated. 1373 1374In all other cases, both @code{Unit_Name} and @code{Entity} arguments 1375are required. If item is an entity of a library package, then the first 1376argument specifies the unit name, and the second argument specifies 1377the particular entity. If the second argument is in string form, it must 1378correspond to the internal manner in which GNAT stores entity names (see 1379compilation unit Namet in the compiler sources for details). 1380 1381The remaining parameters are optionally used to distinguish 1382between overloaded subprograms. There are two ways of doing this. 1383 1384Use @code{Parameter_Types} and @code{Result_Type} to specify the 1385profile of the subprogram to be eliminated in a manner similar to that 1386used for 1387the extended @code{Import} and @code{Export} pragmas, except that the 1388subtype names are always given as string literals, again corresponding 1389to the internal manner in which GNAT stores entity names. 1390 1391Alternatively, the @code{Homonym_Number} parameter is used to specify 1392which overloaded alternative is to be eliminated. A value of 1 indicates 1393the first subprogram (in lexical order), 2 indicates the second etc. 1394 1395The effect of the pragma is to allow the compiler to eliminate 1396the code or data associated with the named entity. Any reference to 1397an eliminated entity outside the compilation unit it is defined in, 1398causes a compile time or link time error. 1399 1400The parameters of this pragma may be given in any order, as long as 1401the usual rules for use of named parameters and position parameters 1402are used. 1403 1404The intention of pragma @code{Eliminate} is to allow a program to be compiled 1405in a system independent manner, with unused entities eliminated, without 1406the requirement of modifying the source text. Normally the required set 1407of @code{Eliminate} pragmas is constructed automatically using the gnatelim 1408tool. Elimination of unused entities local to a compilation unit is 1409automatic, without requiring the use of pragma @code{Eliminate}. 1410 1411Note that the reason this pragma takes string literals where names might 1412be expected is that a pragma @code{Eliminate} can appear in a context where the 1413relevant names are not visible. 1414 1415@node Pragma Export_Exception 1416@unnumberedsec Pragma Export_Exception 1417@cindex OpenVMS 1418@findex Export_Exception 1419@noindent 1420Syntax: 1421 1422@smallexample @c ada 1423pragma Export_Exception ( 1424 [Internal =>] LOCAL_NAME, 1425 [, [External =>] EXTERNAL_SYMBOL,] 1426 [, [Form =>] Ada | VMS] 1427 [, [Code =>] static_integer_EXPRESSION]); 1428 1429EXTERNAL_SYMBOL ::= 1430 IDENTIFIER 1431| static_string_EXPRESSION 1432@end smallexample 1433 1434@noindent 1435This pragma is implemented only in the OpenVMS implementation of GNAT@. It 1436causes the specified exception to be propagated outside of the Ada program, 1437so that it can be handled by programs written in other OpenVMS languages. 1438This pragma establishes an external name for an Ada exception and makes the 1439name available to the OpenVMS Linker as a global symbol. For further details 1440on this pragma, see the 1441DEC Ada Language Reference Manual, section 13.9a3.2. 1442 1443@node Pragma Export_Function 1444@unnumberedsec Pragma Export_Function 1445@cindex Argument passing mechanisms 1446@findex Export_Function 1447 1448@noindent 1449Syntax: 1450 1451@smallexample @c ada 1452pragma Export_Function ( 1453 [Internal =>] LOCAL_NAME, 1454 [, [External =>] EXTERNAL_SYMBOL] 1455 [, [Parameter_Types =>] PARAMETER_TYPES] 1456 [, [Result_Type =>] result_SUBTYPE_MARK] 1457 [, [Mechanism =>] MECHANISM] 1458 [, [Result_Mechanism =>] MECHANISM_NAME]); 1459 1460EXTERNAL_SYMBOL ::= 1461 IDENTIFIER 1462| static_string_EXPRESSION 1463| "" 1464 1465PARAMETER_TYPES ::= 1466 null 1467| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 1468 1469TYPE_DESIGNATOR ::= 1470 subtype_NAME 1471| subtype_Name ' Access 1472 1473MECHANISM ::= 1474 MECHANISM_NAME 1475| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 1476 1477MECHANISM_ASSOCIATION ::= 1478 [formal_parameter_NAME =>] MECHANISM_NAME 1479 1480MECHANISM_NAME ::= 1481 Value 1482| Reference 1483@end smallexample 1484 1485@noindent 1486Use this pragma to make a function externally callable and optionally 1487provide information on mechanisms to be used for passing parameter and 1488result values. We recommend, for the purposes of improving portability, 1489this pragma always be used in conjunction with a separate pragma 1490@code{Export}, which must precede the pragma @code{Export_Function}. 1491GNAT does not require a separate pragma @code{Export}, but if none is 1492present, @code{Convention Ada} is assumed, which is usually 1493not what is wanted, so it is usually appropriate to use this 1494pragma in conjunction with a @code{Export} or @code{Convention} 1495pragma that specifies the desired foreign convention. 1496Pragma @code{Export_Function} 1497(and @code{Export}, if present) must appear in the same declarative 1498region as the function to which they apply. 1499 1500@var{internal_name} must uniquely designate the function to which the 1501pragma applies. If more than one function name exists of this name in 1502the declarative part you must use the @code{Parameter_Types} and 1503@code{Result_Type} parameters is mandatory to achieve the required 1504unique designation. @var{subtype_ mark}s in these parameters must 1505exactly match the subtypes in the corresponding function specification, 1506using positional notation to match parameters with subtype marks. 1507The form with an @code{'Access} attribute can be used to match an 1508anonymous access parameter. 1509 1510@cindex OpenVMS 1511@cindex Passing by descriptor 1512Note that passing by descriptor is not supported, even on the OpenVMS 1513ports of GNAT@. 1514 1515@cindex Suppressing external name 1516Special treatment is given if the EXTERNAL is an explicit null 1517string or a static string expressions that evaluates to the null 1518string. In this case, no external name is generated. This form 1519still allows the specification of parameter mechanisms. 1520 1521@node Pragma Export_Object 1522@unnumberedsec Pragma Export_Object 1523@findex Export_Object 1524@noindent 1525Syntax: 1526 1527@smallexample @c ada 1528pragma Export_Object 1529 [Internal =>] LOCAL_NAME, 1530 [, [External =>] EXTERNAL_SYMBOL] 1531 [, [Size =>] EXTERNAL_SYMBOL] 1532 1533EXTERNAL_SYMBOL ::= 1534 IDENTIFIER 1535| static_string_EXPRESSION 1536@end smallexample 1537 1538@noindent 1539This pragma designates an object as exported, and apart from the 1540extended rules for external symbols, is identical in effect to the use of 1541the normal @code{Export} pragma applied to an object. You may use a 1542separate Export pragma (and you probably should from the point of view 1543of portability), but it is not required. @var{Size} is syntax checked, 1544but otherwise ignored by GNAT@. 1545 1546@node Pragma Export_Procedure 1547@unnumberedsec Pragma Export_Procedure 1548@findex Export_Procedure 1549@noindent 1550Syntax: 1551 1552@smallexample @c ada 1553pragma Export_Procedure ( 1554 [Internal =>] LOCAL_NAME 1555 [, [External =>] EXTERNAL_SYMBOL] 1556 [, [Parameter_Types =>] PARAMETER_TYPES] 1557 [, [Mechanism =>] MECHANISM]); 1558 1559EXTERNAL_SYMBOL ::= 1560 IDENTIFIER 1561| static_string_EXPRESSION 1562| "" 1563 1564PARAMETER_TYPES ::= 1565 null 1566| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 1567 1568TYPE_DESIGNATOR ::= 1569 subtype_NAME 1570| subtype_Name ' Access 1571 1572MECHANISM ::= 1573 MECHANISM_NAME 1574| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 1575 1576MECHANISM_ASSOCIATION ::= 1577 [formal_parameter_NAME =>] MECHANISM_NAME 1578 1579MECHANISM_NAME ::= 1580 Value 1581| Reference 1582@end smallexample 1583 1584@noindent 1585This pragma is identical to @code{Export_Function} except that it 1586applies to a procedure rather than a function and the parameters 1587@code{Result_Type} and @code{Result_Mechanism} are not permitted. 1588GNAT does not require a separate pragma @code{Export}, but if none is 1589present, @code{Convention Ada} is assumed, which is usually 1590not what is wanted, so it is usually appropriate to use this 1591pragma in conjunction with a @code{Export} or @code{Convention} 1592pragma that specifies the desired foreign convention. 1593 1594@cindex OpenVMS 1595@cindex Passing by descriptor 1596Note that passing by descriptor is not supported, even on the OpenVMS 1597ports of GNAT@. 1598 1599@cindex Suppressing external name 1600Special treatment is given if the EXTERNAL is an explicit null 1601string or a static string expressions that evaluates to the null 1602string. In this case, no external name is generated. This form 1603still allows the specification of parameter mechanisms. 1604 1605@node Pragma Export_Value 1606@unnumberedsec Pragma Export_Value 1607@findex Export_Value 1608@noindent 1609Syntax: 1610 1611@smallexample @c ada 1612pragma Export_Value ( 1613 [Value =>] static_integer_EXPRESSION, 1614 [Link_Name =>] static_string_EXPRESSION); 1615@end smallexample 1616 1617@noindent 1618This pragma serves to export a static integer value for external use. 1619The first argument specifies the value to be exported. The Link_Name 1620argument specifies the symbolic name to be associated with the integer 1621value. This pragma is useful for defining a named static value in Ada 1622that can be referenced in assembly language units to be linked with 1623the application. This pragma is currently supported only for the 1624AAMP target and is ignored for other targets. 1625 1626@node Pragma Export_Valued_Procedure 1627@unnumberedsec Pragma Export_Valued_Procedure 1628@findex Export_Valued_Procedure 1629@noindent 1630Syntax: 1631 1632@smallexample @c ada 1633pragma Export_Valued_Procedure ( 1634 [Internal =>] LOCAL_NAME 1635 [, [External =>] EXTERNAL_SYMBOL] 1636 [, [Parameter_Types =>] PARAMETER_TYPES] 1637 [, [Mechanism =>] MECHANISM]); 1638 1639EXTERNAL_SYMBOL ::= 1640 IDENTIFIER 1641| static_string_EXPRESSION 1642| "" 1643 1644PARAMETER_TYPES ::= 1645 null 1646| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 1647 1648TYPE_DESIGNATOR ::= 1649 subtype_NAME 1650| subtype_Name ' Access 1651 1652MECHANISM ::= 1653 MECHANISM_NAME 1654| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 1655 1656MECHANISM_ASSOCIATION ::= 1657 [formal_parameter_NAME =>] MECHANISM_NAME 1658 1659MECHANISM_NAME ::= 1660 Value 1661| Reference 1662@end smallexample 1663 1664@noindent 1665This pragma is identical to @code{Export_Procedure} except that the 1666first parameter of @var{local_name}, which must be present, must be of 1667mode @code{OUT}, and externally the subprogram is treated as a function 1668with this parameter as the result of the function. GNAT provides for 1669this capability to allow the use of @code{OUT} and @code{IN OUT} 1670parameters in interfacing to external functions (which are not permitted 1671in Ada functions). 1672GNAT does not require a separate pragma @code{Export}, but if none is 1673present, @code{Convention Ada} is assumed, which is almost certainly 1674not what is wanted since the whole point of this pragma is to interface 1675with foreign language functions, so it is usually appropriate to use this 1676pragma in conjunction with a @code{Export} or @code{Convention} 1677pragma that specifies the desired foreign convention. 1678 1679@cindex OpenVMS 1680@cindex Passing by descriptor 1681Note that passing by descriptor is not supported, even on the OpenVMS 1682ports of GNAT@. 1683 1684@cindex Suppressing external name 1685Special treatment is given if the EXTERNAL is an explicit null 1686string or a static string expressions that evaluates to the null 1687string. In this case, no external name is generated. This form 1688still allows the specification of parameter mechanisms. 1689 1690@node Pragma Extend_System 1691@unnumberedsec Pragma Extend_System 1692@cindex @code{system}, extending 1693@cindex Dec Ada 83 1694@findex Extend_System 1695@noindent 1696Syntax: 1697 1698@smallexample @c ada 1699pragma Extend_System ([Name =>] IDENTIFIER); 1700@end smallexample 1701 1702@noindent 1703This pragma is used to provide backwards compatibility with other 1704implementations that extend the facilities of package @code{System}. In 1705GNAT, @code{System} contains only the definitions that are present in 1706the Ada 95 RM@. However, other implementations, notably the DEC Ada 83 1707implementation, provide many extensions to package @code{System}. 1708 1709For each such implementation accommodated by this pragma, GNAT provides a 1710package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83 1711implementation, which provides the required additional definitions. You 1712can use this package in two ways. You can @code{with} it in the normal 1713way and access entities either by selection or using a @code{use} 1714clause. In this case no special processing is required. 1715 1716However, if existing code contains references such as 1717@code{System.@var{xxx}} where @var{xxx} is an entity in the extended 1718definitions provided in package @code{System}, you may use this pragma 1719to extend visibility in @code{System} in a non-standard way that 1720provides greater compatibility with the existing code. Pragma 1721@code{Extend_System} is a configuration pragma whose single argument is 1722the name of the package containing the extended definition 1723(e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under 1724control of this pragma will be processed using special visibility 1725processing that looks in package @code{System.Aux_@var{xxx}} where 1726@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in 1727package @code{System}, but not found in package @code{System}. 1728 1729You can use this pragma either to access a predefined @code{System} 1730extension supplied with the compiler, for example @code{Aux_DEC} or 1731you can construct your own extension unit following the above 1732definition. Note that such a package is a child of @code{System} 1733and thus is considered part of the implementation. To compile 1734it you will have to use the appropriate switch for compiling 1735system units. See the GNAT User's Guide for details. 1736 1737@node Pragma External 1738@unnumberedsec Pragma External 1739@findex External 1740@noindent 1741Syntax: 1742 1743@smallexample @c ada 1744pragma External ( 1745 [ Convention =>] convention_IDENTIFIER, 1746 [ Entity =>] local_NAME 1747 [, [External_Name =>] static_string_EXPRESSION ] 1748 [, [Link_Name =>] static_string_EXPRESSION ]); 1749@end smallexample 1750 1751@noindent 1752This pragma is identical in syntax and semantics to pragma 1753@code{Export} as defined in the Ada Reference Manual. It is 1754provided for compatibility with some Ada 83 compilers that 1755used this pragma for exactly the same purposes as pragma 1756@code{Export} before the latter was standardized. 1757 1758@node Pragma External_Name_Casing 1759@unnumberedsec Pragma External_Name_Casing 1760@cindex Dec Ada 83 casing compatibility 1761@cindex External Names, casing 1762@cindex Casing of External names 1763@findex External_Name_Casing 1764@noindent 1765Syntax: 1766 1767@smallexample @c ada 1768pragma External_Name_Casing ( 1769 Uppercase | Lowercase 1770 [, Uppercase | Lowercase | As_Is]); 1771@end smallexample 1772 1773@noindent 1774This pragma provides control over the casing of external names associated 1775with Import and Export pragmas. There are two cases to consider: 1776 1777@table @asis 1778@item Implicit external names 1779Implicit external names are derived from identifiers. The most common case 1780arises when a standard Ada 95 Import or Export pragma is used with only two 1781arguments, as in: 1782 1783@smallexample @c ada 1784 pragma Import (C, C_Routine); 1785@end smallexample 1786 1787@noindent 1788Since Ada is a case insensitive language, the spelling of the identifier in 1789the Ada source program does not provide any information on the desired 1790casing of the external name, and so a convention is needed. In GNAT the 1791default treatment is that such names are converted to all lower case 1792letters. This corresponds to the normal C style in many environments. 1793The first argument of pragma @code{External_Name_Casing} can be used to 1794control this treatment. If @code{Uppercase} is specified, then the name 1795will be forced to all uppercase letters. If @code{Lowercase} is specified, 1796then the normal default of all lower case letters will be used. 1797 1798This same implicit treatment is also used in the case of extended DEC Ada 83 1799compatible Import and Export pragmas where an external name is explicitly 1800specified using an identifier rather than a string. 1801 1802@item Explicit external names 1803Explicit external names are given as string literals. The most common case 1804arises when a standard Ada 95 Import or Export pragma is used with three 1805arguments, as in: 1806 1807@smallexample @c ada 1808pragma Import (C, C_Routine, "C_routine"); 1809@end smallexample 1810 1811@noindent 1812In this case, the string literal normally provides the exact casing required 1813for the external name. The second argument of pragma 1814@code{External_Name_Casing} may be used to modify this behavior. 1815If @code{Uppercase} is specified, then the name 1816will be forced to all uppercase letters. If @code{Lowercase} is specified, 1817then the name will be forced to all lowercase letters. A specification of 1818@code{As_Is} provides the normal default behavior in which the casing is 1819taken from the string provided. 1820@end table 1821 1822@noindent 1823This pragma may appear anywhere that a pragma is valid. In particular, it 1824can be used as a configuration pragma in the @file{gnat.adc} file, in which 1825case it applies to all subsequent compilations, or it can be used as a program 1826unit pragma, in which case it only applies to the current unit, or it can 1827be used more locally to control individual Import/Export pragmas. 1828 1829It is primarily intended for use with OpenVMS systems, where many 1830compilers convert all symbols to upper case by default. For interfacing to 1831such compilers (e.g.@: the DEC C compiler), it may be convenient to use 1832the pragma: 1833 1834@smallexample @c ada 1835pragma External_Name_Casing (Uppercase, Uppercase); 1836@end smallexample 1837 1838@noindent 1839to enforce the upper casing of all external symbols. 1840 1841@node Pragma Finalize_Storage_Only 1842@unnumberedsec Pragma Finalize_Storage_Only 1843@findex Finalize_Storage_Only 1844@noindent 1845Syntax: 1846 1847@smallexample @c ada 1848pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); 1849@end smallexample 1850 1851@noindent 1852This pragma allows the compiler not to emit a Finalize call for objects 1853defined at the library level. This is mostly useful for types where 1854finalization is only used to deal with storage reclamation since in most 1855environments it is not necessary to reclaim memory just before terminating 1856execution, hence the name. 1857 1858@node Pragma Float_Representation 1859@unnumberedsec Pragma Float_Representation 1860@cindex OpenVMS 1861@findex Float_Representation 1862@noindent 1863Syntax: 1864 1865@smallexample @c ada 1866pragma Float_Representation (FLOAT_REP); 1867 1868FLOAT_REP ::= VAX_Float | IEEE_Float 1869@end smallexample 1870 1871@noindent 1872This pragma 1873allows control over the internal representation chosen for the predefined 1874floating point types declared in the packages @code{Standard} and 1875@code{System}. On all systems other than OpenVMS, the argument must 1876be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the 1877argument may be @code{VAX_Float} to specify the use of the VAX float 1878format for the floating-point types in Standard. This requires that 1879the standard runtime libraries be recompiled. See the 1880description of the @code{GNAT LIBRARY} command in the OpenVMS version 1881of the GNAT Users Guide for details on the use of this command. 1882 1883@node Pragma Ident 1884@unnumberedsec Pragma Ident 1885@findex Ident 1886@noindent 1887Syntax: 1888 1889@smallexample @c ada 1890pragma Ident (static_string_EXPRESSION); 1891@end smallexample 1892 1893@noindent 1894This pragma provides a string identification in the generated object file, 1895if the system supports the concept of this kind of identification string. 1896This pragma is allowed only in the outermost declarative part or 1897declarative items of a compilation unit. If more than one @code{Ident} 1898pragma is given, only the last one processed is effective. 1899@cindex OpenVMS 1900On OpenVMS systems, the effect of the pragma is identical to the effect of 1901the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the 1902maximum allowed length is 31 characters, so if it is important to 1903maintain compatibility with this compiler, you should obey this length 1904limit. 1905 1906@node Pragma Import_Exception 1907@unnumberedsec Pragma Import_Exception 1908@cindex OpenVMS 1909@findex Import_Exception 1910@noindent 1911Syntax: 1912 1913@smallexample @c ada 1914pragma Import_Exception ( 1915 [Internal =>] LOCAL_NAME, 1916 [, [External =>] EXTERNAL_SYMBOL,] 1917 [, [Form =>] Ada | VMS] 1918 [, [Code =>] static_integer_EXPRESSION]); 1919 1920EXTERNAL_SYMBOL ::= 1921 IDENTIFIER 1922| static_string_EXPRESSION 1923@end smallexample 1924 1925@noindent 1926This pragma is implemented only in the OpenVMS implementation of GNAT@. 1927It allows OpenVMS conditions (for example, from OpenVMS system services or 1928other OpenVMS languages) to be propagated to Ada programs as Ada exceptions. 1929The pragma specifies that the exception associated with an exception 1930declaration in an Ada program be defined externally (in non-Ada code). 1931For further details on this pragma, see the 1932DEC Ada Language Reference Manual, section 13.9a.3.1. 1933 1934@node Pragma Import_Function 1935@unnumberedsec Pragma Import_Function 1936@findex Import_Function 1937@noindent 1938Syntax: 1939 1940@smallexample @c ada 1941pragma Import_Function ( 1942 [Internal =>] LOCAL_NAME, 1943 [, [External =>] EXTERNAL_SYMBOL] 1944 [, [Parameter_Types =>] PARAMETER_TYPES] 1945 [, [Result_Type =>] SUBTYPE_MARK] 1946 [, [Mechanism =>] MECHANISM] 1947 [, [Result_Mechanism =>] MECHANISM_NAME] 1948 [, [First_Optional_Parameter =>] IDENTIFIER]); 1949 1950EXTERNAL_SYMBOL ::= 1951 IDENTIFIER 1952| static_string_EXPRESSION 1953 1954PARAMETER_TYPES ::= 1955 null 1956| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 1957 1958TYPE_DESIGNATOR ::= 1959 subtype_NAME 1960| subtype_Name ' Access 1961 1962MECHANISM ::= 1963 MECHANISM_NAME 1964| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 1965 1966MECHANISM_ASSOCIATION ::= 1967 [formal_parameter_NAME =>] MECHANISM_NAME 1968 1969MECHANISM_NAME ::= 1970 Value 1971| Reference 1972| Descriptor [([Class =>] CLASS_NAME)] 1973 1974CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 1975@end smallexample 1976 1977@noindent 1978This pragma is used in conjunction with a pragma @code{Import} to 1979specify additional information for an imported function. The pragma 1980@code{Import} (or equivalent pragma @code{Interface}) must precede the 1981@code{Import_Function} pragma and both must appear in the same 1982declarative part as the function specification. 1983 1984The @var{Internal} argument must uniquely designate 1985the function to which the 1986pragma applies. If more than one function name exists of this name in 1987the declarative part you must use the @code{Parameter_Types} and 1988@var{Result_Type} parameters to achieve the required unique 1989designation. Subtype marks in these parameters must exactly match the 1990subtypes in the corresponding function specification, using positional 1991notation to match parameters with subtype marks. 1992The form with an @code{'Access} attribute can be used to match an 1993anonymous access parameter. 1994 1995You may optionally use the @var{Mechanism} and @var{Result_Mechanism} 1996parameters to specify passing mechanisms for the 1997parameters and result. If you specify a single mechanism name, it 1998applies to all parameters. Otherwise you may specify a mechanism on a 1999parameter by parameter basis using either positional or named 2000notation. If the mechanism is not specified, the default mechanism 2001is used. 2002 2003@cindex OpenVMS 2004@cindex Passing by descriptor 2005Passing by descriptor is supported only on the OpenVMS ports of GNAT@. 2006 2007@code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@. 2008It specifies that the designated parameter and all following parameters 2009are optional, meaning that they are not passed at the generated code 2010level (this is distinct from the notion of optional parameters in Ada 2011where the parameters are passed anyway with the designated optional 2012parameters). All optional parameters must be of mode @code{IN} and have 2013default parameter values that are either known at compile time 2014expressions, or uses of the @code{'Null_Parameter} attribute. 2015 2016@node Pragma Import_Object 2017@unnumberedsec Pragma Import_Object 2018@findex Import_Object 2019@noindent 2020Syntax: 2021 2022@smallexample @c ada 2023pragma Import_Object 2024 [Internal =>] LOCAL_NAME, 2025 [, [External =>] EXTERNAL_SYMBOL], 2026 [, [Size =>] EXTERNAL_SYMBOL]); 2027 2028EXTERNAL_SYMBOL ::= 2029 IDENTIFIER 2030| static_string_EXPRESSION 2031@end smallexample 2032 2033@noindent 2034This pragma designates an object as imported, and apart from the 2035extended rules for external symbols, is identical in effect to the use of 2036the normal @code{Import} pragma applied to an object. Unlike the 2037subprogram case, you need not use a separate @code{Import} pragma, 2038although you may do so (and probably should do so from a portability 2039point of view). @var{size} is syntax checked, but otherwise ignored by 2040GNAT@. 2041 2042@node Pragma Import_Procedure 2043@unnumberedsec Pragma Import_Procedure 2044@findex Import_Procedure 2045@noindent 2046Syntax: 2047 2048@smallexample @c ada 2049pragma Import_Procedure ( 2050 [Internal =>] LOCAL_NAME, 2051 [, [External =>] EXTERNAL_SYMBOL] 2052 [, [Parameter_Types =>] PARAMETER_TYPES] 2053 [, [Mechanism =>] MECHANISM] 2054 [, [First_Optional_Parameter =>] IDENTIFIER]); 2055 2056EXTERNAL_SYMBOL ::= 2057 IDENTIFIER 2058| static_string_EXPRESSION 2059 2060PARAMETER_TYPES ::= 2061 null 2062| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 2063 2064TYPE_DESIGNATOR ::= 2065 subtype_NAME 2066| subtype_Name ' Access 2067 2068MECHANISM ::= 2069 MECHANISM_NAME 2070| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 2071 2072MECHANISM_ASSOCIATION ::= 2073 [formal_parameter_NAME =>] MECHANISM_NAME 2074 2075MECHANISM_NAME ::= 2076 Value 2077| Reference 2078| Descriptor [([Class =>] CLASS_NAME)] 2079 2080CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 2081@end smallexample 2082 2083@noindent 2084This pragma is identical to @code{Import_Function} except that it 2085applies to a procedure rather than a function and the parameters 2086@code{Result_Type} and @code{Result_Mechanism} are not permitted. 2087 2088@node Pragma Import_Valued_Procedure 2089@unnumberedsec Pragma Import_Valued_Procedure 2090@findex Import_Valued_Procedure 2091@noindent 2092Syntax: 2093 2094@smallexample @c ada 2095pragma Import_Valued_Procedure ( 2096 [Internal =>] LOCAL_NAME, 2097 [, [External =>] EXTERNAL_SYMBOL] 2098 [, [Parameter_Types =>] PARAMETER_TYPES] 2099 [, [Mechanism =>] MECHANISM] 2100 [, [First_Optional_Parameter =>] IDENTIFIER]); 2101 2102EXTERNAL_SYMBOL ::= 2103 IDENTIFIER 2104| static_string_EXPRESSION 2105 2106PARAMETER_TYPES ::= 2107 null 2108| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} 2109 2110TYPE_DESIGNATOR ::= 2111 subtype_NAME 2112| subtype_Name ' Access 2113 2114MECHANISM ::= 2115 MECHANISM_NAME 2116| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) 2117 2118MECHANISM_ASSOCIATION ::= 2119 [formal_parameter_NAME =>] MECHANISM_NAME 2120 2121MECHANISM_NAME ::= 2122 Value 2123| Reference 2124| Descriptor [([Class =>] CLASS_NAME)] 2125 2126CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca 2127@end smallexample 2128 2129@noindent 2130This pragma is identical to @code{Import_Procedure} except that the 2131first parameter of @var{local_name}, which must be present, must be of 2132mode @code{OUT}, and externally the subprogram is treated as a function 2133with this parameter as the result of the function. The purpose of this 2134capability is to allow the use of @code{OUT} and @code{IN OUT} 2135parameters in interfacing to external functions (which are not permitted 2136in Ada functions). You may optionally use the @code{Mechanism} 2137parameters to specify passing mechanisms for the parameters. 2138If you specify a single mechanism name, it applies to all parameters. 2139Otherwise you may specify a mechanism on a parameter by parameter 2140basis using either positional or named notation. If the mechanism is not 2141specified, the default mechanism is used. 2142 2143Note that it is important to use this pragma in conjunction with a separate 2144pragma Import that specifies the desired convention, since otherwise the 2145default convention is Ada, which is almost certainly not what is required. 2146 2147@node Pragma Initialize_Scalars 2148@unnumberedsec Pragma Initialize_Scalars 2149@findex Initialize_Scalars 2150@cindex debugging with Initialize_Scalars 2151@noindent 2152Syntax: 2153 2154@smallexample @c ada 2155pragma Initialize_Scalars; 2156@end smallexample 2157 2158@noindent 2159This pragma is similar to @code{Normalize_Scalars} conceptually but has 2160two important differences. First, there is no requirement for the pragma 2161to be used uniformly in all units of a partition, in particular, it is fine 2162to use this just for some or all of the application units of a partition, 2163without needing to recompile the run-time library. 2164 2165In the case where some units are compiled with the pragma, and some without, 2166then a declaration of a variable where the type is defined in package 2167Standard or is locally declared will always be subject to initialization, 2168as will any declaration of a scalar variable. For composite variables, 2169whether the variable is initialized may also depend on whether the package 2170in which the type of the variable is declared is compiled with the pragma. 2171 2172The other important difference is that there is control over the value used 2173for initializing scalar objects. At bind time, you can select whether to 2174initialize with invalid values (like Normalize_Scalars), or with high or 2175low values, or with a specified bit pattern. See the users guide for binder 2176options for specifying these cases. 2177 2178This means that you can compile a program, and then without having to 2179recompile the program, you can run it with different values being used 2180for initializing otherwise uninitialized values, to test if your program 2181behavior depends on the choice. Of course the behavior should not change, 2182and if it does, then most likely you have an erroneous reference to an 2183uninitialized value. 2184 2185Note that pragma @code{Initialize_Scalars} is particularly useful in 2186conjunction with the enhanced validity checking that is now provided 2187in GNAT, which checks for invalid values under more conditions. 2188Using this feature (see description of the @code{-gnatV} flag in the 2189users guide) in conjunction with pragma @code{Initialize_Scalars} 2190provides a powerful new tool to assist in the detection of problems 2191caused by uninitialized variables. 2192 2193@node Pragma Inline_Always 2194@unnumberedsec Pragma Inline_Always 2195@findex Inline_Always 2196@noindent 2197Syntax: 2198 2199@smallexample @c ada 2200pragma Inline_Always (NAME [, NAME]); 2201@end smallexample 2202 2203@noindent 2204Similar to pragma @code{Inline} except that inlining is not subject to 2205the use of option @code{-gnatn} and the inlining happens regardless of 2206whether this option is used. 2207 2208@node Pragma Inline_Generic 2209@unnumberedsec Pragma Inline_Generic 2210@findex Inline_Generic 2211@noindent 2212Syntax: 2213 2214@smallexample @c ada 2215pragma Inline_Generic (generic_package_NAME); 2216@end smallexample 2217 2218@noindent 2219This is implemented for compatibility with DEC Ada 83 and is recognized, 2220but otherwise ignored, by GNAT@. All generic instantiations are inlined 2221by default when using GNAT@. 2222 2223@node Pragma Interface 2224@unnumberedsec Pragma Interface 2225@findex Interface 2226@noindent 2227Syntax: 2228 2229@smallexample @c ada 2230pragma Interface ( 2231 [Convention =>] convention_identifier, 2232 [Entity =>] local_name 2233 [, [External_Name =>] static_string_expression], 2234 [, [Link_Name =>] static_string_expression]); 2235@end smallexample 2236 2237@noindent 2238This pragma is identical in syntax and semantics to 2239the standard Ada 95 pragma @code{Import}. It is provided for compatibility 2240with Ada 83. The definition is upwards compatible both with pragma 2241@code{Interface} as defined in the Ada 83 Reference Manual, and also 2242with some extended implementations of this pragma in certain Ada 83 2243implementations. 2244 2245@node Pragma Interface_Name 2246@unnumberedsec Pragma Interface_Name 2247@findex Interface_Name 2248@noindent 2249Syntax: 2250 2251@smallexample @c ada 2252pragma Interface_Name ( 2253 [Entity =>] LOCAL_NAME 2254 [, [External_Name =>] static_string_EXPRESSION] 2255 [, [Link_Name =>] static_string_EXPRESSION]); 2256@end smallexample 2257 2258@noindent 2259This pragma provides an alternative way of specifying the interface name 2260for an interfaced subprogram, and is provided for compatibility with Ada 226183 compilers that use the pragma for this purpose. You must provide at 2262least one of @var{External_Name} or @var{Link_Name}. 2263 2264@node Pragma Interrupt_Handler 2265@unnumberedsec Pragma Interrupt_Handler 2266@findex Interrupt_Handler 2267@noindent 2268Syntax: 2269 2270@smallexample @c ada 2271pragma Interrupt_Handler (procedure_LOCAL_NAME); 2272@end smallexample 2273 2274@noindent 2275This program unit pragma is supported for parameterless protected procedures 2276as described in Annex C of the Ada Reference Manual. On the AAMP target 2277the pragma can also be specified for nonprotected parameterless procedures 2278that are declared at the library level (which includes procedures 2279declared at the top level of a library package). In the case of AAMP, 2280when this pragma is applied to a nonprotected procedure, the instruction 2281@code{IERET} is generated for returns from the procedure, enabling 2282maskable interrupts, in place of the normal return instruction. 2283 2284@node Pragma Interrupt_State 2285@unnumberedsec Pragma Interrupt_State 2286@findex Interrupt_State 2287@noindent 2288Syntax: 2289 2290@smallexample @c ada 2291pragma Interrupt_State (Name => value, State => SYSTEM | RUNTIME | USER); 2292@end smallexample 2293 2294@noindent 2295Normally certain interrupts are reserved to the implementation. Any attempt 2296to attach an interrupt causes Program_Error to be raised, as described in 2297RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 2298many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is 2299reserved to the implementation, so that @kbd{Ctrl-C} can be used to 2300interrupt execution. Additionally, signals such as @code{SIGSEGV}, 2301@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific 2302Ada exceptions, or used to implement run-time functions such as the 2303@code{abort} statement and stack overflow checking. 2304 2305Pragma @code{Interrupt_State} provides a general mechanism for overriding 2306such uses of interrupts. It subsumes the functionality of pragma 2307@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not 2308available on OS/2, Windows or VMS. On all other platforms than VxWorks, 2309it applies to signals; on VxWorks, it applies to vectored hardware interrupts 2310and may be used to mark interrupts required by the board support package 2311as reserved. 2312 2313Interrupts can be in one of three states: 2314@itemize @bullet 2315@item System 2316 2317The interrupt is reserved (no Ada handler can be installed), and the 2318Ada run-time may not install a handler. As a result you are guaranteed 2319standard system default action if this interrupt is raised. 2320 2321@item Runtime 2322 2323The interrupt is reserved (no Ada handler can be installed). The run time 2324is allowed to install a handler for internal control purposes, but is 2325not required to do so. 2326 2327@item User 2328 2329The interrupt is unreserved. The user may install a handler to provide 2330some other action. 2331@end itemize 2332 2333@noindent 2334These states are the allowed values of the @code{State} parameter of the 2335pragma. The @code{Name} parameter is a value of the type 2336@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in 2337@code{Ada.Interrupts.Names}. 2338 2339This is a configuration pragma, and the binder will check that there 2340are no inconsistencies between different units in a partition in how a 2341given interrupt is specified. It may appear anywhere a pragma is legal. 2342 2343The effect is to move the interrupt to the specified state. 2344 2345By declaring interrupts to be SYSTEM, you guarantee the standard system 2346action, such as a core dump. 2347 2348By declaring interrupts to be USER, you guarantee that you can install 2349a handler. 2350 2351Note that certain signals on many operating systems cannot be caught and 2352handled by applications. In such cases, the pragma is ignored. See the 2353operating system documentation, or the value of the array @code{Reserved} 2354declared in the specification of package @code{System.OS_Interface}. 2355 2356Overriding the default state of signals used by the Ada runtime may interfere 2357with an application's runtime behavior in the cases of the synchronous signals, 2358and in the case of the signal used to implement the @code{abort} statement. 2359 2360@node Pragma Keep_Names 2361@unnumberedsec Pragma Keep_Names 2362@findex Keep_Names 2363@noindent 2364Syntax: 2365 2366@smallexample @c ada 2367pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); 2368@end smallexample 2369 2370@noindent 2371The @var{LOCAL_NAME} argument 2372must refer to an enumeration first subtype 2373in the current declarative part. The effect is to retain the enumeration 2374literal names for use by @code{Image} and @code{Value} even if a global 2375@code{Discard_Names} pragma applies. This is useful when you want to 2376generally suppress enumeration literal names and for example you therefore 2377use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you 2378want to retain the names for specific enumeration types. 2379 2380@node Pragma License 2381@unnumberedsec Pragma License 2382@findex License 2383@cindex License checking 2384@noindent 2385Syntax: 2386 2387@smallexample @c ada 2388pragma License (Unrestricted | GPL | Modified_GPL | Restricted); 2389@end smallexample 2390 2391@noindent 2392This pragma is provided to allow automated checking for appropriate license 2393conditions with respect to the standard and modified GPL@. A pragma 2394@code{License}, which is a configuration pragma that typically appears at 2395the start of a source file or in a separate @file{gnat.adc} file, specifies 2396the licensing conditions of a unit as follows: 2397 2398@itemize @bullet 2399@item Unrestricted 2400This is used for a unit that can be freely used with no license restrictions. 2401Examples of such units are public domain units, and units from the Ada 2402Reference Manual. 2403 2404@item GPL 2405This is used for a unit that is licensed under the unmodified GPL, and which 2406therefore cannot be @code{with}'ed by a restricted unit. 2407 2408@item Modified_GPL 2409This is used for a unit licensed under the GNAT modified GPL that includes 2410a special exception paragraph that specifically permits the inclusion of 2411the unit in programs without requiring the entire program to be released 2412under the GPL@. This is the license used for the GNAT run-time which ensures 2413that the run-time can be used freely in any program without GPL concerns. 2414 2415@item Restricted 2416This is used for a unit that is restricted in that it is not permitted to 2417depend on units that are licensed under the GPL@. Typical examples are 2418proprietary code that is to be released under more restrictive license 2419conditions. Note that restricted units are permitted to @code{with} units 2420which are licensed under the modified GPL (this is the whole point of the 2421modified GPL). 2422 2423@end itemize 2424 2425@noindent 2426Normally a unit with no @code{License} pragma is considered to have an 2427unknown license, and no checking is done. However, standard GNAT headers 2428are recognized, and license information is derived from them as follows. 2429 2430@itemize @bullet 2431 2432A GNAT license header starts with a line containing 78 hyphens. The following 2433comment text is searched for the appearance of any of the following strings. 2434 2435If the string ``GNU General Public License'' is found, then the unit is assumed 2436to have GPL license, unless the string ``As a special exception'' follows, in 2437which case the license is assumed to be modified GPL@. 2438 2439If one of the strings 2440``This specification is adapted from the Ada Semantic Interface'' or 2441``This specification is derived from the Ada Reference Manual'' is found 2442then the unit is assumed to be unrestricted. 2443@end itemize 2444 2445@noindent 2446These default actions means that a program with a restricted license pragma 2447will automatically get warnings if a GPL unit is inappropriately 2448@code{with}'ed. For example, the program: 2449 2450@smallexample @c ada 2451with Sem_Ch3; 2452with GNAT.Sockets; 2453procedure Secret_Stuff is 2454 @dots{} 2455end Secret_Stuff 2456@end smallexample 2457 2458@noindent 2459if compiled with pragma @code{License} (@code{Restricted}) in a 2460@file{gnat.adc} file will generate the warning: 2461 2462@smallexample 24631. with Sem_Ch3; 2464 | 2465 >>> license of withed unit "Sem_Ch3" is incompatible 2466 24672. with GNAT.Sockets; 24683. procedure Secret_Stuff is 2469@end smallexample 2470 2471@noindent 2472Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT 2473compiler and is licensed under the 2474GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT 2475run time, and is therefore licensed under the modified GPL@. 2476 2477@node Pragma Link_With 2478@unnumberedsec Pragma Link_With 2479@findex Link_With 2480@noindent 2481Syntax: 2482 2483@smallexample @c ada 2484pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); 2485@end smallexample 2486 2487@noindent 2488This pragma is provided for compatibility with certain Ada 83 compilers. 2489It has exactly the same effect as pragma @code{Linker_Options} except 2490that spaces occurring within one of the string expressions are treated 2491as separators. For example, in the following case: 2492 2493@smallexample @c ada 2494pragma Link_With ("-labc -ldef"); 2495@end smallexample 2496 2497@noindent 2498results in passing the strings @code{-labc} and @code{-ldef} as two 2499separate arguments to the linker. In addition pragma Link_With allows 2500multiple arguments, with the same effect as successive pragmas. 2501 2502@node Pragma Linker_Alias 2503@unnumberedsec Pragma Linker_Alias 2504@findex Linker_Alias 2505@noindent 2506Syntax: 2507 2508@smallexample @c ada 2509pragma Linker_Alias ( 2510 [Entity =>] LOCAL_NAME 2511 [Alias =>] static_string_EXPRESSION); 2512@end smallexample 2513 2514@noindent 2515This pragma establishes a linker alias for the given named entity. For 2516further details on the exact effect, consult the GCC manual. 2517 2518@node Pragma Linker_Section 2519@unnumberedsec Pragma Linker_Section 2520@findex Linker_Section 2521@noindent 2522Syntax: 2523 2524@smallexample @c ada 2525pragma Linker_Section ( 2526 [Entity =>] LOCAL_NAME 2527 [Section =>] static_string_EXPRESSION); 2528@end smallexample 2529 2530@noindent 2531This pragma specifies the name of the linker section for the given entity. 2532For further details on the exact effect, consult the GCC manual. 2533 2534@node Pragma Long_Float 2535@unnumberedsec Pragma Long_Float 2536@cindex OpenVMS 2537@findex Long_Float 2538@noindent 2539Syntax: 2540 2541@smallexample @c ada 2542pragma Long_Float (FLOAT_FORMAT); 2543 2544FLOAT_FORMAT ::= D_Float | G_Float 2545@end smallexample 2546 2547@noindent 2548This pragma is implemented only in the OpenVMS implementation of GNAT@. 2549It allows control over the internal representation chosen for the predefined 2550type @code{Long_Float} and for floating point type representations with 2551@code{digits} specified in the range 7 through 15. 2552For further details on this pragma, see the 2553@cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use 2554this pragma, the standard runtime libraries must be recompiled. See the 2555description of the @code{GNAT LIBRARY} command in the OpenVMS version 2556of the GNAT User's Guide for details on the use of this command. 2557 2558@node Pragma Machine_Attribute 2559@unnumberedsec Pragma Machine_Attribute 2560@findex Machine_Attribute 2561@noindent 2562Syntax: 2563 2564@smallexample @c ada 2565pragma Machine_Attribute ( 2566 [Attribute_Name =>] string_EXPRESSION, 2567 [Entity =>] LOCAL_NAME); 2568@end smallexample 2569 2570@noindent 2571Machine dependent attributes can be specified for types and/or 2572declarations. Currently only subprogram entities are supported. This 2573pragma is semantically equivalent to 2574@code{__attribute__((@var{string_expression}))} in GNU C, 2575where @code{@var{string_expression}} is 2576recognized by the GNU C macros @code{VALID_MACHINE_TYPE_ATTRIBUTE} and 2577@code{VALID_MACHINE_DECL_ATTRIBUTE} which are defined in the 2578configuration header file @file{tm.h} for each machine. See the GCC 2579manual for further information. 2580 2581@node Pragma Main_Storage 2582@unnumberedsec Pragma Main_Storage 2583@cindex OpenVMS 2584@findex Main_Storage 2585@noindent 2586Syntax: 2587 2588@smallexample @c ada 2589pragma Main_Storage 2590 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); 2591 2592MAIN_STORAGE_OPTION ::= 2593 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION 2594| [TOP_GUARD =>] static_SIMPLE_EXPRESSION 2595 2596@end smallexample 2597 2598@noindent 2599This pragma is provided for compatibility with OpenVMS VAX Systems. It has 2600no effect in GNAT, other than being syntax checked. Note that the pragma 2601also has no effect in DEC Ada 83 for OpenVMS Alpha Systems. 2602 2603@node Pragma No_Return 2604@unnumberedsec Pragma No_Return 2605@findex No_Return 2606@noindent 2607Syntax: 2608 2609@smallexample @c ada 2610pragma No_Return (procedure_LOCAL_NAME); 2611@end smallexample 2612 2613@noindent 2614@var{procedure_local_NAME} must refer to one or more procedure 2615declarations in the current declarative part. A procedure to which this 2616pragma is applied may not contain any explicit @code{return} statements, 2617and also may not contain any implicit return statements from falling off 2618the end of a statement sequence. One use of this pragma is to identify 2619procedures whose only purpose is to raise an exception. 2620 2621Another use of this pragma is to suppress incorrect warnings about 2622missing returns in functions, where the last statement of a function 2623statement sequence is a call to such a procedure. 2624 2625@node Pragma Normalize_Scalars 2626@unnumberedsec Pragma Normalize_Scalars 2627@findex Normalize_Scalars 2628@noindent 2629Syntax: 2630 2631@smallexample @c ada 2632pragma Normalize_Scalars; 2633@end smallexample 2634 2635@noindent 2636This is a language defined pragma which is fully implemented in GNAT@. The 2637effect is to cause all scalar objects that are not otherwise initialized 2638to be initialized. The initial values are implementation dependent and 2639are as follows: 2640 2641@table @code 2642@item Standard.Character 2643@noindent 2644Objects whose root type is Standard.Character are initialized to 2645Character'Last. This will be out of range of the subtype only if 2646the subtype range excludes this value. 2647 2648@item Standard.Wide_Character 2649@noindent 2650Objects whose root type is Standard.Wide_Character are initialized to 2651Wide_Character'Last. This will be out of range of the subtype only if 2652the subtype range excludes this value. 2653 2654@item Integer types 2655@noindent 2656Objects of an integer type are initialized to base_type'First, where 2657base_type is the base type of the object type. This will be out of range 2658of the subtype only if the subtype range excludes this value. For example, 2659if you declare the subtype: 2660 2661@smallexample @c ada 2662subtype Ityp is integer range 1 .. 10; 2663@end smallexample 2664 2665@noindent 2666then objects of type x will be initialized to Integer'First, a negative 2667number that is certainly outside the range of subtype @code{Ityp}. 2668 2669@item Real types 2670Objects of all real types (fixed and floating) are initialized to 2671base_type'First, where base_Type is the base type of the object type. 2672This will be out of range of the subtype only if the subtype range 2673excludes this value. 2674 2675@item Modular types 2676Objects of a modular type are initialized to typ'Last. This will be out 2677of range of the subtype only if the subtype excludes this value. 2678 2679@item Enumeration types 2680Objects of an enumeration type are initialized to all one-bits, i.e.@: to 2681the value @code{2 ** typ'Size - 1}. This will be out of range of the 2682enumeration subtype in all cases except where the subtype contains 2683exactly 2**8, 2**16, or 2**32 elements. 2684 2685@end table 2686 2687@node Pragma Obsolescent 2688@unnumberedsec Pragma Obsolescent 2689@findex Obsolescent 2690@noindent 2691Syntax: 2692 2693@smallexample @c ada 2694pragma Obsolescent [(static_string_EXPRESSION)]; 2695@end smallexample 2696 2697@noindent 2698This pragma must occur immediately following a subprogram 2699declaration. It indicates that the associated function or procedure 2700is considered obsolescent and should not be used. Typically this is 2701used when an API must be modified by eventually removing or modifying 2702existing subprograms. The pragma can be used at an intermediate stage 2703when the subprogram is still present, but will be removed later. 2704 2705The effect of this pragma is to output a warning message that the 2706subprogram is obsolescent if the appropriate warning option in the 2707compiler is activated. If a parameter is present, then a second 2708warning message is given containing this text. 2709 2710@node Pragma Passive 2711@unnumberedsec Pragma Passive 2712@findex Passive 2713@noindent 2714Syntax: 2715 2716@smallexample @c ada 2717pragma Passive ([Semaphore | No]); 2718@end smallexample 2719 2720@noindent 2721Syntax checked, but otherwise ignored by GNAT@. This is recognized for 2722compatibility with DEC Ada 83 implementations, where it is used within a 2723task definition to request that a task be made passive. If the argument 2724@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 2725treats the pragma as an assertion that the containing task is passive 2726and that optimization of context switch with this task is permitted and 2727desired. If the argument @code{No} is present, the task must not be 2728optimized. GNAT does not attempt to optimize any tasks in this manner 2729(since protected objects are available in place of passive tasks). 2730 2731@node Pragma Polling 2732@unnumberedsec Pragma Polling 2733@findex Polling 2734@noindent 2735Syntax: 2736 2737@smallexample @c ada 2738pragma Polling (ON | OFF); 2739@end smallexample 2740 2741@noindent 2742This pragma controls the generation of polling code. This is normally off. 2743If @code{pragma Polling (ON)} is used then periodic calls are generated to 2744the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the 2745runtime library, and can be found in file @file{a-excpol.adb}. 2746 2747Pragma @code{Polling} can appear as a configuration pragma (for example it 2748can be placed in the @file{gnat.adc} file) to enable polling globally, or it 2749can be used in the statement or declaration sequence to control polling 2750more locally. 2751 2752A call to the polling routine is generated at the start of every loop and 2753at the start of every subprogram call. This guarantees that the @code{Poll} 2754routine is called frequently, and places an upper bound (determined by 2755the complexity of the code) on the period between two @code{Poll} calls. 2756 2757The primary purpose of the polling interface is to enable asynchronous 2758aborts on targets that cannot otherwise support it (for example Windows 2759NT), but it may be used for any other purpose requiring periodic polling. 2760The standard version is null, and can be replaced by a user program. This 2761will require re-compilation of the @code{Ada.Exceptions} package that can 2762be found in files @file{a-except.ads} and @file{a-except.adb}. 2763 2764A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT 2765distribution) is used to enable the asynchronous abort capability on 2766targets that do not normally support the capability. The version of 2767@code{Poll} in this file makes a call to the appropriate runtime routine 2768to test for an abort condition. 2769 2770Note that polling can also be enabled by use of the @code{-gnatP} switch. See 2771the @cite{GNAT User's Guide} for details. 2772 2773@node Pragma Propagate_Exceptions 2774@unnumberedsec Pragma Propagate_Exceptions 2775@findex Propagate_Exceptions 2776@cindex Zero Cost Exceptions 2777@noindent 2778Syntax: 2779 2780@smallexample @c ada 2781pragma Propagate_Exceptions (subprogram_LOCAL_NAME); 2782@end smallexample 2783 2784@noindent 2785This pragma indicates that the given entity, which is the name of an 2786imported foreign-language subprogram may receive an Ada exception, 2787and that the exception should be propagated. It is relevant only if 2788zero cost exception handling is in use, and is thus never needed if 2789the alternative @code{longjmp} / @code{setjmp} implementation of 2790exceptions is used (although it is harmless to use it in such cases). 2791 2792The implementation of fast exceptions always properly propagates 2793exceptions through Ada code, as described in the Ada Reference Manual. 2794However, this manual is silent about the propagation of exceptions 2795through foreign code. For example, consider the 2796situation where @code{P1} calls 2797@code{P2}, and @code{P2} calls @code{P3}, where 2798@code{P1} and @code{P3} are in Ada, but @code{P2} is in C@. 2799@code{P3} raises an Ada exception. The question is whether or not 2800it will be propagated through @code{P2} and can be handled in 2801@code{P1}. 2802 2803For the @code{longjmp} / @code{setjmp} implementation of exceptions, 2804the answer is always yes. For some targets on which zero cost exception 2805handling is implemented, the answer is also always yes. However, there 2806are some targets, notably in the current version all x86 architecture 2807targets, in which the answer is that such propagation does not 2808happen automatically. If such propagation is required on these 2809targets, it is mandatory to use @code{Propagate_Exceptions} to 2810name all foreign language routines through which Ada exceptions 2811may be propagated. 2812 2813@node Pragma Psect_Object 2814@unnumberedsec Pragma Psect_Object 2815@findex Psect_Object 2816@noindent 2817Syntax: 2818 2819@smallexample @c ada 2820pragma Psect_Object ( 2821 [Internal =>] LOCAL_NAME, 2822 [, [External =>] EXTERNAL_SYMBOL] 2823 [, [Size =>] EXTERNAL_SYMBOL]); 2824 2825EXTERNAL_SYMBOL ::= 2826 IDENTIFIER 2827| static_string_EXPRESSION 2828@end smallexample 2829 2830@noindent 2831This pragma is identical in effect to pragma @code{Common_Object}. 2832 2833@node Pragma Pure_Function 2834@unnumberedsec Pragma Pure_Function 2835@findex Pure_Function 2836@noindent 2837Syntax: 2838 2839@smallexample @c ada 2840pragma Pure_Function ([Entity =>] function_LOCAL_NAME); 2841@end smallexample 2842 2843@noindent 2844This pragma appears in the same declarative part as a function 2845declaration (or a set of function declarations if more than one 2846overloaded declaration exists, in which case the pragma applies 2847to all entities). It specifies that the function @code{Entity} is 2848to be considered pure for the purposes of code generation. This means 2849that the compiler can assume that there are no side effects, and 2850in particular that two calls with identical arguments produce the 2851same result. It also means that the function can be used in an 2852address clause. 2853 2854Note that, quite deliberately, there are no static checks to try 2855to ensure that this promise is met, so @code{Pure_Function} can be used 2856with functions that are conceptually pure, even if they do modify 2857global variables. For example, a square root function that is 2858instrumented to count the number of times it is called is still 2859conceptually pure, and can still be optimized, even though it 2860modifies a global variable (the count). Memo functions are another 2861example (where a table of previous calls is kept and consulted to 2862avoid re-computation). 2863 2864@findex Pure 2865Note: Most functions in a @code{Pure} package are automatically pure, and 2866there is no need to use pragma @code{Pure_Function} for such functions. One 2867exception is any function that has at least one formal of type 2868@code{System.Address} or a type derived from it. Such functions are not 2869considered pure by default, since the compiler assumes that the 2870@code{Address} parameter may be functioning as a pointer and that the 2871referenced data may change even if the address value does not. 2872Similarly, imported functions are not consdered to be pure by default, 2873since there is no way of checking that they are in fact pure. The use 2874of pragma @code{Pure_Function} for such a function will override these default 2875assumption, and cause the compiler to treat a designated subprogram as pure 2876in these cases. 2877 2878Note: If pragma @code{Pure_Function} is applied to a renamed function, it 2879applies to the underlying renamed function. This can be used to 2880disambiguate cases of overloading where some but not all functions 2881in a set of overloaded functions are to be designated as pure. 2882 2883@node Pragma Ravenscar 2884@unnumberedsec Pragma Ravenscar 2885@findex Ravenscar 2886@noindent 2887Syntax: 2888 2889@smallexample @c ada 2890pragma Ravenscar; 2891@end smallexample 2892 2893@noindent 2894A configuration pragma that establishes the following set of restrictions: 2895 2896@table @code 2897@item No_Abort_Statements 2898[RM D.7] There are no abort_statements, and there are 2899no calls to Task_Identification.Abort_Task. 2900 2901@item No_Select_Statements 2902There are no select_statements. 2903 2904@item No_Task_Hierarchy 2905[RM D.7] All (non-environment) tasks depend 2906directly on the environment task of the partition. 2907 2908@item No_Task_Allocators 2909[RM D.7] There are no allocators for task types 2910or types containing task subcomponents. 2911 2912@item No_Dynamic_Priorities 2913[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. 2914 2915@item No_Terminate_Alternatives 2916[RM D.7] There are no selective_accepts with terminate_alternatives 2917 2918@item No_Dynamic_Interrupts 2919There are no semantic dependencies on Ada.Interrupts. 2920 2921@item No_Implicit_Heap_Allocations 2922[RM D.7] No constructs are allowed to cause implicit heap allocation 2923 2924@item No_Protected_Type_Allocators 2925There are no allocators for protected types or 2926types containing protected subcomponents. 2927 2928@item No_Local_Protected_Objects 2929Protected objects and access types that designate 2930such objects shall be declared only at library level. 2931 2932@item No_Requeue 2933Requeue statements are not allowed. 2934 2935@item No_Calendar 2936There are no semantic dependencies on the package Ada.Calendar. 2937 2938@item No_Relative_Delay 2939There are no delay_relative_statements. 2940 2941@item No_Task_Attributes 2942There are no semantic dependencies on the Ada.Task_Attributes package and 2943there are no references to the attributes Callable and Terminated [RM 9.9]. 2944 2945@item Boolean_Entry_Barriers 2946Entry barrier condition expressions shall be boolean 2947objects which are declared in the protected type 2948which contains the entry. 2949 2950@item Max_Asynchronous_Select_Nesting = 0 2951[RM D.7] Specifies the maximum dynamic nesting level of asynchronous_selects. 2952A value of zero prevents the use of any asynchronous_select. 2953 2954@item Max_Task_Entries = 0 2955[RM D.7] Specifies the maximum number of entries 2956per task. The bounds of every entry family 2957of a task unit shall be static, or shall be 2958defined by a discriminant of a subtype whose 2959corresponding bound is static. A value of zero 2960indicates that no rendezvous are possible. For 2961the Ravenscar pragma, the value of Max_Task_Entries is always 29620 (zero). 2963 2964@item Max_Protected_Entries = 1 2965[RM D.7] Specifies the maximum number of entries per 2966protected type. The bounds of every entry family of 2967a protected unit shall be static, or shall be defined 2968by a discriminant of a subtype whose corresponding 2969bound is static. For the Ravenscar pragma the value of 2970Max_Protected_Entries is always 1. 2971 2972@item Max_Select_Alternatives = 0 2973[RM D.7] Specifies the maximum number of alternatives in a selective_accept. 2974For the Ravenscar pragma the value is always 0. 2975 2976@item No_Task_Termination 2977Tasks which terminate are erroneous. 2978 2979@item No_Entry_Queue 2980No task can be queued on a protected entry. Note that this restrictions is 2981checked at run time. The violation of this restriction generates a 2982Program_Error exception. 2983@end table 2984 2985@noindent 2986This set of restrictions corresponds to the definition of the ``Ravenscar 2987Profile'' for limited tasking, devised and published by the 2988@cite{International Real-Time Ada Workshop}, 1997, 2989and whose most recent description is available at 2990@url{ftp://ftp.openravenscar.org/openravenscar/ravenscar00.pdf}. 2991 2992The above set is a superset of the restrictions provided by pragma 2993@code{Restricted_Run_Time}, it includes five additional restrictions 2994(@code{Boolean_Entry_Barriers}, @code{No_Select_Statements}, 2995@code{No_Calendar}, 2996@code{No_Relative_Delay} and @code{No_Task_Termination}). This means 2997that pragma @code{Ravenscar}, like the pragma @code{Restricted_Run_Time}, 2998automatically causes the use of a simplified, more efficient version 2999of the tasking run-time system. 3000 3001@node Pragma Restricted_Run_Time 3002@unnumberedsec Pragma Restricted_Run_Time 3003@findex Restricted_Run_Time 3004@noindent 3005Syntax: 3006 3007@smallexample @c ada 3008pragma Restricted_Run_Time; 3009@end smallexample 3010 3011@noindent 3012A configuration pragma that establishes the following set of restrictions: 3013 3014@itemize @bullet 3015@item No_Abort_Statements 3016@item No_Entry_Queue 3017@item No_Task_Hierarchy 3018@item No_Task_Allocators 3019@item No_Dynamic_Priorities 3020@item No_Terminate_Alternatives 3021@item No_Dynamic_Interrupts 3022@item No_Protected_Type_Allocators 3023@item No_Local_Protected_Objects 3024@item No_Requeue 3025@item No_Task_Attributes 3026@item Max_Asynchronous_Select_Nesting = 0 3027@item Max_Task_Entries = 0 3028@item Max_Protected_Entries = 1 3029@item Max_Select_Alternatives = 0 3030@end itemize 3031 3032@noindent 3033This set of restrictions causes the automatic selection of a simplified 3034version of the run time that provides improved performance for the 3035limited set of tasking functionality permitted by this set of restrictions. 3036 3037@node Pragma Restriction_Warnings 3038@unnumberedsec Pragma Restriction_Warnings 3039@findex Restriction_Warnings 3040@noindent 3041Syntax: 3042 3043@smallexample @c ada 3044pragma Restriction_Warnings 3045 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); 3046@end smallexample 3047 3048@noindent 3049This pragma allows a series of restriction identifiers to be 3050specified (the list of allowed identifiers is the same as for 3051pragma @code{Restrictions}). For each of these identifiers 3052the compiler checks for violations of the restriction, but 3053generates a warning message rather than an error message 3054if the restriction is violated. 3055 3056@node Pragma Source_File_Name 3057@unnumberedsec Pragma Source_File_Name 3058@findex Source_File_Name 3059@noindent 3060Syntax: 3061 3062@smallexample @c ada 3063pragma Source_File_Name ( 3064 [Unit_Name =>] unit_NAME, 3065 Spec_File_Name => STRING_LITERAL); 3066 3067pragma Source_File_Name ( 3068 [Unit_Name =>] unit_NAME, 3069 Body_File_Name => STRING_LITERAL); 3070@end smallexample 3071 3072@noindent 3073Use this to override the normal naming convention. It is a configuration 3074pragma, and so has the usual applicability of configuration pragmas 3075(i.e.@: it applies to either an entire partition, or to all units in a 3076compilation, or to a single unit, depending on how it is used. 3077@var{unit_name} is mapped to @var{file_name_literal}. The identifier for 3078the second argument is required, and indicates whether this is the file 3079name for the spec or for the body. 3080 3081Another form of the @code{Source_File_Name} pragma allows 3082the specification of patterns defining alternative file naming schemes 3083to apply to all files. 3084 3085@smallexample @c ada 3086pragma Source_File_Name 3087 (Spec_File_Name => STRING_LITERAL 3088 [,Casing => CASING_SPEC] 3089 [,Dot_Replacement => STRING_LITERAL]); 3090 3091pragma Source_File_Name 3092 (Body_File_Name => STRING_LITERAL 3093 [,Casing => CASING_SPEC] 3094 [,Dot_Replacement => STRING_LITERAL]); 3095 3096pragma Source_File_Name 3097 (Subunit_File_Name => STRING_LITERAL 3098 [,Casing => CASING_SPEC] 3099 [,Dot_Replacement => STRING_LITERAL]); 3100 3101CASING_SPEC ::= Lowercase | Uppercase | Mixedcase 3102@end smallexample 3103 3104@noindent 3105The first argument is a pattern that contains a single asterisk indicating 3106the point at which the unit name is to be inserted in the pattern string 3107to form the file name. The second argument is optional. If present it 3108specifies the casing of the unit name in the resulting file name string. 3109The default is lower case. Finally the third argument allows for systematic 3110replacement of any dots in the unit name by the specified string literal. 3111 3112A pragma Source_File_Name cannot appear after a 3113@ref{Pragma Source_File_Name_Project}. 3114 3115For more details on the use of the @code{Source_File_Name} pragma, 3116see the sections ``Using Other File Names'' and 3117``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}. 3118 3119@node Pragma Source_File_Name_Project 3120@unnumberedsec Pragma Source_File_Name_Project 3121@findex Source_File_Name_Project 3122@noindent 3123 3124This pragma has the same syntax and semantics as pragma Source_File_Name. 3125It is only allowed as a stand alone configuration pragma. 3126It cannot appear after a @ref{Pragma Source_File_Name}, and 3127most importantly, once pragma Source_File_Name_Project appears, 3128no further Source_File_Name pragmas are allowed. 3129 3130The intention is that Source_File_Name_Project pragmas are always 3131generated by the Project Manager in a manner consistent with the naming 3132specified in a project file, and when naming is controlled in this manner, 3133it is not permissible to attempt to modify this naming scheme using 3134Source_File_Name pragmas (which would not be known to the project manager). 3135 3136@node Pragma Source_Reference 3137@unnumberedsec Pragma Source_Reference 3138@findex Source_Reference 3139@noindent 3140Syntax: 3141 3142@smallexample @c ada 3143pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); 3144@end smallexample 3145 3146@noindent 3147This pragma must appear as the first line of a source file. 3148@var{integer_literal} is the logical line number of the line following 3149the pragma line (for use in error messages and debugging 3150information). @var{string_literal} is a static string constant that 3151specifies the file name to be used in error messages and debugging 3152information. This is most notably used for the output of @code{gnatchop} 3153with the @code{-r} switch, to make sure that the original unchopped 3154source file is the one referred to. 3155 3156The second argument must be a string literal, it cannot be a static 3157string expression other than a string literal. This is because its value 3158is needed for error messages issued by all phases of the compiler. 3159 3160@node Pragma Stream_Convert 3161@unnumberedsec Pragma Stream_Convert 3162@findex Stream_Convert 3163@noindent 3164Syntax: 3165 3166@smallexample @c ada 3167pragma Stream_Convert ( 3168 [Entity =>] type_LOCAL_NAME, 3169 [Read =>] function_NAME, 3170 [Write =>] function NAME); 3171@end smallexample 3172 3173@noindent 3174This pragma provides an efficient way of providing stream functions for 3175types defined in packages. Not only is it simpler to use than declaring 3176the necessary functions with attribute representation clauses, but more 3177significantly, it allows the declaration to made in such a way that the 3178stream packages are not loaded unless they are needed. The use of 3179the Stream_Convert pragma adds no overhead at all, unless the stream 3180attributes are actually used on the designated type. 3181 3182The first argument specifies the type for which stream functions are 3183provided. The second parameter provides a function used to read values 3184of this type. It must name a function whose argument type may be any 3185subtype, and whose returned type must be the type given as the first 3186argument to the pragma. 3187 3188The meaning of the @var{Read} 3189parameter is that if a stream attribute directly 3190or indirectly specifies reading of the type given as the first parameter, 3191then a value of the type given as the argument to the Read function is 3192read from the stream, and then the Read function is used to convert this 3193to the required target type. 3194 3195Similarly the @var{Write} parameter specifies how to treat write attributes 3196that directly or indirectly apply to the type given as the first parameter. 3197It must have an input parameter of the type specified by the first parameter, 3198and the return type must be the same as the input type of the Read function. 3199The effect is to first call the Write function to convert to the given stream 3200type, and then write the result type to the stream. 3201 3202The Read and Write functions must not be overloaded subprograms. If necessary 3203renamings can be supplied to meet this requirement. 3204The usage of this attribute is best illustrated by a simple example, taken 3205from the GNAT implementation of package Ada.Strings.Unbounded: 3206 3207@smallexample @c ada 3208function To_Unbounded (S : String) 3209 return Unbounded_String 3210 renames To_Unbounded_String; 3211 3212pragma Stream_Convert 3213 (Unbounded_String, To_Unbounded, To_String); 3214@end smallexample 3215 3216@noindent 3217The specifications of the referenced functions, as given in the Ada 95 3218Reference Manual are: 3219 3220@smallexample @c ada 3221function To_Unbounded_String (Source : String) 3222 return Unbounded_String; 3223 3224function To_String (Source : Unbounded_String) 3225 return String; 3226@end smallexample 3227 3228@noindent 3229The effect is that if the value of an unbounded string is written to a 3230stream, then the representation of the item in the stream is in the same 3231format used for @code{Standard.String}, and this same representation is 3232expected when a value of this type is read from the stream. 3233 3234@node Pragma Style_Checks 3235@unnumberedsec Pragma Style_Checks 3236@findex Style_Checks 3237@noindent 3238Syntax: 3239 3240@smallexample @c ada 3241pragma Style_Checks (string_LITERAL | ALL_CHECKS | 3242 On | Off [, LOCAL_NAME]); 3243@end smallexample 3244 3245@noindent 3246This pragma is used in conjunction with compiler switches to control the 3247built in style checking provided by GNAT@. The compiler switches, if set, 3248provide an initial setting for the switches, and this pragma may be used 3249to modify these settings, or the settings may be provided entirely by 3250the use of the pragma. This pragma can be used anywhere that a pragma 3251is legal, including use as a configuration pragma (including use in 3252the @file{gnat.adc} file). 3253 3254The form with a string literal specifies which style options are to be 3255activated. These are additive, so they apply in addition to any previously 3256set style check options. The codes for the options are the same as those 3257used in the @code{-gnaty} switch to @code{gcc} or @code{gnatmake}. 3258For example the following two methods can be used to enable 3259layout checking: 3260 3261@itemize @bullet 3262@item 3263@smallexample @c ada 3264pragma Style_Checks ("l"); 3265@end smallexample 3266 3267@item 3268@smallexample 3269gcc -c -gnatyl @dots{} 3270@end smallexample 3271@end itemize 3272 3273@noindent 3274The form ALL_CHECKS activates all standard checks (its use is equivalent 3275to the use of the @code{gnaty} switch with no options. See GNAT User's 3276Guide for details. 3277 3278The forms with @code{Off} and @code{On} 3279can be used to temporarily disable style checks 3280as shown in the following example: 3281 3282@smallexample @c ada 3283@iftex 3284@leftskip=0cm 3285@end iftex 3286pragma Style_Checks ("k"); -- requires keywords in lower case 3287pragma Style_Checks (Off); -- turn off style checks 3288NULL; -- this will not generate an error message 3289pragma Style_Checks (On); -- turn style checks back on 3290NULL; -- this will generate an error message 3291@end smallexample 3292 3293@noindent 3294Finally the two argument form is allowed only if the first argument is 3295@code{On} or @code{Off}. The effect is to turn of semantic style checks 3296for the specified entity, as shown in the following example: 3297 3298@smallexample @c ada 3299@iftex 3300@leftskip=0cm 3301@end iftex 3302pragma Style_Checks ("r"); -- require consistency of identifier casing 3303Arg : Integer; 3304Rf1 : Integer := ARG; -- incorrect, wrong case 3305pragma Style_Checks (Off, Arg); 3306Rf2 : Integer := ARG; -- OK, no error 3307@end smallexample 3308 3309@node Pragma Subtitle 3310@unnumberedsec Pragma Subtitle 3311@findex Subtitle 3312@noindent 3313Syntax: 3314 3315@smallexample @c ada 3316pragma Subtitle ([Subtitle =>] STRING_LITERAL); 3317@end smallexample 3318 3319@noindent 3320This pragma is recognized for compatibility with other Ada compilers 3321but is ignored by GNAT@. 3322 3323@node Pragma Suppress_All 3324@unnumberedsec Pragma Suppress_All 3325@findex Suppress_All 3326@noindent 3327Syntax: 3328 3329@smallexample @c ada 3330pragma Suppress_All; 3331@end smallexample 3332 3333@noindent 3334This pragma can only appear immediately following a compilation 3335unit. The effect is to apply @code{Suppress (All_Checks)} to the unit 3336which it follows. This pragma is implemented for compatibility with DEC 3337Ada 83 usage. The use of pragma @code{Suppress (All_Checks)} as a normal 3338configuration pragma is the preferred usage in GNAT@. 3339 3340@node Pragma Suppress_Exception_Locations 3341@unnumberedsec Pragma Suppress_Exception_Locations 3342@findex Suppress_Exception_Locations 3343@noindent 3344Syntax: 3345 3346@smallexample @c ada 3347pragma Suppress_Exception_Locations; 3348@end smallexample 3349 3350@noindent 3351In normal mode, a raise statement for an exception by default generates 3352an exception message giving the file name and line number for the location 3353of the raise. This is useful for debugging and logging purposes, but this 3354entails extra space for the strings for the messages. The configuration 3355pragma @code{Suppress_Exception_Locations} can be used to suppress the 3356generation of these strings, with the result that space is saved, but the 3357exception message for such raises is null. This configuration pragma may 3358appear in a global configuration pragma file, or in a specific unit as 3359usual. It is not required that this pragma be used consistently within 3360a partition, so it is fine to have some units within a partition compiled 3361with this pragma and others compiled in normal mode without it. 3362 3363@node Pragma Suppress_Initialization 3364@unnumberedsec Pragma Suppress_Initialization 3365@findex Suppress_Initialization 3366@cindex Suppressing initialization 3367@cindex Initialization, suppression of 3368@noindent 3369Syntax: 3370 3371@smallexample @c ada 3372pragma Suppress_Initialization ([Entity =>] type_Name); 3373@end smallexample 3374 3375@noindent 3376This pragma suppresses any implicit or explicit initialization 3377associated with the given type name for all variables of this type. 3378 3379@node Pragma Task_Info 3380@unnumberedsec Pragma Task_Info 3381@findex Task_Info 3382@noindent 3383Syntax 3384 3385@smallexample @c ada 3386pragma Task_Info (EXPRESSION); 3387@end smallexample 3388 3389@noindent 3390This pragma appears within a task definition (like pragma 3391@code{Priority}) and applies to the task in which it appears. The 3392argument must be of type @code{System.Task_Info.Task_Info_Type}. 3393The @code{Task_Info} pragma provides system dependent control over 3394aspects of tasking implementation, for example, the ability to map 3395tasks to specific processors. For details on the facilities available 3396for the version of GNAT that you are using, see the documentation 3397in the specification of package System.Task_Info in the runtime 3398library. 3399 3400@node Pragma Task_Name 3401@unnumberedsec Pragma Task_Name 3402@findex Task_Name 3403@noindent 3404Syntax 3405 3406@smallexample @c ada 3407pragma Task_Name (string_EXPRESSION); 3408@end smallexample 3409 3410@noindent 3411This pragma appears within a task definition (like pragma 3412@code{Priority}) and applies to the task in which it appears. The 3413argument must be of type String, and provides a name to be used for 3414the task instance when the task is created. Note that this expression 3415is not required to be static, and in particular, it can contain 3416references to task discriminants. This facility can be used to 3417provide different names for different tasks as they are created, 3418as illustrated in the example below. 3419 3420The task name is recorded internally in the run-time structures 3421and is accessible to tools like the debugger. In addition the 3422routine @code{Ada.Task_Identification.Image} will return this 3423string, with a unique task address appended. 3424 3425@smallexample @c ada 3426-- Example of the use of pragma Task_Name 3427 3428with Ada.Task_Identification; 3429use Ada.Task_Identification; 3430with Text_IO; use Text_IO; 3431procedure t3 is 3432 3433 type Astring is access String; 3434 3435 task type Task_Typ (Name : access String) is 3436 pragma Task_Name (Name.all); 3437 end Task_Typ; 3438 3439 task body Task_Typ is 3440 Nam : constant String := Image (Current_Task); 3441 begin 3442 Put_Line ("-->" & Nam (1 .. 14) & "<--"); 3443 end Task_Typ; 3444 3445 type Ptr_Task is access Task_Typ; 3446 Task_Var : Ptr_Task; 3447 3448begin 3449 Task_Var := 3450 new Task_Typ (new String'("This is task 1")); 3451 Task_Var := 3452 new Task_Typ (new String'("This is task 2")); 3453end; 3454@end smallexample 3455 3456@node Pragma Task_Storage 3457@unnumberedsec Pragma Task_Storage 3458@findex Task_Storage 3459Syntax: 3460 3461@smallexample @c ada 3462pragma Task_Storage ( 3463 [Task_Type =>] LOCAL_NAME, 3464 [Top_Guard =>] static_integer_EXPRESSION); 3465@end smallexample 3466 3467@noindent 3468This pragma specifies the length of the guard area for tasks. The guard 3469area is an additional storage area allocated to a task. A value of zero 3470means that either no guard area is created or a minimal guard area is 3471created, depending on the target. This pragma can appear anywhere a 3472@code{Storage_Size} attribute definition clause is allowed for a task 3473type. 3474 3475@node Pragma Thread_Body 3476@unnumberedsec Pragma Thread_Body 3477@findex Thread_Body 3478Syntax: 3479 3480@smallexample @c ada 3481pragma Thread_Body ( 3482 [Entity =>] LOCAL_NAME, 3483 [[Secondary_Stack_Size =>] static_integer_EXPRESSION)]; 3484@end smallexample 3485 3486@noindent 3487This pragma specifies that the subprogram whose name is given as the 3488@code{Entity} argument is a thread body, which will be activated 3489by being called via its Address from foreign code. The purpose is 3490to allow execution and registration of the foreign thread within the 3491Ada run-time system. 3492 3493See the library unit @code{System.Threads} for details on the expansion of 3494a thread body subprogram, including the calls made to subprograms 3495within System.Threads to register the task. This unit also lists the 3496targets and runtime systems for which this pragma is supported. 3497 3498A thread body subprogram may not be called directly from Ada code, and 3499it is not permitted to apply the Access (or Unrestricted_Access) attributes 3500to such a subprogram. The only legitimate way of calling such a subprogram 3501is to pass its Address to foreign code and then make the call from the 3502foreign code. 3503 3504A thread body subprogram may have any parameters, and it may be a function 3505returning a result. The convention of the thread body subprogram may be 3506set in the usual manner using @code{pragma Convention}. 3507 3508The secondary stack size parameter, if given, is used to set the size 3509of secondary stack for the thread. The secondary stack is allocated as 3510a local variable of the expanded thread body subprogram, and thus is 3511allocated out of the main thread stack size. If no secondary stack 3512size parameter is present, the default size (from the declaration in 3513@code{System.Secondary_Stack} is used. 3514 3515@node Pragma Time_Slice 3516@unnumberedsec Pragma Time_Slice 3517@findex Time_Slice 3518@noindent 3519Syntax: 3520 3521@smallexample @c ada 3522pragma Time_Slice (static_duration_EXPRESSION); 3523@end smallexample 3524 3525@noindent 3526For implementations of GNAT on operating systems where it is possible 3527to supply a time slice value, this pragma may be used for this purpose. 3528It is ignored if it is used in a system that does not allow this control, 3529or if it appears in other than the main program unit. 3530@cindex OpenVMS 3531Note that the effect of this pragma is identical to the effect of the 3532DEC Ada 83 pragma of the same name when operating under OpenVMS systems. 3533 3534@node Pragma Title 3535@unnumberedsec Pragma Title 3536@findex Title 3537@noindent 3538Syntax: 3539 3540@smallexample @c ada 3541pragma Title (TITLING_OPTION [, TITLING OPTION]); 3542 3543TITLING_OPTION ::= 3544 [Title =>] STRING_LITERAL, 3545| [Subtitle =>] STRING_LITERAL 3546@end smallexample 3547 3548@noindent 3549Syntax checked but otherwise ignored by GNAT@. This is a listing control 3550pragma used in DEC Ada 83 implementations to provide a title and/or 3551subtitle for the program listing. The program listing generated by GNAT 3552does not have titles or subtitles. 3553 3554Unlike other pragmas, the full flexibility of named notation is allowed 3555for this pragma, i.e.@: the parameters may be given in any order if named 3556notation is used, and named and positional notation can be mixed 3557following the normal rules for procedure calls in Ada. 3558 3559@node Pragma Unchecked_Union 3560@unnumberedsec Pragma Unchecked_Union 3561@cindex Unions in C 3562@findex Unchecked_Union 3563@noindent 3564Syntax: 3565 3566@smallexample @c ada 3567pragma Unchecked_Union (first_subtype_LOCAL_NAME); 3568@end smallexample 3569 3570@noindent 3571This pragma is used to declare that the specified type should be represented 3572in a manner 3573equivalent to a C union type, and is intended only for use in 3574interfacing with C code that uses union types. In Ada terms, the named 3575type must obey the following rules: 3576 3577@itemize @bullet 3578@item 3579It is a non-tagged non-limited record type. 3580@item 3581It has a single discrete discriminant with a default value. 3582@item 3583The component list consists of a single variant part. 3584@item 3585Each variant has a component list with a single component. 3586@item 3587No nested variants are allowed. 3588@item 3589No component has an explicit default value. 3590@item 3591No component has a non-static constraint. 3592@end itemize 3593 3594@noindent 3595In addition, given a type that meets the above requirements, the 3596following restrictions apply to its use throughout the program: 3597 3598@itemize @bullet 3599@item 3600The discriminant name can be mentioned only in an aggregate. 3601@item 3602No subtypes may be created of this type. 3603@item 3604The type may not be constrained by giving a discriminant value. 3605@item 3606The type cannot be passed as the actual for a generic formal with a 3607discriminant. 3608@end itemize 3609 3610@noindent 3611Equality and inequality operations on @code{unchecked_unions} are not 3612available, since there is no discriminant to compare and the compiler 3613does not even know how many bits to compare. It is implementation 3614dependent whether this is detected at compile time as an illegality or 3615whether it is undetected and considered to be an erroneous construct. In 3616GNAT, a direct comparison is illegal, but GNAT does not attempt to catch 3617the composite case (where two composites are compared that contain an 3618unchecked union component), so such comparisons are simply considered 3619erroneous. 3620 3621The layout of the resulting type corresponds exactly to a C union, where 3622each branch of the union corresponds to a single variant in the Ada 3623record. The semantics of the Ada program is not changed in any way by 3624the pragma, i.e.@: provided the above restrictions are followed, and no 3625erroneous incorrect references to fields or erroneous comparisons occur, 3626the semantics is exactly as described by the Ada reference manual. 3627Pragma @code{Suppress (Discriminant_Check)} applies implicitly to the 3628type and the default convention is C. 3629 3630@node Pragma Unimplemented_Unit 3631@unnumberedsec Pragma Unimplemented_Unit 3632@findex Unimplemented_Unit 3633@noindent 3634Syntax: 3635 3636@smallexample @c ada 3637pragma Unimplemented_Unit; 3638@end smallexample 3639 3640@noindent 3641If this pragma occurs in a unit that is processed by the compiler, GNAT 3642aborts with the message @samp{@var{xxx} not implemented}, where 3643@var{xxx} is the name of the current compilation unit. This pragma is 3644intended to allow the compiler to handle unimplemented library units in 3645a clean manner. 3646 3647The abort only happens if code is being generated. Thus you can use 3648specs of unimplemented packages in syntax or semantic checking mode. 3649 3650@node Pragma Universal_Data 3651@unnumberedsec Pragma Universal_Data 3652@findex Universal_Data 3653@noindent 3654Syntax: 3655 3656@smallexample @c ada 3657pragma Universal_Data [(library_unit_Name)]; 3658@end smallexample 3659 3660@noindent 3661This pragma is supported only for the AAMP target and is ignored for 3662other targets. The pragma specifies that all library-level objects 3663(Counter 0 data) associated with the library unit are to be accessed 3664and updated using universal addressing (24-bit addresses for AAMP5) 3665rather than the default of 16-bit Data Environment (DENV) addressing. 3666Use of this pragma will generally result in less efficient code for 3667references to global data associated with the library unit, but 3668allows such data to be located anywhere in memory. This pragma is 3669a library unit pragma, but can also be used as a configuration pragma 3670(including use in the @file{gnat.adc} file). The functionality 3671of this pragma is also available by applying the -univ switch on the 3672compilations of units where universal addressing of the data is desired. 3673 3674@node Pragma Unreferenced 3675@unnumberedsec Pragma Unreferenced 3676@findex Unreferenced 3677@cindex Warnings, unreferenced 3678@noindent 3679Syntax: 3680 3681@smallexample @c ada 3682pragma Unreferenced (local_Name @{, local_Name@}); 3683@end smallexample 3684 3685@noindent 3686This pragma signals that the entities whose names are listed are 3687deliberately not referenced. This suppresses warnings about the 3688entities being unreferenced, and in addition a warning will be 3689generated if one of these entities is in fact referenced. 3690 3691This is particularly useful for clearly signaling that a particular 3692parameter is not referenced in some particular subprogram implementation 3693and that this is deliberate. It can also be useful in the case of 3694objects declared only for their initialization or finalization side 3695effects. 3696 3697If @code{local_Name} identifies more than one matching homonym in the 3698current scope, then the entity most recently declared is the one to which 3699the pragma applies. 3700 3701The left hand side of an assignment does not count as a reference for the 3702purpose of this pragma. Thus it is fine to assign to an entity for which 3703pragma Unreferenced is given. 3704 3705@node Pragma Unreserve_All_Interrupts 3706@unnumberedsec Pragma Unreserve_All_Interrupts 3707@findex Unreserve_All_Interrupts 3708@noindent 3709Syntax: 3710 3711@smallexample @c ada 3712pragma Unreserve_All_Interrupts; 3713@end smallexample 3714 3715@noindent 3716Normally certain interrupts are reserved to the implementation. Any attempt 3717to attach an interrupt causes Program_Error to be raised, as described in 3718RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in 3719many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is 3720reserved to the implementation, so that @kbd{Ctrl-C} can be used to 3721interrupt execution. 3722 3723If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in 3724a program, then all such interrupts are unreserved. This allows the 3725program to handle these interrupts, but disables their standard 3726functions. For example, if this pragma is used, then pressing 3727@kbd{Ctrl-C} will not automatically interrupt execution. However, 3728a program can then handle the @code{SIGINT} interrupt as it chooses. 3729 3730For a full list of the interrupts handled in a specific implementation, 3731see the source code for the specification of @code{Ada.Interrupts.Names} in 3732file @file{a-intnam.ads}. This is a target dependent file that contains the 3733list of interrupts recognized for a given target. The documentation in 3734this file also specifies what interrupts are affected by the use of 3735the @code{Unreserve_All_Interrupts} pragma. 3736 3737For a more general facility for controlling what interrupts can be 3738handled, see pragma @code{Interrupt_State}, which subsumes the functionality 3739of the @code{Unreserve_All_Interrupts} pragma. 3740 3741@node Pragma Unsuppress 3742@unnumberedsec Pragma Unsuppress 3743@findex Unsuppress 3744@noindent 3745Syntax: 3746 3747@smallexample @c ada 3748pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); 3749@end smallexample 3750 3751@noindent 3752This pragma undoes the effect of a previous pragma @code{Suppress}. If 3753there is no corresponding pragma @code{Suppress} in effect, it has no 3754effect. The range of the effect is the same as for pragma 3755@code{Suppress}. The meaning of the arguments is identical to that used 3756in pragma @code{Suppress}. 3757 3758One important application is to ensure that checks are on in cases where 3759code depends on the checks for its correct functioning, so that the code 3760will compile correctly even if the compiler switches are set to suppress 3761checks. 3762 3763@node Pragma Use_VADS_Size 3764@unnumberedsec Pragma Use_VADS_Size 3765@cindex @code{Size}, VADS compatibility 3766@findex Use_VADS_Size 3767@noindent 3768Syntax: 3769 3770@smallexample @c ada 3771pragma Use_VADS_Size; 3772@end smallexample 3773 3774@noindent 3775This is a configuration pragma. In a unit to which it applies, any use 3776of the 'Size attribute is automatically interpreted as a use of the 3777'VADS_Size attribute. Note that this may result in incorrect semantic 3778processing of valid Ada 95 programs. This is intended to aid in the 3779handling of legacy code which depends on the interpretation of Size 3780as implemented in the VADS compiler. See description of the VADS_Size 3781attribute for further details. 3782 3783@node Pragma Validity_Checks 3784@unnumberedsec Pragma Validity_Checks 3785@findex Validity_Checks 3786@noindent 3787Syntax: 3788 3789@smallexample @c ada 3790pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); 3791@end smallexample 3792 3793@noindent 3794This pragma is used in conjunction with compiler switches to control the 3795built-in validity checking provided by GNAT@. The compiler switches, if set 3796provide an initial setting for the switches, and this pragma may be used 3797to modify these settings, or the settings may be provided entirely by 3798the use of the pragma. This pragma can be used anywhere that a pragma 3799is legal, including use as a configuration pragma (including use in 3800the @file{gnat.adc} file). 3801 3802The form with a string literal specifies which validity options are to be 3803activated. The validity checks are first set to include only the default 3804reference manual settings, and then a string of letters in the string 3805specifies the exact set of options required. The form of this string 3806is exactly as described for the @code{-gnatVx} compiler switch (see the 3807GNAT users guide for details). For example the following two methods 3808can be used to enable validity checking for mode @code{in} and 3809@code{in out} subprogram parameters: 3810 3811@itemize @bullet 3812@item 3813@smallexample @c ada 3814pragma Validity_Checks ("im"); 3815@end smallexample 3816 3817@item 3818@smallexample 3819gcc -c -gnatVim @dots{} 3820@end smallexample 3821@end itemize 3822 3823@noindent 3824The form ALL_CHECKS activates all standard checks (its use is equivalent 3825to the use of the @code{gnatva} switch. 3826 3827The forms with @code{Off} and @code{On} 3828can be used to temporarily disable validity checks 3829as shown in the following example: 3830 3831@smallexample @c ada 3832@iftex 3833@leftskip=0cm 3834@end iftex 3835pragma Validity_Checks ("c"); -- validity checks for copies 3836pragma Validity_Checks (Off); -- turn off validity checks 3837A := B; -- B will not be validity checked 3838pragma Validity_Checks (On); -- turn validity checks back on 3839A := C; -- C will be validity checked 3840@end smallexample 3841 3842@node Pragma Volatile 3843@unnumberedsec Pragma Volatile 3844@findex Volatile 3845@noindent 3846Syntax: 3847 3848@smallexample @c ada 3849pragma Volatile (local_NAME); 3850@end smallexample 3851 3852@noindent 3853This pragma is defined by the Ada 95 Reference Manual, and the GNAT 3854implementation is fully conformant with this definition. The reason it 3855is mentioned in this section is that a pragma of the same name was supplied 3856in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation 3857of pragma Volatile is upwards compatible with the implementation in 3858Dec Ada 83. 3859 3860@node Pragma Warnings 3861@unnumberedsec Pragma Warnings 3862@findex Warnings 3863@noindent 3864Syntax: 3865 3866@smallexample @c ada 3867pragma Warnings (On | Off [, LOCAL_NAME]); 3868@end smallexample 3869 3870@noindent 3871Normally warnings are enabled, with the output being controlled by 3872the command line switch. Warnings (@code{Off}) turns off generation of 3873warnings until a Warnings (@code{On}) is encountered or the end of the 3874current unit. If generation of warnings is turned off using this 3875pragma, then no warning messages are output, regardless of the 3876setting of the command line switches. 3877 3878The form with a single argument is a configuration pragma. 3879 3880If the @var{local_name} parameter is present, warnings are suppressed for 3881the specified entity. This suppression is effective from the point where 3882it occurs till the end of the extended scope of the variable (similar to 3883the scope of @code{Suppress}). 3884 3885@node Pragma Weak_External 3886@unnumberedsec Pragma Weak_External 3887@findex Weak_External 3888@noindent 3889Syntax: 3890 3891@smallexample @c ada 3892pragma Weak_External ([Entity =>] LOCAL_NAME); 3893@end smallexample 3894 3895@noindent 3896This pragma specifies that the given entity should be marked as a weak 3897external (one that does not have to be resolved) for the linker. For 3898further details, consult the GCC manual. 3899 3900@node Implementation Defined Attributes 3901@chapter Implementation Defined Attributes 3902Ada 95 defines (throughout the Ada 95 reference manual, 3903summarized in annex K), 3904a set of attributes that provide useful additional functionality in all 3905areas of the language. These language defined attributes are implemented 3906in GNAT and work as described in the Ada 95 Reference Manual. 3907 3908In addition, Ada 95 allows implementations to define additional 3909attributes whose meaning is defined by the implementation. GNAT provides 3910a number of these implementation-dependent attributes which can be used 3911to extend and enhance the functionality of the compiler. This section of 3912the GNAT reference manual describes these additional attributes. 3913 3914Note that any program using these attributes may not be portable to 3915other compilers (although GNAT implements this set of attributes on all 3916platforms). Therefore if portability to other compilers is an important 3917consideration, you should minimize the use of these attributes. 3918 3919@menu 3920* Abort_Signal:: 3921* Address_Size:: 3922* Asm_Input:: 3923* Asm_Output:: 3924* AST_Entry:: 3925* Bit:: 3926* Bit_Position:: 3927* Code_Address:: 3928* Default_Bit_Order:: 3929* Elaborated:: 3930* Elab_Body:: 3931* Elab_Spec:: 3932* Emax:: 3933* Enum_Rep:: 3934* Epsilon:: 3935* Fixed_Value:: 3936* Has_Discriminants:: 3937* Img:: 3938* Integer_Value:: 3939* Large:: 3940* Machine_Size:: 3941* Mantissa:: 3942* Max_Interrupt_Priority:: 3943* Max_Priority:: 3944* Maximum_Alignment:: 3945* Mechanism_Code:: 3946* Null_Parameter:: 3947* Object_Size:: 3948* Passed_By_Reference:: 3949* Range_Length:: 3950* Safe_Emax:: 3951* Safe_Large:: 3952* Small:: 3953* Storage_Unit:: 3954* Target_Name:: 3955* Tick:: 3956* To_Address:: 3957* Type_Class:: 3958* UET_Address:: 3959* Unconstrained_Array:: 3960* Universal_Literal_String:: 3961* Unrestricted_Access:: 3962* VADS_Size:: 3963* Value_Size:: 3964* Wchar_T_Size:: 3965* Word_Size:: 3966@end menu 3967 3968@node Abort_Signal 3969@unnumberedsec Abort_Signal 3970@findex Abort_Signal 3971@noindent 3972@code{Standard'Abort_Signal} (@code{Standard} is the only allowed 3973prefix) provides the entity for the special exception used to signal 3974task abort or asynchronous transfer of control. Normally this attribute 3975should only be used in the tasking runtime (it is highly peculiar, and 3976completely outside the normal semantics of Ada, for a user program to 3977intercept the abort exception). 3978 3979@node Address_Size 3980@unnumberedsec Address_Size 3981@cindex Size of @code{Address} 3982@findex Address_Size 3983@noindent 3984@code{Standard'Address_Size} (@code{Standard} is the only allowed 3985prefix) is a static constant giving the number of bits in an 3986@code{Address}. It is the same value as System.Address'Size, 3987but has the advantage of being static, while a direct 3988reference to System.Address'Size is non-static because Address 3989is a private type. 3990 3991@node Asm_Input 3992@unnumberedsec Asm_Input 3993@findex Asm_Input 3994@noindent 3995The @code{Asm_Input} attribute denotes a function that takes two 3996parameters. The first is a string, the second is an expression of the 3997type designated by the prefix. The first (string) argument is required 3998to be a static expression, and is the constraint for the parameter, 3999(e.g.@: what kind of register is required). The second argument is the 4000value to be used as the input argument. The possible values for the 4001constant are the same as those used in the RTL, and are dependent on 4002the configuration file used to built the GCC back end. 4003@ref{Machine Code Insertions} 4004 4005@node Asm_Output 4006@unnumberedsec Asm_Output 4007@findex Asm_Output 4008@noindent 4009The @code{Asm_Output} attribute denotes a function that takes two 4010parameters. The first is a string, the second is the name of a variable 4011of the type designated by the attribute prefix. The first (string) 4012argument is required to be a static expression and designates the 4013constraint for the parameter (e.g.@: what kind of register is 4014required). The second argument is the variable to be updated with the 4015result. The possible values for constraint are the same as those used in 4016the RTL, and are dependent on the configuration file used to build the 4017GCC back end. If there are no output operands, then this argument may 4018either be omitted, or explicitly given as @code{No_Output_Operands}. 4019@ref{Machine Code Insertions} 4020 4021@node AST_Entry 4022@unnumberedsec AST_Entry 4023@cindex OpenVMS 4024@findex AST_Entry 4025@noindent 4026This attribute is implemented only in OpenVMS versions of GNAT@. Applied to 4027the name of an entry, it yields a value of the predefined type AST_Handler 4028(declared in the predefined package System, as extended by the use of 4029pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to 4030be called when an AST occurs. For further details, refer to the @cite{DEC Ada 4031Language Reference Manual}, section 9.12a. 4032 4033@node Bit 4034@unnumberedsec Bit 4035@findex Bit 4036@code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit 4037offset within the storage unit (byte) that contains the first bit of 4038storage allocated for the object. The value of this attribute is of the 4039type @code{Universal_Integer}, and is always a non-negative number not 4040exceeding the value of @code{System.Storage_Unit}. 4041 4042For an object that is a variable or a constant allocated in a register, 4043the value is zero. (The use of this attribute does not force the 4044allocation of a variable to memory). 4045 4046For an object that is a formal parameter, this attribute applies 4047to either the matching actual parameter or to a copy of the 4048matching actual parameter. 4049 4050For an access object the value is zero. Note that 4051@code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the 4052designated object. Similarly for a record component 4053@code{@var{X}.@var{C}'Bit} is subject to a discriminant check and 4054@code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit} 4055are subject to index checks. 4056 4057This attribute is designed to be compatible with the DEC Ada 83 definition 4058and implementation of the @code{Bit} attribute. 4059 4060@node Bit_Position 4061@unnumberedsec Bit_Position 4062@findex Bit_Position 4063@noindent 4064@code{@var{R.C}'Bit}, where @var{R} is a record object and C is one 4065of the fields of the record type, yields the bit 4066offset within the record contains the first bit of 4067storage allocated for the object. The value of this attribute is of the 4068type @code{Universal_Integer}. The value depends only on the field 4069@var{C} and is independent of the alignment of 4070the containing record @var{R}. 4071 4072@node Code_Address 4073@unnumberedsec Code_Address 4074@findex Code_Address 4075@cindex Subprogram address 4076@cindex Address of subprogram code 4077@noindent 4078The @code{'Address} 4079attribute may be applied to subprograms in Ada 95, but the 4080intended effect from the Ada 95 reference manual seems to be to provide 4081an address value which can be used to call the subprogram by means of 4082an address clause as in the following example: 4083 4084@smallexample @c ada 4085procedure K is @dots{} 4086 4087procedure L; 4088for L'Address use K'Address; 4089pragma Import (Ada, L); 4090@end smallexample 4091 4092@noindent 4093A call to @code{L} is then expected to result in a call to @code{K}@. 4094In Ada 83, where there were no access-to-subprogram values, this was 4095a common work around for getting the effect of an indirect call. 4096GNAT implements the above use of @code{Address} and the technique 4097illustrated by the example code works correctly. 4098 4099However, for some purposes, it is useful to have the address of the start 4100of the generated code for the subprogram. On some architectures, this is 4101not necessarily the same as the @code{Address} value described above. 4102For example, the @code{Address} value may reference a subprogram 4103descriptor rather than the subprogram itself. 4104 4105The @code{'Code_Address} attribute, which can only be applied to 4106subprogram entities, always returns the address of the start of the 4107generated code of the specified subprogram, which may or may not be 4108the same value as is returned by the corresponding @code{'Address} 4109attribute. 4110 4111@node Default_Bit_Order 4112@unnumberedsec Default_Bit_Order 4113@cindex Big endian 4114@cindex Little endian 4115@findex Default_Bit_Order 4116@noindent 4117@code{Standard'Default_Bit_Order} (@code{Standard} is the only 4118permissible prefix), provides the value @code{System.Default_Bit_Order} 4119as a @code{Pos} value (0 for @code{High_Order_First}, 1 for 4120@code{Low_Order_First}). This is used to construct the definition of 4121@code{Default_Bit_Order} in package @code{System}. 4122 4123@node Elaborated 4124@unnumberedsec Elaborated 4125@findex Elaborated 4126@noindent 4127The prefix of the @code{'Elaborated} attribute must be a unit name. The 4128value is a Boolean which indicates whether or not the given unit has been 4129elaborated. This attribute is primarily intended for internal use by the 4130generated code for dynamic elaboration checking, but it can also be used 4131in user programs. The value will always be True once elaboration of all 4132units has been completed. 4133 4134@node Elab_Body 4135@unnumberedsec Elab_Body 4136@findex Elab_Body 4137@noindent 4138This attribute can only be applied to a program unit name. It returns 4139the entity for the corresponding elaboration procedure for elaborating 4140the body of the referenced unit. This is used in the main generated 4141elaboration procedure by the binder and is not normally used in any 4142other context. However, there may be specialized situations in which it 4143is useful to be able to call this elaboration procedure from Ada code, 4144e.g.@: if it is necessary to do selective re-elaboration to fix some 4145error. 4146 4147@node Elab_Spec 4148@unnumberedsec Elab_Spec 4149@findex Elab_Spec 4150@noindent 4151This attribute can only be applied to a program unit name. It returns 4152the entity for the corresponding elaboration procedure for elaborating 4153the specification of the referenced unit. This is used in the main 4154generated elaboration procedure by the binder and is not normally used 4155in any other context. However, there may be specialized situations in 4156which it is useful to be able to call this elaboration procedure from 4157Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix 4158some error. 4159 4160@node Emax 4161@unnumberedsec Emax 4162@cindex Ada 83 attributes 4163@findex Emax 4164@noindent 4165The @code{Emax} attribute is provided for compatibility with Ada 83. See 4166the Ada 83 reference manual for an exact description of the semantics of 4167this attribute. 4168 4169@node Enum_Rep 4170@unnumberedsec Enum_Rep 4171@cindex Representation of enums 4172@findex Enum_Rep 4173@noindent 4174For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a 4175function with the following spec: 4176 4177@smallexample @c ada 4178function @var{S}'Enum_Rep (Arg : @var{S}'Base) 4179 return @i{Universal_Integer}; 4180@end smallexample 4181 4182@noindent 4183It is also allowable to apply @code{Enum_Rep} directly to an object of an 4184enumeration type or to a non-overloaded enumeration 4185literal. In this case @code{@var{S}'Enum_Rep} is equivalent to 4186@code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the 4187enumeration literal or object. 4188 4189The function returns the representation value for the given enumeration 4190value. This will be equal to value of the @code{Pos} attribute in the 4191absence of an enumeration representation clause. This is a static 4192attribute (i.e.@: the result is static if the argument is static). 4193 4194@code{@var{S}'Enum_Rep} can also be used with integer types and objects, 4195in which case it simply returns the integer value. The reason for this 4196is to allow it to be used for @code{(<>)} discrete formal arguments in 4197a generic unit that can be instantiated with either enumeration types 4198or integer types. Note that if @code{Enum_Rep} is used on a modular 4199type whose upper bound exceeds the upper bound of the largest signed 4200integer type, and the argument is a variable, so that the universal 4201integer calculation is done at run-time, then the call to @code{Enum_Rep} 4202may raise @code{Constraint_Error}. 4203 4204@node Epsilon 4205@unnumberedsec Epsilon 4206@cindex Ada 83 attributes 4207@findex Epsilon 4208@noindent 4209The @code{Epsilon} attribute is provided for compatibility with Ada 83. See 4210the Ada 83 reference manual for an exact description of the semantics of 4211this attribute. 4212 4213@node Fixed_Value 4214@unnumberedsec Fixed_Value 4215@findex Fixed_Value 4216@noindent 4217For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a 4218function with the following specification: 4219 4220@smallexample @c ada 4221function @var{S}'Fixed_Value (Arg : @i{Universal_Integer}) 4222 return @var{S}; 4223@end smallexample 4224 4225@noindent 4226The value returned is the fixed-point value @var{V} such that 4227 4228@smallexample @c ada 4229@var{V} = Arg * @var{S}'Small 4230@end smallexample 4231 4232@noindent 4233The effect is thus similar to first converting the argument to the 4234integer type used to represent @var{S}, and then doing an unchecked 4235conversion to the fixed-point type. The difference is 4236that there are full range checks, to ensure that the result is in range. 4237This attribute is primarily intended for use in implementation of the 4238input-output functions for fixed-point values. 4239 4240@node Has_Discriminants 4241@unnumberedsec Has_Discriminants 4242@cindex Discriminants, testing for 4243@findex Has_Discriminants 4244@noindent 4245The prefix of the @code{Has_Discriminants} attribute is a type. The result 4246is a Boolean value which is True if the type has discriminants, and False 4247otherwise. The intended use of this attribute is in conjunction with generic 4248definitions. If the attribute is applied to a generic private type, it 4249indicates whether or not the corresponding actual type has discriminants. 4250 4251@node Img 4252@unnumberedsec Img 4253@findex Img 4254@noindent 4255The @code{Img} attribute differs from @code{Image} in that it may be 4256applied to objects as well as types, in which case it gives the 4257@code{Image} for the subtype of the object. This is convenient for 4258debugging: 4259 4260@smallexample @c ada 4261Put_Line ("X = " & X'Img); 4262@end smallexample 4263 4264@noindent 4265has the same meaning as the more verbose: 4266 4267@smallexample @c ada 4268Put_Line ("X = " & @var{T}'Image (X)); 4269@end smallexample 4270 4271@noindent 4272where @var{T} is the (sub)type of the object @code{X}. 4273 4274@node Integer_Value 4275@unnumberedsec Integer_Value 4276@findex Integer_Value 4277@noindent 4278For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a 4279function with the following spec: 4280 4281@smallexample @c ada 4282function @var{S}'Integer_Value (Arg : @i{Universal_Fixed}) 4283 return @var{S}; 4284@end smallexample 4285 4286@noindent 4287The value returned is the integer value @var{V}, such that 4288 4289@smallexample @c ada 4290Arg = @var{V} * @var{T}'Small 4291@end smallexample 4292 4293@noindent 4294where @var{T} is the type of @code{Arg}. 4295The effect is thus similar to first doing an unchecked conversion from 4296the fixed-point type to its corresponding implementation type, and then 4297converting the result to the target integer type. The difference is 4298that there are full range checks, to ensure that the result is in range. 4299This attribute is primarily intended for use in implementation of the 4300standard input-output functions for fixed-point values. 4301 4302@node Large 4303@unnumberedsec Large 4304@cindex Ada 83 attributes 4305@findex Large 4306@noindent 4307The @code{Large} attribute is provided for compatibility with Ada 83. See 4308the Ada 83 reference manual for an exact description of the semantics of 4309this attribute. 4310 4311@node Machine_Size 4312@unnumberedsec Machine_Size 4313@findex Machine_Size 4314@noindent 4315This attribute is identical to the @code{Object_Size} attribute. It is 4316provided for compatibility with the DEC Ada 83 attribute of this name. 4317 4318@node Mantissa 4319@unnumberedsec Mantissa 4320@cindex Ada 83 attributes 4321@findex Mantissa 4322@noindent 4323The @code{Mantissa} attribute is provided for compatibility with Ada 83. See 4324the Ada 83 reference manual for an exact description of the semantics of 4325this attribute. 4326 4327@node Max_Interrupt_Priority 4328@unnumberedsec Max_Interrupt_Priority 4329@cindex Interrupt priority, maximum 4330@findex Max_Interrupt_Priority 4331@noindent 4332@code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only 4333permissible prefix), provides the same value as 4334@code{System.Max_Interrupt_Priority}. 4335 4336@node Max_Priority 4337@unnumberedsec Max_Priority 4338@cindex Priority, maximum 4339@findex Max_Priority 4340@noindent 4341@code{Standard'Max_Priority} (@code{Standard} is the only permissible 4342prefix) provides the same value as @code{System.Max_Priority}. 4343 4344@node Maximum_Alignment 4345@unnumberedsec Maximum_Alignment 4346@cindex Alignment, maximum 4347@findex Maximum_Alignment 4348@noindent 4349@code{Standard'Maximum_Alignment} (@code{Standard} is the only 4350permissible prefix) provides the maximum useful alignment value for the 4351target. This is a static value that can be used to specify the alignment 4352for an object, guaranteeing that it is properly aligned in all 4353cases. 4354 4355@node Mechanism_Code 4356@unnumberedsec Mechanism_Code 4357@cindex Return values, passing mechanism 4358@cindex Parameters, passing mechanism 4359@findex Mechanism_Code 4360@noindent 4361@code{@var{function}'Mechanism_Code} yields an integer code for the 4362mechanism used for the result of function, and 4363@code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism 4364used for formal parameter number @var{n} (a static integer value with 1 4365meaning the first parameter) of @var{subprogram}. The code returned is: 4366 4367@table @asis 4368@item 1 4369by copy (value) 4370@item 2 4371by reference 4372@item 3 4373by descriptor (default descriptor class) 4374@item 4 4375by descriptor (UBS: unaligned bit string) 4376@item 5 4377by descriptor (UBSB: aligned bit string with arbitrary bounds) 4378@item 6 4379by descriptor (UBA: unaligned bit array) 4380@item 7 4381by descriptor (S: string, also scalar access type parameter) 4382@item 8 4383by descriptor (SB: string with arbitrary bounds) 4384@item 9 4385by descriptor (A: contiguous array) 4386@item 10 4387by descriptor (NCA: non-contiguous array) 4388@end table 4389 4390@noindent 4391Values from 3 through 10 are only relevant to Digital OpenVMS implementations. 4392@cindex OpenVMS 4393 4394@node Null_Parameter 4395@unnumberedsec Null_Parameter 4396@cindex Zero address, passing 4397@findex Null_Parameter 4398@noindent 4399A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of 4400type or subtype @var{T} allocated at machine address zero. The attribute 4401is allowed only as the default expression of a formal parameter, or as 4402an actual expression of a subprogram call. In either case, the 4403subprogram must be imported. 4404 4405The identity of the object is represented by the address zero in the 4406argument list, independent of the passing mechanism (explicit or 4407default). 4408 4409This capability is needed to specify that a zero address should be 4410passed for a record or other composite object passed by reference. 4411There is no way of indicating this without the @code{Null_Parameter} 4412attribute. 4413 4414@node Object_Size 4415@unnumberedsec Object_Size 4416@cindex Size, used for objects 4417@findex Object_Size 4418@noindent 4419The size of an object is not necessarily the same as the size of the type 4420of an object. This is because by default object sizes are increased to be 4421a multiple of the alignment of the object. For example, 4422@code{Natural'Size} is 442331, but by default objects of type @code{Natural} will have a size of 32 bits. 4424Similarly, a record containing an integer and a character: 4425 4426@smallexample @c ada 4427type Rec is record 4428 I : Integer; 4429 C : Character; 4430end record; 4431@end smallexample 4432 4433@noindent 4434will have a size of 40 (that is @code{Rec'Size} will be 40. The 4435alignment will be 4, because of the 4436integer field, and so the default size of record objects for this type 4437will be 64 (8 bytes). 4438 4439The @code{@var{type}'Object_Size} attribute 4440has been added to GNAT to allow the 4441default object size of a type to be easily determined. For example, 4442@code{Natural'Object_Size} is 32, and 4443@code{Rec'Object_Size} (for the record type in the above example) will be 444464. Note also that, unlike the situation with the 4445@code{Size} attribute as defined in the Ada RM, the 4446@code{Object_Size} attribute can be specified individually 4447for different subtypes. For example: 4448 4449@smallexample @c ada 4450type R is new Integer; 4451subtype R1 is R range 1 .. 10; 4452subtype R2 is R range 1 .. 10; 4453for R2'Object_Size use 8; 4454@end smallexample 4455 4456@noindent 4457In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both 445832 since the default object size for a subtype is the same as the object size 4459for the parent subtype. This means that objects of type @code{R} 4460or @code{R1} will 4461by default be 32 bits (four bytes). But objects of type 4462@code{R2} will be only 44638 bits (one byte), since @code{R2'Object_Size} has been set to 8. 4464 4465@node Passed_By_Reference 4466@unnumberedsec Passed_By_Reference 4467@cindex Parameters, when passed by reference 4468@findex Passed_By_Reference 4469@noindent 4470@code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns 4471a value of type @code{Boolean} value that is @code{True} if the type is 4472normally passed by reference and @code{False} if the type is normally 4473passed by copy in calls. For scalar types, the result is always @code{False} 4474and is static. For non-scalar types, the result is non-static. 4475 4476@node Range_Length 4477@unnumberedsec Range_Length 4478@findex Range_Length 4479@noindent 4480@code{@var{type}'Range_Length} for any discrete type @var{type} yields 4481the number of values represented by the subtype (zero for a null 4482range). The result is static for static subtypes. @code{Range_Length} 4483applied to the index subtype of a one dimensional array always gives the 4484same result as @code{Range} applied to the array itself. 4485 4486@node Safe_Emax 4487@unnumberedsec Safe_Emax 4488@cindex Ada 83 attributes 4489@findex Safe_Emax 4490@noindent 4491The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See 4492the Ada 83 reference manual for an exact description of the semantics of 4493this attribute. 4494 4495@node Safe_Large 4496@unnumberedsec Safe_Large 4497@cindex Ada 83 attributes 4498@findex Safe_Large 4499@noindent 4500The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See 4501the Ada 83 reference manual for an exact description of the semantics of 4502this attribute. 4503 4504@node Small 4505@unnumberedsec Small 4506@cindex Ada 83 attributes 4507@findex Small 4508@noindent 4509The @code{Small} attribute is defined in Ada 95 only for fixed-point types. 4510GNAT also allows this attribute to be applied to floating-point types 4511for compatibility with Ada 83. See 4512the Ada 83 reference manual for an exact description of the semantics of 4513this attribute when applied to floating-point types. 4514 4515@node Storage_Unit 4516@unnumberedsec Storage_Unit 4517@findex Storage_Unit 4518@noindent 4519@code{Standard'Storage_Unit} (@code{Standard} is the only permissible 4520prefix) provides the same value as @code{System.Storage_Unit}. 4521 4522@node Target_Name 4523@unnumberedsec Target_Name 4524@findex Target_Name 4525@noindent 4526@code{Standard'Target_Name} (@code{Standard} is the only permissible 4527prefix) provides a static string value that identifies the target 4528for the current compilation. For GCC implementations, this is the 4529standard gcc target name without the terminating slash (for 4530example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). 4531 4532@node Tick 4533@unnumberedsec Tick 4534@findex Tick 4535@noindent 4536@code{Standard'Tick} (@code{Standard} is the only permissible prefix) 4537provides the same value as @code{System.Tick}, 4538 4539@node To_Address 4540@unnumberedsec To_Address 4541@findex To_Address 4542@noindent 4543The @code{System'To_Address} 4544(@code{System} is the only permissible prefix) 4545denotes a function identical to 4546@code{System.Storage_Elements.To_Address} except that 4547it is a static attribute. This means that if its argument is 4548a static expression, then the result of the attribute is a 4549static expression. The result is that such an expression can be 4550used in contexts (e.g.@: preelaborable packages) which require a 4551static expression and where the function call could not be used 4552(since the function call is always non-static, even if its 4553argument is static). 4554 4555@node Type_Class 4556@unnumberedsec Type_Class 4557@findex Type_Class 4558@noindent 4559@code{@var{type}'Type_Class} for any type or subtype @var{type} yields 4560the value of the type class for the full type of @var{type}. If 4561@var{type} is a generic formal type, the value is the value for the 4562corresponding actual subtype. The value of this attribute is of type 4563@code{System.Aux_DEC.Type_Class}, which has the following definition: 4564 4565@smallexample @c ada 4566 type Type_Class is 4567 (Type_Class_Enumeration, 4568 Type_Class_Integer, 4569 Type_Class_Fixed_Point, 4570 Type_Class_Floating_Point, 4571 Type_Class_Array, 4572 Type_Class_Record, 4573 Type_Class_Access, 4574 Type_Class_Task, 4575 Type_Class_Address); 4576@end smallexample 4577 4578@noindent 4579Protected types yield the value @code{Type_Class_Task}, which thus 4580applies to all concurrent types. This attribute is designed to 4581be compatible with the DEC Ada 83 attribute of the same name. 4582 4583@node UET_Address 4584@unnumberedsec UET_Address 4585@findex UET_Address 4586@noindent 4587The @code{UET_Address} attribute can only be used for a prefix which 4588denotes a library package. It yields the address of the unit exception 4589table when zero cost exception handling is used. This attribute is 4590intended only for use within the GNAT implementation. See the unit 4591@code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb} 4592for details on how this attribute is used in the implementation. 4593 4594@node Unconstrained_Array 4595@unnumberedsec Unconstrained_Array 4596@findex Unconstrained_Array 4597@noindent 4598The @code{Unconstrained_Array} attribute can be used with a prefix that 4599denotes any type or subtype. It is a static attribute that yields 4600@code{True} if the prefix designates an unconstrained array, 4601and @code{False} otherwise. In a generic instance, the result is 4602still static, and yields the result of applying this test to the 4603generic actual. 4604 4605@node Universal_Literal_String 4606@unnumberedsec Universal_Literal_String 4607@cindex Named numbers, representation of 4608@findex Universal_Literal_String 4609@noindent 4610The prefix of @code{Universal_Literal_String} must be a named 4611number. The static result is the string consisting of the characters of 4612the number as defined in the original source. This allows the user 4613program to access the actual text of named numbers without intermediate 4614conversions and without the need to enclose the strings in quotes (which 4615would preclude their use as numbers). This is used internally for the 4616construction of values of the floating-point attributes from the file 4617@file{ttypef.ads}, but may also be used by user programs. 4618 4619@node Unrestricted_Access 4620@unnumberedsec Unrestricted_Access 4621@cindex @code{Access}, unrestricted 4622@findex Unrestricted_Access 4623@noindent 4624The @code{Unrestricted_Access} attribute is similar to @code{Access} 4625except that all accessibility and aliased view checks are omitted. This 4626is a user-beware attribute. It is similar to 4627@code{Address}, for which it is a desirable replacement where the value 4628desired is an access type. In other words, its effect is identical to 4629first applying the @code{Address} attribute and then doing an unchecked 4630conversion to a desired access type. In GNAT, but not necessarily in 4631other implementations, the use of static chains for inner level 4632subprograms means that @code{Unrestricted_Access} applied to a 4633subprogram yields a value that can be called as long as the subprogram 4634is in scope (normal Ada 95 accessibility rules restrict this usage). 4635 4636It is possible to use @code{Unrestricted_Access} for any type, but care 4637must be excercised if it is used to create pointers to unconstrained 4638objects. In this case, the resulting pointer has the same scope as the 4639context of the attribute, and may not be returned to some enclosing 4640scope. For instance, a function cannot use @code{Unrestricted_Access} 4641to create a unconstrained pointer and then return that value to the 4642caller. 4643 4644@node VADS_Size 4645@unnumberedsec VADS_Size 4646@cindex @code{Size}, VADS compatibility 4647@findex VADS_Size 4648@noindent 4649The @code{'VADS_Size} attribute is intended to make it easier to port 4650legacy code which relies on the semantics of @code{'Size} as implemented 4651by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the 4652same semantic interpretation. In particular, @code{'VADS_Size} applied 4653to a predefined or other primitive type with no Size clause yields the 4654Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on 4655typical machines). In addition @code{'VADS_Size} applied to an object 4656gives the result that would be obtained by applying the attribute to 4657the corresponding type. 4658 4659@node Value_Size 4660@unnumberedsec Value_Size 4661@cindex @code{Size}, setting for not-first subtype 4662@findex Value_Size 4663@code{@var{type}'Value_Size} is the number of bits required to represent 4664a value of the given subtype. It is the same as @code{@var{type}'Size}, 4665but, unlike @code{Size}, may be set for non-first subtypes. 4666 4667@node Wchar_T_Size 4668@unnumberedsec Wchar_T_Size 4669@findex Wchar_T_Size 4670@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible 4671prefix) provides the size in bits of the C @code{wchar_t} type 4672primarily for constructing the definition of this type in 4673package @code{Interfaces.C}. 4674 4675@node Word_Size 4676@unnumberedsec Word_Size 4677@findex Word_Size 4678@code{Standard'Word_Size} (@code{Standard} is the only permissible 4679prefix) provides the value @code{System.Word_Size}. 4680 4681@c ------------------------ 4682@node Implementation Advice 4683@chapter Implementation Advice 4684@noindent 4685The main text of the Ada 95 Reference Manual describes the required 4686behavior of all Ada 95 compilers, and the GNAT compiler conforms to 4687these requirements. 4688 4689In addition, there are sections throughout the Ada 95 4690reference manual headed 4691by the phrase ``implementation advice''. These sections are not normative, 4692i.e.@: they do not specify requirements that all compilers must 4693follow. Rather they provide advice on generally desirable behavior. You 4694may wonder why they are not requirements. The most typical answer is 4695that they describe behavior that seems generally desirable, but cannot 4696be provided on all systems, or which may be undesirable on some systems. 4697 4698As far as practical, GNAT follows the implementation advice sections in 4699the Ada 95 Reference Manual. This chapter contains a table giving the 4700reference manual section number, paragraph number and several keywords 4701for each advice. Each entry consists of the text of the advice followed 4702by the GNAT interpretation of this advice. Most often, this simply says 4703``followed'', which means that GNAT follows the advice. However, in a 4704number of cases, GNAT deliberately deviates from this advice, in which 4705case the text describes what GNAT does and why. 4706 4707@cindex Error detection 4708@unnumberedsec 1.1.3(20): Error Detection 4709@sp 1 4710@cartouche 4711If an implementation detects the use of an unsupported Specialized Needs 4712Annex feature at run time, it should raise @code{Program_Error} if 4713feasible. 4714@end cartouche 4715Not relevant. All specialized needs annex features are either supported, 4716or diagnosed at compile time. 4717 4718@cindex Child Units 4719@unnumberedsec 1.1.3(31): Child Units 4720@sp 1 4721@cartouche 4722If an implementation wishes to provide implementation-defined 4723extensions to the functionality of a language-defined library unit, it 4724should normally do so by adding children to the library unit. 4725@end cartouche 4726Followed. 4727 4728@cindex Bounded errors 4729@unnumberedsec 1.1.5(12): Bounded Errors 4730@sp 1 4731@cartouche 4732If an implementation detects a bounded error or erroneous 4733execution, it should raise @code{Program_Error}. 4734@end cartouche 4735Followed in all cases in which the implementation detects a bounded 4736error or erroneous execution. Not all such situations are detected at 4737runtime. 4738 4739@cindex Pragmas 4740@unnumberedsec 2.8(16): Pragmas 4741@sp 1 4742@cartouche 4743Normally, implementation-defined pragmas should have no semantic effect 4744for error-free programs; that is, if the implementation-defined pragmas 4745are removed from a working program, the program should still be legal, 4746and should still have the same semantics. 4747@end cartouche 4748The following implementation defined pragmas are exceptions to this 4749rule: 4750 4751@table @code 4752@item Abort_Defer 4753Affects semantics 4754@item Ada_83 4755Affects legality 4756@item Assert 4757Affects semantics 4758@item CPP_Class 4759Affects semantics 4760@item CPP_Constructor 4761Affects semantics 4762@item CPP_Virtual 4763Affects semantics 4764@item CPP_Vtable 4765Affects semantics 4766@item Debug 4767Affects semantics 4768@item Interface_Name 4769Affects semantics 4770@item Machine_Attribute 4771Affects semantics 4772@item Unimplemented_Unit 4773Affects legality 4774@item Unchecked_Union 4775Affects semantics 4776@end table 4777 4778@noindent 4779In each of the above cases, it is essential to the purpose of the pragma 4780that this advice not be followed. For details see the separate section 4781on implementation defined pragmas. 4782 4783@unnumberedsec 2.8(17-19): Pragmas 4784@sp 1 4785@cartouche 4786Normally, an implementation should not define pragmas that can 4787make an illegal program legal, except as follows: 4788@end cartouche 4789@sp 1 4790@cartouche 4791A pragma used to complete a declaration, such as a pragma @code{Import}; 4792@end cartouche 4793@sp 1 4794@cartouche 4795A pragma used to configure the environment by adding, removing, or 4796replacing @code{library_items}. 4797@end cartouche 4798See response to paragraph 16 of this same section. 4799 4800@cindex Character Sets 4801@cindex Alternative Character Sets 4802@unnumberedsec 3.5.2(5): Alternative Character Sets 4803@sp 1 4804@cartouche 4805If an implementation supports a mode with alternative interpretations 4806for @code{Character} and @code{Wide_Character}, the set of graphic 4807characters of @code{Character} should nevertheless remain a proper 4808subset of the set of graphic characters of @code{Wide_Character}. Any 4809character set ``localizations'' should be reflected in the results of 4810the subprograms defined in the language-defined package 4811@code{Characters.Handling} (see A.3) available in such a mode. In a mode with 4812an alternative interpretation of @code{Character}, the implementation should 4813also support a corresponding change in what is a legal 4814@code{identifier_letter}. 4815@end cartouche 4816Not all wide character modes follow this advice, in particular the JIS 4817and IEC modes reflect standard usage in Japan, and in these encoding, 4818the upper half of the Latin-1 set is not part of the wide-character 4819subset, since the most significant bit is used for wide character 4820encoding. However, this only applies to the external forms. Internally 4821there is no such restriction. 4822 4823@cindex Integer types 4824@unnumberedsec 3.5.4(28): Integer Types 4825 4826@sp 1 4827@cartouche 4828An implementation should support @code{Long_Integer} in addition to 4829@code{Integer} if the target machine supports 32-bit (or longer) 4830arithmetic. No other named integer subtypes are recommended for package 4831@code{Standard}. Instead, appropriate named integer subtypes should be 4832provided in the library package @code{Interfaces} (see B.2). 4833@end cartouche 4834@code{Long_Integer} is supported. Other standard integer types are supported 4835so this advice is not fully followed. These types 4836are supported for convenient interface to C, and so that all hardware 4837types of the machine are easily available. 4838@unnumberedsec 3.5.4(29): Integer Types 4839 4840@sp 1 4841@cartouche 4842An implementation for a two's complement machine should support 4843modular types with a binary modulus up to @code{System.Max_Int*2+2}. An 4844implementation should support a non-binary modules up to @code{Integer'Last}. 4845@end cartouche 4846Followed. 4847 4848@cindex Enumeration values 4849@unnumberedsec 3.5.5(8): Enumeration Values 4850@sp 1 4851@cartouche 4852For the evaluation of a call on @code{@var{S}'Pos} for an enumeration 4853subtype, if the value of the operand does not correspond to the internal 4854code for any enumeration literal of its type (perhaps due to an 4855un-initialized variable), then the implementation should raise 4856@code{Program_Error}. This is particularly important for enumeration 4857types with noncontiguous internal codes specified by an 4858enumeration_representation_clause. 4859@end cartouche 4860Followed. 4861 4862@cindex Float types 4863@unnumberedsec 3.5.7(17): Float Types 4864@sp 1 4865@cartouche 4866An implementation should support @code{Long_Float} in addition to 4867@code{Float} if the target machine supports 11 or more digits of 4868precision. No other named floating point subtypes are recommended for 4869package @code{Standard}. Instead, appropriate named floating point subtypes 4870should be provided in the library package @code{Interfaces} (see B.2). 4871@end cartouche 4872@code{Short_Float} and @code{Long_Long_Float} are also provided. The 4873former provides improved compatibility with other implementations 4874supporting this type. The latter corresponds to the highest precision 4875floating-point type supported by the hardware. On most machines, this 4876will be the same as @code{Long_Float}, but on some machines, it will 4877correspond to the IEEE extended form. The notable case is all ia32 4878(x86) implementations, where @code{Long_Long_Float} corresponds to 4879the 80-bit extended precision format supported in hardware on this 4880processor. Note that the 128-bit format on SPARC is not supported, 4881since this is a software rather than a hardware format. 4882 4883@cindex Multidimensional arrays 4884@cindex Arrays, multidimensional 4885@unnumberedsec 3.6.2(11): Multidimensional Arrays 4886@sp 1 4887@cartouche 4888An implementation should normally represent multidimensional arrays in 4889row-major order, consistent with the notation used for multidimensional 4890array aggregates (see 4.3.3). However, if a pragma @code{Convention} 4891(@code{Fortran}, @dots{}) applies to a multidimensional array type, then 4892column-major order should be used instead (see B.5, ``Interfacing with 4893Fortran''). 4894@end cartouche 4895Followed. 4896 4897@findex Duration'Small 4898@unnumberedsec 9.6(30-31): Duration'Small 4899@sp 1 4900@cartouche 4901Whenever possible in an implementation, the value of @code{Duration'Small} 4902should be no greater than 100 microseconds. 4903@end cartouche 4904Followed. (@code{Duration'Small} = 10**(@minus{}9)). 4905 4906@sp 1 4907@cartouche 4908The time base for @code{delay_relative_statements} should be monotonic; 4909it need not be the same time base as used for @code{Calendar.Clock}. 4910@end cartouche 4911Followed. 4912 4913@unnumberedsec 10.2.1(12): Consistent Representation 4914@sp 1 4915@cartouche 4916In an implementation, a type declared in a pre-elaborated package should 4917have the same representation in every elaboration of a given version of 4918the package, whether the elaborations occur in distinct executions of 4919the same program, or in executions of distinct programs or partitions 4920that include the given version. 4921@end cartouche 4922Followed, except in the case of tagged types. Tagged types involve 4923implicit pointers to a local copy of a dispatch table, and these pointers 4924have representations which thus depend on a particular elaboration of the 4925package. It is not easy to see how it would be possible to follow this 4926advice without severely impacting efficiency of execution. 4927 4928@cindex Exception information 4929@unnumberedsec 11.4.1(19): Exception Information 4930@sp 1 4931@cartouche 4932@code{Exception_Message} by default and @code{Exception_Information} 4933should produce information useful for 4934debugging. @code{Exception_Message} should be short, about one 4935line. @code{Exception_Information} can be long. @code{Exception_Message} 4936should not include the 4937@code{Exception_Name}. @code{Exception_Information} should include both 4938the @code{Exception_Name} and the @code{Exception_Message}. 4939@end cartouche 4940Followed. For each exception that doesn't have a specified 4941@code{Exception_Message}, the compiler generates one containing the location 4942of the raise statement. This location has the form ``file:line'', where 4943file is the short file name (without path information) and line is the line 4944number in the file. Note that in the case of the Zero Cost Exception 4945mechanism, these messages become redundant with the Exception_Information that 4946contains a full backtrace of the calling sequence, so they are disabled. 4947To disable explicitly the generation of the source location message, use the 4948Pragma @code{Discard_Names}. 4949 4950@cindex Suppression of checks 4951@cindex Checks, suppression of 4952@unnumberedsec 11.5(28): Suppression of Checks 4953@sp 1 4954@cartouche 4955The implementation should minimize the code executed for checks that 4956have been suppressed. 4957@end cartouche 4958Followed. 4959 4960@cindex Representation clauses 4961@unnumberedsec 13.1 (21-24): Representation Clauses 4962@sp 1 4963@cartouche 4964The recommended level of support for all representation items is 4965qualified as follows: 4966@end cartouche 4967@sp 1 4968@cartouche 4969An implementation need not support representation items containing 4970non-static expressions, except that an implementation should support a 4971representation item for a given entity if each non-static expression in 4972the representation item is a name that statically denotes a constant 4973declared before the entity. 4974@end cartouche 4975Followed. GNAT does not support non-static expressions in representation 4976clauses unless they are constants declared before the entity. For 4977example: 4978 4979@smallexample @c ada 4980X : Some_Type; 4981for X'Address use To_address (16#2000#); 4982@end smallexample 4983 4984@noindent 4985will be rejected, since the To_Address expression is non-static. Instead 4986write: 4987 4988@smallexample @c ada 4989X_Address : constant Address : = To_Address (16#2000#); 4990X : Some_Type; 4991for X'Address use X_Address; 4992@end smallexample 4993 4994@sp 1 4995@cartouche 4996An implementation need not support a specification for the @code{Size} 4997for a given composite subtype, nor the size or storage place for an 4998object (including a component) of a given composite subtype, unless the 4999constraints on the subtype and its composite subcomponents (if any) are 5000all static constraints. 5001@end cartouche 5002Followed. Size Clauses are not permitted on non-static components, as 5003described above. 5004 5005@sp 1 5006@cartouche 5007An aliased component, or a component whose type is by-reference, should 5008always be allocated at an addressable location. 5009@end cartouche 5010Followed. 5011 5012@cindex Packed types 5013@unnumberedsec 13.2(6-8): Packed Types 5014@sp 1 5015@cartouche 5016If a type is packed, then the implementation should try to minimize 5017storage allocated to objects of the type, possibly at the expense of 5018speed of accessing components, subject to reasonable complexity in 5019addressing calculations. 5020@end cartouche 5021@sp 1 5022@cartouche 5023The recommended level of support pragma @code{Pack} is: 5024 5025For a packed record type, the components should be packed as tightly as 5026possible subject to the Sizes of the component subtypes, and subject to 5027any @code{record_representation_clause} that applies to the type; the 5028implementation may, but need not, reorder components or cross aligned 5029word boundaries to improve the packing. A component whose @code{Size} is 5030greater than the word size may be allocated an integral number of words. 5031@end cartouche 5032Followed. Tight packing of arrays is supported for all component sizes 5033up to 64-bits. If the array component size is 1 (that is to say, if 5034the component is a boolean type or an enumeration type with two values) 5035then values of the type are implicitly initialized to zero. This 5036happens both for objects of the packed type, and for objects that have a 5037subcomponent of the packed type. 5038 5039@sp 1 5040@cartouche 5041An implementation should support Address clauses for imported 5042subprograms. 5043@end cartouche 5044Followed. 5045@cindex @code{Address} clauses 5046@unnumberedsec 13.3(14-19): Address Clauses 5047 5048@sp 1 5049@cartouche 5050For an array @var{X}, @code{@var{X}'Address} should point at the first 5051component of the array, and not at the array bounds. 5052@end cartouche 5053Followed. 5054 5055@sp 1 5056@cartouche 5057The recommended level of support for the @code{Address} attribute is: 5058 5059@code{@var{X}'Address} should produce a useful result if @var{X} is an 5060object that is aliased or of a by-reference type, or is an entity whose 5061@code{Address} has been specified. 5062@end cartouche 5063Followed. A valid address will be produced even if none of those 5064conditions have been met. If necessary, the object is forced into 5065memory to ensure the address is valid. 5066 5067@sp 1 5068@cartouche 5069An implementation should support @code{Address} clauses for imported 5070subprograms. 5071@end cartouche 5072Followed. 5073 5074@sp 1 5075@cartouche 5076Objects (including subcomponents) that are aliased or of a by-reference 5077type should be allocated on storage element boundaries. 5078@end cartouche 5079Followed. 5080 5081@sp 1 5082@cartouche 5083If the @code{Address} of an object is specified, or it is imported or exported, 5084then the implementation should not perform optimizations based on 5085assumptions of no aliases. 5086@end cartouche 5087Followed. 5088 5089@cindex @code{Alignment} clauses 5090@unnumberedsec 13.3(29-35): Alignment Clauses 5091@sp 1 5092@cartouche 5093The recommended level of support for the @code{Alignment} attribute for 5094subtypes is: 5095 5096An implementation should support specified Alignments that are factors 5097and multiples of the number of storage elements per word, subject to the 5098following: 5099@end cartouche 5100Followed. 5101 5102@sp 1 5103@cartouche 5104An implementation need not support specified @code{Alignment}s for 5105combinations of @code{Size}s and @code{Alignment}s that cannot be easily 5106loaded and stored by available machine instructions. 5107@end cartouche 5108Followed. 5109 5110@sp 1 5111@cartouche 5112An implementation need not support specified @code{Alignment}s that are 5113greater than the maximum @code{Alignment} the implementation ever returns by 5114default. 5115@end cartouche 5116Followed. 5117 5118@sp 1 5119@cartouche 5120The recommended level of support for the @code{Alignment} attribute for 5121objects is: 5122 5123Same as above, for subtypes, but in addition: 5124@end cartouche 5125Followed. 5126 5127@sp 1 5128@cartouche 5129For stand-alone library-level objects of statically constrained 5130subtypes, the implementation should support all @code{Alignment}s 5131supported by the target linker. For example, page alignment is likely to 5132be supported for such objects, but not for subtypes. 5133@end cartouche 5134Followed. 5135 5136@cindex @code{Size} clauses 5137@unnumberedsec 13.3(42-43): Size Clauses 5138@sp 1 5139@cartouche 5140The recommended level of support for the @code{Size} attribute of 5141objects is: 5142 5143A @code{Size} clause should be supported for an object if the specified 5144@code{Size} is at least as large as its subtype's @code{Size}, and 5145corresponds to a size in storage elements that is a multiple of the 5146object's @code{Alignment} (if the @code{Alignment} is nonzero). 5147@end cartouche 5148Followed. 5149 5150@unnumberedsec 13.3(50-56): Size Clauses 5151@sp 1 5152@cartouche 5153If the @code{Size} of a subtype is specified, and allows for efficient 5154independent addressability (see 9.10) on the target architecture, then 5155the @code{Size} of the following objects of the subtype should equal the 5156@code{Size} of the subtype: 5157 5158Aliased objects (including components). 5159@end cartouche 5160Followed. 5161 5162@sp 1 5163@cartouche 5164@code{Size} clause on a composite subtype should not affect the 5165internal layout of components. 5166@end cartouche 5167Followed. 5168 5169@sp 1 5170@cartouche 5171The recommended level of support for the @code{Size} attribute of subtypes is: 5172@end cartouche 5173@sp 1 5174@cartouche 5175The @code{Size} (if not specified) of a static discrete or fixed point 5176subtype should be the number of bits needed to represent each value 5177belonging to the subtype using an unbiased representation, leaving space 5178for a sign bit only if the subtype contains negative values. If such a 5179subtype is a first subtype, then an implementation should support a 5180specified @code{Size} for it that reflects this representation. 5181@end cartouche 5182Followed. 5183 5184@sp 1 5185@cartouche 5186For a subtype implemented with levels of indirection, the @code{Size} 5187should include the size of the pointers, but not the size of what they 5188point at. 5189@end cartouche 5190Followed. 5191 5192@cindex @code{Component_Size} clauses 5193@unnumberedsec 13.3(71-73): Component Size Clauses 5194@sp 1 5195@cartouche 5196The recommended level of support for the @code{Component_Size} 5197attribute is: 5198@end cartouche 5199@sp 1 5200@cartouche 5201An implementation need not support specified @code{Component_Sizes} that are 5202less than the @code{Size} of the component subtype. 5203@end cartouche 5204Followed. 5205 5206@sp 1 5207@cartouche 5208An implementation should support specified @code{Component_Size}s that 5209are factors and multiples of the word size. For such 5210@code{Component_Size}s, the array should contain no gaps between 5211components. For other @code{Component_Size}s (if supported), the array 5212should contain no gaps between components when packing is also 5213specified; the implementation should forbid this combination in cases 5214where it cannot support a no-gaps representation. 5215@end cartouche 5216Followed. 5217 5218@cindex Enumeration representation clauses 5219@cindex Representation clauses, enumeration 5220@unnumberedsec 13.4(9-10): Enumeration Representation Clauses 5221@sp 1 5222@cartouche 5223The recommended level of support for enumeration representation clauses 5224is: 5225 5226An implementation need not support enumeration representation clauses 5227for boolean types, but should at minimum support the internal codes in 5228the range @code{System.Min_Int.System.Max_Int}. 5229@end cartouche 5230Followed. 5231 5232@cindex Record representation clauses 5233@cindex Representation clauses, records 5234@unnumberedsec 13.5.1(17-22): Record Representation Clauses 5235@sp 1 5236@cartouche 5237The recommended level of support for 5238@*@code{record_representation_clauses} is: 5239 5240An implementation should support storage places that can be extracted 5241with a load, mask, shift sequence of machine code, and set with a load, 5242shift, mask, store sequence, given the available machine instructions 5243and run-time model. 5244@end cartouche 5245Followed. 5246 5247@sp 1 5248@cartouche 5249A storage place should be supported if its size is equal to the 5250@code{Size} of the component subtype, and it starts and ends on a 5251boundary that obeys the @code{Alignment} of the component subtype. 5252@end cartouche 5253Followed. 5254 5255@sp 1 5256@cartouche 5257If the default bit ordering applies to the declaration of a given type, 5258then for a component whose subtype's @code{Size} is less than the word 5259size, any storage place that does not cross an aligned word boundary 5260should be supported. 5261@end cartouche 5262Followed. 5263 5264@sp 1 5265@cartouche 5266An implementation may reserve a storage place for the tag field of a 5267tagged type, and disallow other components from overlapping that place. 5268@end cartouche 5269Followed. The storage place for the tag field is the beginning of the tagged 5270record, and its size is Address'Size. GNAT will reject an explicit component 5271clause for the tag field. 5272 5273@sp 1 5274@cartouche 5275An implementation need not support a @code{component_clause} for a 5276component of an extension part if the storage place is not after the 5277storage places of all components of the parent type, whether or not 5278those storage places had been specified. 5279@end cartouche 5280Followed. The above advice on record representation clauses is followed, 5281and all mentioned features are implemented. 5282 5283@cindex Storage place attributes 5284@unnumberedsec 13.5.2(5): Storage Place Attributes 5285@sp 1 5286@cartouche 5287If a component is represented using some form of pointer (such as an 5288offset) to the actual data of the component, and this data is contiguous 5289with the rest of the object, then the storage place attributes should 5290reflect the place of the actual data, not the pointer. If a component is 5291allocated discontinuously from the rest of the object, then a warning 5292should be generated upon reference to one of its storage place 5293attributes. 5294@end cartouche 5295Followed. There are no such components in GNAT@. 5296 5297@cindex Bit ordering 5298@unnumberedsec 13.5.3(7-8): Bit Ordering 5299@sp 1 5300@cartouche 5301The recommended level of support for the non-default bit ordering is: 5302@end cartouche 5303@sp 1 5304@cartouche 5305If @code{Word_Size} = @code{Storage_Unit}, then the implementation 5306should support the non-default bit ordering in addition to the default 5307bit ordering. 5308@end cartouche 5309Followed. Word size does not equal storage size in this implementation. 5310Thus non-default bit ordering is not supported. 5311 5312@cindex @code{Address}, as private type 5313@unnumberedsec 13.7(37): Address as Private 5314@sp 1 5315@cartouche 5316@code{Address} should be of a private type. 5317@end cartouche 5318Followed. 5319 5320@cindex Operations, on @code{Address} 5321@cindex @code{Address}, operations of 5322@unnumberedsec 13.7.1(16): Address Operations 5323@sp 1 5324@cartouche 5325Operations in @code{System} and its children should reflect the target 5326environment semantics as closely as is reasonable. For example, on most 5327machines, it makes sense for address arithmetic to ``wrap around''. 5328Operations that do not make sense should raise @code{Program_Error}. 5329@end cartouche 5330Followed. Address arithmetic is modular arithmetic that wraps around. No 5331operation raises @code{Program_Error}, since all operations make sense. 5332 5333@cindex Unchecked conversion 5334@unnumberedsec 13.9(14-17): Unchecked Conversion 5335@sp 1 5336@cartouche 5337The @code{Size} of an array object should not include its bounds; hence, 5338the bounds should not be part of the converted data. 5339@end cartouche 5340Followed. 5341 5342@sp 1 5343@cartouche 5344The implementation should not generate unnecessary run-time checks to 5345ensure that the representation of @var{S} is a representation of the 5346target type. It should take advantage of the permission to return by 5347reference when possible. Restrictions on unchecked conversions should be 5348avoided unless required by the target environment. 5349@end cartouche 5350Followed. There are no restrictions on unchecked conversion. A warning is 5351generated if the source and target types do not have the same size since 5352the semantics in this case may be target dependent. 5353 5354@sp 1 5355@cartouche 5356The recommended level of support for unchecked conversions is: 5357@end cartouche 5358@sp 1 5359@cartouche 5360Unchecked conversions should be supported and should be reversible in 5361the cases where this clause defines the result. To enable meaningful use 5362of unchecked conversion, a contiguous representation should be used for 5363elementary subtypes, for statically constrained array subtypes whose 5364component subtype is one of the subtypes described in this paragraph, 5365and for record subtypes without discriminants whose component subtypes 5366are described in this paragraph. 5367@end cartouche 5368Followed. 5369 5370@cindex Heap usage, implicit 5371@unnumberedsec 13.11(23-25): Implicit Heap Usage 5372@sp 1 5373@cartouche 5374An implementation should document any cases in which it dynamically 5375allocates heap storage for a purpose other than the evaluation of an 5376allocator. 5377@end cartouche 5378Followed, the only other points at which heap storage is dynamically 5379allocated are as follows: 5380 5381@itemize @bullet 5382@item 5383At initial elaboration time, to allocate dynamically sized global 5384objects. 5385 5386@item 5387To allocate space for a task when a task is created. 5388 5389@item 5390To extend the secondary stack dynamically when needed. The secondary 5391stack is used for returning variable length results. 5392@end itemize 5393 5394@sp 1 5395@cartouche 5396A default (implementation-provided) storage pool for an 5397access-to-constant type should not have overhead to support deallocation of 5398individual objects. 5399@end cartouche 5400Followed. 5401 5402@sp 1 5403@cartouche 5404A storage pool for an anonymous access type should be created at the 5405point of an allocator for the type, and be reclaimed when the designated 5406object becomes inaccessible. 5407@end cartouche 5408Followed. 5409 5410@cindex Unchecked deallocation 5411@unnumberedsec 13.11.2(17): Unchecked De-allocation 5412@sp 1 5413@cartouche 5414For a standard storage pool, @code{Free} should actually reclaim the 5415storage. 5416@end cartouche 5417Followed. 5418 5419@cindex Stream oriented attributes 5420@unnumberedsec 13.13.2(17): Stream Oriented Attributes 5421@sp 1 5422@cartouche 5423If a stream element is the same size as a storage element, then the 5424normal in-memory representation should be used by @code{Read} and 5425@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write} 5426should use the smallest number of stream elements needed to represent 5427all values in the base range of the scalar type. 5428@end cartouche 5429 5430Followed. By default, GNAT uses the interpretation suggested by AI-195, 5431which specifies using the size of the first subtype. 5432However, such an implementation is based on direct binary 5433representations and is therefore target- and endianness-dependent. 5434To address this issue, GNAT also supplies an alternate implementation 5435of the stream attributes @code{Read} and @code{Write}, 5436which uses the target-independent XDR standard representation 5437for scalar types. 5438@cindex XDR representation 5439@cindex @code{Read} attribute 5440@cindex @code{Write} attribute 5441@cindex Stream oriented attributes 5442The XDR implementation is provided as an alternative body of the 5443@code{System.Stream_Attributes} package, in the file 5444@file{s-strxdr.adb} in the GNAT library. 5445There is no @file{s-strxdr.ads} file. 5446In order to install the XDR implementation, do the following: 5447@enumerate 5448@item Replace the default implementation of the 5449@code{System.Stream_Attributes} package with the XDR implementation. 5450For example on a Unix platform issue the commands: 5451@smallexample 5452$ mv s-stratt.adb s-strold.adb 5453$ mv s-strxdr.adb s-stratt.adb 5454@end smallexample 5455 5456@item 5457Rebuild the GNAT run-time library as documented in the 5458@cite{GNAT User's Guide} 5459@end enumerate 5460 5461@unnumberedsec A.1(52): Names of Predefined Numeric Types 5462@sp 1 5463@cartouche 5464If an implementation provides additional named predefined integer types, 5465then the names should end with @samp{Integer} as in 5466@samp{Long_Integer}. If an implementation provides additional named 5467predefined floating point types, then the names should end with 5468@samp{Float} as in @samp{Long_Float}. 5469@end cartouche 5470Followed. 5471 5472@findex Ada.Characters.Handling 5473@unnumberedsec A.3.2(49): @code{Ada.Characters.Handling} 5474@sp 1 5475@cartouche 5476If an implementation provides a localized definition of @code{Character} 5477or @code{Wide_Character}, then the effects of the subprograms in 5478@code{Characters.Handling} should reflect the localizations. See also 54793.5.2. 5480@end cartouche 5481Followed. GNAT provides no such localized definitions. 5482 5483@cindex Bounded-length strings 5484@unnumberedsec A.4.4(106): Bounded-Length String Handling 5485@sp 1 5486@cartouche 5487Bounded string objects should not be implemented by implicit pointers 5488and dynamic allocation. 5489@end cartouche 5490Followed. No implicit pointers or dynamic allocation are used. 5491 5492@cindex Random number generation 5493@unnumberedsec A.5.2(46-47): Random Number Generation 5494@sp 1 5495@cartouche 5496Any storage associated with an object of type @code{Generator} should be 5497reclaimed on exit from the scope of the object. 5498@end cartouche 5499Followed. 5500 5501@sp 1 5502@cartouche 5503If the generator period is sufficiently long in relation to the number 5504of distinct initiator values, then each possible value of 5505@code{Initiator} passed to @code{Reset} should initiate a sequence of 5506random numbers that does not, in a practical sense, overlap the sequence 5507initiated by any other value. If this is not possible, then the mapping 5508between initiator values and generator states should be a rapidly 5509varying function of the initiator value. 5510@end cartouche 5511Followed. The generator period is sufficiently long for the first 5512condition here to hold true. 5513 5514@findex Get_Immediate 5515@unnumberedsec A.10.7(23): @code{Get_Immediate} 5516@sp 1 5517@cartouche 5518The @code{Get_Immediate} procedures should be implemented with 5519unbuffered input. For a device such as a keyboard, input should be 5520@dfn{available} if a key has already been typed, whereas for a disk 5521file, input should always be available except at end of file. For a file 5522associated with a keyboard-like device, any line-editing features of the 5523underlying operating system should be disabled during the execution of 5524@code{Get_Immediate}. 5525@end cartouche 5526Followed on all targets except VxWorks. For VxWorks, there is no way to 5527provide this functionality that does not result in the input buffer being 5528flushed before the @code{Get_Immediate} call. A special unit 5529@code{Interfaces.Vxworks.IO} is provided that contains routines to enable 5530this functionality. 5531 5532@findex Export 5533@unnumberedsec B.1(39-41): Pragma @code{Export} 5534@sp 1 5535@cartouche 5536If an implementation supports pragma @code{Export} to a given language, 5537then it should also allow the main subprogram to be written in that 5538language. It should support some mechanism for invoking the elaboration 5539of the Ada library units included in the system, and for invoking the 5540finalization of the environment task. On typical systems, the 5541recommended mechanism is to provide two subprograms whose link names are 5542@code{adainit} and @code{adafinal}. @code{adainit} should contain the 5543elaboration code for library units. @code{adafinal} should contain the 5544finalization code. These subprograms should have no effect the second 5545and subsequent time they are called. 5546@end cartouche 5547Followed. 5548 5549@sp 1 5550@cartouche 5551Automatic elaboration of pre-elaborated packages should be 5552provided when pragma @code{Export} is supported. 5553@end cartouche 5554Followed when the main program is in Ada. If the main program is in a 5555foreign language, then 5556@code{adainit} must be called to elaborate pre-elaborated 5557packages. 5558 5559@sp 1 5560@cartouche 5561For each supported convention @var{L} other than @code{Intrinsic}, an 5562implementation should support @code{Import} and @code{Export} pragmas 5563for objects of @var{L}-compatible types and for subprograms, and pragma 5564@code{Convention} for @var{L}-eligible types and for subprograms, 5565presuming the other language has corresponding features. Pragma 5566@code{Convention} need not be supported for scalar types. 5567@end cartouche 5568Followed. 5569 5570@cindex Package @code{Interfaces} 5571@findex Interfaces 5572@unnumberedsec B.2(12-13): Package @code{Interfaces} 5573@sp 1 5574@cartouche 5575For each implementation-defined convention identifier, there should be a 5576child package of package Interfaces with the corresponding name. This 5577package should contain any declarations that would be useful for 5578interfacing to the language (implementation) represented by the 5579convention. Any declarations useful for interfacing to any language on 5580the given hardware architecture should be provided directly in 5581@code{Interfaces}. 5582@end cartouche 5583Followed. An additional package not defined 5584in the Ada 95 Reference Manual is @code{Interfaces.CPP}, used 5585for interfacing to C++. 5586 5587@sp 1 5588@cartouche 5589An implementation supporting an interface to C, COBOL, or Fortran should 5590provide the corresponding package or packages described in the following 5591clauses. 5592@end cartouche 5593Followed. GNAT provides all the packages described in this section. 5594 5595@cindex C, interfacing with 5596@unnumberedsec B.3(63-71): Interfacing with C 5597@sp 1 5598@cartouche 5599An implementation should support the following interface correspondences 5600between Ada and C@. 5601@end cartouche 5602Followed. 5603 5604@sp 1 5605@cartouche 5606An Ada procedure corresponds to a void-returning C function. 5607@end cartouche 5608Followed. 5609 5610@sp 1 5611@cartouche 5612An Ada function corresponds to a non-void C function. 5613@end cartouche 5614Followed. 5615 5616@sp 1 5617@cartouche 5618An Ada @code{in} scalar parameter is passed as a scalar argument to a C 5619function. 5620@end cartouche 5621Followed. 5622 5623@sp 1 5624@cartouche 5625An Ada @code{in} parameter of an access-to-object type with designated 5626type @var{T} is passed as a @code{@var{t}*} argument to a C function, 5627where @var{t} is the C type corresponding to the Ada type @var{T}. 5628@end cartouche 5629Followed. 5630 5631@sp 1 5632@cartouche 5633An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out} 5634parameter of an elementary type @var{T}, is passed as a @code{@var{t}*} 5635argument to a C function, where @var{t} is the C type corresponding to 5636the Ada type @var{T}. In the case of an elementary @code{out} or 5637@code{in out} parameter, a pointer to a temporary copy is used to 5638preserve by-copy semantics. 5639@end cartouche 5640Followed. 5641 5642@sp 1 5643@cartouche 5644An Ada parameter of a record type @var{T}, of any mode, is passed as a 5645@code{@var{t}*} argument to a C function, where @var{t} is the C 5646structure corresponding to the Ada type @var{T}. 5647@end cartouche 5648Followed. This convention may be overridden by the use of the C_Pass_By_Copy 5649pragma, or Convention, or by explicitly specifying the mechanism for a given 5650call using an extended import or export pragma. 5651 5652@sp 1 5653@cartouche 5654An Ada parameter of an array type with component type @var{T}, of any 5655mode, is passed as a @code{@var{t}*} argument to a C function, where 5656@var{t} is the C type corresponding to the Ada type @var{T}. 5657@end cartouche 5658Followed. 5659 5660@sp 1 5661@cartouche 5662An Ada parameter of an access-to-subprogram type is passed as a pointer 5663to a C function whose prototype corresponds to the designated 5664subprogram's specification. 5665@end cartouche 5666Followed. 5667 5668@cindex COBOL, interfacing with 5669@unnumberedsec B.4(95-98): Interfacing with COBOL 5670@sp 1 5671@cartouche 5672An Ada implementation should support the following interface 5673correspondences between Ada and COBOL@. 5674@end cartouche 5675Followed. 5676 5677@sp 1 5678@cartouche 5679An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of 5680the COBOL type corresponding to @var{T}. 5681@end cartouche 5682Followed. 5683 5684@sp 1 5685@cartouche 5686An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of 5687the corresponding COBOL type. 5688@end cartouche 5689Followed. 5690 5691@sp 1 5692@cartouche 5693Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the 5694COBOL type corresponding to the Ada parameter type; for scalars, a local 5695copy is used if necessary to ensure by-copy semantics. 5696@end cartouche 5697Followed. 5698 5699@cindex Fortran, interfacing with 5700@unnumberedsec B.5(22-26): Interfacing with Fortran 5701@sp 1 5702@cartouche 5703An Ada implementation should support the following interface 5704correspondences between Ada and Fortran: 5705@end cartouche 5706Followed. 5707 5708@sp 1 5709@cartouche 5710An Ada procedure corresponds to a Fortran subroutine. 5711@end cartouche 5712Followed. 5713 5714@sp 1 5715@cartouche 5716An Ada function corresponds to a Fortran function. 5717@end cartouche 5718Followed. 5719 5720@sp 1 5721@cartouche 5722An Ada parameter of an elementary, array, or record type @var{T} is 5723passed as a @var{T} argument to a Fortran procedure, where @var{T} is 5724the Fortran type corresponding to the Ada type @var{T}, and where the 5725INTENT attribute of the corresponding dummy argument matches the Ada 5726formal parameter mode; the Fortran implementation's parameter passing 5727conventions are used. For elementary types, a local copy is used if 5728necessary to ensure by-copy semantics. 5729@end cartouche 5730Followed. 5731 5732@sp 1 5733@cartouche 5734An Ada parameter of an access-to-subprogram type is passed as a 5735reference to a Fortran procedure whose interface corresponds to the 5736designated subprogram's specification. 5737@end cartouche 5738Followed. 5739 5740@cindex Machine operations 5741@unnumberedsec C.1(3-5): Access to Machine Operations 5742@sp 1 5743@cartouche 5744The machine code or intrinsic support should allow access to all 5745operations normally available to assembly language programmers for the 5746target environment, including privileged instructions, if any. 5747@end cartouche 5748Followed. 5749 5750@sp 1 5751@cartouche 5752The interfacing pragmas (see Annex B) should support interface to 5753assembler; the default assembler should be associated with the 5754convention identifier @code{Assembler}. 5755@end cartouche 5756Followed. 5757 5758@sp 1 5759@cartouche 5760If an entity is exported to assembly language, then the implementation 5761should allocate it at an addressable location, and should ensure that it 5762is retained by the linking process, even if not otherwise referenced 5763from the Ada code. The implementation should assume that any call to a 5764machine code or assembler subprogram is allowed to read or update every 5765object that is specified as exported. 5766@end cartouche 5767Followed. 5768 5769@unnumberedsec C.1(10-16): Access to Machine Operations 5770@sp 1 5771@cartouche 5772The implementation should ensure that little or no overhead is 5773associated with calling intrinsic and machine-code subprograms. 5774@end cartouche 5775Followed for both intrinsics and machine-code subprograms. 5776 5777@sp 1 5778@cartouche 5779It is recommended that intrinsic subprograms be provided for convenient 5780access to any machine operations that provide special capabilities or 5781efficiency and that are not otherwise available through the language 5782constructs. 5783@end cartouche 5784Followed. A full set of machine operation intrinsic subprograms is provided. 5785 5786@sp 1 5787@cartouche 5788Atomic read-modify-write operations---e.g.@:, test and set, compare and 5789swap, decrement and test, enqueue/dequeue. 5790@end cartouche 5791Followed on any target supporting such operations. 5792 5793@sp 1 5794@cartouche 5795Standard numeric functions---e.g.@:, sin, log. 5796@end cartouche 5797Followed on any target supporting such operations. 5798 5799@sp 1 5800@cartouche 5801String manipulation operations---e.g.@:, translate and test. 5802@end cartouche 5803Followed on any target supporting such operations. 5804 5805@sp 1 5806@cartouche 5807Vector operations---e.g.@:, compare vector against thresholds. 5808@end cartouche 5809Followed on any target supporting such operations. 5810 5811@sp 1 5812@cartouche 5813Direct operations on I/O ports. 5814@end cartouche 5815Followed on any target supporting such operations. 5816 5817@cindex Interrupt support 5818@unnumberedsec C.3(28): Interrupt Support 5819@sp 1 5820@cartouche 5821If the @code{Ceiling_Locking} policy is not in effect, the 5822implementation should provide means for the application to specify which 5823interrupts are to be blocked during protected actions, if the underlying 5824system allows for a finer-grain control of interrupt blocking. 5825@end cartouche 5826Followed. The underlying system does not allow for finer-grain control 5827of interrupt blocking. 5828 5829@cindex Protected procedure handlers 5830@unnumberedsec C.3.1(20-21): Protected Procedure Handlers 5831@sp 1 5832@cartouche 5833Whenever possible, the implementation should allow interrupt handlers to 5834be called directly by the hardware. 5835@end cartouche 5836@c SGI info: 5837@ignore 5838This is never possible under IRIX, so this is followed by default. 5839@end ignore 5840Followed on any target where the underlying operating system permits 5841such direct calls. 5842 5843@sp 1 5844@cartouche 5845Whenever practical, violations of any 5846implementation-defined restrictions should be detected before run time. 5847@end cartouche 5848Followed. Compile time warnings are given when possible. 5849 5850@cindex Package @code{Interrupts} 5851@findex Interrupts 5852@unnumberedsec C.3.2(25): Package @code{Interrupts} 5853 5854@sp 1 5855@cartouche 5856If implementation-defined forms of interrupt handler procedures are 5857supported, such as protected procedures with parameters, then for each 5858such form of a handler, a type analogous to @code{Parameterless_Handler} 5859should be specified in a child package of @code{Interrupts}, with the 5860same operations as in the predefined package Interrupts. 5861@end cartouche 5862Followed. 5863 5864@cindex Pre-elaboration requirements 5865@unnumberedsec C.4(14): Pre-elaboration Requirements 5866@sp 1 5867@cartouche 5868It is recommended that pre-elaborated packages be implemented in such a 5869way that there should be little or no code executed at run time for the 5870elaboration of entities not already covered by the Implementation 5871Requirements. 5872@end cartouche 5873Followed. Executable code is generated in some cases, e.g.@: loops 5874to initialize large arrays. 5875 5876@unnumberedsec C.5(8): Pragma @code{Discard_Names} 5877 5878@sp 1 5879@cartouche 5880If the pragma applies to an entity, then the implementation should 5881reduce the amount of storage used for storing names associated with that 5882entity. 5883@end cartouche 5884Followed. 5885 5886@cindex Package @code{Task_Attributes} 5887@findex Task_Attributes 5888@unnumberedsec C.7.2(30): The Package Task_Attributes 5889@sp 1 5890@cartouche 5891Some implementations are targeted to domains in which memory use at run 5892time must be completely deterministic. For such implementations, it is 5893recommended that the storage for task attributes will be pre-allocated 5894statically and not from the heap. This can be accomplished by either 5895placing restrictions on the number and the size of the task's 5896attributes, or by using the pre-allocated storage for the first @var{N} 5897attribute objects, and the heap for the others. In the latter case, 5898@var{N} should be documented. 5899@end cartouche 5900Not followed. This implementation is not targeted to such a domain. 5901 5902@cindex Locking Policies 5903@unnumberedsec D.3(17): Locking Policies 5904 5905@sp 1 5906@cartouche 5907The implementation should use names that end with @samp{_Locking} for 5908locking policies defined by the implementation. 5909@end cartouche 5910Followed. A single implementation-defined locking policy is defined, 5911whose name (@code{Inheritance_Locking}) follows this suggestion. 5912 5913@cindex Entry queuing policies 5914@unnumberedsec D.4(16): Entry Queuing Policies 5915@sp 1 5916@cartouche 5917Names that end with @samp{_Queuing} should be used 5918for all implementation-defined queuing policies. 5919@end cartouche 5920Followed. No such implementation-defined queuing policies exist. 5921 5922@cindex Preemptive abort 5923@unnumberedsec D.6(9-10): Preemptive Abort 5924@sp 1 5925@cartouche 5926Even though the @code{abort_statement} is included in the list of 5927potentially blocking operations (see 9.5.1), it is recommended that this 5928statement be implemented in a way that never requires the task executing 5929the @code{abort_statement} to block. 5930@end cartouche 5931Followed. 5932 5933@sp 1 5934@cartouche 5935On a multi-processor, the delay associated with aborting a task on 5936another processor should be bounded; the implementation should use 5937periodic polling, if necessary, to achieve this. 5938@end cartouche 5939Followed. 5940 5941@cindex Tasking restrictions 5942@unnumberedsec D.7(21): Tasking Restrictions 5943@sp 1 5944@cartouche 5945When feasible, the implementation should take advantage of the specified 5946restrictions to produce a more efficient implementation. 5947@end cartouche 5948GNAT currently takes advantage of these restrictions by providing an optimized 5949run time when the Ravenscar profile and the GNAT restricted run time set 5950of restrictions are specified. See pragma @code{Ravenscar} and pragma 5951@code{Restricted_Run_Time} for more details. 5952 5953@cindex Time, monotonic 5954@unnumberedsec D.8(47-49): Monotonic Time 5955@sp 1 5956@cartouche 5957When appropriate, implementations should provide configuration 5958mechanisms to change the value of @code{Tick}. 5959@end cartouche 5960Such configuration mechanisms are not appropriate to this implementation 5961and are thus not supported. 5962 5963@sp 1 5964@cartouche 5965It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} 5966be implemented as transformations of the same time base. 5967@end cartouche 5968Followed. 5969 5970@sp 1 5971@cartouche 5972It is recommended that the @dfn{best} time base which exists in 5973the underlying system be available to the application through 5974@code{Clock}. @dfn{Best} may mean highest accuracy or largest range. 5975@end cartouche 5976Followed. 5977 5978@cindex Partition communication subsystem 5979@cindex PCS 5980@unnumberedsec E.5(28-29): Partition Communication Subsystem 5981@sp 1 5982@cartouche 5983Whenever possible, the PCS on the called partition should allow for 5984multiple tasks to call the RPC-receiver with different messages and 5985should allow them to block until the corresponding subprogram body 5986returns. 5987@end cartouche 5988Followed by GLADE, a separately supplied PCS that can be used with 5989GNAT. 5990 5991@sp 1 5992@cartouche 5993The @code{Write} operation on a stream of type @code{Params_Stream_Type} 5994should raise @code{Storage_Error} if it runs out of space trying to 5995write the @code{Item} into the stream. 5996@end cartouche 5997Followed by GLADE, a separately supplied PCS that can be used with 5998GNAT@. 5999 6000@cindex COBOL support 6001@unnumberedsec F(7): COBOL Support 6002@sp 1 6003@cartouche 6004If COBOL (respectively, C) is widely supported in the target 6005environment, implementations supporting the Information Systems Annex 6006should provide the child package @code{Interfaces.COBOL} (respectively, 6007@code{Interfaces.C}) specified in Annex B and should support a 6008@code{convention_identifier} of COBOL (respectively, C) in the interfacing 6009pragmas (see Annex B), thus allowing Ada programs to interface with 6010programs written in that language. 6011@end cartouche 6012Followed. 6013 6014@cindex Decimal radix support 6015@unnumberedsec F.1(2): Decimal Radix Support 6016@sp 1 6017@cartouche 6018Packed decimal should be used as the internal representation for objects 6019of subtype @var{S} when @var{S}'Machine_Radix = 10. 6020@end cartouche 6021Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary 6022representations. 6023 6024@cindex Numerics 6025@unnumberedsec G: Numerics 6026@sp 2 6027@cartouche 6028If Fortran (respectively, C) is widely supported in the target 6029environment, implementations supporting the Numerics Annex 6030should provide the child package @code{Interfaces.Fortran} (respectively, 6031@code{Interfaces.C}) specified in Annex B and should support a 6032@code{convention_identifier} of Fortran (respectively, C) in the interfacing 6033pragmas (see Annex B), thus allowing Ada programs to interface with 6034programs written in that language. 6035@end cartouche 6036Followed. 6037 6038@cindex Complex types 6039@unnumberedsec G.1.1(56-58): Complex Types 6040@sp 2 6041@cartouche 6042Because the usual mathematical meaning of multiplication of a complex 6043operand and a real operand is that of the scaling of both components of 6044the former by the latter, an implementation should not perform this 6045operation by first promoting the real operand to complex type and then 6046performing a full complex multiplication. In systems that, in the 6047future, support an Ada binding to IEC 559:1989, the latter technique 6048will not generate the required result when one of the components of the 6049complex operand is infinite. (Explicit multiplication of the infinite 6050component by the zero component obtained during promotion yields a NaN 6051that propagates into the final result.) Analogous advice applies in the 6052case of multiplication of a complex operand and a pure-imaginary 6053operand, and in the case of division of a complex operand by a real or 6054pure-imaginary operand. 6055@end cartouche 6056Not followed. 6057 6058@sp 1 6059@cartouche 6060Similarly, because the usual mathematical meaning of addition of a 6061complex operand and a real operand is that the imaginary operand remains 6062unchanged, an implementation should not perform this operation by first 6063promoting the real operand to complex type and then performing a full 6064complex addition. In implementations in which the @code{Signed_Zeros} 6065attribute of the component type is @code{True} (and which therefore 6066conform to IEC 559:1989 in regard to the handling of the sign of zero in 6067predefined arithmetic operations), the latter technique will not 6068generate the required result when the imaginary component of the complex 6069operand is a negatively signed zero. (Explicit addition of the negative 6070zero to the zero obtained during promotion yields a positive zero.) 6071Analogous advice applies in the case of addition of a complex operand 6072and a pure-imaginary operand, and in the case of subtraction of a 6073complex operand and a real or pure-imaginary operand. 6074@end cartouche 6075Not followed. 6076 6077@sp 1 6078@cartouche 6079Implementations in which @code{Real'Signed_Zeros} is @code{True} should 6080attempt to provide a rational treatment of the signs of zero results and 6081result components. As one example, the result of the @code{Argument} 6082function should have the sign of the imaginary component of the 6083parameter @code{X} when the point represented by that parameter lies on 6084the positive real axis; as another, the sign of the imaginary component 6085of the @code{Compose_From_Polar} function should be the same as 6086(respectively, the opposite of) that of the @code{Argument} parameter when that 6087parameter has a value of zero and the @code{Modulus} parameter has a 6088nonnegative (respectively, negative) value. 6089@end cartouche 6090Followed. 6091 6092@cindex Complex elementary functions 6093@unnumberedsec G.1.2(49): Complex Elementary Functions 6094@sp 1 6095@cartouche 6096Implementations in which @code{Complex_Types.Real'Signed_Zeros} is 6097@code{True} should attempt to provide a rational treatment of the signs 6098of zero results and result components. For example, many of the complex 6099elementary functions have components that are odd functions of one of 6100the parameter components; in these cases, the result component should 6101have the sign of the parameter component at the origin. Other complex 6102elementary functions have zero components whose sign is opposite that of 6103a parameter component at the origin, or is always positive or always 6104negative. 6105@end cartouche 6106Followed. 6107 6108@cindex Accuracy requirements 6109@unnumberedsec G.2.4(19): Accuracy Requirements 6110@sp 1 6111@cartouche 6112The versions of the forward trigonometric functions without a 6113@code{Cycle} parameter should not be implemented by calling the 6114corresponding version with a @code{Cycle} parameter of 6115@code{2.0*Numerics.Pi}, since this will not provide the required 6116accuracy in some portions of the domain. For the same reason, the 6117version of @code{Log} without a @code{Base} parameter should not be 6118implemented by calling the corresponding version with a @code{Base} 6119parameter of @code{Numerics.e}. 6120@end cartouche 6121Followed. 6122 6123@cindex Complex arithmetic accuracy 6124@cindex Accuracy, complex arithmetic 6125@unnumberedsec G.2.6(15): Complex Arithmetic Accuracy 6126 6127@sp 1 6128@cartouche 6129The version of the @code{Compose_From_Polar} function without a 6130@code{Cycle} parameter should not be implemented by calling the 6131corresponding version with a @code{Cycle} parameter of 6132@code{2.0*Numerics.Pi}, since this will not provide the required 6133accuracy in some portions of the domain. 6134@end cartouche 6135Followed. 6136 6137@c ----------------------------------------- 6138@node Implementation Defined Characteristics 6139@chapter Implementation Defined Characteristics 6140 6141@noindent 6142In addition to the implementation dependent pragmas and attributes, and 6143the implementation advice, there are a number of other features of Ada 614495 that are potentially implementation dependent. These are mentioned 6145throughout the Ada 95 Reference Manual, and are summarized in annex M@. 6146 6147A requirement for conforming Ada compilers is that they provide 6148documentation describing how the implementation deals with each of these 6149issues. In this chapter, you will find each point in annex M listed 6150followed by a description in italic font of how GNAT 6151@c SGI info: 6152@ignore 6153in the ProDev Ada 6154implementation on IRIX 5.3 operating system or greater 6155@end ignore 6156handles the implementation dependence. 6157 6158You can use this chapter as a guide to minimizing implementation 6159dependent features in your programs if portability to other compilers 6160and other operating systems is an important consideration. The numbers 6161in each section below correspond to the paragraph number in the Ada 95 6162Reference Manual. 6163 6164@sp 1 6165@cartouche 6166@noindent 6167@strong{2}. Whether or not each recommendation given in Implementation 6168Advice is followed. See 1.1.2(37). 6169@end cartouche 6170@noindent 6171@xref{Implementation Advice}. 6172 6173@sp 1 6174@cartouche 6175@noindent 6176@strong{3}. Capacity limitations of the implementation. See 1.1.3(3). 6177@end cartouche 6178@noindent 6179The complexity of programs that can be processed is limited only by the 6180total amount of available virtual memory, and disk space for the 6181generated object files. 6182 6183@sp 1 6184@cartouche 6185@noindent 6186@strong{4}. Variations from the standard that are impractical to avoid 6187given the implementation's execution environment. See 1.1.3(6). 6188@end cartouche 6189@noindent 6190There are no variations from the standard. 6191 6192@sp 1 6193@cartouche 6194@noindent 6195@strong{5}. Which @code{code_statement}s cause external 6196interactions. See 1.1.3(10). 6197@end cartouche 6198@noindent 6199Any @code{code_statement} can potentially cause external interactions. 6200 6201@sp 1 6202@cartouche 6203@noindent 6204@strong{6}. The coded representation for the text of an Ada 6205program. See 2.1(4). 6206@end cartouche 6207@noindent 6208See separate section on source representation. 6209 6210@sp 1 6211@cartouche 6212@noindent 6213@strong{7}. The control functions allowed in comments. See 2.1(14). 6214@end cartouche 6215@noindent 6216See separate section on source representation. 6217 6218@sp 1 6219@cartouche 6220@noindent 6221@strong{8}. The representation for an end of line. See 2.2(2). 6222@end cartouche 6223@noindent 6224See separate section on source representation. 6225 6226@sp 1 6227@cartouche 6228@noindent 6229@strong{9}. Maximum supported line length and lexical element 6230length. See 2.2(15). 6231@end cartouche 6232@noindent 6233The maximum line length is 255 characters an the maximum length of a 6234lexical element is also 255 characters. 6235 6236@sp 1 6237@cartouche 6238@noindent 6239@strong{10}. Implementation defined pragmas. See 2.8(14). 6240@end cartouche 6241@noindent 6242 6243@xref{Implementation Defined Pragmas}. 6244 6245@sp 1 6246@cartouche 6247@noindent 6248@strong{11}. Effect of pragma @code{Optimize}. See 2.8(27). 6249@end cartouche 6250@noindent 6251Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} 6252parameter, checks that the optimization flag is set, and aborts if it is 6253not. 6254 6255@sp 1 6256@cartouche 6257@noindent 6258@strong{12}. The sequence of characters of the value returned by 6259@code{@var{S}'Image} when some of the graphic characters of 6260@code{@var{S}'Wide_Image} are not defined in @code{Character}. See 62613.5(37). 6262@end cartouche 6263@noindent 6264The sequence of characters is as defined by the wide character encoding 6265method used for the source. See section on source representation for 6266further details. 6267 6268@sp 1 6269@cartouche 6270@noindent 6271@strong{13}. The predefined integer types declared in 6272@code{Standard}. See 3.5.4(25). 6273@end cartouche 6274@noindent 6275@table @code 6276@item Short_Short_Integer 62778 bit signed 6278@item Short_Integer 6279(Short) 16 bit signed 6280@item Integer 628132 bit signed 6282@item Long_Integer 628364 bit signed (Alpha OpenVMS only) 628432 bit signed (all other targets) 6285@item Long_Long_Integer 628664 bit signed 6287@end table 6288 6289@sp 1 6290@cartouche 6291@noindent 6292@strong{14}. Any nonstandard integer types and the operators defined 6293for them. See 3.5.4(26). 6294@end cartouche 6295@noindent 6296There are no nonstandard integer types. 6297 6298@sp 1 6299@cartouche 6300@noindent 6301@strong{15}. Any nonstandard real types and the operators defined for 6302them. See 3.5.6(8). 6303@end cartouche 6304@noindent 6305There are no nonstandard real types. 6306 6307@sp 1 6308@cartouche 6309@noindent 6310@strong{16}. What combinations of requested decimal precision and range 6311are supported for floating point types. See 3.5.7(7). 6312@end cartouche 6313@noindent 6314The precision and range is as defined by the IEEE standard. 6315 6316@sp 1 6317@cartouche 6318@noindent 6319@strong{17}. The predefined floating point types declared in 6320@code{Standard}. See 3.5.7(16). 6321@end cartouche 6322@noindent 6323@table @code 6324@item Short_Float 632532 bit IEEE short 6326@item Float 6327(Short) 32 bit IEEE short 6328@item Long_Float 632964 bit IEEE long 6330@item Long_Long_Float 633164 bit IEEE long (80 bit IEEE long on x86 processors) 6332@end table 6333 6334@sp 1 6335@cartouche 6336@noindent 6337@strong{18}. The small of an ordinary fixed point type. See 3.5.9(8). 6338@end cartouche 6339@noindent 6340@code{Fine_Delta} is 2**(@minus{}63) 6341 6342@sp 1 6343@cartouche 6344@noindent 6345@strong{19}. What combinations of small, range, and digits are 6346supported for fixed point types. See 3.5.9(10). 6347@end cartouche 6348@noindent 6349Any combinations are permitted that do not result in a small less than 6350@code{Fine_Delta} and do not result in a mantissa larger than 63 bits. 6351If the mantissa is larger than 53 bits on machines where Long_Long_Float 6352is 64 bits (true of all architectures except ia32), then the output from 6353Text_IO is accurate to only 53 bits, rather than the full mantissa. This 6354is because floating-point conversions are used to convert fixed point. 6355 6356@sp 1 6357@cartouche 6358@noindent 6359@strong{20}. The result of @code{Tags.Expanded_Name} for types declared 6360within an unnamed @code{block_statement}. See 3.9(10). 6361@end cartouche 6362@noindent 6363Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a 6364decimal integer are allocated. 6365 6366@sp 1 6367@cartouche 6368@noindent 6369@strong{21}. Implementation-defined attributes. See 4.1.4(12). 6370@end cartouche 6371@noindent 6372@xref{Implementation Defined Attributes}. 6373 6374@sp 1 6375@cartouche 6376@noindent 6377@strong{22}. Any implementation-defined time types. See 9.6(6). 6378@end cartouche 6379@noindent 6380There are no implementation-defined time types. 6381 6382@sp 1 6383@cartouche 6384@noindent 6385@strong{23}. The time base associated with relative delays. 6386@end cartouche 6387@noindent 6388See 9.6(20). The time base used is that provided by the C library 6389function @code{gettimeofday}. 6390 6391@sp 1 6392@cartouche 6393@noindent 6394@strong{24}. The time base of the type @code{Calendar.Time}. See 63959.6(23). 6396@end cartouche 6397@noindent 6398The time base used is that provided by the C library function 6399@code{gettimeofday}. 6400 6401@sp 1 6402@cartouche 6403@noindent 6404@strong{25}. The time zone used for package @code{Calendar} 6405operations. See 9.6(24). 6406@end cartouche 6407@noindent 6408The time zone used by package @code{Calendar} is the current system time zone 6409setting for local time, as accessed by the C library function 6410@code{localtime}. 6411 6412@sp 1 6413@cartouche 6414@noindent 6415@strong{26}. Any limit on @code{delay_until_statements} of 6416@code{select_statements}. See 9.6(29). 6417@end cartouche 6418@noindent 6419There are no such limits. 6420 6421@sp 1 6422@cartouche 6423@noindent 6424@strong{27}. Whether or not two non overlapping parts of a composite 6425object are independently addressable, in the case where packing, record 6426layout, or @code{Component_Size} is specified for the object. See 64279.10(1). 6428@end cartouche 6429@noindent 6430Separate components are independently addressable if they do not share 6431overlapping storage units. 6432 6433@sp 1 6434@cartouche 6435@noindent 6436@strong{28}. The representation for a compilation. See 10.1(2). 6437@end cartouche 6438@noindent 6439A compilation is represented by a sequence of files presented to the 6440compiler in a single invocation of the @code{gcc} command. 6441 6442@sp 1 6443@cartouche 6444@noindent 6445@strong{29}. Any restrictions on compilations that contain multiple 6446compilation_units. See 10.1(4). 6447@end cartouche 6448@noindent 6449No single file can contain more than one compilation unit, but any 6450sequence of files can be presented to the compiler as a single 6451compilation. 6452 6453@sp 1 6454@cartouche 6455@noindent 6456@strong{30}. The mechanisms for creating an environment and for adding 6457and replacing compilation units. See 10.1.4(3). 6458@end cartouche 6459@noindent 6460See separate section on compilation model. 6461 6462@sp 1 6463@cartouche 6464@noindent 6465@strong{31}. The manner of explicitly assigning library units to a 6466partition. See 10.2(2). 6467@end cartouche 6468@noindent 6469If a unit contains an Ada main program, then the Ada units for the partition 6470are determined by recursive application of the rules in the Ada Reference 6471Manual section 10.2(2-6). In other words, the Ada units will be those that 6472are needed by the main program, and then this definition of need is applied 6473recursively to those units, and the partition contains the transitive 6474closure determined by this relationship. In short, all the necessary units 6475are included, with no need to explicitly specify the list. If additional 6476units are required, e.g.@: by foreign language units, then all units must be 6477mentioned in the context clause of one of the needed Ada units. 6478 6479If the partition contains no main program, or if the main program is in 6480a language other than Ada, then GNAT 6481provides the binder options @code{-z} and @code{-n} respectively, and in 6482this case a list of units can be explicitly supplied to the binder for 6483inclusion in the partition (all units needed by these units will also 6484be included automatically). For full details on the use of these 6485options, refer to the @cite{GNAT User's Guide} sections on Binding 6486and Linking. 6487 6488@sp 1 6489@cartouche 6490@noindent 6491@strong{32}. The implementation-defined means, if any, of specifying 6492which compilation units are needed by a given compilation unit. See 649310.2(2). 6494@end cartouche 6495@noindent 6496The units needed by a given compilation unit are as defined in 6497the Ada Reference Manual section 10.2(2-6). There are no 6498implementation-defined pragmas or other implementation-defined 6499means for specifying needed units. 6500 6501@sp 1 6502@cartouche 6503@noindent 6504@strong{33}. The manner of designating the main subprogram of a 6505partition. See 10.2(7). 6506@end cartouche 6507@noindent 6508The main program is designated by providing the name of the 6509corresponding @file{ALI} file as the input parameter to the binder. 6510 6511@sp 1 6512@cartouche 6513@noindent 6514@strong{34}. The order of elaboration of @code{library_items}. See 651510.2(18). 6516@end cartouche 6517@noindent 6518The first constraint on ordering is that it meets the requirements of 6519chapter 10 of the Ada 95 Reference Manual. This still leaves some 6520implementation dependent choices, which are resolved by first 6521elaborating bodies as early as possible (i.e.@: in preference to specs 6522where there is a choice), and second by evaluating the immediate with 6523clauses of a unit to determine the probably best choice, and 6524third by elaborating in alphabetical order of unit names 6525where a choice still remains. 6526 6527@sp 1 6528@cartouche 6529@noindent 6530@strong{35}. Parameter passing and function return for the main 6531subprogram. See 10.2(21). 6532@end cartouche 6533@noindent 6534The main program has no parameters. It may be a procedure, or a function 6535returning an integer type. In the latter case, the returned integer 6536value is the return code of the program (overriding any value that 6537may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). 6538 6539@sp 1 6540@cartouche 6541@noindent 6542@strong{36}. The mechanisms for building and running partitions. See 654310.2(24). 6544@end cartouche 6545@noindent 6546GNAT itself supports programs with only a single partition. The GNATDIST 6547tool provided with the GLADE package (which also includes an implementation 6548of the PCS) provides a completely flexible method for building and running 6549programs consisting of multiple partitions. See the separate GLADE manual 6550for details. 6551 6552@sp 1 6553@cartouche 6554@noindent 6555@strong{37}. The details of program execution, including program 6556termination. See 10.2(25). 6557@end cartouche 6558@noindent 6559See separate section on compilation model. 6560 6561@sp 1 6562@cartouche 6563@noindent 6564@strong{38}. The semantics of any non-active partitions supported by the 6565implementation. See 10.2(28). 6566@end cartouche 6567@noindent 6568Passive partitions are supported on targets where shared memory is 6569provided by the operating system. See the GLADE reference manual for 6570further details. 6571 6572@sp 1 6573@cartouche 6574@noindent 6575@strong{39}. The information returned by @code{Exception_Message}. See 657611.4.1(10). 6577@end cartouche 6578@noindent 6579Exception message returns the null string unless a specific message has 6580been passed by the program. 6581 6582@sp 1 6583@cartouche 6584@noindent 6585@strong{40}. The result of @code{Exceptions.Exception_Name} for types 6586declared within an unnamed @code{block_statement}. See 11.4.1(12). 6587@end cartouche 6588@noindent 6589Blocks have implementation defined names of the form @code{B@var{nnn}} 6590where @var{nnn} is an integer. 6591 6592@sp 1 6593@cartouche 6594@noindent 6595@strong{41}. The information returned by 6596@code{Exception_Information}. See 11.4.1(13). 6597@end cartouche 6598@noindent 6599@code{Exception_Information} returns a string in the following format: 6600 6601@smallexample 6602@emph{Exception_Name:} nnnnn 6603@emph{Message:} mmmmm 6604@emph{PID:} ppp 6605@emph{Call stack traceback locations:} 66060xhhhh 0xhhhh 0xhhhh ... 0xhhh 6607@end smallexample 6608 6609@noindent 6610where 6611 6612@itemize @bullet 6613@item 6614@code{nnnn} is the fully qualified name of the exception in all upper 6615case letters. This line is always present. 6616 6617@item 6618@code{mmmm} is the message (this line present only if message is non-null) 6619 6620@item 6621@code{ppp} is the Process Id value as a decimal integer (this line is 6622present only if the Process Id is non-zero). Currently we are 6623not making use of this field. 6624 6625@item 6626The Call stack traceback locations line and the following values 6627are present only if at least one traceback location was recorded. 6628The values are given in C style format, with lower case letters 6629for a-f, and only as many digits present as are necessary. 6630@end itemize 6631 6632@noindent 6633The line terminator sequence at the end of each line, including 6634the last line is a single @code{LF} character (@code{16#0A#}). 6635 6636@sp 1 6637@cartouche 6638@noindent 6639@strong{42}. Implementation-defined check names. See 11.5(27). 6640@end cartouche 6641@noindent 6642No implementation-defined check names are supported. 6643 6644@sp 1 6645@cartouche 6646@noindent 6647@strong{43}. The interpretation of each aspect of representation. See 664813.1(20). 6649@end cartouche 6650@noindent 6651See separate section on data representations. 6652 6653@sp 1 6654@cartouche 6655@noindent 6656@strong{44}. Any restrictions placed upon representation items. See 665713.1(20). 6658@end cartouche 6659@noindent 6660See separate section on data representations. 6661 6662@sp 1 6663@cartouche 6664@noindent 6665@strong{45}. The meaning of @code{Size} for indefinite subtypes. See 666613.3(48). 6667@end cartouche 6668@noindent 6669Size for an indefinite subtype is the maximum possible size, except that 6670for the case of a subprogram parameter, the size of the parameter object 6671is the actual size. 6672 6673@sp 1 6674@cartouche 6675@noindent 6676@strong{46}. The default external representation for a type tag. See 667713.3(75). 6678@end cartouche 6679@noindent 6680The default external representation for a type tag is the fully expanded 6681name of the type in upper case letters. 6682 6683@sp 1 6684@cartouche 6685@noindent 6686@strong{47}. What determines whether a compilation unit is the same in 6687two different partitions. See 13.3(76). 6688@end cartouche 6689@noindent 6690A compilation unit is the same in two different partitions if and only 6691if it derives from the same source file. 6692 6693@sp 1 6694@cartouche 6695@noindent 6696@strong{48}. Implementation-defined components. See 13.5.1(15). 6697@end cartouche 6698@noindent 6699The only implementation defined component is the tag for a tagged type, 6700which contains a pointer to the dispatching table. 6701 6702@sp 1 6703@cartouche 6704@noindent 6705@strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit 6706ordering. See 13.5.3(5). 6707@end cartouche 6708@noindent 6709@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this 6710implementation, so no non-default bit ordering is supported. The default 6711bit ordering corresponds to the natural endianness of the target architecture. 6712 6713@sp 1 6714@cartouche 6715@noindent 6716@strong{50}. The contents of the visible part of package @code{System} 6717and its language-defined children. See 13.7(2). 6718@end cartouche 6719@noindent 6720See the definition of these packages in files @file{system.ads} and 6721@file{s-stoele.ads}. 6722 6723@sp 1 6724@cartouche 6725@noindent 6726@strong{51}. The contents of the visible part of package 6727@code{System.Machine_Code}, and the meaning of 6728@code{code_statements}. See 13.8(7). 6729@end cartouche 6730@noindent 6731See the definition and documentation in file @file{s-maccod.ads}. 6732 6733@sp 1 6734@cartouche 6735@noindent 6736@strong{52}. The effect of unchecked conversion. See 13.9(11). 6737@end cartouche 6738@noindent 6739Unchecked conversion between types of the same size 6740and results in an uninterpreted transmission of the bits from one type 6741to the other. If the types are of unequal sizes, then in the case of 6742discrete types, a shorter source is first zero or sign extended as 6743necessary, and a shorter target is simply truncated on the left. 6744For all non-discrete types, the source is first copied if necessary 6745to ensure that the alignment requirements of the target are met, then 6746a pointer is constructed to the source value, and the result is obtained 6747by dereferencing this pointer after converting it to be a pointer to the 6748target type. 6749 6750@sp 1 6751@cartouche 6752@noindent 6753@strong{53}. The manner of choosing a storage pool for an access type 6754when @code{Storage_Pool} is not specified for the type. See 13.11(17). 6755@end cartouche 6756@noindent 6757There are 3 different standard pools used by the compiler when 6758@code{Storage_Pool} is not specified depending whether the type is local 6759to a subprogram or defined at the library level and whether 6760@code{Storage_Size}is specified or not. See documentation in the runtime 6761library units @code{System.Pool_Global}, @code{System.Pool_Size} and 6762@code{System.Pool_Local} in files @file{s-poosiz.ads}, 6763@file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the 6764default pools used. 6765 6766@sp 1 6767@cartouche 6768@noindent 6769@strong{54}. Whether or not the implementation provides user-accessible 6770names for the standard pool type(s). See 13.11(17). 6771@end cartouche 6772@noindent 6773 6774See documentation in the sources of the run time mentioned in paragraph 6775@strong{53} . All these pools are accessible by means of @code{with}'ing 6776these units. 6777 6778@sp 1 6779@cartouche 6780@noindent 6781@strong{55}. The meaning of @code{Storage_Size}. See 13.11(18). 6782@end cartouche 6783@noindent 6784@code{Storage_Size} is measured in storage units, and refers to the 6785total space available for an access type collection, or to the primary 6786stack space for a task. 6787 6788@sp 1 6789@cartouche 6790@noindent 6791@strong{56}. Implementation-defined aspects of storage pools. See 679213.11(22). 6793@end cartouche 6794@noindent 6795See documentation in the sources of the run time mentioned in paragraph 6796@strong{53} for details on GNAT-defined aspects of storage pools. 6797 6798@sp 1 6799@cartouche 6800@noindent 6801@strong{57}. The set of restrictions allowed in a pragma 6802@code{Restrictions}. See 13.12(7). 6803@end cartouche 6804@noindent 6805All RM defined Restriction identifiers are implemented. The following 6806additional restriction identifiers are provided. There are two separate 6807lists of implementation dependent restriction identifiers. The first 6808set requires consistency throughout a partition (in other words, if the 6809restriction identifier is used for any compilation unit in the partition, 6810then all compilation units in the partition must obey the restriction. 6811 6812@table @code 6813 6814@item Boolean_Entry_Barriers 6815@findex Boolean_Entry_Barriers 6816This restriction ensures at compile time that barriers in entry declarations 6817for protected types are restricted to references to simple boolean variables 6818defined in the private part of the protected type. No other form of entry 6819barriers is permitted. This is one of the restrictions of the Ravenscar 6820profile for limited tasking (see also pragma @code{Ravenscar}). 6821 6822@item Max_Entry_Queue_Depth => Expr 6823@findex Max_Entry_Queue_Depth 6824This restriction is a declaration that any protected entry compiled in 6825the scope of the restriction has at most the specified number of 6826tasks waiting on the entry 6827at any one time, and so no queue is required. This restriction is not 6828checked at compile time. A program execution is erroneous if an attempt 6829is made to queue more than the specified number of tasks on such an entry. 6830 6831@item No_Calendar 6832@findex No_Calendar 6833This restriction ensures at compile time that there is no implicit or 6834explicit dependence on the package @code{Ada.Calendar}. 6835 6836@item No_Direct_Boolean_Operators 6837@findex No_Direct_Boolean_Operators 6838This restrcition ensures that no logical (and/or/xor) or comparison 6839operators are used on operands of type Boolean (or any type derived 6840from Boolean). This is intended for use in safety critical programs 6841where the certification protocol requires the use of short-circuit 6842(and then, or else) forms for all composite boolean operations. 6843 6844@item No_Dynamic_Interrupts 6845@findex No_Dynamic_Interrupts 6846This restriction ensures at compile time that there is no attempt to 6847dynamically associate interrupts. Only static association is allowed. 6848 6849@item No_Enumeration_Maps 6850@findex No_Enumeration_Maps 6851This restriction ensures at compile time that no operations requiring 6852enumeration maps are used (that is Image and Value attributes applied 6853to enumeration types). 6854 6855@item No_Entry_Calls_In_Elaboration_Code 6856@findex No_Entry_Calls_In_Elaboration_Code 6857This restriction ensures at compile time that no task or protected entry 6858calls are made during elaboration code. As a result of the use of this 6859restriction, the compiler can assume that no code past an accept statement 6860in a task can be executed at elaboration time. 6861 6862@item No_Exception_Handlers 6863@findex No_Exception_Handlers 6864This restriction ensures at compile time that there are no explicit 6865exception handlers. It also indicates that no exception propagation will 6866be provided. In this mode, exceptions may be raised but will result in 6867an immediate call to the last chance handler, a routine that the user 6868must define with the following profile: 6869 6870 procedure Last_Chance_Handler 6871 (Source_Location : System.Address; Line : Integer); 6872 pragma Export (C, Last_Chance_Handler, 6873 "__gnat_last_chance_handler"); 6874 6875 The parameter is a C null-terminated string representing a message to be 6876 associated with the exception (typically the source location of the raise 6877 statement generated by the compiler). The Line parameter when non-zero 6878 represents the line number in the source program where the raise occurs. 6879 6880@item No_Exception_Streams 6881@findex No_Exception_Streams 6882This restriction ensures at compile time that no stream operations for 6883types Exception_Id or Exception_Occurrence are used. This also makes it 6884impossible to pass exceptions to or from a partition with this restriction 6885in a distributed environment. If this exception is active, then the generated 6886code is simplified by omitting the otherwise-required global registration 6887of exceptions when they are declared. 6888 6889@item No_Implicit_Conditionals 6890@findex No_Implicit_Conditionals 6891This restriction ensures that the generated code does not contain any 6892implicit conditionals, either by modifying the generated code where possible, 6893or by rejecting any construct that would otherwise generate an implicit 6894conditional. 6895 6896@item No_Implicit_Dynamic_Code 6897@findex No_Implicit_Dynamic_Code 6898This restriction prevents the compiler from building ``trampolines''. 6899This is a structure that is built on the stack and contains dynamic 6900code to be executed at run time. A trampoline is needed to indirectly 6901address a nested subprogram (that is a subprogram that is not at the 6902library level). The restriction prevents the use of any of the 6903attributes @code{Address}, @code{Access} or @code{Unrestricted_Access} 6904being applied to a subprogram that is not at the library level. 6905 6906@item No_Implicit_Loops 6907@findex No_Implicit_Loops 6908This restriction ensures that the generated code does not contain any 6909implicit @code{for} loops, either by modifying 6910the generated code where possible, 6911or by rejecting any construct that would otherwise generate an implicit 6912@code{for} loop. 6913 6914@item No_Initialize_Scalars 6915@findex No_Initialize_Scalars 6916This restriction ensures that no unit in the partition is compiled with 6917pragma Initialize_Scalars. This allows the generation of more efficient 6918code, and in particular eliminates dummy null initialization routines that 6919are otherwise generated for some record and array types. 6920 6921@item No_Local_Protected_Objects 6922@findex No_Local_Protected_Objects 6923This restriction ensures at compile time that protected objects are 6924only declared at the library level. 6925 6926@item No_Protected_Type_Allocators 6927@findex No_Protected_Type_Allocators 6928This restriction ensures at compile time that there are no allocator 6929expressions that attempt to allocate protected objects. 6930 6931@item No_Secondary_Stack 6932@findex No_Secondary_Stack 6933This restriction ensures at compile time that the generated code does not 6934contain any reference to the secondary stack. The secondary stack is used 6935to implement functions returning unconstrained objects (arrays or records) 6936on some targets. 6937 6938@item No_Select_Statements 6939@findex No_Select_Statements 6940This restriction ensures at compile time no select statements of any kind 6941are permitted, that is the keyword @code{select} may not appear. 6942This is one of the restrictions of the Ravenscar 6943profile for limited tasking (see also pragma @code{Ravenscar}). 6944 6945@item No_Standard_Storage_Pools 6946@findex No_Standard_Storage_Pools 6947This restriction ensures at compile time that no access types 6948use the standard default storage pool. Any access type declared must 6949have an explicit Storage_Pool attribute defined specifying a 6950user-defined storage pool. 6951 6952@item No_Streams 6953@findex No_Streams 6954This restriction ensures at compile time that there are no implicit or 6955explicit dependencies on the package @code{Ada.Streams}. 6956 6957@item No_Task_Attributes 6958@findex No_Task_Attributes 6959This restriction ensures at compile time that there are no implicit or 6960explicit dependencies on the package @code{Ada.Task_Attributes}. 6961 6962@item No_Task_Termination 6963@findex No_Task_Termination 6964This restriction ensures at compile time that no terminate alternatives 6965appear in any task body. 6966 6967@item No_Tasking 6968@findex No_Tasking 6969This restriction prevents the declaration of tasks or task types throughout 6970the partition. It is similar in effect to the use of @code{Max_Tasks => 0} 6971except that violations are caught at compile time and cause an error message 6972to be output either by the compiler or binder. 6973 6974@item No_Wide_Characters 6975@findex No_Wide_Characters 6976This restriction ensures at compile time that no uses of the types 6977@code{Wide_Character} or @code{Wide_String} 6978appear, and that no wide character literals 6979appear in the program (that is literals representing characters not in 6980type @code{Character}. 6981 6982@item Static_Priorities 6983@findex Static_Priorities 6984This restriction ensures at compile time that all priority expressions 6985are static, and that there are no dependencies on the package 6986@code{Ada.Dynamic_Priorities}. 6987 6988@item Static_Storage_Size 6989@findex Static_Storage_Size 6990This restriction ensures at compile time that any expression appearing 6991in a Storage_Size pragma or attribute definition clause is static. 6992 6993@end table 6994 6995@noindent 6996The second set of implementation dependent restriction identifiers 6997does not require partition-wide consistency. 6998The restriction may be enforced for a single 6999compilation unit without any effect on any of the 7000other compilation units in the partition. 7001 7002@table @code 7003 7004@item No_Elaboration_Code 7005@findex No_Elaboration_Code 7006This restriction ensures at compile time that no elaboration code is 7007generated. Note that this is not the same condition as is enforced 7008by pragma @code{Preelaborate}. There are cases in which pragma 7009@code{Preelaborate} still permits code to be generated (e.g.@: code 7010to initialize a large array to all zeroes), and there are cases of units 7011which do not meet the requirements for pragma @code{Preelaborate}, 7012but for which no elaboration code is generated. Generally, it is 7013the case that preelaborable units will meet the restrictions, with 7014the exception of large aggregates initialized with an others_clause, 7015and exception declarations (which generate calls to a run-time 7016registry procedure). Note that this restriction is enforced on 7017a unit by unit basis, it need not be obeyed consistently 7018throughout a partition. 7019 7020@item No_Entry_Queue 7021@findex No_Entry_Queue 7022This restriction is a declaration that any protected entry compiled in 7023the scope of the restriction has at most one task waiting on the entry 7024at any one time, and so no queue is required. This restriction is not 7025checked at compile time. A program execution is erroneous if an attempt 7026is made to queue a second task on such an entry. 7027 7028@item No_Implementation_Attributes 7029@findex No_Implementation_Attributes 7030This restriction checks at compile time that no GNAT-defined attributes 7031are present. With this restriction, the only attributes that can be used 7032are those defined in the Ada 95 Reference Manual. 7033 7034@item No_Implementation_Pragmas 7035@findex No_Implementation_Pragmas 7036This restriction checks at compile time that no GNAT-defined pragmas 7037are present. With this restriction, the only pragmas that can be used 7038are those defined in the Ada 95 Reference Manual. 7039 7040@item No_Implementation_Restrictions 7041@findex No_Implementation_Restrictions 7042This restriction checks at compile time that no GNAT-defined restriction 7043identifiers (other than @code{No_Implementation_Restrictions} itself) 7044are present. With this restriction, the only other restriction identifiers 7045that can be used are those defined in the Ada 95 Reference Manual. 7046 7047@end table 7048 7049@sp 1 7050@cartouche 7051@noindent 7052@strong{58}. The consequences of violating limitations on 7053@code{Restrictions} pragmas. See 13.12(9). 7054@end cartouche 7055@noindent 7056Restrictions that can be checked at compile time result in illegalities 7057if violated. Currently there are no other consequences of violating 7058restrictions. 7059 7060@sp 1 7061@cartouche 7062@noindent 7063@strong{59}. The representation used by the @code{Read} and 7064@code{Write} attributes of elementary types in terms of stream 7065elements. See 13.13.2(9). 7066@end cartouche 7067@noindent 7068The representation is the in-memory representation of the base type of 7069the type, using the number of bits corresponding to the 7070@code{@var{type}'Size} value, and the natural ordering of the machine. 7071 7072@sp 1 7073@cartouche 7074@noindent 7075@strong{60}. The names and characteristics of the numeric subtypes 7076declared in the visible part of package @code{Standard}. See A.1(3). 7077@end cartouche 7078@noindent 7079See items describing the integer and floating-point types supported. 7080 7081@sp 1 7082@cartouche 7083@noindent 7084@strong{61}. The accuracy actually achieved by the elementary 7085functions. See A.5.1(1). 7086@end cartouche 7087@noindent 7088The elementary functions correspond to the functions available in the C 7089library. Only fast math mode is implemented. 7090 7091@sp 1 7092@cartouche 7093@noindent 7094@strong{62}. The sign of a zero result from some of the operators or 7095functions in @code{Numerics.Generic_Elementary_Functions}, when 7096@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46). 7097@end cartouche 7098@noindent 7099The sign of zeroes follows the requirements of the IEEE 754 standard on 7100floating-point. 7101 7102@sp 1 7103@cartouche 7104@noindent 7105@strong{63}. The value of 7106@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27). 7107@end cartouche 7108@noindent 7109Maximum image width is 649, see library file @file{a-numran.ads}. 7110 7111@sp 1 7112@cartouche 7113@noindent 7114@strong{64}. The value of 7115@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27). 7116@end cartouche 7117@noindent 7118Maximum image width is 80, see library file @file{a-nudira.ads}. 7119 7120@sp 1 7121@cartouche 7122@noindent 7123@strong{65}. The algorithms for random number generation. See 7124A.5.2(32). 7125@end cartouche 7126@noindent 7127The algorithm is documented in the source files @file{a-numran.ads} and 7128@file{a-numran.adb}. 7129 7130@sp 1 7131@cartouche 7132@noindent 7133@strong{66}. The string representation of a random number generator's 7134state. See A.5.2(38). 7135@end cartouche 7136@noindent 7137See the documentation contained in the file @file{a-numran.adb}. 7138 7139@sp 1 7140@cartouche 7141@noindent 7142@strong{67}. The minimum time interval between calls to the 7143time-dependent Reset procedure that are guaranteed to initiate different 7144random number sequences. See A.5.2(45). 7145@end cartouche 7146@noindent 7147The minimum period between reset calls to guarantee distinct series of 7148random numbers is one microsecond. 7149 7150@sp 1 7151@cartouche 7152@noindent 7153@strong{68}. The values of the @code{Model_Mantissa}, 7154@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, 7155@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics 7156Annex is not supported. See A.5.3(72). 7157@end cartouche 7158@noindent 7159See the source file @file{ttypef.ads} for the values of all numeric 7160attributes. 7161 7162@sp 1 7163@cartouche 7164@noindent 7165@strong{69}. Any implementation-defined characteristics of the 7166input-output packages. See A.7(14). 7167@end cartouche 7168@noindent 7169There are no special implementation defined characteristics for these 7170packages. 7171 7172@sp 1 7173@cartouche 7174@noindent 7175@strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See 7176A.9(10). 7177@end cartouche 7178@noindent 7179All type representations are contiguous, and the @code{Buffer_Size} is 7180the value of @code{@var{type}'Size} rounded up to the next storage unit 7181boundary. 7182 7183@sp 1 7184@cartouche 7185@noindent 7186@strong{71}. External files for standard input, standard output, and 7187standard error See A.10(5). 7188@end cartouche 7189@noindent 7190These files are mapped onto the files provided by the C streams 7191libraries. See source file @file{i-cstrea.ads} for further details. 7192 7193@sp 1 7194@cartouche 7195@noindent 7196@strong{72}. The accuracy of the value produced by @code{Put}. See 7197A.10.9(36). 7198@end cartouche 7199@noindent 7200If more digits are requested in the output than are represented by the 7201precision of the value, zeroes are output in the corresponding least 7202significant digit positions. 7203 7204@sp 1 7205@cartouche 7206@noindent 7207@strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and 7208@code{Command_Name}. See A.15(1). 7209@end cartouche 7210@noindent 7211These are mapped onto the @code{argv} and @code{argc} parameters of the 7212main program in the natural manner. 7213 7214@sp 1 7215@cartouche 7216@noindent 7217@strong{74}. Implementation-defined convention names. See B.1(11). 7218@end cartouche 7219@noindent 7220The following convention names are supported 7221 7222@table @code 7223@item Ada 7224Ada 7225@item Assembler 7226Assembly language 7227@item Asm 7228Synonym for Assembler 7229@item Assembly 7230Synonym for Assembler 7231@item C 7232C 7233@item C_Pass_By_Copy 7234Allowed only for record types, like C, but also notes that record 7235is to be passed by copy rather than reference. 7236@item COBOL 7237COBOL 7238@item CPP 7239C++ 7240@item Default 7241Treated the same as C 7242@item External 7243Treated the same as C 7244@item Fortran 7245Fortran 7246@item Intrinsic 7247For support of pragma @code{Import} with convention Intrinsic, see 7248separate section on Intrinsic Subprograms. 7249@item Stdcall 7250Stdcall (used for Windows implementations only). This convention correspond 7251to the WINAPI (previously called Pascal convention) C/C++ convention under 7252Windows. A function with this convention cleans the stack before exit. 7253@item DLL 7254Synonym for Stdcall 7255@item Win32 7256Synonym for Stdcall 7257@item Stubbed 7258Stubbed is a special convention used to indicate that the body of the 7259subprogram will be entirely ignored. Any call to the subprogram 7260is converted into a raise of the @code{Program_Error} exception. If a 7261pragma @code{Import} specifies convention @code{stubbed} then no body need 7262be present at all. This convention is useful during development for the 7263inclusion of subprograms whose body has not yet been written. 7264 7265@end table 7266@noindent 7267In addition, all otherwise unrecognized convention names are also 7268treated as being synonymous with convention C@. In all implementations 7269except for VMS, use of such other names results in a warning. In VMS 7270implementations, these names are accepted silently. 7271 7272@sp 1 7273@cartouche 7274@noindent 7275@strong{75}. The meaning of link names. See B.1(36). 7276@end cartouche 7277@noindent 7278Link names are the actual names used by the linker. 7279 7280@sp 1 7281@cartouche 7282@noindent 7283@strong{76}. The manner of choosing link names when neither the link 7284name nor the address of an imported or exported entity is specified. See 7285B.1(36). 7286@end cartouche 7287@noindent 7288The default linker name is that which would be assigned by the relevant 7289external language, interpreting the Ada name as being in all lower case 7290letters. 7291 7292@sp 1 7293@cartouche 7294@noindent 7295@strong{77}. The effect of pragma @code{Linker_Options}. See B.1(37). 7296@end cartouche 7297@noindent 7298The string passed to @code{Linker_Options} is presented uninterpreted as 7299an argument to the link command, unless it contains Ascii.NUL characters. 7300NUL characters if they appear act as argument separators, so for example 7301 7302@smallexample @c ada 7303pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef"); 7304@end smallexample 7305 7306@noindent 7307causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the 7308linker. The order of linker options is preserved for a given unit. The final 7309list of options passed to the linker is in reverse order of the elaboration 7310order. For example, linker options fo a body always appear before the options 7311from the corresponding package spec. 7312 7313@sp 1 7314@cartouche 7315@noindent 7316@strong{78}. The contents of the visible part of package 7317@code{Interfaces} and its language-defined descendants. See B.2(1). 7318@end cartouche 7319@noindent 7320See files with prefix @file{i-} in the distributed library. 7321 7322@sp 1 7323@cartouche 7324@noindent 7325@strong{79}. Implementation-defined children of package 7326@code{Interfaces}. The contents of the visible part of package 7327@code{Interfaces}. See B.2(11). 7328@end cartouche 7329@noindent 7330See files with prefix @file{i-} in the distributed library. 7331 7332@sp 1 7333@cartouche 7334@noindent 7335@strong{80}. The types @code{Floating}, @code{Long_Floating}, 7336@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and 7337@code{COBOL_Character}; and the initialization of the variables 7338@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in 7339@code{Interfaces.COBOL}. See B.4(50). 7340@end cartouche 7341@noindent 7342@table @code 7343@item Floating 7344Float 7345@item Long_Floating 7346(Floating) Long_Float 7347@item Binary 7348Integer 7349@item Long_Binary 7350Long_Long_Integer 7351@item Decimal_Element 7352Character 7353@item COBOL_Character 7354Character 7355@end table 7356 7357@noindent 7358For initialization, see the file @file{i-cobol.ads} in the distributed library. 7359 7360@sp 1 7361@cartouche 7362@noindent 7363@strong{81}. Support for access to machine instructions. See C.1(1). 7364@end cartouche 7365@noindent 7366See documentation in file @file{s-maccod.ads} in the distributed library. 7367 7368@sp 1 7369@cartouche 7370@noindent 7371@strong{82}. Implementation-defined aspects of access to machine 7372operations. See C.1(9). 7373@end cartouche 7374@noindent 7375See documentation in file @file{s-maccod.ads} in the distributed library. 7376 7377@sp 1 7378@cartouche 7379@noindent 7380@strong{83}. Implementation-defined aspects of interrupts. See C.3(2). 7381@end cartouche 7382@noindent 7383Interrupts are mapped to signals or conditions as appropriate. See 7384definition of unit 7385@code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details 7386on the interrupts supported on a particular target. 7387 7388@sp 1 7389@cartouche 7390@noindent 7391@strong{84}. Implementation-defined aspects of pre-elaboration. See 7392C.4(13). 7393@end cartouche 7394@noindent 7395GNAT does not permit a partition to be restarted without reloading, 7396except under control of the debugger. 7397 7398@sp 1 7399@cartouche 7400@noindent 7401@strong{85}. The semantics of pragma @code{Discard_Names}. See C.5(7). 7402@end cartouche 7403@noindent 7404Pragma @code{Discard_Names} causes names of enumeration literals to 7405be suppressed. In the presence of this pragma, the Image attribute 7406provides the image of the Pos of the literal, and Value accepts 7407Pos values. 7408 7409@sp 1 7410@cartouche 7411@noindent 7412@strong{86}. The result of the @code{Task_Identification.Image} 7413attribute. See C.7.1(7). 7414@end cartouche 7415@noindent 7416The result of this attribute is an 8-digit hexadecimal string 7417representing the virtual address of the task control block. 7418 7419@sp 1 7420@cartouche 7421@noindent 7422@strong{87}. The value of @code{Current_Task} when in a protected entry 7423or interrupt handler. See C.7.1(17). 7424@end cartouche 7425@noindent 7426Protected entries or interrupt handlers can be executed by any 7427convenient thread, so the value of @code{Current_Task} is undefined. 7428 7429@sp 1 7430@cartouche 7431@noindent 7432@strong{88}. The effect of calling @code{Current_Task} from an entry 7433body or interrupt handler. See C.7.1(19). 7434@end cartouche 7435@noindent 7436The effect of calling @code{Current_Task} from an entry body or 7437interrupt handler is to return the identification of the task currently 7438executing the code. 7439 7440@sp 1 7441@cartouche 7442@noindent 7443@strong{89}. Implementation-defined aspects of 7444@code{Task_Attributes}. See C.7.2(19). 7445@end cartouche 7446@noindent 7447There are no implementation-defined aspects of @code{Task_Attributes}. 7448 7449@sp 1 7450@cartouche 7451@noindent 7452@strong{90}. Values of all @code{Metrics}. See D(2). 7453@end cartouche 7454@noindent 7455The metrics information for GNAT depends on the performance of the 7456underlying operating system. The sources of the run-time for tasking 7457implementation, together with the output from @code{-gnatG} can be 7458used to determine the exact sequence of operating systems calls made 7459to implement various tasking constructs. Together with appropriate 7460information on the performance of the underlying operating system, 7461on the exact target in use, this information can be used to determine 7462the required metrics. 7463 7464@sp 1 7465@cartouche 7466@noindent 7467@strong{91}. The declarations of @code{Any_Priority} and 7468@code{Priority}. See D.1(11). 7469@end cartouche 7470@noindent 7471See declarations in file @file{system.ads}. 7472 7473@sp 1 7474@cartouche 7475@noindent 7476@strong{92}. Implementation-defined execution resources. See D.1(15). 7477@end cartouche 7478@noindent 7479There are no implementation-defined execution resources. 7480 7481@sp 1 7482@cartouche 7483@noindent 7484@strong{93}. Whether, on a multiprocessor, a task that is waiting for 7485access to a protected object keeps its processor busy. See D.2.1(3). 7486@end cartouche 7487@noindent 7488On a multi-processor, a task that is waiting for access to a protected 7489object does not keep its processor busy. 7490 7491@sp 1 7492@cartouche 7493@noindent 7494@strong{94}. The affect of implementation defined execution resources 7495on task dispatching. See D.2.1(9). 7496@end cartouche 7497@noindent 7498@c SGI info 7499@ignore 7500Tasks map to IRIX threads, and the dispatching policy is as defined by 7501the IRIX implementation of threads. 7502@end ignore 7503Tasks map to threads in the threads package used by GNAT@. Where possible 7504and appropriate, these threads correspond to native threads of the 7505underlying operating system. 7506 7507@sp 1 7508@cartouche 7509@noindent 7510@strong{95}. Implementation-defined @code{policy_identifiers} allowed 7511in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3). 7512@end cartouche 7513@noindent 7514There are no implementation-defined policy-identifiers allowed in this 7515pragma. 7516 7517@sp 1 7518@cartouche 7519@noindent 7520@strong{96}. Implementation-defined aspects of priority inversion. See 7521D.2.2(16). 7522@end cartouche 7523@noindent 7524Execution of a task cannot be preempted by the implementation processing 7525of delay expirations for lower priority tasks. 7526 7527@sp 1 7528@cartouche 7529@noindent 7530@strong{97}. Implementation defined task dispatching. See D.2.2(18). 7531@end cartouche 7532@noindent 7533@c SGI info: 7534@ignore 7535Tasks map to IRIX threads, and the dispatching policy is as defied by 7536the IRIX implementation of threads. 7537@end ignore 7538The policy is the same as that of the underlying threads implementation. 7539 7540@sp 1 7541@cartouche 7542@noindent 7543@strong{98}. Implementation-defined @code{policy_identifiers} allowed 7544in a pragma @code{Locking_Policy}. See D.3(4). 7545@end cartouche 7546@noindent 7547The only implementation defined policy permitted in GNAT is 7548@code{Inheritance_Locking}. On targets that support this policy, locking 7549is implemented by inheritance, i.e.@: the task owning the lock operates 7550at a priority equal to the highest priority of any task currently 7551requesting the lock. 7552 7553@sp 1 7554@cartouche 7555@noindent 7556@strong{99}. Default ceiling priorities. See D.3(10). 7557@end cartouche 7558@noindent 7559The ceiling priority of protected objects of the type 7560@code{System.Interrupt_Priority'Last} as described in the Ada 95 7561Reference Manual D.3(10), 7562 7563@sp 1 7564@cartouche 7565@noindent 7566@strong{100}. The ceiling of any protected object used internally by 7567the implementation. See D.3(16). 7568@end cartouche 7569@noindent 7570The ceiling priority of internal protected objects is 7571@code{System.Priority'Last}. 7572 7573@sp 1 7574@cartouche 7575@noindent 7576@strong{101}. Implementation-defined queuing policies. See D.4(1). 7577@end cartouche 7578@noindent 7579There are no implementation-defined queueing policies. 7580 7581@sp 1 7582@cartouche 7583@noindent 7584@strong{102}. On a multiprocessor, any conditions that cause the 7585completion of an aborted construct to be delayed later than what is 7586specified for a single processor. See D.6(3). 7587@end cartouche 7588@noindent 7589The semantics for abort on a multi-processor is the same as on a single 7590processor, there are no further delays. 7591 7592@sp 1 7593@cartouche 7594@noindent 7595@strong{103}. Any operations that implicitly require heap storage 7596allocation. See D.7(8). 7597@end cartouche 7598@noindent 7599The only operation that implicitly requires heap storage allocation is 7600task creation. 7601 7602@sp 1 7603@cartouche 7604@noindent 7605@strong{104}. Implementation-defined aspects of pragma 7606@code{Restrictions}. See D.7(20). 7607@end cartouche 7608@noindent 7609There are no such implementation-defined aspects. 7610 7611@sp 1 7612@cartouche 7613@noindent 7614@strong{105}. Implementation-defined aspects of package 7615@code{Real_Time}. See D.8(17). 7616@end cartouche 7617@noindent 7618There are no implementation defined aspects of package @code{Real_Time}. 7619 7620@sp 1 7621@cartouche 7622@noindent 7623@strong{106}. Implementation-defined aspects of 7624@code{delay_statements}. See D.9(8). 7625@end cartouche 7626@noindent 7627Any difference greater than one microsecond will cause the task to be 7628delayed (see D.9(7)). 7629 7630@sp 1 7631@cartouche 7632@noindent 7633@strong{107}. The upper bound on the duration of interrupt blocking 7634caused by the implementation. See D.12(5). 7635@end cartouche 7636@noindent 7637The upper bound is determined by the underlying operating system. In 7638no cases is it more than 10 milliseconds. 7639 7640@sp 1 7641@cartouche 7642@noindent 7643@strong{108}. The means for creating and executing distributed 7644programs. See E(5). 7645@end cartouche 7646@noindent 7647The GLADE package provides a utility GNATDIST for creating and executing 7648distributed programs. See the GLADE reference manual for further details. 7649 7650@sp 1 7651@cartouche 7652@noindent 7653@strong{109}. Any events that can result in a partition becoming 7654inaccessible. See E.1(7). 7655@end cartouche 7656@noindent 7657See the GLADE reference manual for full details on such events. 7658 7659@sp 1 7660@cartouche 7661@noindent 7662@strong{110}. The scheduling policies, treatment of priorities, and 7663management of shared resources between partitions in certain cases. See 7664E.1(11). 7665@end cartouche 7666@noindent 7667See the GLADE reference manual for full details on these aspects of 7668multi-partition execution. 7669 7670@sp 1 7671@cartouche 7672@noindent 7673@strong{111}. Events that cause the version of a compilation unit to 7674change. See E.3(5). 7675@end cartouche 7676@noindent 7677Editing the source file of a compilation unit, or the source files of 7678any units on which it is dependent in a significant way cause the version 7679to change. No other actions cause the version number to change. All changes 7680are significant except those which affect only layout, capitalization or 7681comments. 7682 7683@sp 1 7684@cartouche 7685@noindent 7686@strong{112}. Whether the execution of the remote subprogram is 7687immediately aborted as a result of cancellation. See E.4(13). 7688@end cartouche 7689@noindent 7690See the GLADE reference manual for details on the effect of abort in 7691a distributed application. 7692 7693@sp 1 7694@cartouche 7695@noindent 7696@strong{113}. Implementation-defined aspects of the PCS@. See E.5(25). 7697@end cartouche 7698@noindent 7699See the GLADE reference manual for a full description of all implementation 7700defined aspects of the PCS@. 7701 7702@sp 1 7703@cartouche 7704@noindent 7705@strong{114}. Implementation-defined interfaces in the PCS@. See 7706E.5(26). 7707@end cartouche 7708@noindent 7709See the GLADE reference manual for a full description of all 7710implementation defined interfaces. 7711 7712@sp 1 7713@cartouche 7714@noindent 7715@strong{115}. The values of named numbers in the package 7716@code{Decimal}. See F.2(7). 7717@end cartouche 7718@noindent 7719@table @code 7720@item Max_Scale 7721+18 7722@item Min_Scale 7723-18 7724@item Min_Delta 77251.0E-18 7726@item Max_Delta 77271.0E+18 7728@item Max_Decimal_Digits 772918 7730@end table 7731 7732@sp 1 7733@cartouche 7734@noindent 7735@strong{116}. The value of @code{Max_Picture_Length} in the package 7736@code{Text_IO.Editing}. See F.3.3(16). 7737@end cartouche 7738@noindent 773964 7740 7741@sp 1 7742@cartouche 7743@noindent 7744@strong{117}. The value of @code{Max_Picture_Length} in the package 7745@code{Wide_Text_IO.Editing}. See F.3.4(5). 7746@end cartouche 7747@noindent 774864 7749 7750@sp 1 7751@cartouche 7752@noindent 7753@strong{118}. The accuracy actually achieved by the complex elementary 7754functions and by other complex arithmetic operations. See G.1(1). 7755@end cartouche 7756@noindent 7757Standard library functions are used for the complex arithmetic 7758operations. Only fast math mode is currently supported. 7759 7760@sp 1 7761@cartouche 7762@noindent 7763@strong{119}. The sign of a zero result (or a component thereof) from 7764any operator or function in @code{Numerics.Generic_Complex_Types}, when 7765@code{Real'Signed_Zeros} is True. See G.1.1(53). 7766@end cartouche 7767@noindent 7768The signs of zero values are as recommended by the relevant 7769implementation advice. 7770 7771@sp 1 7772@cartouche 7773@noindent 7774@strong{120}. The sign of a zero result (or a component thereof) from 7775any operator or function in 7776@code{Numerics.Generic_Complex_Elementary_Functions}, when 7777@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45). 7778@end cartouche 7779@noindent 7780The signs of zero values are as recommended by the relevant 7781implementation advice. 7782 7783@sp 1 7784@cartouche 7785@noindent 7786@strong{121}. Whether the strict mode or the relaxed mode is the 7787default. See G.2(2). 7788@end cartouche 7789@noindent 7790The strict mode is the default. There is no separate relaxed mode. GNAT 7791provides a highly efficient implementation of strict mode. 7792 7793@sp 1 7794@cartouche 7795@noindent 7796@strong{122}. The result interval in certain cases of fixed-to-float 7797conversion. See G.2.1(10). 7798@end cartouche 7799@noindent 7800For cases where the result interval is implementation dependent, the 7801accuracy is that provided by performing all operations in 64-bit IEEE 7802floating-point format. 7803 7804@sp 1 7805@cartouche 7806@noindent 7807@strong{123}. The result of a floating point arithmetic operation in 7808overflow situations, when the @code{Machine_Overflows} attribute of the 7809result type is @code{False}. See G.2.1(13). 7810@end cartouche 7811@noindent 7812Infinite and Nan values are produced as dictated by the IEEE 7813floating-point standard. 7814 7815@sp 1 7816@cartouche 7817@noindent 7818@strong{124}. The result interval for division (or exponentiation by a 7819negative exponent), when the floating point hardware implements division 7820as multiplication by a reciprocal. See G.2.1(16). 7821@end cartouche 7822@noindent 7823Not relevant, division is IEEE exact. 7824 7825@sp 1 7826@cartouche 7827@noindent 7828@strong{125}. The definition of close result set, which determines the 7829accuracy of certain fixed point multiplications and divisions. See 7830G.2.3(5). 7831@end cartouche 7832@noindent 7833Operations in the close result set are performed using IEEE long format 7834floating-point arithmetic. The input operands are converted to 7835floating-point, the operation is done in floating-point, and the result 7836is converted to the target type. 7837 7838@sp 1 7839@cartouche 7840@noindent 7841@strong{126}. Conditions on a @code{universal_real} operand of a fixed 7842point multiplication or division for which the result shall be in the 7843perfect result set. See G.2.3(22). 7844@end cartouche 7845@noindent 7846The result is only defined to be in the perfect result set if the result 7847can be computed by a single scaling operation involving a scale factor 7848representable in 64-bits. 7849 7850@sp 1 7851@cartouche 7852@noindent 7853@strong{127}. The result of a fixed point arithmetic operation in 7854overflow situations, when the @code{Machine_Overflows} attribute of the 7855result type is @code{False}. See G.2.3(27). 7856@end cartouche 7857@noindent 7858Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point 7859types. 7860 7861@sp 1 7862@cartouche 7863@noindent 7864@strong{128}. The result of an elementary function reference in 7865overflow situations, when the @code{Machine_Overflows} attribute of the 7866result type is @code{False}. See G.2.4(4). 7867@end cartouche 7868@noindent 7869IEEE infinite and Nan values are produced as appropriate. 7870 7871@sp 1 7872@cartouche 7873@noindent 7874@strong{129}. The value of the angle threshold, within which certain 7875elementary functions, complex arithmetic operations, and complex 7876elementary functions yield results conforming to a maximum relative 7877error bound. See G.2.4(10). 7878@end cartouche 7879@noindent 7880Information on this subject is not yet available. 7881 7882@sp 1 7883@cartouche 7884@noindent 7885@strong{130}. The accuracy of certain elementary functions for 7886parameters beyond the angle threshold. See G.2.4(10). 7887@end cartouche 7888@noindent 7889Information on this subject is not yet available. 7890 7891@sp 1 7892@cartouche 7893@noindent 7894@strong{131}. The result of a complex arithmetic operation or complex 7895elementary function reference in overflow situations, when the 7896@code{Machine_Overflows} attribute of the corresponding real type is 7897@code{False}. See G.2.6(5). 7898@end cartouche 7899@noindent 7900IEEE infinite and Nan values are produced as appropriate. 7901 7902@sp 1 7903@cartouche 7904@noindent 7905@strong{132}. The accuracy of certain complex arithmetic operations and 7906certain complex elementary functions for parameters (or components 7907thereof) beyond the angle threshold. See G.2.6(8). 7908@end cartouche 7909@noindent 7910Information on those subjects is not yet available. 7911 7912@sp 1 7913@cartouche 7914@noindent 7915@strong{133}. Information regarding bounded errors and erroneous 7916execution. See H.2(1). 7917@end cartouche 7918@noindent 7919Information on this subject is not yet available. 7920 7921@sp 1 7922@cartouche 7923@noindent 7924@strong{134}. Implementation-defined aspects of pragma 7925@code{Inspection_Point}. See H.3.2(8). 7926@end cartouche 7927@noindent 7928Pragma @code{Inspection_Point} ensures that the variable is live and can 7929be examined by the debugger at the inspection point. 7930 7931@sp 1 7932@cartouche 7933@noindent 7934@strong{135}. Implementation-defined aspects of pragma 7935@code{Restrictions}. See H.4(25). 7936@end cartouche 7937@noindent 7938There are no implementation-defined aspects of pragma @code{Restrictions}. The 7939use of pragma @code{Restrictions [No_Exceptions]} has no effect on the 7940generated code. Checks must suppressed by use of pragma @code{Suppress}. 7941 7942@sp 1 7943@cartouche 7944@noindent 7945@strong{136}. Any restrictions on pragma @code{Restrictions}. See 7946H.4(27). 7947@end cartouche 7948@noindent 7949There are no restrictions on pragma @code{Restrictions}. 7950 7951@node Intrinsic Subprograms 7952@chapter Intrinsic Subprograms 7953@cindex Intrinsic Subprograms 7954 7955@menu 7956* Intrinsic Operators:: 7957* Enclosing_Entity:: 7958* Exception_Information:: 7959* Exception_Message:: 7960* Exception_Name:: 7961* File:: 7962* Line:: 7963* Rotate_Left:: 7964* Rotate_Right:: 7965* Shift_Left:: 7966* Shift_Right:: 7967* Shift_Right_Arithmetic:: 7968* Source_Location:: 7969@end menu 7970 7971@noindent 7972GNAT allows a user application program to write the declaration: 7973 7974@smallexample @c ada 7975 pragma Import (Intrinsic, name); 7976@end smallexample 7977 7978@noindent 7979providing that the name corresponds to one of the implemented intrinsic 7980subprograms in GNAT, and that the parameter profile of the referenced 7981subprogram meets the requirements. This chapter describes the set of 7982implemented intrinsic subprograms, and the requirements on parameter profiles. 7983Note that no body is supplied; as with other uses of pragma Import, the 7984body is supplied elsewhere (in this case by the compiler itself). Note 7985that any use of this feature is potentially non-portable, since the 7986Ada standard does not require Ada compilers to implement this feature. 7987 7988@node Intrinsic Operators 7989@section Intrinsic Operators 7990@cindex Intrinsic operator 7991 7992@noindent 7993All the predefined numeric operators in package Standard 7994in @code{pragma Import (Intrinsic,..)} 7995declarations. In the binary operator case, the operands must have the same 7996size. The operand or operands must also be appropriate for 7997the operator. For example, for addition, the operands must 7998both be floating-point or both be fixed-point, and the 7999right operand for @code{"**"} must have a root type of 8000@code{Standard.Integer'Base}. 8001You can use an intrinsic operator declaration as in the following example: 8002 8003@smallexample @c ada 8004 type Int1 is new Integer; 8005 type Int2 is new Integer; 8006 8007 function "+" (X1 : Int1; X2 : Int2) return Int1; 8008 function "+" (X1 : Int1; X2 : Int2) return Int2; 8009 pragma Import (Intrinsic, "+"); 8010@end smallexample 8011 8012@noindent 8013This declaration would permit ``mixed mode'' arithmetic on items 8014of the differing types @code{Int1} and @code{Int2}. 8015It is also possible to specify such operators for private types, if the 8016full views are appropriate arithmetic types. 8017 8018@node Enclosing_Entity 8019@section Enclosing_Entity 8020@cindex Enclosing_Entity 8021@noindent 8022This intrinsic subprogram is used in the implementation of the 8023library routine @code{GNAT.Source_Info}. The only useful use of the 8024intrinsic import in this case is the one in this unit, so an 8025application program should simply call the function 8026@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of 8027the current subprogram, package, task, entry, or protected subprogram. 8028 8029@node Exception_Information 8030@section Exception_Information 8031@cindex Exception_Information' 8032@noindent 8033This intrinsic subprogram is used in the implementation of the 8034library routine @code{GNAT.Current_Exception}. The only useful 8035use of the intrinsic import in this case is the one in this unit, 8036so an application program should simply call the function 8037@code{GNAT.Current_Exception.Exception_Information} to obtain 8038the exception information associated with the current exception. 8039 8040@node Exception_Message 8041@section Exception_Message 8042@cindex Exception_Message 8043@noindent 8044This intrinsic subprogram is used in the implementation of the 8045library routine @code{GNAT.Current_Exception}. The only useful 8046use of the intrinsic import in this case is the one in this unit, 8047so an application program should simply call the function 8048@code{GNAT.Current_Exception.Exception_Message} to obtain 8049the message associated with the current exception. 8050 8051@node Exception_Name 8052@section Exception_Name 8053@cindex Exception_Name 8054@noindent 8055This intrinsic subprogram is used in the implementation of the 8056library routine @code{GNAT.Current_Exception}. The only useful 8057use of the intrinsic import in this case is the one in this unit, 8058so an application program should simply call the function 8059@code{GNAT.Current_Exception.Exception_Name} to obtain 8060the name of the current exception. 8061 8062@node File 8063@section File 8064@cindex File 8065@noindent 8066This intrinsic subprogram is used in the implementation of the 8067library routine @code{GNAT.Source_Info}. The only useful use of the 8068intrinsic import in this case is the one in this unit, so an 8069application program should simply call the function 8070@code{GNAT.Source_Info.File} to obtain the name of the current 8071file. 8072 8073@node Line 8074@section Line 8075@cindex Line 8076@noindent 8077This intrinsic subprogram is used in the implementation of the 8078library routine @code{GNAT.Source_Info}. The only useful use of the 8079intrinsic import in this case is the one in this unit, so an 8080application program should simply call the function 8081@code{GNAT.Source_Info.Line} to obtain the number of the current 8082source line. 8083 8084@node Rotate_Left 8085@section Rotate_Left 8086@cindex Rotate_Left 8087@noindent 8088In standard Ada 95, the @code{Rotate_Left} function is available only 8089for the predefined modular types in package @code{Interfaces}. However, in 8090GNAT it is possible to define a Rotate_Left function for a user 8091defined modular type or any signed integer type as in this example: 8092 8093@smallexample @c ada 8094 function Shift_Left 8095 (Value : My_Modular_Type; 8096 Amount : Natural) 8097 return My_Modular_Type; 8098@end smallexample 8099 8100@noindent 8101The requirements are that the profile be exactly as in the example 8102above. The only modifications allowed are in the formal parameter 8103names, and in the type of @code{Value} and the return type, which 8104must be the same, and must be either a signed integer type, or 8105a modular integer type with a binary modulus, and the size must 8106be 8. 16, 32 or 64 bits. 8107 8108@node Rotate_Right 8109@section Rotate_Right 8110@cindex Rotate_Right 8111@noindent 8112A @code{Rotate_Right} function can be defined for any user defined 8113binary modular integer type, or signed integer type, as described 8114above for @code{Rotate_Left}. 8115 8116@node Shift_Left 8117@section Shift_Left 8118@cindex Shift_Left 8119@noindent 8120A @code{Shift_Left} function can be defined for any user defined 8121binary modular integer type, or signed integer type, as described 8122above for @code{Rotate_Left}. 8123 8124@node Shift_Right 8125@section Shift_Right 8126@cindex Shift_Right 8127@noindent 8128A @code{Shift_Right} function can be defined for any user defined 8129binary modular integer type, or signed integer type, as described 8130above for @code{Rotate_Left}. 8131 8132@node Shift_Right_Arithmetic 8133@section Shift_Right_Arithmetic 8134@cindex Shift_Right_Arithmetic 8135@noindent 8136A @code{Shift_Right_Arithmetic} function can be defined for any user 8137defined binary modular integer type, or signed integer type, as described 8138above for @code{Rotate_Left}. 8139 8140@node Source_Location 8141@section Source_Location 8142@cindex Source_Location 8143@noindent 8144This intrinsic subprogram is used in the implementation of the 8145library routine @code{GNAT.Source_Info}. The only useful use of the 8146intrinsic import in this case is the one in this unit, so an 8147application program should simply call the function 8148@code{GNAT.Source_Info.Source_Location} to obtain the current 8149source file location. 8150 8151@node Representation Clauses and Pragmas 8152@chapter Representation Clauses and Pragmas 8153@cindex Representation Clauses 8154 8155@menu 8156* Alignment Clauses:: 8157* Size Clauses:: 8158* Storage_Size Clauses:: 8159* Size of Variant Record Objects:: 8160* Biased Representation :: 8161* Value_Size and Object_Size Clauses:: 8162* Component_Size Clauses:: 8163* Bit_Order Clauses:: 8164* Effect of Bit_Order on Byte Ordering:: 8165* Pragma Pack for Arrays:: 8166* Pragma Pack for Records:: 8167* Record Representation Clauses:: 8168* Enumeration Clauses:: 8169* Address Clauses:: 8170* Effect of Convention on Representation:: 8171* Determining the Representations chosen by GNAT:: 8172@end menu 8173 8174@noindent 8175@cindex Representation Clause 8176@cindex Representation Pragma 8177@cindex Pragma, representation 8178This section describes the representation clauses accepted by GNAT, and 8179their effect on the representation of corresponding data objects. 8180 8181GNAT fully implements Annex C (Systems Programming). This means that all 8182the implementation advice sections in chapter 13 are fully implemented. 8183However, these sections only require a minimal level of support for 8184representation clauses. GNAT provides much more extensive capabilities, 8185and this section describes the additional capabilities provided. 8186 8187@node Alignment Clauses 8188@section Alignment Clauses 8189@cindex Alignment Clause 8190 8191@noindent 8192GNAT requires that all alignment clauses specify a power of 2, and all 8193default alignments are always a power of 2. The default alignment 8194values are as follows: 8195 8196@itemize @bullet 8197@item @emph{Primitive Types}. 8198For primitive types, the alignment is the minimum of the actual size of 8199objects of the type divided by @code{Storage_Unit}, 8200and the maximum alignment supported by the target. 8201(This maximum alignment is given by the GNAT-specific attribute 8202@code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.) 8203@cindex @code{Maximum_Alignment} attribute 8204For example, for type @code{Long_Float}, the object size is 8 bytes, and the 8205default alignment will be 8 on any target that supports alignments 8206this large, but on some targets, the maximum alignment may be smaller 8207than 8, in which case objects of type @code{Long_Float} will be maximally 8208aligned. 8209 8210@item @emph{Arrays}. 8211For arrays, the alignment is equal to the alignment of the component type 8212for the normal case where no packing or component size is given. If the 8213array is packed, and the packing is effective (see separate section on 8214packed arrays), then the alignment will be one for long packed arrays, 8215or arrays whose length is not known at compile time. For short packed 8216arrays, which are handled internally as modular types, the alignment 8217will be as described for primitive types, e.g.@: a packed array of length 821831 bits will have an object size of four bytes, and an alignment of 4. 8219 8220@item @emph{Records}. 8221For the normal non-packed case, the alignment of a record is equal to 8222the maximum alignment of any of its components. For tagged records, this 8223includes the implicit access type used for the tag. If a pragma @code{Pack} is 8224used and all fields are packable (see separate section on pragma @code{Pack}), 8225then the resulting alignment is 1. 8226 8227A special case is when: 8228@itemize @bullet 8229@item 8230the size of the record is given explicitly, or a 8231full record representation clause is given, and 8232@item 8233the size of the record is 2, 4, or 8 bytes. 8234@end itemize 8235@noindent 8236In this case, an alignment is chosen to match the 8237size of the record. For example, if we have: 8238 8239@smallexample @c ada 8240 type Small is record 8241 A, B : Character; 8242 end record; 8243 for Small'Size use 16; 8244@end smallexample 8245 8246@noindent 8247then the default alignment of the record type @code{Small} is 2, not 1. This 8248leads to more efficient code when the record is treated as a unit, and also 8249allows the type to specified as @code{Atomic} on architectures requiring 8250strict alignment. 8251 8252@end itemize 8253 8254@noindent 8255An alignment clause may 8256always specify a larger alignment than the default value, up to some 8257maximum value dependent on the target (obtainable by using the 8258attribute reference @code{Standard'Maximum_Alignment}). 8259The only case where 8260it is permissible to specify a smaller alignment than the default value 8261is for a record with a record representation clause. 8262In this case, packable fields for which a component clause is 8263given still result in a default alignment corresponding to the original 8264type, but this may be overridden, since these components in fact only 8265require an alignment of one byte. For example, given 8266 8267@smallexample @c ada 8268 type V is record 8269 A : Integer; 8270 end record; 8271 8272 for V use record 8273 A at 0 range 0 .. 31; 8274 end record; 8275 8276 for V'alignment use 1; 8277@end smallexample 8278 8279@noindent 8280@cindex Alignment, default 8281The default alignment for the type @code{V} is 4, as a result of the 8282Integer field in the record, but since this field is placed with a 8283component clause, it is permissible, as shown, to override the default 8284alignment of the record with a smaller value. 8285 8286@node Size Clauses 8287@section Size Clauses 8288@cindex Size Clause 8289 8290@noindent 8291The default size for a type @code{T} is obtainable through the 8292language-defined attribute @code{T'Size} and also through the 8293equivalent GNAT-defined attribute @code{T'Value_Size}. 8294For objects of type @code{T}, GNAT will generally increase the type size 8295so that the object size (obtainable through the GNAT-defined attribute 8296@code{T'Object_Size}) 8297is a multiple of @code{T'Alignment * Storage_Unit}. 8298For example 8299 8300@smallexample @c ada 8301 type Smallint is range 1 .. 6; 8302 8303 type Rec is record 8304 Y1 : integer; 8305 Y2 : boolean; 8306 end record; 8307@end smallexample 8308 8309@noindent 8310In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, 8311as specified by the RM rules, 8312but objects of this type will have a size of 8 8313(@code{Smallint'Object_Size} = 8), 8314since objects by default occupy an integral number 8315of storage units. On some targets, notably older 8316versions of the Digital Alpha, the size of stand 8317alone objects of this type may be 32, reflecting 8318the inability of the hardware to do byte load/stores. 8319 8320Similarly, the size of type @code{Rec} is 40 bits 8321(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but 8322the alignment is 4, so objects of this type will have 8323their size increased to 64 bits so that it is a multiple 8324of the alignment (in bits). The reason for this decision, which is 8325in accordance with the specific Implementation Advice in RM 13.3(43): 8326 8327@quotation 8328A @code{Size} clause should be supported for an object if the specified 8329@code{Size} is at least as large as its subtype's @code{Size}, and corresponds 8330to a size in storage elements that is a multiple of the object's 8331@code{Alignment} (if the @code{Alignment} is nonzero). 8332@end quotation 8333 8334@noindent 8335An explicit size clause may be used to override the default size by 8336increasing it. For example, if we have: 8337 8338@smallexample @c ada 8339 type My_Boolean is new Boolean; 8340 for My_Boolean'Size use 32; 8341@end smallexample 8342 8343@noindent 8344then values of this type will always be 32 bits long. In the case of 8345discrete types, the size can be increased up to 64 bits, with the effect 8346that the entire specified field is used to hold the value, sign- or 8347zero-extended as appropriate. If more than 64 bits is specified, then 8348padding space is allocated after the value, and a warning is issued that 8349there are unused bits. 8350 8351Similarly the size of records and arrays may be increased, and the effect 8352is to add padding bits after the value. This also causes a warning message 8353to be generated. 8354 8355The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a 8356Size in bits, this corresponds to an object of size 256 megabytes (minus 8357one). This limitation is true on all targets. The reason for this 8358limitation is that it improves the quality of the code in many cases 8359if it is known that a Size value can be accommodated in an object of 8360type Integer. 8361 8362@node Storage_Size Clauses 8363@section Storage_Size Clauses 8364@cindex Storage_Size Clause 8365 8366@noindent 8367For tasks, the @code{Storage_Size} clause specifies the amount of space 8368to be allocated for the task stack. This cannot be extended, and if the 8369stack is exhausted, then @code{Storage_Error} will be raised (if stack 8370checking is enabled). If the default size of 20K bytes is insufficient, 8371then you need to use a @code{Storage_Size} attribute definition clause, 8372or a @code{Storage_Size} pragma in the task definition to set the 8373appropriate required size. A useful technique is to include in every 8374task definition a pragma of the form: 8375 8376@smallexample @c ada 8377 pragma Storage_Size (Default_Stack_Size); 8378@end smallexample 8379 8380@noindent 8381Then @code{Default_Stack_Size} can be defined in a global package, and 8382modified as required. Any tasks requiring stack sizes different from the 8383default can have an appropriate alternative reference in the pragma. 8384 8385For access types, the @code{Storage_Size} clause specifies the maximum 8386space available for allocation of objects of the type. If this space is 8387exceeded then @code{Storage_Error} will be raised by an allocation attempt. 8388In the case where the access type is declared local to a subprogram, the 8389use of a @code{Storage_Size} clause triggers automatic use of a special 8390predefined storage pool (@code{System.Pool_Size}) that ensures that all 8391space for the pool is automatically reclaimed on exit from the scope in 8392which the type is declared. 8393 8394A special case recognized by the compiler is the specification of a 8395@code{Storage_Size} of zero for an access type. This means that no 8396items can be allocated from the pool, and this is recognized at compile 8397time, and all the overhead normally associated with maintaining a fixed 8398size storage pool is eliminated. Consider the following example: 8399 8400@smallexample @c ada 8401 procedure p is 8402 type R is array (Natural) of Character; 8403 type P is access all R; 8404 for P'Storage_Size use 0; 8405 -- Above access type intended only for interfacing purposes 8406 8407 y : P; 8408 8409 procedure g (m : P); 8410 pragma Import (C, g); 8411 8412 -- @dots{} 8413 8414 begin 8415 -- @dots{} 8416 y := new R; 8417 end; 8418@end smallexample 8419 8420@noindent 8421As indicated in this example, these dummy storage pools are often useful in 8422connection with interfacing where no object will ever be allocated. If you 8423compile the above example, you get the warning: 8424 8425@smallexample 8426 p.adb:16:09: warning: allocation from empty storage pool 8427 p.adb:16:09: warning: Storage_Error will be raised at run time 8428@end smallexample 8429 8430@noindent 8431Of course in practice, there will not be any explicit allocators in the 8432case of such an access declaration. 8433 8434@node Size of Variant Record Objects 8435@section Size of Variant Record Objects 8436@cindex Size, variant record objects 8437@cindex Variant record objects, size 8438 8439@noindent 8440In the case of variant record objects, there is a question whether Size gives 8441information about a particular variant, or the maximum size required 8442for any variant. Consider the following program 8443 8444@smallexample @c ada 8445with Text_IO; use Text_IO; 8446procedure q is 8447 type R1 (A : Boolean := False) is record 8448 case A is 8449 when True => X : Character; 8450 when False => null; 8451 end case; 8452 end record; 8453 8454 V1 : R1 (False); 8455 V2 : R1; 8456 8457begin 8458 Put_Line (Integer'Image (V1'Size)); 8459 Put_Line (Integer'Image (V2'Size)); 8460end q; 8461@end smallexample 8462 8463@noindent 8464Here we are dealing with a variant record, where the True variant 8465requires 16 bits, and the False variant requires 8 bits. 8466In the above example, both V1 and V2 contain the False variant, 8467which is only 8 bits long. However, the result of running the 8468program is: 8469 8470@smallexample 84718 847216 8473@end smallexample 8474 8475@noindent 8476The reason for the difference here is that the discriminant value of 8477V1 is fixed, and will always be False. It is not possible to assign 8478a True variant value to V1, therefore 8 bits is sufficient. On the 8479other hand, in the case of V2, the initial discriminant value is 8480False (from the default), but it is possible to assign a True 8481variant value to V2, therefore 16 bits must be allocated for V2 8482in the general case, even fewer bits may be needed at any particular 8483point during the program execution. 8484 8485As can be seen from the output of this program, the @code{'Size} 8486attribute applied to such an object in GNAT gives the actual allocated 8487size of the variable, which is the largest size of any of the variants. 8488The Ada Reference Manual is not completely clear on what choice should 8489be made here, but the GNAT behavior seems most consistent with the 8490language in the RM@. 8491 8492In some cases, it may be desirable to obtain the size of the current 8493variant, rather than the size of the largest variant. This can be 8494achieved in GNAT by making use of the fact that in the case of a 8495subprogram parameter, GNAT does indeed return the size of the current 8496variant (because a subprogram has no way of knowing how much space 8497is actually allocated for the actual). 8498 8499Consider the following modified version of the above program: 8500 8501@smallexample @c ada 8502with Text_IO; use Text_IO; 8503procedure q is 8504 type R1 (A : Boolean := False) is record 8505 case A is 8506 when True => X : Character; 8507 when False => null; 8508 end case; 8509 end record; 8510 8511 V2 : R1; 8512 8513 function Size (V : R1) return Integer is 8514 begin 8515 return V'Size; 8516 end Size; 8517 8518begin 8519 Put_Line (Integer'Image (V2'Size)); 8520 Put_Line (Integer'IMage (Size (V2))); 8521 V2 := (True, 'x'); 8522 Put_Line (Integer'Image (V2'Size)); 8523 Put_Line (Integer'IMage (Size (V2))); 8524end q; 8525@end smallexample 8526 8527@noindent 8528The output from this program is 8529 8530@smallexample 853116 85328 853316 853416 8535@end smallexample 8536 8537@noindent 8538Here we see that while the @code{'Size} attribute always returns 8539the maximum size, regardless of the current variant value, the 8540@code{Size} function does indeed return the size of the current 8541variant value. 8542 8543@node Biased Representation 8544@section Biased Representation 8545@cindex Size for biased representation 8546@cindex Biased representation 8547 8548@noindent 8549In the case of scalars with a range starting at other than zero, it is 8550possible in some cases to specify a size smaller than the default minimum 8551value, and in such cases, GNAT uses an unsigned biased representation, 8552in which zero is used to represent the lower bound, and successive values 8553represent successive values of the type. 8554 8555For example, suppose we have the declaration: 8556 8557@smallexample @c ada 8558 type Small is range -7 .. -4; 8559 for Small'Size use 2; 8560@end smallexample 8561 8562@noindent 8563Although the default size of type @code{Small} is 4, the @code{Size} 8564clause is accepted by GNAT and results in the following representation 8565scheme: 8566 8567@smallexample 8568 -7 is represented as 2#00# 8569 -6 is represented as 2#01# 8570 -5 is represented as 2#10# 8571 -4 is represented as 2#11# 8572@end smallexample 8573 8574@noindent 8575Biased representation is only used if the specified @code{Size} clause 8576cannot be accepted in any other manner. These reduced sizes that force 8577biased representation can be used for all discrete types except for 8578enumeration types for which a representation clause is given. 8579 8580@node Value_Size and Object_Size Clauses 8581@section Value_Size and Object_Size Clauses 8582@findex Value_Size 8583@findex Object_Size 8584@cindex Size, of objects 8585 8586@noindent 8587In Ada 95, @code{T'Size} for a type @code{T} is the minimum number of bits 8588required to hold values of type @code{T}. Although this interpretation was 8589allowed in Ada 83, it was not required, and this requirement in practice 8590can cause some significant difficulties. For example, in most Ada 83 8591compilers, @code{Natural'Size} was 32. However, in Ada 95, 8592@code{Natural'Size} is 8593typically 31. This means that code may change in behavior when moving 8594from Ada 83 to Ada 95. For example, consider: 8595 8596@smallexample @c ada 8597 type Rec is record; 8598 A : Natural; 8599 B : Natural; 8600 end record; 8601 8602 for Rec use record 8603 at 0 range 0 .. Natural'Size - 1; 8604 at 0 range Natural'Size .. 2 * Natural'Size - 1; 8605 end record; 8606@end smallexample 8607 8608@noindent 8609In the above code, since the typical size of @code{Natural} objects 8610is 32 bits and @code{Natural'Size} is 31, the above code can cause 8611unexpected inefficient packing in Ada 95, and in general there are 8612cases where the fact that the object size can exceed the 8613size of the type causes surprises. 8614 8615To help get around this problem GNAT provides two implementation 8616defined attributes, @code{Value_Size} and @code{Object_Size}. When 8617applied to a type, these attributes yield the size of the type 8618(corresponding to the RM defined size attribute), and the size of 8619objects of the type respectively. 8620 8621The @code{Object_Size} is used for determining the default size of 8622objects and components. This size value can be referred to using the 8623@code{Object_Size} attribute. The phrase ``is used'' here means that it is 8624the basis of the determination of the size. The backend is free to 8625pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone 8626character might be stored in 32 bits on a machine with no efficient 8627byte access instructions such as the Alpha. 8628 8629The default rules for the value of @code{Object_Size} for 8630discrete types are as follows: 8631 8632@itemize @bullet 8633@item 8634The @code{Object_Size} for base subtypes reflect the natural hardware 8635size in bits (run the utility @code{gnatpsta} to find those values for 8636numeric types). Enumeration types and fixed-point base subtypes have 86378, 16, 32 or 64 bits for this size, depending on the range of values 8638to be stored. 8639 8640@item 8641The @code{Object_Size} of a subtype is the same as the 8642@code{Object_Size} of 8643the type from which it is obtained. 8644 8645@item 8646The @code{Object_Size} of a derived base type is copied from the parent 8647base type, and the @code{Object_Size} of a derived first subtype is copied 8648from the parent first subtype. 8649@end itemize 8650 8651@noindent 8652The @code{Value_Size} attribute 8653is the (minimum) number of bits required to store a value 8654of the type. 8655This value is used to determine how tightly to pack 8656records or arrays with components of this type, and also affects 8657the semantics of unchecked conversion (unchecked conversions where 8658the @code{Value_Size} values differ generate a warning, and are potentially 8659target dependent). 8660 8661The default rules for the value of @code{Value_Size} are as follows: 8662 8663@itemize @bullet 8664@item 8665The @code{Value_Size} for a base subtype is the minimum number of bits 8666required to store all values of the type (including the sign bit 8667only if negative values are possible). 8668 8669@item 8670If a subtype statically matches the first subtype of a given type, then it has 8671by default the same @code{Value_Size} as the first subtype. This is a 8672consequence of RM 13.1(14) (``if two subtypes statically match, 8673then their subtype-specific aspects are the same''.) 8674 8675@item 8676All other subtypes have a @code{Value_Size} corresponding to the minimum 8677number of bits required to store all values of the subtype. For 8678dynamic bounds, it is assumed that the value can range down or up 8679to the corresponding bound of the ancestor 8680@end itemize 8681 8682@noindent 8683The RM defined attribute @code{Size} corresponds to the 8684@code{Value_Size} attribute. 8685 8686The @code{Size} attribute may be defined for a first-named subtype. This sets 8687the @code{Value_Size} of 8688the first-named subtype to the given value, and the 8689@code{Object_Size} of this first-named subtype to the given value padded up 8690to an appropriate boundary. It is a consequence of the default rules 8691above that this @code{Object_Size} will apply to all further subtypes. On the 8692other hand, @code{Value_Size} is affected only for the first subtype, any 8693dynamic subtypes obtained from it directly, and any statically matching 8694subtypes. The @code{Value_Size} of any other static subtypes is not affected. 8695 8696@code{Value_Size} and 8697@code{Object_Size} may be explicitly set for any subtype using 8698an attribute definition clause. Note that the use of these attributes 8699can cause the RM 13.1(14) rule to be violated. If two access types 8700reference aliased objects whose subtypes have differing @code{Object_Size} 8701values as a result of explicit attribute definition clauses, then it 8702is erroneous to convert from one access subtype to the other. 8703 8704At the implementation level, Esize stores the Object_Size and the 8705RM_Size field stores the @code{Value_Size} (and hence the value of the 8706@code{Size} attribute, 8707which, as noted above, is equivalent to @code{Value_Size}). 8708 8709To get a feel for the difference, consider the following examples (note 8710that in each case the base is @code{Short_Short_Integer} with a size of 8): 8711 8712@smallexample 8713 Object_Size Value_Size 8714 8715type x1 is range 0 .. 5; 8 3 8716 8717type x2 is range 0 .. 5; 8718for x2'size use 12; 16 12 8719 8720subtype x3 is x2 range 0 .. 3; 16 2 8721 8722subtype x4 is x2'base range 0 .. 10; 8 4 8723 8724subtype x5 is x2 range 0 .. dynamic; 16 3* 8725 8726subtype x6 is x2'base range 0 .. dynamic; 8 3* 8727 8728@end smallexample 8729 8730@noindent 8731Note: the entries marked ``3*'' are not actually specified by the Ada 95 RM, 8732but it seems in the spirit of the RM rules to allocate the minimum number 8733of bits (here 3, given the range for @code{x2}) 8734known to be large enough to hold the given range of values. 8735 8736So far, so good, but GNAT has to obey the RM rules, so the question is 8737under what conditions must the RM @code{Size} be used. 8738The following is a list 8739of the occasions on which the RM @code{Size} must be used: 8740 8741@itemize @bullet 8742@item 8743Component size for packed arrays or records 8744 8745@item 8746Value of the attribute @code{Size} for a type 8747 8748@item 8749Warning about sizes not matching for unchecked conversion 8750@end itemize 8751 8752@noindent 8753For record types, the @code{Object_Size} is always a multiple of the 8754alignment of the type (this is true for all types). In some cases the 8755@code{Value_Size} can be smaller. Consider: 8756 8757@smallexample 8758 type R is record 8759 X : Integer; 8760 Y : Character; 8761 end record; 8762@end smallexample 8763 8764@noindent 8765On a typical 32-bit architecture, the X component will be four bytes, and 8766require four-byte alignment, and the Y component will be one byte. In this 8767case @code{R'Value_Size} will be 40 (bits) since this is the minimum size 8768required to store a value of this type, and for example, it is permissible 8769to have a component of type R in an outer record whose component size is 8770specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits), 8771since it must be rounded up so that this value is a multiple of the 8772alignment (4 bytes = 32 bits). 8773 8774@noindent 8775For all other types, the @code{Object_Size} 8776and Value_Size are the same (and equivalent to the RM attribute @code{Size}). 8777Only @code{Size} may be specified for such types. 8778 8779@node Component_Size Clauses 8780@section Component_Size Clauses 8781@cindex Component_Size Clause 8782 8783@noindent 8784Normally, the value specified in a component clause must be consistent 8785with the subtype of the array component with regard to size and alignment. 8786In other words, the value specified must be at least equal to the size 8787of this subtype, and must be a multiple of the alignment value. 8788 8789In addition, component size clauses are allowed which cause the array 8790to be packed, by specifying a smaller value. The cases in which this 8791is allowed are for component size values in the range 1 through 63. The value 8792specified must not be smaller than the Size of the subtype. GNAT will 8793accurately honor all packing requests in this range. For example, if 8794we have: 8795 8796@smallexample @c ada 8797type r is array (1 .. 8) of Natural; 8798for r'Component_Size use 31; 8799@end smallexample 8800 8801@noindent 8802then the resulting array has a length of 31 bytes (248 bits = 8 * 31). 8803Of course access to the components of such an array is considerably 8804less efficient than if the natural component size of 32 is used. 8805 8806@node Bit_Order Clauses 8807@section Bit_Order Clauses 8808@cindex Bit_Order Clause 8809@cindex bit ordering 8810@cindex ordering, of bits 8811 8812@noindent 8813For record subtypes, GNAT permits the specification of the @code{Bit_Order} 8814attribute. The specification may either correspond to the default bit 8815order for the target, in which case the specification has no effect and 8816places no additional restrictions, or it may be for the non-standard 8817setting (that is the opposite of the default). 8818 8819In the case where the non-standard value is specified, the effect is 8820to renumber bits within each byte, but the ordering of bytes is not 8821affected. There are certain 8822restrictions placed on component clauses as follows: 8823 8824@itemize @bullet 8825 8826@item Components fitting within a single storage unit. 8827@noindent 8828These are unrestricted, and the effect is merely to renumber bits. For 8829example if we are on a little-endian machine with @code{Low_Order_First} 8830being the default, then the following two declarations have exactly 8831the same effect: 8832 8833@smallexample @c ada 8834 type R1 is record 8835 A : Boolean; 8836 B : Integer range 1 .. 120; 8837 end record; 8838 8839 for R1 use record 8840 A at 0 range 0 .. 0; 8841 B at 0 range 1 .. 7; 8842 end record; 8843 8844 type R2 is record 8845 A : Boolean; 8846 B : Integer range 1 .. 120; 8847 end record; 8848 8849 for R2'Bit_Order use High_Order_First; 8850 8851 for R2 use record 8852 A at 0 range 7 .. 7; 8853 B at 0 range 0 .. 6; 8854 end record; 8855@end smallexample 8856 8857@noindent 8858The useful application here is to write the second declaration with the 8859@code{Bit_Order} attribute definition clause, and know that it will be treated 8860the same, regardless of whether the target is little-endian or big-endian. 8861 8862@item Components occupying an integral number of bytes. 8863@noindent 8864These are components that exactly fit in two or more bytes. Such component 8865declarations are allowed, but have no effect, since it is important to realize 8866that the @code{Bit_Order} specification does not affect the ordering of bytes. 8867In particular, the following attempt at getting an endian-independent integer 8868does not work: 8869 8870@smallexample @c ada 8871 type R2 is record 8872 A : Integer; 8873 end record; 8874 8875 for R2'Bit_Order use High_Order_First; 8876 8877 for R2 use record 8878 A at 0 range 0 .. 31; 8879 end record; 8880@end smallexample 8881 8882@noindent 8883This declaration will result in a little-endian integer on a 8884little-endian machine, and a big-endian integer on a big-endian machine. 8885If byte flipping is required for interoperability between big- and 8886little-endian machines, this must be explicitly programmed. This capability 8887is not provided by @code{Bit_Order}. 8888 8889@item Components that are positioned across byte boundaries 8890@noindent 8891but do not occupy an integral number of bytes. Given that bytes are not 8892reordered, such fields would occupy a non-contiguous sequence of bits 8893in memory, requiring non-trivial code to reassemble. They are for this 8894reason not permitted, and any component clause specifying such a layout 8895will be flagged as illegal by GNAT@. 8896 8897@end itemize 8898 8899@noindent 8900Since the misconception that Bit_Order automatically deals with all 8901endian-related incompatibilities is a common one, the specification of 8902a component field that is an integral number of bytes will always 8903generate a warning. This warning may be suppressed using 8904@code{pragma Suppress} if desired. The following section contains additional 8905details regarding the issue of byte ordering. 8906 8907@node Effect of Bit_Order on Byte Ordering 8908@section Effect of Bit_Order on Byte Ordering 8909@cindex byte ordering 8910@cindex ordering, of bytes 8911 8912@noindent 8913In this section we will review the effect of the @code{Bit_Order} attribute 8914definition clause on byte ordering. Briefly, it has no effect at all, but 8915a detailed example will be helpful. Before giving this 8916example, let us review the precise 8917definition of the effect of defining @code{Bit_Order}. The effect of a 8918non-standard bit order is described in section 15.5.3 of the Ada 8919Reference Manual: 8920 8921@quotation 89222 A bit ordering is a method of interpreting the meaning of 8923the storage place attributes. 8924@end quotation 8925 8926@noindent 8927To understand the precise definition of storage place attributes in 8928this context, we visit section 13.5.1 of the manual: 8929 8930@quotation 893113 A record_representation_clause (without the mod_clause) 8932specifies the layout. The storage place attributes (see 13.5.2) 8933are taken from the values of the position, first_bit, and last_bit 8934expressions after normalizing those values so that first_bit is 8935less than Storage_Unit. 8936@end quotation 8937 8938@noindent 8939The critical point here is that storage places are taken from 8940the values after normalization, not before. So the @code{Bit_Order} 8941interpretation applies to normalized values. The interpretation 8942is described in the later part of the 15.5.3 paragraph: 8943 8944@quotation 89452 A bit ordering is a method of interpreting the meaning of 8946the storage place attributes. High_Order_First (known in the 8947vernacular as ``big endian'') means that the first bit of a 8948storage element (bit 0) is the most significant bit (interpreting 8949the sequence of bits that represent a component as an unsigned 8950integer value). Low_Order_First (known in the vernacular as 8951``little endian'') means the opposite: the first bit is the 8952least significant. 8953@end quotation 8954 8955@noindent 8956Note that the numbering is with respect to the bits of a storage 8957unit. In other words, the specification affects only the numbering 8958of bits within a single storage unit. 8959 8960We can make the effect clearer by giving an example. 8961 8962Suppose that we have an external device which presents two bytes, the first 8963byte presented, which is the first (low addressed byte) of the two byte 8964record is called Master, and the second byte is called Slave. 8965 8966The left most (most significant bit is called Control for each byte, and 8967the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost 8968(least significant) bit. 8969 8970On a big-endian machine, we can write the following representation clause 8971 8972@smallexample @c ada 8973 type Data is record 8974 Master_Control : Bit; 8975 Master_V1 : Bit; 8976 Master_V2 : Bit; 8977 Master_V3 : Bit; 8978 Master_V4 : Bit; 8979 Master_V5 : Bit; 8980 Master_V6 : Bit; 8981 Master_V7 : Bit; 8982 Slave_Control : Bit; 8983 Slave_V1 : Bit; 8984 Slave_V2 : Bit; 8985 Slave_V3 : Bit; 8986 Slave_V4 : Bit; 8987 Slave_V5 : Bit; 8988 Slave_V6 : Bit; 8989 Slave_V7 : Bit; 8990 end record; 8991 8992 for Data use record 8993 Master_Control at 0 range 0 .. 0; 8994 Master_V1 at 0 range 1 .. 1; 8995 Master_V2 at 0 range 2 .. 2; 8996 Master_V3 at 0 range 3 .. 3; 8997 Master_V4 at 0 range 4 .. 4; 8998 Master_V5 at 0 range 5 .. 5; 8999 Master_V6 at 0 range 6 .. 6; 9000 Master_V7 at 0 range 7 .. 7; 9001 Slave_Control at 1 range 0 .. 0; 9002 Slave_V1 at 1 range 1 .. 1; 9003 Slave_V2 at 1 range 2 .. 2; 9004 Slave_V3 at 1 range 3 .. 3; 9005 Slave_V4 at 1 range 4 .. 4; 9006 Slave_V5 at 1 range 5 .. 5; 9007 Slave_V6 at 1 range 6 .. 6; 9008 Slave_V7 at 1 range 7 .. 7; 9009 end record; 9010@end smallexample 9011 9012@noindent 9013Now if we move this to a little endian machine, then the bit ordering within 9014the byte is backwards, so we have to rewrite the record rep clause as: 9015 9016@smallexample @c ada 9017 for Data use record 9018 Master_Control at 0 range 7 .. 7; 9019 Master_V1 at 0 range 6 .. 6; 9020 Master_V2 at 0 range 5 .. 5; 9021 Master_V3 at 0 range 4 .. 4; 9022 Master_V4 at 0 range 3 .. 3; 9023 Master_V5 at 0 range 2 .. 2; 9024 Master_V6 at 0 range 1 .. 1; 9025 Master_V7 at 0 range 0 .. 0; 9026 Slave_Control at 1 range 7 .. 7; 9027 Slave_V1 at 1 range 6 .. 6; 9028 Slave_V2 at 1 range 5 .. 5; 9029 Slave_V3 at 1 range 4 .. 4; 9030 Slave_V4 at 1 range 3 .. 3; 9031 Slave_V5 at 1 range 2 .. 2; 9032 Slave_V6 at 1 range 1 .. 1; 9033 Slave_V7 at 1 range 0 .. 0; 9034 end record; 9035@end smallexample 9036 9037@noindent 9038It is a nuisance to have to rewrite the clause, especially if 9039the code has to be maintained on both machines. However, 9040this is a case that we can handle with the 9041@code{Bit_Order} attribute if it is implemented. 9042Note that the implementation is not required on byte addressed 9043machines, but it is indeed implemented in GNAT. 9044This means that we can simply use the 9045first record clause, together with the declaration 9046 9047@smallexample @c ada 9048 for Data'Bit_Order use High_Order_First; 9049@end smallexample 9050 9051@noindent 9052and the effect is what is desired, namely the layout is exactly the same, 9053independent of whether the code is compiled on a big-endian or little-endian 9054machine. 9055 9056The important point to understand is that byte ordering is not affected. 9057A @code{Bit_Order} attribute definition never affects which byte a field 9058ends up in, only where it ends up in that byte. 9059To make this clear, let us rewrite the record rep clause of the previous 9060example as: 9061 9062@smallexample @c ada 9063 for Data'Bit_Order use High_Order_First; 9064 for Data use record 9065 Master_Control at 0 range 0 .. 0; 9066 Master_V1 at 0 range 1 .. 1; 9067 Master_V2 at 0 range 2 .. 2; 9068 Master_V3 at 0 range 3 .. 3; 9069 Master_V4 at 0 range 4 .. 4; 9070 Master_V5 at 0 range 5 .. 5; 9071 Master_V6 at 0 range 6 .. 6; 9072 Master_V7 at 0 range 7 .. 7; 9073 Slave_Control at 0 range 8 .. 8; 9074 Slave_V1 at 0 range 9 .. 9; 9075 Slave_V2 at 0 range 10 .. 10; 9076 Slave_V3 at 0 range 11 .. 11; 9077 Slave_V4 at 0 range 12 .. 12; 9078 Slave_V5 at 0 range 13 .. 13; 9079 Slave_V6 at 0 range 14 .. 14; 9080 Slave_V7 at 0 range 15 .. 15; 9081 end record; 9082@end smallexample 9083 9084@noindent 9085This is exactly equivalent to saying (a repeat of the first example): 9086 9087@smallexample @c ada 9088 for Data'Bit_Order use High_Order_First; 9089 for Data use record 9090 Master_Control at 0 range 0 .. 0; 9091 Master_V1 at 0 range 1 .. 1; 9092 Master_V2 at 0 range 2 .. 2; 9093 Master_V3 at 0 range 3 .. 3; 9094 Master_V4 at 0 range 4 .. 4; 9095 Master_V5 at 0 range 5 .. 5; 9096 Master_V6 at 0 range 6 .. 6; 9097 Master_V7 at 0 range 7 .. 7; 9098 Slave_Control at 1 range 0 .. 0; 9099 Slave_V1 at 1 range 1 .. 1; 9100 Slave_V2 at 1 range 2 .. 2; 9101 Slave_V3 at 1 range 3 .. 3; 9102 Slave_V4 at 1 range 4 .. 4; 9103 Slave_V5 at 1 range 5 .. 5; 9104 Slave_V6 at 1 range 6 .. 6; 9105 Slave_V7 at 1 range 7 .. 7; 9106 end record; 9107@end smallexample 9108 9109@noindent 9110Why are they equivalent? Well take a specific field, the @code{Slave_V2} 9111field. The storage place attributes are obtained by normalizing the 9112values given so that the @code{First_Bit} value is less than 8. After 9113normalizing the values (0,10,10) we get (1,2,2) which is exactly what 9114we specified in the other case. 9115 9116Now one might expect that the @code{Bit_Order} attribute might affect 9117bit numbering within the entire record component (two bytes in this 9118case, thus affecting which byte fields end up in), but that is not 9119the way this feature is defined, it only affects numbering of bits, 9120not which byte they end up in. 9121 9122Consequently it never makes sense to specify a starting bit number 9123greater than 7 (for a byte addressable field) if an attribute 9124definition for @code{Bit_Order} has been given, and indeed it 9125may be actively confusing to specify such a value, so the compiler 9126generates a warning for such usage. 9127 9128If you do need to control byte ordering then appropriate conditional 9129values must be used. If in our example, the slave byte came first on 9130some machines we might write: 9131 9132@smallexample @c ada 9133 Master_Byte_First constant Boolean := @dots{}; 9134 9135 Master_Byte : constant Natural := 9136 1 - Boolean'Pos (Master_Byte_First); 9137 Slave_Byte : constant Natural := 9138 Boolean'Pos (Master_Byte_First); 9139 9140 for Data'Bit_Order use High_Order_First; 9141 for Data use record 9142 Master_Control at Master_Byte range 0 .. 0; 9143 Master_V1 at Master_Byte range 1 .. 1; 9144 Master_V2 at Master_Byte range 2 .. 2; 9145 Master_V3 at Master_Byte range 3 .. 3; 9146 Master_V4 at Master_Byte range 4 .. 4; 9147 Master_V5 at Master_Byte range 5 .. 5; 9148 Master_V6 at Master_Byte range 6 .. 6; 9149 Master_V7 at Master_Byte range 7 .. 7; 9150 Slave_Control at Slave_Byte range 0 .. 0; 9151 Slave_V1 at Slave_Byte range 1 .. 1; 9152 Slave_V2 at Slave_Byte range 2 .. 2; 9153 Slave_V3 at Slave_Byte range 3 .. 3; 9154 Slave_V4 at Slave_Byte range 4 .. 4; 9155 Slave_V5 at Slave_Byte range 5 .. 5; 9156 Slave_V6 at Slave_Byte range 6 .. 6; 9157 Slave_V7 at Slave_Byte range 7 .. 7; 9158 end record; 9159@end smallexample 9160 9161@noindent 9162Now to switch between machines, all that is necessary is 9163to set the boolean constant @code{Master_Byte_First} in 9164an appropriate manner. 9165 9166@node Pragma Pack for Arrays 9167@section Pragma Pack for Arrays 9168@cindex Pragma Pack (for arrays) 9169 9170@noindent 9171Pragma @code{Pack} applied to an array has no effect unless the component type 9172is packable. For a component type to be packable, it must be one of the 9173following cases: 9174 9175@itemize @bullet 9176@item 9177Any scalar type 9178@item 9179Any type whose size is specified with a size clause 9180@item 9181Any packed array type with a static size 9182@end itemize 9183 9184@noindent 9185For all these cases, if the component subtype size is in the range 91861 through 63, then the effect of the pragma @code{Pack} is exactly as though a 9187component size were specified giving the component subtype size. 9188For example if we have: 9189 9190@smallexample @c ada 9191 type r is range 0 .. 17; 9192 9193 type ar is array (1 .. 8) of r; 9194 pragma Pack (ar); 9195@end smallexample 9196 9197@noindent 9198Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size}, 9199and the size of the array @code{ar} will be exactly 40 bits. 9200 9201Note that in some cases this rather fierce approach to packing can produce 9202unexpected effects. For example, in Ada 95, type Natural typically has a 9203size of 31, meaning that if you pack an array of Natural, you get 31-bit 9204close packing, which saves a few bits, but results in far less efficient 9205access. Since many other Ada compilers will ignore such a packing request, 9206GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses 9207might not be what is intended. You can easily remove this warning by 9208using an explicit @code{Component_Size} setting instead, which never generates 9209a warning, since the intention of the programmer is clear in this case. 9210 9211GNAT treats packed arrays in one of two ways. If the size of the array is 9212known at compile time and is less than 64 bits, then internally the array 9213is represented as a single modular type, of exactly the appropriate number 9214of bits. If the length is greater than 63 bits, or is not known at compile 9215time, then the packed array is represented as an array of bytes, and the 9216length is always a multiple of 8 bits. 9217 9218Note that to represent a packed array as a modular type, the alignment must 9219be suitable for the modular type involved. For example, on typical machines 9220a 32-bit packed array will be represented by a 32-bit modular integer with 9221an alignment of four bytes. If you explicitly override the default alignment 9222with an alignment clause that is too small, the modular representation 9223cannot be used. For example, consider the following set of declarations: 9224 9225@smallexample @c ada 9226 type R is range 1 .. 3; 9227 type S is array (1 .. 31) of R; 9228 for S'Component_Size use 2; 9229 for S'Size use 62; 9230 for S'Alignment use 1; 9231@end smallexample 9232 9233@noindent 9234If the alignment clause were not present, then a 62-bit modular 9235representation would be chosen (typically with an alignment of 4 or 8 9236bytes depending on the target). But the default alignment is overridden 9237with the explicit alignment clause. This means that the modular 9238representation cannot be used, and instead the array of bytes 9239representation must be used, meaning that the length must be a multiple 9240of 8. Thus the above set of declarations will result in a diagnostic 9241rejecting the size clause and noting that the minimum size allowed is 64. 9242 9243@cindex Pragma Pack (for type Natural) 9244@cindex Pragma Pack warning 9245 9246One special case that is worth noting occurs when the base type of the 9247component size is 8/16/32 and the subtype is one bit less. Notably this 9248occurs with subtype @code{Natural}. Consider: 9249 9250@smallexample @c ada 9251 type Arr is array (1 .. 32) of Natural; 9252 pragma Pack (Arr); 9253@end smallexample 9254 9255@noindent 9256In all commonly used Ada 83 compilers, this pragma Pack would be ignored, 9257since typically @code{Natural'Size} is 32 in Ada 83, and in any case most 9258Ada 83 compilers did not attempt 31 bit packing. 9259 9260In Ada 95, @code{Natural'Size} is required to be 31. Furthermore, GNAT really 9261does pack 31-bit subtype to 31 bits. This may result in a substantial 9262unintended performance penalty when porting legacy Ada 83 code. To help 9263prevent this, GNAT generates a warning in such cases. If you really want 31 9264bit packing in a case like this, you can set the component size explicitly: 9265 9266@smallexample @c ada 9267 type Arr is array (1 .. 32) of Natural; 9268 for Arr'Component_Size use 31; 9269@end smallexample 9270 9271@noindent 9272Here 31-bit packing is achieved as required, and no warning is generated, 9273since in this case the programmer intention is clear. 9274 9275@node Pragma Pack for Records 9276@section Pragma Pack for Records 9277@cindex Pragma Pack (for records) 9278 9279@noindent 9280Pragma @code{Pack} applied to a record will pack the components to reduce 9281wasted space from alignment gaps and by reducing the amount of space 9282taken by components. We distinguish between @emph{packable} components and 9283@emph{non-packable} components. 9284Components of the following types are considered packable: 9285@itemize @bullet 9286@item 9287All primitive types are packable. 9288 9289@item 9290Small packed arrays, whose size does not exceed 64 bits, and where the 9291size is statically known at compile time, are represented internally 9292as modular integers, and so they are also packable. 9293 9294@end itemize 9295 9296@noindent 9297All packable components occupy the exact number of bits corresponding to 9298their @code{Size} value, and are packed with no padding bits, i.e.@: they 9299can start on an arbitrary bit boundary. 9300 9301All other types are non-packable, they occupy an integral number of 9302storage units, and 9303are placed at a boundary corresponding to their alignment requirements. 9304 9305For example, consider the record 9306 9307@smallexample @c ada 9308 type Rb1 is array (1 .. 13) of Boolean; 9309 pragma Pack (rb1); 9310 9311 type Rb2 is array (1 .. 65) of Boolean; 9312 pragma Pack (rb2); 9313 9314 type x2 is record 9315 l1 : Boolean; 9316 l2 : Duration; 9317 l3 : Float; 9318 l4 : Boolean; 9319 l5 : Rb1; 9320 l6 : Rb2; 9321 end record; 9322 pragma Pack (x2); 9323@end smallexample 9324 9325@noindent 9326The representation for the record x2 is as follows: 9327 9328@smallexample @c ada 9329for x2'Size use 224; 9330for x2 use record 9331 l1 at 0 range 0 .. 0; 9332 l2 at 0 range 1 .. 64; 9333 l3 at 12 range 0 .. 31; 9334 l4 at 16 range 0 .. 0; 9335 l5 at 16 range 1 .. 13; 9336 l6 at 18 range 0 .. 71; 9337end record; 9338@end smallexample 9339 9340@noindent 9341Studying this example, we see that the packable fields @code{l1} 9342and @code{l2} are 9343of length equal to their sizes, and placed at specific bit boundaries (and 9344not byte boundaries) to 9345eliminate padding. But @code{l3} is of a non-packable float type, so 9346it is on the next appropriate alignment boundary. 9347 9348The next two fields are fully packable, so @code{l4} and @code{l5} are 9349minimally packed with no gaps. However, type @code{Rb2} is a packed 9350array that is longer than 64 bits, so it is itself non-packable. Thus 9351the @code{l6} field is aligned to the next byte boundary, and takes an 9352integral number of bytes, i.e.@: 72 bits. 9353 9354@node Record Representation Clauses 9355@section Record Representation Clauses 9356@cindex Record Representation Clause 9357 9358@noindent 9359Record representation clauses may be given for all record types, including 9360types obtained by record extension. Component clauses are allowed for any 9361static component. The restrictions on component clauses depend on the type 9362of the component. 9363 9364@cindex Component Clause 9365For all components of an elementary type, the only restriction on component 9366clauses is that the size must be at least the 'Size value of the type 9367(actually the Value_Size). There are no restrictions due to alignment, 9368and such components may freely cross storage boundaries. 9369 9370Packed arrays with a size up to and including 64 bits are represented 9371internally using a modular type with the appropriate number of bits, and 9372thus the same lack of restriction applies. For example, if you declare: 9373 9374@smallexample @c ada 9375 type R is array (1 .. 49) of Boolean; 9376 pragma Pack (R); 9377 for R'Size use 49; 9378@end smallexample 9379 9380@noindent 9381then a component clause for a component of type R may start on any 9382specified bit boundary, and may specify a value of 49 bits or greater. 9383 9384The rules for other types are different for GNAT 3 and GNAT 5 versions 9385(based on GCC 2 and GCC 3 respectively). In GNAT 5, larger components 9386may also be placed on arbitrary boundaries, so for example, the following 9387is permitted: 9388 9389@smallexample @c ada 9390 type R is array (1 .. 79) of Boolean; 9391 pragma Pack (R); 9392 for R'Size use 79; 9393 9394 type Q is record 9395 G, H : Boolean; 9396 L, M : R; 9397 end record; 9398 9399 for Q use record 9400 G at 0 range 0 .. 0; 9401 H at 0 range 1 .. 1; 9402 L at 0 range 2 .. 80; 9403 R at 0 range 81 .. 159; 9404 end record; 9405@end smallexample 9406 9407@noindent 9408In GNAT 3, there are more severe restrictions on larger components. 9409For non-primitive types, including packed arrays with a size greater than 941064 bits, component clauses must respect the alignment requirement of the 9411type, in particular, always starting on a byte boundary, and the length 9412must be a multiple of the storage unit. 9413 9414The following rules regarding tagged types are enforced in both GNAT 3 and 9415GNAT 5: 9416 9417The tag field of a tagged type always occupies an address sized field at 9418the start of the record. No component clause may attempt to overlay this 9419tag. 9420 9421In the case of a record extension T1, of a type T, no component clause applied 9422to the type T1 can specify a storage location that would overlap the first 9423T'Size bytes of the record. 9424 9425@node Enumeration Clauses 9426@section Enumeration Clauses 9427 9428The only restriction on enumeration clauses is that the range of values 9429must be representable. For the signed case, if one or more of the 9430representation values are negative, all values must be in the range: 9431 9432@smallexample @c ada 9433 System.Min_Int .. System.Max_Int 9434@end smallexample 9435 9436@noindent 9437For the unsigned case, where all values are non negative, the values must 9438be in the range: 9439 9440@smallexample @c ada 9441 0 .. System.Max_Binary_Modulus; 9442@end smallexample 9443 9444@noindent 9445A @emph{confirming} representation clause is one in which the values range 9446from 0 in sequence, i.e.@: a clause that confirms the default representation 9447for an enumeration type. 9448Such a confirming representation 9449is permitted by these rules, and is specially recognized by the compiler so 9450that no extra overhead results from the use of such a clause. 9451 9452If an array has an index type which is an enumeration type to which an 9453enumeration clause has been applied, then the array is stored in a compact 9454manner. Consider the declarations: 9455 9456@smallexample @c ada 9457 type r is (A, B, C); 9458 for r use (A => 1, B => 5, C => 10); 9459 type t is array (r) of Character; 9460@end smallexample 9461 9462@noindent 9463The array type t corresponds to a vector with exactly three elements and 9464has a default size equal to @code{3*Character'Size}. This ensures efficient 9465use of space, but means that accesses to elements of the array will incur 9466the overhead of converting representation values to the corresponding 9467positional values, (i.e.@: the value delivered by the @code{Pos} attribute). 9468 9469@node Address Clauses 9470@section Address Clauses 9471@cindex Address Clause 9472 9473The reference manual allows a general restriction on representation clauses, 9474as found in RM 13.1(22): 9475 9476@quotation 9477An implementation need not support representation 9478items containing nonstatic expressions, except that 9479an implementation should support a representation item 9480for a given entity if each nonstatic expression in the 9481representation item is a name that statically denotes 9482a constant declared before the entity. 9483@end quotation 9484 9485@noindent 9486In practice this is applicable only to address clauses, since this is the 9487only case in which a non-static expression is permitted by the syntax. As 9488the AARM notes in sections 13.1 (22.a-22.h): 9489 9490@display 9491 22.a Reason: This is to avoid the following sort of thing: 9492 9493 22.b X : Integer := F(@dots{}); 9494 Y : Address := G(@dots{}); 9495 for X'Address use Y; 9496 9497 22.c In the above, we have to evaluate the 9498 initialization expression for X before we 9499 know where to put the result. This seems 9500 like an unreasonable implementation burden. 9501 9502 22.d The above code should instead be written 9503 like this: 9504 9505 22.e Y : constant Address := G(@dots{}); 9506 X : Integer := F(@dots{}); 9507 for X'Address use Y; 9508 9509 22.f This allows the expression ``Y'' to be safely 9510 evaluated before X is created. 9511 9512 22.g The constant could be a formal parameter of mode in. 9513 9514 22.h An implementation can support other nonstatic 9515 expressions if it wants to. Expressions of type 9516 Address are hardly ever static, but their value 9517 might be known at compile time anyway in many 9518 cases. 9519@end display 9520 9521@noindent 9522GNAT does indeed permit many additional cases of non-static expressions. In 9523particular, if the type involved is elementary there are no restrictions 9524(since in this case, holding a temporary copy of the initialization value, 9525if one is present, is inexpensive). In addition, if there is no implicit or 9526explicit initialization, then there are no restrictions. GNAT will reject 9527only the case where all three of these conditions hold: 9528 9529@itemize @bullet 9530 9531@item 9532The type of the item is non-elementary (e.g.@: a record or array). 9533 9534@item 9535There is explicit or implicit initialization required for the object. 9536Note that access values are always implicitly initialized, and also 9537in GNAT, certain bit-packed arrays (those having a dynamic length or 9538a length greater than 64) will also be implicitly initialized to zero. 9539 9540@item 9541The address value is non-static. Here GNAT is more permissive than the 9542RM, and allows the address value to be the address of a previously declared 9543stand-alone variable, as long as it does not itself have an address clause. 9544 9545@smallexample @c ada 9546 Anchor : Some_Initialized_Type; 9547 Overlay : Some_Initialized_Type; 9548 for Overlay'Address use Anchor'Address; 9549@end smallexample 9550 9551@noindent 9552However, the prefix of the address clause cannot be an array component, or 9553a component of a discriminated record. 9554 9555@end itemize 9556 9557@noindent 9558As noted above in section 22.h, address values are typically non-static. In 9559particular the To_Address function, even if applied to a literal value, is 9560a non-static function call. To avoid this minor annoyance, GNAT provides 9561the implementation defined attribute 'To_Address. The following two 9562expressions have identical values: 9563 9564@findex Attribute 9565@findex To_Address 9566@smallexample @c ada 9567 To_Address (16#1234_0000#) 9568 System'To_Address (16#1234_0000#); 9569@end smallexample 9570 9571@noindent 9572except that the second form is considered to be a static expression, and 9573thus when used as an address clause value is always permitted. 9574 9575@noindent 9576Additionally, GNAT treats as static an address clause that is an 9577unchecked_conversion of a static integer value. This simplifies the porting 9578of legacy code, and provides a portable equivalent to the GNAT attribute 9579@code{To_Address}. 9580 9581Another issue with address clauses is the interaction with alignment 9582requirements. When an address clause is given for an object, the address 9583value must be consistent with the alignment of the object (which is usually 9584the same as the alignment of the type of the object). If an address clause 9585is given that specifies an inappropriately aligned address value, then the 9586program execution is erroneous. 9587 9588Since this source of erroneous behavior can have unfortunate effects, GNAT 9589checks (at compile time if possible, generating a warning, or at execution 9590time with a run-time check) that the alignment is appropriate. If the 9591run-time check fails, then @code{Program_Error} is raised. This run-time 9592check is suppressed if range checks are suppressed, or if 9593@code{pragma Restrictions (No_Elaboration_Code)} is in effect. 9594 9595@findex Export 9596An address clause cannot be given for an exported object. More 9597understandably the real restriction is that objects with an address 9598clause cannot be exported. This is because such variables are not 9599defined by the Ada program, so there is no external object to export. 9600 9601@findex Import 9602It is permissible to give an address clause and a pragma Import for the 9603same object. In this case, the variable is not really defined by the 9604Ada program, so there is no external symbol to be linked. The link name 9605and the external name are ignored in this case. The reason that we allow this 9606combination is that it provides a useful idiom to avoid unwanted 9607initializations on objects with address clauses. 9608 9609When an address clause is given for an object that has implicit or 9610explicit initialization, then by default initialization takes place. This 9611means that the effect of the object declaration is to overwrite the 9612memory at the specified address. This is almost always not what the 9613programmer wants, so GNAT will output a warning: 9614 9615@smallexample 9616 with System; 9617 package G is 9618 type R is record 9619 M : Integer := 0; 9620 end record; 9621 9622 Ext : R; 9623 for Ext'Address use System'To_Address (16#1234_1234#); 9624 | 9625 >>> warning: implicit initialization of "Ext" may 9626 modify overlaid storage 9627 >>> warning: use pragma Import for "Ext" to suppress 9628 initialization (RM B(24)) 9629 9630 end G; 9631@end smallexample 9632 9633@noindent 9634As indicated by the warning message, the solution is to use a (dummy) pragma 9635Import to suppress this initialization. The pragma tell the compiler that the 9636object is declared and initialized elsewhere. The following package compiles 9637without warnings (and the initialization is suppressed): 9638 9639@smallexample @c ada 9640 with System; 9641 package G is 9642 type R is record 9643 M : Integer := 0; 9644 end record; 9645 9646 Ext : R; 9647 for Ext'Address use System'To_Address (16#1234_1234#); 9648 pragma Import (Ada, Ext); 9649 end G; 9650@end smallexample 9651 9652@noindent 9653A final issue with address clauses involves their use for overlaying 9654variables, as in the following example: 9655@cindex Overlaying of objects 9656 9657@smallexample @c ada 9658 A : Integer; 9659 B : Integer; 9660 for B'Address use A'Address; 9661@end smallexample 9662 9663@noindent 9664or alternatively, using the form recommended by the RM: 9665 9666@smallexample @c ada 9667 A : Integer; 9668 Addr : constant Address := A'Address; 9669 B : Integer; 9670 for B'Address use Addr; 9671@end smallexample 9672 9673@noindent 9674In both of these cases, @code{A} 9675and @code{B} become aliased to one another via the 9676address clause. This use of address clauses to overlay 9677variables, achieving an effect similar to unchecked 9678conversion was erroneous in Ada 83, but in Ada 95 9679the effect is implementation defined. Furthermore, the 9680Ada 95 RM specifically recommends that in a situation 9681like this, @code{B} should be subject to the following 9682implementation advice (RM 13.3(19)): 9683 9684@quotation 968519 If the Address of an object is specified, or it is imported 9686 or exported, then the implementation should not perform 9687 optimizations based on assumptions of no aliases. 9688@end quotation 9689 9690@noindent 9691GNAT follows this recommendation, and goes further by also applying 9692this recommendation to the overlaid variable (@code{A} 9693in the above example) in this case. This means that the overlay 9694works "as expected", in that a modification to one of the variables 9695will affect the value of the other. 9696 9697@node Effect of Convention on Representation 9698@section Effect of Convention on Representation 9699@cindex Convention, effect on representation 9700 9701@noindent 9702Normally the specification of a foreign language convention for a type or 9703an object has no effect on the chosen representation. In particular, the 9704representation chosen for data in GNAT generally meets the standard system 9705conventions, and for example records are laid out in a manner that is 9706consistent with C@. This means that specifying convention C (for example) 9707has no effect. 9708 9709There are three exceptions to this general rule: 9710 9711@itemize @bullet 9712 9713@item Convention Fortran and array subtypes 9714If pragma Convention Fortran is specified for an array subtype, then in 9715accordance with the implementation advice in section 3.6.2(11) of the 9716Ada Reference Manual, the array will be stored in a Fortran-compatible 9717column-major manner, instead of the normal default row-major order. 9718 9719@item Convention C and enumeration types 9720GNAT normally stores enumeration types in 8, 16, or 32 bits as required 9721to accommodate all values of the type. For example, for the enumeration 9722type declared by: 9723 9724@smallexample @c ada 9725 type Color is (Red, Green, Blue); 9726@end smallexample 9727 9728@noindent 97298 bits is sufficient to store all values of the type, so by default, objects 9730of type @code{Color} will be represented using 8 bits. However, normal C 9731convention is to use 32 bits for all enum values in C, since enum values 9732are essentially of type int. If pragma @code{Convention C} is specified for an 9733Ada enumeration type, then the size is modified as necessary (usually to 973432 bits) to be consistent with the C convention for enum values. 9735 9736@item Convention C/Fortran and Boolean types 9737In C, the usual convention for boolean values, that is values used for 9738conditions, is that zero represents false, and nonzero values represent 9739true. In Ada, the normal convention is that two specific values, typically 97400/1, are used to represent false/true respectively. 9741 9742Fortran has a similar convention for @code{LOGICAL} values (any nonzero 9743value represents true). 9744 9745To accommodate the Fortran and C conventions, if a pragma Convention specifies 9746C or Fortran convention for a derived Boolean, as in the following example: 9747 9748@smallexample @c ada 9749 type C_Switch is new Boolean; 9750 pragma Convention (C, C_Switch); 9751@end smallexample 9752 9753@noindent 9754then the GNAT generated code will treat any nonzero value as true. For truth 9755values generated by GNAT, the conventional value 1 will be used for True, but 9756when one of these values is read, any nonzero value is treated as True. 9757 9758@end itemize 9759 9760@node Determining the Representations chosen by GNAT 9761@section Determining the Representations chosen by GNAT 9762@cindex Representation, determination of 9763@cindex @code{-gnatR} switch 9764 9765@noindent 9766Although the descriptions in this section are intended to be complete, it is 9767often easier to simply experiment to see what GNAT accepts and what the 9768effect is on the layout of types and objects. 9769 9770As required by the Ada RM, if a representation clause is not accepted, then 9771it must be rejected as illegal by the compiler. However, when a 9772representation clause or pragma is accepted, there can still be questions 9773of what the compiler actually does. For example, if a partial record 9774representation clause specifies the location of some components and not 9775others, then where are the non-specified components placed? Or if pragma 9776@code{Pack} is used on a record, then exactly where are the resulting 9777fields placed? The section on pragma @code{Pack} in this chapter can be 9778used to answer the second question, but it is often easier to just see 9779what the compiler does. 9780 9781For this purpose, GNAT provides the option @code{-gnatR}. If you compile 9782with this option, then the compiler will output information on the actual 9783representations chosen, in a format similar to source representation 9784clauses. For example, if we compile the package: 9785 9786@smallexample @c ada 9787package q is 9788 type r (x : boolean) is tagged record 9789 case x is 9790 when True => S : String (1 .. 100); 9791 when False => null; 9792 end case; 9793 end record; 9794 9795 type r2 is new r (false) with record 9796 y2 : integer; 9797 end record; 9798 9799 for r2 use record 9800 y2 at 16 range 0 .. 31; 9801 end record; 9802 9803 type x is record 9804 y : character; 9805 end record; 9806 9807 type x1 is array (1 .. 10) of x; 9808 for x1'component_size use 11; 9809 9810 type ia is access integer; 9811 9812 type Rb1 is array (1 .. 13) of Boolean; 9813 pragma Pack (rb1); 9814 9815 type Rb2 is array (1 .. 65) of Boolean; 9816 pragma Pack (rb2); 9817 9818 type x2 is record 9819 l1 : Boolean; 9820 l2 : Duration; 9821 l3 : Float; 9822 l4 : Boolean; 9823 l5 : Rb1; 9824 l6 : Rb2; 9825 end record; 9826 pragma Pack (x2); 9827end q; 9828@end smallexample 9829 9830@noindent 9831using the switch @code{-gnatR} we obtain the following output: 9832 9833@smallexample 9834Representation information for unit q 9835------------------------------------- 9836 9837for r'Size use ??; 9838for r'Alignment use 4; 9839for r use record 9840 x at 4 range 0 .. 7; 9841 _tag at 0 range 0 .. 31; 9842 s at 5 range 0 .. 799; 9843end record; 9844 9845for r2'Size use 160; 9846for r2'Alignment use 4; 9847for r2 use record 9848 x at 4 range 0 .. 7; 9849 _tag at 0 range 0 .. 31; 9850 _parent at 0 range 0 .. 63; 9851 y2 at 16 range 0 .. 31; 9852end record; 9853 9854for x'Size use 8; 9855for x'Alignment use 1; 9856for x use record 9857 y at 0 range 0 .. 7; 9858end record; 9859 9860for x1'Size use 112; 9861for x1'Alignment use 1; 9862for x1'Component_Size use 11; 9863 9864for rb1'Size use 13; 9865for rb1'Alignment use 2; 9866for rb1'Component_Size use 1; 9867 9868for rb2'Size use 72; 9869for rb2'Alignment use 1; 9870for rb2'Component_Size use 1; 9871 9872for x2'Size use 224; 9873for x2'Alignment use 4; 9874for x2 use record 9875 l1 at 0 range 0 .. 0; 9876 l2 at 0 range 1 .. 64; 9877 l3 at 12 range 0 .. 31; 9878 l4 at 16 range 0 .. 0; 9879 l5 at 16 range 1 .. 13; 9880 l6 at 18 range 0 .. 71; 9881end record; 9882@end smallexample 9883 9884@noindent 9885The Size values are actually the Object_Size, i.e.@: the default size that 9886will be allocated for objects of the type. 9887The ?? size for type r indicates that we have a variant record, and the 9888actual size of objects will depend on the discriminant value. 9889 9890The Alignment values show the actual alignment chosen by the compiler 9891for each record or array type. 9892 9893The record representation clause for type r shows where all fields 9894are placed, including the compiler generated tag field (whose location 9895cannot be controlled by the programmer). 9896 9897The record representation clause for the type extension r2 shows all the 9898fields present, including the parent field, which is a copy of the fields 9899of the parent type of r2, i.e.@: r1. 9900 9901The component size and size clauses for types rb1 and rb2 show 9902the exact effect of pragma @code{Pack} on these arrays, and the record 9903representation clause for type x2 shows how pragma @code{Pack} affects 9904this record type. 9905 9906In some cases, it may be useful to cut and paste the representation clauses 9907generated by the compiler into the original source to fix and guarantee 9908the actual representation to be used. 9909 9910@node Standard Library Routines 9911@chapter Standard Library Routines 9912 9913@noindent 9914The Ada 95 Reference Manual contains in Annex A a full description of an 9915extensive set of standard library routines that can be used in any Ada 9916program, and which must be provided by all Ada compilers. They are 9917analogous to the standard C library used by C programs. 9918 9919GNAT implements all of the facilities described in annex A, and for most 9920purposes the description in the Ada 95 9921reference manual, or appropriate Ada 9922text book, will be sufficient for making use of these facilities. 9923 9924In the case of the input-output facilities, @xref{The Implementation of 9925Standard I/O}, gives details on exactly how GNAT interfaces to the 9926file system. For the remaining packages, the Ada 95 reference manual 9927should be sufficient. The following is a list of the packages included, 9928together with a brief description of the functionality that is provided. 9929 9930For completeness, references are included to other predefined library 9931routines defined in other sections of the Ada 95 reference manual (these are 9932cross-indexed from annex A). 9933 9934@table @code 9935@item Ada (A.2) 9936This is a parent package for all the standard library packages. It is 9937usually included implicitly in your program, and itself contains no 9938useful data or routines. 9939 9940@item Ada.Calendar (9.6) 9941@code{Calendar} provides time of day access, and routines for 9942manipulating times and durations. 9943 9944@item Ada.Characters (A.3.1) 9945This is a dummy parent package that contains no useful entities 9946 9947@item Ada.Characters.Handling (A.3.2) 9948This package provides some basic character handling capabilities, 9949including classification functions for classes of characters (e.g.@: test 9950for letters, or digits). 9951 9952@item Ada.Characters.Latin_1 (A.3.3) 9953This package includes a complete set of definitions of the characters 9954that appear in type CHARACTER@. It is useful for writing programs that 9955will run in international environments. For example, if you want an 9956upper case E with an acute accent in a string, it is often better to use 9957the definition of @code{UC_E_Acute} in this package. Then your program 9958will print in an understandable manner even if your environment does not 9959support these extended characters. 9960 9961@item Ada.Command_Line (A.15) 9962This package provides access to the command line parameters and the name 9963of the current program (analogous to the use of @code{argc} and @code{argv} 9964in C), and also allows the exit status for the program to be set in a 9965system-independent manner. 9966 9967@item Ada.Decimal (F.2) 9968This package provides constants describing the range of decimal numbers 9969implemented, and also a decimal divide routine (analogous to the COBOL 9970verb DIVIDE .. GIVING .. REMAINDER ..) 9971 9972@item Ada.Direct_IO (A.8.4) 9973This package provides input-output using a model of a set of records of 9974fixed-length, containing an arbitrary definite Ada type, indexed by an 9975integer record number. 9976 9977@item Ada.Dynamic_Priorities (D.5) 9978This package allows the priorities of a task to be adjusted dynamically 9979as the task is running. 9980 9981@item Ada.Exceptions (11.4.1) 9982This package provides additional information on exceptions, and also 9983contains facilities for treating exceptions as data objects, and raising 9984exceptions with associated messages. 9985 9986@item Ada.Finalization (7.6) 9987This package contains the declarations and subprograms to support the 9988use of controlled types, providing for automatic initialization and 9989finalization (analogous to the constructors and destructors of C++) 9990 9991@item Ada.Interrupts (C.3.2) 9992This package provides facilities for interfacing to interrupts, which 9993includes the set of signals or conditions that can be raised and 9994recognized as interrupts. 9995 9996@item Ada.Interrupts.Names (C.3.2) 9997This package provides the set of interrupt names (actually signal 9998or condition names) that can be handled by GNAT@. 9999 10000@item Ada.IO_Exceptions (A.13) 10001This package defines the set of exceptions that can be raised by use of 10002the standard IO packages. 10003 10004@item Ada.Numerics 10005This package contains some standard constants and exceptions used 10006throughout the numerics packages. Note that the constants pi and e are 10007defined here, and it is better to use these definitions than rolling 10008your own. 10009 10010@item Ada.Numerics.Complex_Elementary_Functions 10011Provides the implementation of standard elementary functions (such as 10012log and trigonometric functions) operating on complex numbers using the 10013standard @code{Float} and the @code{Complex} and @code{Imaginary} types 10014created by the package @code{Numerics.Complex_Types}. 10015 10016@item Ada.Numerics.Complex_Types 10017This is a predefined instantiation of 10018@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to 10019build the type @code{Complex} and @code{Imaginary}. 10020 10021@item Ada.Numerics.Discrete_Random 10022This package provides a random number generator suitable for generating 10023random integer values from a specified range. 10024 10025@item Ada.Numerics.Float_Random 10026This package provides a random number generator suitable for generating 10027uniformly distributed floating point values. 10028 10029@item Ada.Numerics.Generic_Complex_Elementary_Functions 10030This is a generic version of the package that provides the 10031implementation of standard elementary functions (such as log and 10032trigonometric functions) for an arbitrary complex type. 10033 10034The following predefined instantiations of this package are provided: 10035 10036@table @code 10037@item Short_Float 10038@code{Ada.Numerics.Short_Complex_Elementary_Functions} 10039@item Float 10040@code{Ada.Numerics.Complex_Elementary_Functions} 10041@item Long_Float 10042@code{Ada.Numerics. 10043 Long_Complex_Elementary_Functions} 10044@end table 10045 10046@item Ada.Numerics.Generic_Complex_Types 10047This is a generic package that allows the creation of complex types, 10048with associated complex arithmetic operations. 10049 10050The following predefined instantiations of this package exist 10051@table @code 10052@item Short_Float 10053@code{Ada.Numerics.Short_Complex_Complex_Types} 10054@item Float 10055@code{Ada.Numerics.Complex_Complex_Types} 10056@item Long_Float 10057@code{Ada.Numerics.Long_Complex_Complex_Types} 10058@end table 10059 10060@item Ada.Numerics.Generic_Elementary_Functions 10061This is a generic package that provides the implementation of standard 10062elementary functions (such as log an trigonometric functions) for an 10063arbitrary float type. 10064 10065The following predefined instantiations of this package exist 10066 10067@table @code 10068@item Short_Float 10069@code{Ada.Numerics.Short_Elementary_Functions} 10070@item Float 10071@code{Ada.Numerics.Elementary_Functions} 10072@item Long_Float 10073@code{Ada.Numerics.Long_Elementary_Functions} 10074@end table 10075 10076@item Ada.Real_Time (D.8) 10077This package provides facilities similar to those of @code{Calendar}, but 10078operating with a finer clock suitable for real time control. Note that 10079annex D requires that there be no backward clock jumps, and GNAT generally 10080guarantees this behavior, but of course if the external clock on which 10081the GNAT runtime depends is deliberately reset by some external event, 10082then such a backward jump may occur. 10083 10084@item Ada.Sequential_IO (A.8.1) 10085This package provides input-output facilities for sequential files, 10086which can contain a sequence of values of a single type, which can be 10087any Ada type, including indefinite (unconstrained) types. 10088 10089@item Ada.Storage_IO (A.9) 10090This package provides a facility for mapping arbitrary Ada types to and 10091from a storage buffer. It is primarily intended for the creation of new 10092IO packages. 10093 10094@item Ada.Streams (13.13.1) 10095This is a generic package that provides the basic support for the 10096concept of streams as used by the stream attributes (@code{Input}, 10097@code{Output}, @code{Read} and @code{Write}). 10098 10099@item Ada.Streams.Stream_IO (A.12.1) 10100This package is a specialization of the type @code{Streams} defined in 10101package @code{Streams} together with a set of operations providing 10102Stream_IO capability. The Stream_IO model permits both random and 10103sequential access to a file which can contain an arbitrary set of values 10104of one or more Ada types. 10105 10106@item Ada.Strings (A.4.1) 10107This package provides some basic constants used by the string handling 10108packages. 10109 10110@item Ada.Strings.Bounded (A.4.4) 10111This package provides facilities for handling variable length 10112strings. The bounded model requires a maximum length. It is thus 10113somewhat more limited than the unbounded model, but avoids the use of 10114dynamic allocation or finalization. 10115 10116@item Ada.Strings.Fixed (A.4.3) 10117This package provides facilities for handling fixed length strings. 10118 10119@item Ada.Strings.Maps (A.4.2) 10120This package provides facilities for handling character mappings and 10121arbitrarily defined subsets of characters. For instance it is useful in 10122defining specialized translation tables. 10123 10124@item Ada.Strings.Maps.Constants (A.4.6) 10125This package provides a standard set of predefined mappings and 10126predefined character sets. For example, the standard upper to lower case 10127conversion table is found in this package. Note that upper to lower case 10128conversion is non-trivial if you want to take the entire set of 10129characters, including extended characters like E with an acute accent, 10130into account. You should use the mappings in this package (rather than 10131adding 32 yourself) to do case mappings. 10132 10133@item Ada.Strings.Unbounded (A.4.5) 10134This package provides facilities for handling variable length 10135strings. The unbounded model allows arbitrary length strings, but 10136requires the use of dynamic allocation and finalization. 10137 10138@item Ada.Strings.Wide_Bounded (A.4.7) 10139@itemx Ada.Strings.Wide_Fixed (A.4.7) 10140@itemx Ada.Strings.Wide_Maps (A.4.7) 10141@itemx Ada.Strings.Wide_Maps.Constants (A.4.7) 10142@itemx Ada.Strings.Wide_Unbounded (A.4.7) 10143These packages provide analogous capabilities to the corresponding 10144packages without @samp{Wide_} in the name, but operate with the types 10145@code{Wide_String} and @code{Wide_Character} instead of @code{String} 10146and @code{Character}. 10147 10148@item Ada.Synchronous_Task_Control (D.10) 10149This package provides some standard facilities for controlling task 10150communication in a synchronous manner. 10151 10152@item Ada.Tags 10153This package contains definitions for manipulation of the tags of tagged 10154values. 10155 10156@item Ada.Task_Attributes 10157This package provides the capability of associating arbitrary 10158task-specific data with separate tasks. 10159 10160@item Ada.Text_IO 10161This package provides basic text input-output capabilities for 10162character, string and numeric data. The subpackages of this 10163package are listed next. 10164 10165@item Ada.Text_IO.Decimal_IO 10166Provides input-output facilities for decimal fixed-point types 10167 10168@item Ada.Text_IO.Enumeration_IO 10169Provides input-output facilities for enumeration types. 10170 10171@item Ada.Text_IO.Fixed_IO 10172Provides input-output facilities for ordinary fixed-point types. 10173 10174@item Ada.Text_IO.Float_IO 10175Provides input-output facilities for float types. The following 10176predefined instantiations of this generic package are available: 10177 10178@table @code 10179@item Short_Float 10180@code{Short_Float_Text_IO} 10181@item Float 10182@code{Float_Text_IO} 10183@item Long_Float 10184@code{Long_Float_Text_IO} 10185@end table 10186 10187@item Ada.Text_IO.Integer_IO 10188Provides input-output facilities for integer types. The following 10189predefined instantiations of this generic package are available: 10190 10191@table @code 10192@item Short_Short_Integer 10193@code{Ada.Short_Short_Integer_Text_IO} 10194@item Short_Integer 10195@code{Ada.Short_Integer_Text_IO} 10196@item Integer 10197@code{Ada.Integer_Text_IO} 10198@item Long_Integer 10199@code{Ada.Long_Integer_Text_IO} 10200@item Long_Long_Integer 10201@code{Ada.Long_Long_Integer_Text_IO} 10202@end table 10203 10204@item Ada.Text_IO.Modular_IO 10205Provides input-output facilities for modular (unsigned) types 10206 10207@item Ada.Text_IO.Complex_IO (G.1.3) 10208This package provides basic text input-output capabilities for complex 10209data. 10210 10211@item Ada.Text_IO.Editing (F.3.3) 10212This package contains routines for edited output, analogous to the use 10213of pictures in COBOL@. The picture formats used by this package are a 10214close copy of the facility in COBOL@. 10215 10216@item Ada.Text_IO.Text_Streams (A.12.2) 10217This package provides a facility that allows Text_IO files to be treated 10218as streams, so that the stream attributes can be used for writing 10219arbitrary data, including binary data, to Text_IO files. 10220 10221@item Ada.Unchecked_Conversion (13.9) 10222This generic package allows arbitrary conversion from one type to 10223another of the same size, providing for breaking the type safety in 10224special circumstances. 10225 10226If the types have the same Size (more accurately the same Value_Size), 10227then the effect is simply to transfer the bits from the source to the 10228target type without any modification. This usage is well defined, and 10229for simple types whose representation is typically the same across 10230all implementations, gives a portable method of performing such 10231conversions. 10232 10233If the types do not have the same size, then the result is implementation 10234defined, and thus may be non-portable. The following describes how GNAT 10235handles such unchecked conversion cases. 10236 10237If the types are of different sizes, and are both discrete types, then 10238the effect is of a normal type conversion without any constraint checking. 10239In particular if the result type has a larger size, the result will be 10240zero or sign extended. If the result type has a smaller size, the result 10241will be truncated by ignoring high order bits. 10242 10243If the types are of different sizes, and are not both discrete types, 10244then the conversion works as though pointers were created to the source 10245and target, and the pointer value is converted. The effect is that bits 10246are copied from successive low order storage units and bits of the source 10247up to the length of the target type. 10248 10249A warning is issued if the lengths differ, since the effect in this 10250case is implementation dependent, and the above behavior may not match 10251that of some other compiler. 10252 10253A pointer to one type may be converted to a pointer to another type using 10254unchecked conversion. The only case in which the effect is undefined is 10255when one or both pointers are pointers to unconstrained array types. In 10256this case, the bounds information may get incorrectly transferred, and in 10257particular, GNAT uses double size pointers for such types, and it is 10258meaningless to convert between such pointer types. GNAT will issue a 10259warning if the alignment of the target designated type is more strict 10260than the alignment of the source designated type (since the result may 10261be unaligned in this case). 10262 10263A pointer other than a pointer to an unconstrained array type may be 10264converted to and from System.Address. Such usage is common in Ada 83 10265programs, but note that Ada.Address_To_Access_Conversions is the 10266preferred method of performing such conversions in Ada 95. Neither 10267unchecked conversion nor Ada.Address_To_Access_Conversions should be 10268used in conjunction with pointers to unconstrained objects, since 10269the bounds information cannot be handled correctly in this case. 10270 10271@item Ada.Unchecked_Deallocation (13.11.2) 10272This generic package allows explicit freeing of storage previously 10273allocated by use of an allocator. 10274 10275@item Ada.Wide_Text_IO (A.11) 10276This package is similar to @code{Ada.Text_IO}, except that the external 10277file supports wide character representations, and the internal types are 10278@code{Wide_Character} and @code{Wide_String} instead of @code{Character} 10279and @code{String}. It contains generic subpackages listed next. 10280 10281@item Ada.Wide_Text_IO.Decimal_IO 10282Provides input-output facilities for decimal fixed-point types 10283 10284@item Ada.Wide_Text_IO.Enumeration_IO 10285Provides input-output facilities for enumeration types. 10286 10287@item Ada.Wide_Text_IO.Fixed_IO 10288Provides input-output facilities for ordinary fixed-point types. 10289 10290@item Ada.Wide_Text_IO.Float_IO 10291Provides input-output facilities for float types. The following 10292predefined instantiations of this generic package are available: 10293 10294@table @code 10295@item Short_Float 10296@code{Short_Float_Wide_Text_IO} 10297@item Float 10298@code{Float_Wide_Text_IO} 10299@item Long_Float 10300@code{Long_Float_Wide_Text_IO} 10301@end table 10302 10303@item Ada.Wide_Text_IO.Integer_IO 10304Provides input-output facilities for integer types. The following 10305predefined instantiations of this generic package are available: 10306 10307@table @code 10308@item Short_Short_Integer 10309@code{Ada.Short_Short_Integer_Wide_Text_IO} 10310@item Short_Integer 10311@code{Ada.Short_Integer_Wide_Text_IO} 10312@item Integer 10313@code{Ada.Integer_Wide_Text_IO} 10314@item Long_Integer 10315@code{Ada.Long_Integer_Wide_Text_IO} 10316@item Long_Long_Integer 10317@code{Ada.Long_Long_Integer_Wide_Text_IO} 10318@end table 10319 10320@item Ada.Wide_Text_IO.Modular_IO 10321Provides input-output facilities for modular (unsigned) types 10322 10323@item Ada.Wide_Text_IO.Complex_IO (G.1.3) 10324This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the 10325external file supports wide character representations. 10326 10327@item Ada.Wide_Text_IO.Editing (F.3.4) 10328This package is similar to @code{Ada.Text_IO.Editing}, except that the 10329types are @code{Wide_Character} and @code{Wide_String} instead of 10330@code{Character} and @code{String}. 10331 10332@item Ada.Wide_Text_IO.Streams (A.12.3) 10333This package is similar to @code{Ada.Text_IO.Streams}, except that the 10334types are @code{Wide_Character} and @code{Wide_String} instead of 10335@code{Character} and @code{String}. 10336@end table 10337 10338@node The Implementation of Standard I/O 10339@chapter The Implementation of Standard I/O 10340 10341@noindent 10342GNAT implements all the required input-output facilities described in 10343A.6 through A.14. These sections of the Ada 95 reference manual describe the 10344required behavior of these packages from the Ada point of view, and if 10345you are writing a portable Ada program that does not need to know the 10346exact manner in which Ada maps to the outside world when it comes to 10347reading or writing external files, then you do not need to read this 10348chapter. As long as your files are all regular files (not pipes or 10349devices), and as long as you write and read the files only from Ada, the 10350description in the Ada 95 reference manual is sufficient. 10351 10352However, if you want to do input-output to pipes or other devices, such 10353as the keyboard or screen, or if the files you are dealing with are 10354either generated by some other language, or to be read by some other 10355language, then you need to know more about the details of how the GNAT 10356implementation of these input-output facilities behaves. 10357 10358In this chapter we give a detailed description of exactly how GNAT 10359interfaces to the file system. As always, the sources of the system are 10360available to you for answering questions at an even more detailed level, 10361but for most purposes the information in this chapter will suffice. 10362 10363Another reason that you may need to know more about how input-output is 10364implemented arises when you have a program written in mixed languages 10365where, for example, files are shared between the C and Ada sections of 10366the same program. GNAT provides some additional facilities, in the form 10367of additional child library packages, that facilitate this sharing, and 10368these additional facilities are also described in this chapter. 10369 10370@menu 10371* Standard I/O Packages:: 10372* FORM Strings:: 10373* Direct_IO:: 10374* Sequential_IO:: 10375* Text_IO:: 10376* Wide_Text_IO:: 10377* Stream_IO:: 10378* Shared Files:: 10379* Open Modes:: 10380* Operations on C Streams:: 10381* Interfacing to C Streams:: 10382@end menu 10383 10384@node Standard I/O Packages 10385@section Standard I/O Packages 10386 10387@noindent 10388The Standard I/O packages described in Annex A for 10389 10390@itemize @bullet 10391@item 10392Ada.Text_IO 10393@item 10394Ada.Text_IO.Complex_IO 10395@item 10396Ada.Text_IO.Text_Streams, 10397@item 10398Ada.Wide_Text_IO 10399@item 10400Ada.Wide_Text_IO.Complex_IO, 10401@item 10402Ada.Wide_Text_IO.Text_Streams 10403@item 10404Ada.Stream_IO 10405@item 10406Ada.Sequential_IO 10407@item 10408Ada.Direct_IO 10409@end itemize 10410 10411@noindent 10412are implemented using the C 10413library streams facility; where 10414 10415@itemize @bullet 10416@item 10417All files are opened using @code{fopen}. 10418@item 10419All input/output operations use @code{fread}/@code{fwrite}. 10420@end itemize 10421 10422@noindent 10423There is no internal buffering of any kind at the Ada library level. The 10424only buffering is that provided at the system level in the 10425implementation of the C library routines that support streams. This 10426facilitates shared use of these streams by mixed language programs. 10427 10428@node FORM Strings 10429@section FORM Strings 10430 10431@noindent 10432The format of a FORM string in GNAT is: 10433 10434@smallexample 10435"keyword=value,keyword=value,@dots{},keyword=value" 10436@end smallexample 10437 10438@noindent 10439where letters may be in upper or lower case, and there are no spaces 10440between values. The order of the entries is not important. Currently 10441there are two keywords defined. 10442 10443@smallexample 10444SHARED=[YES|NO] 10445WCEM=[n|h|u|s\e] 10446@end smallexample 10447 10448@noindent 10449The use of these parameters is described later in this section. 10450 10451@node Direct_IO 10452@section Direct_IO 10453 10454@noindent 10455Direct_IO can only be instantiated for definite types. This is a 10456restriction of the Ada language, which means that the records are fixed 10457length (the length being determined by @code{@var{type}'Size}, rounded 10458up to the next storage unit boundary if necessary). 10459 10460The records of a Direct_IO file are simply written to the file in index 10461sequence, with the first record starting at offset zero, and subsequent 10462records following. There is no control information of any kind. For 10463example, if 32-bit integers are being written, each record takes 104644-bytes, so the record at index @var{K} starts at offset 10465(@var{K}@minus{}1)*4. 10466 10467There is no limit on the size of Direct_IO files, they are expanded as 10468necessary to accommodate whatever records are written to the file. 10469 10470@node Sequential_IO 10471@section Sequential_IO 10472 10473@noindent 10474Sequential_IO may be instantiated with either a definite (constrained) 10475or indefinite (unconstrained) type. 10476 10477For the definite type case, the elements written to the file are simply 10478the memory images of the data values with no control information of any 10479kind. The resulting file should be read using the same type, no validity 10480checking is performed on input. 10481 10482For the indefinite type case, the elements written consist of two 10483parts. First is the size of the data item, written as the memory image 10484of a @code{Interfaces.C.size_t} value, followed by the memory image of 10485the data value. The resulting file can only be read using the same 10486(unconstrained) type. Normal assignment checks are performed on these 10487read operations, and if these checks fail, @code{Data_Error} is 10488raised. In particular, in the array case, the lengths must match, and in 10489the variant record case, if the variable for a particular read operation 10490is constrained, the discriminants must match. 10491 10492Note that it is not possible to use Sequential_IO to write variable 10493length array items, and then read the data back into different length 10494arrays. For example, the following will raise @code{Data_Error}: 10495 10496@smallexample @c ada 10497 package IO is new Sequential_IO (String); 10498 F : IO.File_Type; 10499 S : String (1..4); 10500 @dots{} 10501 IO.Create (F) 10502 IO.Write (F, "hello!") 10503 IO.Reset (F, Mode=>In_File); 10504 IO.Read (F, S); 10505 Put_Line (S); 10506 10507@end smallexample 10508 10509@noindent 10510On some Ada implementations, this will print @code{hell}, but the program is 10511clearly incorrect, since there is only one element in the file, and that 10512element is the string @code{hello!}. 10513 10514In Ada 95, this kind of behavior can be legitimately achieved using 10515Stream_IO, and this is the preferred mechanism. In particular, the above 10516program fragment rewritten to use Stream_IO will work correctly. 10517 10518@node Text_IO 10519@section Text_IO 10520 10521@noindent 10522Text_IO files consist of a stream of characters containing the following 10523special control characters: 10524 10525@smallexample 10526LF (line feed, 16#0A#) Line Mark 10527FF (form feed, 16#0C#) Page Mark 10528@end smallexample 10529 10530@noindent 10531A canonical Text_IO file is defined as one in which the following 10532conditions are met: 10533 10534@itemize @bullet 10535@item 10536The character @code{LF} is used only as a line mark, i.e.@: to mark the end 10537of the line. 10538 10539@item 10540The character @code{FF} is used only as a page mark, i.e.@: to mark the 10541end of a page and consequently can appear only immediately following a 10542@code{LF} (line mark) character. 10543 10544@item 10545The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF} 10546(line mark, page mark). In the former case, the page mark is implicitly 10547assumed to be present. 10548@end itemize 10549 10550@noindent 10551A file written using Text_IO will be in canonical form provided that no 10552explicit @code{LF} or @code{FF} characters are written using @code{Put} 10553or @code{Put_Line}. There will be no @code{FF} character at the end of 10554the file unless an explicit @code{New_Page} operation was performed 10555before closing the file. 10556 10557A canonical Text_IO file that is a regular file, i.e.@: not a device or a 10558pipe, can be read using any of the routines in Text_IO@. The 10559semantics in this case will be exactly as defined in the Ada 95 reference 10560manual and all the routines in Text_IO are fully implemented. 10561 10562A text file that does not meet the requirements for a canonical Text_IO 10563file has one of the following: 10564 10565@itemize @bullet 10566@item 10567The file contains @code{FF} characters not immediately following a 10568@code{LF} character. 10569 10570@item 10571The file contains @code{LF} or @code{FF} characters written by 10572@code{Put} or @code{Put_Line}, which are not logically considered to be 10573line marks or page marks. 10574 10575@item 10576The file ends in a character other than @code{LF} or @code{FF}, 10577i.e.@: there is no explicit line mark or page mark at the end of the file. 10578@end itemize 10579 10580@noindent 10581Text_IO can be used to read such non-standard text files but subprograms 10582to do with line or page numbers do not have defined meanings. In 10583particular, a @code{FF} character that does not follow a @code{LF} 10584character may or may not be treated as a page mark from the point of 10585view of page and line numbering. Every @code{LF} character is considered 10586to end a line, and there is an implied @code{LF} character at the end of 10587the file. 10588 10589@menu 10590* Text_IO Stream Pointer Positioning:: 10591* Text_IO Reading and Writing Non-Regular Files:: 10592* Get_Immediate:: 10593* Treating Text_IO Files as Streams:: 10594* Text_IO Extensions:: 10595* Text_IO Facilities for Unbounded Strings:: 10596@end menu 10597 10598@node Text_IO Stream Pointer Positioning 10599@subsection Stream Pointer Positioning 10600 10601@noindent 10602@code{Ada.Text_IO} has a definition of current position for a file that 10603is being read. No internal buffering occurs in Text_IO, and usually the 10604physical position in the stream used to implement the file corresponds 10605to this logical position defined by Text_IO@. There are two exceptions: 10606 10607@itemize @bullet 10608@item 10609After a call to @code{End_Of_Page} that returns @code{True}, the stream 10610is positioned past the @code{LF} (line mark) that precedes the page 10611mark. Text_IO maintains an internal flag so that subsequent read 10612operations properly handle the logical position which is unchanged by 10613the @code{End_Of_Page} call. 10614 10615@item 10616After a call to @code{End_Of_File} that returns @code{True}, if the 10617Text_IO file was positioned before the line mark at the end of file 10618before the call, then the logical position is unchanged, but the stream 10619is physically positioned right at the end of file (past the line mark, 10620and past a possible page mark following the line mark. Again Text_IO 10621maintains internal flags so that subsequent read operations properly 10622handle the logical position. 10623@end itemize 10624 10625@noindent 10626These discrepancies have no effect on the observable behavior of 10627Text_IO, but if a single Ada stream is shared between a C program and 10628Ada program, or shared (using @samp{shared=yes} in the form string) 10629between two Ada files, then the difference may be observable in some 10630situations. 10631 10632@node Text_IO Reading and Writing Non-Regular Files 10633@subsection Reading and Writing Non-Regular Files 10634 10635@noindent 10636A non-regular file is a device (such as a keyboard), or a pipe. Text_IO 10637can be used for reading and writing. Writing is not affected and the 10638sequence of characters output is identical to the normal file case, but 10639for reading, the behavior of Text_IO is modified to avoid undesirable 10640look-ahead as follows: 10641 10642An input file that is not a regular file is considered to have no page 10643marks. Any @code{Ascii.FF} characters (the character normally used for a 10644page mark) appearing in the file are considered to be data 10645characters. In particular: 10646 10647@itemize @bullet 10648@item 10649@code{Get_Line} and @code{Skip_Line} do not test for a page mark 10650following a line mark. If a page mark appears, it will be treated as a 10651data character. 10652 10653@item 10654This avoids the need to wait for an extra character to be typed or 10655entered from the pipe to complete one of these operations. 10656 10657@item 10658@code{End_Of_Page} always returns @code{False} 10659 10660@item 10661@code{End_Of_File} will return @code{False} if there is a page mark at 10662the end of the file. 10663@end itemize 10664 10665@noindent 10666Output to non-regular files is the same as for regular files. Page marks 10667may be written to non-regular files using @code{New_Page}, but as noted 10668above they will not be treated as page marks on input if the output is 10669piped to another Ada program. 10670 10671Another important discrepancy when reading non-regular files is that the end 10672of file indication is not ``sticky''. If an end of file is entered, e.g.@: by 10673pressing the @key{EOT} key, 10674then end of file 10675is signaled once (i.e.@: the test @code{End_Of_File} 10676will yield @code{True}, or a read will 10677raise @code{End_Error}), but then reading can resume 10678to read data past that end of 10679file indication, until another end of file indication is entered. 10680 10681@node Get_Immediate 10682@subsection Get_Immediate 10683@cindex Get_Immediate 10684 10685@noindent 10686Get_Immediate returns the next character (including control characters) 10687from the input file. In particular, Get_Immediate will return LF or FF 10688characters used as line marks or page marks. Such operations leave the 10689file positioned past the control character, and it is thus not treated 10690as having its normal function. This means that page, line and column 10691counts after this kind of Get_Immediate call are set as though the mark 10692did not occur. In the case where a Get_Immediate leaves the file 10693positioned between the line mark and page mark (which is not normally 10694possible), it is undefined whether the FF character will be treated as a 10695page mark. 10696 10697@node Treating Text_IO Files as Streams 10698@subsection Treating Text_IO Files as Streams 10699@cindex Stream files 10700 10701@noindent 10702The package @code{Text_IO.Streams} allows a Text_IO file to be treated 10703as a stream. Data written to a Text_IO file in this stream mode is 10704binary data. If this binary data contains bytes 16#0A# (@code{LF}) or 1070516#0C# (@code{FF}), the resulting file may have non-standard 10706format. Similarly if read operations are used to read from a Text_IO 10707file treated as a stream, then @code{LF} and @code{FF} characters may be 10708skipped and the effect is similar to that described above for 10709@code{Get_Immediate}. 10710 10711@node Text_IO Extensions 10712@subsection Text_IO Extensions 10713@cindex Text_IO extensions 10714 10715@noindent 10716A package GNAT.IO_Aux in the GNAT library provides some useful extensions 10717to the standard @code{Text_IO} package: 10718 10719@itemize @bullet 10720@item function File_Exists (Name : String) return Boolean; 10721Determines if a file of the given name exists. 10722 10723@item function Get_Line return String; 10724Reads a string from the standard input file. The value returned is exactly 10725the length of the line that was read. 10726 10727@item function Get_Line (File : Ada.Text_IO.File_Type) return String; 10728Similar, except that the parameter File specifies the file from which 10729the string is to be read. 10730 10731@end itemize 10732 10733@node Text_IO Facilities for Unbounded Strings 10734@subsection Text_IO Facilities for Unbounded Strings 10735@cindex Text_IO for unbounded strings 10736@cindex Unbounded_String, Text_IO operations 10737 10738@noindent 10739The package @code{Ada.Strings.Unbounded.Text_IO} 10740in library files @code{a-suteio.ads/adb} contains some GNAT-specific 10741subprograms useful for Text_IO operations on unbounded strings: 10742 10743@itemize @bullet 10744 10745@item function Get_Line (File : File_Type) return Unbounded_String; 10746Reads a line from the specified file 10747and returns the result as an unbounded string. 10748 10749@item procedure Put (File : File_Type; U : Unbounded_String); 10750Writes the value of the given unbounded string to the specified file 10751Similar to the effect of 10752@code{Put (To_String (U))} except that an extra copy is avoided. 10753 10754@item procedure Put_Line (File : File_Type; U : Unbounded_String); 10755Writes the value of the given unbounded string to the specified file, 10756followed by a @code{New_Line}. 10757Similar to the effect of @code{Put_Line (To_String (U))} except 10758that an extra copy is avoided. 10759@end itemize 10760 10761@noindent 10762In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} 10763and is optional. If the parameter is omitted, then the standard input or 10764output file is referenced as appropriate. 10765 10766The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library 10767files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended 10768@code{Wide_Text_IO} functionality for unbounded wide strings. 10769 10770@node Wide_Text_IO 10771@section Wide_Text_IO 10772 10773@noindent 10774@code{Wide_Text_IO} is similar in most respects to Text_IO, except that 10775both input and output files may contain special sequences that represent 10776wide character values. The encoding scheme for a given file may be 10777specified using a FORM parameter: 10778 10779@smallexample 10780WCEM=@var{x} 10781@end smallexample 10782 10783@noindent 10784as part of the FORM string (WCEM = wide character encoding method), 10785where @var{x} is one of the following characters 10786 10787@table @samp 10788@item h 10789Hex ESC encoding 10790@item u 10791Upper half encoding 10792@item s 10793Shift-JIS encoding 10794@item e 10795EUC Encoding 10796@item 8 10797UTF-8 encoding 10798@item b 10799Brackets encoding 10800@end table 10801 10802@noindent 10803The encoding methods match those that 10804can be used in a source 10805program, but there is no requirement that the encoding method used for 10806the source program be the same as the encoding method used for files, 10807and different files may use different encoding methods. 10808 10809The default encoding method for the standard files, and for opened files 10810for which no WCEM parameter is given in the FORM string matches the 10811wide character encoding specified for the main program (the default 10812being brackets encoding if no coding method was specified with -gnatW). 10813 10814@table @asis 10815@item Hex Coding 10816In this encoding, a wide character is represented by a five character 10817sequence: 10818 10819@smallexample 10820ESC a b c d 10821@end smallexample 10822 10823@noindent 10824where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal 10825characters (using upper case letters) of the wide character code. For 10826example, ESC A345 is used to represent the wide character with code 1082716#A345#. This scheme is compatible with use of the full 10828@code{Wide_Character} set. 10829 10830@item Upper Half Coding 10831The wide character with encoding 16#abcd#, where the upper bit is on 10832(i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and 1083316#cd#. The second byte may never be a format control character, but is 10834not required to be in the upper half. This method can be also used for 10835shift-JIS or EUC where the internal coding matches the external coding. 10836 10837@item Shift JIS Coding 10838A wide character is represented by a two character sequence 16#ab# and 1083916#cd#, with the restrictions described for upper half encoding as 10840described above. The internal character code is the corresponding JIS 10841character according to the standard algorithm for Shift-JIS 10842conversion. Only characters defined in the JIS code set table can be 10843used with this encoding method. 10844 10845@item EUC Coding 10846A wide character is represented by a two character sequence 16#ab# and 1084716#cd#, with both characters being in the upper half. The internal 10848character code is the corresponding JIS character according to the EUC 10849encoding algorithm. Only characters defined in the JIS code set table 10850can be used with this encoding method. 10851 10852@item UTF-8 Coding 10853A wide character is represented using 10854UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO 1085510646-1/Am.2. Depending on the character value, the representation 10856is a one, two, or three byte sequence: 10857 10858@smallexample 1085916#0000#-16#007f#: 2#0xxxxxxx# 1086016#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# 1086116#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# 10862@end smallexample 10863 10864@noindent 10865where the xxx bits correspond to the left-padded bits of the 1086616-bit character value. Note that all lower half ASCII characters 10867are represented as ASCII bytes and all upper half characters and 10868other wide characters are represented as sequences of upper-half 10869(The full UTF-8 scheme allows for encoding 31-bit characters as 108706-byte sequences, but in this implementation, all UTF-8 sequences 10871of four or more bytes length will raise a Constraint_Error, as 10872will all invalid UTF-8 sequences.) 10873 10874@item Brackets Coding 10875In this encoding, a wide character is represented by the following eight 10876character sequence: 10877 10878@smallexample 10879[ " a b c d " ] 10880@end smallexample 10881 10882@noindent 10883where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal 10884characters (using uppercase letters) of the wide character code. For 10885example, @code{["A345"]} is used to represent the wide character with code 10886@code{16#A345#}. 10887This scheme is compatible with use of the full Wide_Character set. 10888On input, brackets coding can also be used for upper half characters, 10889e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation 10890is only used for wide characters with a code greater than @code{16#FF#}. 10891 10892@end table 10893 10894@noindent 10895For the coding schemes other than Hex and Brackets encoding, 10896not all wide character 10897values can be represented. An attempt to output a character that cannot 10898be represented using the encoding scheme for the file causes 10899Constraint_Error to be raised. An invalid wide character sequence on 10900input also causes Constraint_Error to be raised. 10901 10902@menu 10903* Wide_Text_IO Stream Pointer Positioning:: 10904* Wide_Text_IO Reading and Writing Non-Regular Files:: 10905@end menu 10906 10907@node Wide_Text_IO Stream Pointer Positioning 10908@subsection Stream Pointer Positioning 10909 10910@noindent 10911@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling 10912of stream pointer positioning (@pxref{Text_IO}). There is one additional 10913case: 10914 10915If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the 10916normal lower ASCII set (i.e.@: a character in the range: 10917 10918@smallexample @c ada 10919Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) 10920@end smallexample 10921 10922@noindent 10923then although the logical position of the file pointer is unchanged by 10924the @code{Look_Ahead} call, the stream is physically positioned past the 10925wide character sequence. Again this is to avoid the need for buffering 10926or backup, and all @code{Wide_Text_IO} routines check the internal 10927indication that this situation has occurred so that this is not visible 10928to a normal program using @code{Wide_Text_IO}. However, this discrepancy 10929can be observed if the wide text file shares a stream with another file. 10930 10931@node Wide_Text_IO Reading and Writing Non-Regular Files 10932@subsection Reading and Writing Non-Regular Files 10933 10934@noindent 10935As in the case of Text_IO, when a non-regular file is read, it is 10936assumed that the file contains no page marks (any form characters are 10937treated as data characters), and @code{End_Of_Page} always returns 10938@code{False}. Similarly, the end of file indication is not sticky, so 10939it is possible to read beyond an end of file. 10940 10941@node Stream_IO 10942@section Stream_IO 10943 10944@noindent 10945A stream file is a sequence of bytes, where individual elements are 10946written to the file as described in the Ada 95 reference manual. The type 10947@code{Stream_Element} is simply a byte. There are two ways to read or 10948write a stream file. 10949 10950@itemize @bullet 10951@item 10952The operations @code{Read} and @code{Write} directly read or write a 10953sequence of stream elements with no control information. 10954 10955@item 10956The stream attributes applied to a stream file transfer data in the 10957manner described for stream attributes. 10958@end itemize 10959 10960@node Shared Files 10961@section Shared Files 10962 10963@noindent 10964Section A.14 of the Ada 95 Reference Manual allows implementations to 10965provide a wide variety of behavior if an attempt is made to access the 10966same external file with two or more internal files. 10967 10968To provide a full range of functionality, while at the same time 10969minimizing the problems of portability caused by this implementation 10970dependence, GNAT handles file sharing as follows: 10971 10972@itemize @bullet 10973@item 10974In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt 10975to open two or more files with the same full name is considered an error 10976and is not supported. The exception @code{Use_Error} will be 10977raised. Note that a file that is not explicitly closed by the program 10978remains open until the program terminates. 10979 10980@item 10981If the form parameter @samp{shared=no} appears in the form string, the 10982file can be opened or created with its own separate stream identifier, 10983regardless of whether other files sharing the same external file are 10984opened. The exact effect depends on how the C stream routines handle 10985multiple accesses to the same external files using separate streams. 10986 10987@item 10988If the form parameter @samp{shared=yes} appears in the form string for 10989each of two or more files opened using the same full name, the same 10990stream is shared between these files, and the semantics are as described 10991in Ada 95 Reference Manual, Section A.14. 10992@end itemize 10993 10994@noindent 10995When a program that opens multiple files with the same name is ported 10996from another Ada compiler to GNAT, the effect will be that 10997@code{Use_Error} is raised. 10998 10999The documentation of the original compiler and the documentation of the 11000program should then be examined to determine if file sharing was 11001expected, and @samp{shared=@var{xxx}} parameters added to @code{Open} 11002and @code{Create} calls as required. 11003 11004When a program is ported from GNAT to some other Ada compiler, no 11005special attention is required unless the @samp{shared=@var{xxx}} form 11006parameter is used in the program. In this case, you must examine the 11007documentation of the new compiler to see if it supports the required 11008file sharing semantics, and form strings modified appropriately. Of 11009course it may be the case that the program cannot be ported if the 11010target compiler does not support the required functionality. The best 11011approach in writing portable code is to avoid file sharing (and hence 11012the use of the @samp{shared=@var{xxx}} parameter in the form string) 11013completely. 11014 11015One common use of file sharing in Ada 83 is the use of instantiations of 11016Sequential_IO on the same file with different types, to achieve 11017heterogeneous input-output. Although this approach will work in GNAT if 11018@samp{shared=yes} is specified, it is preferable in Ada 95 to use Stream_IO 11019for this purpose (using the stream attributes) 11020 11021@node Open Modes 11022@section Open Modes 11023 11024@noindent 11025@code{Open} and @code{Create} calls result in a call to @code{fopen} 11026using the mode shown in the following table: 11027 11028@sp 2 11029@center @code{Open} and @code{Create} Call Modes 11030@smallexample 11031 @b{OPEN } @b{CREATE} 11032Append_File "r+" "w+" 11033In_File "r" "w+" 11034Out_File (Direct_IO) "r+" "w" 11035Out_File (all other cases) "w" "w" 11036Inout_File "r+" "w+" 11037@end smallexample 11038 11039@noindent 11040If text file translation is required, then either @samp{b} or @samp{t} 11041is added to the mode, depending on the setting of Text. Text file 11042translation refers to the mapping of CR/LF sequences in an external file 11043to LF characters internally. This mapping only occurs in DOS and 11044DOS-like systems, and is not relevant to other systems. 11045 11046A special case occurs with Stream_IO@. As shown in the above table, the 11047file is initially opened in @samp{r} or @samp{w} mode for the 11048@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation 11049subsequently requires switching from reading to writing or vice-versa, 11050then the file is reopened in @samp{r+} mode to permit the required operation. 11051 11052@node Operations on C Streams 11053@section Operations on C Streams 11054The package @code{Interfaces.C_Streams} provides an Ada program with direct 11055access to the C library functions for operations on C streams: 11056 11057@smallexample @c adanocomment 11058package Interfaces.C_Streams is 11059 -- Note: the reason we do not use the types that are in 11060 -- Interfaces.C is that we want to avoid dragging in the 11061 -- code in this unit if possible. 11062 subtype chars is System.Address; 11063 -- Pointer to null-terminated array of characters 11064 subtype FILEs is System.Address; 11065 -- Corresponds to the C type FILE* 11066 subtype voids is System.Address; 11067 -- Corresponds to the C type void* 11068 subtype int is Integer; 11069 subtype long is Long_Integer; 11070 -- Note: the above types are subtypes deliberately, and it 11071 -- is part of this spec that the above correspondences are 11072 -- guaranteed. This means that it is legitimate to, for 11073 -- example, use Integer instead of int. We provide these 11074 -- synonyms for clarity, but in some cases it may be 11075 -- convenient to use the underlying types (for example to 11076 -- avoid an unnecessary dependency of a spec on the spec 11077 -- of this unit). 11078 type size_t is mod 2 ** Standard'Address_Size; 11079 NULL_Stream : constant FILEs; 11080 -- Value returned (NULL in C) to indicate an 11081 -- fdopen/fopen/tmpfile error 11082 ---------------------------------- 11083 -- Constants Defined in stdio.h -- 11084 ---------------------------------- 11085 EOF : constant int; 11086 -- Used by a number of routines to indicate error or 11087 -- end of file 11088 IOFBF : constant int; 11089 IOLBF : constant int; 11090 IONBF : constant int; 11091 -- Used to indicate buffering mode for setvbuf call 11092 SEEK_CUR : constant int; 11093 SEEK_END : constant int; 11094 SEEK_SET : constant int; 11095 -- Used to indicate origin for fseek call 11096 function stdin return FILEs; 11097 function stdout return FILEs; 11098 function stderr return FILEs; 11099 -- Streams associated with standard files 11100 -------------------------- 11101 -- Standard C functions -- 11102 -------------------------- 11103 -- The functions selected below are ones that are 11104 -- available in DOS, OS/2, UNIX and Xenix (but not 11105 -- necessarily in ANSI C). These are very thin interfaces 11106 -- which copy exactly the C headers. For more 11107 -- documentation on these functions, see the Microsoft C 11108 -- "Run-Time Library Reference" (Microsoft Press, 1990, 11109 -- ISBN 1-55615-225-6), which includes useful information 11110 -- on system compatibility. 11111 procedure clearerr (stream : FILEs); 11112 function fclose (stream : FILEs) return int; 11113 function fdopen (handle : int; mode : chars) return FILEs; 11114 function feof (stream : FILEs) return int; 11115 function ferror (stream : FILEs) return int; 11116 function fflush (stream : FILEs) return int; 11117 function fgetc (stream : FILEs) return int; 11118 function fgets (strng : chars; n : int; stream : FILEs) 11119 return chars; 11120 function fileno (stream : FILEs) return int; 11121 function fopen (filename : chars; Mode : chars) 11122 return FILEs; 11123 -- Note: to maintain target independence, use 11124 -- text_translation_required, a boolean variable defined in 11125 -- a-sysdep.c to deal with the target dependent text 11126 -- translation requirement. If this variable is set, 11127 -- then b/t should be appended to the standard mode 11128 -- argument to set the text translation mode off or on 11129 -- as required. 11130 function fputc (C : int; stream : FILEs) return int; 11131 function fputs (Strng : chars; Stream : FILEs) return int; 11132 function fread 11133 (buffer : voids; 11134 size : size_t; 11135 count : size_t; 11136 stream : FILEs) 11137 return size_t; 11138 function freopen 11139 (filename : chars; 11140 mode : chars; 11141 stream : FILEs) 11142 return FILEs; 11143 function fseek 11144 (stream : FILEs; 11145 offset : long; 11146 origin : int) 11147 return int; 11148 function ftell (stream : FILEs) return long; 11149 function fwrite 11150 (buffer : voids; 11151 size : size_t; 11152 count : size_t; 11153 stream : FILEs) 11154 return size_t; 11155 function isatty (handle : int) return int; 11156 procedure mktemp (template : chars); 11157 -- The return value (which is just a pointer to template) 11158 -- is discarded 11159 procedure rewind (stream : FILEs); 11160 function rmtmp return int; 11161 function setvbuf 11162 (stream : FILEs; 11163 buffer : chars; 11164 mode : int; 11165 size : size_t) 11166 return int; 11167 11168 function tmpfile return FILEs; 11169 function ungetc (c : int; stream : FILEs) return int; 11170 function unlink (filename : chars) return int; 11171 --------------------- 11172 -- Extra functions -- 11173 --------------------- 11174 -- These functions supply slightly thicker bindings than 11175 -- those above. They are derived from functions in the 11176 -- C Run-Time Library, but may do a bit more work than 11177 -- just directly calling one of the Library functions. 11178 function is_regular_file (handle : int) return int; 11179 -- Tests if given handle is for a regular file (result 1) 11180 -- or for a non-regular file (pipe or device, result 0). 11181 --------------------------------- 11182 -- Control of Text/Binary Mode -- 11183 --------------------------------- 11184 -- If text_translation_required is true, then the following 11185 -- functions may be used to dynamically switch a file from 11186 -- binary to text mode or vice versa. These functions have 11187 -- no effect if text_translation_required is false (i.e. in 11188 -- normal UNIX mode). Use fileno to get a stream handle. 11189 procedure set_binary_mode (handle : int); 11190 procedure set_text_mode (handle : int); 11191 ---------------------------- 11192 -- Full Path Name support -- 11193 ---------------------------- 11194 procedure full_name (nam : chars; buffer : chars); 11195 -- Given a NUL terminated string representing a file 11196 -- name, returns in buffer a NUL terminated string 11197 -- representing the full path name for the file name. 11198 -- On systems where it is relevant the drive is also 11199 -- part of the full path name. It is the responsibility 11200 -- of the caller to pass an actual parameter for buffer 11201 -- that is big enough for any full path name. Use 11202 -- max_path_len given below as the size of buffer. 11203 max_path_len : integer; 11204 -- Maximum length of an allowable full path name on the 11205 -- system, including a terminating NUL character. 11206end Interfaces.C_Streams; 11207@end smallexample 11208 11209@node Interfacing to C Streams 11210@section Interfacing to C Streams 11211 11212@noindent 11213The packages in this section permit interfacing Ada files to C Stream 11214operations. 11215 11216@smallexample @c ada 11217 with Interfaces.C_Streams; 11218 package Ada.Sequential_IO.C_Streams is 11219 function C_Stream (F : File_Type) 11220 return Interfaces.C_Streams.FILEs; 11221 procedure Open 11222 (File : in out File_Type; 11223 Mode : in File_Mode; 11224 C_Stream : in Interfaces.C_Streams.FILEs; 11225 Form : in String := ""); 11226 end Ada.Sequential_IO.C_Streams; 11227 11228 with Interfaces.C_Streams; 11229 package Ada.Direct_IO.C_Streams is 11230 function C_Stream (F : File_Type) 11231 return Interfaces.C_Streams.FILEs; 11232 procedure Open 11233 (File : in out File_Type; 11234 Mode : in File_Mode; 11235 C_Stream : in Interfaces.C_Streams.FILEs; 11236 Form : in String := ""); 11237 end Ada.Direct_IO.C_Streams; 11238 11239 with Interfaces.C_Streams; 11240 package Ada.Text_IO.C_Streams is 11241 function C_Stream (F : File_Type) 11242 return Interfaces.C_Streams.FILEs; 11243 procedure Open 11244 (File : in out File_Type; 11245 Mode : in File_Mode; 11246 C_Stream : in Interfaces.C_Streams.FILEs; 11247 Form : in String := ""); 11248 end Ada.Text_IO.C_Streams; 11249 11250 with Interfaces.C_Streams; 11251 package Ada.Wide_Text_IO.C_Streams is 11252 function C_Stream (F : File_Type) 11253 return Interfaces.C_Streams.FILEs; 11254 procedure Open 11255 (File : in out File_Type; 11256 Mode : in File_Mode; 11257 C_Stream : in Interfaces.C_Streams.FILEs; 11258 Form : in String := ""); 11259 end Ada.Wide_Text_IO.C_Streams; 11260 11261 with Interfaces.C_Streams; 11262 package Ada.Stream_IO.C_Streams is 11263 function C_Stream (F : File_Type) 11264 return Interfaces.C_Streams.FILEs; 11265 procedure Open 11266 (File : in out File_Type; 11267 Mode : in File_Mode; 11268 C_Stream : in Interfaces.C_Streams.FILEs; 11269 Form : in String := ""); 11270 end Ada.Stream_IO.C_Streams; 11271@end smallexample 11272 11273@noindent 11274In each of these five packages, the @code{C_Stream} function obtains the 11275@code{FILE} pointer from a currently opened Ada file. It is then 11276possible to use the @code{Interfaces.C_Streams} package to operate on 11277this stream, or the stream can be passed to a C program which can 11278operate on it directly. Of course the program is responsible for 11279ensuring that only appropriate sequences of operations are executed. 11280 11281One particular use of relevance to an Ada program is that the 11282@code{setvbuf} function can be used to control the buffering of the 11283stream used by an Ada file. In the absence of such a call the standard 11284default buffering is used. 11285 11286The @code{Open} procedures in these packages open a file giving an 11287existing C Stream instead of a file name. Typically this stream is 11288imported from a C program, allowing an Ada file to operate on an 11289existing C file. 11290 11291@node The GNAT Library 11292@chapter The GNAT Library 11293 11294@noindent 11295The GNAT library contains a number of general and special purpose packages. 11296It represents functionality that the GNAT developers have found useful, and 11297which is made available to GNAT users. The packages described here are fully 11298supported, and upwards compatibility will be maintained in future releases, 11299so you can use these facilities with the confidence that the same functionality 11300will be available in future releases. 11301 11302The chapter here simply gives a brief summary of the facilities available. 11303The full documentation is found in the spec file for the package. The full 11304sources of these library packages, including both spec and body, are provided 11305with all GNAT releases. For example, to find out the full specifications of 11306the SPITBOL pattern matching capability, including a full tutorial and 11307extensive examples, look in the @file{g-spipat.ads} file in the library. 11308 11309For each entry here, the package name (as it would appear in a @code{with} 11310clause) is given, followed by the name of the corresponding spec file in 11311parentheses. The packages are children in four hierarchies, @code{Ada}, 11312@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a 11313GNAT-specific hierarchy. 11314 11315Note that an application program should only use packages in one of these 11316four hierarchies if the package is defined in the Ada Reference Manual, 11317or is listed in this section of the GNAT Programmers Reference Manual. 11318All other units should be considered internal implementation units and 11319should not be directly @code{with}'ed by application code. The use of 11320a @code{with} statement that references one of these internal implementation 11321units makes an application potentially dependent on changes in versions 11322of GNAT, and will generate a warning message. 11323 11324@menu 11325* Ada.Characters.Latin_9 (a-chlat9.ads):: 11326* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: 11327* Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: 11328* Ada.Command_Line.Remove (a-colire.ads):: 11329* Ada.Command_Line.Environment (a-colien.ads):: 11330* Ada.Direct_IO.C_Streams (a-diocst.ads):: 11331* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: 11332* Ada.Exceptions.Traceback (a-exctra.ads):: 11333* Ada.Sequential_IO.C_Streams (a-siocst.ads):: 11334* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: 11335* Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: 11336* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: 11337* Ada.Text_IO.C_Streams (a-tiocst.ads):: 11338* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: 11339* GNAT.Array_Split (g-arrspl.ads):: 11340* GNAT.AWK (g-awk.ads):: 11341* GNAT.Bounded_Buffers (g-boubuf.ads):: 11342* GNAT.Bounded_Mailboxes (g-boumai.ads):: 11343* GNAT.Bubble_Sort (g-bubsor.ads):: 11344* GNAT.Bubble_Sort_A (g-busora.ads):: 11345* GNAT.Bubble_Sort_G (g-busorg.ads):: 11346* GNAT.Calendar (g-calend.ads):: 11347* GNAT.Calendar.Time_IO (g-catiio.ads):: 11348* GNAT.CRC32 (g-crc32.ads):: 11349* GNAT.Case_Util (g-casuti.ads):: 11350* GNAT.CGI (g-cgi.ads):: 11351* GNAT.CGI.Cookie (g-cgicoo.ads):: 11352* GNAT.CGI.Debug (g-cgideb.ads):: 11353* GNAT.Command_Line (g-comlin.ads):: 11354* GNAT.Compiler_Version (g-comver.ads):: 11355* GNAT.Ctrl_C (g-ctrl_c.ads):: 11356* GNAT.Current_Exception (g-curexc.ads):: 11357* GNAT.Debug_Pools (g-debpoo.ads):: 11358* GNAT.Debug_Utilities (g-debuti.ads):: 11359* GNAT.Directory_Operations (g-dirope.ads):: 11360* GNAT.Dynamic_HTables (g-dynhta.ads):: 11361* GNAT.Dynamic_Tables (g-dyntab.ads):: 11362* GNAT.Exception_Actions (g-excact.ads):: 11363* GNAT.Exception_Traces (g-exctra.ads):: 11364* GNAT.Exceptions (g-except.ads):: 11365* GNAT.Expect (g-expect.ads):: 11366* GNAT.Float_Control (g-flocon.ads):: 11367* GNAT.Heap_Sort (g-heasor.ads):: 11368* GNAT.Heap_Sort_A (g-hesora.ads):: 11369* GNAT.Heap_Sort_G (g-hesorg.ads):: 11370* GNAT.HTable (g-htable.ads):: 11371* GNAT.IO (g-io.ads):: 11372* GNAT.IO_Aux (g-io_aux.ads):: 11373* GNAT.Lock_Files (g-locfil.ads):: 11374* GNAT.MD5 (g-md5.ads):: 11375* GNAT.Memory_Dump (g-memdum.ads):: 11376* GNAT.Most_Recent_Exception (g-moreex.ads):: 11377* GNAT.OS_Lib (g-os_lib.ads):: 11378* GNAT.Perfect_Hash.Generators (g-pehage.ads):: 11379* GNAT.Regexp (g-regexp.ads):: 11380* GNAT.Registry (g-regist.ads):: 11381* GNAT.Regpat (g-regpat.ads):: 11382* GNAT.Secondary_Stack_Info (g-sestin.ads):: 11383* GNAT.Semaphores (g-semaph.ads):: 11384* GNAT.Signals (g-signal.ads):: 11385* GNAT.Sockets (g-socket.ads):: 11386* GNAT.Source_Info (g-souinf.ads):: 11387* GNAT.Spell_Checker (g-speche.ads):: 11388* GNAT.Spitbol.Patterns (g-spipat.ads):: 11389* GNAT.Spitbol (g-spitbo.ads):: 11390* GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: 11391* GNAT.Spitbol.Table_Integer (g-sptain.ads):: 11392* GNAT.Spitbol.Table_VString (g-sptavs.ads):: 11393* GNAT.Strings (g-string.ads):: 11394* GNAT.String_Split (g-strspl.ads):: 11395* GNAT.Table (g-table.ads):: 11396* GNAT.Task_Lock (g-tasloc.ads):: 11397* GNAT.Threads (g-thread.ads):: 11398* GNAT.Traceback (g-traceb.ads):: 11399* GNAT.Traceback.Symbolic (g-trasym.ads):: 11400* GNAT.Wide_String_Split (g-wistsp.ads):: 11401* Interfaces.C.Extensions (i-cexten.ads):: 11402* Interfaces.C.Streams (i-cstrea.ads):: 11403* Interfaces.CPP (i-cpp.ads):: 11404* Interfaces.Os2lib (i-os2lib.ads):: 11405* Interfaces.Os2lib.Errors (i-os2err.ads):: 11406* Interfaces.Os2lib.Synchronization (i-os2syn.ads):: 11407* Interfaces.Os2lib.Threads (i-os2thr.ads):: 11408* Interfaces.Packed_Decimal (i-pacdec.ads):: 11409* Interfaces.VxWorks (i-vxwork.ads):: 11410* Interfaces.VxWorks.IO (i-vxwoio.ads):: 11411* System.Address_Image (s-addima.ads):: 11412* System.Assertions (s-assert.ads):: 11413* System.Memory (s-memory.ads):: 11414* System.Partition_Interface (s-parint.ads):: 11415* System.Task_Info (s-tasinf.ads):: 11416* System.Wch_Cnv (s-wchcnv.ads):: 11417* System.Wch_Con (s-wchcon.ads):: 11418@end menu 11419 11420@node Ada.Characters.Latin_9 (a-chlat9.ads) 11421@section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) 11422@cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) 11423@cindex Latin_9 constants for Character 11424 11425@noindent 11426This child of @code{Ada.Characters} 11427provides a set of definitions corresponding to those in the 11428RM-defined package @code{Ada.Characters.Latin_1} but with the 11429few modifications required for @code{Latin-9} 11430The provision of such a package 11431is specifically authorized by the Ada Reference Manual 11432(RM A.3(27)). 11433 11434@node Ada.Characters.Wide_Latin_1 (a-cwila1.ads) 11435@section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) 11436@cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) 11437@cindex Latin_1 constants for Wide_Character 11438 11439@noindent 11440This child of @code{Ada.Characters} 11441provides a set of definitions corresponding to those in the 11442RM-defined package @code{Ada.Characters.Latin_1} but with the 11443types of the constants being @code{Wide_Character} 11444instead of @code{Character}. The provision of such a package 11445is specifically authorized by the Ada Reference Manual 11446(RM A.3(27)). 11447 11448@node Ada.Characters.Wide_Latin_9 (a-cwila9.ads) 11449@section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) 11450@cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) 11451@cindex Latin_9 constants for Wide_Character 11452 11453@noindent 11454This child of @code{Ada.Characters} 11455provides a set of definitions corresponding to those in the 11456GNAT defined package @code{Ada.Characters.Latin_9} but with the 11457types of the constants being @code{Wide_Character} 11458instead of @code{Character}. The provision of such a package 11459is specifically authorized by the Ada Reference Manual 11460(RM A.3(27)). 11461 11462@node Ada.Command_Line.Remove (a-colire.ads) 11463@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) 11464@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) 11465@cindex Removing command line arguments 11466@cindex Command line, argument removal 11467 11468@noindent 11469This child of @code{Ada.Command_Line} 11470provides a mechanism for logically removing 11471arguments from the argument list. Once removed, an argument is not visible 11472to further calls on the subprograms in @code{Ada.Command_Line} will not 11473see the removed argument. 11474 11475@node Ada.Command_Line.Environment (a-colien.ads) 11476@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) 11477@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) 11478@cindex Environment entries 11479 11480@noindent 11481This child of @code{Ada.Command_Line} 11482provides a mechanism for obtaining environment values on systems 11483where this concept makes sense. 11484 11485@node Ada.Direct_IO.C_Streams (a-diocst.ads) 11486@section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) 11487@cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) 11488@cindex C Streams, Interfacing with Direct_IO 11489 11490@noindent 11491This package provides subprograms that allow interfacing between 11492C streams and @code{Direct_IO}. The stream identifier can be 11493extracted from a file opened on the Ada side, and an Ada file 11494can be constructed from a stream opened on the C side. 11495 11496@node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) 11497@section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) 11498@cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) 11499@cindex Null_Occurrence, testing for 11500 11501@noindent 11502This child subprogram provides a way of testing for the null 11503exception occurrence (@code{Null_Occurrence}) without raising 11504an exception. 11505 11506@node Ada.Exceptions.Traceback (a-exctra.ads) 11507@section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) 11508@cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) 11509@cindex Traceback for Exception Occurrence 11510 11511@noindent 11512This child package provides the subprogram (@code{Tracebacks}) to 11513give a traceback array of addresses based on an exception 11514occurrence. 11515 11516@node Ada.Sequential_IO.C_Streams (a-siocst.ads) 11517@section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) 11518@cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) 11519@cindex C Streams, Interfacing with Sequential_IO 11520 11521@noindent 11522This package provides subprograms that allow interfacing between 11523C streams and @code{Sequential_IO}. The stream identifier can be 11524extracted from a file opened on the Ada side, and an Ada file 11525can be constructed from a stream opened on the C side. 11526 11527@node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) 11528@section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) 11529@cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) 11530@cindex C Streams, Interfacing with Stream_IO 11531 11532@noindent 11533This package provides subprograms that allow interfacing between 11534C streams and @code{Stream_IO}. The stream identifier can be 11535extracted from a file opened on the Ada side, and an Ada file 11536can be constructed from a stream opened on the C side. 11537 11538@node Ada.Strings.Unbounded.Text_IO (a-suteio.ads) 11539@section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) 11540@cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) 11541@cindex @code{Unbounded_String}, IO support 11542@cindex @code{Text_IO}, extensions for unbounded strings 11543 11544@noindent 11545This package provides subprograms for Text_IO for unbounded 11546strings, avoiding the necessity for an intermediate operation 11547with ordinary strings. 11548 11549@node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) 11550@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) 11551@cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) 11552@cindex @code{Unbounded_Wide_String}, IO support 11553@cindex @code{Text_IO}, extensions for unbounded wide strings 11554 11555@noindent 11556This package provides subprograms for Text_IO for unbounded 11557wide strings, avoiding the necessity for an intermediate operation 11558with ordinary wide strings. 11559 11560@node Ada.Text_IO.C_Streams (a-tiocst.ads) 11561@section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) 11562@cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) 11563@cindex C Streams, Interfacing with @code{Text_IO} 11564 11565@noindent 11566This package provides subprograms that allow interfacing between 11567C streams and @code{Text_IO}. The stream identifier can be 11568extracted from a file opened on the Ada side, and an Ada file 11569can be constructed from a stream opened on the C side. 11570 11571@node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) 11572@section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) 11573@cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) 11574@cindex C Streams, Interfacing with @code{Wide_Text_IO} 11575 11576@noindent 11577This package provides subprograms that allow interfacing between 11578C streams and @code{Wide_Text_IO}. The stream identifier can be 11579extracted from a file opened on the Ada side, and an Ada file 11580can be constructed from a stream opened on the C side. 11581 11582@node GNAT.Array_Split (g-arrspl.ads) 11583@section @code{GNAT.Array_Split} (@file{g-arrspl.ads}) 11584@cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads}) 11585@cindex Array splitter 11586 11587@noindent 11588Useful array-manipulation routines: given a set of separators, split 11589an array wherever the separators appear, and provide direct access 11590to the resulting slices. 11591 11592@node GNAT.AWK (g-awk.ads) 11593@section @code{GNAT.AWK} (@file{g-awk.ads}) 11594@cindex @code{GNAT.AWK} (@file{g-awk.ads}) 11595@cindex Parsing 11596@cindex AWK 11597 11598@noindent 11599Provides AWK-like parsing functions, with an easy interface for parsing one 11600or more files containing formatted data. The file is viewed as a database 11601where each record is a line and a field is a data element in this line. 11602 11603@node GNAT.Bounded_Buffers (g-boubuf.ads) 11604@section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) 11605@cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) 11606@cindex Parsing 11607@cindex Bounded Buffers 11608 11609@noindent 11610Provides a concurrent generic bounded buffer abstraction. Instances are 11611useful directly or as parts of the implementations of other abstractions, 11612such as mailboxes. 11613 11614@node GNAT.Bounded_Mailboxes (g-boumai.ads) 11615@section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) 11616@cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) 11617@cindex Parsing 11618@cindex Mailboxes 11619 11620@noindent 11621Provides a thread-safe asynchronous intertask mailbox communication facility. 11622 11623@node GNAT.Bubble_Sort (g-bubsor.ads) 11624@section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) 11625@cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) 11626@cindex Sorting 11627@cindex Bubble sort 11628 11629@noindent 11630Provides a general implementation of bubble sort usable for sorting arbitrary 11631data items. Exchange and comparison procedures are provided by passing 11632access-to-procedure values. 11633 11634@node GNAT.Bubble_Sort_A (g-busora.ads) 11635@section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) 11636@cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) 11637@cindex Sorting 11638@cindex Bubble sort 11639 11640@noindent 11641Provides a general implementation of bubble sort usable for sorting arbitrary 11642data items. Move and comparison procedures are provided by passing 11643access-to-procedure values. This is an older version, retained for 11644compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. 11645 11646@node GNAT.Bubble_Sort_G (g-busorg.ads) 11647@section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) 11648@cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) 11649@cindex Sorting 11650@cindex Bubble sort 11651 11652@noindent 11653Similar to @code{Bubble_Sort_A} except that the move and sorting procedures 11654are provided as generic parameters, this improves efficiency, especially 11655if the procedures can be inlined, at the expense of duplicating code for 11656multiple instantiations. 11657 11658@node GNAT.Calendar (g-calend.ads) 11659@section @code{GNAT.Calendar} (@file{g-calend.ads}) 11660@cindex @code{GNAT.Calendar} (@file{g-calend.ads}) 11661@cindex @code{Calendar} 11662 11663@noindent 11664Extends the facilities provided by @code{Ada.Calendar} to include handling 11665of days of the week, an extended @code{Split} and @code{Time_Of} capability. 11666Also provides conversion of @code{Ada.Calendar.Time} values to and from the 11667C @code{timeval} format. 11668 11669@node GNAT.Calendar.Time_IO (g-catiio.ads) 11670@section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) 11671@cindex @code{Calendar} 11672@cindex Time 11673@cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) 11674 11675@node GNAT.CRC32 (g-crc32.ads) 11676@section @code{GNAT.CRC32} (@file{g-crc32.ads}) 11677@cindex @code{GNAT.CRC32} (@file{g-crc32.ads}) 11678@cindex CRC32 11679@cindex Cyclic Redundancy Check 11680 11681@noindent 11682This package implements the CRC-32 algorithm. For a full description 11683of this algorithm see 11684``Computation of Cyclic Redundancy Checks via Table Look-Up'', 11685@cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013, 11686Aug.@: 1988. Sarwate, D.V@. 11687 11688@noindent 11689Provides an extended capability for formatted output of time values with 11690full user control over the format. Modeled on the GNU Date specification. 11691 11692@node GNAT.Case_Util (g-casuti.ads) 11693@section @code{GNAT.Case_Util} (@file{g-casuti.ads}) 11694@cindex @code{GNAT.Case_Util} (@file{g-casuti.ads}) 11695@cindex Casing utilities 11696@cindex Character handling (@code{GNAT.Case_Util}) 11697 11698@noindent 11699A set of simple routines for handling upper and lower casing of strings 11700without the overhead of the full casing tables 11701in @code{Ada.Characters.Handling}. 11702 11703@node GNAT.CGI (g-cgi.ads) 11704@section @code{GNAT.CGI} (@file{g-cgi.ads}) 11705@cindex @code{GNAT.CGI} (@file{g-cgi.ads}) 11706@cindex CGI (Common Gateway Interface) 11707 11708@noindent 11709This is a package for interfacing a GNAT program with a Web server via the 11710Common Gateway Interface (CGI)@. Basically this package parses the CGI 11711parameters, which are a set of key/value pairs sent by the Web server. It 11712builds a table whose index is the key and provides some services to deal 11713with this table. 11714 11715@node GNAT.CGI.Cookie (g-cgicoo.ads) 11716@section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) 11717@cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) 11718@cindex CGI (Common Gateway Interface) cookie support 11719@cindex Cookie support in CGI 11720 11721@noindent 11722This is a package to interface a GNAT program with a Web server via the 11723Common Gateway Interface (CGI). It exports services to deal with Web 11724cookies (piece of information kept in the Web client software). 11725 11726@node GNAT.CGI.Debug (g-cgideb.ads) 11727@section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) 11728@cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) 11729@cindex CGI (Common Gateway Interface) debugging 11730 11731@noindent 11732This is a package to help debugging CGI (Common Gateway Interface) 11733programs written in Ada. 11734 11735@node GNAT.Command_Line (g-comlin.ads) 11736@section @code{GNAT.Command_Line} (@file{g-comlin.ads}) 11737@cindex @code{GNAT.Command_Line} (@file{g-comlin.ads}) 11738@cindex Command line 11739 11740@noindent 11741Provides a high level interface to @code{Ada.Command_Line} facilities, 11742including the ability to scan for named switches with optional parameters 11743and expand file names using wild card notations. 11744 11745@node GNAT.Compiler_Version (g-comver.ads) 11746@section @code{GNAT.Compiler_Version} (@file{g-comver.ads}) 11747@cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads}) 11748@cindex Compiler Version 11749@cindex Version, of compiler 11750 11751@noindent 11752Provides a routine for obtaining the version of the compiler used to 11753compile the program. More accurately this is the version of the binder 11754used to bind the program (this will normally be the same as the version 11755of the compiler if a consistent tool set is used to compile all units 11756of a partition). 11757 11758@node GNAT.Ctrl_C (g-ctrl_c.ads) 11759@section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) 11760@cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) 11761@cindex Interrupt 11762 11763@noindent 11764Provides a simple interface to handle Ctrl-C keyboard events. 11765 11766@node GNAT.Current_Exception (g-curexc.ads) 11767@section @code{GNAT.Current_Exception} (@file{g-curexc.ads}) 11768@cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads}) 11769@cindex Current exception 11770@cindex Exception retrieval 11771 11772@noindent 11773Provides access to information on the current exception that has been raised 11774without the need for using the Ada-95 exception choice parameter specification 11775syntax. This is particularly useful in simulating typical facilities for 11776obtaining information about exceptions provided by Ada 83 compilers. 11777 11778@node GNAT.Debug_Pools (g-debpoo.ads) 11779@section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) 11780@cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) 11781@cindex Debugging 11782@cindex Debug pools 11783@cindex Memory corruption debugging 11784 11785@noindent 11786Provide a debugging storage pools that helps tracking memory corruption 11787problems. See section ``Finding memory problems with GNAT Debug Pool'' in 11788the @cite{GNAT User's Guide}. 11789 11790@node GNAT.Debug_Utilities (g-debuti.ads) 11791@section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) 11792@cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) 11793@cindex Debugging 11794 11795@noindent 11796Provides a few useful utilities for debugging purposes, including conversion 11797to and from string images of address values. Supports both C and Ada formats 11798for hexadecimal literals. 11799 11800@node GNAT.Directory_Operations (g-dirope.ads) 11801@section @code{GNAT.Directory_Operations} (g-dirope.ads) 11802@cindex @code{GNAT.Directory_Operations} (g-dirope.ads) 11803@cindex Directory operations 11804 11805@noindent 11806Provides a set of routines for manipulating directories, including changing 11807the current directory, making new directories, and scanning the files in a 11808directory. 11809 11810@node GNAT.Dynamic_HTables (g-dynhta.ads) 11811@section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) 11812@cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) 11813@cindex Hash tables 11814 11815@noindent 11816A generic implementation of hash tables that can be used to hash arbitrary 11817data. Provided in two forms, a simple form with built in hash functions, 11818and a more complex form in which the hash function is supplied. 11819 11820@noindent 11821This package provides a facility similar to that of @code{GNAT.HTable}, 11822except that this package declares a type that can be used to define 11823dynamic instances of the hash table, while an instantiation of 11824@code{GNAT.HTable} creates a single instance of the hash table. 11825 11826@node GNAT.Dynamic_Tables (g-dyntab.ads) 11827@section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) 11828@cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) 11829@cindex Table implementation 11830@cindex Arrays, extendable 11831 11832@noindent 11833A generic package providing a single dimension array abstraction where the 11834length of the array can be dynamically modified. 11835 11836@noindent 11837This package provides a facility similar to that of @code{GNAT.Table}, 11838except that this package declares a type that can be used to define 11839dynamic instances of the table, while an instantiation of 11840@code{GNAT.Table} creates a single instance of the table type. 11841 11842@node GNAT.Exception_Actions (g-excact.ads) 11843@section @code{GNAT.Exception_Actions} (@file{g-excact.ads}) 11844@cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads}) 11845@cindex Exception actions 11846 11847@noindent 11848Provides callbacks when an exception is raised. Callbacks can be registered 11849for specific exceptions, or when any exception is raised. This 11850can be used for instance to force a core dump to ease debugging. 11851 11852@node GNAT.Exception_Traces (g-exctra.ads) 11853@section @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) 11854@cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) 11855@cindex Exception traces 11856@cindex Debugging 11857 11858@noindent 11859Provides an interface allowing to control automatic output upon exception 11860occurrences. 11861 11862@node GNAT.Exceptions (g-except.ads) 11863@section @code{GNAT.Exceptions} (@file{g-expect.ads}) 11864@cindex @code{GNAT.Exceptions} (@file{g-expect.ads}) 11865@cindex Exceptions, Pure 11866@cindex Pure packages, exceptions 11867 11868@noindent 11869Normally it is not possible to raise an exception with 11870a message from a subprogram in a pure package, since the 11871necessary types and subprograms are in @code{Ada.Exceptions} 11872which is not a pure unit. @code{GNAT.Exceptions} provides a 11873facility for getting around this limitation for a few 11874predefined exceptions, and for example allow raising 11875@code{Constraint_Error} with a message from a pure subprogram. 11876 11877@node GNAT.Expect (g-expect.ads) 11878@section @code{GNAT.Expect} (@file{g-expect.ads}) 11879@cindex @code{GNAT.Expect} (@file{g-expect.ads}) 11880 11881@noindent 11882Provides a set of subprograms similar to what is available 11883with the standard Tcl Expect tool. 11884It allows you to easily spawn and communicate with an external process. 11885You can send commands or inputs to the process, and compare the output 11886with some expected regular expression. Currently @code{GNAT.Expect} 11887is implemented on all native GNAT ports except for OpenVMS@. 11888It is not implemented for cross ports, and in particular is not 11889implemented for VxWorks or LynxOS@. 11890 11891@node GNAT.Float_Control (g-flocon.ads) 11892@section @code{GNAT.Float_Control} (@file{g-flocon.ads}) 11893@cindex @code{GNAT.Float_Control} (@file{g-flocon.ads}) 11894@cindex Floating-Point Processor 11895 11896@noindent 11897Provides an interface for resetting the floating-point processor into the 11898mode required for correct semantic operation in Ada. Some third party 11899library calls may cause this mode to be modified, and the Reset procedure 11900in this package can be used to reestablish the required mode. 11901 11902@node GNAT.Heap_Sort (g-heasor.ads) 11903@section @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) 11904@cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) 11905@cindex Sorting 11906 11907@noindent 11908Provides a general implementation of heap sort usable for sorting arbitrary 11909data items. Exchange and comparison procedures are provided by passing 11910access-to-procedure values. The algorithm used is a modified heap sort 11911that performs approximately N*log(N) comparisons in the worst case. 11912 11913@node GNAT.Heap_Sort_A (g-hesora.ads) 11914@section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) 11915@cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) 11916@cindex Sorting 11917 11918@noindent 11919Provides a general implementation of heap sort usable for sorting arbitrary 11920data items. Move and comparison procedures are provided by passing 11921access-to-procedure values. The algorithm used is a modified heap sort 11922that performs approximately N*log(N) comparisons in the worst case. 11923This differs from @code{GNAT.Heap_Sort} in having a less convenient 11924interface, but may be slightly more efficient. 11925 11926@node GNAT.Heap_Sort_G (g-hesorg.ads) 11927@section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) 11928@cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) 11929@cindex Sorting 11930 11931@noindent 11932Similar to @code{Heap_Sort_A} except that the move and sorting procedures 11933are provided as generic parameters, this improves efficiency, especially 11934if the procedures can be inlined, at the expense of duplicating code for 11935multiple instantiations. 11936 11937@node GNAT.HTable (g-htable.ads) 11938@section @code{GNAT.HTable} (@file{g-htable.ads}) 11939@cindex @code{GNAT.HTable} (@file{g-htable.ads}) 11940@cindex Hash tables 11941 11942@noindent 11943A generic implementation of hash tables that can be used to hash arbitrary 11944data. Provides two approaches, one a simple static approach, and the other 11945allowing arbitrary dynamic hash tables. 11946 11947@node GNAT.IO (g-io.ads) 11948@section @code{GNAT.IO} (@file{g-io.ads}) 11949@cindex @code{GNAT.IO} (@file{g-io.ads}) 11950@cindex Simple I/O 11951@cindex Input/Output facilities 11952 11953@noindent 11954A simple preelaborable input-output package that provides a subset of 11955simple Text_IO functions for reading characters and strings from 11956Standard_Input, and writing characters, strings and integers to either 11957Standard_Output or Standard_Error. 11958 11959@node GNAT.IO_Aux (g-io_aux.ads) 11960@section @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) 11961@cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) 11962@cindex Text_IO 11963@cindex Input/Output facilities 11964 11965Provides some auxiliary functions for use with Text_IO, including a test 11966for whether a file exists, and functions for reading a line of text. 11967 11968@node GNAT.Lock_Files (g-locfil.ads) 11969@section @code{GNAT.Lock_Files} (@file{g-locfil.ads}) 11970@cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads}) 11971@cindex File locking 11972@cindex Locking using files 11973 11974@noindent 11975Provides a general interface for using files as locks. Can be used for 11976providing program level synchronization. 11977 11978@node GNAT.MD5 (g-md5.ads) 11979@section @code{GNAT.MD5} (@file{g-md5.ads}) 11980@cindex @code{GNAT.MD5} (@file{g-md5.ads}) 11981@cindex Message Digest MD5 11982 11983@noindent 11984Implements the MD5 Message-Digest Algorithm as described in RFC 1321. 11985 11986@node GNAT.Memory_Dump (g-memdum.ads) 11987@section @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) 11988@cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) 11989@cindex Dump Memory 11990 11991@noindent 11992Provides a convenient routine for dumping raw memory to either the 11993standard output or standard error files. Uses GNAT.IO for actual 11994output. 11995 11996@node GNAT.Most_Recent_Exception (g-moreex.ads) 11997@section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) 11998@cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) 11999@cindex Exception, obtaining most recent 12000 12001@noindent 12002Provides access to the most recently raised exception. Can be used for 12003various logging purposes, including duplicating functionality of some 12004Ada 83 implementation dependent extensions. 12005 12006@node GNAT.OS_Lib (g-os_lib.ads) 12007@section @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) 12008@cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) 12009@cindex Operating System interface 12010@cindex Spawn capability 12011 12012@noindent 12013Provides a range of target independent operating system interface functions, 12014including time/date management, file operations, subprocess management, 12015including a portable spawn procedure, and access to environment variables 12016and error return codes. 12017 12018@node GNAT.Perfect_Hash.Generators (g-pehage.ads) 12019@section @code{GNAT.Perfect_Hash.Generators} (@file{g-pehage.ads}) 12020@cindex @code{GNAT.Perfect_Hash.Generators} (@file{g-pehage.ads}) 12021@cindex Hash functions 12022 12023@noindent 12024Provides a generator of static minimal perfect hash functions. No 12025collisions occur and each item can be retrieved from the table in one 12026probe (perfect property). The hash table size corresponds to the exact 12027size of the key set and no larger (minimal property). The key set has to 12028be know in advance (static property). The hash functions are also order 12029preservering. If w2 is inserted after w1 in the generator, their 12030hashcode are in the same order. These hashing functions are very 12031convenient for use with realtime applications. 12032 12033@node GNAT.Regexp (g-regexp.ads) 12034@section @code{GNAT.Regexp} (@file{g-regexp.ads}) 12035@cindex @code{GNAT.Regexp} (@file{g-regexp.ads}) 12036@cindex Regular expressions 12037@cindex Pattern matching 12038 12039@noindent 12040A simple implementation of regular expressions, using a subset of regular 12041expression syntax copied from familiar Unix style utilities. This is the 12042simples of the three pattern matching packages provided, and is particularly 12043suitable for ``file globbing'' applications. 12044 12045@node GNAT.Registry (g-regist.ads) 12046@section @code{GNAT.Registry} (@file{g-regist.ads}) 12047@cindex @code{GNAT.Registry} (@file{g-regist.ads}) 12048@cindex Windows Registry 12049 12050@noindent 12051This is a high level binding to the Windows registry. It is possible to 12052do simple things like reading a key value, creating a new key. For full 12053registry API, but at a lower level of abstraction, refer to the Win32.Winreg 12054package provided with the Win32Ada binding 12055 12056@node GNAT.Regpat (g-regpat.ads) 12057@section @code{GNAT.Regpat} (@file{g-regpat.ads}) 12058@cindex @code{GNAT.Regpat} (@file{g-regpat.ads}) 12059@cindex Regular expressions 12060@cindex Pattern matching 12061 12062@noindent 12063A complete implementation of Unix-style regular expression matching, copied 12064from the original V7 style regular expression library written in C by 12065Henry Spencer (and binary compatible with this C library). 12066 12067@node GNAT.Secondary_Stack_Info (g-sestin.ads) 12068@section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) 12069@cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) 12070@cindex Secondary Stack Info 12071 12072@noindent 12073Provide the capability to query the high water mark of the current task's 12074secondary stack. 12075 12076@node GNAT.Semaphores (g-semaph.ads) 12077@section @code{GNAT.Semaphores} (@file{g-semaph.ads}) 12078@cindex @code{GNAT.Semaphores} (@file{g-semaph.ads}) 12079@cindex Semaphores 12080 12081@noindent 12082Provides classic counting and binary semaphores using protected types. 12083 12084@node GNAT.Signals (g-signal.ads) 12085@section @code{GNAT.Signals} (@file{g-signal.ads}) 12086@cindex @code{GNAT.Signals} (@file{g-signal.ads}) 12087@cindex Signals 12088 12089@noindent 12090Provides the ability to manipulate the blocked status of signals on supported 12091targets. 12092 12093@node GNAT.Sockets (g-socket.ads) 12094@section @code{GNAT.Sockets} (@file{g-socket.ads}) 12095@cindex @code{GNAT.Sockets} (@file{g-socket.ads}) 12096@cindex Sockets 12097 12098@noindent 12099A high level and portable interface to develop sockets based applications. 12100This package is based on the sockets thin binding found in 12101@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented 12102on all native GNAT ports except for OpenVMS@. It is not implemented 12103for the LynxOS@ cross port. 12104 12105@node GNAT.Source_Info (g-souinf.ads) 12106@section @code{GNAT.Source_Info} (@file{g-souinf.ads}) 12107@cindex @code{GNAT.Source_Info} (@file{g-souinf.ads}) 12108@cindex Source Information 12109 12110@noindent 12111Provides subprograms that give access to source code information known at 12112compile time, such as the current file name and line number. 12113 12114@node GNAT.Spell_Checker (g-speche.ads) 12115@section @code{GNAT.Spell_Checker} (@file{g-speche.ads}) 12116@cindex @code{GNAT.Spell_Checker} (@file{g-speche.ads}) 12117@cindex Spell checking 12118 12119@noindent 12120Provides a function for determining whether one string is a plausible 12121near misspelling of another string. 12122 12123@node GNAT.Spitbol.Patterns (g-spipat.ads) 12124@section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) 12125@cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) 12126@cindex SPITBOL pattern matching 12127@cindex Pattern matching 12128 12129@noindent 12130A complete implementation of SNOBOL4 style pattern matching. This is the 12131most elaborate of the pattern matching packages provided. It fully duplicates 12132the SNOBOL4 dynamic pattern construction and matching capabilities, using the 12133efficient algorithm developed by Robert Dewar for the SPITBOL system. 12134 12135@node GNAT.Spitbol (g-spitbo.ads) 12136@section @code{GNAT.Spitbol} (@file{g-spitbo.ads}) 12137@cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads}) 12138@cindex SPITBOL interface 12139 12140@noindent 12141The top level package of the collection of SPITBOL-style functionality, this 12142package provides basic SNOBOL4 string manipulation functions, such as 12143Pad, Reverse, Trim, Substr capability, as well as a generic table function 12144useful for constructing arbitrary mappings from strings in the style of 12145the SNOBOL4 TABLE function. 12146 12147@node GNAT.Spitbol.Table_Boolean (g-sptabo.ads) 12148@section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) 12149@cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) 12150@cindex Sets of strings 12151@cindex SPITBOL Tables 12152 12153@noindent 12154A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 12155for type @code{Standard.Boolean}, giving an implementation of sets of 12156string values. 12157 12158@node GNAT.Spitbol.Table_Integer (g-sptain.ads) 12159@section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) 12160@cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) 12161@cindex Integer maps 12162@cindex Maps 12163@cindex SPITBOL Tables 12164 12165@noindent 12166A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} 12167for type @code{Standard.Integer}, giving an implementation of maps 12168from string to integer values. 12169 12170@node GNAT.Spitbol.Table_VString (g-sptavs.ads) 12171@section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) 12172@cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) 12173@cindex String maps 12174@cindex Maps 12175@cindex SPITBOL Tables 12176 12177@noindent 12178A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for 12179a variable length string type, giving an implementation of general 12180maps from strings to strings. 12181 12182@node GNAT.Strings (g-string.ads) 12183@section @code{GNAT.Strings} (@file{g-string.ads}) 12184@cindex @code{GNAT.Strings} (@file{g-string.ads}) 12185 12186@noindent 12187Common String access types and related subprograms. Basically it 12188defines a string access and an array of string access types. 12189 12190@node GNAT.String_Split (g-strspl.ads) 12191@section @code{GNAT.String_Split} (@file{g-strspl.ads}) 12192@cindex @code{GNAT.String_Split} (@file{g-strspl.ads}) 12193@cindex String splitter 12194 12195@noindent 12196Useful string-manipulation routines: given a set of separators, split 12197a string wherever the separators appear, and provide direct access 12198to the resulting slices. This package is instantiated from 12199@code{GNAT.Array_Split}. 12200 12201@node GNAT.Table (g-table.ads) 12202@section @code{GNAT.Table} (@file{g-table.ads}) 12203@cindex @code{GNAT.Table} (@file{g-table.ads}) 12204@cindex Table implementation 12205@cindex Arrays, extendable 12206 12207@noindent 12208A generic package providing a single dimension array abstraction where the 12209length of the array can be dynamically modified. 12210 12211@noindent 12212This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, 12213except that this package declares a single instance of the table type, 12214while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be 12215used to define dynamic instances of the table. 12216 12217@node GNAT.Task_Lock (g-tasloc.ads) 12218@section @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) 12219@cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) 12220@cindex Task synchronization 12221@cindex Task locking 12222@cindex Locking 12223 12224@noindent 12225A very simple facility for locking and unlocking sections of code using a 12226single global task lock. Appropriate for use in situations where contention 12227between tasks is very rarely expected. 12228 12229@node GNAT.Threads (g-thread.ads) 12230@section @code{GNAT.Threads} (@file{g-thread.ads}) 12231@cindex @code{GNAT.Threads} (@file{g-thread.ads}) 12232@cindex Foreign threads 12233@cindex Threads, foreign 12234 12235@noindent 12236Provides facilities for creating and destroying threads with explicit calls. 12237These threads are known to the GNAT run-time system. These subprograms are 12238exported C-convention procedures intended to be called from foreign code. 12239By using these primitives rather than directly calling operating systems 12240routines, compatibility with the Ada tasking runt-time is provided. 12241 12242@node GNAT.Traceback (g-traceb.ads) 12243@section @code{GNAT.Traceback} (@file{g-traceb.ads}) 12244@cindex @code{GNAT.Traceback} (@file{g-traceb.ads}) 12245@cindex Trace back facilities 12246 12247@noindent 12248Provides a facility for obtaining non-symbolic traceback information, useful 12249in various debugging situations. 12250 12251@node GNAT.Traceback.Symbolic (g-trasym.ads) 12252@section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) 12253@cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) 12254@cindex Trace back facilities 12255 12256@noindent 12257Provides symbolic traceback information that includes the subprogram 12258name and line number information. 12259 12260@node GNAT.Wide_String_Split (g-wistsp.ads) 12261@section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) 12262@cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) 12263@cindex Wide_String splitter 12264 12265@noindent 12266Useful wide_string-manipulation routines: given a set of separators, split 12267a wide_string wherever the separators appear, and provide direct access 12268to the resulting slices. This package is instantiated from 12269@code{GNAT.Array_Split}. 12270 12271@node Interfaces.C.Extensions (i-cexten.ads) 12272@section @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) 12273@cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) 12274 12275@noindent 12276This package contains additional C-related definitions, intended 12277for use with either manually or automatically generated bindings 12278to C libraries. 12279 12280@node Interfaces.C.Streams (i-cstrea.ads) 12281@section @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) 12282@cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) 12283@cindex C streams, interfacing 12284 12285@noindent 12286This package is a binding for the most commonly used operations 12287on C streams. 12288 12289@node Interfaces.CPP (i-cpp.ads) 12290@section @code{Interfaces.CPP} (@file{i-cpp.ads}) 12291@cindex @code{Interfaces.CPP} (@file{i-cpp.ads}) 12292@cindex C++ interfacing 12293@cindex Interfacing, to C++ 12294 12295@noindent 12296This package provides facilities for use in interfacing to C++. It 12297is primarily intended to be used in connection with automated tools 12298for the generation of C++ interfaces. 12299 12300@node Interfaces.Os2lib (i-os2lib.ads) 12301@section @code{Interfaces.Os2lib} (@file{i-os2lib.ads}) 12302@cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads}) 12303@cindex Interfacing, to OS/2 12304@cindex OS/2 interfacing 12305 12306@noindent 12307This package provides interface definitions to the OS/2 library. 12308It is a thin binding which is a direct translation of the 12309various @file{<bse@.h>} files. 12310 12311@node Interfaces.Os2lib.Errors (i-os2err.ads) 12312@section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads}) 12313@cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads}) 12314@cindex OS/2 Error codes 12315@cindex Interfacing, to OS/2 12316@cindex OS/2 interfacing 12317 12318@noindent 12319This package provides definitions of the OS/2 error codes. 12320 12321@node Interfaces.Os2lib.Synchronization (i-os2syn.ads) 12322@section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads}) 12323@cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads}) 12324@cindex Interfacing, to OS/2 12325@cindex Synchronization, OS/2 12326@cindex OS/2 synchronization primitives 12327 12328@noindent 12329This is a child package that provides definitions for interfacing 12330to the @code{OS/2} synchronization primitives. 12331 12332@node Interfaces.Os2lib.Threads (i-os2thr.ads) 12333@section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads}) 12334@cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads}) 12335@cindex Interfacing, to OS/2 12336@cindex Thread control, OS/2 12337@cindex OS/2 thread interfacing 12338 12339@noindent 12340This is a child package that provides definitions for interfacing 12341to the @code{OS/2} thread primitives. 12342 12343@node Interfaces.Packed_Decimal (i-pacdec.ads) 12344@section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) 12345@cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) 12346@cindex IBM Packed Format 12347@cindex Packed Decimal 12348 12349@noindent 12350This package provides a set of routines for conversions to and 12351from a packed decimal format compatible with that used on IBM 12352mainframes. 12353 12354@node Interfaces.VxWorks (i-vxwork.ads) 12355@section @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) 12356@cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) 12357@cindex Interfacing to VxWorks 12358@cindex VxWorks, interfacing 12359 12360@noindent 12361This package provides a limited binding to the VxWorks API. 12362In particular, it interfaces with the 12363VxWorks hardware interrupt facilities. 12364 12365@node Interfaces.VxWorks.IO (i-vxwoio.ads) 12366@section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) 12367@cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) 12368@cindex Interfacing to VxWorks' I/O 12369@cindex VxWorks, I/O interfacing 12370@cindex VxWorks, Get_Immediate 12371@cindex Get_Immediate, VxWorks 12372 12373@noindent 12374This package provides a binding to the ioctl (IO/Control) 12375function of VxWorks, defining a set of option values and 12376function codes. A particular use of this package is 12377to enable the use of Get_Immediate under VxWorks. 12378 12379@node System.Address_Image (s-addima.ads) 12380@section @code{System.Address_Image} (@file{s-addima.ads}) 12381@cindex @code{System.Address_Image} (@file{s-addima.ads}) 12382@cindex Address image 12383@cindex Image, of an address 12384 12385@noindent 12386This function provides a useful debugging 12387function that gives an (implementation dependent) 12388string which identifies an address. 12389 12390@node System.Assertions (s-assert.ads) 12391@section @code{System.Assertions} (@file{s-assert.ads}) 12392@cindex @code{System.Assertions} (@file{s-assert.ads}) 12393@cindex Assertions 12394@cindex Assert_Failure, exception 12395 12396@noindent 12397This package provides the declaration of the exception raised 12398by an run-time assertion failure, as well as the routine that 12399is used internally to raise this assertion. 12400 12401@node System.Memory (s-memory.ads) 12402@section @code{System.Memory} (@file{s-memory.ads}) 12403@cindex @code{System.Memory} (@file{s-memory.ads}) 12404@cindex Memory allocation 12405 12406@noindent 12407This package provides the interface to the low level routines used 12408by the generated code for allocation and freeing storage for the 12409default storage pool (analogous to the C routines malloc and free. 12410It also provides a reallocation interface analogous to the C routine 12411realloc. The body of this unit may be modified to provide alternative 12412allocation mechanisms for the default pool, and in addition, direct 12413calls to this unit may be made for low level allocation uses (for 12414example see the body of @code{GNAT.Tables}). 12415 12416@node System.Partition_Interface (s-parint.ads) 12417@section @code{System.Partition_Interface} (@file{s-parint.ads}) 12418@cindex @code{System.Partition_Interface} (@file{s-parint.ads}) 12419@cindex Partition intefacing functions 12420 12421@noindent 12422This package provides facilities for partition interfacing. It 12423is used primarily in a distribution context when using Annex E 12424with @code{GLADE}. 12425 12426@node System.Task_Info (s-tasinf.ads) 12427@section @code{System.Task_Info} (@file{s-tasinf.ads}) 12428@cindex @code{System.Task_Info} (@file{s-tasinf.ads}) 12429@cindex Task_Info pragma 12430 12431@noindent 12432This package provides target dependent functionality that is used 12433to support the @code{Task_Info} pragma 12434 12435@node System.Wch_Cnv (s-wchcnv.ads) 12436@section @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) 12437@cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) 12438@cindex Wide Character, Representation 12439@cindex Wide String, Conversion 12440@cindex Representation of wide characters 12441 12442@noindent 12443This package provides routines for converting between 12444wide characters and a representation as a value of type 12445@code{Standard.String}, using a specified wide character 12446encoding method. It uses definitions in 12447package @code{System.Wch_Con}. 12448 12449@node System.Wch_Con (s-wchcon.ads) 12450@section @code{System.Wch_Con} (@file{s-wchcon.ads}) 12451@cindex @code{System.Wch_Con} (@file{s-wchcon.ads}) 12452 12453@noindent 12454This package provides definitions and descriptions of 12455the various methods used for encoding wide characters 12456in ordinary strings. These definitions are used by 12457the package @code{System.Wch_Cnv}. 12458 12459@node Interfacing to Other Languages 12460@chapter Interfacing to Other Languages 12461@noindent 12462The facilities in annex B of the Ada 95 Reference Manual are fully 12463implemented in GNAT, and in addition, a full interface to C++ is 12464provided. 12465 12466@menu 12467* Interfacing to C:: 12468* Interfacing to C++:: 12469* Interfacing to COBOL:: 12470* Interfacing to Fortran:: 12471* Interfacing to non-GNAT Ada code:: 12472@end menu 12473 12474@node Interfacing to C 12475@section Interfacing to C 12476 12477@noindent 12478Interfacing to C with GNAT can use one of two approaches: 12479 12480@itemize @bullet 12481@item 12482The types in the package @code{Interfaces.C} may be used. 12483@item 12484Standard Ada types may be used directly. This may be less portable to 12485other compilers, but will work on all GNAT compilers, which guarantee 12486correspondence between the C and Ada types. 12487@end itemize 12488 12489@noindent 12490Pragma @code{Convention C} may be applied to Ada types, but mostly has no 12491effect, since this is the default. The following table shows the 12492correspondence between Ada scalar types and the corresponding C types. 12493 12494@table @code 12495@item Integer 12496@code{int} 12497@item Short_Integer 12498@code{short} 12499@item Short_Short_Integer 12500@code{signed char} 12501@item Long_Integer 12502@code{long} 12503@item Long_Long_Integer 12504@code{long long} 12505@item Short_Float 12506@code{float} 12507@item Float 12508@code{float} 12509@item Long_Float 12510@code{double} 12511@item Long_Long_Float 12512This is the longest floating-point type supported by the hardware. 12513@end table 12514 12515@noindent 12516Additionally, there are the following general correspondences between Ada 12517and C types: 12518@itemize @bullet 12519@item 12520Ada enumeration types map to C enumeration types directly if pragma 12521@code{Convention C} is specified, which causes them to have int 12522length. Without pragma @code{Convention C}, Ada enumeration types map to 125238, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short}, 12524@code{int}, respectively) depending on the number of values passed. 12525This is the only case in which pragma @code{Convention C} affects the 12526representation of an Ada type. 12527 12528@item 12529Ada access types map to C pointers, except for the case of pointers to 12530unconstrained types in Ada, which have no direct C equivalent. 12531 12532@item 12533Ada arrays map directly to C arrays. 12534 12535@item 12536Ada records map directly to C structures. 12537 12538@item 12539Packed Ada records map to C structures where all members are bit fields 12540of the length corresponding to the @code{@var{type}'Size} value in Ada. 12541@end itemize 12542 12543@node Interfacing to C++ 12544@section Interfacing to C++ 12545 12546@noindent 12547The interface to C++ makes use of the following pragmas, which are 12548primarily intended to be constructed automatically using a binding generator 12549tool, although it is possible to construct them by hand. No suitable binding 12550generator tool is supplied with GNAT though. 12551 12552 12553Using these pragmas it is possible to achieve complete 12554inter-operability between Ada tagged types and C class definitions. 12555See @ref{Implementation Defined Pragmas}, for more details. 12556 12557@table @code 12558@item pragma CPP_Class ([Entity =>] @var{local_name}) 12559The argument denotes an entity in the current declarative region that is 12560declared as a tagged or untagged record type. It indicates that the type 12561corresponds to an externally declared C++ class type, and is to be laid 12562out the same way that C++ would lay out the type. 12563 12564@item pragma CPP_Constructor ([Entity =>] @var{local_name}) 12565This pragma identifies an imported function (imported in the usual way 12566with pragma @code{Import}) as corresponding to a C++ constructor. 12567 12568@item pragma CPP_Vtable @dots{} 12569One @code{CPP_Vtable} pragma can be present for each component of type 12570@code{CPP.Interfaces.Vtable_Ptr} in a record to which pragma @code{CPP_Class} 12571applies. 12572@end table 12573 12574@node Interfacing to COBOL 12575@section Interfacing to COBOL 12576 12577@noindent 12578Interfacing to COBOL is achieved as described in section B.4 of 12579the Ada 95 reference manual. 12580 12581@node Interfacing to Fortran 12582@section Interfacing to Fortran 12583 12584@noindent 12585Interfacing to Fortran is achieved as described in section B.5 of the 12586reference manual. The pragma @code{Convention Fortran}, applied to a 12587multi-dimensional array causes the array to be stored in column-major 12588order as required for convenient interface to Fortran. 12589 12590@node Interfacing to non-GNAT Ada code 12591@section Interfacing to non-GNAT Ada code 12592 12593It is possible to specify the convention @code{Ada} in a pragma 12594@code{Import} or pragma @code{Export}. However this refers to 12595the calling conventions used by GNAT, which may or may not be 12596similar enough to those used by some other Ada 83 or Ada 95 12597compiler to allow interoperation. 12598 12599If arguments types are kept simple, and if the foreign compiler generally 12600follows system calling conventions, then it may be possible to integrate 12601files compiled by other Ada compilers, provided that the elaboration 12602issues are adequately addressed (for example by eliminating the 12603need for any load time elaboration). 12604 12605In particular, GNAT running on VMS is designed to 12606be highly compatible with the DEC Ada 83 compiler, so this is one 12607case in which it is possible to import foreign units of this type, 12608provided that the data items passed are restricted to simple scalar 12609values or simple record types without variants, or simple array 12610types with fixed bounds. 12611 12612 12613@node Specialized Needs Annexes 12614@chapter Specialized Needs Annexes 12615 12616@noindent 12617Ada 95 defines a number of specialized needs annexes, which are not 12618required in all implementations. However, as described in this chapter, 12619GNAT implements all of these special needs annexes: 12620 12621@table @asis 12622@item Systems Programming (Annex C) 12623The Systems Programming Annex is fully implemented. 12624 12625@item Real-Time Systems (Annex D) 12626The Real-Time Systems Annex is fully implemented. 12627 12628@item Distributed Systems (Annex E) 12629Stub generation is fully implemented in the GNAT compiler. In addition, 12630a complete compatible PCS is available as part of the GLADE system, 12631a separate product. When the two 12632products are used in conjunction, this annex is fully implemented. 12633 12634@item Information Systems (Annex F) 12635The Information Systems annex is fully implemented. 12636 12637@item Numerics (Annex G) 12638The Numerics Annex is fully implemented. 12639 12640@item Safety and Security (Annex H) 12641The Safety and Security annex is fully implemented. 12642@end table 12643 12644 12645@node Implementation of Specific Ada Features 12646@chapter Implementation of Specific Ada Features 12647 12648@noindent 12649This chapter describes the GNAT implementation of several Ada language 12650facilities. 12651 12652@menu 12653* Machine Code Insertions:: 12654* GNAT Implementation of Tasking:: 12655* GNAT Implementation of Shared Passive Packages:: 12656* Code Generation for Array Aggregates:: 12657@end menu 12658 12659 12660@node Machine Code Insertions 12661@section Machine Code Insertions 12662 12663@noindent 12664Package @code{Machine_Code} provides machine code support as described 12665in the Ada 95 Reference Manual in two separate forms: 12666@itemize @bullet 12667@item 12668Machine code statements, consisting of qualified expressions that 12669fit the requirements of RM section 13.8. 12670@item 12671An intrinsic callable procedure, providing an alternative mechanism of 12672including machine instructions in a subprogram. 12673@end itemize 12674 12675@noindent 12676The two features are similar, and both closely related to the mechanism 12677provided by the asm instruction in the GNU C compiler. Full understanding 12678and use of the facilities in this package requires understanding the asm 12679instruction as described in 12680@cite{Using and Porting the GNU Compiler Collection (GCC)} by Richard 12681Stallman. Calls to the function @code{Asm} and the procedure @code{Asm} 12682have identical semantic restrictions and effects as described below. 12683Both are provided so that the procedure call can be used as a statement, 12684and the function call can be used to form a code_statement. 12685 12686The first example given in the GCC documentation is the C @code{asm} 12687instruction: 12688@smallexample 12689 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); 12690@end smallexample 12691 12692@noindent 12693The equivalent can be written for GNAT as: 12694 12695@smallexample @c ada 12696Asm ("fsinx %1 %0", 12697 My_Float'Asm_Output ("=f", result), 12698 My_Float'Asm_Input ("f", angle)); 12699@end smallexample 12700 12701@noindent 12702The first argument to @code{Asm} is the assembler template, and is 12703identical to what is used in GNU C@. This string must be a static 12704expression. The second argument is the output operand list. It is 12705either a single @code{Asm_Output} attribute reference, or a list of such 12706references enclosed in parentheses (technically an array aggregate of 12707such references). 12708 12709The @code{Asm_Output} attribute denotes a function that takes two 12710parameters. The first is a string, the second is the name of a variable 12711of the type designated by the attribute prefix. The first (string) 12712argument is required to be a static expression and designates the 12713constraint for the parameter (e.g.@: what kind of register is 12714required). The second argument is the variable to be updated with the 12715result. The possible values for constraint are the same as those used in 12716the RTL, and are dependent on the configuration file used to build the 12717GCC back end. If there are no output operands, then this argument may 12718either be omitted, or explicitly given as @code{No_Output_Operands}. 12719 12720The second argument of @code{@var{my_float}'Asm_Output} functions as 12721though it were an @code{out} parameter, which is a little curious, but 12722all names have the form of expressions, so there is no syntactic 12723irregularity, even though normally functions would not be permitted 12724@code{out} parameters. The third argument is the list of input 12725operands. It is either a single @code{Asm_Input} attribute reference, or 12726a list of such references enclosed in parentheses (technically an array 12727aggregate of such references). 12728 12729The @code{Asm_Input} attribute denotes a function that takes two 12730parameters. The first is a string, the second is an expression of the 12731type designated by the prefix. The first (string) argument is required 12732to be a static expression, and is the constraint for the parameter, 12733(e.g.@: what kind of register is required). The second argument is the 12734value to be used as the input argument. The possible values for the 12735constant are the same as those used in the RTL, and are dependent on 12736the configuration file used to built the GCC back end. 12737 12738If there are no input operands, this argument may either be omitted, or 12739explicitly given as @code{No_Input_Operands}. The fourth argument, not 12740present in the above example, is a list of register names, called the 12741@dfn{clobber} argument. This argument, if given, must be a static string 12742expression, and is a space or comma separated list of names of registers 12743that must be considered destroyed as a result of the @code{Asm} call. If 12744this argument is the null string (the default value), then the code 12745generator assumes that no additional registers are destroyed. 12746 12747The fifth argument, not present in the above example, called the 12748@dfn{volatile} argument, is by default @code{False}. It can be set to 12749the literal value @code{True} to indicate to the code generator that all 12750optimizations with respect to the instruction specified should be 12751suppressed, and that in particular, for an instruction that has outputs, 12752the instruction will still be generated, even if none of the outputs are 12753used. See the full description in the GCC manual for further details. 12754 12755The @code{Asm} subprograms may be used in two ways. First the procedure 12756forms can be used anywhere a procedure call would be valid, and 12757correspond to what the RM calls ``intrinsic'' routines. Such calls can 12758be used to intersperse machine instructions with other Ada statements. 12759Second, the function forms, which return a dummy value of the limited 12760private type @code{Asm_Insn}, can be used in code statements, and indeed 12761this is the only context where such calls are allowed. Code statements 12762appear as aggregates of the form: 12763 12764@smallexample @c ada 12765Asm_Insn'(Asm (@dots{})); 12766Asm_Insn'(Asm_Volatile (@dots{})); 12767@end smallexample 12768 12769@noindent 12770In accordance with RM rules, such code statements are allowed only 12771within subprograms whose entire body consists of such statements. It is 12772not permissible to intermix such statements with other Ada statements. 12773 12774Typically the form using intrinsic procedure calls is more convenient 12775and more flexible. The code statement form is provided to meet the RM 12776suggestion that such a facility should be made available. The following 12777is the exact syntax of the call to @code{Asm}. As usual, if named notation 12778is used, the arguments may be given in arbitrary order, following the 12779normal rules for use of positional and named arguments) 12780 12781@smallexample 12782ASM_CALL ::= Asm ( 12783 [Template =>] static_string_EXPRESSION 12784 [,[Outputs =>] OUTPUT_OPERAND_LIST ] 12785 [,[Inputs =>] INPUT_OPERAND_LIST ] 12786 [,[Clobber =>] static_string_EXPRESSION ] 12787 [,[Volatile =>] static_boolean_EXPRESSION] ) 12788 12789OUTPUT_OPERAND_LIST ::= 12790 [PREFIX.]No_Output_Operands 12791| OUTPUT_OPERAND_ATTRIBUTE 12792| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) 12793 12794OUTPUT_OPERAND_ATTRIBUTE ::= 12795 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) 12796 12797INPUT_OPERAND_LIST ::= 12798 [PREFIX.]No_Input_Operands 12799| INPUT_OPERAND_ATTRIBUTE 12800| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) 12801 12802INPUT_OPERAND_ATTRIBUTE ::= 12803 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) 12804@end smallexample 12805 12806@noindent 12807The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} 12808are declared in the package @code{Machine_Code} and must be referenced 12809according to normal visibility rules. In particular if there is no 12810@code{use} clause for this package, then appropriate package name 12811qualification is required. 12812 12813@node GNAT Implementation of Tasking 12814@section GNAT Implementation of Tasking 12815 12816@noindent 12817This chapter outlines the basic GNAT approach to tasking (in particular, 12818a multi-layered library for portability) and discusses issues related 12819to compliance with the Real-Time Systems Annex. 12820 12821@menu 12822* Mapping Ada Tasks onto the Underlying Kernel Threads:: 12823* Ensuring Compliance with the Real-Time Annex:: 12824@end menu 12825 12826@node Mapping Ada Tasks onto the Underlying Kernel Threads 12827@subsection Mapping Ada Tasks onto the Underlying Kernel Threads 12828 12829@noindent 12830GNAT's run-time support comprises two layers: 12831 12832@itemize @bullet 12833@item GNARL (GNAT Run-time Layer) 12834@item GNULL (GNAT Low-level Library) 12835@end itemize 12836 12837@noindent 12838In GNAT, Ada's tasking services rely on a platform and OS independent 12839layer known as GNARL@. This code is responsible for implementing the 12840correct semantics of Ada's task creation, rendezvous, protected 12841operations etc. 12842 12843GNARL decomposes Ada's tasking semantics into simpler lower level 12844operations such as create a thread, set the priority of a thread, 12845yield, create a lock, lock/unlock, etc. The spec for these low-level 12846operations constitutes GNULLI, the GNULL Interface. This interface is 12847directly inspired from the POSIX real-time API@. 12848 12849If the underlying executive or OS implements the POSIX standard 12850faithfully, the GNULL Interface maps as is to the services offered by 12851the underlying kernel. Otherwise, some target dependent glue code maps 12852the services offered by the underlying kernel to the semantics expected 12853by GNARL@. 12854 12855Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the 12856key point is that each Ada task is mapped on a thread in the underlying 12857kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. 12858 12859In addition Ada task priorities map onto the underlying thread priorities. 12860Mapping Ada tasks onto the underlying kernel threads has several advantages: 12861 12862@itemize @bullet 12863@item 12864The underlying scheduler is used to schedule the Ada tasks. This 12865makes Ada tasks as efficient as kernel threads from a scheduling 12866standpoint. 12867 12868@item 12869Interaction with code written in C containing threads is eased 12870since at the lowest level Ada tasks and C threads map onto the same 12871underlying kernel concept. 12872 12873@item 12874When an Ada task is blocked during I/O the remaining Ada tasks are 12875able to proceed. 12876 12877@item 12878On multiprocessor systems Ada tasks can execute in parallel. 12879@end itemize 12880 12881@noindent 12882Some threads libraries offer a mechanism to fork a new process, with the 12883child process duplicating the threads from the parent. 12884GNAT does not 12885support this functionality when the parent contains more than one task. 12886@cindex Forking a new process 12887 12888 12889@node Ensuring Compliance with the Real-Time Annex 12890@subsection Ensuring Compliance with the Real-Time Annex 12891@cindex Real-Time Systems Annex compliance 12892 12893@noindent 12894Although mapping Ada tasks onto 12895the underlying threads has significant advantages, it does create some 12896complications when it comes to respecting the scheduling semantics 12897specified in the real-time annex (Annex D). 12898 12899For instance the Annex D requirement for the @code{FIFO_Within_Priorities} 12900scheduling policy states: 12901 12902@quotation 12903@emph{When the active priority of a ready task that is not running 12904changes, or the setting of its base priority takes effect, the 12905task is removed from the ready queue for its old active priority 12906and is added at the tail of the ready queue for its new active 12907priority, except in the case where the active priority is lowered 12908due to the loss of inherited priority, in which case the task is 12909added at the head of the ready queue for its new active priority.} 12910@end quotation 12911 12912@noindent 12913While most kernels do put tasks at the end of the priority queue when 12914a task changes its priority, (which respects the main 12915FIFO_Within_Priorities requirement), almost none keep a thread at the 12916beginning of its priority queue when its priority drops from the loss 12917of inherited priority. 12918 12919As a result most vendors have provided incomplete Annex D implementations. 12920 12921The GNAT run-time, has a nice cooperative solution to this problem 12922which ensures that accurate FIFO_Within_Priorities semantics are 12923respected. 12924 12925The principle is as follows. When an Ada task T is about to start 12926running, it checks whether some other Ada task R with the same 12927priority as T has been suspended due to the loss of priority 12928inheritance. If this is the case, T yields and is placed at the end of 12929its priority queue. When R arrives at the front of the queue it 12930executes. 12931 12932Note that this simple scheme preserves the relative order of the tasks 12933that were ready to execute in the priority queue where R has been 12934placed at the end. 12935 12936@node GNAT Implementation of Shared Passive Packages 12937@section GNAT Implementation of Shared Passive Packages 12938@cindex Shared passive packages 12939 12940@noindent 12941GNAT fully implements the pragma @code{Shared_Passive} for 12942@cindex pragma @code{Shared_Passive} 12943the purpose of designating shared passive packages. 12944This allows the use of passive partitions in the 12945context described in the Ada Reference Manual; i.e. for communication 12946between separate partitions of a distributed application using the 12947features in Annex E. 12948@cindex Annex E 12949@cindex Distribution Systems Annex 12950 12951However, the implementation approach used by GNAT provides for more 12952extensive usage as follows: 12953 12954@table @emph 12955@item Communication between separate programs 12956 12957This allows separate programs to access the data in passive 12958partitions, using protected objects for synchronization where 12959needed. The only requirement is that the two programs have a 12960common shared file system. It is even possible for programs 12961running on different machines with different architectures 12962(e.g. different endianness) to communicate via the data in 12963a passive partition. 12964 12965@item Persistence between program runs 12966 12967The data in a passive package can persist from one run of a 12968program to another, so that a later program sees the final 12969values stored by a previous run of the same program. 12970 12971@end table 12972 12973@noindent 12974The implementation approach used is to store the data in files. A 12975separate stream file is created for each object in the package, and 12976an access to an object causes the corresponding file to be read or 12977written. 12978 12979The environment variable @code{SHARED_MEMORY_DIRECTORY} should be 12980@cindex @code{SHARED_MEMORY_DIRECTORY} environment variable 12981set to the directory to be used for these files. 12982The files in this directory 12983have names that correspond to their fully qualified names. For 12984example, if we have the package 12985 12986@smallexample @c ada 12987package X is 12988 pragma Shared_Passive (X); 12989 Y : Integer; 12990 Z : Float; 12991end X; 12992@end smallexample 12993 12994@noindent 12995and the environment variable is set to @code{/stemp/}, then the files created 12996will have the names: 12997 12998@smallexample 12999/stemp/x.y 13000/stemp/x.z 13001@end smallexample 13002 13003@noindent 13004These files are created when a value is initially written to the object, and 13005the files are retained until manually deleted. This provides the persistence 13006semantics. If no file exists, it means that no partition has assigned a value 13007to the variable; in this case the initial value declared in the package 13008will be used. This model ensures that there are no issues in synchronizing 13009the elaboration process, since elaboration of passive packages elaborates the 13010initial values, but does not create the files. 13011 13012The files are written using normal @code{Stream_IO} access. 13013If you want to be able 13014to communicate between programs or partitions running on different 13015architectures, then you should use the XDR versions of the stream attribute 13016routines, since these are architecture independent. 13017 13018If active synchronization is required for access to the variables in the 13019shared passive package, then as described in the Ada Reference Manual, the 13020package may contain protected objects used for this purpose. In this case 13021a lock file (whose name is @file{___lock} (three underscores) 13022is created in the shared memory directory. 13023@cindex @file{___lock} file (for shared passive packages) 13024This is used to provide the required locking 13025semantics for proper protected object synchronization. 13026 13027As of January 2003, GNAT supports shared passive packages on all platforms 13028except for OpenVMS. 13029 13030@node Code Generation for Array Aggregates 13031@section Code Generation for Array Aggregates 13032 13033@menu 13034* Static constant aggregates with static bounds:: 13035* Constant aggregates with an unconstrained nominal types:: 13036* Aggregates with static bounds:: 13037* Aggregates with non-static bounds:: 13038* Aggregates in assignment statements:: 13039@end menu 13040 13041@noindent 13042Aggregate have a rich syntax and allow the user to specify the values of 13043complex data structures by means of a single construct. As a result, the 13044code generated for aggregates can be quite complex and involve loops, case 13045statements and multiple assignments. In the simplest cases, however, the 13046compiler will recognize aggregates whose components and constraints are 13047fully static, and in those cases the compiler will generate little or no 13048executable code. The following is an outline of the code that GNAT generates 13049for various aggregate constructs. For further details, the user will find it 13050useful to examine the output produced by the -gnatG flag to see the expanded 13051source that is input to the code generator. The user will also want to examine 13052the assembly code generated at various levels of optimization. 13053 13054The code generated for aggregates depends on the context, the component values, 13055and the type. In the context of an object declaration the code generated is 13056generally simpler than in the case of an assignment. As a general rule, static 13057component values and static subtypes also lead to simpler code. 13058 13059@node Static constant aggregates with static bounds 13060@subsection Static constant aggregates with static bounds 13061 13062@noindent 13063For the declarations: 13064@smallexample @c ada 13065 type One_Dim is array (1..10) of integer; 13066 ar0 : constant One_Dim := ( 1, 2, 3, 4, 5, 6, 7, 8, 9, 0); 13067@end smallexample 13068 13069@noindent 13070GNAT generates no executable code: the constant ar0 is placed in static memory. 13071The same is true for constant aggregates with named associations: 13072 13073@smallexample @c ada 13074 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1=> 1); 13075 Cr3 : constant One_Dim := (others => 7777); 13076@end smallexample 13077 13078@noindent 13079The same is true for multidimensional constant arrays such as: 13080 13081@smallexample @c ada 13082 type two_dim is array (1..3, 1..3) of integer; 13083 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); 13084@end smallexample 13085 13086@noindent 13087The same is true for arrays of one-dimensional arrays: the following are 13088static: 13089 13090@smallexample @c ada 13091type ar1b is array (1..3) of boolean; 13092type ar_ar is array (1..3) of ar1b; 13093None : constant ar1b := (others => false); -- fully static 13094None2 : constant ar_ar := (1..3 => None); -- fully static 13095@end smallexample 13096 13097@noindent 13098However, for multidimensional aggregates with named associations, GNAT will 13099generate assignments and loops, even if all associations are static. The 13100following two declarations generate a loop for the first dimension, and 13101individual component assignments for the second dimension: 13102 13103@smallexample @c ada 13104Zero1: constant two_dim := (1..3 => (1..3 => 0)); 13105Zero2: constant two_dim := (others => (others => 0)); 13106@end smallexample 13107 13108@node Constant aggregates with an unconstrained nominal types 13109@subsection Constant aggregates with an unconstrained nominal types 13110 13111@noindent 13112In such cases the aggregate itself establishes the subtype, so that 13113associations with @code{others} cannot be used. GNAT determines the 13114bounds for the actual subtype of the aggregate, and allocates the 13115aggregate statically as well. No code is generated for the following: 13116 13117@smallexample @c ada 13118 type One_Unc is array (natural range <>) of integer; 13119 Cr_Unc : constant One_Unc := (12,24,36); 13120@end smallexample 13121 13122@node Aggregates with static bounds 13123@subsection Aggregates with static bounds 13124 13125@noindent 13126In all previous examples the aggregate was the initial (and immutable) value 13127of a constant. If the aggregate initializes a variable, then code is generated 13128for it as a combination of individual assignments and loops over the target 13129object. The declarations 13130 13131@smallexample @c ada 13132 Cr_Var1 : One_Dim := (2, 5, 7, 11); 13133 Cr_Var2 : One_Dim := (others > -1); 13134@end smallexample 13135 13136@noindent 13137generate the equivalent of 13138 13139@smallexample @c ada 13140 Cr_Var1 (1) := 2; 13141 Cr_Var1 (2) := 3; 13142 Cr_Var1 (3) := 5; 13143 Cr_Var1 (4) := 11; 13144 13145 for I in Cr_Var2'range loop 13146 Cr_Var2 (I) := =-1; 13147 end loop; 13148@end smallexample 13149 13150@node Aggregates with non-static bounds 13151@subsection Aggregates with non-static bounds 13152 13153@noindent 13154If the bounds of the aggregate are not statically compatible with the bounds 13155of the nominal subtype of the target, then constraint checks have to be 13156generated on the bounds. For a multidimensional array, constraint checks may 13157have to be applied to sub-arrays individually, if they do not have statically 13158compatible subtypes. 13159 13160@node Aggregates in assignment statements 13161@subsection Aggregates in assignment statements 13162 13163@noindent 13164In general, aggregate assignment requires the construction of a temporary, 13165and a copy from the temporary to the target of the assignment. This is because 13166it is not always possible to convert the assignment into a series of individual 13167component assignments. For example, consider the simple case: 13168 13169@smallexample @c ada 13170 A := (A(2), A(1)); 13171@end smallexample 13172 13173@noindent 13174This cannot be converted into: 13175 13176@smallexample @c ada 13177 A(1) := A(2); 13178 A(2) := A(1); 13179@end smallexample 13180 13181@noindent 13182So the aggregate has to be built first in a separate location, and then 13183copied into the target. GNAT recognizes simple cases where this intermediate 13184step is not required, and the assignments can be performed in place, directly 13185into the target. The following sufficient criteria are applied: 13186 13187@itemize @bullet 13188@item 13189The bounds of the aggregate are static, and the associations are static. 13190@item 13191The components of the aggregate are static constants, names of 13192simple variables that are not renamings, or expressions not involving 13193indexed components whose operands obey these rules. 13194@end itemize 13195 13196@noindent 13197If any of these conditions are violated, the aggregate will be built in 13198a temporary (created either by the front-end or the code generator) and then 13199that temporary will be copied onto the target. 13200 13201 13202@node Project File Reference 13203@chapter Project File Reference 13204 13205@noindent 13206This chapter describes the syntax and semantics of project files. 13207Project files specify the options to be used when building a system. 13208Project files can specify global settings for all tools, 13209as well as tool-specific settings. 13210See the chapter on project files in the GNAT Users guide for examples of use. 13211 13212@menu 13213* Reserved Words:: 13214* Lexical Elements:: 13215* Declarations:: 13216* Typed string declarations:: 13217* Variables:: 13218* Expressions:: 13219* Attributes:: 13220* Project Attributes:: 13221* Attribute References:: 13222* External Values:: 13223* Case Construction:: 13224* Packages:: 13225* Package Renamings:: 13226* Projects:: 13227* Project Extensions:: 13228* Project File Elaboration:: 13229@end menu 13230 13231@node Reserved Words 13232@section Reserved Words 13233 13234@noindent 13235All Ada95 reserved words are reserved in project files, and cannot be used 13236as variable names or project names. In addition, the following are 13237also reserved in project files: 13238 13239@itemize 13240@item @code{extends} 13241 13242@item @code{external} 13243 13244@item @code{project} 13245 13246@end itemize 13247 13248@node Lexical Elements 13249@section Lexical Elements 13250 13251@noindent 13252Rules for identifiers are the same as in Ada95. Identifiers 13253are case-insensitive. Strings are case sensitive, except where noted. 13254Comments have the same form as in Ada95. 13255 13256@noindent 13257Syntax: 13258 13259@smallexample 13260simple_name ::= 13261 identifier 13262 13263name ::= 13264 simple_name @{. simple_name@} 13265@end smallexample 13266 13267@node Declarations 13268@section Declarations 13269 13270@noindent 13271Declarations introduce new entities that denote types, variables, attributes, 13272and packages. Some declarations can only appear immediately within a project 13273declaration. Others can appear within a project or within a package. 13274 13275Syntax: 13276@smallexample 13277declarative_item ::= 13278 simple_declarative_item | 13279 typed_string_declaration | 13280 package_declaration 13281 13282simple_declarative_item ::= 13283 variable_declaration | 13284 typed_variable_declaration | 13285 attribute_declaration | 13286 case_construction 13287@end smallexample 13288 13289@node Typed string declarations 13290@section Typed string declarations 13291 13292@noindent 13293Typed strings are sequences of string literals. Typed strings are the only 13294named types in project files. They are used in case constructions, where they 13295provide support for conditional attribute definitions. 13296 13297Syntax: 13298@smallexample 13299typed_string_declaration ::= 13300 @b{type} <typed_string_>_simple_name @b{is} 13301 ( string_literal @{, string_literal@} ); 13302@end smallexample 13303 13304@noindent 13305A typed string declaration can only appear immediately within a project 13306declaration. 13307 13308All the string literals in a typed string declaration must be distinct. 13309 13310@node Variables 13311@section Variables 13312 13313@noindent 13314Variables denote values, and appear as constituents of expressions. 13315 13316@smallexample 13317typed_variable_declaration ::= 13318 <typed_variable_>simple_name : <typed_string_>name := string_expression ; 13319 13320variable_declaration ::= 13321 <variable_>simple_name := expression; 13322@end smallexample 13323 13324@noindent 13325The elaboration of a variable declaration introduces the variable and 13326assigns to it the value of the expression. The name of the variable is 13327available after the assignment symbol. 13328 13329@noindent 13330A typed_variable can only be declare once. 13331 13332@noindent 13333a non typed variable can be declared multiple times. 13334 13335@noindent 13336Before the completion of its first declaration, the value of variable 13337is the null string. 13338 13339@node Expressions 13340@section Expressions 13341 13342@noindent 13343An expression is a formula that defines a computation or retrieval of a value. 13344In a project file the value of an expression is either a string or a list 13345of strings. A string value in an expression is either a literal, the current 13346value of a variable, an external value, an attribute reference, or a 13347concatenation operation. 13348 13349Syntax: 13350 13351@smallexample 13352expression ::= 13353 term @{& term@} 13354 13355term ::= 13356 string_literal | 13357 string_list | 13358 <variable_>name | 13359 external_value | 13360 attribute_reference 13361 13362string_literal ::= 13363 (same as Ada) 13364 13365string_list ::= 13366 ( <string_>expression @{ , <string_>expression @} ) 13367@end smallexample 13368 13369@subsection Concatenation 13370@noindent 13371The following concatenation functions are defined: 13372 13373@smallexample @c ada 13374 function "&" (X : String; Y : String) return String; 13375 function "&" (X : String_List; Y : String) return String_List; 13376 function "&" (X : String_List; Y : String_List) return String_List; 13377@end smallexample 13378 13379@node Attributes 13380@section Attributes 13381 13382@noindent 13383An attribute declaration defines a property of a project or package. This 13384property can later be queried by means of an attribute reference. 13385Attribute values are strings or string lists. 13386 13387Some attributes are associative arrays. These attributes are mappings whose 13388domain is a set of strings. These attributes are declared one association 13389at a time, by specifying a point in the domain and the corresponding image 13390of the attribute. They may also be declared as a full associative array, 13391getting the same associations as the corresponding attribute in an imported 13392or extended project. 13393 13394Attributes that are not associative arrays are called simple attributes. 13395 13396Syntax: 13397@smallexample 13398attribute_declaration ::= 13399 full_associative_array_declaration | 13400 @b{for} attribute_designator @b{use} expression ; 13401 13402full_associative_array_declaration ::= 13403 @b{for} <associative_array_attribute_>simple_name @b{use} 13404 <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ; 13405 13406attribute_designator ::= 13407 <simple_attribute_>simple_name | 13408 <associative_array_attribute_>simple_name ( string_literal ) 13409@end smallexample 13410 13411@noindent 13412Some attributes are project-specific, and can only appear immediately within 13413a project declaration. Others are package-specific, and can only appear within 13414the proper package. 13415 13416The expression in an attribute definition must be a string or a string_list. 13417The string literal appearing in the attribute_designator of an associative 13418array attribute is case-insensitive. 13419 13420@node Project Attributes 13421@section Project Attributes 13422 13423@noindent 13424The following attributes apply to a project. All of them are simple 13425attributes. 13426 13427@table @code 13428@item Object_Dir 13429Expression must be a path name. The attribute defines the 13430directory in which the object files created by the build are to be placed. If 13431not specified, object files are placed in the project directory. 13432 13433@item Exec_Dir 13434Expression must be a path name. The attribute defines the 13435directory in which the executables created by the build are to be placed. 13436If not specified, executables are placed in the object directory. 13437 13438@item Source_Dirs 13439Expression must be a list of path names. The attribute 13440defines the directories in which the source files for the project are to be 13441found. If not specified, source files are found in the project directory. 13442 13443@item Source_Files 13444Expression must be a list of file names. The attribute 13445defines the individual files, in the project directory, which are to be used 13446as sources for the project. File names are path_names that contain no directory 13447information. If the project has no sources the attribute must be declared 13448explicitly with an empty list. 13449 13450@item Source_List_File 13451Expression must a single path name. The attribute 13452defines a text file that contains a list of source file names to be used 13453as sources for the project 13454 13455@item Library_Dir 13456Expression must be a path name. The attribute defines the 13457directory in which a library is to be built. The directory must exist, must 13458be distinct from the project's object directory, and must be writable. 13459 13460@item Library_Name 13461Expression must be a string that is a legal file name, 13462without extension. The attribute defines a string that is used to generate 13463the name of the library to be built by the project. 13464 13465@item Library_Kind 13466Argument must be a string value that must be one of the 13467following @code{"static"}, @code{"dynamic"} or @code{"relocatable"}. This 13468string is case-insensitive. If this attribute is not specified, the library is 13469a static library. Otherwise, the library may be dynamic or relocatable. This 13470distinction is operating-system dependent. 13471 13472@item Library_Version 13473Expression must be a string value whose interpretation 13474is platform dependent. On UNIX, it is used only for dynamic/relocatable 13475libraries as the internal name of the library (the @code{"soname"}). If the 13476library file name (built from the @code{Library_Name}) is different from the 13477@code{Library_Version}, then the library file will be a symbolic link to the 13478actual file whose name will be @code{Library_Version}. 13479 13480@item Library_Interface 13481Expression must be a string list. Each element of the string list 13482must designate a unit of the project. 13483If this attribute is present in a Library Project File, then the project 13484file is a Stand-alone Library_Project_File. 13485 13486@item Library_Auto_Init 13487Expression must be a single string "true" or "false", case-insensitive. 13488If this attribute is present in a Stand-alone Library Project File, 13489it indicates if initialization is automatic when the dynamic library 13490is loaded. 13491 13492@item Library_Options 13493Expression must be a string list. Indicates additional switches that 13494are to be used when building a shared library. 13495 13496@item Library_GCC 13497Expression must be a single string. Designates an alternative to "gcc" 13498for building shared libraries. 13499 13500@item Library_Src_Dir 13501Expression must be a path name. The attribute defines the 13502directory in which the sources of the interfaces of a Stand-alone Library will 13503be copied. The directory must exist, must be distinct from the project's 13504object directory and source directories, and must be writable. 13505 13506@item Main 13507Expression must be a list of strings that are legal file names. 13508These file names designate existing compilation units in the source directory 13509that are legal main subprograms. 13510 13511When a project file is elaborated, as part of the execution of a gnatmake 13512command, one or several executables are built and placed in the Exec_Dir. 13513If the gnatmake command does not include explicit file names, the executables 13514that are built correspond to the files specified by this attribute. 13515 13516@item Main_Language 13517This is a simple attribute. Its value is a string that specifies the 13518language of the main program. 13519 13520@item Languages 13521Expression must be a string list. Each string designates 13522a programming language that is known to GNAT. The strings are case-insensitive. 13523 13524@item Locally_Removed_Files 13525This attribute is legal only in a project file that extends another. 13526Expression must be a list of strings that are legal file names. 13527Each file name must designate a source that would normally be inherited 13528by the current project file. It cannot designate an immediate source that is 13529not inherited. Each of the source files in the list are not considered to 13530be sources of the project file: they are not inherited. 13531@end table 13532 13533@node Attribute References 13534@section Attribute References 13535 13536@noindent 13537Attribute references are used to retrieve the value of previously defined 13538attribute for a package or project. 13539Syntax: 13540@smallexample 13541attribute_reference ::= 13542 attribute_prefix ' <simple_attribute_>simple_name [ ( string_literal ) ] 13543 13544attribute_prefix ::= 13545 @b{project} | 13546 <project_simple_name | package_identifier | 13547 <project_>simple_name . package_identifier 13548@end smallexample 13549 13550@noindent 13551If an attribute has not been specified for a given package or project, its 13552value is the null string or the empty list. 13553 13554@node External Values 13555@section External Values 13556 13557@noindent 13558An external value is an expression whose value is obtained from the command 13559that invoked the processing of the current project file (typically a 13560gnatmake command). 13561 13562Syntax: 13563@smallexample 13564external_value ::= 13565 @b{external} ( string_literal [, string_literal] ) 13566@end smallexample 13567 13568@noindent 13569The first string_literal is the string to be used on the command line or 13570in the environment to specify the external value. The second string_literal, 13571if present, is the default to use if there is no specification for this 13572external value either on the command line or in the environment. 13573 13574@node Case Construction 13575@section Case Construction 13576 13577@noindent 13578A case construction supports attribute declarations that depend on the value of 13579a previously declared variable. 13580 13581Syntax: 13582@smallexample 13583case_construction ::= 13584 @b{case} <typed_variable_>name @b{is} 13585 @{case_item@} 13586 @b{end case} ; 13587 13588case_item ::= 13589 @b{when} discrete_choice_list => 13590 @{case_construction | attribute_declaration@} 13591 13592discrete_choice_list ::= 13593 string_literal @{| string_literal@} | 13594 @b{others} 13595@end smallexample 13596 13597@noindent 13598All choices in a choice list must be distinct. The choice lists of two 13599distinct alternatives must be disjoint. Unlike Ada, the choice lists of all 13600alternatives do not need to include all values of the type. An @code{others} 13601choice must appear last in the list of alternatives. 13602 13603@node Packages 13604@section Packages 13605 13606@noindent 13607A package provides a grouping of variable declarations and attribute 13608declarations to be used when invoking various GNAT tools. The name of 13609the package indicates the tool(s) to which it applies. 13610Syntax: 13611 13612@smallexample 13613package_declaration ::= 13614 package_specification | package_renaming 13615 13616package_specification ::= 13617 @b{package} package_identifier @b{is} 13618 @{simple_declarative_item@} 13619 @b{end} package_identifier ; 13620 13621package_identifier ::= 13622 @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} | 13623 @code{Linker} | @code{Finder} | @code{Cross_Reference} | 13624 @code{gnatls} | @code{IDE} | @code{Pretty_Printer} 13625@end smallexample 13626 13627@subsection Package Naming 13628 13629@noindent 13630The attributes of a @code{Naming} package specifies the naming conventions 13631that apply to the source files in a project. When invoking other GNAT tools, 13632they will use the sources in the source directories that satisfy these 13633naming conventions. 13634 13635The following attributes apply to a @code{Naming} package: 13636 13637@table @code 13638@item Casing 13639This is a simple attribute whose value is a string. Legal values of this 13640string are @code{"lowercase"}, @code{"uppercase"} or @code{"mixedcase"}. 13641These strings are themselves case insensitive. 13642 13643@noindent 13644If @code{Casing} is not specified, then the default is @code{"lowercase"}. 13645 13646@item Dot_Replacement 13647This is a simple attribute whose string value satisfies the following 13648requirements: 13649 13650@itemize @bullet 13651@item It must not be empty 13652@item It cannot start or end with an alphanumeric character 13653@item It cannot be a single underscore 13654@item It cannot start with an underscore followed by an alphanumeric 13655@item It cannot contain a dot @code{'.'} if longer than one character 13656@end itemize 13657 13658@noindent 13659If @code{Dot_Replacement} is not specified, then the default is @code{"-"}. 13660 13661@item Spec_Suffix 13662This is an associative array attribute, defined on language names, 13663whose image is a string that must satisfy the following 13664conditions: 13665 13666@itemize @bullet 13667@item It must not be empty 13668@item It cannot start with an alphanumeric character 13669@item It cannot start with an underscore followed by an alphanumeric character 13670@end itemize 13671 13672@noindent 13673For Ada, the attribute denotes the suffix used in file names that contain 13674library unit declarations, that is to say units that are package and 13675subprogram declarations. If @code{Spec_Suffix ("Ada")} is not 13676specified, then the default is @code{".ads"}. 13677 13678For C and C++, the attribute denotes the suffix used in file names that 13679contain prototypes. 13680 13681@item Body_Suffix 13682This is an associative array attribute defined on language names, 13683whose image is a string that must satisfy the following 13684conditions: 13685 13686@itemize @bullet 13687@item It must not be empty 13688@item It cannot start with an alphanumeric character 13689@item It cannot start with an underscore followed by an alphanumeric character 13690@item It cannot be a suffix of @code{Spec_Suffix} 13691@end itemize 13692 13693@noindent 13694For Ada, the attribute denotes the suffix used in file names that contain 13695library bodies, that is to say units that are package and subprogram bodies. 13696If @code{Body_Suffix ("Ada")} is not specified, then the default is 13697@code{".adb"}. 13698 13699For C and C++, the attribute denotes the suffix used in file names that contain 13700source code. 13701 13702@item Separate_Suffix 13703This is a simple attribute whose value satisfies the same conditions as 13704@code{Body_Suffix}. 13705 13706This attribute is specific to Ada. It denotes the suffix used in file names 13707that contain separate bodies. If it is not specified, then it defaults to same 13708value as @code{Body_Suffix ("Ada")}. 13709 13710@item Spec 13711This is an associative array attribute, specific to Ada, defined over 13712compilation unit names. The image is a string that is the name of the file 13713that contains that library unit. The file name is case sensitive if the 13714conventions of the host operating system require it. 13715 13716@item Body 13717This is an associative array attribute, specific to Ada, defined over 13718compilation unit names. The image is a string that is the name of the file 13719that contains the library unit body for the named unit. The file name is case 13720sensitive if the conventions of the host operating system require it. 13721 13722@item Specification_Exceptions 13723This is an associative array attribute defined on language names, 13724whose value is a list of strings. 13725 13726This attribute is not significant for Ada. 13727 13728For C and C++, each string in the list denotes the name of a file that 13729contains prototypes, but whose suffix is not necessarily the 13730@code{Spec_Suffix} for the language. 13731 13732@item Implementation_Exceptions 13733This is an associative array attribute defined on language names, 13734whose value is a list of strings. 13735 13736This attribute is not significant for Ada. 13737 13738For C and C++, each string in the list denotes the name of a file that 13739contains source code, but whose suffix is not necessarily the 13740@code{Body_Suffix} for the language. 13741@end table 13742 13743The following attributes of package @code{Naming} are obsolescent. They are 13744kept as synonyms of other attributes for compatibility with previous versions 13745of the Project Manager. 13746 13747@table @code 13748@item Specification_Suffix 13749This is a synonym of @code{Spec_Suffix}. 13750 13751@item Implementation_Suffix 13752This is a synonym of @code{Body_Suffix}. 13753 13754@item Specification 13755This is a synonym of @code{Spec}. 13756 13757@item Implementation 13758This is a synonym of @code{Body}. 13759@end table 13760 13761@subsection package Compiler 13762 13763@noindent 13764The attributes of the @code{Compiler} package specify the compilation options 13765to be used by the underlying compiler. 13766 13767@table @code 13768@item Default_Switches 13769This is an associative array attribute. Its 13770domain is a set of language names. Its range is a string list that 13771specifies the compilation options to be used when compiling a component 13772written in that language, for which no file-specific switches have been 13773specified.. 13774 13775@item Switches 13776This is an associative array attribute. Its domain is 13777a set of file names. Its range is a string list that specifies the 13778compilation options to be used when compiling the named file. If a file 13779is not specified in the Switches attribute, it is compiled with the 13780settings specified by Default_Switches. 13781 13782@item Local_Configuration_Pragmas. 13783This is a simple attribute, whose 13784value is a path name that designates a file containing configuration pragmas 13785to be used for all invocations of the compiler for immediate sources of the 13786project. 13787 13788@item Executable 13789This is an associative array attribute. Its domain is 13790a set of main source file names. Its range is a simple string that specifies 13791the executable file name to be used when linking the specified main source. 13792If a main source is not specified in the Executable attribute, the executable 13793file name is deducted from the main source file name. 13794@end table 13795 13796@subsection package Builder 13797 13798@noindent 13799The attributes of package @code{Builder} specify the compilation, binding, and 13800linking options to be used when building an executable for a project. The 13801following attributes apply to package @code{Builder}: 13802 13803@table @code 13804@item Default_Switches 13805As above. 13806 13807@item Switches 13808As above. 13809 13810@item Global_Configuration_Pragmas 13811This is a simple attribute, whose 13812value is a path name that designates a file that contains configuration pragmas 13813to be used in every build of an executable. If both local and global 13814configuration pragmas are specified, a compilation makes use of both sets. 13815 13816@item Executable 13817This is an associative array attribute, defined over 13818compilation unit names. The image is a string that is the name of the 13819executable file corresponding to the main source file index. 13820This attribute has no effect if its value is the empty string. 13821 13822@item Executable_Suffix 13823This is a simple attribute whose value is a suffix to be added to 13824the executables that don't have an attribute Executable specified. 13825@end table 13826 13827@subsection package Gnatls 13828 13829@noindent 13830The attributes of package @code{Gnatls} specify the tool options to be used 13831when invoking the library browser @command{gnatls}. 13832The following attributes apply to package @code{Gnatls}: 13833 13834@table @code 13835@item Switches 13836As above. 13837@end table 13838 13839@subsection package Binder 13840 13841@noindent 13842The attributes of package @code{Binder} specify the options to be used 13843when invoking the binder in the construction of an executable. 13844The following attributes apply to package @code{Binder}: 13845 13846@table @code 13847@item Default_Switches 13848As above. 13849@item Switches 13850As above. 13851@end table 13852 13853@subsection package Linker 13854 13855@noindent 13856The attributes of package @code{Linker} specify the options to be used when 13857invoking the linker in the construction of an executable. 13858The following attributes apply to package @code{Linker}: 13859 13860@table @code 13861@item Default_Switches 13862As above 13863@item Switches 13864As above. 13865@end table 13866 13867@subsection package Cross_Reference 13868 13869@noindent 13870The attributes of package @code{Cross_Reference} specify the tool options 13871to be used 13872when invoking the library tool @command{gnatxref}. 13873The following attributes apply to package @code{Cross_Reference}: 13874 13875@table @code 13876@item Default_Switches 13877As above. 13878@item Switches 13879As above. 13880@end table 13881 13882@subsection package Finder 13883 13884@noindent 13885The attributes of package @code{Finder} specify the tool options to be used 13886when invoking the search tool @command{gnatfind}. 13887The following attributes apply to package @code{Finder}: 13888 13889@table @code 13890@item Default_Switches 13891As above. 13892@item Switches 13893As above. 13894@end table 13895 13896@subsection package Pretty_Printer 13897 13898@noindent 13899The attributes of package @code{Pretty_Printer} 13900specify the tool options to be used 13901when invoking the formatting tool @command{gnatpp}. 13902The following attributes apply to package @code{Pretty_Printer}: 13903 13904@table @code 13905@item Default_switches 13906As above. 13907@item Switches 13908As above. 13909@end table 13910 13911@subsection package IDE 13912 13913@noindent 13914The attributes of package @code{IDE} specify the options to be used when using 13915an Integrated Development Environment such as @command{GPS}. 13916 13917@table @code 13918@item Remote_Host 13919This is a simple attribute. Its value is a string that designates the remote 13920host in a cross-compilation environment, to be used for remote compilation and 13921debugging. This field should not be specified when running on the local 13922machine. 13923 13924@item Program_Host 13925This is a simple attribute. Its value is a string that specifies the 13926name of IP address of the embedded target in a cross-compilation environment, 13927on which the program should execute. 13928 13929@item Communication_Protocol 13930This is a simple string attribute. Its value is the name of the protocol 13931to use to communicate with the target in a cross-compilation environment, 13932e.g. @code{"wtx"} or @code{"vxworks"}. 13933 13934@item Compiler_Command 13935This is an associative array attribute, whose domain is a language name. Its 13936value is string that denotes the command to be used to invoke the compiler. 13937The value of @code{Compiler_Command ("Ada")} is expected to be compatible with 13938gnatmake, in particular in the handling of switches. 13939 13940@item Debugger_Command 13941This is simple attribute, Its value is a string that specifies the name of 13942the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4. 13943 13944@item Default_Switches 13945This is an associative array attribute. Its indexes are the name of the 13946external tools that the GNAT Programming System (GPS) is supporting. Its 13947value is a list of switches to use when invoking that tool. 13948 13949@item Gnatlist 13950This is a simple attribute. Its value is a string that specifies the name 13951of the @command{gnatls} utility to be used to retrieve information about the 13952predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. 13953 13954@item VCS_Kind 13955This is a simple atribute. Is value is a string used to specify the 13956Version Control System (VCS) to be used for this project, e.g CVS, RCS 13957ClearCase or Perforce. 13958 13959@item VCS_File_Check 13960This is a simple attribute. Its value is a string that specifies the 13961command used by the VCS to check the validity of a file, either 13962when the user explicitly asks for a check, or as a sanity check before 13963doing the check-in. 13964 13965@item VCS_Log_Check 13966This is a simple attribute. Its value is a string that specifies 13967the command used by the VCS to check the validity of a log file. 13968 13969@end table 13970 13971@node Package Renamings 13972@section Package Renamings 13973 13974@noindent 13975A package can be defined by a renaming declaration. The new package renames 13976a package declared in a different project file, and has the same attributes 13977as the package it renames. 13978Syntax: 13979@smallexample 13980package_renaming ::== 13981 @b{package} package_identifier @b{renames} 13982 <project_>simple_name.package_identifier ; 13983@end smallexample 13984 13985@noindent 13986The package_identifier of the renamed package must be the same as the 13987package_identifier. The project whose name is the prefix of the renamed 13988package must contain a package declaration with this name. This project 13989must appear in the context_clause of the enclosing project declaration, 13990or be the parent project of the enclosing child project. 13991 13992@node Projects 13993@section Projects 13994 13995@noindent 13996A project file specifies a set of rules for constructing a software system. 13997A project file can be self-contained, or depend on other project files. 13998Dependencies are expressed through a context clause that names other projects. 13999 14000Syntax: 14001 14002@smallexample 14003project ::= 14004 context_clause project_declaration 14005 14006project_declaration ::= 14007 simple_project_declaration | project_extension 14008 14009simple_project_declaration ::= 14010 @b{project} <project_>simple_name @b{is} 14011 @{declarative_item@} 14012 @b{end} <project_>simple_name; 14013 14014context_clause ::= 14015 @{with_clause@} 14016 14017with_clause ::= 14018 [@b{limited}] @b{with} path_name @{ , path_name @} ; 14019 14020path_name ::= 14021 string_literal 14022@end smallexample 14023 14024@noindent 14025A path name denotes a project file. A path name can be absolute or relative. 14026An absolute path name includes a sequence of directories, in the syntax of 14027the host operating system, that identifies uniquely the project file in the 14028file system. A relative path name identifies the directory that contains the 14029project file, relative to the directory that contains the current project. 14030Path names are case sensitive if file names in the host operating system 14031are case sensitive. 14032 14033A given project name can appear only once in a context_clause. 14034 14035It is illegal for a project imported by a context clause to refer, directly 14036or indirectly, to the project in which this context clause appears (the 14037dependency graph cannot contain cycles), except when one of the with_clause 14038in the cycle is a @code{limited with}. 14039 14040@node Project Extensions 14041@section Project Extensions 14042 14043@noindent 14044A project extension introduces a new project, which inherits the declarations 14045of another project. 14046Syntax: 14047@smallexample 14048 14049project_extension ::= 14050 @b{project} <project_>simple_name @b{extends} path_name @b{is} 14051 @{declarative_item@} 14052 @b{end} <project_>simple_name; 14053@end smallexample 14054 14055@noindent 14056The project extension declares a child project. The child project inherits 14057all the declarations and all the files of the parent project, These inherited 14058declaration can be overridden in the child project, by means of suitable 14059declarations. 14060 14061@node Project File Elaboration 14062@section Project File Elaboration 14063 14064@noindent 14065A project file is processed as part of the invocation of a gnat tool that 14066uses the project option. Elaboration of the process file consists in the 14067sequential elaboration of all its declarations. The computed values of 14068attributes and variables in the project are then used to establish the 14069environment in which the gnat tool will execute. 14070 14071@include fdl.texi 14072@c GNU Free Documentation License 14073 14074@node Index,,GNU Free Documentation License, Top 14075@unnumbered Index 14076 14077@printindex cp 14078 14079@contents 14080 14081@bye 14082