diff options
Diffstat (limited to 'gcc-4.2.1/gcc/ada/gnat_rm.texi')
| -rw-r--r-- | gcc-4.2.1/gcc/ada/gnat_rm.texi | 15486 |
1 files changed, 15486 insertions, 0 deletions
diff --git a/gcc-4.2.1/gcc/ada/gnat_rm.texi b/gcc-4.2.1/gcc/ada/gnat_rm.texi new file mode 100644 index 000000000..ef41c7527 --- /dev/null +++ b/gcc-4.2.1/gcc/ada/gnat_rm.texi @@ -0,0 +1,15486 @@ +\input texinfo @c -*-texinfo-*- + +@c %**start of header + +@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo +@c o +@c GNAT DOCUMENTATION o +@c o +@c G N A T _ RM o +@c o +@c Copyright (C) 1995-2005 Free Software Foundation o +@c o +@c o +@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o +@c o +@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo + +@setfilename gnat_rm.info + +@set FSFEDITION + +@settitle GNAT Reference Manual + +@setchapternewpage odd +@syncodeindex fn cp + +@include gcc-common.texi + +@dircategory GNU Ada tools +@direntry +* GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools. +@end direntry + +@copying +Copyright @copyright{} 1995-2004, Free Software Foundation + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 +or any later version published by the Free Software Foundation; +with the Invariant Sections being ``GNU Free Documentation License'', +with the Front-Cover Texts being ``GNAT Reference Manual'', and with +no Back-Cover Texts. A copy of the license is included in the section +entitled ``GNU Free Documentation License''. +@end copying + +@titlepage +@title GNAT Reference Manual +@subtitle GNAT, The GNU Ada 95 Compiler +@versionsubtitle +@author Ada Core Technologies, Inc. +@page +@vskip 0pt plus 1filll + +@insertcopying + +@end titlepage + +@ifnottex +@node Top, About This Guide, (dir), (dir) +@top GNAT Reference Manual + +@noindent +GNAT Reference Manual + +@noindent +GNAT, The GNU Ada 95 Compiler@* +GCC version @value{version-GCC}@* + +@noindent +AdaCore + +@menu +* About This Guide:: +* Implementation Defined Pragmas:: +* Implementation Defined Attributes:: +* Implementation Advice:: +* Implementation Defined Characteristics:: +* Intrinsic Subprograms:: +* Representation Clauses and Pragmas:: +* Standard Library Routines:: +* The Implementation of Standard I/O:: +* The GNAT Library:: +* Interfacing to Other Languages:: +* Specialized Needs Annexes:: +* Implementation of Specific Ada Features:: +* Project File Reference:: +* Obsolescent Features:: +* GNU Free Documentation License:: +* Index:: + + --- The Detailed Node Listing --- + +About This Guide + +* What This Reference Manual Contains:: +* Related Information:: + +Implementation Defined Pragmas + +* Pragma Abort_Defer:: +* Pragma Ada_83:: +* Pragma Ada_95:: +* Pragma Ada_05:: +* Pragma Ada_2005:: +* Pragma Annotate:: +* Pragma Assert:: +* Pragma Ast_Entry:: +* Pragma C_Pass_By_Copy:: +* Pragma Comment:: +* Pragma Common_Object:: +* Pragma Compile_Time_Warning:: +* Pragma Complete_Representation:: +* Pragma Complex_Representation:: +* Pragma Component_Alignment:: +* Pragma Convention_Identifier:: +* Pragma CPP_Class:: +* Pragma CPP_Constructor:: +* Pragma CPP_Virtual:: +* Pragma CPP_Vtable:: +* Pragma Debug:: +* Pragma Debug_Policy:: +* Pragma Detect_Blocking:: +* Pragma Elaboration_Checks:: +* Pragma Eliminate:: +* Pragma Export_Exception:: +* Pragma Export_Function:: +* Pragma Export_Object:: +* Pragma Export_Procedure:: +* Pragma Export_Value:: +* Pragma Export_Valued_Procedure:: +* Pragma Extend_System:: +* Pragma External:: +* Pragma External_Name_Casing:: +* Pragma Finalize_Storage_Only:: +* Pragma Float_Representation:: +* Pragma Ident:: +* Pragma Import_Exception:: +* Pragma Import_Function:: +* Pragma Import_Object:: +* Pragma Import_Procedure:: +* Pragma Import_Valued_Procedure:: +* Pragma Initialize_Scalars:: +* Pragma Inline_Always:: +* Pragma Inline_Generic:: +* Pragma Interface:: +* Pragma Interface_Name:: +* Pragma Interrupt_Handler:: +* Pragma Interrupt_State:: +* Pragma Keep_Names:: +* Pragma License:: +* Pragma Link_With:: +* Pragma Linker_Alias:: +* Pragma Linker_Constructor:: +* Pragma Linker_Destructor:: +* Pragma Linker_Section:: +* Pragma Long_Float:: +* Pragma Machine_Attribute:: +* Pragma Main_Storage:: +* Pragma No_Return:: +* Pragma No_Strict_Aliasing :: +* Pragma Normalize_Scalars:: +* Pragma Obsolescent:: +* Pragma Passive:: +* Pragma Persistent_BSS:: +* Pragma Polling:: +* Pragma Profile (Ravenscar):: +* Pragma Profile (Restricted):: +* Pragma Psect_Object:: +* Pragma Pure_Function:: +* Pragma Restriction_Warnings:: +* Pragma Source_File_Name:: +* Pragma Source_File_Name_Project:: +* Pragma Source_Reference:: +* Pragma Stream_Convert:: +* Pragma Style_Checks:: +* Pragma Subtitle:: +* Pragma Suppress_All:: +* Pragma Suppress_Exception_Locations:: +* Pragma Suppress_Initialization:: +* Pragma Task_Info:: +* Pragma Task_Name:: +* Pragma Task_Storage:: +* Pragma Thread_Body:: +* Pragma Time_Slice:: +* Pragma Title:: +* Pragma Unchecked_Union:: +* Pragma Unimplemented_Unit:: +* Pragma Universal_Data:: +* Pragma Unreferenced:: +* Pragma Unreserve_All_Interrupts:: +* Pragma Unsuppress:: +* Pragma Use_VADS_Size:: +* Pragma Validity_Checks:: +* Pragma Volatile:: +* Pragma Warnings:: +* Pragma Weak_External:: + +Implementation Defined Attributes + +* Abort_Signal:: +* Address_Size:: +* Asm_Input:: +* Asm_Output:: +* AST_Entry:: +* Bit:: +* Bit_Position:: +* Code_Address:: +* Default_Bit_Order:: +* Elaborated:: +* Elab_Body:: +* Elab_Spec:: +* Emax:: +* Enum_Rep:: +* Epsilon:: +* Fixed_Value:: +* Has_Access_Values:: +* Has_Discriminants:: +* Img:: +* Integer_Value:: +* Large:: +* Machine_Size:: +* Mantissa:: +* Max_Interrupt_Priority:: +* Max_Priority:: +* Maximum_Alignment:: +* Mechanism_Code:: +* Null_Parameter:: +* Object_Size:: +* Passed_By_Reference:: +* Range_Length:: +* Safe_Emax:: +* Safe_Large:: +* Small:: +* Storage_Unit:: +* Target_Name:: +* Tick:: +* To_Address:: +* Type_Class:: +* UET_Address:: +* Unconstrained_Array:: +* Universal_Literal_String:: +* Unrestricted_Access:: +* VADS_Size:: +* Value_Size:: +* Wchar_T_Size:: +* Word_Size:: + +The Implementation of Standard I/O + +* Standard I/O Packages:: +* FORM Strings:: +* Direct_IO:: +* Sequential_IO:: +* Text_IO:: +* Wide_Text_IO:: +* Wide_Wide_Text_IO:: +* Stream_IO:: +* Shared Files:: +* Open Modes:: +* Operations on C Streams:: +* Interfacing to C Streams:: + +The GNAT Library + +* Ada.Characters.Latin_9 (a-chlat9.ads):: +* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: +* Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: +* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads):: +* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads):: +* Ada.Command_Line.Remove (a-colire.ads):: +* Ada.Command_Line.Environment (a-colien.ads):: +* Ada.Direct_IO.C_Streams (a-diocst.ads):: +* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: +* Ada.Exceptions.Traceback (a-exctra.ads):: +* Ada.Sequential_IO.C_Streams (a-siocst.ads):: +* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: +* Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: +* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: +* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads):: +* Ada.Text_IO.C_Streams (a-tiocst.ads):: +* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: +* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: +* GNAT.Altivec (g-altive.ads):: +* GNAT.Altivec.Conversions (g-altcon.ads):: +* GNAT.Altivec.Vector_Operations (g-alveop.ads):: +* GNAT.Altivec.Vector_Types (g-alvety.ads):: +* GNAT.Altivec.Vector_Views (g-alvevi.ads):: +* GNAT.Array_Split (g-arrspl.ads):: +* GNAT.AWK (g-awk.ads):: +* GNAT.Bounded_Buffers (g-boubuf.ads):: +* GNAT.Bounded_Mailboxes (g-boumai.ads):: +* GNAT.Bubble_Sort (g-bubsor.ads):: +* GNAT.Bubble_Sort_A (g-busora.ads):: +* GNAT.Bubble_Sort_G (g-busorg.ads):: +* GNAT.Calendar (g-calend.ads):: +* GNAT.Calendar.Time_IO (g-catiio.ads):: +* GNAT.Case_Util (g-casuti.ads):: +* GNAT.CGI (g-cgi.ads):: +* GNAT.CGI.Cookie (g-cgicoo.ads):: +* GNAT.CGI.Debug (g-cgideb.ads):: +* GNAT.Command_Line (g-comlin.ads):: +* GNAT.Compiler_Version (g-comver.ads):: +* GNAT.Ctrl_C (g-ctrl_c.ads):: +* GNAT.CRC32 (g-crc32.ads):: +* GNAT.Current_Exception (g-curexc.ads):: +* GNAT.Debug_Pools (g-debpoo.ads):: +* GNAT.Debug_Utilities (g-debuti.ads):: +* GNAT.Directory_Operations (g-dirope.ads):: +* GNAT.Dynamic_HTables (g-dynhta.ads):: +* GNAT.Dynamic_Tables (g-dyntab.ads):: +* GNAT.Exception_Actions (g-excact.ads):: +* GNAT.Exception_Traces (g-exctra.ads):: +* GNAT.Exceptions (g-except.ads):: +* GNAT.Expect (g-expect.ads):: +* GNAT.Float_Control (g-flocon.ads):: +* GNAT.Heap_Sort (g-heasor.ads):: +* GNAT.Heap_Sort_A (g-hesora.ads):: +* GNAT.Heap_Sort_G (g-hesorg.ads):: +* GNAT.HTable (g-htable.ads):: +* GNAT.IO (g-io.ads):: +* GNAT.IO_Aux (g-io_aux.ads):: +* GNAT.Lock_Files (g-locfil.ads):: +* GNAT.MD5 (g-md5.ads):: +* GNAT.Memory_Dump (g-memdum.ads):: +* GNAT.Most_Recent_Exception (g-moreex.ads):: +* GNAT.OS_Lib (g-os_lib.ads):: +* GNAT.Perfect_Hash_Generators (g-pehage.ads):: +* GNAT.Regexp (g-regexp.ads):: +* GNAT.Registry (g-regist.ads):: +* GNAT.Regpat (g-regpat.ads):: +* GNAT.Secondary_Stack_Info (g-sestin.ads):: +* GNAT.Semaphores (g-semaph.ads):: +* GNAT.Signals (g-signal.ads):: +* GNAT.Sockets (g-socket.ads):: +* GNAT.Source_Info (g-souinf.ads):: +* GNAT.Spell_Checker (g-speche.ads):: +* GNAT.Spitbol.Patterns (g-spipat.ads):: +* GNAT.Spitbol (g-spitbo.ads):: +* GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: +* GNAT.Spitbol.Table_Integer (g-sptain.ads):: +* GNAT.Spitbol.Table_VString (g-sptavs.ads):: +* GNAT.Strings (g-string.ads):: +* GNAT.String_Split (g-strspl.ads):: +* GNAT.Table (g-table.ads):: +* GNAT.Task_Lock (g-tasloc.ads):: +* GNAT.Threads (g-thread.ads):: +* GNAT.Traceback (g-traceb.ads):: +* GNAT.Traceback.Symbolic (g-trasym.ads):: +* GNAT.Wide_String_Split (g-wistsp.ads):: +* GNAT.Wide_Wide_String_Split (g-zistsp.ads):: +* Interfaces.C.Extensions (i-cexten.ads):: +* Interfaces.C.Streams (i-cstrea.ads):: +* Interfaces.CPP (i-cpp.ads):: +* Interfaces.Os2lib (i-os2lib.ads):: +* Interfaces.Os2lib.Errors (i-os2err.ads):: +* Interfaces.Os2lib.Synchronization (i-os2syn.ads):: +* Interfaces.Os2lib.Threads (i-os2thr.ads):: +* Interfaces.Packed_Decimal (i-pacdec.ads):: +* Interfaces.VxWorks (i-vxwork.ads):: +* Interfaces.VxWorks.IO (i-vxwoio.ads):: +* System.Address_Image (s-addima.ads):: +* System.Assertions (s-assert.ads):: +* System.Memory (s-memory.ads):: +* System.Partition_Interface (s-parint.ads):: +* System.Restrictions (s-restri.ads):: +* System.Rident (s-rident.ads):: +* System.Task_Info (s-tasinf.ads):: +* System.Wch_Cnv (s-wchcnv.ads):: +* System.Wch_Con (s-wchcon.ads):: + +Text_IO + +* Text_IO Stream Pointer Positioning:: +* Text_IO Reading and Writing Non-Regular Files:: +* Get_Immediate:: +* Treating Text_IO Files as Streams:: +* Text_IO Extensions:: +* Text_IO Facilities for Unbounded Strings:: + +Wide_Text_IO + +* Wide_Text_IO Stream Pointer Positioning:: +* Wide_Text_IO Reading and Writing Non-Regular Files:: + +Wide_Wide_Text_IO + +* Wide_Wide_Text_IO Stream Pointer Positioning:: +* Wide_Wide_Text_IO Reading and Writing Non-Regular Files:: + +Interfacing to Other Languages + +* Interfacing to C:: +* Interfacing to C++:: +* Interfacing to COBOL:: +* Interfacing to Fortran:: +* Interfacing to non-GNAT Ada code:: + +Specialized Needs Annexes + +Implementation of Specific Ada Features +* Machine Code Insertions:: +* GNAT Implementation of Tasking:: +* GNAT Implementation of Shared Passive Packages:: +* Code Generation for Array Aggregates:: +* The Size of Discriminated Records with Default Discriminants:: +* Strict Conformance to the Ada 95 Reference Manual:: + +Project File Reference + +Obsolescent Features + +GNU Free Documentation License + +Index +@end menu + +@end ifnottex + +@node About This Guide +@unnumbered About This Guide + +@ifclear PROEDITION +@noindent +This manual contains useful information in writing programs using the +GNAT compiler. It includes information on implementation dependent +characteristics of GNAT, including all the information required by Annex +M of the standard. +@end ifclear + +@ifset PROEDITION +@noindent +This manual contains useful information in writing programs using the +GNAT Pro compiler. It includes information on implementation dependent +characteristics of GNAT Pro, including all the information required by Annex +M of the standard. +@end ifset + +Ada 95 is designed to be highly portable. +In general, a program will have the same effect even when compiled by +different compilers on different platforms. +However, since Ada 95 is designed to be used in a +wide variety of applications, it also contains a number of system +dependent features to be used in interfacing to the external world. +@cindex Implementation-dependent features +@cindex Portability + +Note: Any program that makes use of implementation-dependent features +may be non-portable. You should follow good programming practice and +isolate and clearly document any sections of your program that make use +of these features in a non-portable manner. + +@ifset PROEDITION +For ease of exposition, ``GNAT Pro'' will be referred to simply as +``GNAT'' in the remainder of this document. +@end ifset + +@menu +* What This Reference Manual Contains:: +* Conventions:: +* Related Information:: +@end menu + +@node What This Reference Manual Contains +@unnumberedsec What This Reference Manual Contains + +@noindent +This reference manual contains the following chapters: + +@itemize @bullet +@item +@ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent +pragmas, which can be used to extend and enhance the functionality of the +compiler. + +@item +@ref{Implementation Defined Attributes}, lists GNAT +implementation-dependent attributes which can be used to extend and +enhance the functionality of the compiler. + +@item +@ref{Implementation Advice}, provides information on generally +desirable behavior which are not requirements that all compilers must +follow since it cannot be provided on all systems, or which may be +undesirable on some systems. + +@item +@ref{Implementation Defined Characteristics}, provides a guide to +minimizing implementation dependent features. + +@item +@ref{Intrinsic Subprograms}, describes the intrinsic subprograms +implemented by GNAT, and how they can be imported into user +application programs. + +@item +@ref{Representation Clauses and Pragmas}, describes in detail the +way that GNAT represents data, and in particular the exact set +of representation clauses and pragmas that is accepted. + +@item +@ref{Standard Library Routines}, provides a listing of packages and a +brief description of the functionality that is provided by Ada's +extensive set of standard library routines as implemented by GNAT@. + +@item +@ref{The Implementation of Standard I/O}, details how the GNAT +implementation of the input-output facilities. + +@item +@ref{The GNAT Library}, is a catalog of packages that complement +the Ada predefined library. + +@item +@ref{Interfacing to Other Languages}, describes how programs +written in Ada using GNAT can be interfaced to other programming +languages. + +@ref{Specialized Needs Annexes}, describes the GNAT implementation of all +of the specialized needs annexes. + +@item +@ref{Implementation of Specific Ada Features}, discusses issues related +to GNAT's implementation of machine code insertions, tasking, and several +other features. + +@item +@ref{Project File Reference}, presents the syntax and semantics +of project files. + +@item +@ref{Obsolescent Features} documents implementation dependent features, +including pragmas and attributes, which are considered obsolescent, since +there are other preferred ways of achieving the same results. These +obsolescent forms are retained for backwards compatibility. + +@end itemize + +@cindex Ada 95 ISO/ANSI Standard +@noindent +This reference manual assumes that you are familiar with Ada 95 +language, as described in the International Standard +ANSI/ISO/IEC-8652:1995, Jan 1995. + +@node Conventions +@unnumberedsec Conventions +@cindex Conventions, typographical +@cindex Typographical conventions + +@noindent +Following are examples of the typographical and graphic conventions used +in this guide: + +@itemize @bullet +@item +@code{Functions}, @code{utility program names}, @code{standard names}, +and @code{classes}. + +@item +@code{Option flags} + +@item +@file{File Names}, @samp{button names}, and @samp{field names}. + +@item +@code{Variables}. + +@item +@emph{Emphasis}. + +@item +[optional information or parameters] + +@item +Examples are described by text +@smallexample +and then shown this way. +@end smallexample +@end itemize + +@noindent +Commands that are entered by the user are preceded in this manual by the +characters @samp{$ } (dollar sign followed by space). If your system uses this +sequence as a prompt, then the commands will appear exactly as you see them +in the manual. If your system uses some other prompt, then the command will +appear with the @samp{$} replaced by whatever prompt character you are using. + +@node Related Information +@unnumberedsec Related Information +@noindent +See the following documents for further information on GNAT: + +@itemize @bullet +@item +@cite{GNAT User's Guide}, which provides information on how to use +the GNAT compiler system. + +@item +@cite{Ada 95 Reference Manual}, which contains all reference +material for the Ada 95 programming language. + +@item +@cite{Ada 95 Annotated Reference Manual}, which is an annotated version +of the standard reference manual cited above. The annotations describe +detailed aspects of the design decision, and in particular contain useful +sections on Ada 83 compatibility. + +@item +@cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms}, +which contains specific information on compatibility between GNAT and +DEC Ada 83 systems. + +@item +@cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which +describes in detail the pragmas and attributes provided by the DEC Ada 83 +compiler system. + +@end itemize + +@node Implementation Defined Pragmas +@chapter Implementation Defined Pragmas + +@noindent +Ada 95 defines a set of pragmas that can be used to supply additional +information to the compiler. These language defined pragmas are +implemented in GNAT and work as described in the Ada 95 Reference +Manual. + +In addition, Ada 95 allows implementations to define additional pragmas +whose meaning is defined by the implementation. GNAT provides a number +of these implementation-dependent pragmas which can be used to extend +and enhance the functionality of the compiler. This section of the GNAT +Reference Manual describes these additional pragmas. + +Note that any program using these pragmas may not be portable to other +compilers (although GNAT implements this set of pragmas on all +platforms). Therefore if portability to other compilers is an important +consideration, the use of these pragmas should be minimized. + +@menu +* Pragma Abort_Defer:: +* Pragma Ada_83:: +* Pragma Ada_95:: +* Pragma Ada_05:: +* Pragma Ada_2005:: +* Pragma Annotate:: +* Pragma Assert:: +* Pragma Ast_Entry:: +* Pragma C_Pass_By_Copy:: +* Pragma Comment:: +* Pragma Common_Object:: +* Pragma Compile_Time_Warning:: +* Pragma Complete_Representation:: +* Pragma Complex_Representation:: +* Pragma Component_Alignment:: +* Pragma Convention_Identifier:: +* Pragma CPP_Class:: +* Pragma CPP_Constructor:: +* Pragma CPP_Virtual:: +* Pragma CPP_Vtable:: +* Pragma Debug:: +* Pragma Debug_Policy:: +* Pragma Detect_Blocking:: +* Pragma Elaboration_Checks:: +* Pragma Eliminate:: +* Pragma Export_Exception:: +* Pragma Export_Function:: +* Pragma Export_Object:: +* Pragma Export_Procedure:: +* Pragma Export_Value:: +* Pragma Export_Valued_Procedure:: +* Pragma Extend_System:: +* Pragma External:: +* Pragma External_Name_Casing:: +* Pragma Finalize_Storage_Only:: +* Pragma Float_Representation:: +* Pragma Ident:: +* Pragma Import_Exception:: +* Pragma Import_Function:: +* Pragma Import_Object:: +* Pragma Import_Procedure:: +* Pragma Import_Valued_Procedure:: +* Pragma Initialize_Scalars:: +* Pragma Inline_Always:: +* Pragma Inline_Generic:: +* Pragma Interface:: +* Pragma Interface_Name:: +* Pragma Interrupt_Handler:: +* Pragma Interrupt_State:: +* Pragma Keep_Names:: +* Pragma License:: +* Pragma Link_With:: +* Pragma Linker_Alias:: +* Pragma Linker_Constructor:: +* Pragma Linker_Destructor:: +* Pragma Linker_Section:: +* Pragma Long_Float:: +* Pragma Machine_Attribute:: +* Pragma Main_Storage:: +* Pragma No_Return:: +* Pragma No_Strict_Aliasing:: +* Pragma Normalize_Scalars:: +* Pragma Obsolescent:: +* Pragma Passive:: +* Pragma Persistent_BSS:: +* Pragma Polling:: +* Pragma Profile (Ravenscar):: +* Pragma Profile (Restricted):: +* Pragma Psect_Object:: +* Pragma Pure_Function:: +* Pragma Restriction_Warnings:: +* Pragma Source_File_Name:: +* Pragma Source_File_Name_Project:: +* Pragma Source_Reference:: +* Pragma Stream_Convert:: +* Pragma Style_Checks:: +* Pragma Subtitle:: +* Pragma Suppress_All:: +* Pragma Suppress_Exception_Locations:: +* Pragma Suppress_Initialization:: +* Pragma Task_Info:: +* Pragma Task_Name:: +* Pragma Task_Storage:: +* Pragma Thread_Body:: +* Pragma Time_Slice:: +* Pragma Title:: +* Pragma Unchecked_Union:: +* Pragma Unimplemented_Unit:: +* Pragma Universal_Data:: +* Pragma Unreferenced:: +* Pragma Unreserve_All_Interrupts:: +* Pragma Unsuppress:: +* Pragma Use_VADS_Size:: +* Pragma Validity_Checks:: +* Pragma Volatile:: +* Pragma Warnings:: +* Pragma Weak_External:: +@end menu + +@node Pragma Abort_Defer +@unnumberedsec Pragma Abort_Defer +@findex Abort_Defer +@cindex Deferring aborts +@noindent +Syntax: +@smallexample +pragma Abort_Defer; +@end smallexample + +@noindent +This pragma must appear at the start of the statement sequence of a +handled sequence of statements (right after the @code{begin}). It has +the effect of deferring aborts for the sequence of statements (but not +for the declarations or handlers, if any, associated with this statement +sequence). + +@node Pragma Ada_83 +@unnumberedsec Pragma Ada_83 +@findex Ada_83 +@noindent +Syntax: +@smallexample @c ada +pragma Ada_83; +@end smallexample + +@noindent +A configuration pragma that establishes Ada 83 mode for the unit to +which it applies, regardless of the mode set by the command line +switches. In Ada 83 mode, GNAT attempts to be as compatible with +the syntax and semantics of Ada 83, as defined in the original Ada +83 Reference Manual as possible. In particular, the new Ada 95 +keywords are not recognized, optional package bodies are allowed, +and generics may name types with unknown discriminants without using +the @code{(<>)} notation. In addition, some but not all of the additional +restrictions of Ada 83 are enforced. + +Ada 83 mode is intended for two purposes. Firstly, it allows existing +legacy Ada 83 code to be compiled and adapted to GNAT with less effort. +Secondly, it aids in keeping code backwards compatible with Ada 83. +However, there is no guarantee that code that is processed correctly +by GNAT in Ada 83 mode will in fact compile and execute with an Ada +83 compiler, since GNAT does not enforce all the additional checks +required by Ada 83. + +@node Pragma Ada_95 +@unnumberedsec Pragma Ada_95 +@findex Ada_95 +@noindent +Syntax: +@smallexample @c ada +pragma Ada_95; +@end smallexample + +@noindent +A configuration pragma that establishes Ada 95 mode for the unit to which +it applies, regardless of the mode set by the command line switches. +This mode is set automatically for the @code{Ada} and @code{System} +packages and their children, so you need not specify it in these +contexts. This pragma is useful when writing a reusable component that +itself uses Ada 95 features, but which is intended to be usable from +either Ada 83 or Ada 95 programs. + +@node Pragma Ada_05 +@unnumberedsec Pragma Ada_05 +@findex Ada_05 +@noindent +Syntax: +@smallexample @c ada +pragma Ada_05; +@end smallexample + +@noindent +A configuration pragma that establishes Ada 2005 mode for the unit to which +it applies, regardless of the mode set by the command line switches. +This mode is set automatically for the @code{Ada} and @code{System} +packages and their children, so you need not specify it in these +contexts. This pragma is useful when writing a reusable component that +itself uses Ada 2005 features, but which is intended to be usable from +either Ada 83 or Ada 95 programs. + +@node Pragma Ada_2005 +@unnumberedsec Pragma Ada_2005 +@findex Ada_2005 +@noindent +Syntax: +@smallexample @c ada +pragma Ada_2005; +@end smallexample + +@noindent +This configuration pragma is a synonym for pragma Ada_05 and has the +same syntax and effect. + +@node Pragma Annotate +@unnumberedsec Pragma Annotate +@findex Annotate +@noindent +Syntax: +@smallexample @c ada +pragma Annotate (IDENTIFIER @{, ARG@}); + +ARG ::= NAME | EXPRESSION +@end smallexample + +@noindent +This pragma is used to annotate programs. @var{identifier} identifies +the type of annotation. GNAT verifies this is an identifier, but does +not otherwise analyze it. The @var{arg} argument +can be either a string literal or an +expression. String literals are assumed to be of type +@code{Standard.String}. Names of entities are simply analyzed as entity +names. All other expressions are analyzed as expressions, and must be +unambiguous. + +The analyzed pragma is retained in the tree, but not otherwise processed +by any part of the GNAT compiler. This pragma is intended for use by +external tools, including ASIS@. + +@node Pragma Assert +@unnumberedsec Pragma Assert +@findex Assert +@noindent +Syntax: +@smallexample @c ada +pragma Assert ( + boolean_EXPRESSION + [, static_string_EXPRESSION]); +@end smallexample + +@noindent +The effect of this pragma depends on whether the corresponding command +line switch is set to activate assertions. The pragma expands into code +equivalent to the following: + +@smallexample @c ada +if assertions-enabled then + if not boolean_EXPRESSION then + System.Assertions.Raise_Assert_Failure + (string_EXPRESSION); + end if; +end if; +@end smallexample + +@noindent +The string argument, if given, is the message that will be associated +with the exception occurrence if the exception is raised. If no second +argument is given, the default message is @samp{@var{file}:@var{nnn}}, +where @var{file} is the name of the source file containing the assert, +and @var{nnn} is the line number of the assert. A pragma is not a +statement, so if a statement sequence contains nothing but a pragma +assert, then a null statement is required in addition, as in: + +@smallexample @c ada +@dots{} +if J > 3 then + pragma Assert (K > 3, "Bad value for K"); + null; +end if; +@end smallexample + +@noindent +Note that, as with the @code{if} statement to which it is equivalent, the +type of the expression is either @code{Standard.Boolean}, or any type derived +from this standard type. + +If assertions are disabled (switch @code{-gnata} not used), then there +is no effect (and in particular, any side effects from the expression +are suppressed). More precisely it is not quite true that the pragma +has no effect, since the expression is analyzed, and may cause types +to be frozen if they are mentioned here for the first time. + +If assertions are enabled, then the given expression is tested, and if +it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called +which results in the raising of @code{Assert_Failure} with the given message. + +If the boolean expression has side effects, these side effects will turn +on and off with the setting of the assertions mode, resulting in +assertions that have an effect on the program. You should generally +avoid side effects in the expression arguments of this pragma. However, +the expressions are analyzed for semantic correctness whether or not +assertions are enabled, so turning assertions on and off cannot affect +the legality of a program. + +@node Pragma Ast_Entry +@unnumberedsec Pragma Ast_Entry +@cindex OpenVMS +@findex Ast_Entry +@noindent +Syntax: +@smallexample @c ada +pragma AST_Entry (entry_IDENTIFIER); +@end smallexample + +@noindent +This pragma is implemented only in the OpenVMS implementation of GNAT@. The +argument is the simple name of a single entry; at most one @code{AST_Entry} +pragma is allowed for any given entry. This pragma must be used in +conjunction with the @code{AST_Entry} attribute, and is only allowed after +the entry declaration and in the same task type specification or single task +as the entry to which it applies. This pragma specifies that the given entry +may be used to handle an OpenVMS asynchronous system trap (@code{AST}) +resulting from an OpenVMS system service call. The pragma does not affect +normal use of the entry. For further details on this pragma, see the +DEC Ada Language Reference Manual, section 9.12a. + +@node Pragma C_Pass_By_Copy +@unnumberedsec Pragma C_Pass_By_Copy +@cindex Passing by copy +@findex C_Pass_By_Copy +@noindent +Syntax: +@smallexample @c ada +pragma C_Pass_By_Copy + ([Max_Size =>] static_integer_EXPRESSION); +@end smallexample + +@noindent +Normally the default mechanism for passing C convention records to C +convention subprograms is to pass them by reference, as suggested by RM +B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change +this default, by requiring that record formal parameters be passed by +copy if all of the following conditions are met: + +@itemize @bullet +@item +The size of the record type does not exceed@*@var{static_integer_expression}. +@item +The record type has @code{Convention C}. +@item +The formal parameter has this record type, and the subprogram has a +foreign (non-Ada) convention. +@end itemize + +@noindent +If these conditions are met the argument is passed by copy, i.e.@: in a +manner consistent with what C expects if the corresponding formal in the +C prototype is a struct (rather than a pointer to a struct). + +You can also pass records by copy by specifying the convention +@code{C_Pass_By_Copy} for the record type, or by using the extended +@code{Import} and @code{Export} pragmas, which allow specification of +passing mechanisms on a parameter by parameter basis. + +@node Pragma Comment +@unnumberedsec Pragma Comment +@findex Comment +@noindent +Syntax: + +@smallexample @c ada +pragma Comment (static_string_EXPRESSION); +@end smallexample + +@noindent +This is almost identical in effect to pragma @code{Ident}. It allows the +placement of a comment into the object file and hence into the +executable file if the operating system permits such usage. The +difference is that @code{Comment}, unlike @code{Ident}, has +no limitations on placement of the pragma (it can be placed +anywhere in the main source unit), and if more than one pragma +is used, all comments are retained. + +@node Pragma Common_Object +@unnumberedsec Pragma Common_Object +@findex Common_Object +@noindent +Syntax: + +@smallexample @c ada +pragma Common_Object ( + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Size =>] EXTERNAL_SYMBOL] ); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +@end smallexample + +@noindent +This pragma enables the shared use of variables stored in overlaid +linker areas corresponding to the use of @code{COMMON} +in Fortran. The single +object @var{local_NAME} is assigned to the area designated by +the @var{External} argument. +You may define a record to correspond to a series +of fields. The @var{size} argument +is syntax checked in GNAT, but otherwise ignored. + +@code{Common_Object} is not supported on all platforms. If no +support is available, then the code generator will issue a message +indicating that the necessary attribute for implementation of this +pragma is not available. + +@node Pragma Compile_Time_Warning +@unnumberedsec Pragma Compile_Time_Warning +@findex Compile_Time_Warning +@noindent +Syntax: + +@smallexample @c ada +pragma Compile_Time_Warning + (boolean_EXPRESSION, static_string_EXPRESSION); +@end smallexample + +@noindent +This pragma can be used to generate additional compile time warnings. It +is particularly useful in generics, where warnings can be issued for +specific problematic instantiations. The first parameter is a boolean +expression. The pragma is effective only if the value of this expression +is known at compile time, and has the value True. The set of expressions +whose values are known at compile time includes all static boolean +expressions, and also other values which the compiler can determine +at compile time (e.g. the size of a record type set by an explicit +size representation clause, or the value of a variable which was +initialized to a constant and is known not to have been modified). +If these conditions are met, a warning message is generated using +the value given as the second argument. This string value may contain +embedded ASCII.LF characters to break the message into multiple lines. + +@node Pragma Complete_Representation +@unnumberedsec Pragma Complete_Representation +@findex Complete_Representation +@noindent +Syntax: + +@smallexample @c ada +pragma Complete_Representation; +@end smallexample + +@noindent +This pragma must appear immediately within a record representation +clause. Typical placements are before the first component clause +or after the last component clause. The effect is to give an error +message if any component is missing a component clause. This pragma +may be used to ensure that a record representation clause is +complete, and that this invariant is maintained if fields are +added to the record in the future. + +@node Pragma Complex_Representation +@unnumberedsec Pragma Complex_Representation +@findex Complex_Representation +@noindent +Syntax: + +@smallexample @c ada +pragma Complex_Representation + ([Entity =>] local_NAME); +@end smallexample + +@noindent +The @var{Entity} argument must be the name of a record type which has +two fields of the same floating-point type. The effect of this pragma is +to force gcc to use the special internal complex representation form for +this record, which may be more efficient. Note that this may result in +the code for this type not conforming to standard ABI (application +binary interface) requirements for the handling of record types. For +example, in some environments, there is a requirement for passing +records by pointer, and the use of this pragma may result in passing +this type in floating-point registers. + +@node Pragma Component_Alignment +@unnumberedsec Pragma Component_Alignment +@cindex Alignments of components +@findex Component_Alignment +@noindent +Syntax: + +@smallexample @c ada +pragma Component_Alignment ( + [Form =>] ALIGNMENT_CHOICE + [, [Name =>] type_local_NAME]); + +ALIGNMENT_CHOICE ::= + Component_Size +| Component_Size_4 +| Storage_Unit +| Default +@end smallexample + +@noindent +Specifies the alignment of components in array or record types. +The meaning of the @var{Form} argument is as follows: + +@table @code +@findex Component_Size +@item Component_Size +Aligns scalar components and subcomponents of the array or record type +on boundaries appropriate to their inherent size (naturally +aligned). For example, 1-byte components are aligned on byte boundaries, +2-byte integer components are aligned on 2-byte boundaries, 4-byte +integer components are aligned on 4-byte boundaries and so on. These +alignment rules correspond to the normal rules for C compilers on all +machines except the VAX@. + +@findex Component_Size_4 +@item Component_Size_4 +Naturally aligns components with a size of four or fewer +bytes. Components that are larger than 4 bytes are placed on the next +4-byte boundary. + +@findex Storage_Unit +@item Storage_Unit +Specifies that array or record components are byte aligned, i.e.@: +aligned on boundaries determined by the value of the constant +@code{System.Storage_Unit}. + +@cindex OpenVMS +@item Default +Specifies that array or record components are aligned on default +boundaries, appropriate to the underlying hardware or operating system or +both. For OpenVMS VAX systems, the @code{Default} choice is the same as +the @code{Storage_Unit} choice (byte alignment). For all other systems, +the @code{Default} choice is the same as @code{Component_Size} (natural +alignment). +@end table + +@noindent +If the @code{Name} parameter is present, @var{type_local_NAME} must +refer to a local record or array type, and the specified alignment +choice applies to the specified type. The use of +@code{Component_Alignment} together with a pragma @code{Pack} causes the +@code{Component_Alignment} pragma to be ignored. The use of +@code{Component_Alignment} together with a record representation clause +is only effective for fields not specified by the representation clause. + +If the @code{Name} parameter is absent, the pragma can be used as either +a configuration pragma, in which case it applies to one or more units in +accordance with the normal rules for configuration pragmas, or it can be +used within a declarative part, in which case it applies to types that +are declared within this declarative part, or within any nested scope +within this declarative part. In either case it specifies the alignment +to be applied to any record or array type which has otherwise standard +representation. + +If the alignment for a record or array type is not specified (using +pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep +clause), the GNAT uses the default alignment as described previously. + +@node Pragma Convention_Identifier +@unnumberedsec Pragma Convention_Identifier +@findex Convention_Identifier +@cindex Conventions, synonyms +@noindent +Syntax: + +@smallexample @c ada +pragma Convention_Identifier ( + [Name =>] IDENTIFIER, + [Convention =>] convention_IDENTIFIER); +@end smallexample + +@noindent +This pragma provides a mechanism for supplying synonyms for existing +convention identifiers. The @code{Name} identifier can subsequently +be used as a synonym for the given convention in other pragmas (including +for example pragma @code{Import} or another @code{Convention_Identifier} +pragma). As an example of the use of this, suppose you had legacy code +which used Fortran77 as the identifier for Fortran. Then the pragma: + +@smallexample @c ada +pragma Convention_Identifier (Fortran77, Fortran); +@end smallexample + +@noindent +would allow the use of the convention identifier @code{Fortran77} in +subsequent code, avoiding the need to modify the sources. As another +example, you could use this to parametrize convention requirements +according to systems. Suppose you needed to use @code{Stdcall} on +windows systems, and @code{C} on some other system, then you could +define a convention identifier @code{Library} and use a single +@code{Convention_Identifier} pragma to specify which convention +would be used system-wide. + +@node Pragma CPP_Class +@unnumberedsec Pragma CPP_Class +@findex CPP_Class +@cindex Interfacing with C++ +@noindent +Syntax: + +@smallexample @c ada +pragma CPP_Class ([Entity =>] local_NAME); +@end smallexample + +@noindent +The argument denotes an entity in the current declarative region +that is declared as a tagged or untagged record type. It indicates that +the type corresponds to an externally declared C++ class type, and is to +be laid out the same way that C++ would lay out the type. + +If (and only if) the type is tagged, at least one component in the +record must be of type @code{Interfaces.CPP.Vtable_Ptr}, corresponding +to the C++ Vtable (or Vtables in the case of multiple inheritance) used +for dispatching. + +Types for which @code{CPP_Class} is specified do not have assignment or +equality operators defined (such operations can be imported or declared +as subprograms as required). Initialization is allowed only by +constructor functions (see pragma @code{CPP_Constructor}). + +Pragma @code{CPP_Class} is intended primarily for automatic generation +using an automatic binding generator tool. +See @ref{Interfacing to C++} for related information. + +@node Pragma CPP_Constructor +@unnumberedsec Pragma CPP_Constructor +@cindex Interfacing with C++ +@findex CPP_Constructor +@noindent +Syntax: + +@smallexample @c ada +pragma CPP_Constructor ([Entity =>] local_NAME); +@end smallexample + +@noindent +This pragma identifies an imported function (imported in the usual way +with pragma @code{Import}) as corresponding to a C++ +constructor. The argument is a name that must have been +previously mentioned in a pragma @code{Import} +with @code{Convention} = @code{CPP}, and must be of one of the following +forms: + +@itemize @bullet +@item +@code{function @var{Fname} return @var{T}'Class} + +@item +@code{function @var{Fname} (@dots{}) return @var{T}'Class} +@end itemize + +@noindent +where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies. + +The first form is the default constructor, used when an object of type +@var{T} is created on the Ada side with no explicit constructor. Other +constructors (including the copy constructor, which is simply a special +case of the second form in which the one and only argument is of type +@var{T}), can only appear in two contexts: + +@itemize @bullet +@item +On the right side of an initialization of an object of type @var{T}. +@item +In an extension aggregate for an object of a type derived from @var{T}. +@end itemize + +@noindent +Although the constructor is described as a function that returns a value +on the Ada side, it is typically a procedure with an extra implicit +argument (the object being initialized) at the implementation +level. GNAT issues the appropriate call, whatever it is, to get the +object properly initialized. + +In the case of derived objects, you may use one of two possible forms +for declaring and creating an object: + +@itemize @bullet +@item @code{New_Object : Derived_T} +@item @code{New_Object : Derived_T := (@var{constructor-call with} @dots{})} +@end itemize + +@noindent +In the first case the default constructor is called and extension fields +if any are initialized according to the default initialization +expressions in the Ada declaration. In the second case, the given +constructor is called and the extension aggregate indicates the explicit +values of the extension fields. + +If no constructors are imported, it is impossible to create any objects +on the Ada side. If no default constructor is imported, only the +initialization forms using an explicit call to a constructor are +permitted. + +Pragma @code{CPP_Constructor} is intended primarily for automatic generation +using an automatic binding generator tool. +See @ref{Interfacing to C++} for more related information. + +@node Pragma CPP_Virtual +@unnumberedsec Pragma CPP_Virtual +@cindex Interfacing to C++ +@findex CPP_Virtual +@noindent +Syntax: + +@smallexample @c ada +pragma CPP_Virtual + [Entity =>] ENTITY, + [, [Vtable_Ptr =>] vtable_ENTITY,] + [, [Position =>] static_integer_EXPRESSION]); +@end smallexample + +@noindent +This pragma serves the same function as pragma @code{Import} in that +case of a virtual function imported from C++. The @var{Entity} argument +must be a +primitive subprogram of a tagged type to which pragma @code{CPP_Class} +applies. The @var{Vtable_Ptr} argument specifies +the Vtable_Ptr component which contains the +entry for this virtual function. The @var{Position} argument +is the sequential number +counting virtual functions for this Vtable starting at 1. + +The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if +there is one Vtable_Ptr present (single inheritance case) and all +virtual functions are imported. In that case the compiler can deduce both +these values. + +No @code{External_Name} or @code{Link_Name} arguments are required for a +virtual function, since it is always accessed indirectly via the +appropriate Vtable entry. + +Pragma @code{CPP_Virtual} is intended primarily for automatic generation +using an automatic binding generator tool. +See @ref{Interfacing to C++} for related information. + +@node Pragma CPP_Vtable +@unnumberedsec Pragma CPP_Vtable +@cindex Interfacing with C++ +@findex CPP_Vtable +@noindent +Syntax: + +@smallexample @c ada +pragma CPP_Vtable ( + [Entity =>] ENTITY, + [Vtable_Ptr =>] vtable_ENTITY, + [Entry_Count =>] static_integer_EXPRESSION); +@end smallexample + +@noindent +Given a record to which the pragma @code{CPP_Class} applies, +this pragma can be specified for each component of type +@code{CPP.Interfaces.Vtable_Ptr}. +@var{Entity} is the tagged type, @var{Vtable_Ptr} +is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is +the number of virtual functions on the C++ side. Not all of these +functions need to be imported on the Ada side. + +You may omit the @code{CPP_Vtable} pragma if there is only one +@code{Vtable_Ptr} component in the record and all virtual functions are +imported on the Ada side (the default value for the entry count in this +case is simply the total number of virtual functions). + +Pragma @code{CPP_Vtable} is intended primarily for automatic generation +using an automatic binding generator tool. +See @ref{Interfacing to C++} for related information. + +@node Pragma Debug +@unnumberedsec Pragma Debug +@findex Debug +@noindent +Syntax: + +@smallexample @c ada +pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); + +PROCEDURE_CALL_WITHOUT_SEMICOLON ::= + PROCEDURE_NAME +| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART +@end smallexample + +@noindent +The procedure call argument has the syntactic form of an expression, meeting +the syntactic requirements for pragmas. + +If debug pragmas are not enabled or if the condition is present and evaluates +to False, this pragma has no effect. If debug pragmas are enabled, the +semantics of the pragma is exactly equivalent to the procedure call statement +corresponding to the argument with a terminating semicolon. Pragmas are +permitted in sequences of declarations, so you can use pragma @code{Debug} to +intersperse calls to debug procedures in the middle of declarations. Debug +pragmas can be enabled either by use of the command line switch @code{-gnata} +or by use of the configuration pragma @code{Debug_Policy}. + +@node Pragma Debug_Policy +@unnumberedsec Pragma Debug_Policy +@findex Debug_Policy +@noindent +Syntax: + +@smallexample @c ada +pragma Debug_Policy (CHECK | IGNORE); +@end smallexample + +@noindent +If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled. +If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored. +This pragma overrides the effect of the @code{-gnata} switch on the +command line. + +@node Pragma Detect_Blocking +@unnumberedsec Pragma Detect_Blocking +@findex Detect_Blocking +@noindent +Syntax: + +@smallexample @c ada +pragma Detect_Blocking; +@end smallexample + +@noindent +This is a configuration pragma that forces the detection of potentially +blocking operations within a protected operation, and to raise Program_Error +if that happens. + +@node Pragma Elaboration_Checks +@unnumberedsec Pragma Elaboration_Checks +@cindex Elaboration control +@findex Elaboration_Checks +@noindent +Syntax: + +@smallexample @c ada +pragma Elaboration_Checks (Dynamic | Static); +@end smallexample + +@noindent +This is a configuration pragma that provides control over the +elaboration model used by the compilation affected by the +pragma. If the parameter is @code{Dynamic}, +then the dynamic elaboration +model described in the Ada Reference Manual is used, as though +the @code{-gnatE} switch had been specified on the command +line. If the parameter is @code{Static}, then the default GNAT static +model is used. This configuration pragma overrides the setting +of the command line. For full details on the elaboration models +used by the GNAT compiler, see section ``Elaboration Order +Handling in GNAT'' in the @cite{GNAT User's Guide}. + +@node Pragma Eliminate +@unnumberedsec Pragma Eliminate +@cindex Elimination of unused subprograms +@findex Eliminate +@noindent +Syntax: + +@smallexample @c ada +pragma Eliminate ( + [Unit_Name =>] IDENTIFIER | + SELECTED_COMPONENT); + +pragma Eliminate ( + [Unit_Name =>] IDENTIFIER | + SELECTED_COMPONENT, + [Entity =>] IDENTIFIER | + SELECTED_COMPONENT | + STRING_LITERAL + [,OVERLOADING_RESOLUTION]); + +OVERLOADING_RESOLUTION ::= PARAMETER_AND_RESULT_TYPE_PROFILE | + SOURCE_LOCATION + +PARAMETER_AND_RESULT_TYPE_PROFILE ::= PROCEDURE_PROFILE | + FUNCTION_PROFILE + +PROCEDURE_PROFILE ::= Parameter_Types => PARAMETER_TYPES + +FUNCTION_PROFILE ::= [Parameter_Types => PARAMETER_TYPES,] + Result_Type => result_SUBTYPE_NAME] + +PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@}) +SUBTYPE_NAME ::= STRING_VALUE + +SOURCE_LOCATION ::= Source_Location => SOURCE_TRACE +SOURCE_TRACE ::= STRING_VALUE + +STRING_VALUE ::= STRING_LITERAL @{& STRING_LITERAL@} +@end smallexample + +@noindent +This pragma indicates that the given entity is not used outside the +compilation unit it is defined in. The entity must be an explicitly declared +subprogram; this includes generic subprogram instances and +subprograms declared in generic package instances. + +If the entity to be eliminated is a library level subprogram, then +the first form of pragma @code{Eliminate} is used with only a single argument. +In this form, the @code{Unit_Name} argument specifies the name of the +library level unit to be eliminated. + +In all other cases, both @code{Unit_Name} and @code{Entity} arguments +are required. If item is an entity of a library package, then the first +argument specifies the unit name, and the second argument specifies +the particular entity. If the second argument is in string form, it must +correspond to the internal manner in which GNAT stores entity names (see +compilation unit Namet in the compiler sources for details). + +The remaining parameters (OVERLOADING_RESOLUTION) are optionally used +to distinguish between overloaded subprograms. If a pragma does not contain +the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded +subprograms denoted by the first two parameters. + +Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram +to be eliminated in a manner similar to that used for the extended +@code{Import} and @code{Export} pragmas, except that the subtype names are +always given as strings. At the moment, this form of distinguishing +overloaded subprograms is implemented only partially, so we do not recommend +using it for practical subprogram elimination. + +Note, that in case of a parameterless procedure its profile is represented +as @code{Parameter_Types => ("")} + +Alternatively, the @code{Source_Location} parameter is used to specify +which overloaded alternative is to be eliminated by pointing to the +location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the +source text. The string literal (or concatenation of string literals) +given as SOURCE_TRACE must have the following format: + +@smallexample @c ada +SOURCE_TRACE ::= SOURCE_LOCATION@{LBRACKET SOURCE_LOCATION RBRACKET@} + +LBRACKET ::= [ +RBRACKET ::= ] + +SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER +FILE_NAME ::= STRING_LITERAL +LINE_NUMBER ::= DIGIT @{DIGIT@} +@end smallexample + +SOURCE_TRACE should be the short name of the source file (with no directory +information), and LINE_NUMBER is supposed to point to the line where the +defining name of the subprogram is located. + +For the subprograms that are not a part of generic instantiations, only one +SOURCE_LOCATION is used. If a subprogram is declared in a package +instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is +the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the +second one denotes the declaration of the corresponding subprogram in the +generic package. This approach is recursively used to create SOURCE_LOCATIONs +in case of nested instantiations. + +The effect of the pragma is to allow the compiler to eliminate +the code or data associated with the named entity. Any reference to +an eliminated entity outside the compilation unit it is defined in, +causes a compile time or link time error. + +The intention of pragma @code{Eliminate} is to allow a program to be compiled +in a system independent manner, with unused entities eliminated, without +the requirement of modifying the source text. Normally the required set +of @code{Eliminate} pragmas is constructed automatically using the gnatelim +tool. Elimination of unused entities local to a compilation unit is +automatic, without requiring the use of pragma @code{Eliminate}. + +Note that the reason this pragma takes string literals where names might +be expected is that a pragma @code{Eliminate} can appear in a context where the +relevant names are not visible. + +Note that any change in the source files that includes removing, splitting of +adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION +parameter illegal. + +@node Pragma Export_Exception +@unnumberedsec Pragma Export_Exception +@cindex OpenVMS +@findex Export_Exception +@noindent +Syntax: + +@smallexample @c ada +pragma Export_Exception ( + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL,] + [, [Form =>] Ada | VMS] + [, [Code =>] static_integer_EXPRESSION]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +@end smallexample + +@noindent +This pragma is implemented only in the OpenVMS implementation of GNAT@. It +causes the specified exception to be propagated outside of the Ada program, +so that it can be handled by programs written in other OpenVMS languages. +This pragma establishes an external name for an Ada exception and makes the +name available to the OpenVMS Linker as a global symbol. For further details +on this pragma, see the +DEC Ada Language Reference Manual, section 13.9a3.2. + +@node Pragma Export_Function +@unnumberedsec Pragma Export_Function +@cindex Argument passing mechanisms +@findex Export_Function + +@noindent +Syntax: + +@smallexample @c ada +pragma Export_Function ( + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Result_Type =>] result_SUBTYPE_MARK] + [, [Mechanism =>] MECHANISM] + [, [Result_Mechanism =>] MECHANISM_NAME]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +| "" + +PARAMETER_TYPES ::= + null +| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} + +TYPE_DESIGNATOR ::= + subtype_NAME +| subtype_Name ' Access + +MECHANISM ::= + MECHANISM_NAME +| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) + +MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + +MECHANISM_NAME ::= + Value +| Reference +@end smallexample + +@noindent +Use this pragma to make a function externally callable and optionally +provide information on mechanisms to be used for passing parameter and +result values. We recommend, for the purposes of improving portability, +this pragma always be used in conjunction with a separate pragma +@code{Export}, which must precede the pragma @code{Export_Function}. +GNAT does not require a separate pragma @code{Export}, but if none is +present, @code{Convention Ada} is assumed, which is usually +not what is wanted, so it is usually appropriate to use this +pragma in conjunction with a @code{Export} or @code{Convention} +pragma that specifies the desired foreign convention. +Pragma @code{Export_Function} +(and @code{Export}, if present) must appear in the same declarative +region as the function to which they apply. + +@var{internal_name} must uniquely designate the function to which the +pragma applies. If more than one function name exists of this name in +the declarative part you must use the @code{Parameter_Types} and +@code{Result_Type} parameters is mandatory to achieve the required +unique designation. @var{subtype_ mark}s in these parameters must +exactly match the subtypes in the corresponding function specification, +using positional notation to match parameters with subtype marks. +The form with an @code{'Access} attribute can be used to match an +anonymous access parameter. + +@cindex OpenVMS +@cindex Passing by descriptor +Note that passing by descriptor is not supported, even on the OpenVMS +ports of GNAT@. + +@cindex Suppressing external name +Special treatment is given if the EXTERNAL is an explicit null +string or a static string expressions that evaluates to the null +string. In this case, no external name is generated. This form +still allows the specification of parameter mechanisms. + +@node Pragma Export_Object +@unnumberedsec Pragma Export_Object +@findex Export_Object +@noindent +Syntax: + +@smallexample @c ada +pragma Export_Object + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Size =>] EXTERNAL_SYMBOL] + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +@end smallexample + +@noindent +This pragma designates an object as exported, and apart from the +extended rules for external symbols, is identical in effect to the use of +the normal @code{Export} pragma applied to an object. You may use a +separate Export pragma (and you probably should from the point of view +of portability), but it is not required. @var{Size} is syntax checked, +but otherwise ignored by GNAT@. + +@node Pragma Export_Procedure +@unnumberedsec Pragma Export_Procedure +@findex Export_Procedure +@noindent +Syntax: + +@smallexample @c ada +pragma Export_Procedure ( + [Internal =>] local_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Mechanism =>] MECHANISM]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +| "" + +PARAMETER_TYPES ::= + null +| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} + +TYPE_DESIGNATOR ::= + subtype_NAME +| subtype_Name ' Access + +MECHANISM ::= + MECHANISM_NAME +| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) + +MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + +MECHANISM_NAME ::= + Value +| Reference +@end smallexample + +@noindent +This pragma is identical to @code{Export_Function} except that it +applies to a procedure rather than a function and the parameters +@code{Result_Type} and @code{Result_Mechanism} are not permitted. +GNAT does not require a separate pragma @code{Export}, but if none is +present, @code{Convention Ada} is assumed, which is usually +not what is wanted, so it is usually appropriate to use this +pragma in conjunction with a @code{Export} or @code{Convention} +pragma that specifies the desired foreign convention. + +@cindex OpenVMS +@cindex Passing by descriptor +Note that passing by descriptor is not supported, even on the OpenVMS +ports of GNAT@. + +@cindex Suppressing external name +Special treatment is given if the EXTERNAL is an explicit null +string or a static string expressions that evaluates to the null +string. In this case, no external name is generated. This form +still allows the specification of parameter mechanisms. + +@node Pragma Export_Value +@unnumberedsec Pragma Export_Value +@findex Export_Value +@noindent +Syntax: + +@smallexample @c ada +pragma Export_Value ( + [Value =>] static_integer_EXPRESSION, + [Link_Name =>] static_string_EXPRESSION); +@end smallexample + +@noindent +This pragma serves to export a static integer value for external use. +The first argument specifies the value to be exported. The Link_Name +argument specifies the symbolic name to be associated with the integer +value. This pragma is useful for defining a named static value in Ada +that can be referenced in assembly language units to be linked with +the application. This pragma is currently supported only for the +AAMP target and is ignored for other targets. + +@node Pragma Export_Valued_Procedure +@unnumberedsec Pragma Export_Valued_Procedure +@findex Export_Valued_Procedure +@noindent +Syntax: + +@smallexample @c ada +pragma Export_Valued_Procedure ( + [Internal =>] local_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Mechanism =>] MECHANISM]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +| "" + +PARAMETER_TYPES ::= + null +| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} + +TYPE_DESIGNATOR ::= + subtype_NAME +| subtype_Name ' Access + +MECHANISM ::= + MECHANISM_NAME +| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) + +MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + +MECHANISM_NAME ::= + Value +| Reference +@end smallexample + +@noindent +This pragma is identical to @code{Export_Procedure} except that the +first parameter of @var{local_NAME}, which must be present, must be of +mode @code{OUT}, and externally the subprogram is treated as a function +with this parameter as the result of the function. GNAT provides for +this capability to allow the use of @code{OUT} and @code{IN OUT} +parameters in interfacing to external functions (which are not permitted +in Ada functions). +GNAT does not require a separate pragma @code{Export}, but if none is +present, @code{Convention Ada} is assumed, which is almost certainly +not what is wanted since the whole point of this pragma is to interface +with foreign language functions, so it is usually appropriate to use this +pragma in conjunction with a @code{Export} or @code{Convention} +pragma that specifies the desired foreign convention. + +@cindex OpenVMS +@cindex Passing by descriptor +Note that passing by descriptor is not supported, even on the OpenVMS +ports of GNAT@. + +@cindex Suppressing external name +Special treatment is given if the EXTERNAL is an explicit null +string or a static string expressions that evaluates to the null +string. In this case, no external name is generated. This form +still allows the specification of parameter mechanisms. + +@node Pragma Extend_System +@unnumberedsec Pragma Extend_System +@cindex @code{system}, extending +@cindex Dec Ada 83 +@findex Extend_System +@noindent +Syntax: + +@smallexample @c ada +pragma Extend_System ([Name =>] IDENTIFIER); +@end smallexample + +@noindent +This pragma is used to provide backwards compatibility with other +implementations that extend the facilities of package @code{System}. In +GNAT, @code{System} contains only the definitions that are present in +the Ada 95 RM@. However, other implementations, notably the DEC Ada 83 +implementation, provide many extensions to package @code{System}. + +For each such implementation accommodated by this pragma, GNAT provides a +package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83 +implementation, which provides the required additional definitions. You +can use this package in two ways. You can @code{with} it in the normal +way and access entities either by selection or using a @code{use} +clause. In this case no special processing is required. + +However, if existing code contains references such as +@code{System.@var{xxx}} where @var{xxx} is an entity in the extended +definitions provided in package @code{System}, you may use this pragma +to extend visibility in @code{System} in a non-standard way that +provides greater compatibility with the existing code. Pragma +@code{Extend_System} is a configuration pragma whose single argument is +the name of the package containing the extended definition +(e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under +control of this pragma will be processed using special visibility +processing that looks in package @code{System.Aux_@var{xxx}} where +@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in +package @code{System}, but not found in package @code{System}. + +You can use this pragma either to access a predefined @code{System} +extension supplied with the compiler, for example @code{Aux_DEC} or +you can construct your own extension unit following the above +definition. Note that such a package is a child of @code{System} +and thus is considered part of the implementation. To compile +it you will have to use the appropriate switch for compiling +system units. See the GNAT User's Guide for details. + +@node Pragma External +@unnumberedsec Pragma External +@findex External +@noindent +Syntax: + +@smallexample @c ada +pragma External ( + [ Convention =>] convention_IDENTIFIER, + [ Entity =>] local_NAME + [, [External_Name =>] static_string_EXPRESSION ] + [, [Link_Name =>] static_string_EXPRESSION ]); +@end smallexample + +@noindent +This pragma is identical in syntax and semantics to pragma +@code{Export} as defined in the Ada Reference Manual. It is +provided for compatibility with some Ada 83 compilers that +used this pragma for exactly the same purposes as pragma +@code{Export} before the latter was standardized. + +@node Pragma External_Name_Casing +@unnumberedsec Pragma External_Name_Casing +@cindex Dec Ada 83 casing compatibility +@cindex External Names, casing +@cindex Casing of External names +@findex External_Name_Casing +@noindent +Syntax: + +@smallexample @c ada +pragma External_Name_Casing ( + Uppercase | Lowercase + [, Uppercase | Lowercase | As_Is]); +@end smallexample + +@noindent +This pragma provides control over the casing of external names associated +with Import and Export pragmas. There are two cases to consider: + +@table @asis +@item Implicit external names +Implicit external names are derived from identifiers. The most common case +arises when a standard Ada 95 Import or Export pragma is used with only two +arguments, as in: + +@smallexample @c ada + pragma Import (C, C_Routine); +@end smallexample + +@noindent +Since Ada is a case insensitive language, the spelling of the identifier in +the Ada source program does not provide any information on the desired +casing of the external name, and so a convention is needed. In GNAT the +default treatment is that such names are converted to all lower case +letters. This corresponds to the normal C style in many environments. +The first argument of pragma @code{External_Name_Casing} can be used to +control this treatment. If @code{Uppercase} is specified, then the name +will be forced to all uppercase letters. If @code{Lowercase} is specified, +then the normal default of all lower case letters will be used. + +This same implicit treatment is also used in the case of extended DEC Ada 83 +compatible Import and Export pragmas where an external name is explicitly +specified using an identifier rather than a string. + +@item Explicit external names +Explicit external names are given as string literals. The most common case +arises when a standard Ada 95 Import or Export pragma is used with three +arguments, as in: + +@smallexample @c ada +pragma Import (C, C_Routine, "C_routine"); +@end smallexample + +@noindent +In this case, the string literal normally provides the exact casing required +for the external name. The second argument of pragma +@code{External_Name_Casing} may be used to modify this behavior. +If @code{Uppercase} is specified, then the name +will be forced to all uppercase letters. If @code{Lowercase} is specified, +then the name will be forced to all lowercase letters. A specification of +@code{As_Is} provides the normal default behavior in which the casing is +taken from the string provided. +@end table + +@noindent +This pragma may appear anywhere that a pragma is valid. In particular, it +can be used as a configuration pragma in the @file{gnat.adc} file, in which +case it applies to all subsequent compilations, or it can be used as a program +unit pragma, in which case it only applies to the current unit, or it can +be used more locally to control individual Import/Export pragmas. + +It is primarily intended for use with OpenVMS systems, where many +compilers convert all symbols to upper case by default. For interfacing to +such compilers (e.g.@: the DEC C compiler), it may be convenient to use +the pragma: + +@smallexample @c ada +pragma External_Name_Casing (Uppercase, Uppercase); +@end smallexample + +@noindent +to enforce the upper casing of all external symbols. + +@node Pragma Finalize_Storage_Only +@unnumberedsec Pragma Finalize_Storage_Only +@findex Finalize_Storage_Only +@noindent +Syntax: + +@smallexample @c ada +pragma Finalize_Storage_Only (first_subtype_local_NAME); +@end smallexample + +@noindent +This pragma allows the compiler not to emit a Finalize call for objects +defined at the library level. This is mostly useful for types where +finalization is only used to deal with storage reclamation since in most +environments it is not necessary to reclaim memory just before terminating +execution, hence the name. + +@node Pragma Float_Representation +@unnumberedsec Pragma Float_Representation +@cindex OpenVMS +@findex Float_Representation +@noindent +Syntax: + +@smallexample @c ada +pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); + +FLOAT_REP ::= VAX_Float | IEEE_Float +@end smallexample + +@noindent +In the one argument form, this pragma is a configuration pragma which +allows control over the internal representation chosen for the predefined +floating point types declared in the packages @code{Standard} and +@code{System}. On all systems other than OpenVMS, the argument must +be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the +argument may be @code{VAX_Float} to specify the use of the VAX float +format for the floating-point types in Standard. This requires that +the standard runtime libraries be recompiled. See the +description of the @code{GNAT LIBRARY} command in the OpenVMS version +of the GNAT Users Guide for details on the use of this command. + +The two argument form specifies the representation to be used for +the specified floating-point type. On all systems other than OpenVMS, +the argument must +be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the +argument may be @code{VAX_Float} to specify the use of the VAX float +format, as follows: + +@itemize @bullet +@item +For digits values up to 6, F float format will be used. +@item +For digits values from 7 to 9, G float format will be used. +@item +For digits values from 10 to 15, F float format will be used. +@item +Digits values above 15 are not allowed. +@end itemize + +@node Pragma Ident +@unnumberedsec Pragma Ident +@findex Ident +@noindent +Syntax: + +@smallexample @c ada +pragma Ident (static_string_EXPRESSION); +@end smallexample + +@noindent +This pragma provides a string identification in the generated object file, +if the system supports the concept of this kind of identification string. +This pragma is allowed only in the outermost declarative part or +declarative items of a compilation unit. If more than one @code{Ident} +pragma is given, only the last one processed is effective. +@cindex OpenVMS +On OpenVMS systems, the effect of the pragma is identical to the effect of +the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the +maximum allowed length is 31 characters, so if it is important to +maintain compatibility with this compiler, you should obey this length +limit. + +@node Pragma Import_Exception +@unnumberedsec Pragma Import_Exception +@cindex OpenVMS +@findex Import_Exception +@noindent +Syntax: + +@smallexample @c ada +pragma Import_Exception ( + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL,] + [, [Form =>] Ada | VMS] + [, [Code =>] static_integer_EXPRESSION]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +@end smallexample + +@noindent +This pragma is implemented only in the OpenVMS implementation of GNAT@. +It allows OpenVMS conditions (for example, from OpenVMS system services or +other OpenVMS languages) to be propagated to Ada programs as Ada exceptions. +The pragma specifies that the exception associated with an exception +declaration in an Ada program be defined externally (in non-Ada code). +For further details on this pragma, see the +DEC Ada Language Reference Manual, section 13.9a.3.1. + +@node Pragma Import_Function +@unnumberedsec Pragma Import_Function +@findex Import_Function +@noindent +Syntax: + +@smallexample @c ada +pragma Import_Function ( + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Result_Type =>] SUBTYPE_MARK] + [, [Mechanism =>] MECHANISM] + [, [Result_Mechanism =>] MECHANISM_NAME] + [, [First_Optional_Parameter =>] IDENTIFIER]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION + +PARAMETER_TYPES ::= + null +| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} + +TYPE_DESIGNATOR ::= + subtype_NAME +| subtype_Name ' Access + +MECHANISM ::= + MECHANISM_NAME +| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) + +MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + +MECHANISM_NAME ::= + Value +| Reference +| Descriptor [([Class =>] CLASS_NAME)] + +CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca +@end smallexample + +@noindent +This pragma is used in conjunction with a pragma @code{Import} to +specify additional information for an imported function. The pragma +@code{Import} (or equivalent pragma @code{Interface}) must precede the +@code{Import_Function} pragma and both must appear in the same +declarative part as the function specification. + +The @var{Internal} argument must uniquely designate +the function to which the +pragma applies. If more than one function name exists of this name in +the declarative part you must use the @code{Parameter_Types} and +@var{Result_Type} parameters to achieve the required unique +designation. Subtype marks in these parameters must exactly match the +subtypes in the corresponding function specification, using positional +notation to match parameters with subtype marks. +The form with an @code{'Access} attribute can be used to match an +anonymous access parameter. + +You may optionally use the @var{Mechanism} and @var{Result_Mechanism} +parameters to specify passing mechanisms for the +parameters and result. If you specify a single mechanism name, it +applies to all parameters. Otherwise you may specify a mechanism on a +parameter by parameter basis using either positional or named +notation. If the mechanism is not specified, the default mechanism +is used. + +@cindex OpenVMS +@cindex Passing by descriptor +Passing by descriptor is supported only on the OpenVMS ports of GNAT@. + +@code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@. +It specifies that the designated parameter and all following parameters +are optional, meaning that they are not passed at the generated code +level (this is distinct from the notion of optional parameters in Ada +where the parameters are passed anyway with the designated optional +parameters). All optional parameters must be of mode @code{IN} and have +default parameter values that are either known at compile time +expressions, or uses of the @code{'Null_Parameter} attribute. + +@node Pragma Import_Object +@unnumberedsec Pragma Import_Object +@findex Import_Object +@noindent +Syntax: + +@smallexample @c ada +pragma Import_Object + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL], + [, [Size =>] EXTERNAL_SYMBOL]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +@end smallexample + +@noindent +This pragma designates an object as imported, and apart from the +extended rules for external symbols, is identical in effect to the use of +the normal @code{Import} pragma applied to an object. Unlike the +subprogram case, you need not use a separate @code{Import} pragma, +although you may do so (and probably should do so from a portability +point of view). @var{size} is syntax checked, but otherwise ignored by +GNAT@. + +@node Pragma Import_Procedure +@unnumberedsec Pragma Import_Procedure +@findex Import_Procedure +@noindent +Syntax: + +@smallexample @c ada +pragma Import_Procedure ( + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Mechanism =>] MECHANISM] + [, [First_Optional_Parameter =>] IDENTIFIER]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION + +PARAMETER_TYPES ::= + null +| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} + +TYPE_DESIGNATOR ::= + subtype_NAME +| subtype_Name ' Access + +MECHANISM ::= + MECHANISM_NAME +| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) + +MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + +MECHANISM_NAME ::= + Value +| Reference +| Descriptor [([Class =>] CLASS_NAME)] + +CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca +@end smallexample + +@noindent +This pragma is identical to @code{Import_Function} except that it +applies to a procedure rather than a function and the parameters +@code{Result_Type} and @code{Result_Mechanism} are not permitted. + +@node Pragma Import_Valued_Procedure +@unnumberedsec Pragma Import_Valued_Procedure +@findex Import_Valued_Procedure +@noindent +Syntax: + +@smallexample @c ada +pragma Import_Valued_Procedure ( + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Mechanism =>] MECHANISM] + [, [First_Optional_Parameter =>] IDENTIFIER]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION + +PARAMETER_TYPES ::= + null +| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} + +TYPE_DESIGNATOR ::= + subtype_NAME +| subtype_Name ' Access + +MECHANISM ::= + MECHANISM_NAME +| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) + +MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + +MECHANISM_NAME ::= + Value +| Reference +| Descriptor [([Class =>] CLASS_NAME)] + +CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca +@end smallexample + +@noindent +This pragma is identical to @code{Import_Procedure} except that the +first parameter of @var{local_NAME}, which must be present, must be of +mode @code{OUT}, and externally the subprogram is treated as a function +with this parameter as the result of the function. The purpose of this +capability is to allow the use of @code{OUT} and @code{IN OUT} +parameters in interfacing to external functions (which are not permitted +in Ada functions). You may optionally use the @code{Mechanism} +parameters to specify passing mechanisms for the parameters. +If you specify a single mechanism name, it applies to all parameters. +Otherwise you may specify a mechanism on a parameter by parameter +basis using either positional or named notation. If the mechanism is not +specified, the default mechanism is used. + +Note that it is important to use this pragma in conjunction with a separate +pragma Import that specifies the desired convention, since otherwise the +default convention is Ada, which is almost certainly not what is required. + +@node Pragma Initialize_Scalars +@unnumberedsec Pragma Initialize_Scalars +@findex Initialize_Scalars +@cindex debugging with Initialize_Scalars +@noindent +Syntax: + +@smallexample @c ada +pragma Initialize_Scalars; +@end smallexample + +@noindent +This pragma is similar to @code{Normalize_Scalars} conceptually but has +two important differences. First, there is no requirement for the pragma +to be used uniformly in all units of a partition, in particular, it is fine +to use this just for some or all of the application units of a partition, +without needing to recompile the run-time library. + +In the case where some units are compiled with the pragma, and some without, +then a declaration of a variable where the type is defined in package +Standard or is locally declared will always be subject to initialization, +as will any declaration of a scalar variable. For composite variables, +whether the variable is initialized may also depend on whether the package +in which the type of the variable is declared is compiled with the pragma. + +The other important difference is that you can control the value used +for initializing scalar objects. At bind time, you can select several +options for initialization. You can +initialize with invalid values (similar to Normalize_Scalars, though for +Initialize_Scalars it is not always possible to determine the invalid +values in complex cases like signed component fields with non-standard +sizes). You can also initialize with high or +low values, or with a specified bit pattern. See the users guide for binder +options for specifying these cases. + +This means that you can compile a program, and then without having to +recompile the program, you can run it with different values being used +for initializing otherwise uninitialized values, to test if your program +behavior depends on the choice. Of course the behavior should not change, +and if it does, then most likely you have an erroneous reference to an +uninitialized value. + +It is even possible to change the value at execution time eliminating even +the need to rebind with a different switch using an environment variable. +See the GNAT users guide for details. + +Note that pragma @code{Initialize_Scalars} is particularly useful in +conjunction with the enhanced validity checking that is now provided +in GNAT, which checks for invalid values under more conditions. +Using this feature (see description of the @code{-gnatV} flag in the +users guide) in conjunction with pragma @code{Initialize_Scalars} +provides a powerful new tool to assist in the detection of problems +caused by uninitialized variables. + +Note: the use of @code{Initialize_Scalars} has a fairly extensive +effect on the generated code. This may cause your code to be +substantially larger. It may also cause an increase in the amount +of stack required, so it is probably a good idea to turn on stack +checking (see description of stack checking in the GNAT users guide) +when using this pragma. + +@node Pragma Inline_Always +@unnumberedsec Pragma Inline_Always +@findex Inline_Always +@noindent +Syntax: + +@smallexample @c ada +pragma Inline_Always (NAME [, NAME]); +@end smallexample + +@noindent +Similar to pragma @code{Inline} except that inlining is not subject to +the use of option @code{-gnatn} and the inlining happens regardless of +whether this option is used. + +@node Pragma Inline_Generic +@unnumberedsec Pragma Inline_Generic +@findex Inline_Generic +@noindent +Syntax: + +@smallexample @c ada +pragma Inline_Generic (generic_package_NAME); +@end smallexample + +@noindent +This is implemented for compatibility with DEC Ada 83 and is recognized, +but otherwise ignored, by GNAT@. All generic instantiations are inlined +by default when using GNAT@. + +@node Pragma Interface +@unnumberedsec Pragma Interface +@findex Interface +@noindent +Syntax: + +@smallexample @c ada +pragma Interface ( + [Convention =>] convention_identifier, + [Entity =>] local_NAME + [, [External_Name =>] static_string_expression], + [, [Link_Name =>] static_string_expression]); +@end smallexample + +@noindent +This pragma is identical in syntax and semantics to +the standard Ada 95 pragma @code{Import}. It is provided for compatibility +with Ada 83. The definition is upwards compatible both with pragma +@code{Interface} as defined in the Ada 83 Reference Manual, and also +with some extended implementations of this pragma in certain Ada 83 +implementations. + +@node Pragma Interface_Name +@unnumberedsec Pragma Interface_Name +@findex Interface_Name +@noindent +Syntax: + +@smallexample @c ada +pragma Interface_Name ( + [Entity =>] local_NAME + [, [External_Name =>] static_string_EXPRESSION] + [, [Link_Name =>] static_string_EXPRESSION]); +@end smallexample + +@noindent +This pragma provides an alternative way of specifying the interface name +for an interfaced subprogram, and is provided for compatibility with Ada +83 compilers that use the pragma for this purpose. You must provide at +least one of @var{External_Name} or @var{Link_Name}. + +@node Pragma Interrupt_Handler +@unnumberedsec Pragma Interrupt_Handler +@findex Interrupt_Handler +@noindent +Syntax: + +@smallexample @c ada +pragma Interrupt_Handler (procedure_local_NAME); +@end smallexample + +@noindent +This program unit pragma is supported for parameterless protected procedures +as described in Annex C of the Ada Reference Manual. On the AAMP target +the pragma can also be specified for nonprotected parameterless procedures +that are declared at the library level (which includes procedures +declared at the top level of a library package). In the case of AAMP, +when this pragma is applied to a nonprotected procedure, the instruction +@code{IERET} is generated for returns from the procedure, enabling +maskable interrupts, in place of the normal return instruction. + +@node Pragma Interrupt_State +@unnumberedsec Pragma Interrupt_State +@findex Interrupt_State +@noindent +Syntax: + +@smallexample @c ada +pragma Interrupt_State (Name => value, State => SYSTEM | RUNTIME | USER); +@end smallexample + +@noindent +Normally certain interrupts are reserved to the implementation. Any attempt +to attach an interrupt causes Program_Error to be raised, as described in +RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in +many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is +reserved to the implementation, so that @kbd{Ctrl-C} can be used to +interrupt execution. Additionally, signals such as @code{SIGSEGV}, +@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific +Ada exceptions, or used to implement run-time functions such as the +@code{abort} statement and stack overflow checking. + +Pragma @code{Interrupt_State} provides a general mechanism for overriding +such uses of interrupts. It subsumes the functionality of pragma +@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not +available on OS/2, Windows or VMS. On all other platforms than VxWorks, +it applies to signals; on VxWorks, it applies to vectored hardware interrupts +and may be used to mark interrupts required by the board support package +as reserved. + +Interrupts can be in one of three states: +@itemize @bullet +@item System + +The interrupt is reserved (no Ada handler can be installed), and the +Ada run-time may not install a handler. As a result you are guaranteed +standard system default action if this interrupt is raised. + +@item Runtime + +The interrupt is reserved (no Ada handler can be installed). The run time +is allowed to install a handler for internal control purposes, but is +not required to do so. + +@item User + +The interrupt is unreserved. The user may install a handler to provide +some other action. +@end itemize + +@noindent +These states are the allowed values of the @code{State} parameter of the +pragma. The @code{Name} parameter is a value of the type +@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in +@code{Ada.Interrupts.Names}. + +This is a configuration pragma, and the binder will check that there +are no inconsistencies between different units in a partition in how a +given interrupt is specified. It may appear anywhere a pragma is legal. + +The effect is to move the interrupt to the specified state. + +By declaring interrupts to be SYSTEM, you guarantee the standard system +action, such as a core dump. + +By declaring interrupts to be USER, you guarantee that you can install +a handler. + +Note that certain signals on many operating systems cannot be caught and +handled by applications. In such cases, the pragma is ignored. See the +operating system documentation, or the value of the array @code{Reserved} +declared in the specification of package @code{System.OS_Interface}. + +Overriding the default state of signals used by the Ada runtime may interfere +with an application's runtime behavior in the cases of the synchronous signals, +and in the case of the signal used to implement the @code{abort} statement. + +@node Pragma Keep_Names +@unnumberedsec Pragma Keep_Names +@findex Keep_Names +@noindent +Syntax: + +@smallexample @c ada +pragma Keep_Names ([On =>] enumeration_first_subtype_local_NAME); +@end smallexample + +@noindent +The @var{local_NAME} argument +must refer to an enumeration first subtype +in the current declarative part. The effect is to retain the enumeration +literal names for use by @code{Image} and @code{Value} even if a global +@code{Discard_Names} pragma applies. This is useful when you want to +generally suppress enumeration literal names and for example you therefore +use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you +want to retain the names for specific enumeration types. + +@node Pragma License +@unnumberedsec Pragma License +@findex License +@cindex License checking +@noindent +Syntax: + +@smallexample @c ada +pragma License (Unrestricted | GPL | Modified_GPL | Restricted); +@end smallexample + +@noindent +This pragma is provided to allow automated checking for appropriate license +conditions with respect to the standard and modified GPL@. A pragma +@code{License}, which is a configuration pragma that typically appears at +the start of a source file or in a separate @file{gnat.adc} file, specifies +the licensing conditions of a unit as follows: + +@itemize @bullet +@item Unrestricted +This is used for a unit that can be freely used with no license restrictions. +Examples of such units are public domain units, and units from the Ada +Reference Manual. + +@item GPL +This is used for a unit that is licensed under the unmodified GPL, and which +therefore cannot be @code{with}'ed by a restricted unit. + +@item Modified_GPL +This is used for a unit licensed under the GNAT modified GPL that includes +a special exception paragraph that specifically permits the inclusion of +the unit in programs without requiring the entire program to be released +under the GPL@. + +@item Restricted +This is used for a unit that is restricted in that it is not permitted to +depend on units that are licensed under the GPL@. Typical examples are +proprietary code that is to be released under more restrictive license +conditions. Note that restricted units are permitted to @code{with} units +which are licensed under the modified GPL (this is the whole point of the +modified GPL). + +@end itemize + +@noindent +Normally a unit with no @code{License} pragma is considered to have an +unknown license, and no checking is done. However, standard GNAT headers +are recognized, and license information is derived from them as follows. + +@itemize @bullet + +A GNAT license header starts with a line containing 78 hyphens. The following +comment text is searched for the appearance of any of the following strings. + +If the string ``GNU General Public License'' is found, then the unit is assumed +to have GPL license, unless the string ``As a special exception'' follows, in +which case the license is assumed to be modified GPL@. + +If one of the strings +``This specification is adapted from the Ada Semantic Interface'' or +``This specification is derived from the Ada Reference Manual'' is found +then the unit is assumed to be unrestricted. +@end itemize + +@noindent +These default actions means that a program with a restricted license pragma +will automatically get warnings if a GPL unit is inappropriately +@code{with}'ed. For example, the program: + +@smallexample @c ada +with Sem_Ch3; +with GNAT.Sockets; +procedure Secret_Stuff is + @dots{} +end Secret_Stuff +@end smallexample + +@noindent +if compiled with pragma @code{License} (@code{Restricted}) in a +@file{gnat.adc} file will generate the warning: + +@smallexample +1. with Sem_Ch3; + | + >>> license of withed unit "Sem_Ch3" is incompatible + +2. with GNAT.Sockets; +3. procedure Secret_Stuff is +@end smallexample + +@noindent +Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT +compiler and is licensed under the +GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT +run time, and is therefore licensed under the modified GPL@. + +@node Pragma Link_With +@unnumberedsec Pragma Link_With +@findex Link_With +@noindent +Syntax: + +@smallexample @c ada +pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); +@end smallexample + +@noindent +This pragma is provided for compatibility with certain Ada 83 compilers. +It has exactly the same effect as pragma @code{Linker_Options} except +that spaces occurring within one of the string expressions are treated +as separators. For example, in the following case: + +@smallexample @c ada +pragma Link_With ("-labc -ldef"); +@end smallexample + +@noindent +results in passing the strings @code{-labc} and @code{-ldef} as two +separate arguments to the linker. In addition pragma Link_With allows +multiple arguments, with the same effect as successive pragmas. + +@node Pragma Linker_Alias +@unnumberedsec Pragma Linker_Alias +@findex Linker_Alias +@noindent +Syntax: + +@smallexample @c ada +pragma Linker_Alias ( + [Entity =>] local_NAME + [Target =>] static_string_EXPRESSION); +@end smallexample + +@noindent +@var{local_NAME} must refer to an object that is declared at the library +level. This pragma establishes the given entity as a linker alias for the +given target. It is equivalent to @code{__attribute__((alias))} in GNU C +and causes @var{local_NAME} to be emitted as an alias for the symbol +@var{static_string_EXPRESSION} in the object file, that is to say no space +is reserved for @var{local_NAME} by the assembler and it will be resolved +to the same address as @var{static_string_EXPRESSION} by the linker. + +The actual linker name for the target must be used (e.g. the fully +encoded name with qualification in Ada, or the mangled name in C++), +or it must be declared using the C convention with @code{pragma Import} +or @code{pragma Export}. + +Not all target machines support this pragma. On some of them it is accepted +only if @code{pragma Weak_External} has been applied to @var{local_NAME}. + +@smallexample @c ada +-- Example of the use of pragma Linker_Alias + +package p is + i : Integer := 1; + pragma Export (C, i); + + new_name_for_i : Integer; + pragma Linker_Alias (new_name_for_i, "i"); +end p; +@end smallexample + +@node Pragma Linker_Constructor +@unnumberedsec Pragma Linker_Constructor +@findex Linker_Constructor +@noindent +Syntax: + +@smallexample @c ada +pragma Linker_Constructor (procedure_LOCAL_NAME); +@end smallexample + +@noindent +@var{procedure_local_NAME} must refer to a parameterless procedure that +is declared at the library level. A procedure to which this pragma is +applied will be treated as an initialization routine by the linker. +It is equivalent to @code{__attribute__((constructor))} in GNU C and +causes @var{procedure_LOCAL_NAME} to be invoked before the entry point +of the executable is called (or immediately after the shared library is +loaded if the procedure is linked in a shared library), in particular +before the Ada run-time environment is set up. + +Because of these specific contexts, the set of operations such a procedure +can perform is very limited and the type of objects it can manipulate is +essentially restricted to the elementary types. In particular, it must only +contain code to which pragma Restrictions (No_Elaboration_Code) applies. + +This pragma is used by GNAT to implement auto-initialization of shared Stand +Alone Libraries, which provides a related capability without the restrictions +listed above. Where possible, the use of Stand Alone Libraries is preferable +to the use of this pragma. + +@node Pragma Linker_Destructor +@unnumberedsec Pragma Linker_Destructor +@findex Linker_Destructor +@noindent +Syntax: + +@smallexample @c ada +pragma Linker_Destructor (procedure_LOCAL_NAME); +@end smallexample + +@noindent +@var{procedure_local_NAME} must refer to a parameterless procedure that +is declared at the library level. A procedure to which this pragma is +applied will be treated as a finalization routine by the linker. +It is equivalent to @code{__attribute__((destructor))} in GNU C and +causes @var{procedure_LOCAL_NAME} to be invoked after the entry point +of the executable has exited (or immediately before the shared library +is unloaded if the procedure is linked in a shared library), in particular +after the Ada run-time environment is shut down. + +See @code{pragma Linker_Constructor} for the set of restrictions that apply +because of these specific contexts. + +@node Pragma Linker_Section +@unnumberedsec Pragma Linker_Section +@findex Linker_Section +@noindent +Syntax: + +@smallexample @c ada +pragma Linker_Section ( + [Entity =>] local_NAME + [Section =>] static_string_EXPRESSION); +@end smallexample + +@noindent +@var{local_NAME} must refer to an object that is declared at the library +level. This pragma specifies the name of the linker section for the given +entity. It is equivalent to @code{__attribute__((section))} in GNU C and +causes @var{local_NAME} to be placed in the @var{static_string_EXPRESSION} +section of the executable (assuming the linker doesn't rename the section). + +The compiler normally places library-level objects in standard sections +depending on their type: procedures and functions generally go in the +@code{.text} section, initialized variables in the @code{.data} section +and uninitialized variables in the @code{.bss} section. + +Other, special sections may exist on given target machines to map special +hardware, for example I/O ports or flash memory. This pragma is a means to +defer the final layout of the executable to the linker, thus fully working +at the symbolic level with the compiler. + +Some file formats do not support arbitrary sections so not all target +machines support this pragma. The use of this pragma may cause a program +execution to be erroneous if it is used to place an entity into an +inappropriate section (e.g. a modified variable into the @code{.text} +section). See also @code{pragma Persistent_BSS}. + +@smallexample @c ada +-- Example of the use of pragma Linker_Section + +package IO_Card is + Port_A : Integer; + pragma Volatile (Port_A); + pragma Linker_Section (Port_A, ".bss.port_a"); + + Port_B : Integer; + pragma Volatile (Port_B); + pragma Linker_Section (Port_B, ".bss.port_b"); +end IO_Card; +@end smallexample + +@node Pragma Long_Float +@unnumberedsec Pragma Long_Float +@cindex OpenVMS +@findex Long_Float +@noindent +Syntax: + +@smallexample @c ada +pragma Long_Float (FLOAT_FORMAT); + +FLOAT_FORMAT ::= D_Float | G_Float +@end smallexample + +@noindent +This pragma is implemented only in the OpenVMS implementation of GNAT@. +It allows control over the internal representation chosen for the predefined +type @code{Long_Float} and for floating point type representations with +@code{digits} specified in the range 7 through 15. +For further details on this pragma, see the +@cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use +this pragma, the standard runtime libraries must be recompiled. See the +description of the @code{GNAT LIBRARY} command in the OpenVMS version +of the GNAT User's Guide for details on the use of this command. + +@node Pragma Machine_Attribute +@unnumberedsec Pragma Machine_Attribute +@findex Machine_Attribute +@noindent +Syntax: + +@smallexample @c ada +pragma Machine_Attribute ( + [Attribute_Name =>] string_EXPRESSION, + [Entity =>] local_NAME); +@end smallexample + +@noindent +Machine-dependent attributes can be specified for types and/or +declarations. This pragma is semantically equivalent to +@code{__attribute__((@var{string_expression}))} in GNU C, +where @code{@var{string_expression}} is +recognized by the target macro @code{TARGET_ATTRIBUTE_TABLE} which is +defined for each machine. See the GCC manual for further information. +It is not possible to specify attributes defined by other languages, +only attributes defined by the machine the code is intended to run on. + +@node Pragma Main_Storage +@unnumberedsec Pragma Main_Storage +@cindex OpenVMS +@findex Main_Storage +@noindent +Syntax: + +@smallexample @c ada +pragma Main_Storage + (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); + +MAIN_STORAGE_OPTION ::= + [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION +| [TOP_GUARD =>] static_SIMPLE_EXPRESSION + +@end smallexample + +@noindent +This pragma is provided for compatibility with OpenVMS VAX Systems. It has +no effect in GNAT, other than being syntax checked. Note that the pragma +also has no effect in DEC Ada 83 for OpenVMS Alpha Systems. + +@node Pragma No_Return +@unnumberedsec Pragma No_Return +@findex No_Return +@noindent +Syntax: + +@smallexample @c ada +pragma No_Return (procedure_local_NAME @{, procedure_local_NAME@}); +@end smallexample + +@noindent +Each @var{procedure_local_NAME} argument must refer to one or more procedure +declarations in the current declarative part. A procedure to which this +pragma is applied may not contain any explicit @code{return} statements. +In addition, if the procedure contains any implicit returns from falling +off the end of a statement sequence, then execution of that implicit +return will cause Program_Error to be raised. + +One use of this pragma is to identify procedures whose only purpose is to raise +an exception. Another use of this pragma is to suppress incorrect warnings +about missing returns in functions, where the last statement of a function +statement sequence is a call to such a procedure. + +Note that in Ada 2005 mode, this pragma is part of the language, and is +identical in effect to the pragma as implemented in Ada 95 mode. + +@node Pragma No_Strict_Aliasing +@unnumberedsec Pragma No_Strict_Aliasing +@findex No_Strict_Aliasing +@noindent +Syntax: + +@smallexample @c ada +pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; +@end smallexample + +@noindent +@var{type_LOCAL_NAME} must refer to an access type +declaration in the current declarative part. The effect is to inhibit +strict aliasing optimization for the given type. The form with no +arguments is a configuration pragma which applies to all access types +declared in units to which the pragma applies. For a detailed +description of the strict aliasing optimization, and the situations +in which it must be suppressed, see section +``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide. + +@node Pragma Normalize_Scalars +@unnumberedsec Pragma Normalize_Scalars +@findex Normalize_Scalars +@noindent +Syntax: + +@smallexample @c ada +pragma Normalize_Scalars; +@end smallexample + +@noindent +This is a language defined pragma which is fully implemented in GNAT@. The +effect is to cause all scalar objects that are not otherwise initialized +to be initialized. The initial values are implementation dependent and +are as follows: + +@table @code +@item Standard.Character +@noindent +Objects whose root type is Standard.Character are initialized to +Character'Last unless the subtype range excludes NUL (in which case +NUL is used). This choice will always generate an invalid value if +one exists. + +@item Standard.Wide_Character +@noindent +Objects whose root type is Standard.Wide_Character are initialized to +Wide_Character'Last unless the subtype range excludes NUL (in which case +NUL is used). This choice will always generate an invalid value if +one exists. + +@item Standard.Wide_Wide_Character +@noindent +Objects whose root type is Standard.Wide_Wide_Character are initialized to +the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in +which case NUL is used). This choice will always generate an invalid value if +one exists. + +@item Integer types +@noindent +Objects of an integer type are treated differently depending on whether +negative values are present in the subtype. If no negative values are +present, then all one bits is used as the initial value except in the +special case where zero is excluded from the subtype, in which case +all zero bits are used. This choice will always generate an invalid +value if one exists. + +For subtypes with negative values present, the largest negative number +is used, except in the unusual case where this largest negative number +is in the subtype, and the largest positive number is not, in which case +the largest positive value is used. This choice will always generate +an invalid value if one exists. + +@item Floating-Point Types +Objects of all floating-point types are initialized to all 1-bits. For +standard IEEE format, this corresponds to a NaN (not a number) which is +indeed an invalid value. + +@item Fixed-Point Types +Objects of all fixed-point types are treated as described above for integers, +with the rules applying to the underlying integer value used to represent +the fixed-point value. + +@item Modular types +Objects of a modular type are initialized to all one bits, except in +the special case where zero is excluded from the subtype, in which +case all zero bits are used. This choice will always generate an +invalid value if one exists. + +@item Enumeration types +Objects of an enumeration type are initialized to all one-bits, i.e.@: to +the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal +whose Pos value is zero, in which case a code of zero is used. This choice +will always generate an invalid value if one exists. + +@end table + +@node Pragma Obsolescent +@unnumberedsec Pragma Obsolescent +@findex Obsolescent +@noindent +Syntax: + +@smallexample @c ada +pragma Obsolescent [(static_string_EXPRESSION [,Ada_05])]; +@end smallexample + +@noindent +This pragma can occur immediately following a subprogram +declaration and indicates that the associated function or procedure +is considered obsolescent and should not be used. Typically this is +used when an API must be modified by eventually removing or modifying +existing subprograms. The pragma can be used at an intermediate stage +when the subprogram is still present, but will be removed later. + +The effect of this pragma is to output a warning message on +a call to a program thus marked that the +subprogram is obsolescent if the appropriate warning option in the +compiler is activated. If a parameter is present, then a second +warning message is given containing this text. +In addition, a call to such a program is considered a violation of +pragma Restrictions (No_Obsolescent_Features). + +This pragma can also be used as a program unit pragma for a package, +in which case it indicates that the entire package is considered +obsolescent. In this case a client @code{with}'ing such a package +violates the restriction, and the @code{with} statement is +flagged with warnings if the warning option is set. + +If the optional second parameter is present (which must be exactly +the identifier Ada_05, no other argument is allowed), then the +indication of obsolescence applies only when compiling in Ada 2005 +mode. This is primarily intended for dealing with the situations +in the predefined library where subprograms or packages +have become defined as obsolescent in Ada 2005 +(e.g. in Ada.Characters.Handling), but may be used anywhere. + +@node Pragma Passive +@unnumberedsec Pragma Passive +@findex Passive +@noindent +Syntax: + +@smallexample @c ada +pragma Passive ([Semaphore | No]); +@end smallexample + +@noindent +Syntax checked, but otherwise ignored by GNAT@. This is recognized for +compatibility with DEC Ada 83 implementations, where it is used within a +task definition to request that a task be made passive. If the argument +@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 +treats the pragma as an assertion that the containing task is passive +and that optimization of context switch with this task is permitted and +desired. If the argument @code{No} is present, the task must not be +optimized. GNAT does not attempt to optimize any tasks in this manner +(since protected objects are available in place of passive tasks). + +@node Pragma Persistent_BSS +@unnumberedsec Pragma Persistent_BSS +@findex Persistent_BSS +@noindent +Syntax: + +@smallexample @c ada +pragma Persistent_BSS [local_NAME] +@end smallexample + +@noindent +This pragma allows selected objects to be placed in the @code{.persistent_bss} +section. On some targets the linker and loader provide for special +treatment of this section, allowing a program to be reloaded without +affecting the contents of this data (hence the name persistent). + +There are two forms of usage. If an argument is given, it must be the +local name of a library level object, with no explicit initialization +and whose type is potentially persistent. If no argument is given, then +the pragma is a configuration pragma, and applies to all library level +objects with no explicit initialization of potentially persistent types. + +A potentially persistent type is a scalar type, or a non-tagged, +non-discriminated record, all of whose components have no explicit +initialization and are themselves of a potentially persistent type, +or an array, all of whose constraints are static, and whose component +type is potentially persistent. + +If this pragma is used on a target where this feature is not supported, +then the pragma will be ignored. See also @code{pragma Linker_Section}. + +@node Pragma Polling +@unnumberedsec Pragma Polling +@findex Polling +@noindent +Syntax: + +@smallexample @c ada +pragma Polling (ON | OFF); +@end smallexample + +@noindent +This pragma controls the generation of polling code. This is normally off. +If @code{pragma Polling (ON)} is used then periodic calls are generated to +the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the +runtime library, and can be found in file @file{a-excpol.adb}. + +Pragma @code{Polling} can appear as a configuration pragma (for example it +can be placed in the @file{gnat.adc} file) to enable polling globally, or it +can be used in the statement or declaration sequence to control polling +more locally. + +A call to the polling routine is generated at the start of every loop and +at the start of every subprogram call. This guarantees that the @code{Poll} +routine is called frequently, and places an upper bound (determined by +the complexity of the code) on the period between two @code{Poll} calls. + +The primary purpose of the polling interface is to enable asynchronous +aborts on targets that cannot otherwise support it (for example Windows +NT), but it may be used for any other purpose requiring periodic polling. +The standard version is null, and can be replaced by a user program. This +will require re-compilation of the @code{Ada.Exceptions} package that can +be found in files @file{a-except.ads} and @file{a-except.adb}. + +A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT +distribution) is used to enable the asynchronous abort capability on +targets that do not normally support the capability. The version of +@code{Poll} in this file makes a call to the appropriate runtime routine +to test for an abort condition. + +Note that polling can also be enabled by use of the @code{-gnatP} switch. See +the @cite{GNAT User's Guide} for details. + +@node Pragma Profile (Ravenscar) +@unnumberedsec Pragma Profile (Ravenscar) +@findex Ravenscar +@noindent +Syntax: + +@smallexample @c ada +pragma Profile (Ravenscar); +@end smallexample + +@noindent +A configuration pragma that establishes the following set of configuration +pragmas: + +@table @code +@item Task_Dispatching_Policy (FIFO_Within_Priorities) +[RM D.2.2] Tasks are dispatched following a preemptive +priority-ordered scheduling policy. + +@item Locking_Policy (Ceiling_Locking) +[RM D.3] While tasks and interrupts execute a protected action, they inherit +the ceiling priority of the corresponding protected object. +@c +@c @item Detect_Blocking +@c This pragma forces the detection of potentially blocking operations within a +@c protected operation, and to raise Program_Error if that happens. +@end table +@noindent + +plus the following set of restrictions: + +@table @code +@item Max_Entry_Queue_Length = 1 +Defines the maximum number of calls that are queued on a (protected) entry. +Note that this restrictions is checked at run time. Violation of this +restriction results in the raising of Program_Error exception at the point of +the call. For the Profile (Ravenscar) the value of Max_Entry_Queue_Length is +always 1 and hence no task can be queued on a protected entry. + +@item Max_Protected_Entries = 1 +[RM D.7] Specifies the maximum number of entries per protected type. The +bounds of every entry family of a protected unit shall be static, or shall be +defined by a discriminant of a subtype whose corresponding bound is static. +For the Profile (Ravenscar) the value of Max_Protected_Entries is always 1. + +@item Max_Task_Entries = 0 +[RM D.7] Specifies the maximum number of entries +per task. The bounds of every entry family +of a task unit shall be static, or shall be +defined by a discriminant of a subtype whose +corresponding bound is static. A value of zero +indicates that no rendezvous are possible. For +the Profile (Ravenscar), the value of Max_Task_Entries is always +0 (zero). + +@item No_Abort_Statements +[RM D.7] There are no abort_statements, and there are +no calls to Task_Identification.Abort_Task. + +@item No_Asynchronous_Control +[RM D.7] There are no semantic dependences on the package +Asynchronous_Task_Control. + +@item No_Calendar +There are no semantic dependencies on the package Ada.Calendar. + +@item No_Dynamic_Attachment +There is no call to any of the operations defined in package Ada.Interrupts +(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, +Detach_Handler, and Reference). + +@item No_Dynamic_Priorities +[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. + +@item No_Implicit_Heap_Allocations +[RM D.7] No constructs are allowed to cause implicit heap allocation. + +@item No_Local_Protected_Objects +Protected objects and access types that designate +such objects shall be declared only at library level. + +@item No_Protected_Type_Allocators +There are no allocators for protected types or +types containing protected subcomponents. + +@item No_Relative_Delay +There are no delay_relative statements. + +@item No_Requeue_Statements +Requeue statements are not allowed. + +@item No_Select_Statements +There are no select_statements. + +@item No_Task_Allocators +[RM D.7] There are no allocators for task types +or types containing task subcomponents. + +@item No_Task_Attributes_Package +There are no semantic dependencies on the Ada.Task_Attributes package. + +@item No_Task_Hierarchy +[RM D.7] All (non-environment) tasks depend +directly on the environment task of the partition. + +@item No_Task_Termination +Tasks which terminate are erroneous. + +@item Simple_Barriers +Entry barrier condition expressions shall be either static +boolean expressions or boolean objects which are declared in +the protected type which contains the entry. +@end table + +@noindent +This set of configuration pragmas and restrictions correspond to the +definition of the ``Ravenscar Profile'' for limited tasking, devised and +published by the @cite{International Real-Time Ada Workshop}, 1997, +and whose most recent description is available at +@url{ftp://ftp.openravenscar.org/openravenscar/ravenscar00.pdf}. + +The original definition of the profile was revised at subsequent IRTAW +meetings. It has been included in the ISO +@cite{Guide for the Use of the Ada Programming Language in High +Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in +the next revision of the standard. The formal definition given by +the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and +AI-305) available at +@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00249.TXT} and +@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00305.TXT} +respectively. + +The above set is a superset of the restrictions provided by pragma +@code{Profile (Restricted)}, it includes six additional restrictions +(@code{Simple_Barriers}, @code{No_Select_Statements}, +@code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, +@code{No_Relative_Delay} and @code{No_Task_Termination}). This means +that pragma @code{Profile (Ravenscar)}, like the pragma +@code{Profile (Restricted)}, +automatically causes the use of a simplified, +more efficient version of the tasking run-time system. + +@node Pragma Profile (Restricted) +@unnumberedsec Pragma Profile (Restricted) +@findex Restricted Run Time +@noindent +Syntax: + +@smallexample @c ada +pragma Profile (Restricted); +@end smallexample + +@noindent +A configuration pragma that establishes the following set of restrictions: + +@itemize @bullet +@item No_Abort_Statements +@item No_Entry_Queue +@item No_Task_Hierarchy +@item No_Task_Allocators +@item No_Dynamic_Priorities +@item No_Terminate_Alternatives +@item No_Dynamic_Attachment +@item No_Protected_Type_Allocators +@item No_Local_Protected_Objects +@item No_Requeue_Statements +@item No_Task_Attributes_Package +@item Max_Asynchronous_Select_Nesting = 0 +@item Max_Task_Entries = 0 +@item Max_Protected_Entries = 1 +@item Max_Select_Alternatives = 0 +@end itemize + +@noindent +This set of restrictions causes the automatic selection of a simplified +version of the run time that provides improved performance for the +limited set of tasking functionality permitted by this set of restrictions. + +@node Pragma Psect_Object +@unnumberedsec Pragma Psect_Object +@findex Psect_Object +@noindent +Syntax: + +@smallexample @c ada +pragma Psect_Object ( + [Internal =>] local_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Size =>] EXTERNAL_SYMBOL]); + +EXTERNAL_SYMBOL ::= + IDENTIFIER +| static_string_EXPRESSION +@end smallexample + +@noindent +This pragma is identical in effect to pragma @code{Common_Object}. + +@node Pragma Pure_Function +@unnumberedsec Pragma Pure_Function +@findex Pure_Function +@noindent +Syntax: + +@smallexample @c ada +pragma Pure_Function ([Entity =>] function_local_NAME); +@end smallexample + +@noindent +This pragma appears in the same declarative part as a function +declaration (or a set of function declarations if more than one +overloaded declaration exists, in which case the pragma applies +to all entities). It specifies that the function @code{Entity} is +to be considered pure for the purposes of code generation. This means +that the compiler can assume that there are no side effects, and +in particular that two calls with identical arguments produce the +same result. It also means that the function can be used in an +address clause. + +Note that, quite deliberately, there are no static checks to try +to ensure that this promise is met, so @code{Pure_Function} can be used +with functions that are conceptually pure, even if they do modify +global variables. For example, a square root function that is +instrumented to count the number of times it is called is still +conceptually pure, and can still be optimized, even though it +modifies a global variable (the count). Memo functions are another +example (where a table of previous calls is kept and consulted to +avoid re-computation). + +@findex Pure +Note: Most functions in a @code{Pure} package are automatically pure, and +there is no need to use pragma @code{Pure_Function} for such functions. One +exception is any function that has at least one formal of type +@code{System.Address} or a type derived from it. Such functions are not +considered pure by default, since the compiler assumes that the +@code{Address} parameter may be functioning as a pointer and that the +referenced data may change even if the address value does not. +Similarly, imported functions are not considered to be pure by default, +since there is no way of checking that they are in fact pure. The use +of pragma @code{Pure_Function} for such a function will override these default +assumption, and cause the compiler to treat a designated subprogram as pure +in these cases. + +Note: If pragma @code{Pure_Function} is applied to a renamed function, it +applies to the underlying renamed function. This can be used to +disambiguate cases of overloading where some but not all functions +in a set of overloaded functions are to be designated as pure. + +If pragma @code{Pure_Function} is applied to a library level function, the +function is also considered pure from an optimization point of view, but the +unit is not a Pure unit in the categorization sense. So for example, a function +thus marked is free to @code{with} non-pure units. + +@node Pragma Restriction_Warnings +@unnumberedsec Pragma Restriction_Warnings +@findex Restriction_Warnings +@noindent +Syntax: + +@smallexample @c ada +pragma Restriction_Warnings + (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); +@end smallexample + +@noindent +This pragma allows a series of restriction identifiers to be +specified (the list of allowed identifiers is the same as for +pragma @code{Restrictions}). For each of these identifiers +the compiler checks for violations of the restriction, but +generates a warning message rather than an error message +if the restriction is violated. + +@node Pragma Source_File_Name +@unnumberedsec Pragma Source_File_Name +@findex Source_File_Name +@noindent +Syntax: + +@smallexample @c ada +pragma Source_File_Name ( + [Unit_Name =>] unit_NAME, + Spec_File_Name => STRING_LITERAL); + +pragma Source_File_Name ( + [Unit_Name =>] unit_NAME, + Body_File_Name => STRING_LITERAL); +@end smallexample + +@noindent +Use this to override the normal naming convention. It is a configuration +pragma, and so has the usual applicability of configuration pragmas +(i.e.@: it applies to either an entire partition, or to all units in a +compilation, or to a single unit, depending on how it is used. +@var{unit_name} is mapped to @var{file_name_literal}. The identifier for +the second argument is required, and indicates whether this is the file +name for the spec or for the body. + +Another form of the @code{Source_File_Name} pragma allows +the specification of patterns defining alternative file naming schemes +to apply to all files. + +@smallexample @c ada +pragma Source_File_Name + (Spec_File_Name => STRING_LITERAL + [,Casing => CASING_SPEC] + [,Dot_Replacement => STRING_LITERAL]); + +pragma Source_File_Name + (Body_File_Name => STRING_LITERAL + [,Casing => CASING_SPEC] + [,Dot_Replacement => STRING_LITERAL]); + +pragma Source_File_Name + (Subunit_File_Name => STRING_LITERAL + [,Casing => CASING_SPEC] + [,Dot_Replacement => STRING_LITERAL]); + +CASING_SPEC ::= Lowercase | Uppercase | Mixedcase +@end smallexample + +@noindent +The first argument is a pattern that contains a single asterisk indicating +the point at which the unit name is to be inserted in the pattern string +to form the file name. The second argument is optional. If present it +specifies the casing of the unit name in the resulting file name string. +The default is lower case. Finally the third argument allows for systematic +replacement of any dots in the unit name by the specified string literal. + +A pragma Source_File_Name cannot appear after a +@ref{Pragma Source_File_Name_Project}. + +For more details on the use of the @code{Source_File_Name} pragma, +see the sections ``Using Other File Names'' and +``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}. + +@node Pragma Source_File_Name_Project +@unnumberedsec Pragma Source_File_Name_Project +@findex Source_File_Name_Project +@noindent + +This pragma has the same syntax and semantics as pragma Source_File_Name. +It is only allowed as a stand alone configuration pragma. +It cannot appear after a @ref{Pragma Source_File_Name}, and +most importantly, once pragma Source_File_Name_Project appears, +no further Source_File_Name pragmas are allowed. + +The intention is that Source_File_Name_Project pragmas are always +generated by the Project Manager in a manner consistent with the naming +specified in a project file, and when naming is controlled in this manner, +it is not permissible to attempt to modify this naming scheme using +Source_File_Name pragmas (which would not be known to the project manager). + +@node Pragma Source_Reference +@unnumberedsec Pragma Source_Reference +@findex Source_Reference +@noindent +Syntax: + +@smallexample @c ada +pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); +@end smallexample + +@noindent +This pragma must appear as the first line of a source file. +@var{integer_literal} is the logical line number of the line following +the pragma line (for use in error messages and debugging +information). @var{string_literal} is a static string constant that +specifies the file name to be used in error messages and debugging +information. This is most notably used for the output of @code{gnatchop} +with the @code{-r} switch, to make sure that the original unchopped +source file is the one referred to. + +The second argument must be a string literal, it cannot be a static +string expression other than a string literal. This is because its value +is needed for error messages issued by all phases of the compiler. + +@node Pragma Stream_Convert +@unnumberedsec Pragma Stream_Convert +@findex Stream_Convert +@noindent +Syntax: + +@smallexample @c ada +pragma Stream_Convert ( + [Entity =>] type_local_NAME, + [Read =>] function_NAME, + [Write =>] function_NAME); +@end smallexample + +@noindent +This pragma provides an efficient way of providing stream functions for +types defined in packages. Not only is it simpler to use than declaring +the necessary functions with attribute representation clauses, but more +significantly, it allows the declaration to made in such a way that the +stream packages are not loaded unless they are needed. The use of +the Stream_Convert pragma adds no overhead at all, unless the stream +attributes are actually used on the designated type. + +The first argument specifies the type for which stream functions are +provided. The second parameter provides a function used to read values +of this type. It must name a function whose argument type may be any +subtype, and whose returned type must be the type given as the first +argument to the pragma. + +The meaning of the @var{Read} +parameter is that if a stream attribute directly +or indirectly specifies reading of the type given as the first parameter, +then a value of the type given as the argument to the Read function is +read from the stream, and then the Read function is used to convert this +to the required target type. + +Similarly the @var{Write} parameter specifies how to treat write attributes +that directly or indirectly apply to the type given as the first parameter. +It must have an input parameter of the type specified by the first parameter, +and the return type must be the same as the input type of the Read function. +The effect is to first call the Write function to convert to the given stream +type, and then write the result type to the stream. + +The Read and Write functions must not be overloaded subprograms. If necessary +renamings can be supplied to meet this requirement. +The usage of this attribute is best illustrated by a simple example, taken +from the GNAT implementation of package Ada.Strings.Unbounded: + +@smallexample @c ada +function To_Unbounded (S : String) + return Unbounded_String + renames To_Unbounded_String; + +pragma Stream_Convert + (Unbounded_String, To_Unbounded, To_String); +@end smallexample + +@noindent +The specifications of the referenced functions, as given in the Ada 95 +Reference Manual are: + +@smallexample @c ada +function To_Unbounded_String (Source : String) + return Unbounded_String; + +function To_String (Source : Unbounded_String) + return String; +@end smallexample + +@noindent +The effect is that if the value of an unbounded string is written to a +stream, then the representation of the item in the stream is in the same +format used for @code{Standard.String}, and this same representation is +expected when a value of this type is read from the stream. + +@node Pragma Style_Checks +@unnumberedsec Pragma Style_Checks +@findex Style_Checks +@noindent +Syntax: + +@smallexample @c ada +pragma Style_Checks (string_LITERAL | ALL_CHECKS | + On | Off [, local_NAME]); +@end smallexample + +@noindent +This pragma is used in conjunction with compiler switches to control the +built in style checking provided by GNAT@. The compiler switches, if set, +provide an initial setting for the switches, and this pragma may be used +to modify these settings, or the settings may be provided entirely by +the use of the pragma. This pragma can be used anywhere that a pragma +is legal, including use as a configuration pragma (including use in +the @file{gnat.adc} file). + +The form with a string literal specifies which style options are to be +activated. These are additive, so they apply in addition to any previously +set style check options. The codes for the options are the same as those +used in the @code{-gnaty} switch to @code{gcc} or @code{gnatmake}. +For example the following two methods can be used to enable +layout checking: + +@itemize @bullet +@item +@smallexample @c ada +pragma Style_Checks ("l"); +@end smallexample + +@item +@smallexample +gcc -c -gnatyl @dots{} +@end smallexample +@end itemize + +@noindent +The form ALL_CHECKS activates all standard checks (its use is equivalent +to the use of the @code{gnaty} switch with no options. See GNAT User's +Guide for details. + +The forms with @code{Off} and @code{On} +can be used to temporarily disable style checks +as shown in the following example: + +@smallexample @c ada +@iftex +@leftskip=0cm +@end iftex +pragma Style_Checks ("k"); -- requires keywords in lower case +pragma Style_Checks (Off); -- turn off style checks +NULL; -- this will not generate an error message +pragma Style_Checks (On); -- turn style checks back on +NULL; -- this will generate an error message +@end smallexample + +@noindent +Finally the two argument form is allowed only if the first argument is +@code{On} or @code{Off}. The effect is to turn of semantic style checks +for the specified entity, as shown in the following example: + +@smallexample @c ada +@iftex +@leftskip=0cm +@end iftex +pragma Style_Checks ("r"); -- require consistency of identifier casing +Arg : Integer; +Rf1 : Integer := ARG; -- incorrect, wrong case +pragma Style_Checks (Off, Arg); +Rf2 : Integer := ARG; -- OK, no error +@end smallexample + +@node Pragma Subtitle +@unnumberedsec Pragma Subtitle +@findex Subtitle +@noindent +Syntax: + +@smallexample @c ada +pragma Subtitle ([Subtitle =>] STRING_LITERAL); +@end smallexample + +@noindent +This pragma is recognized for compatibility with other Ada compilers +but is ignored by GNAT@. + +@node Pragma Suppress_All +@unnumberedsec Pragma Suppress_All +@findex Suppress_All +@noindent +Syntax: + +@smallexample @c ada +pragma Suppress_All; +@end smallexample + +@noindent +This pragma can only appear immediately following a compilation +unit. The effect is to apply @code{Suppress (All_Checks)} to the unit +which it follows. This pragma is implemented for compatibility with DEC +Ada 83 usage. The use of pragma @code{Suppress (All_Checks)} as a normal +configuration pragma is the preferred usage in GNAT@. + +@node Pragma Suppress_Exception_Locations +@unnumberedsec Pragma Suppress_Exception_Locations +@findex Suppress_Exception_Locations +@noindent +Syntax: + +@smallexample @c ada +pragma Suppress_Exception_Locations; +@end smallexample + +@noindent +In normal mode, a raise statement for an exception by default generates +an exception message giving the file name and line number for the location +of the raise. This is useful for debugging and logging purposes, but this +entails extra space for the strings for the messages. The configuration +pragma @code{Suppress_Exception_Locations} can be used to suppress the +generation of these strings, with the result that space is saved, but the +exception message for such raises is null. This configuration pragma may +appear in a global configuration pragma file, or in a specific unit as +usual. It is not required that this pragma be used consistently within +a partition, so it is fine to have some units within a partition compiled +with this pragma and others compiled in normal mode without it. + +@node Pragma Suppress_Initialization +@unnumberedsec Pragma Suppress_Initialization +@findex Suppress_Initialization +@cindex Suppressing initialization +@cindex Initialization, suppression of +@noindent +Syntax: + +@smallexample @c ada +pragma Suppress_Initialization ([Entity =>] type_Name); +@end smallexample + +@noindent +This pragma suppresses any implicit or explicit initialization +associated with the given type name for all variables of this type. + +@node Pragma Task_Info +@unnumberedsec Pragma Task_Info +@findex Task_Info +@noindent +Syntax + +@smallexample @c ada +pragma Task_Info (EXPRESSION); +@end smallexample + +@noindent +This pragma appears within a task definition (like pragma +@code{Priority}) and applies to the task in which it appears. The +argument must be of type @code{System.Task_Info.Task_Info_Type}. +The @code{Task_Info} pragma provides system dependent control over +aspects of tasking implementation, for example, the ability to map +tasks to specific processors. For details on the facilities available +for the version of GNAT that you are using, see the documentation +in the specification of package System.Task_Info in the runtime +library. + +@node Pragma Task_Name +@unnumberedsec Pragma Task_Name +@findex Task_Name +@noindent +Syntax + +@smallexample @c ada +pragma Task_Name (string_EXPRESSION); +@end smallexample + +@noindent +This pragma appears within a task definition (like pragma +@code{Priority}) and applies to the task in which it appears. The +argument must be of type String, and provides a name to be used for +the task instance when the task is created. Note that this expression +is not required to be static, and in particular, it can contain +references to task discriminants. This facility can be used to +provide different names for different tasks as they are created, +as illustrated in the example below. + +The task name is recorded internally in the run-time structures +and is accessible to tools like the debugger. In addition the +routine @code{Ada.Task_Identification.Image} will return this +string, with a unique task address appended. + +@smallexample @c ada +-- Example of the use of pragma Task_Name + +with Ada.Task_Identification; +use Ada.Task_Identification; +with Text_IO; use Text_IO; +procedure t3 is + + type Astring is access String; + + task type Task_Typ (Name : access String) is + pragma Task_Name (Name.all); + end Task_Typ; + + task body Task_Typ is + Nam : constant String := Image (Current_Task); + begin + Put_Line ("-->" & Nam (1 .. 14) & "<--"); + end Task_Typ; + + type Ptr_Task is access Task_Typ; + Task_Var : Ptr_Task; + +begin + Task_Var := + new Task_Typ (new String'("This is task 1")); + Task_Var := + new Task_Typ (new String'("This is task 2")); +end; +@end smallexample + +@node Pragma Task_Storage +@unnumberedsec Pragma Task_Storage +@findex Task_Storage +Syntax: + +@smallexample @c ada +pragma Task_Storage ( + [Task_Type =>] local_NAME, + [Top_Guard =>] static_integer_EXPRESSION); +@end smallexample + +@noindent +This pragma specifies the length of the guard area for tasks. The guard +area is an additional storage area allocated to a task. A value of zero +means that either no guard area is created or a minimal guard area is +created, depending on the target. This pragma can appear anywhere a +@code{Storage_Size} attribute definition clause is allowed for a task +type. + +@node Pragma Thread_Body +@unnumberedsec Pragma Thread_Body +@findex Thread_Body +Syntax: + +@smallexample @c ada +pragma Thread_Body ( + [Entity =>] local_NAME, + [[Secondary_Stack_Size =>] static_integer_EXPRESSION)]; +@end smallexample + +@noindent +This pragma specifies that the subprogram whose name is given as the +@code{Entity} argument is a thread body, which will be activated +by being called via its Address from foreign code. The purpose is +to allow execution and registration of the foreign thread within the +Ada run-time system. + +See the library unit @code{System.Threads} for details on the expansion of +a thread body subprogram, including the calls made to subprograms +within System.Threads to register the task. This unit also lists the +targets and runtime systems for which this pragma is supported. + +A thread body subprogram may not be called directly from Ada code, and +it is not permitted to apply the Access (or Unrestricted_Access) attributes +to such a subprogram. The only legitimate way of calling such a subprogram +is to pass its Address to foreign code and then make the call from the +foreign code. + +A thread body subprogram may have any parameters, and it may be a function +returning a result. The convention of the thread body subprogram may be +set in the usual manner using @code{pragma Convention}. + +The secondary stack size parameter, if given, is used to set the size +of secondary stack for the thread. The secondary stack is allocated as +a local variable of the expanded thread body subprogram, and thus is +allocated out of the main thread stack size. If no secondary stack +size parameter is present, the default size (from the declaration in +@code{System.Secondary_Stack} is used. + +@node Pragma Time_Slice +@unnumberedsec Pragma Time_Slice +@findex Time_Slice +@noindent +Syntax: + +@smallexample @c ada +pragma Time_Slice (static_duration_EXPRESSION); +@end smallexample + +@noindent +For implementations of GNAT on operating systems where it is possible +to supply a time slice value, this pragma may be used for this purpose. +It is ignored if it is used in a system that does not allow this control, +or if it appears in other than the main program unit. +@cindex OpenVMS +Note that the effect of this pragma is identical to the effect of the +DEC Ada 83 pragma of the same name when operating under OpenVMS systems. + +@node Pragma Title +@unnumberedsec Pragma Title +@findex Title +@noindent +Syntax: + +@smallexample @c ada +pragma Title (TITLING_OPTION [, TITLING OPTION]); + +TITLING_OPTION ::= + [Title =>] STRING_LITERAL, +| [Subtitle =>] STRING_LITERAL +@end smallexample + +@noindent +Syntax checked but otherwise ignored by GNAT@. This is a listing control +pragma used in DEC Ada 83 implementations to provide a title and/or +subtitle for the program listing. The program listing generated by GNAT +does not have titles or subtitles. + +Unlike other pragmas, the full flexibility of named notation is allowed +for this pragma, i.e.@: the parameters may be given in any order if named +notation is used, and named and positional notation can be mixed +following the normal rules for procedure calls in Ada. + +@node Pragma Unchecked_Union +@unnumberedsec Pragma Unchecked_Union +@cindex Unions in C +@findex Unchecked_Union +@noindent +Syntax: + +@smallexample @c ada +pragma Unchecked_Union (first_subtype_local_NAME); +@end smallexample + +@noindent +This pragma is used to declare that the specified type should be represented +in a manner +equivalent to a C union type, and is intended only for use in +interfacing with C code that uses union types. In Ada terms, the named +type must obey the following rules: + +@itemize @bullet +@item +It is a non-tagged non-limited record type. +@item +It has a single discrete discriminant with a default value. +@item +The component list consists of a single variant part. +@item +Each variant has a component list with a single component. +@item +No nested variants are allowed. +@item +No component has an explicit default value. +@item +No component has a non-static constraint. +@end itemize + +@noindent +In addition, given a type that meets the above requirements, the +following restrictions apply to its use throughout the program: + +@itemize @bullet +@item +The discriminant name can be mentioned only in an aggregate. +@item +No subtypes may be created of this type. +@item +The type may not be constrained by giving a discriminant value. +@item +The type cannot be passed as the actual for a generic formal with a +discriminant. +@end itemize + +@noindent +Equality and inequality operations on @code{unchecked_unions} are not +available, since there is no discriminant to compare and the compiler +does not even know how many bits to compare. It is implementation +dependent whether this is detected at compile time as an illegality or +whether it is undetected and considered to be an erroneous construct. In +GNAT, a direct comparison is illegal, but GNAT does not attempt to catch +the composite case (where two composites are compared that contain an +unchecked union component), so such comparisons are simply considered +erroneous. + +The layout of the resulting type corresponds exactly to a C union, where +each branch of the union corresponds to a single variant in the Ada +record. The semantics of the Ada program is not changed in any way by +the pragma, i.e.@: provided the above restrictions are followed, and no +erroneous incorrect references to fields or erroneous comparisons occur, +the semantics is exactly as described by the Ada reference manual. +Pragma @code{Suppress (Discriminant_Check)} applies implicitly to the +type and the default convention is C. + +@node Pragma Unimplemented_Unit +@unnumberedsec Pragma Unimplemented_Unit +@findex Unimplemented_Unit +@noindent +Syntax: + +@smallexample @c ada +pragma Unimplemented_Unit; +@end smallexample + +@noindent +If this pragma occurs in a unit that is processed by the compiler, GNAT +aborts with the message @samp{@var{xxx} not implemented}, where +@var{xxx} is the name of the current compilation unit. This pragma is +intended to allow the compiler to handle unimplemented library units in +a clean manner. + +The abort only happens if code is being generated. Thus you can use +specs of unimplemented packages in syntax or semantic checking mode. + +@node Pragma Universal_Data +@unnumberedsec Pragma Universal_Data +@findex Universal_Data +@noindent +Syntax: + +@smallexample @c ada +pragma Universal_Data [(library_unit_Name)]; +@end smallexample + +@noindent +This pragma is supported only for the AAMP target and is ignored for +other targets. The pragma specifies that all library-level objects +(Counter 0 data) associated with the library unit are to be accessed +and updated using universal addressing (24-bit addresses for AAMP5) +rather than the default of 16-bit Data Environment (DENV) addressing. +Use of this pragma will generally result in less efficient code for +references to global data associated with the library unit, but +allows such data to be located anywhere in memory. This pragma is +a library unit pragma, but can also be used as a configuration pragma +(including use in the @file{gnat.adc} file). The functionality +of this pragma is also available by applying the -univ switch on the +compilations of units where universal addressing of the data is desired. + +@node Pragma Unreferenced +@unnumberedsec Pragma Unreferenced +@findex Unreferenced +@cindex Warnings, unreferenced +@noindent +Syntax: + +@smallexample @c ada +pragma Unreferenced (local_NAME @{, local_NAME@}); +@end smallexample + +@noindent +This pragma signals that the entities whose names are listed are +deliberately not referenced in the current source unit. This +suppresses warnings about the +entities being unreferenced, and in addition a warning will be +generated if one of these entities is in fact referenced in the +same unit as the pragma (or in the corresponding body, or one +of its subunits). + +This is particularly useful for clearly signaling that a particular +parameter is not referenced in some particular subprogram implementation +and that this is deliberate. It can also be useful in the case of +objects declared only for their initialization or finalization side +effects. + +If @code{local_NAME} identifies more than one matching homonym in the +current scope, then the entity most recently declared is the one to which +the pragma applies. Note that in the case of accept formals, the pragma +Unreferenced may appear immediately after the keyword @code{do} which +allows the indication of whether or not accept formals are referenced +or not to be given individually for each accept statement. + +The left hand side of an assignment does not count as a reference for the +purpose of this pragma. Thus it is fine to assign to an entity for which +pragma Unreferenced is given. + +Note that if a warning is desired for all calls to a given subprogram, +regardless of whether they occur in the same unit as the subprogram +declaration, then this pragma should not be used (calls from another +unit would not be flagged); pragma Obsolescent can be used instead +for this purpose, see @xref{Pragma Obsolescent}. + +@node Pragma Unreserve_All_Interrupts +@unnumberedsec Pragma Unreserve_All_Interrupts +@findex Unreserve_All_Interrupts +@noindent +Syntax: + +@smallexample @c ada +pragma Unreserve_All_Interrupts; +@end smallexample + +@noindent +Normally certain interrupts are reserved to the implementation. Any attempt +to attach an interrupt causes Program_Error to be raised, as described in +RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in +many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is +reserved to the implementation, so that @kbd{Ctrl-C} can be used to +interrupt execution. + +If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in +a program, then all such interrupts are unreserved. This allows the +program to handle these interrupts, but disables their standard +functions. For example, if this pragma is used, then pressing +@kbd{Ctrl-C} will not automatically interrupt execution. However, +a program can then handle the @code{SIGINT} interrupt as it chooses. + +For a full list of the interrupts handled in a specific implementation, +see the source code for the specification of @code{Ada.Interrupts.Names} in +file @file{a-intnam.ads}. This is a target dependent file that contains the +list of interrupts recognized for a given target. The documentation in +this file also specifies what interrupts are affected by the use of +the @code{Unreserve_All_Interrupts} pragma. + +For a more general facility for controlling what interrupts can be +handled, see pragma @code{Interrupt_State}, which subsumes the functionality +of the @code{Unreserve_All_Interrupts} pragma. + +@node Pragma Unsuppress +@unnumberedsec Pragma Unsuppress +@findex Unsuppress +@noindent +Syntax: + +@smallexample @c ada +pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); +@end smallexample + +@noindent +This pragma undoes the effect of a previous pragma @code{Suppress}. If +there is no corresponding pragma @code{Suppress} in effect, it has no +effect. The range of the effect is the same as for pragma +@code{Suppress}. The meaning of the arguments is identical to that used +in pragma @code{Suppress}. + +One important application is to ensure that checks are on in cases where +code depends on the checks for its correct functioning, so that the code +will compile correctly even if the compiler switches are set to suppress +checks. + +@node Pragma Use_VADS_Size +@unnumberedsec Pragma Use_VADS_Size +@cindex @code{Size}, VADS compatibility +@findex Use_VADS_Size +@noindent +Syntax: + +@smallexample @c ada +pragma Use_VADS_Size; +@end smallexample + +@noindent +This is a configuration pragma. In a unit to which it applies, any use +of the 'Size attribute is automatically interpreted as a use of the +'VADS_Size attribute. Note that this may result in incorrect semantic +processing of valid Ada 95 programs. This is intended to aid in the +handling of legacy code which depends on the interpretation of Size +as implemented in the VADS compiler. See description of the VADS_Size +attribute for further details. + +@node Pragma Validity_Checks +@unnumberedsec Pragma Validity_Checks +@findex Validity_Checks +@noindent +Syntax: + +@smallexample @c ada +pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); +@end smallexample + +@noindent +This pragma is used in conjunction with compiler switches to control the +built-in validity checking provided by GNAT@. The compiler switches, if set +provide an initial setting for the switches, and this pragma may be used +to modify these settings, or the settings may be provided entirely by +the use of the pragma. This pragma can be used anywhere that a pragma +is legal, including use as a configuration pragma (including use in +the @file{gnat.adc} file). + +The form with a string literal specifies which validity options are to be +activated. The validity checks are first set to include only the default +reference manual settings, and then a string of letters in the string +specifies the exact set of options required. The form of this string +is exactly as described for the @code{-gnatVx} compiler switch (see the +GNAT users guide for details). For example the following two methods +can be used to enable validity checking for mode @code{in} and +@code{in out} subprogram parameters: + +@itemize @bullet +@item +@smallexample @c ada +pragma Validity_Checks ("im"); +@end smallexample + +@item +@smallexample +gcc -c -gnatVim @dots{} +@end smallexample +@end itemize + +@noindent +The form ALL_CHECKS activates all standard checks (its use is equivalent +to the use of the @code{gnatva} switch. + +The forms with @code{Off} and @code{On} +can be used to temporarily disable validity checks +as shown in the following example: + +@smallexample @c ada +@iftex +@leftskip=0cm +@end iftex +pragma Validity_Checks ("c"); -- validity checks for copies +pragma Validity_Checks (Off); -- turn off validity checks +A := B; -- B will not be validity checked +pragma Validity_Checks (On); -- turn validity checks back on +A := C; -- C will be validity checked +@end smallexample + +@node Pragma Volatile +@unnumberedsec Pragma Volatile +@findex Volatile +@noindent +Syntax: + +@smallexample @c ada +pragma Volatile (local_NAME); +@end smallexample + +@noindent +This pragma is defined by the Ada 95 Reference Manual, and the GNAT +implementation is fully conformant with this definition. The reason it +is mentioned in this section is that a pragma of the same name was supplied +in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation +of pragma Volatile is upwards compatible with the implementation in +Dec Ada 83. + +@node Pragma Warnings +@unnumberedsec Pragma Warnings +@findex Warnings +@noindent +Syntax: + +@smallexample @c ada +pragma Warnings (On | Off [, local_NAME]); +pragma Warnings (static_string_EXPRESSION); +@end smallexample + +@noindent +Normally warnings are enabled, with the output being controlled by +the command line switch. Warnings (@code{Off}) turns off generation of +warnings until a Warnings (@code{On}) is encountered or the end of the +current unit. If generation of warnings is turned off using this +pragma, then no warning messages are output, regardless of the +setting of the command line switches. + +The form with a single argument is a configuration pragma. + +If the @var{local_NAME} parameter is present, warnings are suppressed for +the specified entity. This suppression is effective from the point where +it occurs till the end of the extended scope of the variable (similar to +the scope of @code{Suppress}). + +The form with a static_string_EXPRESSION argument provides more precise +control over which warnings are active. The string is a list of letters +specifying which warnings are to be activated and which deactivated. The +code for these letters is the same as the string used in the command +line switch controlling warnings. The following is a brief summary. For +full details see the GNAT Users Guide: + +@smallexample +a turn on all optional warnings (except d,h,l) +A turn off all optional warnings +b turn on warnings for bad fixed value (not multiple of small) +B turn off warnings for bad fixed value (not multiple of small) +c turn on warnings for constant conditional +C turn off warnings for constant conditional +d turn on warnings for implicit dereference +D turn off warnings for implicit dereference +e treat all warnings as errors +f turn on warnings for unreferenced formal +F turn off warnings for unreferenced formal +g turn on warnings for unrecognized pragma +G turn off warnings for unrecognized pragma +h turn on warnings for hiding variable +H turn off warnings for hiding variable +i turn on warnings for implementation unit +I turn off warnings for implementation unit +j turn on warnings for obsolescent (annex J) feature +J turn off warnings for obsolescent (annex J) feature +k turn on warnings on constant variable +K turn off warnings on constant variable +l turn on warnings for missing elaboration pragma +L turn off warnings for missing elaboration pragma +m turn on warnings for variable assigned but not read +M turn off warnings for variable assigned but not read +n normal warning mode (cancels s/e) +o turn on warnings for address clause overlay +O turn off warnings for address clause overlay +p turn on warnings for ineffective pragma Inline +P turn off warnings for ineffective pragma Inline +r turn on warnings for redundant construct +R turn off warnings for redundant construct +s suppress all warnings +u turn on warnings for unused entity +U turn off warnings for unused entity +v turn on warnings for unassigned variable +V turn off warnings for unassigned variable +x turn on warnings for export/import +X turn off warnings for export/import +y turn on warnings for Ada 2005 incompatibility +Y turn off warnings for Ada 2005 incompatibility +z turn on size/align warnings for unchecked conversion +Z turn off size/align warnings for unchecked conversion +@end smallexample + +@noindent +The specified warnings will be in effect until the end of the program +or another pragma Warnings is encountered. The effect of the pragma is +cumulative. Initially the set of warnings is the standard default set +as possibly modified by compiler switches. Then each pragma Warning +modifies this set of warnings as specified. + +@node Pragma Weak_External +@unnumberedsec Pragma Weak_External +@findex Weak_External +@noindent +Syntax: + +@smallexample @c ada +pragma Weak_External ([Entity =>] local_NAME); +@end smallexample + +@noindent +@var{local_NAME} must refer to an object that is declared at the library +level. This pragma specifies that the given entity should be marked as a +weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} +in GNU C and causes @var{local_NAME} to be emitted as a weak symbol instead +of a regular symbol, that is to say a symbol that does not have to be +resolved by the linker if used in conjunction with a pragma Import. + +When a weak symbol is not resolved by the linker, its address is set to +zero. This is useful in writing interfaces to external modules that may +or may not be linked in the final executable, for example depending on +configuration settings. + +If a program references at run time an entity to which this pragma has been +applied, and the corresponding symbol was not resolved at link time, then +the execution of the program is erroneous. It is not erroneous to take the +Address of such an entity, for example to guard potential references, +as shown in the example below. + +Some file formats do not support weak symbols so not all target machines +support this pragma. + +@smallexample @c ada +-- Example of the use of pragma Weak_External + +package External_Module is + key : Integer; + pragma Import (C, key); + pragma Weak_External (key); + function Present return boolean; +end External_Module; + +with System; use System; +package body External_Module is + function Present return boolean is + begin + return key'Address /= System.Null_Address; + end Present; +end External_Module; +@end smallexample + +@node Implementation Defined Attributes +@chapter Implementation Defined Attributes +Ada 95 defines (throughout the Ada 95 reference manual, +summarized in annex K), +a set of attributes that provide useful additional functionality in all +areas of the language. These language defined attributes are implemented +in GNAT and work as described in the Ada 95 Reference Manual. + +In addition, Ada 95 allows implementations to define additional +attributes whose meaning is defined by the implementation. GNAT provides +a number of these implementation-dependent attributes which can be used +to extend and enhance the functionality of the compiler. This section of +the GNAT reference manual describes these additional attributes. + +Note that any program using these attributes may not be portable to +other compilers (although GNAT implements this set of attributes on all +platforms). Therefore if portability to other compilers is an important +consideration, you should minimize the use of these attributes. + +@menu +* Abort_Signal:: +* Address_Size:: +* Asm_Input:: +* Asm_Output:: +* AST_Entry:: +* Bit:: +* Bit_Position:: +* Code_Address:: +* Default_Bit_Order:: +* Elaborated:: +* Elab_Body:: +* Elab_Spec:: +* Emax:: +* Enum_Rep:: +* Epsilon:: +* Fixed_Value:: +* Has_Access_Values:: +* Has_Discriminants:: +* Img:: +* Integer_Value:: +* Large:: +* Machine_Size:: +* Mantissa:: +* Max_Interrupt_Priority:: +* Max_Priority:: +* Maximum_Alignment:: +* Mechanism_Code:: +* Null_Parameter:: +* Object_Size:: +* Passed_By_Reference:: +* Range_Length:: +* Safe_Emax:: +* Safe_Large:: +* Small:: +* Storage_Unit:: +* Target_Name:: +* Tick:: +* To_Address:: +* Type_Class:: +* UET_Address:: +* Unconstrained_Array:: +* Universal_Literal_String:: +* Unrestricted_Access:: +* VADS_Size:: +* Value_Size:: +* Wchar_T_Size:: +* Word_Size:: +@end menu + +@node Abort_Signal +@unnumberedsec Abort_Signal +@findex Abort_Signal +@noindent +@code{Standard'Abort_Signal} (@code{Standard} is the only allowed +prefix) provides the entity for the special exception used to signal +task abort or asynchronous transfer of control. Normally this attribute +should only be used in the tasking runtime (it is highly peculiar, and +completely outside the normal semantics of Ada, for a user program to +intercept the abort exception). + +@node Address_Size +@unnumberedsec Address_Size +@cindex Size of @code{Address} +@findex Address_Size +@noindent +@code{Standard'Address_Size} (@code{Standard} is the only allowed +prefix) is a static constant giving the number of bits in an +@code{Address}. It is the same value as System.Address'Size, +but has the advantage of being static, while a direct +reference to System.Address'Size is non-static because Address +is a private type. + +@node Asm_Input +@unnumberedsec Asm_Input +@findex Asm_Input +@noindent +The @code{Asm_Input} attribute denotes a function that takes two +parameters. The first is a string, the second is an expression of the +type designated by the prefix. The first (string) argument is required +to be a static expression, and is the constraint for the parameter, +(e.g.@: what kind of register is required). The second argument is the +value to be used as the input argument. The possible values for the +constant are the same as those used in the RTL, and are dependent on +the configuration file used to built the GCC back end. +@ref{Machine Code Insertions} + +@node Asm_Output +@unnumberedsec Asm_Output +@findex Asm_Output +@noindent +The @code{Asm_Output} attribute denotes a function that takes two +parameters. The first is a string, the second is the name of a variable +of the type designated by the attribute prefix. The first (string) +argument is required to be a static expression and designates the +constraint for the parameter (e.g.@: what kind of register is +required). The second argument is the variable to be updated with the +result. The possible values for constraint are the same as those used in +the RTL, and are dependent on the configuration file used to build the +GCC back end. If there are no output operands, then this argument may +either be omitted, or explicitly given as @code{No_Output_Operands}. +@ref{Machine Code Insertions} + +@node AST_Entry +@unnumberedsec AST_Entry +@cindex OpenVMS +@findex AST_Entry +@noindent +This attribute is implemented only in OpenVMS versions of GNAT@. Applied to +the name of an entry, it yields a value of the predefined type AST_Handler +(declared in the predefined package System, as extended by the use of +pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to +be called when an AST occurs. For further details, refer to the @cite{DEC Ada +Language Reference Manual}, section 9.12a. + +@node Bit +@unnumberedsec Bit +@findex Bit +@code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit +offset within the storage unit (byte) that contains the first bit of +storage allocated for the object. The value of this attribute is of the +type @code{Universal_Integer}, and is always a non-negative number not +exceeding the value of @code{System.Storage_Unit}. + +For an object that is a variable or a constant allocated in a register, +the value is zero. (The use of this attribute does not force the +allocation of a variable to memory). + +For an object that is a formal parameter, this attribute applies +to either the matching actual parameter or to a copy of the +matching actual parameter. + +For an access object the value is zero. Note that +@code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the +designated object. Similarly for a record component +@code{@var{X}.@var{C}'Bit} is subject to a discriminant check and +@code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit} +are subject to index checks. + +This attribute is designed to be compatible with the DEC Ada 83 definition +and implementation of the @code{Bit} attribute. + +@node Bit_Position +@unnumberedsec Bit_Position +@findex Bit_Position +@noindent +@code{@var{R.C}'Bit}, where @var{R} is a record object and C is one +of the fields of the record type, yields the bit +offset within the record contains the first bit of +storage allocated for the object. The value of this attribute is of the +type @code{Universal_Integer}. The value depends only on the field +@var{C} and is independent of the alignment of +the containing record @var{R}. + +@node Code_Address +@unnumberedsec Code_Address +@findex Code_Address +@cindex Subprogram address +@cindex Address of subprogram code +@noindent +The @code{'Address} +attribute may be applied to subprograms in Ada 95, but the +intended effect from the Ada 95 reference manual seems to be to provide +an address value which can be used to call the subprogram by means of +an address clause as in the following example: + +@smallexample @c ada +procedure K is @dots{} + +procedure L; +for L'Address use K'Address; +pragma Import (Ada, L); +@end smallexample + +@noindent +A call to @code{L} is then expected to result in a call to @code{K}@. +In Ada 83, where there were no access-to-subprogram values, this was +a common work around for getting the effect of an indirect call. +GNAT implements the above use of @code{Address} and the technique +illustrated by the example code works correctly. + +However, for some purposes, it is useful to have the address of the start +of the generated code for the subprogram. On some architectures, this is +not necessarily the same as the @code{Address} value described above. +For example, the @code{Address} value may reference a subprogram +descriptor rather than the subprogram itself. + +The @code{'Code_Address} attribute, which can only be applied to +subprogram entities, always returns the address of the start of the +generated code of the specified subprogram, which may or may not be +the same value as is returned by the corresponding @code{'Address} +attribute. + +@node Default_Bit_Order +@unnumberedsec Default_Bit_Order +@cindex Big endian +@cindex Little endian +@findex Default_Bit_Order +@noindent +@code{Standard'Default_Bit_Order} (@code{Standard} is the only +permissible prefix), provides the value @code{System.Default_Bit_Order} +as a @code{Pos} value (0 for @code{High_Order_First}, 1 for +@code{Low_Order_First}). This is used to construct the definition of +@code{Default_Bit_Order} in package @code{System}. + +@node Elaborated +@unnumberedsec Elaborated +@findex Elaborated +@noindent +The prefix of the @code{'Elaborated} attribute must be a unit name. The +value is a Boolean which indicates whether or not the given unit has been +elaborated. This attribute is primarily intended for internal use by the +generated code for dynamic elaboration checking, but it can also be used +in user programs. The value will always be True once elaboration of all +units has been completed. An exception is for units which need no +elaboration, the value is always False for such units. + +@node Elab_Body +@unnumberedsec Elab_Body +@findex Elab_Body +@noindent +This attribute can only be applied to a program unit name. It returns +the entity for the corresponding elaboration procedure for elaborating +the body of the referenced unit. This is used in the main generated +elaboration procedure by the binder and is not normally used in any +other context. However, there may be specialized situations in which it +is useful to be able to call this elaboration procedure from Ada code, +e.g.@: if it is necessary to do selective re-elaboration to fix some +error. + +@node Elab_Spec +@unnumberedsec Elab_Spec +@findex Elab_Spec +@noindent +This attribute can only be applied to a program unit name. It returns +the entity for the corresponding elaboration procedure for elaborating +the specification of the referenced unit. This is used in the main +generated elaboration procedure by the binder and is not normally used +in any other context. However, there may be specialized situations in +which it is useful to be able to call this elaboration procedure from +Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix +some error. + +@node Emax +@unnumberedsec Emax +@cindex Ada 83 attributes +@findex Emax +@noindent +The @code{Emax} attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +@node Enum_Rep +@unnumberedsec Enum_Rep +@cindex Representation of enums +@findex Enum_Rep +@noindent +For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a +function with the following spec: + +@smallexample @c ada +function @var{S}'Enum_Rep (Arg : @var{S}'Base) + return @i{Universal_Integer}; +@end smallexample + +@noindent +It is also allowable to apply @code{Enum_Rep} directly to an object of an +enumeration type or to a non-overloaded enumeration +literal. In this case @code{@var{S}'Enum_Rep} is equivalent to +@code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the +enumeration literal or object. + +The function returns the representation value for the given enumeration +value. This will be equal to value of the @code{Pos} attribute in the +absence of an enumeration representation clause. This is a static +attribute (i.e.@: the result is static if the argument is static). + +@code{@var{S}'Enum_Rep} can also be used with integer types and objects, +in which case it simply returns the integer value. The reason for this +is to allow it to be used for @code{(<>)} discrete formal arguments in +a generic unit that can be instantiated with either enumeration types +or integer types. Note that if @code{Enum_Rep} is used on a modular +type whose upper bound exceeds the upper bound of the largest signed +integer type, and the argument is a variable, so that the universal +integer calculation is done at run-time, then the call to @code{Enum_Rep} +may raise @code{Constraint_Error}. + +@node Epsilon +@unnumberedsec Epsilon +@cindex Ada 83 attributes +@findex Epsilon +@noindent +The @code{Epsilon} attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +@node Fixed_Value +@unnumberedsec Fixed_Value +@findex Fixed_Value +@noindent +For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a +function with the following specification: + +@smallexample @c ada +function @var{S}'Fixed_Value (Arg : @i{Universal_Integer}) + return @var{S}; +@end smallexample + +@noindent +The value returned is the fixed-point value @var{V} such that + +@smallexample @c ada +@var{V} = Arg * @var{S}'Small +@end smallexample + +@noindent +The effect is thus similar to first converting the argument to the +integer type used to represent @var{S}, and then doing an unchecked +conversion to the fixed-point type. The difference is +that there are full range checks, to ensure that the result is in range. +This attribute is primarily intended for use in implementation of the +input-output functions for fixed-point values. + +@node Has_Access_Values +@unnumberedsec Has_Access_Values +@cindex Access values, testing for +@findex Has_Access_Values +@noindent +The prefix of the @code{Has_Access_Values} attribute is a type. The result +is a Boolean value which is True if the is an access type, or is a composite +type with a component (at any nesting depth) that is an access type, and is +False otherwise. +The intended use of this attribute is in conjunction with generic +definitions. If the attribute is applied to a generic private type, it +indicates whether or not the corresponding actual type has access values. + +@node Has_Discriminants +@unnumberedsec Has_Discriminants +@cindex Discriminants, testing for +@findex Has_Discriminants +@noindent +The prefix of the @code{Has_Discriminants} attribute is a type. The result +is a Boolean value which is True if the type has discriminants, and False +otherwise. The intended use of this attribute is in conjunction with generic +definitions. If the attribute is applied to a generic private type, it +indicates whether or not the corresponding actual type has discriminants. + +@node Img +@unnumberedsec Img +@findex Img +@noindent +The @code{Img} attribute differs from @code{Image} in that it may be +applied to objects as well as types, in which case it gives the +@code{Image} for the subtype of the object. This is convenient for +debugging: + +@smallexample @c ada +Put_Line ("X = " & X'Img); +@end smallexample + +@noindent +has the same meaning as the more verbose: + +@smallexample @c ada +Put_Line ("X = " & @var{T}'Image (X)); +@end smallexample + +@noindent +where @var{T} is the (sub)type of the object @code{X}. + +@node Integer_Value +@unnumberedsec Integer_Value +@findex Integer_Value +@noindent +For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a +function with the following spec: + +@smallexample @c ada +function @var{S}'Integer_Value (Arg : @i{Universal_Fixed}) + return @var{S}; +@end smallexample + +@noindent +The value returned is the integer value @var{V}, such that + +@smallexample @c ada +Arg = @var{V} * @var{T}'Small +@end smallexample + +@noindent +where @var{T} is the type of @code{Arg}. +The effect is thus similar to first doing an unchecked conversion from +the fixed-point type to its corresponding implementation type, and then +converting the result to the target integer type. The difference is +that there are full range checks, to ensure that the result is in range. +This attribute is primarily intended for use in implementation of the +standard input-output functions for fixed-point values. + +@node Large +@unnumberedsec Large +@cindex Ada 83 attributes +@findex Large +@noindent +The @code{Large} attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +@node Machine_Size +@unnumberedsec Machine_Size +@findex Machine_Size +@noindent +This attribute is identical to the @code{Object_Size} attribute. It is +provided for compatibility with the DEC Ada 83 attribute of this name. + +@node Mantissa +@unnumberedsec Mantissa +@cindex Ada 83 attributes +@findex Mantissa +@noindent +The @code{Mantissa} attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +@node Max_Interrupt_Priority +@unnumberedsec Max_Interrupt_Priority +@cindex Interrupt priority, maximum +@findex Max_Interrupt_Priority +@noindent +@code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only +permissible prefix), provides the same value as +@code{System.Max_Interrupt_Priority}. + +@node Max_Priority +@unnumberedsec Max_Priority +@cindex Priority, maximum +@findex Max_Priority +@noindent +@code{Standard'Max_Priority} (@code{Standard} is the only permissible +prefix) provides the same value as @code{System.Max_Priority}. + +@node Maximum_Alignment +@unnumberedsec Maximum_Alignment +@cindex Alignment, maximum +@findex Maximum_Alignment +@noindent +@code{Standard'Maximum_Alignment} (@code{Standard} is the only +permissible prefix) provides the maximum useful alignment value for the +target. This is a static value that can be used to specify the alignment +for an object, guaranteeing that it is properly aligned in all +cases. + +@node Mechanism_Code +@unnumberedsec Mechanism_Code +@cindex Return values, passing mechanism +@cindex Parameters, passing mechanism +@findex Mechanism_Code +@noindent +@code{@var{function}'Mechanism_Code} yields an integer code for the +mechanism used for the result of function, and +@code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism +used for formal parameter number @var{n} (a static integer value with 1 +meaning the first parameter) of @var{subprogram}. The code returned is: + +@table @asis +@item 1 +by copy (value) +@item 2 +by reference +@item 3 +by descriptor (default descriptor class) +@item 4 +by descriptor (UBS: unaligned bit string) +@item 5 +by descriptor (UBSB: aligned bit string with arbitrary bounds) +@item 6 +by descriptor (UBA: unaligned bit array) +@item 7 +by descriptor (S: string, also scalar access type parameter) +@item 8 +by descriptor (SB: string with arbitrary bounds) +@item 9 +by descriptor (A: contiguous array) +@item 10 +by descriptor (NCA: non-contiguous array) +@end table + +@noindent +Values from 3 through 10 are only relevant to Digital OpenVMS implementations. +@cindex OpenVMS + +@node Null_Parameter +@unnumberedsec Null_Parameter +@cindex Zero address, passing +@findex Null_Parameter +@noindent +A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of +type or subtype @var{T} allocated at machine address zero. The attribute +is allowed only as the default expression of a formal parameter, or as +an actual expression of a subprogram call. In either case, the +subprogram must be imported. + +The identity of the object is represented by the address zero in the +argument list, independent of the passing mechanism (explicit or +default). + +This capability is needed to specify that a zero address should be +passed for a record or other composite object passed by reference. +There is no way of indicating this without the @code{Null_Parameter} +attribute. + +@node Object_Size +@unnumberedsec Object_Size +@cindex Size, used for objects +@findex Object_Size +@noindent +The size of an object is not necessarily the same as the size of the type +of an object. This is because by default object sizes are increased to be +a multiple of the alignment of the object. For example, +@code{Natural'Size} is +31, but by default objects of type @code{Natural} will have a size of 32 bits. +Similarly, a record containing an integer and a character: + +@smallexample @c ada +type Rec is record + I : Integer; + C : Character; +end record; +@end smallexample + +@noindent +will have a size of 40 (that is @code{Rec'Size} will be 40. The +alignment will be 4, because of the +integer field, and so the default size of record objects for this type +will be 64 (8 bytes). + +The @code{@var{type}'Object_Size} attribute +has been added to GNAT to allow the +default object size of a type to be easily determined. For example, +@code{Natural'Object_Size} is 32, and +@code{Rec'Object_Size} (for the record type in the above example) will be +64. Note also that, unlike the situation with the +@code{Size} attribute as defined in the Ada RM, the +@code{Object_Size} attribute can be specified individually +for different subtypes. For example: + +@smallexample @c ada +type R is new Integer; +subtype R1 is R range 1 .. 10; +subtype R2 is R range 1 .. 10; +for R2'Object_Size use 8; +@end smallexample + +@noindent +In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both +32 since the default object size for a subtype is the same as the object size +for the parent subtype. This means that objects of type @code{R} +or @code{R1} will +by default be 32 bits (four bytes). But objects of type +@code{R2} will be only +8 bits (one byte), since @code{R2'Object_Size} has been set to 8. + +@node Passed_By_Reference +@unnumberedsec Passed_By_Reference +@cindex Parameters, when passed by reference +@findex Passed_By_Reference +@noindent +@code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns +a value of type @code{Boolean} value that is @code{True} if the type is +normally passed by reference and @code{False} if the type is normally +passed by copy in calls. For scalar types, the result is always @code{False} +and is static. For non-scalar types, the result is non-static. + +@node Range_Length +@unnumberedsec Range_Length +@findex Range_Length +@noindent +@code{@var{type}'Range_Length} for any discrete type @var{type} yields +the number of values represented by the subtype (zero for a null +range). The result is static for static subtypes. @code{Range_Length} +applied to the index subtype of a one dimensional array always gives the +same result as @code{Range} applied to the array itself. + +@node Safe_Emax +@unnumberedsec Safe_Emax +@cindex Ada 83 attributes +@findex Safe_Emax +@noindent +The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +@node Safe_Large +@unnumberedsec Safe_Large +@cindex Ada 83 attributes +@findex Safe_Large +@noindent +The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +@node Small +@unnumberedsec Small +@cindex Ada 83 attributes +@findex Small +@noindent +The @code{Small} attribute is defined in Ada 95 only for fixed-point types. +GNAT also allows this attribute to be applied to floating-point types +for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute when applied to floating-point types. + +@node Storage_Unit +@unnumberedsec Storage_Unit +@findex Storage_Unit +@noindent +@code{Standard'Storage_Unit} (@code{Standard} is the only permissible +prefix) provides the same value as @code{System.Storage_Unit}. + +@node Target_Name +@unnumberedsec Target_Name +@findex Target_Name +@noindent +@code{Standard'Target_Name} (@code{Standard} is the only permissible +prefix) provides a static string value that identifies the target +for the current compilation. For GCC implementations, this is the +standard gcc target name without the terminating slash (for +example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). + +@node Tick +@unnumberedsec Tick +@findex Tick +@noindent +@code{Standard'Tick} (@code{Standard} is the only permissible prefix) +provides the same value as @code{System.Tick}, + +@node To_Address +@unnumberedsec To_Address +@findex To_Address +@noindent +The @code{System'To_Address} +(@code{System} is the only permissible prefix) +denotes a function identical to +@code{System.Storage_Elements.To_Address} except that +it is a static attribute. This means that if its argument is +a static expression, then the result of the attribute is a +static expression. The result is that such an expression can be +used in contexts (e.g.@: preelaborable packages) which require a +static expression and where the function call could not be used +(since the function call is always non-static, even if its +argument is static). + +@node Type_Class +@unnumberedsec Type_Class +@findex Type_Class +@noindent +@code{@var{type}'Type_Class} for any type or subtype @var{type} yields +the value of the type class for the full type of @var{type}. If +@var{type} is a generic formal type, the value is the value for the +corresponding actual subtype. The value of this attribute is of type +@code{System.Aux_DEC.Type_Class}, which has the following definition: + +@smallexample @c ada + type Type_Class is + (Type_Class_Enumeration, + Type_Class_Integer, + Type_Class_Fixed_Point, + Type_Class_Floating_Point, + Type_Class_Array, + Type_Class_Record, + Type_Class_Access, + Type_Class_Task, + Type_Class_Address); +@end smallexample + +@noindent +Protected types yield the value @code{Type_Class_Task}, which thus +applies to all concurrent types. This attribute is designed to +be compatible with the DEC Ada 83 attribute of the same name. + +@node UET_Address +@unnumberedsec UET_Address +@findex UET_Address +@noindent +The @code{UET_Address} attribute can only be used for a prefix which +denotes a library package. It yields the address of the unit exception +table when zero cost exception handling is used. This attribute is +intended only for use within the GNAT implementation. See the unit +@code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb} +for details on how this attribute is used in the implementation. + +@node Unconstrained_Array +@unnumberedsec Unconstrained_Array +@findex Unconstrained_Array +@noindent +The @code{Unconstrained_Array} attribute can be used with a prefix that +denotes any type or subtype. It is a static attribute that yields +@code{True} if the prefix designates an unconstrained array, +and @code{False} otherwise. In a generic instance, the result is +still static, and yields the result of applying this test to the +generic actual. + +@node Universal_Literal_String +@unnumberedsec Universal_Literal_String +@cindex Named numbers, representation of +@findex Universal_Literal_String +@noindent +The prefix of @code{Universal_Literal_String} must be a named +number. The static result is the string consisting of the characters of +the number as defined in the original source. This allows the user +program to access the actual text of named numbers without intermediate +conversions and without the need to enclose the strings in quotes (which +would preclude their use as numbers). This is used internally for the +construction of values of the floating-point attributes from the file +@file{ttypef.ads}, but may also be used by user programs. + +For example, the following program prints the first 50 digits of pi: + +@smallexample @c ada +with Text_IO; use Text_IO; +with Ada.Numerics; +procedure Pi is +begin + Put (Ada.Numerics.Pi'Universal_Literal_String); +end; +@end smallexample + +@node Unrestricted_Access +@unnumberedsec Unrestricted_Access +@cindex @code{Access}, unrestricted +@findex Unrestricted_Access +@noindent +The @code{Unrestricted_Access} attribute is similar to @code{Access} +except that all accessibility and aliased view checks are omitted. This +is a user-beware attribute. It is similar to +@code{Address}, for which it is a desirable replacement where the value +desired is an access type. In other words, its effect is identical to +first applying the @code{Address} attribute and then doing an unchecked +conversion to a desired access type. In GNAT, but not necessarily in +other implementations, the use of static chains for inner level +subprograms means that @code{Unrestricted_Access} applied to a +subprogram yields a value that can be called as long as the subprogram +is in scope (normal Ada 95 accessibility rules restrict this usage). + +It is possible to use @code{Unrestricted_Access} for any type, but care +must be exercised if it is used to create pointers to unconstrained +objects. In this case, the resulting pointer has the same scope as the +context of the attribute, and may not be returned to some enclosing +scope. For instance, a function cannot use @code{Unrestricted_Access} +to create a unconstrained pointer and then return that value to the +caller. + +@node VADS_Size +@unnumberedsec VADS_Size +@cindex @code{Size}, VADS compatibility +@findex VADS_Size +@noindent +The @code{'VADS_Size} attribute is intended to make it easier to port +legacy code which relies on the semantics of @code{'Size} as implemented +by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the +same semantic interpretation. In particular, @code{'VADS_Size} applied +to a predefined or other primitive type with no Size clause yields the +Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on +typical machines). In addition @code{'VADS_Size} applied to an object +gives the result that would be obtained by applying the attribute to +the corresponding type. + +@node Value_Size +@unnumberedsec Value_Size +@cindex @code{Size}, setting for not-first subtype +@findex Value_Size +@code{@var{type}'Value_Size} is the number of bits required to represent +a value of the given subtype. It is the same as @code{@var{type}'Size}, +but, unlike @code{Size}, may be set for non-first subtypes. + +@node Wchar_T_Size +@unnumberedsec Wchar_T_Size +@findex Wchar_T_Size +@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible +prefix) provides the size in bits of the C @code{wchar_t} type +primarily for constructing the definition of this type in +package @code{Interfaces.C}. + +@node Word_Size +@unnumberedsec Word_Size +@findex Word_Size +@code{Standard'Word_Size} (@code{Standard} is the only permissible +prefix) provides the value @code{System.Word_Size}. + +@c ------------------------ +@node Implementation Advice +@chapter Implementation Advice +@noindent +The main text of the Ada 95 Reference Manual describes the required +behavior of all Ada 95 compilers, and the GNAT compiler conforms to +these requirements. + +In addition, there are sections throughout the Ada 95 +reference manual headed +by the phrase ``implementation advice''. These sections are not normative, +i.e.@: they do not specify requirements that all compilers must +follow. Rather they provide advice on generally desirable behavior. You +may wonder why they are not requirements. The most typical answer is +that they describe behavior that seems generally desirable, but cannot +be provided on all systems, or which may be undesirable on some systems. + +As far as practical, GNAT follows the implementation advice sections in +the Ada 95 Reference Manual. This chapter contains a table giving the +reference manual section number, paragraph number and several keywords +for each advice. Each entry consists of the text of the advice followed +by the GNAT interpretation of this advice. Most often, this simply says +``followed'', which means that GNAT follows the advice. However, in a +number of cases, GNAT deliberately deviates from this advice, in which +case the text describes what GNAT does and why. + +@cindex Error detection +@unnumberedsec 1.1.3(20): Error Detection +@sp 1 +@cartouche +If an implementation detects the use of an unsupported Specialized Needs +Annex feature at run time, it should raise @code{Program_Error} if +feasible. +@end cartouche +Not relevant. All specialized needs annex features are either supported, +or diagnosed at compile time. + +@cindex Child Units +@unnumberedsec 1.1.3(31): Child Units +@sp 1 +@cartouche +If an implementation wishes to provide implementation-defined +extensions to the functionality of a language-defined library unit, it +should normally do so by adding children to the library unit. +@end cartouche +Followed. + +@cindex Bounded errors +@unnumberedsec 1.1.5(12): Bounded Errors +@sp 1 +@cartouche +If an implementation detects a bounded error or erroneous +execution, it should raise @code{Program_Error}. +@end cartouche +Followed in all cases in which the implementation detects a bounded +error or erroneous execution. Not all such situations are detected at +runtime. + +@cindex Pragmas +@unnumberedsec 2.8(16): Pragmas +@sp 1 +@cartouche +Normally, implementation-defined pragmas should have no semantic effect +for error-free programs; that is, if the implementation-defined pragmas +are removed from a working program, the program should still be legal, +and should still have the same semantics. +@end cartouche +The following implementation defined pragmas are exceptions to this +rule: + +@table @code +@item Abort_Defer +Affects semantics +@item Ada_83 +Affects legality +@item Assert +Affects semantics +@item CPP_Class +Affects semantics +@item CPP_Constructor +Affects semantics +@item CPP_Virtual +Affects semantics +@item CPP_Vtable +Affects semantics +@item Debug +Affects semantics +@item Interface_Name +Affects semantics +@item Machine_Attribute +Affects semantics +@item Unimplemented_Unit +Affects legality +@item Unchecked_Union +Affects semantics +@end table + +@noindent +In each of the above cases, it is essential to the purpose of the pragma +that this advice not be followed. For details see the separate section +on implementation defined pragmas. + +@unnumberedsec 2.8(17-19): Pragmas +@sp 1 +@cartouche +Normally, an implementation should not define pragmas that can +make an illegal program legal, except as follows: +@end cartouche +@sp 1 +@cartouche +A pragma used to complete a declaration, such as a pragma @code{Import}; +@end cartouche +@sp 1 +@cartouche +A pragma used to configure the environment by adding, removing, or +replacing @code{library_items}. +@end cartouche +See response to paragraph 16 of this same section. + +@cindex Character Sets +@cindex Alternative Character Sets +@unnumberedsec 3.5.2(5): Alternative Character Sets +@sp 1 +@cartouche +If an implementation supports a mode with alternative interpretations +for @code{Character} and @code{Wide_Character}, the set of graphic +characters of @code{Character} should nevertheless remain a proper +subset of the set of graphic characters of @code{Wide_Character}. Any +character set ``localizations'' should be reflected in the results of +the subprograms defined in the language-defined package +@code{Characters.Handling} (see A.3) available in such a mode. In a mode with +an alternative interpretation of @code{Character}, the implementation should +also support a corresponding change in what is a legal +@code{identifier_letter}. +@end cartouche +Not all wide character modes follow this advice, in particular the JIS +and IEC modes reflect standard usage in Japan, and in these encoding, +the upper half of the Latin-1 set is not part of the wide-character +subset, since the most significant bit is used for wide character +encoding. However, this only applies to the external forms. Internally +there is no such restriction. + +@cindex Integer types +@unnumberedsec 3.5.4(28): Integer Types + +@sp 1 +@cartouche +An implementation should support @code{Long_Integer} in addition to +@code{Integer} if the target machine supports 32-bit (or longer) +arithmetic. No other named integer subtypes are recommended for package +@code{Standard}. Instead, appropriate named integer subtypes should be +provided in the library package @code{Interfaces} (see B.2). +@end cartouche +@code{Long_Integer} is supported. Other standard integer types are supported +so this advice is not fully followed. These types +are supported for convenient interface to C, and so that all hardware +types of the machine are easily available. +@unnumberedsec 3.5.4(29): Integer Types + +@sp 1 +@cartouche +An implementation for a two's complement machine should support +modular types with a binary modulus up to @code{System.Max_Int*2+2}. An +implementation should support a non-binary modules up to @code{Integer'Last}. +@end cartouche +Followed. + +@cindex Enumeration values +@unnumberedsec 3.5.5(8): Enumeration Values +@sp 1 +@cartouche +For the evaluation of a call on @code{@var{S}'Pos} for an enumeration +subtype, if the value of the operand does not correspond to the internal +code for any enumeration literal of its type (perhaps due to an +un-initialized variable), then the implementation should raise +@code{Program_Error}. This is particularly important for enumeration +types with noncontiguous internal codes specified by an +enumeration_representation_clause. +@end cartouche +Followed. + +@cindex Float types +@unnumberedsec 3.5.7(17): Float Types +@sp 1 +@cartouche +An implementation should support @code{Long_Float} in addition to +@code{Float} if the target machine supports 11 or more digits of +precision. No other named floating point subtypes are recommended for +package @code{Standard}. Instead, appropriate named floating point subtypes +should be provided in the library package @code{Interfaces} (see B.2). +@end cartouche +@code{Short_Float} and @code{Long_Long_Float} are also provided. The +former provides improved compatibility with other implementations +supporting this type. The latter corresponds to the highest precision +floating-point type supported by the hardware. On most machines, this +will be the same as @code{Long_Float}, but on some machines, it will +correspond to the IEEE extended form. The notable case is all ia32 +(x86) implementations, where @code{Long_Long_Float} corresponds to +the 80-bit extended precision format supported in hardware on this +processor. Note that the 128-bit format on SPARC is not supported, +since this is a software rather than a hardware format. + +@cindex Multidimensional arrays +@cindex Arrays, multidimensional +@unnumberedsec 3.6.2(11): Multidimensional Arrays +@sp 1 +@cartouche +An implementation should normally represent multidimensional arrays in +row-major order, consistent with the notation used for multidimensional +array aggregates (see 4.3.3). However, if a pragma @code{Convention} +(@code{Fortran}, @dots{}) applies to a multidimensional array type, then +column-major order should be used instead (see B.5, ``Interfacing with +Fortran''). +@end cartouche +Followed. + +@findex Duration'Small +@unnumberedsec 9.6(30-31): Duration'Small +@sp 1 +@cartouche +Whenever possible in an implementation, the value of @code{Duration'Small} +should be no greater than 100 microseconds. +@end cartouche +Followed. (@code{Duration'Small} = 10**(@minus{}9)). + +@sp 1 +@cartouche +The time base for @code{delay_relative_statements} should be monotonic; +it need not be the same time base as used for @code{Calendar.Clock}. +@end cartouche +Followed. + +@unnumberedsec 10.2.1(12): Consistent Representation +@sp 1 +@cartouche +In an implementation, a type declared in a pre-elaborated package should +have the same representation in every elaboration of a given version of +the package, whether the elaborations occur in distinct executions of +the same program, or in executions of distinct programs or partitions +that include the given version. +@end cartouche +Followed, except in the case of tagged types. Tagged types involve +implicit pointers to a local copy of a dispatch table, and these pointers +have representations which thus depend on a particular elaboration of the +package. It is not easy to see how it would be possible to follow this +advice without severely impacting efficiency of execution. + +@cindex Exception information +@unnumberedsec 11.4.1(19): Exception Information +@sp 1 +@cartouche +@code{Exception_Message} by default and @code{Exception_Information} +should produce information useful for +debugging. @code{Exception_Message} should be short, about one +line. @code{Exception_Information} can be long. @code{Exception_Message} +should not include the +@code{Exception_Name}. @code{Exception_Information} should include both +the @code{Exception_Name} and the @code{Exception_Message}. +@end cartouche +Followed. For each exception that doesn't have a specified +@code{Exception_Message}, the compiler generates one containing the location +of the raise statement. This location has the form ``file:line'', where +file is the short file name (without path information) and line is the line +number in the file. Note that in the case of the Zero Cost Exception +mechanism, these messages become redundant with the Exception_Information that +contains a full backtrace of the calling sequence, so they are disabled. +To disable explicitly the generation of the source location message, use the +Pragma @code{Discard_Names}. + +@cindex Suppression of checks +@cindex Checks, suppression of +@unnumberedsec 11.5(28): Suppression of Checks +@sp 1 +@cartouche +The implementation should minimize the code executed for checks that +have been suppressed. +@end cartouche +Followed. + +@cindex Representation clauses +@unnumberedsec 13.1 (21-24): Representation Clauses +@sp 1 +@cartouche +The recommended level of support for all representation items is +qualified as follows: +@end cartouche +@sp 1 +@cartouche +An implementation need not support representation items containing +non-static expressions, except that an implementation should support a +representation item for a given entity if each non-static expression in +the representation item is a name that statically denotes a constant +declared before the entity. +@end cartouche +Followed. In fact, GNAT goes beyond the recommended level of support +by allowing nonstatic expressions in some representation clauses even +without the need to declare constants initialized with the values of +such expressions. +For example: + +@smallexample @c ada + X : Integer; + Y : Float; + for Y'Address use X'Address;>> +@end smallexample + + +@sp 1 +@cartouche +An implementation need not support a specification for the @code{Size} +for a given composite subtype, nor the size or storage place for an +object (including a component) of a given composite subtype, unless the +constraints on the subtype and its composite subcomponents (if any) are +all static constraints. +@end cartouche +Followed. Size Clauses are not permitted on non-static components, as +described above. + +@sp 1 +@cartouche +An aliased component, or a component whose type is by-reference, should +always be allocated at an addressable location. +@end cartouche +Followed. + +@cindex Packed types +@unnumberedsec 13.2(6-8): Packed Types +@sp 1 +@cartouche +If a type is packed, then the implementation should try to minimize +storage allocated to objects of the type, possibly at the expense of +speed of accessing components, subject to reasonable complexity in +addressing calculations. +@end cartouche +@sp 1 +@cartouche +The recommended level of support pragma @code{Pack} is: + +For a packed record type, the components should be packed as tightly as +possible subject to the Sizes of the component subtypes, and subject to +any @code{record_representation_clause} that applies to the type; the +implementation may, but need not, reorder components or cross aligned +word boundaries to improve the packing. A component whose @code{Size} is +greater than the word size may be allocated an integral number of words. +@end cartouche +Followed. Tight packing of arrays is supported for all component sizes +up to 64-bits. If the array component size is 1 (that is to say, if +the component is a boolean type or an enumeration type with two values) +then values of the type are implicitly initialized to zero. This +happens both for objects of the packed type, and for objects that have a +subcomponent of the packed type. + +@sp 1 +@cartouche +An implementation should support Address clauses for imported +subprograms. +@end cartouche +Followed. +@cindex @code{Address} clauses +@unnumberedsec 13.3(14-19): Address Clauses + +@sp 1 +@cartouche +For an array @var{X}, @code{@var{X}'Address} should point at the first +component of the array, and not at the array bounds. +@end cartouche +Followed. + +@sp 1 +@cartouche +The recommended level of support for the @code{Address} attribute is: + +@code{@var{X}'Address} should produce a useful result if @var{X} is an +object that is aliased or of a by-reference type, or is an entity whose +@code{Address} has been specified. +@end cartouche +Followed. A valid address will be produced even if none of those +conditions have been met. If necessary, the object is forced into +memory to ensure the address is valid. + +@sp 1 +@cartouche +An implementation should support @code{Address} clauses for imported +subprograms. +@end cartouche +Followed. + +@sp 1 +@cartouche +Objects (including subcomponents) that are aliased or of a by-reference +type should be allocated on storage element boundaries. +@end cartouche +Followed. + +@sp 1 +@cartouche +If the @code{Address} of an object is specified, or it is imported or exported, +then the implementation should not perform optimizations based on +assumptions of no aliases. +@end cartouche +Followed. + +@cindex @code{Alignment} clauses +@unnumberedsec 13.3(29-35): Alignment Clauses +@sp 1 +@cartouche +The recommended level of support for the @code{Alignment} attribute for +subtypes is: + +An implementation should support specified Alignments that are factors +and multiples of the number of storage elements per word, subject to the +following: +@end cartouche +Followed. + +@sp 1 +@cartouche +An implementation need not support specified @code{Alignment}s for +combinations of @code{Size}s and @code{Alignment}s that cannot be easily +loaded and stored by available machine instructions. +@end cartouche +Followed. + +@sp 1 +@cartouche +An implementation need not support specified @code{Alignment}s that are +greater than the maximum @code{Alignment} the implementation ever returns by +default. +@end cartouche +Followed. + +@sp 1 +@cartouche +The recommended level of support for the @code{Alignment} attribute for +objects is: + +Same as above, for subtypes, but in addition: +@end cartouche +Followed. + +@sp 1 +@cartouche +For stand-alone library-level objects of statically constrained +subtypes, the implementation should support all @code{Alignment}s +supported by the target linker. For example, page alignment is likely to +be supported for such objects, but not for subtypes. +@end cartouche +Followed. + +@cindex @code{Size} clauses +@unnumberedsec 13.3(42-43): Size Clauses +@sp 1 +@cartouche +The recommended level of support for the @code{Size} attribute of +objects is: + +A @code{Size} clause should be supported for an object if the specified +@code{Size} is at least as large as its subtype's @code{Size}, and +corresponds to a size in storage elements that is a multiple of the +object's @code{Alignment} (if the @code{Alignment} is nonzero). +@end cartouche +Followed. + +@unnumberedsec 13.3(50-56): Size Clauses +@sp 1 +@cartouche +If the @code{Size} of a subtype is specified, and allows for efficient +independent addressability (see 9.10) on the target architecture, then +the @code{Size} of the following objects of the subtype should equal the +@code{Size} of the subtype: + +Aliased objects (including components). +@end cartouche +Followed. + +@sp 1 +@cartouche +@code{Size} clause on a composite subtype should not affect the +internal layout of components. +@end cartouche +Followed. + +@sp 1 +@cartouche +The recommended level of support for the @code{Size} attribute of subtypes is: +@end cartouche +@sp 1 +@cartouche +The @code{Size} (if not specified) of a static discrete or fixed point +subtype should be the number of bits needed to represent each value +belonging to the subtype using an unbiased representation, leaving space +for a sign bit only if the subtype contains negative values. If such a +subtype is a first subtype, then an implementation should support a +specified @code{Size} for it that reflects this representation. +@end cartouche +Followed. + +@sp 1 +@cartouche +For a subtype implemented with levels of indirection, the @code{Size} +should include the size of the pointers, but not the size of what they +point at. +@end cartouche +Followed. + +@cindex @code{Component_Size} clauses +@unnumberedsec 13.3(71-73): Component Size Clauses +@sp 1 +@cartouche +The recommended level of support for the @code{Component_Size} +attribute is: +@end cartouche +@sp 1 +@cartouche +An implementation need not support specified @code{Component_Sizes} that are +less than the @code{Size} of the component subtype. +@end cartouche +Followed. + +@sp 1 +@cartouche +An implementation should support specified @code{Component_Size}s that +are factors and multiples of the word size. For such +@code{Component_Size}s, the array should contain no gaps between +components. For other @code{Component_Size}s (if supported), the array +should contain no gaps between components when packing is also +specified; the implementation should forbid this combination in cases +where it cannot support a no-gaps representation. +@end cartouche +Followed. + +@cindex Enumeration representation clauses +@cindex Representation clauses, enumeration +@unnumberedsec 13.4(9-10): Enumeration Representation Clauses +@sp 1 +@cartouche +The recommended level of support for enumeration representation clauses +is: + +An implementation need not support enumeration representation clauses +for boolean types, but should at minimum support the internal codes in +the range @code{System.Min_Int.System.Max_Int}. +@end cartouche +Followed. + +@cindex Record representation clauses +@cindex Representation clauses, records +@unnumberedsec 13.5.1(17-22): Record Representation Clauses +@sp 1 +@cartouche +The recommended level of support for +@*@code{record_representation_clauses} is: + +An implementation should support storage places that can be extracted +with a load, mask, shift sequence of machine code, and set with a load, +shift, mask, store sequence, given the available machine instructions +and run-time model. +@end cartouche +Followed. + +@sp 1 +@cartouche +A storage place should be supported if its size is equal to the +@code{Size} of the component subtype, and it starts and ends on a +boundary that obeys the @code{Alignment} of the component subtype. +@end cartouche +Followed. + +@sp 1 +@cartouche +If the default bit ordering applies to the declaration of a given type, +then for a component whose subtype's @code{Size} is less than the word +size, any storage place that does not cross an aligned word boundary +should be supported. +@end cartouche +Followed. + +@sp 1 +@cartouche +An implementation may reserve a storage place for the tag field of a +tagged type, and disallow other components from overlapping that place. +@end cartouche +Followed. The storage place for the tag field is the beginning of the tagged +record, and its size is Address'Size. GNAT will reject an explicit component +clause for the tag field. + +@sp 1 +@cartouche +An implementation need not support a @code{component_clause} for a +component of an extension part if the storage place is not after the +storage places of all components of the parent type, whether or not +those storage places had been specified. +@end cartouche +Followed. The above advice on record representation clauses is followed, +and all mentioned features are implemented. + +@cindex Storage place attributes +@unnumberedsec 13.5.2(5): Storage Place Attributes +@sp 1 +@cartouche +If a component is represented using some form of pointer (such as an +offset) to the actual data of the component, and this data is contiguous +with the rest of the object, then the storage place attributes should +reflect the place of the actual data, not the pointer. If a component is +allocated discontinuously from the rest of the object, then a warning +should be generated upon reference to one of its storage place +attributes. +@end cartouche +Followed. There are no such components in GNAT@. + +@cindex Bit ordering +@unnumberedsec 13.5.3(7-8): Bit Ordering +@sp 1 +@cartouche +The recommended level of support for the non-default bit ordering is: +@end cartouche +@sp 1 +@cartouche +If @code{Word_Size} = @code{Storage_Unit}, then the implementation +should support the non-default bit ordering in addition to the default +bit ordering. +@end cartouche +Followed. Word size does not equal storage size in this implementation. +Thus non-default bit ordering is not supported. + +@cindex @code{Address}, as private type +@unnumberedsec 13.7(37): Address as Private +@sp 1 +@cartouche +@code{Address} should be of a private type. +@end cartouche +Followed. + +@cindex Operations, on @code{Address} +@cindex @code{Address}, operations of +@unnumberedsec 13.7.1(16): Address Operations +@sp 1 +@cartouche +Operations in @code{System} and its children should reflect the target +environment semantics as closely as is reasonable. For example, on most +machines, it makes sense for address arithmetic to ``wrap around''. +Operations that do not make sense should raise @code{Program_Error}. +@end cartouche +Followed. Address arithmetic is modular arithmetic that wraps around. No +operation raises @code{Program_Error}, since all operations make sense. + +@cindex Unchecked conversion +@unnumberedsec 13.9(14-17): Unchecked Conversion +@sp 1 +@cartouche +The @code{Size} of an array object should not include its bounds; hence, +the bounds should not be part of the converted data. +@end cartouche +Followed. + +@sp 1 +@cartouche +The implementation should not generate unnecessary run-time checks to +ensure that the representation of @var{S} is a representation of the +target type. It should take advantage of the permission to return by +reference when possible. Restrictions on unchecked conversions should be +avoided unless required by the target environment. +@end cartouche +Followed. There are no restrictions on unchecked conversion. A warning is +generated if the source and target types do not have the same size since +the semantics in this case may be target dependent. + +@sp 1 +@cartouche +The recommended level of support for unchecked conversions is: +@end cartouche +@sp 1 +@cartouche +Unchecked conversions should be supported and should be reversible in +the cases where this clause defines the result. To enable meaningful use +of unchecked conversion, a contiguous representation should be used for +elementary subtypes, for statically constrained array subtypes whose +component subtype is one of the subtypes described in this paragraph, +and for record subtypes without discriminants whose component subtypes +are described in this paragraph. +@end cartouche +Followed. + +@cindex Heap usage, implicit +@unnumberedsec 13.11(23-25): Implicit Heap Usage +@sp 1 +@cartouche +An implementation should document any cases in which it dynamically +allocates heap storage for a purpose other than the evaluation of an +allocator. +@end cartouche +Followed, the only other points at which heap storage is dynamically +allocated are as follows: + +@itemize @bullet +@item +At initial elaboration time, to allocate dynamically sized global +objects. + +@item +To allocate space for a task when a task is created. + +@item +To extend the secondary stack dynamically when needed. The secondary +stack is used for returning variable length results. +@end itemize + +@sp 1 +@cartouche +A default (implementation-provided) storage pool for an +access-to-constant type should not have overhead to support deallocation of +individual objects. +@end cartouche +Followed. + +@sp 1 +@cartouche +A storage pool for an anonymous access type should be created at the +point of an allocator for the type, and be reclaimed when the designated +object becomes inaccessible. +@end cartouche +Followed. + +@cindex Unchecked deallocation +@unnumberedsec 13.11.2(17): Unchecked De-allocation +@sp 1 +@cartouche +For a standard storage pool, @code{Free} should actually reclaim the +storage. +@end cartouche +Followed. + +@cindex Stream oriented attributes +@unnumberedsec 13.13.2(17): Stream Oriented Attributes +@sp 1 +@cartouche +If a stream element is the same size as a storage element, then the +normal in-memory representation should be used by @code{Read} and +@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write} +should use the smallest number of stream elements needed to represent +all values in the base range of the scalar type. +@end cartouche + +Followed. By default, GNAT uses the interpretation suggested by AI-195, +which specifies using the size of the first subtype. +However, such an implementation is based on direct binary +representations and is therefore target- and endianness-dependent. +To address this issue, GNAT also supplies an alternate implementation +of the stream attributes @code{Read} and @code{Write}, +which uses the target-independent XDR standard representation +for scalar types. +@cindex XDR representation +@cindex @code{Read} attribute +@cindex @code{Write} attribute +@cindex Stream oriented attributes +The XDR implementation is provided as an alternative body of the +@code{System.Stream_Attributes} package, in the file +@file{s-strxdr.adb} in the GNAT library. +There is no @file{s-strxdr.ads} file. +In order to install the XDR implementation, do the following: +@enumerate +@item Replace the default implementation of the +@code{System.Stream_Attributes} package with the XDR implementation. +For example on a Unix platform issue the commands: +@smallexample +$ mv s-stratt.adb s-strold.adb +$ mv s-strxdr.adb s-stratt.adb +@end smallexample + +@item +Rebuild the GNAT run-time library as documented in the +@cite{GNAT User's Guide} +@end enumerate + +@unnumberedsec A.1(52): Names of Predefined Numeric Types +@sp 1 +@cartouche +If an implementation provides additional named predefined integer types, +then the names should end with @samp{Integer} as in +@samp{Long_Integer}. If an implementation provides additional named +predefined floating point types, then the names should end with +@samp{Float} as in @samp{Long_Float}. +@end cartouche +Followed. + +@findex Ada.Characters.Handling +@unnumberedsec A.3.2(49): @code{Ada.Characters.Handling} +@sp 1 +@cartouche +If an implementation provides a localized definition of @code{Character} +or @code{Wide_Character}, then the effects of the subprograms in +@code{Characters.Handling} should reflect the localizations. See also +3.5.2. +@end cartouche +Followed. GNAT provides no such localized definitions. + +@cindex Bounded-length strings +@unnumberedsec A.4.4(106): Bounded-Length String Handling +@sp 1 +@cartouche +Bounded string objects should not be implemented by implicit pointers +and dynamic allocation. +@end cartouche +Followed. No implicit pointers or dynamic allocation are used. + +@cindex Random number generation +@unnumberedsec A.5.2(46-47): Random Number Generation +@sp 1 +@cartouche +Any storage associated with an object of type @code{Generator} should be +reclaimed on exit from the scope of the object. +@end cartouche +Followed. + +@sp 1 +@cartouche +If the generator period is sufficiently long in relation to the number +of distinct initiator values, then each possible value of +@code{Initiator} passed to @code{Reset} should initiate a sequence of +random numbers that does not, in a practical sense, overlap the sequence +initiated by any other value. If this is not possible, then the mapping +between initiator values and generator states should be a rapidly +varying function of the initiator value. +@end cartouche +Followed. The generator period is sufficiently long for the first +condition here to hold true. + +@findex Get_Immediate +@unnumberedsec A.10.7(23): @code{Get_Immediate} +@sp 1 +@cartouche +The @code{Get_Immediate} procedures should be implemented with +unbuffered input. For a device such as a keyboard, input should be +@dfn{available} if a key has already been typed, whereas for a disk +file, input should always be available except at end of file. For a file +associated with a keyboard-like device, any line-editing features of the +underlying operating system should be disabled during the execution of +@code{Get_Immediate}. +@end cartouche +Followed on all targets except VxWorks. For VxWorks, there is no way to +provide this functionality that does not result in the input buffer being +flushed before the @code{Get_Immediate} call. A special unit +@code{Interfaces.Vxworks.IO} is provided that contains routines to enable +this functionality. + +@findex Export +@unnumberedsec B.1(39-41): Pragma @code{Export} +@sp 1 +@cartouche +If an implementation supports pragma @code{Export} to a given language, +then it should also allow the main subprogram to be written in that +language. It should support some mechanism for invoking the elaboration +of the Ada library units included in the system, and for invoking the +finalization of the environment task. On typical systems, the +recommended mechanism is to provide two subprograms whose link names are +@code{adainit} and @code{adafinal}. @code{adainit} should contain the +elaboration code for library units. @code{adafinal} should contain the +finalization code. These subprograms should have no effect the second +and subsequent time they are called. +@end cartouche +Followed. + +@sp 1 +@cartouche +Automatic elaboration of pre-elaborated packages should be +provided when pragma @code{Export} is supported. +@end cartouche +Followed when the main program is in Ada. If the main program is in a +foreign language, then +@code{adainit} must be called to elaborate pre-elaborated +packages. + +@sp 1 +@cartouche +For each supported convention @var{L} other than @code{Intrinsic}, an +implementation should support @code{Import} and @code{Export} pragmas +for objects of @var{L}-compatible types and for subprograms, and pragma +@code{Convention} for @var{L}-eligible types and for subprograms, +presuming the other language has corresponding features. Pragma +@code{Convention} need not be supported for scalar types. +@end cartouche +Followed. + +@cindex Package @code{Interfaces} +@findex Interfaces +@unnumberedsec B.2(12-13): Package @code{Interfaces} +@sp 1 +@cartouche +For each implementation-defined convention identifier, there should be a +child package of package Interfaces with the corresponding name. This +package should contain any declarations that would be useful for +interfacing to the language (implementation) represented by the +convention. Any declarations useful for interfacing to any language on +the given hardware architecture should be provided directly in +@code{Interfaces}. +@end cartouche +Followed. An additional package not defined +in the Ada 95 Reference Manual is @code{Interfaces.CPP}, used +for interfacing to C++. + +@sp 1 +@cartouche +An implementation supporting an interface to C, COBOL, or Fortran should +provide the corresponding package or packages described in the following +clauses. +@end cartouche +Followed. GNAT provides all the packages described in this section. + +@cindex C, interfacing with +@unnumberedsec B.3(63-71): Interfacing with C +@sp 1 +@cartouche +An implementation should support the following interface correspondences +between Ada and C@. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada procedure corresponds to a void-returning C function. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada function corresponds to a non-void C function. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada @code{in} scalar parameter is passed as a scalar argument to a C +function. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada @code{in} parameter of an access-to-object type with designated +type @var{T} is passed as a @code{@var{t}*} argument to a C function, +where @var{t} is the C type corresponding to the Ada type @var{T}. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out} +parameter of an elementary type @var{T}, is passed as a @code{@var{t}*} +argument to a C function, where @var{t} is the C type corresponding to +the Ada type @var{T}. In the case of an elementary @code{out} or +@code{in out} parameter, a pointer to a temporary copy is used to +preserve by-copy semantics. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada parameter of a record type @var{T}, of any mode, is passed as a +@code{@var{t}*} argument to a C function, where @var{t} is the C +structure corresponding to the Ada type @var{T}. +@end cartouche +Followed. This convention may be overridden by the use of the C_Pass_By_Copy +pragma, or Convention, or by explicitly specifying the mechanism for a given +call using an extended import or export pragma. + +@sp 1 +@cartouche +An Ada parameter of an array type with component type @var{T}, of any +mode, is passed as a @code{@var{t}*} argument to a C function, where +@var{t} is the C type corresponding to the Ada type @var{T}. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada parameter of an access-to-subprogram type is passed as a pointer +to a C function whose prototype corresponds to the designated +subprogram's specification. +@end cartouche +Followed. + +@cindex COBOL, interfacing with +@unnumberedsec B.4(95-98): Interfacing with COBOL +@sp 1 +@cartouche +An Ada implementation should support the following interface +correspondences between Ada and COBOL@. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of +the COBOL type corresponding to @var{T}. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of +the corresponding COBOL type. +@end cartouche +Followed. + +@sp 1 +@cartouche +Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the +COBOL type corresponding to the Ada parameter type; for scalars, a local +copy is used if necessary to ensure by-copy semantics. +@end cartouche +Followed. + +@cindex Fortran, interfacing with +@unnumberedsec B.5(22-26): Interfacing with Fortran +@sp 1 +@cartouche +An Ada implementation should support the following interface +correspondences between Ada and Fortran: +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada procedure corresponds to a Fortran subroutine. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada function corresponds to a Fortran function. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada parameter of an elementary, array, or record type @var{T} is +passed as a @var{T} argument to a Fortran procedure, where @var{T} is +the Fortran type corresponding to the Ada type @var{T}, and where the +INTENT attribute of the corresponding dummy argument matches the Ada +formal parameter mode; the Fortran implementation's parameter passing +conventions are used. For elementary types, a local copy is used if +necessary to ensure by-copy semantics. +@end cartouche +Followed. + +@sp 1 +@cartouche +An Ada parameter of an access-to-subprogram type is passed as a +reference to a Fortran procedure whose interface corresponds to the +designated subprogram's specification. +@end cartouche +Followed. + +@cindex Machine operations +@unnumberedsec C.1(3-5): Access to Machine Operations +@sp 1 +@cartouche +The machine code or intrinsic support should allow access to all +operations normally available to assembly language programmers for the +target environment, including privileged instructions, if any. +@end cartouche +Followed. + +@sp 1 +@cartouche +The interfacing pragmas (see Annex B) should support interface to +assembler; the default assembler should be associated with the +convention identifier @code{Assembler}. +@end cartouche +Followed. + +@sp 1 +@cartouche +If an entity is exported to assembly language, then the implementation +should allocate it at an addressable location, and should ensure that it +is retained by the linking process, even if not otherwise referenced +from the Ada code. The implementation should assume that any call to a +machine code or assembler subprogram is allowed to read or update every +object that is specified as exported. +@end cartouche +Followed. + +@unnumberedsec C.1(10-16): Access to Machine Operations +@sp 1 +@cartouche +The implementation should ensure that little or no overhead is +associated with calling intrinsic and machine-code subprograms. +@end cartouche +Followed for both intrinsics and machine-code subprograms. + +@sp 1 +@cartouche +It is recommended that intrinsic subprograms be provided for convenient +access to any machine operations that provide special capabilities or +efficiency and that are not otherwise available through the language +constructs. +@end cartouche +Followed. A full set of machine operation intrinsic subprograms is provided. + +@sp 1 +@cartouche +Atomic read-modify-write operations---e.g.@:, test and set, compare and +swap, decrement and test, enqueue/dequeue. +@end cartouche +Followed on any target supporting such operations. + +@sp 1 +@cartouche +Standard numeric functions---e.g.@:, sin, log. +@end cartouche +Followed on any target supporting such operations. + +@sp 1 +@cartouche +String manipulation operations---e.g.@:, translate and test. +@end cartouche +Followed on any target supporting such operations. + +@sp 1 +@cartouche +Vector operations---e.g.@:, compare vector against thresholds. +@end cartouche +Followed on any target supporting such operations. + +@sp 1 +@cartouche +Direct operations on I/O ports. +@end cartouche +Followed on any target supporting such operations. + +@cindex Interrupt support +@unnumberedsec C.3(28): Interrupt Support +@sp 1 +@cartouche +If the @code{Ceiling_Locking} policy is not in effect, the +implementation should provide means for the application to specify which +interrupts are to be blocked during protected actions, if the underlying +system allows for a finer-grain control of interrupt blocking. +@end cartouche +Followed. The underlying system does not allow for finer-grain control +of interrupt blocking. + +@cindex Protected procedure handlers +@unnumberedsec C.3.1(20-21): Protected Procedure Handlers +@sp 1 +@cartouche +Whenever possible, the implementation should allow interrupt handlers to +be called directly by the hardware. +@end cartouche +@c SGI info: +@ignore +This is never possible under IRIX, so this is followed by default. +@end ignore +Followed on any target where the underlying operating system permits +such direct calls. + +@sp 1 +@cartouche +Whenever practical, violations of any +implementation-defined restrictions should be detected before run time. +@end cartouche +Followed. Compile time warnings are given when possible. + +@cindex Package @code{Interrupts} +@findex Interrupts +@unnumberedsec C.3.2(25): Package @code{Interrupts} + +@sp 1 +@cartouche +If implementation-defined forms of interrupt handler procedures are +supported, such as protected procedures with parameters, then for each +such form of a handler, a type analogous to @code{Parameterless_Handler} +should be specified in a child package of @code{Interrupts}, with the +same operations as in the predefined package Interrupts. +@end cartouche +Followed. + +@cindex Pre-elaboration requirements +@unnumberedsec C.4(14): Pre-elaboration Requirements +@sp 1 +@cartouche +It is recommended that pre-elaborated packages be implemented in such a +way that there should be little or no code executed at run time for the +elaboration of entities not already covered by the Implementation +Requirements. +@end cartouche +Followed. Executable code is generated in some cases, e.g.@: loops +to initialize large arrays. + +@unnumberedsec C.5(8): Pragma @code{Discard_Names} + +@sp 1 +@cartouche +If the pragma applies to an entity, then the implementation should +reduce the amount of storage used for storing names associated with that +entity. +@end cartouche +Followed. + +@cindex Package @code{Task_Attributes} +@findex Task_Attributes +@unnumberedsec C.7.2(30): The Package Task_Attributes +@sp 1 +@cartouche +Some implementations are targeted to domains in which memory use at run +time must be completely deterministic. For such implementations, it is +recommended that the storage for task attributes will be pre-allocated +statically and not from the heap. This can be accomplished by either +placing restrictions on the number and the size of the task's +attributes, or by using the pre-allocated storage for the first @var{N} +attribute objects, and the heap for the others. In the latter case, +@var{N} should be documented. +@end cartouche +Not followed. This implementation is not targeted to such a domain. + +@cindex Locking Policies +@unnumberedsec D.3(17): Locking Policies + +@sp 1 +@cartouche +The implementation should use names that end with @samp{_Locking} for +locking policies defined by the implementation. +@end cartouche +Followed. A single implementation-defined locking policy is defined, +whose name (@code{Inheritance_Locking}) follows this suggestion. + +@cindex Entry queuing policies +@unnumberedsec D.4(16): Entry Queuing Policies +@sp 1 +@cartouche +Names that end with @samp{_Queuing} should be used +for all implementation-defined queuing policies. +@end cartouche +Followed. No such implementation-defined queuing policies exist. + +@cindex Preemptive abort +@unnumberedsec D.6(9-10): Preemptive Abort +@sp 1 +@cartouche +Even though the @code{abort_statement} is included in the list of +potentially blocking operations (see 9.5.1), it is recommended that this +statement be implemented in a way that never requires the task executing +the @code{abort_statement} to block. +@end cartouche +Followed. + +@sp 1 +@cartouche +On a multi-processor, the delay associated with aborting a task on +another processor should be bounded; the implementation should use +periodic polling, if necessary, to achieve this. +@end cartouche +Followed. + +@cindex Tasking restrictions +@unnumberedsec D.7(21): Tasking Restrictions +@sp 1 +@cartouche +When feasible, the implementation should take advantage of the specified +restrictions to produce a more efficient implementation. +@end cartouche +GNAT currently takes advantage of these restrictions by providing an optimized +run time when the Ravenscar profile and the GNAT restricted run time set +of restrictions are specified. See pragma @code{Profile (Ravenscar)} and +pragma @code{Profile (Restricted)} for more details. + +@cindex Time, monotonic +@unnumberedsec D.8(47-49): Monotonic Time +@sp 1 +@cartouche +When appropriate, implementations should provide configuration +mechanisms to change the value of @code{Tick}. +@end cartouche +Such configuration mechanisms are not appropriate to this implementation +and are thus not supported. + +@sp 1 +@cartouche +It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} +be implemented as transformations of the same time base. +@end cartouche +Followed. + +@sp 1 +@cartouche +It is recommended that the @dfn{best} time base which exists in +the underlying system be available to the application through +@code{Clock}. @dfn{Best} may mean highest accuracy or largest range. +@end cartouche +Followed. + +@cindex Partition communication subsystem +@cindex PCS +@unnumberedsec E.5(28-29): Partition Communication Subsystem +@sp 1 +@cartouche +Whenever possible, the PCS on the called partition should allow for +multiple tasks to call the RPC-receiver with different messages and +should allow them to block until the corresponding subprogram body +returns. +@end cartouche +Followed by GLADE, a separately supplied PCS that can be used with +GNAT. + +@sp 1 +@cartouche +The @code{Write} operation on a stream of type @code{Params_Stream_Type} +should raise @code{Storage_Error} if it runs out of space trying to +write the @code{Item} into the stream. +@end cartouche +Followed by GLADE, a separately supplied PCS that can be used with +GNAT@. + +@cindex COBOL support +@unnumberedsec F(7): COBOL Support +@sp 1 +@cartouche +If COBOL (respectively, C) is widely supported in the target +environment, implementations supporting the Information Systems Annex +should provide the child package @code{Interfaces.COBOL} (respectively, +@code{Interfaces.C}) specified in Annex B and should support a +@code{convention_identifier} of COBOL (respectively, C) in the interfacing +pragmas (see Annex B), thus allowing Ada programs to interface with +programs written in that language. +@end cartouche +Followed. + +@cindex Decimal radix support +@unnumberedsec F.1(2): Decimal Radix Support +@sp 1 +@cartouche +Packed decimal should be used as the internal representation for objects +of subtype @var{S} when @var{S}'Machine_Radix = 10. +@end cartouche +Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary +representations. + +@cindex Numerics +@unnumberedsec G: Numerics +@sp 2 +@cartouche +If Fortran (respectively, C) is widely supported in the target +environment, implementations supporting the Numerics Annex +should provide the child package @code{Interfaces.Fortran} (respectively, +@code{Interfaces.C}) specified in Annex B and should support a +@code{convention_identifier} of Fortran (respectively, C) in the interfacing +pragmas (see Annex B), thus allowing Ada programs to interface with +programs written in that language. +@end cartouche +Followed. + +@cindex Complex types +@unnumberedsec G.1.1(56-58): Complex Types +@sp 2 +@cartouche +Because the usual mathematical meaning of multiplication of a complex +operand and a real operand is that of the scaling of both components of +the former by the latter, an implementation should not perform this +operation by first promoting the real operand to complex type and then +performing a full complex multiplication. In systems that, in the +future, support an Ada binding to IEC 559:1989, the latter technique +will not generate the required result when one of the components of the +complex operand is infinite. (Explicit multiplication of the infinite +component by the zero component obtained during promotion yields a NaN +that propagates into the final result.) Analogous advice applies in the +case of multiplication of a complex operand and a pure-imaginary +operand, and in the case of division of a complex operand by a real or +pure-imaginary operand. +@end cartouche +Not followed. + +@sp 1 +@cartouche +Similarly, because the usual mathematical meaning of addition of a +complex operand and a real operand is that the imaginary operand remains +unchanged, an implementation should not perform this operation by first +promoting the real operand to complex type and then performing a full +complex addition. In implementations in which the @code{Signed_Zeros} +attribute of the component type is @code{True} (and which therefore +conform to IEC 559:1989 in regard to the handling of the sign of zero in +predefined arithmetic operations), the latter technique will not +generate the required result when the imaginary component of the complex +operand is a negatively signed zero. (Explicit addition of the negative +zero to the zero obtained during promotion yields a positive zero.) +Analogous advice applies in the case of addition of a complex operand +and a pure-imaginary operand, and in the case of subtraction of a +complex operand and a real or pure-imaginary operand. +@end cartouche +Not followed. + +@sp 1 +@cartouche +Implementations in which @code{Real'Signed_Zeros} is @code{True} should +attempt to provide a rational treatment of the signs of zero results and +result components. As one example, the result of the @code{Argument} +function should have the sign of the imaginary component of the +parameter @code{X} when the point represented by that parameter lies on +the positive real axis; as another, the sign of the imaginary component +of the @code{Compose_From_Polar} function should be the same as +(respectively, the opposite of) that of the @code{Argument} parameter when that +parameter has a value of zero and the @code{Modulus} parameter has a +nonnegative (respectively, negative) value. +@end cartouche +Followed. + +@cindex Complex elementary functions +@unnumberedsec G.1.2(49): Complex Elementary Functions +@sp 1 +@cartouche +Implementations in which @code{Complex_Types.Real'Signed_Zeros} is +@code{True} should attempt to provide a rational treatment of the signs +of zero results and result components. For example, many of the complex +elementary functions have components that are odd functions of one of +the parameter components; in these cases, the result component should +have the sign of the parameter component at the origin. Other complex +elementary functions have zero components whose sign is opposite that of +a parameter component at the origin, or is always positive or always +negative. +@end cartouche +Followed. + +@cindex Accuracy requirements +@unnumberedsec G.2.4(19): Accuracy Requirements +@sp 1 +@cartouche +The versions of the forward trigonometric functions without a +@code{Cycle} parameter should not be implemented by calling the +corresponding version with a @code{Cycle} parameter of +@code{2.0*Numerics.Pi}, since this will not provide the required +accuracy in some portions of the domain. For the same reason, the +version of @code{Log} without a @code{Base} parameter should not be +implemented by calling the corresponding version with a @code{Base} +parameter of @code{Numerics.e}. +@end cartouche +Followed. + +@cindex Complex arithmetic accuracy +@cindex Accuracy, complex arithmetic +@unnumberedsec G.2.6(15): Complex Arithmetic Accuracy + +@sp 1 +@cartouche +The version of the @code{Compose_From_Polar} function without a +@code{Cycle} parameter should not be implemented by calling the +corresponding version with a @code{Cycle} parameter of +@code{2.0*Numerics.Pi}, since this will not provide the required +accuracy in some portions of the domain. +@end cartouche +Followed. + +@c ----------------------------------------- +@node Implementation Defined Characteristics +@chapter Implementation Defined Characteristics + +@noindent +In addition to the implementation dependent pragmas and attributes, and +the implementation advice, there are a number of other features of Ada +95 that are potentially implementation dependent. These are mentioned +throughout the Ada 95 Reference Manual, and are summarized in annex M@. + +A requirement for conforming Ada compilers is that they provide +documentation describing how the implementation deals with each of these +issues. In this chapter, you will find each point in annex M listed +followed by a description in italic font of how GNAT +@c SGI info: +@ignore +in the ProDev Ada +implementation on IRIX 5.3 operating system or greater +@end ignore +handles the implementation dependence. + +You can use this chapter as a guide to minimizing implementation +dependent features in your programs if portability to other compilers +and other operating systems is an important consideration. The numbers +in each section below correspond to the paragraph number in the Ada 95 +Reference Manual. + +@sp 1 +@cartouche +@noindent +@strong{2}. Whether or not each recommendation given in Implementation +Advice is followed. See 1.1.2(37). +@end cartouche +@noindent +@xref{Implementation Advice}. + +@sp 1 +@cartouche +@noindent +@strong{3}. Capacity limitations of the implementation. See 1.1.3(3). +@end cartouche +@noindent +The complexity of programs that can be processed is limited only by the +total amount of available virtual memory, and disk space for the +generated object files. + +@sp 1 +@cartouche +@noindent +@strong{4}. Variations from the standard that are impractical to avoid +given the implementation's execution environment. See 1.1.3(6). +@end cartouche +@noindent +There are no variations from the standard. + +@sp 1 +@cartouche +@noindent +@strong{5}. Which @code{code_statement}s cause external +interactions. See 1.1.3(10). +@end cartouche +@noindent +Any @code{code_statement} can potentially cause external interactions. + +@sp 1 +@cartouche +@noindent +@strong{6}. The coded representation for the text of an Ada +program. See 2.1(4). +@end cartouche +@noindent +See separate section on source representation. + +@sp 1 +@cartouche +@noindent +@strong{7}. The control functions allowed in comments. See 2.1(14). +@end cartouche +@noindent +See separate section on source representation. + +@sp 1 +@cartouche +@noindent +@strong{8}. The representation for an end of line. See 2.2(2). +@end cartouche +@noindent +See separate section on source representation. + +@sp 1 +@cartouche +@noindent +@strong{9}. Maximum supported line length and lexical element +length. See 2.2(15). +@end cartouche +@noindent +The maximum line length is 255 characters an the maximum length of a +lexical element is also 255 characters. + +@sp 1 +@cartouche +@noindent +@strong{10}. Implementation defined pragmas. See 2.8(14). +@end cartouche +@noindent + +@xref{Implementation Defined Pragmas}. + +@sp 1 +@cartouche +@noindent +@strong{11}. Effect of pragma @code{Optimize}. See 2.8(27). +@end cartouche +@noindent +Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} +parameter, checks that the optimization flag is set, and aborts if it is +not. + +@sp 1 +@cartouche +@noindent +@strong{12}. The sequence of characters of the value returned by +@code{@var{S}'Image} when some of the graphic characters of +@code{@var{S}'Wide_Image} are not defined in @code{Character}. See +3.5(37). +@end cartouche +@noindent +The sequence of characters is as defined by the wide character encoding +method used for the source. See section on source representation for +further details. + +@sp 1 +@cartouche +@noindent +@strong{13}. The predefined integer types declared in +@code{Standard}. See 3.5.4(25). +@end cartouche +@noindent +@table @code +@item Short_Short_Integer +8 bit signed +@item Short_Integer +(Short) 16 bit signed +@item Integer +32 bit signed +@item Long_Integer +64 bit signed (Alpha OpenVMS only) +32 bit signed (all other targets) +@item Long_Long_Integer +64 bit signed +@end table + +@sp 1 +@cartouche +@noindent +@strong{14}. Any nonstandard integer types and the operators defined +for them. See 3.5.4(26). +@end cartouche +@noindent +There are no nonstandard integer types. + +@sp 1 +@cartouche +@noindent +@strong{15}. Any nonstandard real types and the operators defined for +them. See 3.5.6(8). +@end cartouche +@noindent +There are no nonstandard real types. + +@sp 1 +@cartouche +@noindent +@strong{16}. What combinations of requested decimal precision and range +are supported for floating point types. See 3.5.7(7). +@end cartouche +@noindent +The precision and range is as defined by the IEEE standard. + +@sp 1 +@cartouche +@noindent +@strong{17}. The predefined floating point types declared in +@code{Standard}. See 3.5.7(16). +@end cartouche +@noindent +@table @code +@item Short_Float +32 bit IEEE short +@item Float +(Short) 32 bit IEEE short +@item Long_Float +64 bit IEEE long +@item Long_Long_Float +64 bit IEEE long (80 bit IEEE long on x86 processors) +@end table + +@sp 1 +@cartouche +@noindent +@strong{18}. The small of an ordinary fixed point type. See 3.5.9(8). +@end cartouche +@noindent +@code{Fine_Delta} is 2**(@minus{}63) + +@sp 1 +@cartouche +@noindent +@strong{19}. What combinations of small, range, and digits are +supported for fixed point types. See 3.5.9(10). +@end cartouche +@noindent +Any combinations are permitted that do not result in a small less than +@code{Fine_Delta} and do not result in a mantissa larger than 63 bits. +If the mantissa is larger than 53 bits on machines where Long_Long_Float +is 64 bits (true of all architectures except ia32), then the output from +Text_IO is accurate to only 53 bits, rather than the full mantissa. This +is because floating-point conversions are used to convert fixed point. + +@sp 1 +@cartouche +@noindent +@strong{20}. The result of @code{Tags.Expanded_Name} for types declared +within an unnamed @code{block_statement}. See 3.9(10). +@end cartouche +@noindent +Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a +decimal integer are allocated. + +@sp 1 +@cartouche +@noindent +@strong{21}. Implementation-defined attributes. See 4.1.4(12). +@end cartouche +@noindent +@xref{Implementation Defined Attributes}. + +@sp 1 +@cartouche +@noindent +@strong{22}. Any implementation-defined time types. See 9.6(6). +@end cartouche +@noindent +There are no implementation-defined time types. + +@sp 1 +@cartouche +@noindent +@strong{23}. The time base associated with relative delays. +@end cartouche +@noindent +See 9.6(20). The time base used is that provided by the C library +function @code{gettimeofday}. + +@sp 1 +@cartouche +@noindent +@strong{24}. The time base of the type @code{Calendar.Time}. See +9.6(23). +@end cartouche +@noindent +The time base used is that provided by the C library function +@code{gettimeofday}. + +@sp 1 +@cartouche +@noindent +@strong{25}. The time zone used for package @code{Calendar} +operations. See 9.6(24). +@end cartouche +@noindent +The time zone used by package @code{Calendar} is the current system time zone +setting for local time, as accessed by the C library function +@code{localtime}. + +@sp 1 +@cartouche +@noindent +@strong{26}. Any limit on @code{delay_until_statements} of +@code{select_statements}. See 9.6(29). +@end cartouche +@noindent +There are no such limits. + +@sp 1 +@cartouche +@noindent +@strong{27}. Whether or not two non overlapping parts of a composite +object are independently addressable, in the case where packing, record +layout, or @code{Component_Size} is specified for the object. See +9.10(1). +@end cartouche +@noindent +Separate components are independently addressable if they do not share +overlapping storage units. + +@sp 1 +@cartouche +@noindent +@strong{28}. The representation for a compilation. See 10.1(2). +@end cartouche +@noindent +A compilation is represented by a sequence of files presented to the +compiler in a single invocation of the @code{gcc} command. + +@sp 1 +@cartouche +@noindent +@strong{29}. Any restrictions on compilations that contain multiple +compilation_units. See 10.1(4). +@end cartouche +@noindent +No single file can contain more than one compilation unit, but any +sequence of files can be presented to the compiler as a single +compilation. + +@sp 1 +@cartouche +@noindent +@strong{30}. The mechanisms for creating an environment and for adding +and replacing compilation units. See 10.1.4(3). +@end cartouche +@noindent +See separate section on compilation model. + +@sp 1 +@cartouche +@noindent +@strong{31}. The manner of explicitly assigning library units to a +partition. See 10.2(2). +@end cartouche +@noindent +If a unit contains an Ada main program, then the Ada units for the partition +are determined by recursive application of the rules in the Ada Reference +Manual section 10.2(2-6). In other words, the Ada units will be those that +are needed by the main program, and then this definition of need is applied +recursively to those units, and the partition contains the transitive +closure determined by this relationship. In short, all the necessary units +are included, with no need to explicitly specify the list. If additional +units are required, e.g.@: by foreign language units, then all units must be +mentioned in the context clause of one of the needed Ada units. + +If the partition contains no main program, or if the main program is in +a language other than Ada, then GNAT +provides the binder options @code{-z} and @code{-n} respectively, and in +this case a list of units can be explicitly supplied to the binder for +inclusion in the partition (all units needed by these units will also +be included automatically). For full details on the use of these +options, refer to the @cite{GNAT User's Guide} sections on Binding +and Linking. + +@sp 1 +@cartouche +@noindent +@strong{32}. The implementation-defined means, if any, of specifying +which compilation units are needed by a given compilation unit. See +10.2(2). +@end cartouche +@noindent +The units needed by a given compilation unit are as defined in +the Ada Reference Manual section 10.2(2-6). There are no +implementation-defined pragmas or other implementation-defined +means for specifying needed units. + +@sp 1 +@cartouche +@noindent +@strong{33}. The manner of designating the main subprogram of a +partition. See 10.2(7). +@end cartouche +@noindent +The main program is designated by providing the name of the +corresponding @file{ALI} file as the input parameter to the binder. + +@sp 1 +@cartouche +@noindent +@strong{34}. The order of elaboration of @code{library_items}. See +10.2(18). +@end cartouche +@noindent +The first constraint on ordering is that it meets the requirements of +chapter 10 of the Ada 95 Reference Manual. This still leaves some +implementation dependent choices, which are resolved by first +elaborating bodies as early as possible (i.e.@: in preference to specs +where there is a choice), and second by evaluating the immediate with +clauses of a unit to determine the probably best choice, and +third by elaborating in alphabetical order of unit names +where a choice still remains. + +@sp 1 +@cartouche +@noindent +@strong{35}. Parameter passing and function return for the main +subprogram. See 10.2(21). +@end cartouche +@noindent +The main program has no parameters. It may be a procedure, or a function +returning an integer type. In the latter case, the returned integer +value is the return code of the program (overriding any value that +may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). + +@sp 1 +@cartouche +@noindent +@strong{36}. The mechanisms for building and running partitions. See +10.2(24). +@end cartouche +@noindent +GNAT itself supports programs with only a single partition. The GNATDIST +tool provided with the GLADE package (which also includes an implementation +of the PCS) provides a completely flexible method for building and running +programs consisting of multiple partitions. See the separate GLADE manual +for details. + +@sp 1 +@cartouche +@noindent +@strong{37}. The details of program execution, including program +termination. See 10.2(25). +@end cartouche +@noindent +See separate section on compilation model. + +@sp 1 +@cartouche +@noindent +@strong{38}. The semantics of any non-active partitions supported by the +implementation. See 10.2(28). +@end cartouche +@noindent +Passive partitions are supported on targets where shared memory is +provided by the operating system. See the GLADE reference manual for +further details. + +@sp 1 +@cartouche +@noindent +@strong{39}. The information returned by @code{Exception_Message}. See +11.4.1(10). +@end cartouche +@noindent +Exception message returns the null string unless a specific message has +been passed by the program. + +@sp 1 +@cartouche +@noindent +@strong{40}. The result of @code{Exceptions.Exception_Name} for types +declared within an unnamed @code{block_statement}. See 11.4.1(12). +@end cartouche +@noindent +Blocks have implementation defined names of the form @code{B@var{nnn}} +where @var{nnn} is an integer. + +@sp 1 +@cartouche +@noindent +@strong{41}. The information returned by +@code{Exception_Information}. See 11.4.1(13). +@end cartouche +@noindent +@code{Exception_Information} returns a string in the following format: + +@smallexample +@emph{Exception_Name:} nnnnn +@emph{Message:} mmmmm +@emph{PID:} ppp +@emph{Call stack traceback locations:} +0xhhhh 0xhhhh 0xhhhh ... 0xhhh +@end smallexample + +@noindent +where + +@itemize @bullet +@item +@code{nnnn} is the fully qualified name of the exception in all upper +case letters. This line is always present. + +@item +@code{mmmm} is the message (this line present only if message is non-null) + +@item +@code{ppp} is the Process Id value as a decimal integer (this line is +present only if the Process Id is nonzero). Currently we are +not making use of this field. + +@item +The Call stack traceback locations line and the following values +are present only if at least one traceback location was recorded. +The values are given in C style format, with lower case letters +for a-f, and only as many digits present as are necessary. +@end itemize + +@noindent +The line terminator sequence at the end of each line, including +the last line is a single @code{LF} character (@code{16#0A#}). + +@sp 1 +@cartouche +@noindent +@strong{42}. Implementation-defined check names. See 11.5(27). +@end cartouche +@noindent +No implementation-defined check names are supported. + +@sp 1 +@cartouche +@noindent +@strong{43}. The interpretation of each aspect of representation. See +13.1(20). +@end cartouche +@noindent +See separate section on data representations. + +@sp 1 +@cartouche +@noindent +@strong{44}. Any restrictions placed upon representation items. See +13.1(20). +@end cartouche +@noindent +See separate section on data representations. + +@sp 1 +@cartouche +@noindent +@strong{45}. The meaning of @code{Size} for indefinite subtypes. See +13.3(48). +@end cartouche +@noindent +Size for an indefinite subtype is the maximum possible size, except that +for the case of a subprogram parameter, the size of the parameter object +is the actual size. + +@sp 1 +@cartouche +@noindent +@strong{46}. The default external representation for a type tag. See +13.3(75). +@end cartouche +@noindent +The default external representation for a type tag is the fully expanded +name of the type in upper case letters. + +@sp 1 +@cartouche +@noindent +@strong{47}. What determines whether a compilation unit is the same in +two different partitions. See 13.3(76). +@end cartouche +@noindent +A compilation unit is the same in two different partitions if and only +if it derives from the same source file. + +@sp 1 +@cartouche +@noindent +@strong{48}. Implementation-defined components. See 13.5.1(15). +@end cartouche +@noindent +The only implementation defined component is the tag for a tagged type, +which contains a pointer to the dispatching table. + +@sp 1 +@cartouche +@noindent +@strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit +ordering. See 13.5.3(5). +@end cartouche +@noindent +@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this +implementation, so no non-default bit ordering is supported. The default +bit ordering corresponds to the natural endianness of the target architecture. + +@sp 1 +@cartouche +@noindent +@strong{50}. The contents of the visible part of package @code{System} +and its language-defined children. See 13.7(2). +@end cartouche +@noindent +See the definition of these packages in files @file{system.ads} and +@file{s-stoele.ads}. + +@sp 1 +@cartouche +@noindent +@strong{51}. The contents of the visible part of package +@code{System.Machine_Code}, and the meaning of +@code{code_statements}. See 13.8(7). +@end cartouche +@noindent +See the definition and documentation in file @file{s-maccod.ads}. + +@sp 1 +@cartouche +@noindent +@strong{52}. The effect of unchecked conversion. See 13.9(11). +@end cartouche +@noindent +Unchecked conversion between types of the same size +results in an uninterpreted transmission of the bits from one type +to the other. If the types are of unequal sizes, then in the case of +discrete types, a shorter source is first zero or sign extended as +necessary, and a shorter target is simply truncated on the left. +For all non-discrete types, the source is first copied if necessary +to ensure that the alignment requirements of the target are met, then +a pointer is constructed to the source value, and the result is obtained +by dereferencing this pointer after converting it to be a pointer to the +target type. Unchecked conversions where the target subtype is an +unconstrained array are not permitted. If the target alignment is +greater than the source alignment, then a copy of the result is +made with appropriate alignment + +@sp 1 +@cartouche +@noindent +@strong{53}. The manner of choosing a storage pool for an access type +when @code{Storage_Pool} is not specified for the type. See 13.11(17). +@end cartouche +@noindent +There are 3 different standard pools used by the compiler when +@code{Storage_Pool} is not specified depending whether the type is local +to a subprogram or defined at the library level and whether +@code{Storage_Size}is specified or not. See documentation in the runtime +library units @code{System.Pool_Global}, @code{System.Pool_Size} and +@code{System.Pool_Local} in files @file{s-poosiz.ads}, +@file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the +default pools used. + +@sp 1 +@cartouche +@noindent +@strong{54}. Whether or not the implementation provides user-accessible +names for the standard pool type(s). See 13.11(17). +@end cartouche +@noindent + +See documentation in the sources of the run time mentioned in paragraph +@strong{53} . All these pools are accessible by means of @code{with}'ing +these units. + +@sp 1 +@cartouche +@noindent +@strong{55}. The meaning of @code{Storage_Size}. See 13.11(18). +@end cartouche +@noindent +@code{Storage_Size} is measured in storage units, and refers to the +total space available for an access type collection, or to the primary +stack space for a task. + +@sp 1 +@cartouche +@noindent +@strong{56}. Implementation-defined aspects of storage pools. See +13.11(22). +@end cartouche +@noindent +See documentation in the sources of the run time mentioned in paragraph +@strong{53} for details on GNAT-defined aspects of storage pools. + +@sp 1 +@cartouche +@noindent +@strong{57}. The set of restrictions allowed in a pragma +@code{Restrictions}. See 13.12(7). +@end cartouche +@noindent +All RM defined Restriction identifiers are implemented. The following +additional restriction identifiers are provided. There are two separate +lists of implementation dependent restriction identifiers. The first +set requires consistency throughout a partition (in other words, if the +restriction identifier is used for any compilation unit in the partition, +then all compilation units in the partition must obey the restriction. + +@table @code + +@item Simple_Barriers +@findex Simple_Barriers +This restriction ensures at compile time that barriers in entry declarations +for protected types are restricted to either static boolean expressions or +references to simple boolean variables defined in the private part of the +protected type. No other form of entry barriers is permitted. This is one +of the restrictions of the Ravenscar profile for limited tasking (see also +pragma @code{Profile (Ravenscar)}). + +@item Max_Entry_Queue_Length => Expr +@findex Max_Entry_Queue_Length +This restriction is a declaration that any protected entry compiled in +the scope of the restriction has at most the specified number of +tasks waiting on the entry +at any one time, and so no queue is required. This restriction is not +checked at compile time. A program execution is erroneous if an attempt +is made to queue more than the specified number of tasks on such an entry. + +@item No_Calendar +@findex No_Calendar +This restriction ensures at compile time that there is no implicit or +explicit dependence on the package @code{Ada.Calendar}. + +@item No_Direct_Boolean_Operators +@findex No_Direct_Boolean_Operators +This restriction ensures that no logical (and/or/xor) or comparison +operators are used on operands of type Boolean (or any type derived +from Boolean). This is intended for use in safety critical programs +where the certification protocol requires the use of short-circuit +(and then, or else) forms for all composite boolean operations. + +@item No_Dispatching_Calls +@findex No_Dispatching_Calls +This restriction ensures at compile time that the code generated by the +compiler involves no dispatching calls. The use of this restriction allows the +safe use of record extensions and membership tests and ensures that the code +contains no indirect calls through a dispatching mechanism. (Note that this +includes internally-generated calls created by the compiler, for example in +the implementation of the predefined attributes on class-wide objects.) The +membership test is allowed in the presence of this restriction, because its +implementation requires no dispatching. The following example indicates +constructs that violate this restriction. + +@smallexample +package Pkg is + type T is tagged record + Data : Natural; + end record; + procedure P (X : T); + + type DT is new T with record + More_Data : Natural; + end record; + procedure Q (X : DT); +end Pkg; + +with Pkg; use Pkg; +procedure Example is + procedure Test (O : T'Class) is + N : Natural := O'Size; -- Error: Dispatching call + begin + if O in DT'Class then -- OK : Membership test + Q (DT (O)); -- OK : Type conversion plus direct call + else + P (O); -- Error: Dispatching call + end if; + end Test; + + Obj : DT; +begin + P (Obj); -- OK : Direct call + P (T (Obj)); -- OK : Type conversion plus direct call + P (T'Class (Obj)); -- Error: Dispatching call + + Test (Obj); -- OK : Type conversion + + if Obj in T'Class then -- OK : Membership test + null; + end if; +end Example; +@end smallexample + +@item No_Dynamic_Attachment +@findex No_Dynamic_Attachment +This restriction ensures that there is no call to any of the operations +defined in package Ada.Interrupts. + +@item No_Enumeration_Maps +@findex No_Enumeration_Maps +This restriction ensures at compile time that no operations requiring +enumeration maps are used (that is Image and Value attributes applied +to enumeration types). + +@item No_Entry_Calls_In_Elaboration_Code +@findex No_Entry_Calls_In_Elaboration_Code +This restriction ensures at compile time that no task or protected entry +calls are made during elaboration code. As a result of the use of this +restriction, the compiler can assume that no code past an accept statement +in a task can be executed at elaboration time. + +@item No_Exception_Handlers +@findex No_Exception_Handlers +This restriction ensures at compile time that there are no explicit +exception handlers. It also indicates that no exception propagation will +be provided. In this mode, exceptions may be raised but will result in +an immediate call to the last chance handler, a routine that the user +must define with the following profile: + + procedure Last_Chance_Handler + (Source_Location : System.Address; Line : Integer); + pragma Export (C, Last_Chance_Handler, + "__gnat_last_chance_handler"); + + The parameter is a C null-terminated string representing a message to be + associated with the exception (typically the source location of the raise + statement generated by the compiler). The Line parameter when nonzero + represents the line number in the source program where the raise occurs. + +@item No_Exception_Streams +@findex No_Exception_Streams +This restriction ensures at compile time that no stream operations for +types Exception_Id or Exception_Occurrence are used. This also makes it +impossible to pass exceptions to or from a partition with this restriction +in a distributed environment. If this exception is active, then the generated +code is simplified by omitting the otherwise-required global registration +of exceptions when they are declared. + +@item No_Implicit_Conditionals +@findex No_Implicit_Conditionals +This restriction ensures that the generated code does not contain any +implicit conditionals, either by modifying the generated code where possible, +or by rejecting any construct that would otherwise generate an implicit +conditional. Note that this check does not include run time constraint +checks, which on some targets may generate implicit conditionals as +well. To control the latter, constraint checks can be suppressed in the +normal manner. Constructs generating implicit conditionals include comparisons +of composite objects and the Max/Min attributes. + +@item No_Implicit_Dynamic_Code +@findex No_Implicit_Dynamic_Code +This restriction prevents the compiler from building ``trampolines''. +This is a structure that is built on the stack and contains dynamic +code to be executed at run time. A trampoline is needed to indirectly +address a nested subprogram (that is a subprogram that is not at the +library level). The restriction prevents the use of any of the +attributes @code{Address}, @code{Access} or @code{Unrestricted_Access} +being applied to a subprogram that is not at the library level. + +@item No_Implicit_Loops +@findex No_Implicit_Loops +This restriction ensures that the generated code does not contain any +implicit @code{for} loops, either by modifying +the generated code where possible, +or by rejecting any construct that would otherwise generate an implicit +@code{for} loop. + +@item No_Initialize_Scalars +@findex No_Initialize_Scalars +This restriction ensures that no unit in the partition is compiled with +pragma Initialize_Scalars. This allows the generation of more efficient +code, and in particular eliminates dummy null initialization routines that +are otherwise generated for some record and array types. + +@item No_Local_Protected_Objects +@findex No_Local_Protected_Objects +This restriction ensures at compile time that protected objects are +only declared at the library level. + +@item No_Protected_Type_Allocators +@findex No_Protected_Type_Allocators +This restriction ensures at compile time that there are no allocator +expressions that attempt to allocate protected objects. + +@item No_Secondary_Stack +@findex No_Secondary_Stack +This restriction ensures at compile time that the generated code does not +contain any reference to the secondary stack. The secondary stack is used +to implement functions returning unconstrained objects (arrays or records) +on some targets. + +@item No_Select_Statements +@findex No_Select_Statements +This restriction ensures at compile time no select statements of any kind +are permitted, that is the keyword @code{select} may not appear. +This is one of the restrictions of the Ravenscar +profile for limited tasking (see also pragma @code{Profile (Ravenscar)}). + +@item No_Standard_Storage_Pools +@findex No_Standard_Storage_Pools +This restriction ensures at compile time that no access types +use the standard default storage pool. Any access type declared must +have an explicit Storage_Pool attribute defined specifying a +user-defined storage pool. + +@item No_Streams +@findex No_Streams +This restriction ensures at compile/bind time that there are no +stream objects created (and therefore no actual stream operations). +This restriction does not forbid dependences on the package +@code{Ada.Streams}. So it is permissible to with +@code{Ada.Streams} (or another package that does so itself) +as long as no actual stream objects are created. + +@item No_Task_Attributes_Package +@findex No_Task_Attributes_Package +This restriction ensures at compile time that there are no implicit or +explicit dependencies on the package @code{Ada.Task_Attributes}. + +@item No_Task_Termination +@findex No_Task_Termination +This restriction ensures at compile time that no terminate alternatives +appear in any task body. + +@item No_Tasking +@findex No_Tasking +This restriction prevents the declaration of tasks or task types throughout +the partition. It is similar in effect to the use of @code{Max_Tasks => 0} +except that violations are caught at compile time and cause an error message +to be output either by the compiler or binder. + +@item Static_Priorities +@findex Static_Priorities +This restriction ensures at compile time that all priority expressions +are static, and that there are no dependencies on the package +@code{Ada.Dynamic_Priorities}. + +@item Static_Storage_Size +@findex Static_Storage_Size +This restriction ensures at compile time that any expression appearing +in a Storage_Size pragma or attribute definition clause is static. + +@end table + +@noindent +The second set of implementation dependent restriction identifiers +does not require partition-wide consistency. +The restriction may be enforced for a single +compilation unit without any effect on any of the +other compilation units in the partition. + +@table @code + +@item No_Elaboration_Code +@findex No_Elaboration_Code +This restriction ensures at compile time that no elaboration code is +generated. Note that this is not the same condition as is enforced +by pragma @code{Preelaborate}. There are cases in which pragma +@code{Preelaborate} still permits code to be generated (e.g.@: code +to initialize a large array to all zeroes), and there are cases of units +which do not meet the requirements for pragma @code{Preelaborate}, +but for which no elaboration code is generated. Generally, it is +the case that preelaborable units will meet the restrictions, with +the exception of large aggregates initialized with an others_clause, +and exception declarations (which generate calls to a run-time +registry procedure). This restriction is enforced on +a unit by unit basis, it need not be obeyed consistently +throughout a partition. + +It is not possible to precisely document +the constructs which are compatible with this restriction, since, +unlike most other restrictions, this is not a restriction on the +source code, but a restriction on the generated object code. For +example, if the source contains a declaration: + +@smallexample + Val : constant Integer := X; +@end smallexample + +@noindent +where X is not a static constant, it may be possible, depending +on complex optimization circuitry, for the compiler to figure +out the value of X at compile time, in which case this initialization +can be done by the loader, and requires no initialization code. It +is not possible to document the precise conditions under which the +optimizer can figure this out. + +@item No_Entry_Queue +@findex No_Entry_Queue +This restriction is a declaration that any protected entry compiled in +the scope of the restriction has at most one task waiting on the entry +at any one time, and so no queue is required. This restriction is not +checked at compile time. A program execution is erroneous if an attempt +is made to queue a second task on such an entry. + +@item No_Implementation_Attributes +@findex No_Implementation_Attributes +This restriction checks at compile time that no GNAT-defined attributes +are present. With this restriction, the only attributes that can be used +are those defined in the Ada 95 Reference Manual. + +@item No_Implementation_Pragmas +@findex No_Implementation_Pragmas +This restriction checks at compile time that no GNAT-defined pragmas +are present. With this restriction, the only pragmas that can be used +are those defined in the Ada 95 Reference Manual. + +@item No_Implementation_Restrictions +@findex No_Implementation_Restrictions +This restriction checks at compile time that no GNAT-defined restriction +identifiers (other than @code{No_Implementation_Restrictions} itself) +are present. With this restriction, the only other restriction identifiers +that can be used are those defined in the Ada 95 Reference Manual. + +@item No_Wide_Characters +@findex No_Wide_Characters +This restriction ensures at compile time that no uses of the types +@code{Wide_Character} or @code{Wide_String} or corresponding wide +wide types +appear, and that no wide or wide wide string or character literals +appear in the program (that is literals representing characters not in +type @code{Character}. + +@end table + +@sp 1 +@cartouche +@noindent +@strong{58}. The consequences of violating limitations on +@code{Restrictions} pragmas. See 13.12(9). +@end cartouche +@noindent +Restrictions that can be checked at compile time result in illegalities +if violated. Currently there are no other consequences of violating +restrictions. + +@sp 1 +@cartouche +@noindent +@strong{59}. The representation used by the @code{Read} and +@code{Write} attributes of elementary types in terms of stream +elements. See 13.13.2(9). +@end cartouche +@noindent +The representation is the in-memory representation of the base type of +the type, using the number of bits corresponding to the +@code{@var{type}'Size} value, and the natural ordering of the machine. + +@sp 1 +@cartouche +@noindent +@strong{60}. The names and characteristics of the numeric subtypes +declared in the visible part of package @code{Standard}. See A.1(3). +@end cartouche +@noindent +See items describing the integer and floating-point types supported. + +@sp 1 +@cartouche +@noindent +@strong{61}. The accuracy actually achieved by the elementary +functions. See A.5.1(1). +@end cartouche +@noindent +The elementary functions correspond to the functions available in the C +library. Only fast math mode is implemented. + +@sp 1 +@cartouche +@noindent +@strong{62}. The sign of a zero result from some of the operators or +functions in @code{Numerics.Generic_Elementary_Functions}, when +@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46). +@end cartouche +@noindent +The sign of zeroes follows the requirements of the IEEE 754 standard on +floating-point. + +@sp 1 +@cartouche +@noindent +@strong{63}. The value of +@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27). +@end cartouche +@noindent +Maximum image width is 649, see library file @file{a-numran.ads}. + +@sp 1 +@cartouche +@noindent +@strong{64}. The value of +@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27). +@end cartouche +@noindent +Maximum image width is 80, see library file @file{a-nudira.ads}. + +@sp 1 +@cartouche +@noindent +@strong{65}. The algorithms for random number generation. See +A.5.2(32). +@end cartouche +@noindent +The algorithm is documented in the source files @file{a-numran.ads} and +@file{a-numran.adb}. + +@sp 1 +@cartouche +@noindent +@strong{66}. The string representation of a random number generator's +state. See A.5.2(38). +@end cartouche +@noindent +See the documentation contained in the file @file{a-numran.adb}. + +@sp 1 +@cartouche +@noindent +@strong{67}. The minimum time interval between calls to the +time-dependent Reset procedure that are guaranteed to initiate different +random number sequences. See A.5.2(45). +@end cartouche +@noindent +The minimum period between reset calls to guarantee distinct series of +random numbers is one microsecond. + +@sp 1 +@cartouche +@noindent +@strong{68}. The values of the @code{Model_Mantissa}, +@code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, +@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics +Annex is not supported. See A.5.3(72). +@end cartouche +@noindent +See the source file @file{ttypef.ads} for the values of all numeric +attributes. + +@sp 1 +@cartouche +@noindent +@strong{69}. Any implementation-defined characteristics of the +input-output packages. See A.7(14). +@end cartouche +@noindent +There are no special implementation defined characteristics for these +packages. + +@sp 1 +@cartouche +@noindent +@strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See +A.9(10). +@end cartouche +@noindent +All type representations are contiguous, and the @code{Buffer_Size} is +the value of @code{@var{type}'Size} rounded up to the next storage unit +boundary. + +@sp 1 +@cartouche +@noindent +@strong{71}. External files for standard input, standard output, and +standard error See A.10(5). +@end cartouche +@noindent +These files are mapped onto the files provided by the C streams +libraries. See source file @file{i-cstrea.ads} for further details. + +@sp 1 +@cartouche +@noindent +@strong{72}. The accuracy of the value produced by @code{Put}. See +A.10.9(36). +@end cartouche +@noindent +If more digits are requested in the output than are represented by the +precision of the value, zeroes are output in the corresponding least +significant digit positions. + +@sp 1 +@cartouche +@noindent +@strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and +@code{Command_Name}. See A.15(1). +@end cartouche +@noindent +These are mapped onto the @code{argv} and @code{argc} parameters of the +main program in the natural manner. + +@sp 1 +@cartouche +@noindent +@strong{74}. Implementation-defined convention names. See B.1(11). +@end cartouche +@noindent +The following convention names are supported + +@table @code +@item Ada +Ada +@item Assembler +Assembly language +@item Asm +Synonym for Assembler +@item Assembly +Synonym for Assembler +@item C +C +@item C_Pass_By_Copy +Allowed only for record types, like C, but also notes that record +is to be passed by copy rather than reference. +@item COBOL +COBOL +@item CPP +C++ +@item Default +Treated the same as C +@item External +Treated the same as C +@item Fortran +Fortran +@item Intrinsic +For support of pragma @code{Import} with convention Intrinsic, see +separate section on Intrinsic Subprograms. +@item Stdcall +Stdcall (used for Windows implementations only). This convention correspond +to the WINAPI (previously called Pascal convention) C/C++ convention under +Windows. A function with this convention cleans the stack before exit. +@item DLL +Synonym for Stdcall +@item Win32 +Synonym for Stdcall +@item Stubbed +Stubbed is a special convention used to indicate that the body of the +subprogram will be entirely ignored. Any call to the subprogram +is converted into a raise of the @code{Program_Error} exception. If a +pragma @code{Import} specifies convention @code{stubbed} then no body need +be present at all. This convention is useful during development for the +inclusion of subprograms whose body has not yet been written. + +@end table +@noindent +In addition, all otherwise unrecognized convention names are also +treated as being synonymous with convention C@. In all implementations +except for VMS, use of such other names results in a warning. In VMS +implementations, these names are accepted silently. + +@sp 1 +@cartouche +@noindent +@strong{75}. The meaning of link names. See B.1(36). +@end cartouche +@noindent +Link names are the actual names used by the linker. + +@sp 1 +@cartouche +@noindent +@strong{76}. The manner of choosing link names when neither the link +name nor the address of an imported or exported entity is specified. See +B.1(36). +@end cartouche +@noindent +The default linker name is that which would be assigned by the relevant +external language, interpreting the Ada name as being in all lower case +letters. + +@sp 1 +@cartouche +@noindent +@strong{77}. The effect of pragma @code{Linker_Options}. See B.1(37). +@end cartouche +@noindent +The string passed to @code{Linker_Options} is presented uninterpreted as +an argument to the link command, unless it contains Ascii.NUL characters. +NUL characters if they appear act as argument separators, so for example + +@smallexample @c ada +pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef"); +@end smallexample + +@noindent +causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the +linker. The order of linker options is preserved for a given unit. The final +list of options passed to the linker is in reverse order of the elaboration +order. For example, linker options fo a body always appear before the options +from the corresponding package spec. + +@sp 1 +@cartouche +@noindent +@strong{78}. The contents of the visible part of package +@code{Interfaces} and its language-defined descendants. See B.2(1). +@end cartouche +@noindent +See files with prefix @file{i-} in the distributed library. + +@sp 1 +@cartouche +@noindent +@strong{79}. Implementation-defined children of package +@code{Interfaces}. The contents of the visible part of package +@code{Interfaces}. See B.2(11). +@end cartouche +@noindent +See files with prefix @file{i-} in the distributed library. + +@sp 1 +@cartouche +@noindent +@strong{80}. The types @code{Floating}, @code{Long_Floating}, +@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and +@code{COBOL_Character}; and the initialization of the variables +@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in +@code{Interfaces.COBOL}. See B.4(50). +@end cartouche +@noindent +@table @code +@item Floating +Float +@item Long_Floating +(Floating) Long_Float +@item Binary +Integer +@item Long_Binary +Long_Long_Integer +@item Decimal_Element +Character +@item COBOL_Character +Character +@end table + +@noindent +For initialization, see the file @file{i-cobol.ads} in the distributed library. + +@sp 1 +@cartouche +@noindent +@strong{81}. Support for access to machine instructions. See C.1(1). +@end cartouche +@noindent +See documentation in file @file{s-maccod.ads} in the distributed library. + +@sp 1 +@cartouche +@noindent +@strong{82}. Implementation-defined aspects of access to machine +operations. See C.1(9). +@end cartouche +@noindent +See documentation in file @file{s-maccod.ads} in the distributed library. + +@sp 1 +@cartouche +@noindent +@strong{83}. Implementation-defined aspects of interrupts. See C.3(2). +@end cartouche +@noindent +Interrupts are mapped to signals or conditions as appropriate. See +definition of unit +@code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details +on the interrupts supported on a particular target. + +@sp 1 +@cartouche +@noindent +@strong{84}. Implementation-defined aspects of pre-elaboration. See +C.4(13). +@end cartouche +@noindent +GNAT does not permit a partition to be restarted without reloading, +except under control of the debugger. + +@sp 1 +@cartouche +@noindent +@strong{85}. The semantics of pragma @code{Discard_Names}. See C.5(7). +@end cartouche +@noindent +Pragma @code{Discard_Names} causes names of enumeration literals to +be suppressed. In the presence of this pragma, the Image attribute +provides the image of the Pos of the literal, and Value accepts +Pos values. + +@sp 1 +@cartouche +@noindent +@strong{86}. The result of the @code{Task_Identification.Image} +attribute. See C.7.1(7). +@end cartouche +@noindent +The result of this attribute is an 8-digit hexadecimal string +representing the virtual address of the task control block. + +@sp 1 +@cartouche +@noindent +@strong{87}. The value of @code{Current_Task} when in a protected entry +or interrupt handler. See C.7.1(17). +@end cartouche +@noindent +Protected entries or interrupt handlers can be executed by any +convenient thread, so the value of @code{Current_Task} is undefined. + +@sp 1 +@cartouche +@noindent +@strong{88}. The effect of calling @code{Current_Task} from an entry +body or interrupt handler. See C.7.1(19). +@end cartouche +@noindent +The effect of calling @code{Current_Task} from an entry body or +interrupt handler is to return the identification of the task currently +executing the code. + +@sp 1 +@cartouche +@noindent +@strong{89}. Implementation-defined aspects of +@code{Task_Attributes}. See C.7.2(19). +@end cartouche +@noindent +There are no implementation-defined aspects of @code{Task_Attributes}. + +@sp 1 +@cartouche +@noindent +@strong{90}. Values of all @code{Metrics}. See D(2). +@end cartouche +@noindent +The metrics information for GNAT depends on the performance of the +underlying operating system. The sources of the run-time for tasking +implementation, together with the output from @code{-gnatG} can be +used to determine the exact sequence of operating systems calls made +to implement various tasking constructs. Together with appropriate +information on the performance of the underlying operating system, +on the exact target in use, this information can be used to determine +the required metrics. + +@sp 1 +@cartouche +@noindent +@strong{91}. The declarations of @code{Any_Priority} and +@code{Priority}. See D.1(11). +@end cartouche +@noindent +See declarations in file @file{system.ads}. + +@sp 1 +@cartouche +@noindent +@strong{92}. Implementation-defined execution resources. See D.1(15). +@end cartouche +@noindent +There are no implementation-defined execution resources. + +@sp 1 +@cartouche +@noindent +@strong{93}. Whether, on a multiprocessor, a task that is waiting for +access to a protected object keeps its processor busy. See D.2.1(3). +@end cartouche +@noindent +On a multi-processor, a task that is waiting for access to a protected +object does not keep its processor busy. + +@sp 1 +@cartouche +@noindent +@strong{94}. The affect of implementation defined execution resources +on task dispatching. See D.2.1(9). +@end cartouche +@noindent +@c SGI info +@ignore +Tasks map to IRIX threads, and the dispatching policy is as defined by +the IRIX implementation of threads. +@end ignore +Tasks map to threads in the threads package used by GNAT@. Where possible +and appropriate, these threads correspond to native threads of the +underlying operating system. + +@sp 1 +@cartouche +@noindent +@strong{95}. Implementation-defined @code{policy_identifiers} allowed +in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3). +@end cartouche +@noindent +There are no implementation-defined policy-identifiers allowed in this +pragma. + +@sp 1 +@cartouche +@noindent +@strong{96}. Implementation-defined aspects of priority inversion. See +D.2.2(16). +@end cartouche +@noindent +Execution of a task cannot be preempted by the implementation processing +of delay expirations for lower priority tasks. + +@sp 1 +@cartouche +@noindent +@strong{97}. Implementation defined task dispatching. See D.2.2(18). +@end cartouche +@noindent +@c SGI info: +@ignore +Tasks map to IRIX threads, and the dispatching policy is as defined by +the IRIX implementation of threads. +@end ignore +The policy is the same as that of the underlying threads implementation. + +@sp 1 +@cartouche +@noindent +@strong{98}. Implementation-defined @code{policy_identifiers} allowed +in a pragma @code{Locking_Policy}. See D.3(4). +@end cartouche +@noindent +The only implementation defined policy permitted in GNAT is +@code{Inheritance_Locking}. On targets that support this policy, locking +is implemented by inheritance, i.e.@: the task owning the lock operates +at a priority equal to the highest priority of any task currently +requesting the lock. + +@sp 1 +@cartouche +@noindent +@strong{99}. Default ceiling priorities. See D.3(10). +@end cartouche +@noindent +The ceiling priority of protected objects of the type +@code{System.Interrupt_Priority'Last} as described in the Ada 95 +Reference Manual D.3(10), + +@sp 1 +@cartouche +@noindent +@strong{100}. The ceiling of any protected object used internally by +the implementation. See D.3(16). +@end cartouche +@noindent +The ceiling priority of internal protected objects is +@code{System.Priority'Last}. + +@sp 1 +@cartouche +@noindent +@strong{101}. Implementation-defined queuing policies. See D.4(1). +@end cartouche +@noindent +There are no implementation-defined queuing policies. + +@sp 1 +@cartouche +@noindent +@strong{102}. On a multiprocessor, any conditions that cause the +completion of an aborted construct to be delayed later than what is +specified for a single processor. See D.6(3). +@end cartouche +@noindent +The semantics for abort on a multi-processor is the same as on a single +processor, there are no further delays. + +@sp 1 +@cartouche +@noindent +@strong{103}. Any operations that implicitly require heap storage +allocation. See D.7(8). +@end cartouche +@noindent +The only operation that implicitly requires heap storage allocation is +task creation. + +@sp 1 +@cartouche +@noindent +@strong{104}. Implementation-defined aspects of pragma +@code{Restrictions}. See D.7(20). +@end cartouche +@noindent +There are no such implementation-defined aspects. + +@sp 1 +@cartouche +@noindent +@strong{105}. Implementation-defined aspects of package +@code{Real_Time}. See D.8(17). +@end cartouche +@noindent +There are no implementation defined aspects of package @code{Real_Time}. + +@sp 1 +@cartouche +@noindent +@strong{106}. Implementation-defined aspects of +@code{delay_statements}. See D.9(8). +@end cartouche +@noindent +Any difference greater than one microsecond will cause the task to be +delayed (see D.9(7)). + +@sp 1 +@cartouche +@noindent +@strong{107}. The upper bound on the duration of interrupt blocking +caused by the implementation. See D.12(5). +@end cartouche +@noindent +The upper bound is determined by the underlying operating system. In +no cases is it more than 10 milliseconds. + +@sp 1 +@cartouche +@noindent +@strong{108}. The means for creating and executing distributed +programs. See E(5). +@end cartouche +@noindent +The GLADE package provides a utility GNATDIST for creating and executing +distributed programs. See the GLADE reference manual for further details. + +@sp 1 +@cartouche +@noindent +@strong{109}. Any events that can result in a partition becoming +inaccessible. See E.1(7). +@end cartouche +@noindent +See the GLADE reference manual for full details on such events. + +@sp 1 +@cartouche +@noindent +@strong{110}. The scheduling policies, treatment of priorities, and +management of shared resources between partitions in certain cases. See +E.1(11). +@end cartouche +@noindent +See the GLADE reference manual for full details on these aspects of +multi-partition execution. + +@sp 1 +@cartouche +@noindent +@strong{111}. Events that cause the version of a compilation unit to +change. See E.3(5). +@end cartouche +@noindent +Editing the source file of a compilation unit, or the source files of +any units on which it is dependent in a significant way cause the version +to change. No other actions cause the version number to change. All changes +are significant except those which affect only layout, capitalization or +comments. + +@sp 1 +@cartouche +@noindent +@strong{112}. Whether the execution of the remote subprogram is +immediately aborted as a result of cancellation. See E.4(13). +@end cartouche +@noindent +See the GLADE reference manual for details on the effect of abort in +a distributed application. + +@sp 1 +@cartouche +@noindent +@strong{113}. Implementation-defined aspects of the PCS@. See E.5(25). +@end cartouche +@noindent +See the GLADE reference manual for a full description of all implementation +defined aspects of the PCS@. + +@sp 1 +@cartouche +@noindent +@strong{114}. Implementation-defined interfaces in the PCS@. See +E.5(26). +@end cartouche +@noindent +See the GLADE reference manual for a full description of all +implementation defined interfaces. + +@sp 1 +@cartouche +@noindent +@strong{115}. The values of named numbers in the package +@code{Decimal}. See F.2(7). +@end cartouche +@noindent +@table @code +@item Max_Scale ++18 +@item Min_Scale +-18 +@item Min_Delta +1.0E-18 +@item Max_Delta +1.0E+18 +@item Max_Decimal_Digits +18 +@end table + +@sp 1 +@cartouche +@noindent +@strong{116}. The value of @code{Max_Picture_Length} in the package +@code{Text_IO.Editing}. See F.3.3(16). +@end cartouche +@noindent +64 + +@sp 1 +@cartouche +@noindent +@strong{117}. The value of @code{Max_Picture_Length} in the package +@code{Wide_Text_IO.Editing}. See F.3.4(5). +@end cartouche +@noindent +64 + +@sp 1 +@cartouche +@noindent +@strong{118}. The accuracy actually achieved by the complex elementary +functions and by other complex arithmetic operations. See G.1(1). +@end cartouche +@noindent +Standard library functions are used for the complex arithmetic +operations. Only fast math mode is currently supported. + +@sp 1 +@cartouche +@noindent +@strong{119}. The sign of a zero result (or a component thereof) from +any operator or function in @code{Numerics.Generic_Complex_Types}, when +@code{Real'Signed_Zeros} is True. See G.1.1(53). +@end cartouche +@noindent +The signs of zero values are as recommended by the relevant +implementation advice. + +@sp 1 +@cartouche +@noindent +@strong{120}. The sign of a zero result (or a component thereof) from +any operator or function in +@code{Numerics.Generic_Complex_Elementary_Functions}, when +@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45). +@end cartouche +@noindent +The signs of zero values are as recommended by the relevant +implementation advice. + +@sp 1 +@cartouche +@noindent +@strong{121}. Whether the strict mode or the relaxed mode is the +default. See G.2(2). +@end cartouche +@noindent +The strict mode is the default. There is no separate relaxed mode. GNAT +provides a highly efficient implementation of strict mode. + +@sp 1 +@cartouche +@noindent +@strong{122}. The result interval in certain cases of fixed-to-float +conversion. See G.2.1(10). +@end cartouche +@noindent +For cases where the result interval is implementation dependent, the +accuracy is that provided by performing all operations in 64-bit IEEE +floating-point format. + +@sp 1 +@cartouche +@noindent +@strong{123}. The result of a floating point arithmetic operation in +overflow situations, when the @code{Machine_Overflows} attribute of the +result type is @code{False}. See G.2.1(13). +@end cartouche +@noindent +Infinite and NaN values are produced as dictated by the IEEE +floating-point standard. + +Note that on machines that are not fully compliant with the IEEE +floating-point standard, such as Alpha, the @option{-mieee} compiler flag +must be used for achieving IEEE confirming behavior (although at the cost +of a significant performance penalty), so infinite and NaN values are +properly generated. + +@sp 1 +@cartouche +@noindent +@strong{124}. The result interval for division (or exponentiation by a +negative exponent), when the floating point hardware implements division +as multiplication by a reciprocal. See G.2.1(16). +@end cartouche +@noindent +Not relevant, division is IEEE exact. + +@sp 1 +@cartouche +@noindent +@strong{125}. The definition of close result set, which determines the +accuracy of certain fixed point multiplications and divisions. See +G.2.3(5). +@end cartouche +@noindent +Operations in the close result set are performed using IEEE long format +floating-point arithmetic. The input operands are converted to +floating-point, the operation is done in floating-point, and the result +is converted to the target type. + +@sp 1 +@cartouche +@noindent +@strong{126}. Conditions on a @code{universal_real} operand of a fixed +point multiplication or division for which the result shall be in the +perfect result set. See G.2.3(22). +@end cartouche +@noindent +The result is only defined to be in the perfect result set if the result +can be computed by a single scaling operation involving a scale factor +representable in 64-bits. + +@sp 1 +@cartouche +@noindent +@strong{127}. The result of a fixed point arithmetic operation in +overflow situations, when the @code{Machine_Overflows} attribute of the +result type is @code{False}. See G.2.3(27). +@end cartouche +@noindent +Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point +types. + +@sp 1 +@cartouche +@noindent +@strong{128}. The result of an elementary function reference in +overflow situations, when the @code{Machine_Overflows} attribute of the +result type is @code{False}. See G.2.4(4). +@end cartouche +@noindent +IEEE infinite and Nan values are produced as appropriate. + +@sp 1 +@cartouche +@noindent +@strong{129}. The value of the angle threshold, within which certain +elementary functions, complex arithmetic operations, and complex +elementary functions yield results conforming to a maximum relative +error bound. See G.2.4(10). +@end cartouche +@noindent +Information on this subject is not yet available. + +@sp 1 +@cartouche +@noindent +@strong{130}. The accuracy of certain elementary functions for +parameters beyond the angle threshold. See G.2.4(10). +@end cartouche +@noindent +Information on this subject is not yet available. + +@sp 1 +@cartouche +@noindent +@strong{131}. The result of a complex arithmetic operation or complex +elementary function reference in overflow situations, when the +@code{Machine_Overflows} attribute of the corresponding real type is +@code{False}. See G.2.6(5). +@end cartouche +@noindent +IEEE infinite and Nan values are produced as appropriate. + +@sp 1 +@cartouche +@noindent +@strong{132}. The accuracy of certain complex arithmetic operations and +certain complex elementary functions for parameters (or components +thereof) beyond the angle threshold. See G.2.6(8). +@end cartouche +@noindent +Information on those subjects is not yet available. + +@sp 1 +@cartouche +@noindent +@strong{133}. Information regarding bounded errors and erroneous +execution. See H.2(1). +@end cartouche +@noindent +Information on this subject is not yet available. + +@sp 1 +@cartouche +@noindent +@strong{134}. Implementation-defined aspects of pragma +@code{Inspection_Point}. See H.3.2(8). +@end cartouche +@noindent +Pragma @code{Inspection_Point} ensures that the variable is live and can +be examined by the debugger at the inspection point. + +@sp 1 +@cartouche +@noindent +@strong{135}. Implementation-defined aspects of pragma +@code{Restrictions}. See H.4(25). +@end cartouche +@noindent +There are no implementation-defined aspects of pragma @code{Restrictions}. The +use of pragma @code{Restrictions [No_Exceptions]} has no effect on the +generated code. Checks must suppressed by use of pragma @code{Suppress}. + +@sp 1 +@cartouche +@noindent +@strong{136}. Any restrictions on pragma @code{Restrictions}. See +H.4(27). +@end cartouche +@noindent +There are no restrictions on pragma @code{Restrictions}. + +@node Intrinsic Subprograms +@chapter Intrinsic Subprograms +@cindex Intrinsic Subprograms + +@menu +* Intrinsic Operators:: +* Enclosing_Entity:: +* Exception_Information:: +* Exception_Message:: +* Exception_Name:: +* File:: +* Line:: +* Rotate_Left:: +* Rotate_Right:: +* Shift_Left:: +* Shift_Right:: +* Shift_Right_Arithmetic:: +* Source_Location:: +@end menu + +@noindent +GNAT allows a user application program to write the declaration: + +@smallexample @c ada + pragma Import (Intrinsic, name); +@end smallexample + +@noindent +providing that the name corresponds to one of the implemented intrinsic +subprograms in GNAT, and that the parameter profile of the referenced +subprogram meets the requirements. This chapter describes the set of +implemented intrinsic subprograms, and the requirements on parameter profiles. +Note that no body is supplied; as with other uses of pragma Import, the +body is supplied elsewhere (in this case by the compiler itself). Note +that any use of this feature is potentially non-portable, since the +Ada standard does not require Ada compilers to implement this feature. + +@node Intrinsic Operators +@section Intrinsic Operators +@cindex Intrinsic operator + +@noindent +All the predefined numeric operators in package Standard +in @code{pragma Import (Intrinsic,..)} +declarations. In the binary operator case, the operands must have the same +size. The operand or operands must also be appropriate for +the operator. For example, for addition, the operands must +both be floating-point or both be fixed-point, and the +right operand for @code{"**"} must have a root type of +@code{Standard.Integer'Base}. +You can use an intrinsic operator declaration as in the following example: + +@smallexample @c ada + type Int1 is new Integer; + type Int2 is new Integer; + + function "+" (X1 : Int1; X2 : Int2) return Int1; + function "+" (X1 : Int1; X2 : Int2) return Int2; + pragma Import (Intrinsic, "+"); +@end smallexample + +@noindent +This declaration would permit ``mixed mode'' arithmetic on items +of the differing types @code{Int1} and @code{Int2}. +It is also possible to specify such operators for private types, if the +full views are appropriate arithmetic types. + +@node Enclosing_Entity +@section Enclosing_Entity +@cindex Enclosing_Entity +@noindent +This intrinsic subprogram is used in the implementation of the +library routine @code{GNAT.Source_Info}. The only useful use of the +intrinsic import in this case is the one in this unit, so an +application program should simply call the function +@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of +the current subprogram, package, task, entry, or protected subprogram. + +@node Exception_Information +@section Exception_Information +@cindex Exception_Information' +@noindent +This intrinsic subprogram is used in the implementation of the +library routine @code{GNAT.Current_Exception}. The only useful +use of the intrinsic import in this case is the one in this unit, +so an application program should simply call the function +@code{GNAT.Current_Exception.Exception_Information} to obtain +the exception information associated with the current exception. + +@node Exception_Message +@section Exception_Message +@cindex Exception_Message +@noindent +This intrinsic subprogram is used in the implementation of the +library routine @code{GNAT.Current_Exception}. The only useful +use of the intrinsic import in this case is the one in this unit, +so an application program should simply call the function +@code{GNAT.Current_Exception.Exception_Message} to obtain +the message associated with the current exception. + +@node Exception_Name +@section Exception_Name +@cindex Exception_Name +@noindent +This intrinsic subprogram is used in the implementation of the +library routine @code{GNAT.Current_Exception}. The only useful +use of the intrinsic import in this case is the one in this unit, +so an application program should simply call the function +@code{GNAT.Current_Exception.Exception_Name} to obtain +the name of the current exception. + +@node File +@section File +@cindex File +@noindent +This intrinsic subprogram is used in the implementation of the +library routine @code{GNAT.Source_Info}. The only useful use of the +intrinsic import in this case is the one in this unit, so an +application program should simply call the function +@code{GNAT.Source_Info.File} to obtain the name of the current +file. + +@node Line +@section Line +@cindex Line +@noindent +This intrinsic subprogram is used in the implementation of the +library routine @code{GNAT.Source_Info}. The only useful use of the +intrinsic import in this case is the one in this unit, so an +application program should simply call the function +@code{GNAT.Source_Info.Line} to obtain the number of the current +source line. + +@node Rotate_Left +@section Rotate_Left +@cindex Rotate_Left +@noindent +In standard Ada 95, the @code{Rotate_Left} function is available only +for the predefined modular types in package @code{Interfaces}. However, in +GNAT it is possible to define a Rotate_Left function for a user +defined modular type or any signed integer type as in this example: + +@smallexample @c ada + function Shift_Left + (Value : My_Modular_Type; + Amount : Natural) + return My_Modular_Type; +@end smallexample + +@noindent +The requirements are that the profile be exactly as in the example +above. The only modifications allowed are in the formal parameter +names, and in the type of @code{Value} and the return type, which +must be the same, and must be either a signed integer type, or +a modular integer type with a binary modulus, and the size must +be 8. 16, 32 or 64 bits. + +@node Rotate_Right +@section Rotate_Right +@cindex Rotate_Right +@noindent +A @code{Rotate_Right} function can be defined for any user defined +binary modular integer type, or signed integer type, as described +above for @code{Rotate_Left}. + +@node Shift_Left +@section Shift_Left +@cindex Shift_Left +@noindent +A @code{Shift_Left} function can be defined for any user defined +binary modular integer type, or signed integer type, as described +above for @code{Rotate_Left}. + +@node Shift_Right +@section Shift_Right +@cindex Shift_Right +@noindent +A @code{Shift_Right} function can be defined for any user defined +binary modular integer type, or signed integer type, as described +above for @code{Rotate_Left}. + +@node Shift_Right_Arithmetic +@section Shift_Right_Arithmetic +@cindex Shift_Right_Arithmetic +@noindent +A @code{Shift_Right_Arithmetic} function can be defined for any user +defined binary modular integer type, or signed integer type, as described +above for @code{Rotate_Left}. + +@node Source_Location +@section Source_Location +@cindex Source_Location +@noindent +This intrinsic subprogram is used in the implementation of the +library routine @code{GNAT.Source_Info}. The only useful use of the +intrinsic import in this case is the one in this unit, so an +application program should simply call the function +@code{GNAT.Source_Info.Source_Location} to obtain the current +source file location. + +@node Representation Clauses and Pragmas +@chapter Representation Clauses and Pragmas +@cindex Representation Clauses + +@menu +* Alignment Clauses:: +* Size Clauses:: +* Storage_Size Clauses:: +* Size of Variant Record Objects:: +* Biased Representation :: +* Value_Size and Object_Size Clauses:: +* Component_Size Clauses:: +* Bit_Order Clauses:: +* Effect of Bit_Order on Byte Ordering:: +* Pragma Pack for Arrays:: +* Pragma Pack for Records:: +* Record Representation Clauses:: +* Enumeration Clauses:: +* Address Clauses:: +* Effect of Convention on Representation:: +* Determining the Representations chosen by GNAT:: +@end menu + +@noindent +@cindex Representation Clause +@cindex Representation Pragma +@cindex Pragma, representation +This section describes the representation clauses accepted by GNAT, and +their effect on the representation of corresponding data objects. + +GNAT fully implements Annex C (Systems Programming). This means that all +the implementation advice sections in chapter 13 are fully implemented. +However, these sections only require a minimal level of support for +representation clauses. GNAT provides much more extensive capabilities, +and this section describes the additional capabilities provided. + +@node Alignment Clauses +@section Alignment Clauses +@cindex Alignment Clause + +@noindent +GNAT requires that all alignment clauses specify a power of 2, and all +default alignments are always a power of 2. The default alignment +values are as follows: + +@itemize @bullet +@item @emph{Primitive Types}. +For primitive types, the alignment is the minimum of the actual size of +objects of the type divided by @code{Storage_Unit}, +and the maximum alignment supported by the target. +(This maximum alignment is given by the GNAT-specific attribute +@code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.) +@cindex @code{Maximum_Alignment} attribute +For example, for type @code{Long_Float}, the object size is 8 bytes, and the +default alignment will be 8 on any target that supports alignments +this large, but on some targets, the maximum alignment may be smaller +than 8, in which case objects of type @code{Long_Float} will be maximally +aligned. + +@item @emph{Arrays}. +For arrays, the alignment is equal to the alignment of the component type +for the normal case where no packing or component size is given. If the +array is packed, and the packing is effective (see separate section on +packed arrays), then the alignment will be one for long packed arrays, +or arrays whose length is not known at compile time. For short packed +arrays, which are handled internally as modular types, the alignment +will be as described for primitive types, e.g.@: a packed array of length +31 bits will have an object size of four bytes, and an alignment of 4. + +@item @emph{Records}. +For the normal non-packed case, the alignment of a record is equal to +the maximum alignment of any of its components. For tagged records, this +includes the implicit access type used for the tag. If a pragma @code{Pack} is +used and all fields are packable (see separate section on pragma @code{Pack}), +then the resulting alignment is 1. + +A special case is when: +@itemize @bullet +@item +the size of the record is given explicitly, or a +full record representation clause is given, and +@item +the size of the record is 2, 4, or 8 bytes. +@end itemize +@noindent +In this case, an alignment is chosen to match the +size of the record. For example, if we have: + +@smallexample @c ada + type Small is record + A, B : Character; + end record; + for Small'Size use 16; +@end smallexample + +@noindent +then the default alignment of the record type @code{Small} is 2, not 1. This +leads to more efficient code when the record is treated as a unit, and also +allows the type to specified as @code{Atomic} on architectures requiring +strict alignment. + +@end itemize + +@noindent +An alignment clause may +always specify a larger alignment than the default value, up to some +maximum value dependent on the target (obtainable by using the +attribute reference @code{Standard'Maximum_Alignment}). +The only case where +it is permissible to specify a smaller alignment than the default value +is for a record with a record representation clause. +In this case, packable fields for which a component clause is +given still result in a default alignment corresponding to the original +type, but this may be overridden, since these components in fact only +require an alignment of one byte. For example, given + +@smallexample @c ada + type V is record + A : Integer; + end record; + + for V use record + A at 0 range 0 .. 31; + end record; + + for V'alignment use 1; +@end smallexample + +@noindent +@cindex Alignment, default +The default alignment for the type @code{V} is 4, as a result of the +Integer field in the record, but since this field is placed with a +component clause, it is permissible, as shown, to override the default +alignment of the record with a smaller value. + +@node Size Clauses +@section Size Clauses +@cindex Size Clause + +@noindent +The default size for a type @code{T} is obtainable through the +language-defined attribute @code{T'Size} and also through the +equivalent GNAT-defined attribute @code{T'Value_Size}. +For objects of type @code{T}, GNAT will generally increase the type size +so that the object size (obtainable through the GNAT-defined attribute +@code{T'Object_Size}) +is a multiple of @code{T'Alignment * Storage_Unit}. +For example + +@smallexample @c ada + type Smallint is range 1 .. 6; + + type Rec is record + Y1 : integer; + Y2 : boolean; + end record; +@end smallexample + +@noindent +In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, +as specified by the RM rules, +but objects of this type will have a size of 8 +(@code{Smallint'Object_Size} = 8), +since objects by default occupy an integral number +of storage units. On some targets, notably older +versions of the Digital Alpha, the size of stand +alone objects of this type may be 32, reflecting +the inability of the hardware to do byte load/stores. + +Similarly, the size of type @code{Rec} is 40 bits +(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but +the alignment is 4, so objects of this type will have +their size increased to 64 bits so that it is a multiple +of the alignment (in bits). This decision is +in accordance with the specific Implementation Advice in RM 13.3(43): + +@quotation +A @code{Size} clause should be supported for an object if the specified +@code{Size} is at least as large as its subtype's @code{Size}, and corresponds +to a size in storage elements that is a multiple of the object's +@code{Alignment} (if the @code{Alignment} is nonzero). +@end quotation + +@noindent +An explicit size clause may be used to override the default size by +increasing it. For example, if we have: + +@smallexample @c ada + type My_Boolean is new Boolean; + for My_Boolean'Size use 32; +@end smallexample + +@noindent +then values of this type will always be 32 bits long. In the case of +discrete types, the size can be increased up to 64 bits, with the effect +that the entire specified field is used to hold the value, sign- or +zero-extended as appropriate. If more than 64 bits is specified, then +padding space is allocated after the value, and a warning is issued that +there are unused bits. + +Similarly the size of records and arrays may be increased, and the effect +is to add padding bits after the value. This also causes a warning message +to be generated. + +The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a +Size in bits, this corresponds to an object of size 256 megabytes (minus +one). This limitation is true on all targets. The reason for this +limitation is that it improves the quality of the code in many cases +if it is known that a Size value can be accommodated in an object of +type Integer. + +@node Storage_Size Clauses +@section Storage_Size Clauses +@cindex Storage_Size Clause + +@noindent +For tasks, the @code{Storage_Size} clause specifies the amount of space +to be allocated for the task stack. This cannot be extended, and if the +stack is exhausted, then @code{Storage_Error} will be raised (if stack +checking is enabled). Use a @code{Storage_Size} attribute definition clause, +or a @code{Storage_Size} pragma in the task definition to set the +appropriate required size. A useful technique is to include in every +task definition a pragma of the form: + +@smallexample @c ada + pragma Storage_Size (Default_Stack_Size); +@end smallexample + +@noindent +Then @code{Default_Stack_Size} can be defined in a global package, and +modified as required. Any tasks requiring stack sizes different from the +default can have an appropriate alternative reference in the pragma. + +You can also use the @code{-d} binder switch to modify the default stack +size. + +For access types, the @code{Storage_Size} clause specifies the maximum +space available for allocation of objects of the type. If this space is +exceeded then @code{Storage_Error} will be raised by an allocation attempt. +In the case where the access type is declared local to a subprogram, the +use of a @code{Storage_Size} clause triggers automatic use of a special +predefined storage pool (@code{System.Pool_Size}) that ensures that all +space for the pool is automatically reclaimed on exit from the scope in +which the type is declared. + +A special case recognized by the compiler is the specification of a +@code{Storage_Size} of zero for an access type. This means that no +items can be allocated from the pool, and this is recognized at compile +time, and all the overhead normally associated with maintaining a fixed +size storage pool is eliminated. Consider the following example: + +@smallexample @c ada + procedure p is + type R is array (Natural) of Character; + type P is access all R; + for P'Storage_Size use 0; + -- Above access type intended only for interfacing purposes + + y : P; + + procedure g (m : P); + pragma Import (C, g); + + -- @dots{} + + begin + -- @dots{} + y := new R; + end; +@end smallexample + +@noindent +As indicated in this example, these dummy storage pools are often useful in +connection with interfacing where no object will ever be allocated. If you +compile the above example, you get the warning: + +@smallexample + p.adb:16:09: warning: allocation from empty storage pool + p.adb:16:09: warning: Storage_Error will be raised at run time +@end smallexample + +@noindent +Of course in practice, there will not be any explicit allocators in the +case of such an access declaration. + +@node Size of Variant Record Objects +@section Size of Variant Record Objects +@cindex Size, variant record objects +@cindex Variant record objects, size + +@noindent +In the case of variant record objects, there is a question whether Size gives +information about a particular variant, or the maximum size required +for any variant. Consider the following program + +@smallexample @c ada +with Text_IO; use Text_IO; +procedure q is + type R1 (A : Boolean := False) is record + case A is + when True => X : Character; + when False => null; + end case; + end record; + + V1 : R1 (False); + V2 : R1; + +begin + Put_Line (Integer'Image (V1'Size)); + Put_Line (Integer'Image (V2'Size)); +end q; +@end smallexample + +@noindent +Here we are dealing with a variant record, where the True variant +requires 16 bits, and the False variant requires 8 bits. +In the above example, both V1 and V2 contain the False variant, +which is only 8 bits long. However, the result of running the +program is: + +@smallexample +8 +16 +@end smallexample + +@noindent +The reason for the difference here is that the discriminant value of +V1 is fixed, and will always be False. It is not possible to assign +a True variant value to V1, therefore 8 bits is sufficient. On the +other hand, in the case of V2, the initial discriminant value is +False (from the default), but it is possible to assign a True +variant value to V2, therefore 16 bits must be allocated for V2 +in the general case, even fewer bits may be needed at any particular +point during the program execution. + +As can be seen from the output of this program, the @code{'Size} +attribute applied to such an object in GNAT gives the actual allocated +size of the variable, which is the largest size of any of the variants. +The Ada Reference Manual is not completely clear on what choice should +be made here, but the GNAT behavior seems most consistent with the +language in the RM@. + +In some cases, it may be desirable to obtain the size of the current +variant, rather than the size of the largest variant. This can be +achieved in GNAT by making use of the fact that in the case of a +subprogram parameter, GNAT does indeed return the size of the current +variant (because a subprogram has no way of knowing how much space +is actually allocated for the actual). + +Consider the following modified version of the above program: + +@smallexample @c ada +with Text_IO; use Text_IO; +procedure q is + type R1 (A : Boolean := False) is record + case A is + when True => X : Character; + when False => null; + end case; + end record; + + V2 : R1; + + function Size (V : R1) return Integer is + begin + return V'Size; + end Size; + +begin + Put_Line (Integer'Image (V2'Size)); + Put_Line (Integer'IMage (Size (V2))); + V2 := (True, 'x'); + Put_Line (Integer'Image (V2'Size)); + Put_Line (Integer'IMage (Size (V2))); +end q; +@end smallexample + +@noindent +The output from this program is + +@smallexample +16 +8 +16 +16 +@end smallexample + +@noindent +Here we see that while the @code{'Size} attribute always returns +the maximum size, regardless of the current variant value, the +@code{Size} function does indeed return the size of the current +variant value. + +@node Biased Representation +@section Biased Representation +@cindex Size for biased representation +@cindex Biased representation + +@noindent +In the case of scalars with a range starting at other than zero, it is +possible in some cases to specify a size smaller than the default minimum +value, and in such cases, GNAT uses an unsigned biased representation, +in which zero is used to represent the lower bound, and successive values +represent successive values of the type. + +For example, suppose we have the declaration: + +@smallexample @c ada + type Small is range -7 .. -4; + for Small'Size use 2; +@end smallexample + +@noindent +Although the default size of type @code{Small} is 4, the @code{Size} +clause is accepted by GNAT and results in the following representation +scheme: + +@smallexample + -7 is represented as 2#00# + -6 is represented as 2#01# + -5 is represented as 2#10# + -4 is represented as 2#11# +@end smallexample + +@noindent +Biased representation is only used if the specified @code{Size} clause +cannot be accepted in any other manner. These reduced sizes that force +biased representation can be used for all discrete types except for +enumeration types for which a representation clause is given. + +@node Value_Size and Object_Size Clauses +@section Value_Size and Object_Size Clauses +@findex Value_Size +@findex Object_Size +@cindex Size, of objects + +@noindent +In Ada 95, @code{T'Size} for a type @code{T} is the minimum number of bits +required to hold values of type @code{T}. Although this interpretation was +allowed in Ada 83, it was not required, and this requirement in practice +can cause some significant difficulties. For example, in most Ada 83 +compilers, @code{Natural'Size} was 32. However, in Ada 95, +@code{Natural'Size} is +typically 31. This means that code may change in behavior when moving +from Ada 83 to Ada 95. For example, consider: + +@smallexample @c ada + type Rec is record; + A : Natural; + B : Natural; + end record; + + for Rec use record + at 0 range 0 .. Natural'Size - 1; + at 0 range Natural'Size .. 2 * Natural'Size - 1; + end record; +@end smallexample + +@noindent +In the above code, since the typical size of @code{Natural} objects +is 32 bits and @code{Natural'Size} is 31, the above code can cause +unexpected inefficient packing in Ada 95, and in general there are +cases where the fact that the object size can exceed the +size of the type causes surprises. + +To help get around this problem GNAT provides two implementation +defined attributes, @code{Value_Size} and @code{Object_Size}. When +applied to a type, these attributes yield the size of the type +(corresponding to the RM defined size attribute), and the size of +objects of the type respectively. + +The @code{Object_Size} is used for determining the default size of +objects and components. This size value can be referred to using the +@code{Object_Size} attribute. The phrase ``is used'' here means that it is +the basis of the determination of the size. The backend is free to +pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone +character might be stored in 32 bits on a machine with no efficient +byte access instructions such as the Alpha. + +The default rules for the value of @code{Object_Size} for +discrete types are as follows: + +@itemize @bullet +@item +The @code{Object_Size} for base subtypes reflect the natural hardware +size in bits (run the compiler with @option{-gnatS} to find those values +for numeric types). Enumeration types and fixed-point base subtypes have +8, 16, 32 or 64 bits for this size, depending on the range of values +to be stored. + +@item +The @code{Object_Size} of a subtype is the same as the +@code{Object_Size} of +the type from which it is obtained. + +@item +The @code{Object_Size} of a derived base type is copied from the parent +base type, and the @code{Object_Size} of a derived first subtype is copied +from the parent first subtype. +@end itemize + +@noindent +The @code{Value_Size} attribute +is the (minimum) number of bits required to store a value +of the type. +This value is used to determine how tightly to pack +records or arrays with components of this type, and also affects +the semantics of unchecked conversion (unchecked conversions where +the @code{Value_Size} values differ generate a warning, and are potentially +target dependent). + +The default rules for the value of @code{Value_Size} are as follows: + +@itemize @bullet +@item +The @code{Value_Size} for a base subtype is the minimum number of bits +required to store all values of the type (including the sign bit +only if negative values are possible). + +@item +If a subtype statically matches the first subtype of a given type, then it has +by default the same @code{Value_Size} as the first subtype. This is a +consequence of RM 13.1(14) (``if two subtypes statically match, +then their subtype-specific aspects are the same''.) + +@item +All other subtypes have a @code{Value_Size} corresponding to the minimum +number of bits required to store all values of the subtype. For +dynamic bounds, it is assumed that the value can range down or up +to the corresponding bound of the ancestor +@end itemize + +@noindent +The RM defined attribute @code{Size} corresponds to the +@code{Value_Size} attribute. + +The @code{Size} attribute may be defined for a first-named subtype. This sets +the @code{Value_Size} of +the first-named subtype to the given value, and the +@code{Object_Size} of this first-named subtype to the given value padded up +to an appropriate boundary. It is a consequence of the default rules +above that this @code{Object_Size} will apply to all further subtypes. On the +other hand, @code{Value_Size} is affected only for the first subtype, any +dynamic subtypes obtained from it directly, and any statically matching +subtypes. The @code{Value_Size} of any other static subtypes is not affected. + +@code{Value_Size} and +@code{Object_Size} may be explicitly set for any subtype using +an attribute definition clause. Note that the use of these attributes +can cause the RM 13.1(14) rule to be violated. If two access types +reference aliased objects whose subtypes have differing @code{Object_Size} +values as a result of explicit attribute definition clauses, then it +is erroneous to convert from one access subtype to the other. + +At the implementation level, Esize stores the Object_Size and the +RM_Size field stores the @code{Value_Size} (and hence the value of the +@code{Size} attribute, +which, as noted above, is equivalent to @code{Value_Size}). + +To get a feel for the difference, consider the following examples (note +that in each case the base is @code{Short_Short_Integer} with a size of 8): + +@smallexample + Object_Size Value_Size + +type x1 is range 0 .. 5; 8 3 + +type x2 is range 0 .. 5; +for x2'size use 12; 16 12 + +subtype x3 is x2 range 0 .. 3; 16 2 + +subtype x4 is x2'base range 0 .. 10; 8 4 + +subtype x5 is x2 range 0 .. dynamic; 16 3* + +subtype x6 is x2'base range 0 .. dynamic; 8 3* + +@end smallexample + +@noindent +Note: the entries marked ``3*'' are not actually specified by the Ada 95 RM, +but it seems in the spirit of the RM rules to allocate the minimum number +of bits (here 3, given the range for @code{x2}) +known to be large enough to hold the given range of values. + +So far, so good, but GNAT has to obey the RM rules, so the question is +under what conditions must the RM @code{Size} be used. +The following is a list +of the occasions on which the RM @code{Size} must be used: + +@itemize @bullet +@item +Component size for packed arrays or records + +@item +Value of the attribute @code{Size} for a type + +@item +Warning about sizes not matching for unchecked conversion +@end itemize + +@noindent +For record types, the @code{Object_Size} is always a multiple of the +alignment of the type (this is true for all types). In some cases the +@code{Value_Size} can be smaller. Consider: + +@smallexample + type R is record + X : Integer; + Y : Character; + end record; +@end smallexample + +@noindent +On a typical 32-bit architecture, the X component will be four bytes, and +require four-byte alignment, and the Y component will be one byte. In this +case @code{R'Value_Size} will be 40 (bits) since this is the minimum size +required to store a value of this type, and for example, it is permissible +to have a component of type R in an outer record whose component size is +specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits), +since it must be rounded up so that this value is a multiple of the +alignment (4 bytes = 32 bits). + +@noindent +For all other types, the @code{Object_Size} +and Value_Size are the same (and equivalent to the RM attribute @code{Size}). +Only @code{Size} may be specified for such types. + +@node Component_Size Clauses +@section Component_Size Clauses +@cindex Component_Size Clause + +@noindent +Normally, the value specified in a component size clause must be consistent +with the subtype of the array component with regard to size and alignment. +In other words, the value specified must be at least equal to the size +of this subtype, and must be a multiple of the alignment value. + +In addition, component size clauses are allowed which cause the array +to be packed, by specifying a smaller value. The cases in which this +is allowed are for component size values in the range 1 through 63. The value +specified must not be smaller than the Size of the subtype. GNAT will +accurately honor all packing requests in this range. For example, if +we have: + +@smallexample @c ada +type r is array (1 .. 8) of Natural; +for r'Component_Size use 31; +@end smallexample + +@noindent +then the resulting array has a length of 31 bytes (248 bits = 8 * 31). +Of course access to the components of such an array is considerably +less efficient than if the natural component size of 32 is used. + +Note that there is no point in giving both a component size clause +and a pragma Pack for the same array type. if such duplicate +clauses are given, the pragma Pack will be ignored. + +@node Bit_Order Clauses +@section Bit_Order Clauses +@cindex Bit_Order Clause +@cindex bit ordering +@cindex ordering, of bits + +@noindent +For record subtypes, GNAT permits the specification of the @code{Bit_Order} +attribute. The specification may either correspond to the default bit +order for the target, in which case the specification has no effect and +places no additional restrictions, or it may be for the non-standard +setting (that is the opposite of the default). + +In the case where the non-standard value is specified, the effect is +to renumber bits within each byte, but the ordering of bytes is not +affected. There are certain +restrictions placed on component clauses as follows: + +@itemize @bullet + +@item Components fitting within a single storage unit. +@noindent +These are unrestricted, and the effect is merely to renumber bits. For +example if we are on a little-endian machine with @code{Low_Order_First} +being the default, then the following two declarations have exactly +the same effect: + +@smallexample @c ada + type R1 is record + A : Boolean; + B : Integer range 1 .. 120; + end record; + + for R1 use record + A at 0 range 0 .. 0; + B at 0 range 1 .. 7; + end record; + + type R2 is record + A : Boolean; + B : Integer range 1 .. 120; + end record; + + for R2'Bit_Order use High_Order_First; + + for R2 use record + A at 0 range 7 .. 7; + B at 0 range 0 .. 6; + end record; +@end smallexample + +@noindent +The useful application here is to write the second declaration with the +@code{Bit_Order} attribute definition clause, and know that it will be treated +the same, regardless of whether the target is little-endian or big-endian. + +@item Components occupying an integral number of bytes. +@noindent +These are components that exactly fit in two or more bytes. Such component +declarations are allowed, but have no effect, since it is important to realize +that the @code{Bit_Order} specification does not affect the ordering of bytes. +In particular, the following attempt at getting an endian-independent integer +does not work: + +@smallexample @c ada + type R2 is record + A : Integer; + end record; + + for R2'Bit_Order use High_Order_First; + + for R2 use record + A at 0 range 0 .. 31; + end record; +@end smallexample + +@noindent +This declaration will result in a little-endian integer on a +little-endian machine, and a big-endian integer on a big-endian machine. +If byte flipping is required for interoperability between big- and +little-endian machines, this must be explicitly programmed. This capability +is not provided by @code{Bit_Order}. + +@item Components that are positioned across byte boundaries +@noindent +but do not occupy an integral number of bytes. Given that bytes are not +reordered, such fields would occupy a non-contiguous sequence of bits +in memory, requiring non-trivial code to reassemble. They are for this +reason not permitted, and any component clause specifying such a layout +will be flagged as illegal by GNAT@. + +@end itemize + +@noindent +Since the misconception that Bit_Order automatically deals with all +endian-related incompatibilities is a common one, the specification of +a component field that is an integral number of bytes will always +generate a warning. This warning may be suppressed using +@code{pragma Suppress} if desired. The following section contains additional +details regarding the issue of byte ordering. + +@node Effect of Bit_Order on Byte Ordering +@section Effect of Bit_Order on Byte Ordering +@cindex byte ordering +@cindex ordering, of bytes + +@noindent +In this section we will review the effect of the @code{Bit_Order} attribute +definition clause on byte ordering. Briefly, it has no effect at all, but +a detailed example will be helpful. Before giving this +example, let us review the precise +definition of the effect of defining @code{Bit_Order}. The effect of a +non-standard bit order is described in section 15.5.3 of the Ada +Reference Manual: + +@quotation +2 A bit ordering is a method of interpreting the meaning of +the storage place attributes. +@end quotation + +@noindent +To understand the precise definition of storage place attributes in +this context, we visit section 13.5.1 of the manual: + +@quotation +13 A record_representation_clause (without the mod_clause) +specifies the layout. The storage place attributes (see 13.5.2) +are taken from the values of the position, first_bit, and last_bit +expressions after normalizing those values so that first_bit is +less than Storage_Unit. +@end quotation + +@noindent +The critical point here is that storage places are taken from +the values after normalization, not before. So the @code{Bit_Order} +interpretation applies to normalized values. The interpretation +is described in the later part of the 15.5.3 paragraph: + +@quotation +2 A bit ordering is a method of interpreting the meaning of +the storage place attributes. High_Order_First (known in the +vernacular as ``big endian'') means that the first bit of a +storage element (bit 0) is the most significant bit (interpreting +the sequence of bits that represent a component as an unsigned +integer value). Low_Order_First (known in the vernacular as +``little endian'') means the opposite: the first bit is the +least significant. +@end quotation + +@noindent +Note that the numbering is with respect to the bits of a storage +unit. In other words, the specification affects only the numbering +of bits within a single storage unit. + +We can make the effect clearer by giving an example. + +Suppose that we have an external device which presents two bytes, the first +byte presented, which is the first (low addressed byte) of the two byte +record is called Master, and the second byte is called Slave. + +The left most (most significant bit is called Control for each byte, and +the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost +(least significant) bit. + +On a big-endian machine, we can write the following representation clause + +@smallexample @c ada + type Data is record + Master_Control : Bit; + Master_V1 : Bit; + Master_V2 : Bit; + Master_V3 : Bit; + Master_V4 : Bit; + Master_V5 : Bit; + Master_V6 : Bit; + Master_V7 : Bit; + Slave_Control : Bit; + Slave_V1 : Bit; + Slave_V2 : Bit; + Slave_V3 : Bit; + Slave_V4 : Bit; + Slave_V5 : Bit; + Slave_V6 : Bit; + Slave_V7 : Bit; + end record; + + for Data use record + Master_Control at 0 range 0 .. 0; + Master_V1 at 0 range 1 .. 1; + Master_V2 at 0 range 2 .. 2; + Master_V3 at 0 range 3 .. 3; + Master_V4 at 0 range 4 .. 4; + Master_V5 at 0 range 5 .. 5; + Master_V6 at 0 range 6 .. 6; + Master_V7 at 0 range 7 .. 7; + Slave_Control at 1 range 0 .. 0; + Slave_V1 at 1 range 1 .. 1; + Slave_V2 at 1 range 2 .. 2; + Slave_V3 at 1 range 3 .. 3; + Slave_V4 at 1 range 4 .. 4; + Slave_V5 at 1 range 5 .. 5; + Slave_V6 at 1 range 6 .. 6; + Slave_V7 at 1 range 7 .. 7; + end record; +@end smallexample + +@noindent +Now if we move this to a little endian machine, then the bit ordering within +the byte is backwards, so we have to rewrite the record rep clause as: + +@smallexample @c ada + for Data use record + Master_Control at 0 range 7 .. 7; + Master_V1 at 0 range 6 .. 6; + Master_V2 at 0 range 5 .. 5; + Master_V3 at 0 range 4 .. 4; + Master_V4 at 0 range 3 .. 3; + Master_V5 at 0 range 2 .. 2; + Master_V6 at 0 range 1 .. 1; + Master_V7 at 0 range 0 .. 0; + Slave_Control at 1 range 7 .. 7; + Slave_V1 at 1 range 6 .. 6; + Slave_V2 at 1 range 5 .. 5; + Slave_V3 at 1 range 4 .. 4; + Slave_V4 at 1 range 3 .. 3; + Slave_V5 at 1 range 2 .. 2; + Slave_V6 at 1 range 1 .. 1; + Slave_V7 at 1 range 0 .. 0; + end record; +@end smallexample + +@noindent +It is a nuisance to have to rewrite the clause, especially if +the code has to be maintained on both machines. However, +this is a case that we can handle with the +@code{Bit_Order} attribute if it is implemented. +Note that the implementation is not required on byte addressed +machines, but it is indeed implemented in GNAT. +This means that we can simply use the +first record clause, together with the declaration + +@smallexample @c ada + for Data'Bit_Order use High_Order_First; +@end smallexample + +@noindent +and the effect is what is desired, namely the layout is exactly the same, +independent of whether the code is compiled on a big-endian or little-endian +machine. + +The important point to understand is that byte ordering is not affected. +A @code{Bit_Order} attribute definition never affects which byte a field +ends up in, only where it ends up in that byte. +To make this clear, let us rewrite the record rep clause of the previous +example as: + +@smallexample @c ada + for Data'Bit_Order use High_Order_First; + for Data use record + Master_Control at 0 range 0 .. 0; + Master_V1 at 0 range 1 .. 1; + Master_V2 at 0 range 2 .. 2; + Master_V3 at 0 range 3 .. 3; + Master_V4 at 0 range 4 .. 4; + Master_V5 at 0 range 5 .. 5; + Master_V6 at 0 range 6 .. 6; + Master_V7 at 0 range 7 .. 7; + Slave_Control at 0 range 8 .. 8; + Slave_V1 at 0 range 9 .. 9; + Slave_V2 at 0 range 10 .. 10; + Slave_V3 at 0 range 11 .. 11; + Slave_V4 at 0 range 12 .. 12; + Slave_V5 at 0 range 13 .. 13; + Slave_V6 at 0 range 14 .. 14; + Slave_V7 at 0 range 15 .. 15; + end record; +@end smallexample + +@noindent +This is exactly equivalent to saying (a repeat of the first example): + +@smallexample @c ada + for Data'Bit_Order use High_Order_First; + for Data use record + Master_Control at 0 range 0 .. 0; + Master_V1 at 0 range 1 .. 1; + Master_V2 at 0 range 2 .. 2; + Master_V3 at 0 range 3 .. 3; + Master_V4 at 0 range 4 .. 4; + Master_V5 at 0 range 5 .. 5; + Master_V6 at 0 range 6 .. 6; + Master_V7 at 0 range 7 .. 7; + Slave_Control at 1 range 0 .. 0; + Slave_V1 at 1 range 1 .. 1; + Slave_V2 at 1 range 2 .. 2; + Slave_V3 at 1 range 3 .. 3; + Slave_V4 at 1 range 4 .. 4; + Slave_V5 at 1 range 5 .. 5; + Slave_V6 at 1 range 6 .. 6; + Slave_V7 at 1 range 7 .. 7; + end record; +@end smallexample + +@noindent +Why are they equivalent? Well take a specific field, the @code{Slave_V2} +field. The storage place attributes are obtained by normalizing the +values given so that the @code{First_Bit} value is less than 8. After +normalizing the values (0,10,10) we get (1,2,2) which is exactly what +we specified in the other case. + +Now one might expect that the @code{Bit_Order} attribute might affect +bit numbering within the entire record component (two bytes in this +case, thus affecting which byte fields end up in), but that is not +the way this feature is defined, it only affects numbering of bits, +not which byte they end up in. + +Consequently it never makes sense to specify a starting bit number +greater than 7 (for a byte addressable field) if an attribute +definition for @code{Bit_Order} has been given, and indeed it +may be actively confusing to specify such a value, so the compiler +generates a warning for such usage. + +If you do need to control byte ordering then appropriate conditional +values must be used. If in our example, the slave byte came first on +some machines we might write: + +@smallexample @c ada + Master_Byte_First constant Boolean := @dots{}; + + Master_Byte : constant Natural := + 1 - Boolean'Pos (Master_Byte_First); + Slave_Byte : constant Natural := + Boolean'Pos (Master_Byte_First); + + for Data'Bit_Order use High_Order_First; + for Data use record + Master_Control at Master_Byte range 0 .. 0; + Master_V1 at Master_Byte range 1 .. 1; + Master_V2 at Master_Byte range 2 .. 2; + Master_V3 at Master_Byte range 3 .. 3; + Master_V4 at Master_Byte range 4 .. 4; + Master_V5 at Master_Byte range 5 .. 5; + Master_V6 at Master_Byte range 6 .. 6; + Master_V7 at Master_Byte range 7 .. 7; + Slave_Control at Slave_Byte range 0 .. 0; + Slave_V1 at Slave_Byte range 1 .. 1; + Slave_V2 at Slave_Byte range 2 .. 2; + Slave_V3 at Slave_Byte range 3 .. 3; + Slave_V4 at Slave_Byte range 4 .. 4; + Slave_V5 at Slave_Byte range 5 .. 5; + Slave_V6 at Slave_Byte range 6 .. 6; + Slave_V7 at Slave_Byte range 7 .. 7; + end record; +@end smallexample + +@noindent +Now to switch between machines, all that is necessary is +to set the boolean constant @code{Master_Byte_First} in +an appropriate manner. + +@node Pragma Pack for Arrays +@section Pragma Pack for Arrays +@cindex Pragma Pack (for arrays) + +@noindent +Pragma @code{Pack} applied to an array has no effect unless the component type +is packable. For a component type to be packable, it must be one of the +following cases: + +@itemize @bullet +@item +Any scalar type +@item +Any type whose size is specified with a size clause +@item +Any packed array type with a static size +@end itemize + +@noindent +For all these cases, if the component subtype size is in the range +1 through 63, then the effect of the pragma @code{Pack} is exactly as though a +component size were specified giving the component subtype size. +For example if we have: + +@smallexample @c ada + type r is range 0 .. 17; + + type ar is array (1 .. 8) of r; + pragma Pack (ar); +@end smallexample + +@noindent +Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size}, +and the size of the array @code{ar} will be exactly 40 bits. + +Note that in some cases this rather fierce approach to packing can produce +unexpected effects. For example, in Ada 95, type Natural typically has a +size of 31, meaning that if you pack an array of Natural, you get 31-bit +close packing, which saves a few bits, but results in far less efficient +access. Since many other Ada compilers will ignore such a packing request, +GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses +might not be what is intended. You can easily remove this warning by +using an explicit @code{Component_Size} setting instead, which never generates +a warning, since the intention of the programmer is clear in this case. + +GNAT treats packed arrays in one of two ways. If the size of the array is +known at compile time and is less than 64 bits, then internally the array +is represented as a single modular type, of exactly the appropriate number +of bits. If the length is greater than 63 bits, or is not known at compile +time, then the packed array is represented as an array of bytes, and the +length is always a multiple of 8 bits. + +Note that to represent a packed array as a modular type, the alignment must +be suitable for the modular type involved. For example, on typical machines +a 32-bit packed array will be represented by a 32-bit modular integer with +an alignment of four bytes. If you explicitly override the default alignment +with an alignment clause that is too small, the modular representation +cannot be used. For example, consider the following set of declarations: + +@smallexample @c ada + type R is range 1 .. 3; + type S is array (1 .. 31) of R; + for S'Component_Size use 2; + for S'Size use 62; + for S'Alignment use 1; +@end smallexample + +@noindent +If the alignment clause were not present, then a 62-bit modular +representation would be chosen (typically with an alignment of 4 or 8 +bytes depending on the target). But the default alignment is overridden +with the explicit alignment clause. This means that the modular +representation cannot be used, and instead the array of bytes +representation must be used, meaning that the length must be a multiple +of 8. Thus the above set of declarations will result in a diagnostic +rejecting the size clause and noting that the minimum size allowed is 64. + +@cindex Pragma Pack (for type Natural) +@cindex Pragma Pack warning + +One special case that is worth noting occurs when the base type of the +component size is 8/16/32 and the subtype is one bit less. Notably this +occurs with subtype @code{Natural}. Consider: + +@smallexample @c ada + type Arr is array (1 .. 32) of Natural; + pragma Pack (Arr); +@end smallexample + +@noindent +In all commonly used Ada 83 compilers, this pragma Pack would be ignored, +since typically @code{Natural'Size} is 32 in Ada 83, and in any case most +Ada 83 compilers did not attempt 31 bit packing. + +In Ada 95, @code{Natural'Size} is required to be 31. Furthermore, GNAT really +does pack 31-bit subtype to 31 bits. This may result in a substantial +unintended performance penalty when porting legacy Ada 83 code. To help +prevent this, GNAT generates a warning in such cases. If you really want 31 +bit packing in a case like this, you can set the component size explicitly: + +@smallexample @c ada + type Arr is array (1 .. 32) of Natural; + for Arr'Component_Size use 31; +@end smallexample + +@noindent +Here 31-bit packing is achieved as required, and no warning is generated, +since in this case the programmer intention is clear. + +@node Pragma Pack for Records +@section Pragma Pack for Records +@cindex Pragma Pack (for records) + +@noindent +Pragma @code{Pack} applied to a record will pack the components to reduce +wasted space from alignment gaps and by reducing the amount of space +taken by components. We distinguish between @emph{packable} components and +@emph{non-packable} components. +Components of the following types are considered packable: +@itemize @bullet +@item +All primitive types are packable. + +@item +Small packed arrays, whose size does not exceed 64 bits, and where the +size is statically known at compile time, are represented internally +as modular integers, and so they are also packable. + +@end itemize + +@noindent +All packable components occupy the exact number of bits corresponding to +their @code{Size} value, and are packed with no padding bits, i.e.@: they +can start on an arbitrary bit boundary. + +All other types are non-packable, they occupy an integral number of +storage units, and +are placed at a boundary corresponding to their alignment requirements. + +For example, consider the record + +@smallexample @c ada + type Rb1 is array (1 .. 13) of Boolean; + pragma Pack (rb1); + + type Rb2 is array (1 .. 65) of Boolean; + pragma Pack (rb2); + + type x2 is record + l1 : Boolean; + l2 : Duration; + l3 : Float; + l4 : Boolean; + l5 : Rb1; + l6 : Rb2; + end record; + pragma Pack (x2); +@end smallexample + +@noindent +The representation for the record x2 is as follows: + +@smallexample @c ada +for x2'Size use 224; +for x2 use record + l1 at 0 range 0 .. 0; + l2 at 0 range 1 .. 64; + l3 at 12 range 0 .. 31; + l4 at 16 range 0 .. 0; + l5 at 16 range 1 .. 13; + l6 at 18 range 0 .. 71; +end record; +@end smallexample + +@noindent +Studying this example, we see that the packable fields @code{l1} +and @code{l2} are +of length equal to their sizes, and placed at specific bit boundaries (and +not byte boundaries) to +eliminate padding. But @code{l3} is of a non-packable float type, so +it is on the next appropriate alignment boundary. + +The next two fields are fully packable, so @code{l4} and @code{l5} are +minimally packed with no gaps. However, type @code{Rb2} is a packed +array that is longer than 64 bits, so it is itself non-packable. Thus +the @code{l6} field is aligned to the next byte boundary, and takes an +integral number of bytes, i.e.@: 72 bits. + +@node Record Representation Clauses +@section Record Representation Clauses +@cindex Record Representation Clause + +@noindent +Record representation clauses may be given for all record types, including +types obtained by record extension. Component clauses are allowed for any +static component. The restrictions on component clauses depend on the type +of the component. + +@cindex Component Clause +For all components of an elementary type, the only restriction on component +clauses is that the size must be at least the 'Size value of the type +(actually the Value_Size). There are no restrictions due to alignment, +and such components may freely cross storage boundaries. + +Packed arrays with a size up to and including 64 bits are represented +internally using a modular type with the appropriate number of bits, and +thus the same lack of restriction applies. For example, if you declare: + +@smallexample @c ada + type R is array (1 .. 49) of Boolean; + pragma Pack (R); + for R'Size use 49; +@end smallexample + +@noindent +then a component clause for a component of type R may start on any +specified bit boundary, and may specify a value of 49 bits or greater. + +For packed bit arrays that are longer than 64 bits, there are two +cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), +including the important case of single bits or boolean values, then +there are no limitations on placement of such components, and they +may start and end at arbitrary bit boundaries. + +If the component size is not a power of 2 (e.g. 3 or 5), then +an array of this type longer than 64 bits must always be placed on +on a storage unit (byte) boundary and occupy an integral number +of storage units (bytes). Any component clause that does not +meet this requirement will be rejected. + +Any aliased component, or component of an aliased type, must +have its normal alignment and size. A component clause that +does not meet this requirement will be rejected. + +The tag field of a tagged type always occupies an address sized field at +the start of the record. No component clause may attempt to overlay this +tag. When a tagged type appears as a component, the tag field must have +proper alignment + +In the case of a record extension T1, of a type T, no component clause applied +to the type T1 can specify a storage location that would overlap the first +T'Size bytes of the record. + +For all other component types, including non-bit-packed arrays, +the component can be placed at an arbitrary bit boundary, +so for example, the following is permitted: + +@smallexample @c ada + type R is array (1 .. 10) of Boolean; + for R'Size use 80; + + type Q is record + G, H : Boolean; + L, M : R; + end record; + + for Q use record + G at 0 range 0 .. 0; + H at 0 range 1 .. 1; + L at 0 range 2 .. 81; + R at 0 range 82 .. 161; + end record; +@end smallexample + +@noindent +Note: the above rules apply to recent releases of GNAT 5. +In GNAT 3, there are more severe restrictions on larger components. +For non-primitive types, including packed arrays with a size greater than +64 bits, component clauses must respect the alignment requirement of the +type, in particular, always starting on a byte boundary, and the length +must be a multiple of the storage unit. + +@node Enumeration Clauses +@section Enumeration Clauses + +The only restriction on enumeration clauses is that the range of values +must be representable. For the signed case, if one or more of the +representation values are negative, all values must be in the range: + +@smallexample @c ada + System.Min_Int .. System.Max_Int +@end smallexample + +@noindent +For the unsigned case, where all values are non negative, the values must +be in the range: + +@smallexample @c ada + 0 .. System.Max_Binary_Modulus; +@end smallexample + +@noindent +A @emph{confirming} representation clause is one in which the values range +from 0 in sequence, i.e.@: a clause that confirms the default representation +for an enumeration type. +Such a confirming representation +is permitted by these rules, and is specially recognized by the compiler so +that no extra overhead results from the use of such a clause. + +If an array has an index type which is an enumeration type to which an +enumeration clause has been applied, then the array is stored in a compact +manner. Consider the declarations: + +@smallexample @c ada + type r is (A, B, C); + for r use (A => 1, B => 5, C => 10); + type t is array (r) of Character; +@end smallexample + +@noindent +The array type t corresponds to a vector with exactly three elements and +has a default size equal to @code{3*Character'Size}. This ensures efficient +use of space, but means that accesses to elements of the array will incur +the overhead of converting representation values to the corresponding +positional values, (i.e.@: the value delivered by the @code{Pos} attribute). + +@node Address Clauses +@section Address Clauses +@cindex Address Clause + +The reference manual allows a general restriction on representation clauses, +as found in RM 13.1(22): + +@quotation +An implementation need not support representation +items containing nonstatic expressions, except that +an implementation should support a representation item +for a given entity if each nonstatic expression in the +representation item is a name that statically denotes +a constant declared before the entity. +@end quotation + +@noindent +In practice this is applicable only to address clauses, since this is the +only case in which a non-static expression is permitted by the syntax. As +the AARM notes in sections 13.1 (22.a-22.h): + +@display + 22.a Reason: This is to avoid the following sort of thing: + + 22.b X : Integer := F(@dots{}); + Y : Address := G(@dots{}); + for X'Address use Y; + + 22.c In the above, we have to evaluate the + initialization expression for X before we + know where to put the result. This seems + like an unreasonable implementation burden. + + 22.d The above code should instead be written + like this: + + 22.e Y : constant Address := G(@dots{}); + X : Integer := F(@dots{}); + for X'Address use Y; + + 22.f This allows the expression ``Y'' to be safely + evaluated before X is created. + + 22.g The constant could be a formal parameter of mode in. + + 22.h An implementation can support other nonstatic + expressions if it wants to. Expressions of type + Address are hardly ever static, but their value + might be known at compile time anyway in many + cases. +@end display + +@noindent +GNAT does indeed permit many additional cases of non-static expressions. In +particular, if the type involved is elementary there are no restrictions +(since in this case, holding a temporary copy of the initialization value, +if one is present, is inexpensive). In addition, if there is no implicit or +explicit initialization, then there are no restrictions. GNAT will reject +only the case where all three of these conditions hold: + +@itemize @bullet + +@item +The type of the item is non-elementary (e.g.@: a record or array). + +@item +There is explicit or implicit initialization required for the object. +Note that access values are always implicitly initialized, and also +in GNAT, certain bit-packed arrays (those having a dynamic length or +a length greater than 64) will also be implicitly initialized to zero. + +@item +The address value is non-static. Here GNAT is more permissive than the +RM, and allows the address value to be the address of a previously declared +stand-alone variable, as long as it does not itself have an address clause. + +@smallexample @c ada + Anchor : Some_Initialized_Type; + Overlay : Some_Initialized_Type; + for Overlay'Address use Anchor'Address; +@end smallexample + +@noindent +However, the prefix of the address clause cannot be an array component, or +a component of a discriminated record. + +@end itemize + +@noindent +As noted above in section 22.h, address values are typically non-static. In +particular the To_Address function, even if applied to a literal value, is +a non-static function call. To avoid this minor annoyance, GNAT provides +the implementation defined attribute 'To_Address. The following two +expressions have identical values: + +@findex Attribute +@findex To_Address +@smallexample @c ada + To_Address (16#1234_0000#) + System'To_Address (16#1234_0000#); +@end smallexample + +@noindent +except that the second form is considered to be a static expression, and +thus when used as an address clause value is always permitted. + +@noindent +Additionally, GNAT treats as static an address clause that is an +unchecked_conversion of a static integer value. This simplifies the porting +of legacy code, and provides a portable equivalent to the GNAT attribute +@code{To_Address}. + +Another issue with address clauses is the interaction with alignment +requirements. When an address clause is given for an object, the address +value must be consistent with the alignment of the object (which is usually +the same as the alignment of the type of the object). If an address clause +is given that specifies an inappropriately aligned address value, then the +program execution is erroneous. + +Since this source of erroneous behavior can have unfortunate effects, GNAT +checks (at compile time if possible, generating a warning, or at execution +time with a run-time check) that the alignment is appropriate. If the +run-time check fails, then @code{Program_Error} is raised. This run-time +check is suppressed if range checks are suppressed, or if +@code{pragma Restrictions (No_Elaboration_Code)} is in effect. + +@findex Export +An address clause cannot be given for an exported object. More +understandably the real restriction is that objects with an address +clause cannot be exported. This is because such variables are not +defined by the Ada program, so there is no external object to export. + +@findex Import +It is permissible to give an address clause and a pragma Import for the +same object. In this case, the variable is not really defined by the +Ada program, so there is no external symbol to be linked. The link name +and the external name are ignored in this case. The reason that we allow this +combination is that it provides a useful idiom to avoid unwanted +initializations on objects with address clauses. + +When an address clause is given for an object that has implicit or +explicit initialization, then by default initialization takes place. This +means that the effect of the object declaration is to overwrite the +memory at the specified address. This is almost always not what the +programmer wants, so GNAT will output a warning: + +@smallexample + with System; + package G is + type R is record + M : Integer := 0; + end record; + + Ext : R; + for Ext'Address use System'To_Address (16#1234_1234#); + | + >>> warning: implicit initialization of "Ext" may + modify overlaid storage + >>> warning: use pragma Import for "Ext" to suppress + initialization (RM B(24)) + + end G; +@end smallexample + +@noindent +As indicated by the warning message, the solution is to use a (dummy) pragma +Import to suppress this initialization. The pragma tell the compiler that the +object is declared and initialized elsewhere. The following package compiles +without warnings (and the initialization is suppressed): + +@smallexample @c ada + with System; + package G is + type R is record + M : Integer := 0; + end record; + + Ext : R; + for Ext'Address use System'To_Address (16#1234_1234#); + pragma Import (Ada, Ext); + end G; +@end smallexample + +@noindent +A final issue with address clauses involves their use for overlaying +variables, as in the following example: +@cindex Overlaying of objects + +@smallexample @c ada + A : Integer; + B : Integer; + for B'Address use A'Address; +@end smallexample + +@noindent +or alternatively, using the form recommended by the RM: + +@smallexample @c ada + A : Integer; + Addr : constant Address := A'Address; + B : Integer; + for B'Address use Addr; +@end smallexample + +@noindent +In both of these cases, @code{A} +and @code{B} become aliased to one another via the +address clause. This use of address clauses to overlay +variables, achieving an effect similar to unchecked +conversion was erroneous in Ada 83, but in Ada 95 +the effect is implementation defined. Furthermore, the +Ada 95 RM specifically recommends that in a situation +like this, @code{B} should be subject to the following +implementation advice (RM 13.3(19)): + +@quotation +19 If the Address of an object is specified, or it is imported + or exported, then the implementation should not perform + optimizations based on assumptions of no aliases. +@end quotation + +@noindent +GNAT follows this recommendation, and goes further by also applying +this recommendation to the overlaid variable (@code{A} +in the above example) in this case. This means that the overlay +works "as expected", in that a modification to one of the variables +will affect the value of the other. + +@node Effect of Convention on Representation +@section Effect of Convention on Representation +@cindex Convention, effect on representation + +@noindent +Normally the specification of a foreign language convention for a type or +an object has no effect on the chosen representation. In particular, the +representation chosen for data in GNAT generally meets the standard system +conventions, and for example records are laid out in a manner that is +consistent with C@. This means that specifying convention C (for example) +has no effect. + +There are three exceptions to this general rule: + +@itemize @bullet + +@item Convention Fortran and array subtypes +If pragma Convention Fortran is specified for an array subtype, then in +accordance with the implementation advice in section 3.6.2(11) of the +Ada Reference Manual, the array will be stored in a Fortran-compatible +column-major manner, instead of the normal default row-major order. + +@item Convention C and enumeration types +GNAT normally stores enumeration types in 8, 16, or 32 bits as required +to accommodate all values of the type. For example, for the enumeration +type declared by: + +@smallexample @c ada + type Color is (Red, Green, Blue); +@end smallexample + +@noindent +8 bits is sufficient to store all values of the type, so by default, objects +of type @code{Color} will be represented using 8 bits. However, normal C +convention is to use 32 bits for all enum values in C, since enum values +are essentially of type int. If pragma @code{Convention C} is specified for an +Ada enumeration type, then the size is modified as necessary (usually to +32 bits) to be consistent with the C convention for enum values. + +@item Convention C/Fortran and Boolean types +In C, the usual convention for boolean values, that is values used for +conditions, is that zero represents false, and nonzero values represent +true. In Ada, the normal convention is that two specific values, typically +0/1, are used to represent false/true respectively. + +Fortran has a similar convention for @code{LOGICAL} values (any nonzero +value represents true). + +To accommodate the Fortran and C conventions, if a pragma Convention specifies +C or Fortran convention for a derived Boolean, as in the following example: + +@smallexample @c ada + type C_Switch is new Boolean; + pragma Convention (C, C_Switch); +@end smallexample + +@noindent +then the GNAT generated code will treat any nonzero value as true. For truth +values generated by GNAT, the conventional value 1 will be used for True, but +when one of these values is read, any nonzero value is treated as True. + +@end itemize + +@node Determining the Representations chosen by GNAT +@section Determining the Representations chosen by GNAT +@cindex Representation, determination of +@cindex @code{-gnatR} switch + +@noindent +Although the descriptions in this section are intended to be complete, it is +often easier to simply experiment to see what GNAT accepts and what the +effect is on the layout of types and objects. + +As required by the Ada RM, if a representation clause is not accepted, then +it must be rejected as illegal by the compiler. However, when a +representation clause or pragma is accepted, there can still be questions +of what the compiler actually does. For example, if a partial record +representation clause specifies the location of some components and not +others, then where are the non-specified components placed? Or if pragma +@code{Pack} is used on a record, then exactly where are the resulting +fields placed? The section on pragma @code{Pack} in this chapter can be +used to answer the second question, but it is often easier to just see +what the compiler does. + +For this purpose, GNAT provides the option @code{-gnatR}. If you compile +with this option, then the compiler will output information on the actual +representations chosen, in a format similar to source representation +clauses. For example, if we compile the package: + +@smallexample @c ada +package q is + type r (x : boolean) is tagged record + case x is + when True => S : String (1 .. 100); + when False => null; + end case; + end record; + + type r2 is new r (false) with record + y2 : integer; + end record; + + for r2 use record + y2 at 16 range 0 .. 31; + end record; + + type x is record + y : character; + end record; + + type x1 is array (1 .. 10) of x; + for x1'component_size use 11; + + type ia is access integer; + + type Rb1 is array (1 .. 13) of Boolean; + pragma Pack (rb1); + + type Rb2 is array (1 .. 65) of Boolean; + pragma Pack (rb2); + + type x2 is record + l1 : Boolean; + l2 : Duration; + l3 : Float; + l4 : Boolean; + l5 : Rb1; + l6 : Rb2; + end record; + pragma Pack (x2); +end q; +@end smallexample + +@noindent +using the switch @code{-gnatR} we obtain the following output: + +@smallexample +Representation information for unit q +------------------------------------- + +for r'Size use ??; +for r'Alignment use 4; +for r use record + x at 4 range 0 .. 7; + _tag at 0 range 0 .. 31; + s at 5 range 0 .. 799; +end record; + +for r2'Size use 160; +for r2'Alignment use 4; +for r2 use record + x at 4 range 0 .. 7; + _tag at 0 range 0 .. 31; + _parent at 0 range 0 .. 63; + y2 at 16 range 0 .. 31; +end record; + +for x'Size use 8; +for x'Alignment use 1; +for x use record + y at 0 range 0 .. 7; +end record; + +for x1'Size use 112; +for x1'Alignment use 1; +for x1'Component_Size use 11; + +for rb1'Size use 13; +for rb1'Alignment use 2; +for rb1'Component_Size use 1; + +for rb2'Size use 72; +for rb2'Alignment use 1; +for rb2'Component_Size use 1; + +for x2'Size use 224; +for x2'Alignment use 4; +for x2 use record + l1 at 0 range 0 .. 0; + l2 at 0 range 1 .. 64; + l3 at 12 range 0 .. 31; + l4 at 16 range 0 .. 0; + l5 at 16 range 1 .. 13; + l6 at 18 range 0 .. 71; +end record; +@end smallexample + +@noindent +The Size values are actually the Object_Size, i.e.@: the default size that +will be allocated for objects of the type. +The ?? size for type r indicates that we have a variant record, and the +actual size of objects will depend on the discriminant value. + +The Alignment values show the actual alignment chosen by the compiler +for each record or array type. + +The record representation clause for type r shows where all fields +are placed, including the compiler generated tag field (whose location +cannot be controlled by the programmer). + +The record representation clause for the type extension r2 shows all the +fields present, including the parent field, which is a copy of the fields +of the parent type of r2, i.e.@: r1. + +The component size and size clauses for types rb1 and rb2 show +the exact effect of pragma @code{Pack} on these arrays, and the record +representation clause for type x2 shows how pragma @code{Pack} affects +this record type. + +In some cases, it may be useful to cut and paste the representation clauses +generated by the compiler into the original source to fix and guarantee +the actual representation to be used. + +@node Standard Library Routines +@chapter Standard Library Routines + +@noindent +The Ada 95 Reference Manual contains in Annex A a full description of an +extensive set of standard library routines that can be used in any Ada +program, and which must be provided by all Ada compilers. They are +analogous to the standard C library used by C programs. + +GNAT implements all of the facilities described in annex A, and for most +purposes the description in the Ada 95 +reference manual, or appropriate Ada +text book, will be sufficient for making use of these facilities. + +In the case of the input-output facilities, +@xref{The Implementation of Standard I/O}, +gives details on exactly how GNAT interfaces to the +file system. For the remaining packages, the Ada 95 reference manual +should be sufficient. The following is a list of the packages included, +together with a brief description of the functionality that is provided. + +For completeness, references are included to other predefined library +routines defined in other sections of the Ada 95 reference manual (these are +cross-indexed from annex A). + +@table @code +@item Ada (A.2) +This is a parent package for all the standard library packages. It is +usually included implicitly in your program, and itself contains no +useful data or routines. + +@item Ada.Calendar (9.6) +@code{Calendar} provides time of day access, and routines for +manipulating times and durations. + +@item Ada.Characters (A.3.1) +This is a dummy parent package that contains no useful entities + +@item Ada.Characters.Handling (A.3.2) +This package provides some basic character handling capabilities, +including classification functions for classes of characters (e.g.@: test +for letters, or digits). + +@item Ada.Characters.Latin_1 (A.3.3) +This package includes a complete set of definitions of the characters +that appear in type CHARACTER@. It is useful for writing programs that +will run in international environments. For example, if you want an +upper case E with an acute accent in a string, it is often better to use +the definition of @code{UC_E_Acute} in this package. Then your program +will print in an understandable manner even if your environment does not +support these extended characters. + +@item Ada.Command_Line (A.15) +This package provides access to the command line parameters and the name +of the current program (analogous to the use of @code{argc} and @code{argv} +in C), and also allows the exit status for the program to be set in a +system-independent manner. + +@item Ada.Decimal (F.2) +This package provides constants describing the range of decimal numbers +implemented, and also a decimal divide routine (analogous to the COBOL +verb DIVIDE .. GIVING .. REMAINDER ..) + +@item Ada.Direct_IO (A.8.4) +This package provides input-output using a model of a set of records of +fixed-length, containing an arbitrary definite Ada type, indexed by an +integer record number. + +@item Ada.Dynamic_Priorities (D.5) +This package allows the priorities of a task to be adjusted dynamically +as the task is running. + +@item Ada.Exceptions (11.4.1) +This package provides additional information on exceptions, and also +contains facilities for treating exceptions as data objects, and raising +exceptions with associated messages. + +@item Ada.Finalization (7.6) +This package contains the declarations and subprograms to support the +use of controlled types, providing for automatic initialization and +finalization (analogous to the constructors and destructors of C++) + +@item Ada.Interrupts (C.3.2) +This package provides facilities for interfacing to interrupts, which +includes the set of signals or conditions that can be raised and +recognized as interrupts. + +@item Ada.Interrupts.Names (C.3.2) +This package provides the set of interrupt names (actually signal +or condition names) that can be handled by GNAT@. + +@item Ada.IO_Exceptions (A.13) +This package defines the set of exceptions that can be raised by use of +the standard IO packages. + +@item Ada.Numerics +This package contains some standard constants and exceptions used +throughout the numerics packages. Note that the constants pi and e are +defined here, and it is better to use these definitions than rolling +your own. + +@item Ada.Numerics.Complex_Elementary_Functions +Provides the implementation of standard elementary functions (such as +log and trigonometric functions) operating on complex numbers using the +standard @code{Float} and the @code{Complex} and @code{Imaginary} types +created by the package @code{Numerics.Complex_Types}. + +@item Ada.Numerics.Complex_Types +This is a predefined instantiation of +@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to +build the type @code{Complex} and @code{Imaginary}. + +@item Ada.Numerics.Discrete_Random +This package provides a random number generator suitable for generating +random integer values from a specified range. + +@item Ada.Numerics.Float_Random +This package provides a random number generator suitable for generating +uniformly distributed floating point values. + +@item Ada.Numerics.Generic_Complex_Elementary_Functions +This is a generic version of the package that provides the +implementation of standard elementary functions (such as log and +trigonometric functions) for an arbitrary complex type. + +The following predefined instantiations of this package are provided: + +@table @code +@item Short_Float +@code{Ada.Numerics.Short_Complex_Elementary_Functions} +@item Float +@code{Ada.Numerics.Complex_Elementary_Functions} +@item Long_Float +@code{Ada.Numerics. + Long_Complex_Elementary_Functions} +@end table + +@item Ada.Numerics.Generic_Complex_Types +This is a generic package that allows the creation of complex types, +with associated complex arithmetic operations. + +The following predefined instantiations of this package exist +@table @code +@item Short_Float +@code{Ada.Numerics.Short_Complex_Complex_Types} +@item Float +@code{Ada.Numerics.Complex_Complex_Types} +@item Long_Float +@code{Ada.Numerics.Long_Complex_Complex_Types} +@end table + +@item Ada.Numerics.Generic_Elementary_Functions +This is a generic package that provides the implementation of standard +elementary functions (such as log an trigonometric functions) for an +arbitrary float type. + +The following predefined instantiations of this package exist + +@table @code +@item Short_Float +@code{Ada.Numerics.Short_Elementary_Functions} +@item Float +@code{Ada.Numerics.Elementary_Functions} +@item Long_Float +@code{Ada.Numerics.Long_Elementary_Functions} +@end table + +@item Ada.Real_Time (D.8) +This package provides facilities similar to those of @code{Calendar}, but +operating with a finer clock suitable for real time control. Note that +annex D requires that there be no backward clock jumps, and GNAT generally +guarantees this behavior, but of course if the external clock on which +the GNAT runtime depends is deliberately reset by some external event, +then such a backward jump may occur. + +@item Ada.Sequential_IO (A.8.1) +This package provides input-output facilities for sequential files, +which can contain a sequence of values of a single type, which can be +any Ada type, including indefinite (unconstrained) types. + +@item Ada.Storage_IO (A.9) +This package provides a facility for mapping arbitrary Ada types to and +from a storage buffer. It is primarily intended for the creation of new +IO packages. + +@item Ada.Streams (13.13.1) +This is a generic package that provides the basic support for the +concept of streams as used by the stream attributes (@code{Input}, +@code{Output}, @code{Read} and @code{Write}). + +@item Ada.Streams.Stream_IO (A.12.1) +This package is a specialization of the type @code{Streams} defined in +package @code{Streams} together with a set of operations providing +Stream_IO capability. The Stream_IO model permits both random and +sequential access to a file which can contain an arbitrary set of values +of one or more Ada types. + +@item Ada.Strings (A.4.1) +This package provides some basic constants used by the string handling +packages. + +@item Ada.Strings.Bounded (A.4.4) +This package provides facilities for handling variable length +strings. The bounded model requires a maximum length. It is thus +somewhat more limited than the unbounded model, but avoids the use of +dynamic allocation or finalization. + +@item Ada.Strings.Fixed (A.4.3) +This package provides facilities for handling fixed length strings. + +@item Ada.Strings.Maps (A.4.2) +This package provides facilities for handling character mappings and +arbitrarily defined subsets of characters. For instance it is useful in +defining specialized translation tables. + +@item Ada.Strings.Maps.Constants (A.4.6) +This package provides a standard set of predefined mappings and +predefined character sets. For example, the standard upper to lower case +conversion table is found in this package. Note that upper to lower case +conversion is non-trivial if you want to take the entire set of +characters, including extended characters like E with an acute accent, +into account. You should use the mappings in this package (rather than +adding 32 yourself) to do case mappings. + +@item Ada.Strings.Unbounded (A.4.5) +This package provides facilities for handling variable length +strings. The unbounded model allows arbitrary length strings, but +requires the use of dynamic allocation and finalization. + +@item Ada.Strings.Wide_Bounded (A.4.7) +@itemx Ada.Strings.Wide_Fixed (A.4.7) +@itemx Ada.Strings.Wide_Maps (A.4.7) +@itemx Ada.Strings.Wide_Maps.Constants (A.4.7) +@itemx Ada.Strings.Wide_Unbounded (A.4.7) +These packages provide analogous capabilities to the corresponding +packages without @samp{Wide_} in the name, but operate with the types +@code{Wide_String} and @code{Wide_Character} instead of @code{String} +and @code{Character}. + +@item Ada.Strings.Wide_Wide_Bounded (A.4.7) +@itemx Ada.Strings.Wide_Wide_Fixed (A.4.7) +@itemx Ada.Strings.Wide_Wide_Maps (A.4.7) +@itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7) +@itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7) +These packages provide analogous capabilities to the corresponding +packages without @samp{Wide_} in the name, but operate with the types +@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead +of @code{String} and @code{Character}. + +@item Ada.Synchronous_Task_Control (D.10) +This package provides some standard facilities for controlling task +communication in a synchronous manner. + +@item Ada.Tags +This package contains definitions for manipulation of the tags of tagged +values. + +@item Ada.Task_Attributes +This package provides the capability of associating arbitrary +task-specific data with separate tasks. + +@item Ada.Text_IO +This package provides basic text input-output capabilities for +character, string and numeric data. The subpackages of this +package are listed next. + +@item Ada.Text_IO.Decimal_IO +Provides input-output facilities for decimal fixed-point types + +@item Ada.Text_IO.Enumeration_IO +Provides input-output facilities for enumeration types. + +@item Ada.Text_IO.Fixed_IO +Provides input-output facilities for ordinary fixed-point types. + +@item Ada.Text_IO.Float_IO +Provides input-output facilities for float types. The following +predefined instantiations of this generic package are available: + +@table @code +@item Short_Float +@code{Short_Float_Text_IO} +@item Float +@code{Float_Text_IO} +@item Long_Float +@code{Long_Float_Text_IO} +@end table + +@item Ada.Text_IO.Integer_IO +Provides input-output facilities for integer types. The following +predefined instantiations of this generic package are available: + +@table @code +@item Short_Short_Integer +@code{Ada.Short_Short_Integer_Text_IO} +@item Short_Integer +@code{Ada.Short_Integer_Text_IO} +@item Integer +@code{Ada.Integer_Text_IO} +@item Long_Integer +@code{Ada.Long_Integer_Text_IO} +@item Long_Long_Integer +@code{Ada.Long_Long_Integer_Text_IO} +@end table + +@item Ada.Text_IO.Modular_IO +Provides input-output facilities for modular (unsigned) types + +@item Ada.Text_IO.Complex_IO (G.1.3) +This package provides basic text input-output capabilities for complex +data. + +@item Ada.Text_IO.Editing (F.3.3) +This package contains routines for edited output, analogous to the use +of pictures in COBOL@. The picture formats used by this package are a +close copy of the facility in COBOL@. + +@item Ada.Text_IO.Text_Streams (A.12.2) +This package provides a facility that allows Text_IO files to be treated +as streams, so that the stream attributes can be used for writing +arbitrary data, including binary data, to Text_IO files. + +@item Ada.Unchecked_Conversion (13.9) +This generic package allows arbitrary conversion from one type to +another of the same size, providing for breaking the type safety in +special circumstances. + +If the types have the same Size (more accurately the same Value_Size), +then the effect is simply to transfer the bits from the source to the +target type without any modification. This usage is well defined, and +for simple types whose representation is typically the same across +all implementations, gives a portable method of performing such +conversions. + +If the types do not have the same size, then the result is implementation +defined, and thus may be non-portable. The following describes how GNAT +handles such unchecked conversion cases. + +If the types are of different sizes, and are both discrete types, then +the effect is of a normal type conversion without any constraint checking. +In particular if the result type has a larger size, the result will be +zero or sign extended. If the result type has a smaller size, the result +will be truncated by ignoring high order bits. + +If the types are of different sizes, and are not both discrete types, +then the conversion works as though pointers were created to the source +and target, and the pointer value is converted. The effect is that bits +are copied from successive low order storage units and bits of the source +up to the length of the target type. + +A warning is issued if the lengths differ, since the effect in this +case is implementation dependent, and the above behavior may not match +that of some other compiler. + +A pointer to one type may be converted to a pointer to another type using +unchecked conversion. The only case in which the effect is undefined is +when one or both pointers are pointers to unconstrained array types. In +this case, the bounds information may get incorrectly transferred, and in +particular, GNAT uses double size pointers for such types, and it is +meaningless to convert between such pointer types. GNAT will issue a +warning if the alignment of the target designated type is more strict +than the alignment of the source designated type (since the result may +be unaligned in this case). + +A pointer other than a pointer to an unconstrained array type may be +converted to and from System.Address. Such usage is common in Ada 83 +programs, but note that Ada.Address_To_Access_Conversions is the +preferred method of performing such conversions in Ada 95. Neither +unchecked conversion nor Ada.Address_To_Access_Conversions should be +used in conjunction with pointers to unconstrained objects, since +the bounds information cannot be handled correctly in this case. + +@item Ada.Unchecked_Deallocation (13.11.2) +This generic package allows explicit freeing of storage previously +allocated by use of an allocator. + +@item Ada.Wide_Text_IO (A.11) +This package is similar to @code{Ada.Text_IO}, except that the external +file supports wide character representations, and the internal types are +@code{Wide_Character} and @code{Wide_String} instead of @code{Character} +and @code{String}. It contains generic subpackages listed next. + +@item Ada.Wide_Text_IO.Decimal_IO +Provides input-output facilities for decimal fixed-point types + +@item Ada.Wide_Text_IO.Enumeration_IO +Provides input-output facilities for enumeration types. + +@item Ada.Wide_Text_IO.Fixed_IO +Provides input-output facilities for ordinary fixed-point types. + +@item Ada.Wide_Text_IO.Float_IO +Provides input-output facilities for float types. The following +predefined instantiations of this generic package are available: + +@table @code +@item Short_Float +@code{Short_Float_Wide_Text_IO} +@item Float +@code{Float_Wide_Text_IO} +@item Long_Float +@code{Long_Float_Wide_Text_IO} +@end table + +@item Ada.Wide_Text_IO.Integer_IO +Provides input-output facilities for integer types. The following +predefined instantiations of this generic package are available: + +@table @code +@item Short_Short_Integer +@code{Ada.Short_Short_Integer_Wide_Text_IO} +@item Short_Integer +@code{Ada.Short_Integer_Wide_Text_IO} +@item Integer +@code{Ada.Integer_Wide_Text_IO} +@item Long_Integer +@code{Ada.Long_Integer_Wide_Text_IO} +@item Long_Long_Integer +@code{Ada.Long_Long_Integer_Wide_Text_IO} +@end table + +@item Ada.Wide_Text_IO.Modular_IO +Provides input-output facilities for modular (unsigned) types + +@item Ada.Wide_Text_IO.Complex_IO (G.1.3) +This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the +external file supports wide character representations. + +@item Ada.Wide_Text_IO.Editing (F.3.4) +This package is similar to @code{Ada.Text_IO.Editing}, except that the +types are @code{Wide_Character} and @code{Wide_String} instead of +@code{Character} and @code{String}. + +@item Ada.Wide_Text_IO.Streams (A.12.3) +This package is similar to @code{Ada.Text_IO.Streams}, except that the +types are @code{Wide_Character} and @code{Wide_String} instead of +@code{Character} and @code{String}. + +@item Ada.Wide_Wide_Text_IO (A.11) +This package is similar to @code{Ada.Text_IO}, except that the external +file supports wide character representations, and the internal types are +@code{Wide_Character} and @code{Wide_String} instead of @code{Character} +and @code{String}. It contains generic subpackages listed next. + +@item Ada.Wide_Wide_Text_IO.Decimal_IO +Provides input-output facilities for decimal fixed-point types + +@item Ada.Wide_Wide_Text_IO.Enumeration_IO +Provides input-output facilities for enumeration types. + +@item Ada.Wide_Wide_Text_IO.Fixed_IO +Provides input-output facilities for ordinary fixed-point types. + +@item Ada.Wide_Wide_Text_IO.Float_IO +Provides input-output facilities for float types. The following +predefined instantiations of this generic package are available: + +@table @code +@item Short_Float +@code{Short_Float_Wide_Wide_Text_IO} +@item Float +@code{Float_Wide_Wide_Text_IO} +@item Long_Float +@code{Long_Float_Wide_Wide_Text_IO} +@end table + +@item Ada.Wide_Wide_Text_IO.Integer_IO +Provides input-output facilities for integer types. The following +predefined instantiations of this generic package are available: + +@table @code +@item Short_Short_Integer +@code{Ada.Short_Short_Integer_Wide_Wide_Text_IO} +@item Short_Integer +@code{Ada.Short_Integer_Wide_Wide_Text_IO} +@item Integer +@code{Ada.Integer_Wide_Wide_Text_IO} +@item Long_Integer +@code{Ada.Long_Integer_Wide_Wide_Text_IO} +@item Long_Long_Integer +@code{Ada.Long_Long_Integer_Wide_Wide_Text_IO} +@end table + +@item Ada.Wide_Wide_Text_IO.Modular_IO +Provides input-output facilities for modular (unsigned) types + +@item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3) +This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the +external file supports wide character representations. + +@item Ada.Wide_Wide_Text_IO.Editing (F.3.4) +This package is similar to @code{Ada.Text_IO.Editing}, except that the +types are @code{Wide_Character} and @code{Wide_String} instead of +@code{Character} and @code{String}. + +@item Ada.Wide_Wide_Text_IO.Streams (A.12.3) +This package is similar to @code{Ada.Text_IO.Streams}, except that the +types are @code{Wide_Character} and @code{Wide_String} instead of +@code{Character} and @code{String}. +@end table + + + +@node The Implementation of Standard I/O +@chapter The Implementation of Standard I/O + +@noindent +GNAT implements all the required input-output facilities described in +A.6 through A.14. These sections of the Ada 95 reference manual describe the +required behavior of these packages from the Ada point of view, and if +you are writing a portable Ada program that does not need to know the +exact manner in which Ada maps to the outside world when it comes to +reading or writing external files, then you do not need to read this +chapter. As long as your files are all regular files (not pipes or +devices), and as long as you write and read the files only from Ada, the +description in the Ada 95 reference manual is sufficient. + +However, if you want to do input-output to pipes or other devices, such +as the keyboard or screen, or if the files you are dealing with are +either generated by some other language, or to be read by some other +language, then you need to know more about the details of how the GNAT +implementation of these input-output facilities behaves. + +In this chapter we give a detailed description of exactly how GNAT +interfaces to the file system. As always, the sources of the system are +available to you for answering questions at an even more detailed level, +but for most purposes the information in this chapter will suffice. + +Another reason that you may need to know more about how input-output is +implemented arises when you have a program written in mixed languages +where, for example, files are shared between the C and Ada sections of +the same program. GNAT provides some additional facilities, in the form +of additional child library packages, that facilitate this sharing, and +these additional facilities are also described in this chapter. + +@menu +* Standard I/O Packages:: +* FORM Strings:: +* Direct_IO:: +* Sequential_IO:: +* Text_IO:: +* Wide_Text_IO:: +* Wide_Wide_Text_IO:: +* Stream_IO:: +* Shared Files:: +* Open Modes:: +* Operations on C Streams:: +* Interfacing to C Streams:: +@end menu + +@node Standard I/O Packages +@section Standard I/O Packages + +@noindent +The Standard I/O packages described in Annex A for + +@itemize @bullet +@item +Ada.Text_IO +@item +Ada.Text_IO.Complex_IO +@item +Ada.Text_IO.Text_Streams +@item +Ada.Wide_Text_IO +@item +Ada.Wide_Text_IO.Complex_IO +@item +Ada.Wide_Text_IO.Text_Streams +@item +Ada.Wide_Wide_Text_IO +@item +Ada.Wide_Wide_Text_IO.Complex_IO +@item +Ada.Wide_Wide_Text_IO.Text_Streams +@item +Ada.Stream_IO +@item +Ada.Sequential_IO +@item +Ada.Direct_IO +@end itemize + +@noindent +are implemented using the C +library streams facility; where + +@itemize @bullet +@item +All files are opened using @code{fopen}. +@item +All input/output operations use @code{fread}/@code{fwrite}. +@end itemize + +@noindent +There is no internal buffering of any kind at the Ada library level. The only +buffering is that provided at the system level in the implementation of the +library routines that support streams. This facilitates shared use of these +streams by mixed language programs. Note though that system level buffering is +explicitly enabled at elaboration of the standard I/O packages and that can +have an impact on mixed language programs, in particular those using I/O before +calling the Ada elaboration routine (e.g. adainit). It is recommended to call +the Ada elaboration routine before performing any I/O or when impractical, +flush the common I/O streams and in particular Standard_Output before +elaborating the Ada code. + +@node FORM Strings +@section FORM Strings + +@noindent +The format of a FORM string in GNAT is: + +@smallexample +"keyword=value,keyword=value,@dots{},keyword=value" +@end smallexample + +@noindent +where letters may be in upper or lower case, and there are no spaces +between values. The order of the entries is not important. Currently +there are two keywords defined. + +@smallexample +SHARED=[YES|NO] +WCEM=[n|h|u|s\e] +@end smallexample + +@noindent +The use of these parameters is described later in this section. + +@node Direct_IO +@section Direct_IO + +@noindent +Direct_IO can only be instantiated for definite types. This is a +restriction of the Ada language, which means that the records are fixed +length (the length being determined by @code{@var{type}'Size}, rounded +up to the next storage unit boundary if necessary). + +The records of a Direct_IO file are simply written to the file in index +sequence, with the first record starting at offset zero, and subsequent +records following. There is no control information of any kind. For +example, if 32-bit integers are being written, each record takes +4-bytes, so the record at index @var{K} starts at offset +(@var{K}@minus{}1)*4. + +There is no limit on the size of Direct_IO files, they are expanded as +necessary to accommodate whatever records are written to the file. + +@node Sequential_IO +@section Sequential_IO + +@noindent +Sequential_IO may be instantiated with either a definite (constrained) +or indefinite (unconstrained) type. + +For the definite type case, the elements written to the file are simply +the memory images of the data values with no control information of any +kind. The resulting file should be read using the same type, no validity +checking is performed on input. + +For the indefinite type case, the elements written consist of two +parts. First is the size of the data item, written as the memory image +of a @code{Interfaces.C.size_t} value, followed by the memory image of +the data value. The resulting file can only be read using the same +(unconstrained) type. Normal assignment checks are performed on these +read operations, and if these checks fail, @code{Data_Error} is +raised. In particular, in the array case, the lengths must match, and in +the variant record case, if the variable for a particular read operation +is constrained, the discriminants must match. + +Note that it is not possible to use Sequential_IO to write variable +length array items, and then read the data back into different length +arrays. For example, the following will raise @code{Data_Error}: + +@smallexample @c ada + package IO is new Sequential_IO (String); + F : IO.File_Type; + S : String (1..4); + @dots{} + IO.Create (F) + IO.Write (F, "hello!") + IO.Reset (F, Mode=>In_File); + IO.Read (F, S); + Put_Line (S); + +@end smallexample + +@noindent +On some Ada implementations, this will print @code{hell}, but the program is +clearly incorrect, since there is only one element in the file, and that +element is the string @code{hello!}. + +In Ada 95, this kind of behavior can be legitimately achieved using +Stream_IO, and this is the preferred mechanism. In particular, the above +program fragment rewritten to use Stream_IO will work correctly. + +@node Text_IO +@section Text_IO + +@noindent +Text_IO files consist of a stream of characters containing the following +special control characters: + +@smallexample +LF (line feed, 16#0A#) Line Mark +FF (form feed, 16#0C#) Page Mark +@end smallexample + +@noindent +A canonical Text_IO file is defined as one in which the following +conditions are met: + +@itemize @bullet +@item +The character @code{LF} is used only as a line mark, i.e.@: to mark the end +of the line. + +@item +The character @code{FF} is used only as a page mark, i.e.@: to mark the +end of a page and consequently can appear only immediately following a +@code{LF} (line mark) character. + +@item +The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF} +(line mark, page mark). In the former case, the page mark is implicitly +assumed to be present. +@end itemize + +@noindent +A file written using Text_IO will be in canonical form provided that no +explicit @code{LF} or @code{FF} characters are written using @code{Put} +or @code{Put_Line}. There will be no @code{FF} character at the end of +the file unless an explicit @code{New_Page} operation was performed +before closing the file. + +A canonical Text_IO file that is a regular file, i.e.@: not a device or a +pipe, can be read using any of the routines in Text_IO@. The +semantics in this case will be exactly as defined in the Ada 95 reference +manual and all the routines in Text_IO are fully implemented. + +A text file that does not meet the requirements for a canonical Text_IO +file has one of the following: + +@itemize @bullet +@item +The file contains @code{FF} characters not immediately following a +@code{LF} character. + +@item +The file contains @code{LF} or @code{FF} characters written by +@code{Put} or @code{Put_Line}, which are not logically considered to be +line marks or page marks. + +@item +The file ends in a character other than @code{LF} or @code{FF}, +i.e.@: there is no explicit line mark or page mark at the end of the file. +@end itemize + +@noindent +Text_IO can be used to read such non-standard text files but subprograms +to do with line or page numbers do not have defined meanings. In +particular, a @code{FF} character that does not follow a @code{LF} +character may or may not be treated as a page mark from the point of +view of page and line numbering. Every @code{LF} character is considered +to end a line, and there is an implied @code{LF} character at the end of +the file. + +@menu +* Text_IO Stream Pointer Positioning:: +* Text_IO Reading and Writing Non-Regular Files:: +* Get_Immediate:: +* Treating Text_IO Files as Streams:: +* Text_IO Extensions:: +* Text_IO Facilities for Unbounded Strings:: +@end menu + +@node Text_IO Stream Pointer Positioning +@subsection Stream Pointer Positioning + +@noindent +@code{Ada.Text_IO} has a definition of current position for a file that +is being read. No internal buffering occurs in Text_IO, and usually the +physical position in the stream used to implement the file corresponds +to this logical position defined by Text_IO@. There are two exceptions: + +@itemize @bullet +@item +After a call to @code{End_Of_Page} that returns @code{True}, the stream +is positioned past the @code{LF} (line mark) that precedes the page +mark. Text_IO maintains an internal flag so that subsequent read +operations properly handle the logical position which is unchanged by +the @code{End_Of_Page} call. + +@item +After a call to @code{End_Of_File} that returns @code{True}, if the +Text_IO file was positioned before the line mark at the end of file +before the call, then the logical position is unchanged, but the stream +is physically positioned right at the end of file (past the line mark, +and past a possible page mark following the line mark. Again Text_IO +maintains internal flags so that subsequent read operations properly +handle the logical position. +@end itemize + +@noindent +These discrepancies have no effect on the observable behavior of +Text_IO, but if a single Ada stream is shared between a C program and +Ada program, or shared (using @samp{shared=yes} in the form string) +between two Ada files, then the difference may be observable in some +situations. + +@node Text_IO Reading and Writing Non-Regular Files +@subsection Reading and Writing Non-Regular Files + +@noindent +A non-regular file is a device (such as a keyboard), or a pipe. Text_IO +can be used for reading and writing. Writing is not affected and the +sequence of characters output is identical to the normal file case, but +for reading, the behavior of Text_IO is modified to avoid undesirable +look-ahead as follows: + +An input file that is not a regular file is considered to have no page +marks. Any @code{Ascii.FF} characters (the character normally used for a +page mark) appearing in the file are considered to be data +characters. In particular: + +@itemize @bullet +@item +@code{Get_Line} and @code{Skip_Line} do not test for a page mark +following a line mark. If a page mark appears, it will be treated as a +data character. + +@item +This avoids the need to wait for an extra character to be typed or +entered from the pipe to complete one of these operations. + +@item +@code{End_Of_Page} always returns @code{False} + +@item +@code{End_Of_File} will return @code{False} if there is a page mark at +the end of the file. +@end itemize + +@noindent +Output to non-regular files is the same as for regular files. Page marks +may be written to non-regular files using @code{New_Page}, but as noted +above they will not be treated as page marks on input if the output is +piped to another Ada program. + +Another important discrepancy when reading non-regular files is that the end +of file indication is not ``sticky''. If an end of file is entered, e.g.@: by +pressing the @key{EOT} key, +then end of file +is signaled once (i.e.@: the test @code{End_Of_File} +will yield @code{True}, or a read will +raise @code{End_Error}), but then reading can resume +to read data past that end of +file indication, until another end of file indication is entered. + +@node Get_Immediate +@subsection Get_Immediate +@cindex Get_Immediate + +@noindent +Get_Immediate returns the next character (including control characters) +from the input file. In particular, Get_Immediate will return LF or FF +characters used as line marks or page marks. Such operations leave the +file positioned past the control character, and it is thus not treated +as having its normal function. This means that page, line and column +counts after this kind of Get_Immediate call are set as though the mark +did not occur. In the case where a Get_Immediate leaves the file +positioned between the line mark and page mark (which is not normally +possible), it is undefined whether the FF character will be treated as a +page mark. + +@node Treating Text_IO Files as Streams +@subsection Treating Text_IO Files as Streams +@cindex Stream files + +@noindent +The package @code{Text_IO.Streams} allows a Text_IO file to be treated +as a stream. Data written to a Text_IO file in this stream mode is +binary data. If this binary data contains bytes 16#0A# (@code{LF}) or +16#0C# (@code{FF}), the resulting file may have non-standard +format. Similarly if read operations are used to read from a Text_IO +file treated as a stream, then @code{LF} and @code{FF} characters may be +skipped and the effect is similar to that described above for +@code{Get_Immediate}. + +@node Text_IO Extensions +@subsection Text_IO Extensions +@cindex Text_IO extensions + +@noindent +A package GNAT.IO_Aux in the GNAT library provides some useful extensions +to the standard @code{Text_IO} package: + +@itemize @bullet +@item function File_Exists (Name : String) return Boolean; +Determines if a file of the given name exists. + +@item function Get_Line return String; +Reads a string from the standard input file. The value returned is exactly +the length of the line that was read. + +@item function Get_Line (File : Ada.Text_IO.File_Type) return String; +Similar, except that the parameter File specifies the file from which +the string is to be read. + +@end itemize + +@node Text_IO Facilities for Unbounded Strings +@subsection Text_IO Facilities for Unbounded Strings +@cindex Text_IO for unbounded strings +@cindex Unbounded_String, Text_IO operations + +@noindent +The package @code{Ada.Strings.Unbounded.Text_IO} +in library files @code{a-suteio.ads/adb} contains some GNAT-specific +subprograms useful for Text_IO operations on unbounded strings: + +@itemize @bullet + +@item function Get_Line (File : File_Type) return Unbounded_String; +Reads a line from the specified file +and returns the result as an unbounded string. + +@item procedure Put (File : File_Type; U : Unbounded_String); +Writes the value of the given unbounded string to the specified file +Similar to the effect of +@code{Put (To_String (U))} except that an extra copy is avoided. + +@item procedure Put_Line (File : File_Type; U : Unbounded_String); +Writes the value of the given unbounded string to the specified file, +followed by a @code{New_Line}. +Similar to the effect of @code{Put_Line (To_String (U))} except +that an extra copy is avoided. +@end itemize + +@noindent +In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} +and is optional. If the parameter is omitted, then the standard input or +output file is referenced as appropriate. + +The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library +files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended +@code{Wide_Text_IO} functionality for unbounded wide strings. + +The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library +files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended +@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. + +@node Wide_Text_IO +@section Wide_Text_IO + +@noindent +@code{Wide_Text_IO} is similar in most respects to Text_IO, except that +both input and output files may contain special sequences that represent +wide character values. The encoding scheme for a given file may be +specified using a FORM parameter: + +@smallexample +WCEM=@var{x} +@end smallexample + +@noindent +as part of the FORM string (WCEM = wide character encoding method), +where @var{x} is one of the following characters + +@table @samp +@item h +Hex ESC encoding +@item u +Upper half encoding +@item s +Shift-JIS encoding +@item e +EUC Encoding +@item 8 +UTF-8 encoding +@item b +Brackets encoding +@end table + +@noindent +The encoding methods match those that +can be used in a source +program, but there is no requirement that the encoding method used for +the source program be the same as the encoding method used for files, +and different files may use different encoding methods. + +The default encoding method for the standard files, and for opened files +for which no WCEM parameter is given in the FORM string matches the +wide character encoding specified for the main program (the default +being brackets encoding if no coding method was specified with -gnatW). + +@table @asis +@item Hex Coding +In this encoding, a wide character is represented by a five character +sequence: + +@smallexample +ESC a b c d +@end smallexample + +@noindent +where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal +characters (using upper case letters) of the wide character code. For +example, ESC A345 is used to represent the wide character with code +16#A345#. This scheme is compatible with use of the full +@code{Wide_Character} set. + +@item Upper Half Coding +The wide character with encoding 16#abcd#, where the upper bit is on +(i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and +16#cd#. The second byte may never be a format control character, but is +not required to be in the upper half. This method can be also used for +shift-JIS or EUC where the internal coding matches the external coding. + +@item Shift JIS Coding +A wide character is represented by a two character sequence 16#ab# and +16#cd#, with the restrictions described for upper half encoding as +described above. The internal character code is the corresponding JIS +character according to the standard algorithm for Shift-JIS +conversion. Only characters defined in the JIS code set table can be +used with this encoding method. + +@item EUC Coding +A wide character is represented by a two character sequence 16#ab# and +16#cd#, with both characters being in the upper half. The internal +character code is the corresponding JIS character according to the EUC +encoding algorithm. Only characters defined in the JIS code set table +can be used with this encoding method. + +@item UTF-8 Coding +A wide character is represented using +UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO +10646-1/Am.2. Depending on the character value, the representation +is a one, two, or three byte sequence: + +@smallexample +16#0000#-16#007f#: 2#0xxxxxxx# +16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# +16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# +@end smallexample + +@noindent +where the xxx bits correspond to the left-padded bits of the +16-bit character value. Note that all lower half ASCII characters +are represented as ASCII bytes and all upper half characters and +other wide characters are represented as sequences of upper-half +(The full UTF-8 scheme allows for encoding 31-bit characters as +6-byte sequences, but in this implementation, all UTF-8 sequences +of four or more bytes length will raise a Constraint_Error, as +will all invalid UTF-8 sequences.) + +@item Brackets Coding +In this encoding, a wide character is represented by the following eight +character sequence: + +@smallexample +[ " a b c d " ] +@end smallexample + +@noindent +where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal +characters (using uppercase letters) of the wide character code. For +example, @code{["A345"]} is used to represent the wide character with code +@code{16#A345#}. +This scheme is compatible with use of the full Wide_Character set. +On input, brackets coding can also be used for upper half characters, +e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation +is only used for wide characters with a code greater than @code{16#FF#}. + +@end table + +@noindent +For the coding schemes other than Hex and Brackets encoding, +not all wide character +values can be represented. An attempt to output a character that cannot +be represented using the encoding scheme for the file causes +Constraint_Error to be raised. An invalid wide character sequence on +input also causes Constraint_Error to be raised. + +@menu +* Wide_Text_IO Stream Pointer Positioning:: +* Wide_Text_IO Reading and Writing Non-Regular Files:: +@end menu + +@node Wide_Text_IO Stream Pointer Positioning +@subsection Stream Pointer Positioning + +@noindent +@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling +of stream pointer positioning (@pxref{Text_IO}). There is one additional +case: + +If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the +normal lower ASCII set (i.e.@: a character in the range: + +@smallexample @c ada +Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) +@end smallexample + +@noindent +then although the logical position of the file pointer is unchanged by +the @code{Look_Ahead} call, the stream is physically positioned past the +wide character sequence. Again this is to avoid the need for buffering +or backup, and all @code{Wide_Text_IO} routines check the internal +indication that this situation has occurred so that this is not visible +to a normal program using @code{Wide_Text_IO}. However, this discrepancy +can be observed if the wide text file shares a stream with another file. + +@node Wide_Text_IO Reading and Writing Non-Regular Files +@subsection Reading and Writing Non-Regular Files + +@noindent +As in the case of Text_IO, when a non-regular file is read, it is +assumed that the file contains no page marks (any form characters are +treated as data characters), and @code{End_Of_Page} always returns +@code{False}. Similarly, the end of file indication is not sticky, so +it is possible to read beyond an end of file. + +@node Wide_Wide_Text_IO +@section Wide_Wide_Text_IO + +@noindent +@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that +both input and output files may contain special sequences that represent +wide wide character values. The encoding scheme for a given file may be +specified using a FORM parameter: + +@smallexample +WCEM=@var{x} +@end smallexample + +@noindent +as part of the FORM string (WCEM = wide character encoding method), +where @var{x} is one of the following characters + +@table @samp +@item h +Hex ESC encoding +@item u +Upper half encoding +@item s +Shift-JIS encoding +@item e +EUC Encoding +@item 8 +UTF-8 encoding +@item b +Brackets encoding +@end table + +@noindent +The encoding methods match those that +can be used in a source +program, but there is no requirement that the encoding method used for +the source program be the same as the encoding method used for files, +and different files may use different encoding methods. + +The default encoding method for the standard files, and for opened files +for which no WCEM parameter is given in the FORM string matches the +wide character encoding specified for the main program (the default +being brackets encoding if no coding method was specified with -gnatW). + +@table @asis + +@item UTF-8 Coding +A wide character is represented using +UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO +10646-1/Am.2. Depending on the character value, the representation +is a one, two, three, or four byte sequence: + +@smallexample +16#000000#-16#00007f#: 2#0xxxxxxx# +16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# +16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# +16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# +@end smallexample + +@noindent +where the xxx bits correspond to the left-padded bits of the +21-bit character value. Note that all lower half ASCII characters +are represented as ASCII bytes and all upper half characters and +other wide characters are represented as sequences of upper-half +characters. + +@item Brackets Coding +In this encoding, a wide wide character is represented by the following eight +character sequence if is in wide character range + +@smallexample +[ " a b c d " ] +@end smallexample + +and by the following ten character sequence if not + +@smallexample +[ " a b c d e f " ] +@end smallexample + +@noindent +where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} +are the four or six hexadecimal +characters (using uppercase letters) of the wide wide character code. For +example, @code{["01A345"]} is used to represent the wide wide character +with code @code{16#01A345#}. + +This scheme is compatible with use of the full Wide_Wide_Character set. +On input, brackets coding can also be used for upper half characters, +e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation +is only used for wide characters with a code greater than @code{16#FF#}. + +@end table + +@noindent +If is also possible to use the other Wide_Character encoding methods, +such as Shift-JIS, but the other schemes cannot support the full range +of wide wide characters. +An attempt to output a character that cannot +be represented using the encoding scheme for the file causes +Constraint_Error to be raised. An invalid wide character sequence on +input also causes Constraint_Error to be raised. + +@menu +* Wide_Wide_Text_IO Stream Pointer Positioning:: +* Wide_Wide_Text_IO Reading and Writing Non-Regular Files:: +@end menu + +@node Wide_Wide_Text_IO Stream Pointer Positioning +@subsection Stream Pointer Positioning + +@noindent +@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling +of stream pointer positioning (@pxref{Text_IO}). There is one additional +case: + +If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the +normal lower ASCII set (i.e.@: a character in the range: + +@smallexample @c ada +Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) +@end smallexample + +@noindent +then although the logical position of the file pointer is unchanged by +the @code{Look_Ahead} call, the stream is physically positioned past the +wide character sequence. Again this is to avoid the need for buffering +or backup, and all @code{Wide_Wide_Text_IO} routines check the internal +indication that this situation has occurred so that this is not visible +to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy +can be observed if the wide text file shares a stream with another file. + +@node Wide_Wide_Text_IO Reading and Writing Non-Regular Files +@subsection Reading and Writing Non-Regular Files + +@noindent +As in the case of Text_IO, when a non-regular file is read, it is +assumed that the file contains no page marks (any form characters are +treated as data characters), and @code{End_Of_Page} always returns +@code{False}. Similarly, the end of file indication is not sticky, so +it is possible to read beyond an end of file. + +@node Stream_IO +@section Stream_IO + +@noindent +A stream file is a sequence of bytes, where individual elements are +written to the file as described in the Ada 95 reference manual. The type +@code{Stream_Element} is simply a byte. There are two ways to read or +write a stream file. + +@itemize @bullet +@item +The operations @code{Read} and @code{Write} directly read or write a +sequence of stream elements with no control information. + +@item +The stream attributes applied to a stream file transfer data in the +manner described for stream attributes. +@end itemize + +@node Shared Files +@section Shared Files + +@noindent +Section A.14 of the Ada 95 Reference Manual allows implementations to +provide a wide variety of behavior if an attempt is made to access the +same external file with two or more internal files. + +To provide a full range of functionality, while at the same time +minimizing the problems of portability caused by this implementation +dependence, GNAT handles file sharing as follows: + +@itemize @bullet +@item +In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt +to open two or more files with the same full name is considered an error +and is not supported. The exception @code{Use_Error} will be +raised. Note that a file that is not explicitly closed by the program +remains open until the program terminates. + +@item +If the form parameter @samp{shared=no} appears in the form string, the +file can be opened or created with its own separate stream identifier, +regardless of whether other files sharing the same external file are +opened. The exact effect depends on how the C stream routines handle +multiple accesses to the same external files using separate streams. + +@item +If the form parameter @samp{shared=yes} appears in the form string for +each of two or more files opened using the same full name, the same +stream is shared between these files, and the semantics are as described +in Ada 95 Reference Manual, Section A.14. +@end itemize + +@noindent +When a program that opens multiple files with the same name is ported +from another Ada compiler to GNAT, the effect will be that +@code{Use_Error} is raised. + +The documentation of the original compiler and the documentation of the +program should then be examined to determine if file sharing was +expected, and @samp{shared=@var{xxx}} parameters added to @code{Open} +and @code{Create} calls as required. + +When a program is ported from GNAT to some other Ada compiler, no +special attention is required unless the @samp{shared=@var{xxx}} form +parameter is used in the program. In this case, you must examine the +documentation of the new compiler to see if it supports the required +file sharing semantics, and form strings modified appropriately. Of +course it may be the case that the program cannot be ported if the +target compiler does not support the required functionality. The best +approach in writing portable code is to avoid file sharing (and hence +the use of the @samp{shared=@var{xxx}} parameter in the form string) +completely. + +One common use of file sharing in Ada 83 is the use of instantiations of +Sequential_IO on the same file with different types, to achieve +heterogeneous input-output. Although this approach will work in GNAT if +@samp{shared=yes} is specified, it is preferable in Ada 95 to use Stream_IO +for this purpose (using the stream attributes) + +@node Open Modes +@section Open Modes + +@noindent +@code{Open} and @code{Create} calls result in a call to @code{fopen} +using the mode shown in the following table: + +@sp 2 +@center @code{Open} and @code{Create} Call Modes +@smallexample + @b{OPEN } @b{CREATE} +Append_File "r+" "w+" +In_File "r" "w+" +Out_File (Direct_IO) "r+" "w" +Out_File (all other cases) "w" "w" +Inout_File "r+" "w+" +@end smallexample + +@noindent +If text file translation is required, then either @samp{b} or @samp{t} +is added to the mode, depending on the setting of Text. Text file +translation refers to the mapping of CR/LF sequences in an external file +to LF characters internally. This mapping only occurs in DOS and +DOS-like systems, and is not relevant to other systems. + +A special case occurs with Stream_IO@. As shown in the above table, the +file is initially opened in @samp{r} or @samp{w} mode for the +@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation +subsequently requires switching from reading to writing or vice-versa, +then the file is reopened in @samp{r+} mode to permit the required operation. + +@node Operations on C Streams +@section Operations on C Streams +The package @code{Interfaces.C_Streams} provides an Ada program with direct +access to the C library functions for operations on C streams: + +@smallexample @c adanocomment +package Interfaces.C_Streams is + -- Note: the reason we do not use the types that are in + -- Interfaces.C is that we want to avoid dragging in the + -- code in this unit if possible. + subtype chars is System.Address; + -- Pointer to null-terminated array of characters + subtype FILEs is System.Address; + -- Corresponds to the C type FILE* + subtype voids is System.Address; + -- Corresponds to the C type void* + subtype int is Integer; + subtype long is Long_Integer; + -- Note: the above types are subtypes deliberately, and it + -- is part of this spec that the above correspondences are + -- guaranteed. This means that it is legitimate to, for + -- example, use Integer instead of int. We provide these + -- synonyms for clarity, but in some cases it may be + -- convenient to use the underlying types (for example to + -- avoid an unnecessary dependency of a spec on the spec + -- of this unit). + type size_t is mod 2 ** Standard'Address_Size; + NULL_Stream : constant FILEs; + -- Value returned (NULL in C) to indicate an + -- fdopen/fopen/tmpfile error + ---------------------------------- + -- Constants Defined in stdio.h -- + ---------------------------------- + EOF : constant int; + -- Used by a number of routines to indicate error or + -- end of file + IOFBF : constant int; + IOLBF : constant int; + IONBF : constant int; + -- Used to indicate buffering mode for setvbuf call + SEEK_CUR : constant int; + SEEK_END : constant int; + SEEK_SET : constant int; + -- Used to indicate origin for fseek call + function stdin return FILEs; + function stdout return FILEs; + function stderr return FILEs; + -- Streams associated with standard files + -------------------------- + -- Standard C functions -- + -------------------------- + -- The functions selected below are ones that are + -- available in DOS, OS/2, UNIX and Xenix (but not + -- necessarily in ANSI C). These are very thin interfaces + -- which copy exactly the C headers. For more + -- documentation on these functions, see the Microsoft C + -- "Run-Time Library Reference" (Microsoft Press, 1990, + -- ISBN 1-55615-225-6), which includes useful information + -- on system compatibility. + procedure clearerr (stream : FILEs); + function fclose (stream : FILEs) return int; + function fdopen (handle : int; mode : chars) return FILEs; + function feof (stream : FILEs) return int; + function ferror (stream : FILEs) return int; + function fflush (stream : FILEs) return int; + function fgetc (stream : FILEs) return int; + function fgets (strng : chars; n : int; stream : FILEs) + return chars; + function fileno (stream : FILEs) return int; + function fopen (filename : chars; Mode : chars) + return FILEs; + -- Note: to maintain target independence, use + -- text_translation_required, a boolean variable defined in + -- a-sysdep.c to deal with the target dependent text + -- translation requirement. If this variable is set, + -- then b/t should be appended to the standard mode + -- argument to set the text translation mode off or on + -- as required. + function fputc (C : int; stream : FILEs) return int; + function fputs (Strng : chars; Stream : FILEs) return int; + function fread + (buffer : voids; + size : size_t; + count : size_t; + stream : FILEs) + return size_t; + function freopen + (filename : chars; + mode : chars; + stream : FILEs) + return FILEs; + function fseek + (stream : FILEs; + offset : long; + origin : int) + return int; + function ftell (stream : FILEs) return long; + function fwrite + (buffer : voids; + size : size_t; + count : size_t; + stream : FILEs) + return size_t; + function isatty (handle : int) return int; + procedure mktemp (template : chars); + -- The return value (which is just a pointer to template) + -- is discarded + procedure rewind (stream : FILEs); + function rmtmp return int; + function setvbuf + (stream : FILEs; + buffer : chars; + mode : int; + size : size_t) + return int; + + function tmpfile return FILEs; + function ungetc (c : int; stream : FILEs) return int; + function unlink (filename : chars) return int; + --------------------- + -- Extra functions -- + --------------------- + -- These functions supply slightly thicker bindings than + -- those above. They are derived from functions in the + -- C Run-Time Library, but may do a bit more work than + -- just directly calling one of the Library functions. + function is_regular_file (handle : int) return int; + -- Tests if given handle is for a regular file (result 1) + -- or for a non-regular file (pipe or device, result 0). + --------------------------------- + -- Control of Text/Binary Mode -- + --------------------------------- + -- If text_translation_required is true, then the following + -- functions may be used to dynamically switch a file from + -- binary to text mode or vice versa. These functions have + -- no effect if text_translation_required is false (i.e. in + -- normal UNIX mode). Use fileno to get a stream handle. + procedure set_binary_mode (handle : int); + procedure set_text_mode (handle : int); + ---------------------------- + -- Full Path Name support -- + ---------------------------- + procedure full_name (nam : chars; buffer : chars); + -- Given a NUL terminated string representing a file + -- name, returns in buffer a NUL terminated string + -- representing the full path name for the file name. + -- On systems where it is relevant the drive is also + -- part of the full path name. It is the responsibility + -- of the caller to pass an actual parameter for buffer + -- that is big enough for any full path name. Use + -- max_path_len given below as the size of buffer. + max_path_len : integer; + -- Maximum length of an allowable full path name on the + -- system, including a terminating NUL character. +end Interfaces.C_Streams; +@end smallexample + +@node Interfacing to C Streams +@section Interfacing to C Streams + +@noindent +The packages in this section permit interfacing Ada files to C Stream +operations. + +@smallexample @c ada + with Interfaces.C_Streams; + package Ada.Sequential_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Sequential_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Direct_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Direct_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Text_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Text_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Wide_Text_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Wide_Text_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Wide_Wide_Text_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Wide_Wide_Text_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Stream_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Stream_IO.C_Streams; +@end smallexample + +@noindent +In each of these six packages, the @code{C_Stream} function obtains the +@code{FILE} pointer from a currently opened Ada file. It is then +possible to use the @code{Interfaces.C_Streams} package to operate on +this stream, or the stream can be passed to a C program which can +operate on it directly. Of course the program is responsible for +ensuring that only appropriate sequences of operations are executed. + +One particular use of relevance to an Ada program is that the +@code{setvbuf} function can be used to control the buffering of the +stream used by an Ada file. In the absence of such a call the standard +default buffering is used. + +The @code{Open} procedures in these packages open a file giving an +existing C Stream instead of a file name. Typically this stream is +imported from a C program, allowing an Ada file to operate on an +existing C file. + +@node The GNAT Library +@chapter The GNAT Library + +@noindent +The GNAT library contains a number of general and special purpose packages. +It represents functionality that the GNAT developers have found useful, and +which is made available to GNAT users. The packages described here are fully +supported, and upwards compatibility will be maintained in future releases, +so you can use these facilities with the confidence that the same functionality +will be available in future releases. + +The chapter here simply gives a brief summary of the facilities available. +The full documentation is found in the spec file for the package. The full +sources of these library packages, including both spec and body, are provided +with all GNAT releases. For example, to find out the full specifications of +the SPITBOL pattern matching capability, including a full tutorial and +extensive examples, look in the @file{g-spipat.ads} file in the library. + +For each entry here, the package name (as it would appear in a @code{with} +clause) is given, followed by the name of the corresponding spec file in +parentheses. The packages are children in four hierarchies, @code{Ada}, +@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a +GNAT-specific hierarchy. + +Note that an application program should only use packages in one of these +four hierarchies if the package is defined in the Ada Reference Manual, +or is listed in this section of the GNAT Programmers Reference Manual. +All other units should be considered internal implementation units and +should not be directly @code{with}'ed by application code. The use of +a @code{with} statement that references one of these internal implementation +units makes an application potentially dependent on changes in versions +of GNAT, and will generate a warning message. + +@menu +* Ada.Characters.Latin_9 (a-chlat9.ads):: +* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: +* Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: +* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads):: +* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads):: +* Ada.Command_Line.Remove (a-colire.ads):: +* Ada.Command_Line.Environment (a-colien.ads):: +* Ada.Direct_IO.C_Streams (a-diocst.ads):: +* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: +* Ada.Exceptions.Traceback (a-exctra.ads):: +* Ada.Sequential_IO.C_Streams (a-siocst.ads):: +* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: +* Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: +* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: +* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads):: +* Ada.Text_IO.C_Streams (a-tiocst.ads):: +* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: +* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: +* GNAT.Altivec (g-altive.ads):: +* GNAT.Altivec.Conversions (g-altcon.ads):: +* GNAT.Altivec.Vector_Operations (g-alveop.ads):: +* GNAT.Altivec.Vector_Types (g-alvety.ads):: +* GNAT.Altivec.Vector_Views (g-alvevi.ads):: +* GNAT.Array_Split (g-arrspl.ads):: +* GNAT.AWK (g-awk.ads):: +* GNAT.Bounded_Buffers (g-boubuf.ads):: +* GNAT.Bounded_Mailboxes (g-boumai.ads):: +* GNAT.Bubble_Sort (g-bubsor.ads):: +* GNAT.Bubble_Sort_A (g-busora.ads):: +* GNAT.Bubble_Sort_G (g-busorg.ads):: +* GNAT.Calendar (g-calend.ads):: +* GNAT.Calendar.Time_IO (g-catiio.ads):: +* GNAT.CRC32 (g-crc32.ads):: +* GNAT.Case_Util (g-casuti.ads):: +* GNAT.CGI (g-cgi.ads):: +* GNAT.CGI.Cookie (g-cgicoo.ads):: +* GNAT.CGI.Debug (g-cgideb.ads):: +* GNAT.Command_Line (g-comlin.ads):: +* GNAT.Compiler_Version (g-comver.ads):: +* GNAT.Ctrl_C (g-ctrl_c.ads):: +* GNAT.Current_Exception (g-curexc.ads):: +* GNAT.Debug_Pools (g-debpoo.ads):: +* GNAT.Debug_Utilities (g-debuti.ads):: +* GNAT.Directory_Operations (g-dirope.ads):: +* GNAT.Dynamic_HTables (g-dynhta.ads):: +* GNAT.Dynamic_Tables (g-dyntab.ads):: +* GNAT.Exception_Actions (g-excact.ads):: +* GNAT.Exception_Traces (g-exctra.ads):: +* GNAT.Exceptions (g-except.ads):: +* GNAT.Expect (g-expect.ads):: +* GNAT.Float_Control (g-flocon.ads):: +* GNAT.Heap_Sort (g-heasor.ads):: +* GNAT.Heap_Sort_A (g-hesora.ads):: +* GNAT.Heap_Sort_G (g-hesorg.ads):: +* GNAT.HTable (g-htable.ads):: +* GNAT.IO (g-io.ads):: +* GNAT.IO_Aux (g-io_aux.ads):: +* GNAT.Lock_Files (g-locfil.ads):: +* GNAT.MD5 (g-md5.ads):: +* GNAT.Memory_Dump (g-memdum.ads):: +* GNAT.Most_Recent_Exception (g-moreex.ads):: +* GNAT.OS_Lib (g-os_lib.ads):: +* GNAT.Perfect_Hash_Generators (g-pehage.ads):: +* GNAT.Regexp (g-regexp.ads):: +* GNAT.Registry (g-regist.ads):: +* GNAT.Regpat (g-regpat.ads):: +* GNAT.Secondary_Stack_Info (g-sestin.ads):: +* GNAT.Semaphores (g-semaph.ads):: +* GNAT.Signals (g-signal.ads):: +* GNAT.Sockets (g-socket.ads):: +* GNAT.Source_Info (g-souinf.ads):: +* GNAT.Spell_Checker (g-speche.ads):: +* GNAT.Spitbol.Patterns (g-spipat.ads):: +* GNAT.Spitbol (g-spitbo.ads):: +* GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: +* GNAT.Spitbol.Table_Integer (g-sptain.ads):: +* GNAT.Spitbol.Table_VString (g-sptavs.ads):: +* GNAT.Strings (g-string.ads):: +* GNAT.String_Split (g-strspl.ads):: +* GNAT.UTF_32 (g-utf_32.ads):: +* GNAT.Table (g-table.ads):: +* GNAT.Task_Lock (g-tasloc.ads):: +* GNAT.Threads (g-thread.ads):: +* GNAT.Traceback (g-traceb.ads):: +* GNAT.Traceback.Symbolic (g-trasym.ads):: +* GNAT.Wide_String_Split (g-wistsp.ads):: +* GNAT.Wide_Wide_String_Split (g-zistsp.ads):: +* Interfaces.C.Extensions (i-cexten.ads):: +* Interfaces.C.Streams (i-cstrea.ads):: +* Interfaces.CPP (i-cpp.ads):: +* Interfaces.Os2lib (i-os2lib.ads):: +* Interfaces.Os2lib.Errors (i-os2err.ads):: +* Interfaces.Os2lib.Synchronization (i-os2syn.ads):: +* Interfaces.Os2lib.Threads (i-os2thr.ads):: +* Interfaces.Packed_Decimal (i-pacdec.ads):: +* Interfaces.VxWorks (i-vxwork.ads):: +* Interfaces.VxWorks.IO (i-vxwoio.ads):: +* System.Address_Image (s-addima.ads):: +* System.Assertions (s-assert.ads):: +* System.Memory (s-memory.ads):: +* System.Partition_Interface (s-parint.ads):: +* System.Restrictions (s-restri.ads):: +* System.Rident (s-rident.ads):: +* System.Task_Info (s-tasinf.ads):: +* System.Wch_Cnv (s-wchcnv.ads):: +* System.Wch_Con (s-wchcon.ads):: +@end menu + +@node Ada.Characters.Latin_9 (a-chlat9.ads) +@section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) +@cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) +@cindex Latin_9 constants for Character + +@noindent +This child of @code{Ada.Characters} +provides a set of definitions corresponding to those in the +RM-defined package @code{Ada.Characters.Latin_1} but with the +few modifications required for @code{Latin-9} +The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3(27)). + +@node Ada.Characters.Wide_Latin_1 (a-cwila1.ads) +@section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) +@cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) +@cindex Latin_1 constants for Wide_Character + +@noindent +This child of @code{Ada.Characters} +provides a set of definitions corresponding to those in the +RM-defined package @code{Ada.Characters.Latin_1} but with the +types of the constants being @code{Wide_Character} +instead of @code{Character}. The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3(27)). + +@node Ada.Characters.Wide_Latin_9 (a-cwila9.ads) +@section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) +@cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) +@cindex Latin_9 constants for Wide_Character + +@noindent +This child of @code{Ada.Characters} +provides a set of definitions corresponding to those in the +GNAT defined package @code{Ada.Characters.Latin_9} but with the +types of the constants being @code{Wide_Character} +instead of @code{Character}. The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3(27)). + +@node Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads) +@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads}) +@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads}) +@cindex Latin_1 constants for Wide_Wide_Character + +@noindent +This child of @code{Ada.Characters} +provides a set of definitions corresponding to those in the +RM-defined package @code{Ada.Characters.Latin_1} but with the +types of the constants being @code{Wide_Wide_Character} +instead of @code{Character}. The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3(27)). + +@node Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads) +@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads}) +@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads}) +@cindex Latin_9 constants for Wide_Wide_Character + +@noindent +This child of @code{Ada.Characters} +provides a set of definitions corresponding to those in the +GNAT defined package @code{Ada.Characters.Latin_9} but with the +types of the constants being @code{Wide_Wide_Character} +instead of @code{Character}. The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3(27)). + +@node Ada.Command_Line.Remove (a-colire.ads) +@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) +@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) +@cindex Removing command line arguments +@cindex Command line, argument removal + +@noindent +This child of @code{Ada.Command_Line} +provides a mechanism for logically removing +arguments from the argument list. Once removed, an argument is not visible +to further calls on the subprograms in @code{Ada.Command_Line} will not +see the removed argument. + +@node Ada.Command_Line.Environment (a-colien.ads) +@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) +@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) +@cindex Environment entries + +@noindent +This child of @code{Ada.Command_Line} +provides a mechanism for obtaining environment values on systems +where this concept makes sense. + +@node Ada.Direct_IO.C_Streams (a-diocst.ads) +@section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) +@cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) +@cindex C Streams, Interfacing with Direct_IO + +@noindent +This package provides subprograms that allow interfacing between +C streams and @code{Direct_IO}. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +@node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) +@section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) +@cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) +@cindex Null_Occurrence, testing for + +@noindent +This child subprogram provides a way of testing for the null +exception occurrence (@code{Null_Occurrence}) without raising +an exception. + +@node Ada.Exceptions.Traceback (a-exctra.ads) +@section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) +@cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) +@cindex Traceback for Exception Occurrence + +@noindent +This child package provides the subprogram (@code{Tracebacks}) to +give a traceback array of addresses based on an exception +occurrence. + +@node Ada.Sequential_IO.C_Streams (a-siocst.ads) +@section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) +@cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) +@cindex C Streams, Interfacing with Sequential_IO + +@noindent +This package provides subprograms that allow interfacing between +C streams and @code{Sequential_IO}. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +@node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) +@section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) +@cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) +@cindex C Streams, Interfacing with Stream_IO + +@noindent +This package provides subprograms that allow interfacing between +C streams and @code{Stream_IO}. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +@node Ada.Strings.Unbounded.Text_IO (a-suteio.ads) +@section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) +@cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) +@cindex @code{Unbounded_String}, IO support +@cindex @code{Text_IO}, extensions for unbounded strings + +@noindent +This package provides subprograms for Text_IO for unbounded +strings, avoiding the necessity for an intermediate operation +with ordinary strings. + +@node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) +@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) +@cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) +@cindex @code{Unbounded_Wide_String}, IO support +@cindex @code{Text_IO}, extensions for unbounded wide strings + +@noindent +This package provides subprograms for Text_IO for unbounded +wide strings, avoiding the necessity for an intermediate operation +with ordinary wide strings. + +@node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) +@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads}) +@cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads}) +@cindex @code{Unbounded_Wide_Wide_String}, IO support +@cindex @code{Text_IO}, extensions for unbounded wide wide strings + +@noindent +This package provides subprograms for Text_IO for unbounded +wide wide strings, avoiding the necessity for an intermediate operation +with ordinary wide wide strings. + +@node Ada.Text_IO.C_Streams (a-tiocst.ads) +@section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) +@cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) +@cindex C Streams, Interfacing with @code{Text_IO} + +@noindent +This package provides subprograms that allow interfacing between +C streams and @code{Text_IO}. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +@node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) +@section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) +@cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) +@cindex C Streams, Interfacing with @code{Wide_Text_IO} + +@noindent +This package provides subprograms that allow interfacing between +C streams and @code{Wide_Text_IO}. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +@node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) +@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads}) +@cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads}) +@cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO} + +@noindent +This package provides subprograms that allow interfacing between +C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +@node GNAT.Altivec (g-altive.ads) +@section @code{GNAT.Altivec} (@file{g-altive.ads}) +@cindex @code{GNAT.Altivec} (@file{g-altive.ads}) +@cindex AltiVec + +@noindent +This is the root package of the GNAT AltiVec binding. It provides +definitions of constants and types common to all the versions of the +binding. + +@node GNAT.Altivec.Conversions (g-altcon.ads) +@section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads}) +@cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads}) +@cindex AltiVec + +@noindent +This package provides the Vector/View conversion routines. + +@node GNAT.Altivec.Vector_Operations (g-alveop.ads) +@section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads}) +@cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads}) +@cindex AltiVec + +@noindent +This package exposes the Ada interface to the AltiVec operations on +vector objects. A soft emulation is included by default in the GNAT +library. The hard binding is provided as a separate package. This unit +is common to both bindings. + +@node GNAT.Altivec.Vector_Types (g-alvety.ads) +@section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads}) +@cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads}) +@cindex AltiVec + +@noindent +This package exposes the various vector types part of the Ada binding +to AltiVec facilities. + +@node GNAT.Altivec.Vector_Views (g-alvevi.ads) +@section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads}) +@cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads}) +@cindex AltiVec + +@noindent +This package provides public 'View' data types from/to which private +vector representations can be converted via +GNAT.Altivec.Conversions. This allows convenient access to individual +vector elements and provides a simple way to initialize vector +objects. + +@node GNAT.Array_Split (g-arrspl.ads) +@section @code{GNAT.Array_Split} (@file{g-arrspl.ads}) +@cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads}) +@cindex Array splitter + +@noindent +Useful array-manipulation routines: given a set of separators, split +an array wherever the separators appear, and provide direct access +to the resulting slices. + +@node GNAT.AWK (g-awk.ads) +@section @code{GNAT.AWK} (@file{g-awk.ads}) +@cindex @code{GNAT.AWK} (@file{g-awk.ads}) +@cindex Parsing +@cindex AWK + +@noindent +Provides AWK-like parsing functions, with an easy interface for parsing one +or more files containing formatted data. The file is viewed as a database +where each record is a line and a field is a data element in this line. + +@node GNAT.Bounded_Buffers (g-boubuf.ads) +@section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) +@cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) +@cindex Parsing +@cindex Bounded Buffers + +@noindent +Provides a concurrent generic bounded buffer abstraction. Instances are +useful directly or as parts of the implementations of other abstractions, +such as mailboxes. + +@node GNAT.Bounded_Mailboxes (g-boumai.ads) +@section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) +@cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) +@cindex Parsing +@cindex Mailboxes + +@noindent +Provides a thread-safe asynchronous intertask mailbox communication facility. + +@node GNAT.Bubble_Sort (g-bubsor.ads) +@section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) +@cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) +@cindex Sorting +@cindex Bubble sort + +@noindent +Provides a general implementation of bubble sort usable for sorting arbitrary +data items. Exchange and comparison procedures are provided by passing +access-to-procedure values. + +@node GNAT.Bubble_Sort_A (g-busora.ads) +@section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) +@cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) +@cindex Sorting +@cindex Bubble sort + +@noindent +Provides a general implementation of bubble sort usable for sorting arbitrary +data items. Move and comparison procedures are provided by passing +access-to-procedure values. This is an older version, retained for +compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. + +@node GNAT.Bubble_Sort_G (g-busorg.ads) +@section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) +@cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) +@cindex Sorting +@cindex Bubble sort + +@noindent +Similar to @code{Bubble_Sort_A} except that the move and sorting procedures +are provided as generic parameters, this improves efficiency, especially +if the procedures can be inlined, at the expense of duplicating code for +multiple instantiations. + +@node GNAT.Calendar (g-calend.ads) +@section @code{GNAT.Calendar} (@file{g-calend.ads}) +@cindex @code{GNAT.Calendar} (@file{g-calend.ads}) +@cindex @code{Calendar} + +@noindent +Extends the facilities provided by @code{Ada.Calendar} to include handling +of days of the week, an extended @code{Split} and @code{Time_Of} capability. +Also provides conversion of @code{Ada.Calendar.Time} values to and from the +C @code{timeval} format. + +@node GNAT.Calendar.Time_IO (g-catiio.ads) +@section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) +@cindex @code{Calendar} +@cindex Time +@cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) + +@node GNAT.CRC32 (g-crc32.ads) +@section @code{GNAT.CRC32} (@file{g-crc32.ads}) +@cindex @code{GNAT.CRC32} (@file{g-crc32.ads}) +@cindex CRC32 +@cindex Cyclic Redundancy Check + +@noindent +This package implements the CRC-32 algorithm. For a full description +of this algorithm see +``Computation of Cyclic Redundancy Checks via Table Look-Up'', +@cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013, +Aug.@: 1988. Sarwate, D.V@. + +@noindent +Provides an extended capability for formatted output of time values with +full user control over the format. Modeled on the GNU Date specification. + +@node GNAT.Case_Util (g-casuti.ads) +@section @code{GNAT.Case_Util} (@file{g-casuti.ads}) +@cindex @code{GNAT.Case_Util} (@file{g-casuti.ads}) +@cindex Casing utilities +@cindex Character handling (@code{GNAT.Case_Util}) + +@noindent +A set of simple routines for handling upper and lower casing of strings +without the overhead of the full casing tables +in @code{Ada.Characters.Handling}. + +@node GNAT.CGI (g-cgi.ads) +@section @code{GNAT.CGI} (@file{g-cgi.ads}) +@cindex @code{GNAT.CGI} (@file{g-cgi.ads}) +@cindex CGI (Common Gateway Interface) + +@noindent +This is a package for interfacing a GNAT program with a Web server via the +Common Gateway Interface (CGI)@. Basically this package parses the CGI +parameters, which are a set of key/value pairs sent by the Web server. It +builds a table whose index is the key and provides some services to deal +with this table. + +@node GNAT.CGI.Cookie (g-cgicoo.ads) +@section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) +@cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) +@cindex CGI (Common Gateway Interface) cookie support +@cindex Cookie support in CGI + +@noindent +This is a package to interface a GNAT program with a Web server via the +Common Gateway Interface (CGI). It exports services to deal with Web +cookies (piece of information kept in the Web client software). + +@node GNAT.CGI.Debug (g-cgideb.ads) +@section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) +@cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) +@cindex CGI (Common Gateway Interface) debugging + +@noindent +This is a package to help debugging CGI (Common Gateway Interface) +programs written in Ada. + +@node GNAT.Command_Line (g-comlin.ads) +@section @code{GNAT.Command_Line} (@file{g-comlin.ads}) +@cindex @code{GNAT.Command_Line} (@file{g-comlin.ads}) +@cindex Command line + +@noindent +Provides a high level interface to @code{Ada.Command_Line} facilities, +including the ability to scan for named switches with optional parameters +and expand file names using wild card notations. + +@node GNAT.Compiler_Version (g-comver.ads) +@section @code{GNAT.Compiler_Version} (@file{g-comver.ads}) +@cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads}) +@cindex Compiler Version +@cindex Version, of compiler + +@noindent +Provides a routine for obtaining the version of the compiler used to +compile the program. More accurately this is the version of the binder +used to bind the program (this will normally be the same as the version +of the compiler if a consistent tool set is used to compile all units +of a partition). + +@node GNAT.Ctrl_C (g-ctrl_c.ads) +@section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) +@cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) +@cindex Interrupt + +@noindent +Provides a simple interface to handle Ctrl-C keyboard events. + +@node GNAT.Current_Exception (g-curexc.ads) +@section @code{GNAT.Current_Exception} (@file{g-curexc.ads}) +@cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads}) +@cindex Current exception +@cindex Exception retrieval + +@noindent +Provides access to information on the current exception that has been raised +without the need for using the Ada-95 exception choice parameter specification +syntax. This is particularly useful in simulating typical facilities for +obtaining information about exceptions provided by Ada 83 compilers. + +@node GNAT.Debug_Pools (g-debpoo.ads) +@section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) +@cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) +@cindex Debugging +@cindex Debug pools +@cindex Memory corruption debugging + +@noindent +Provide a debugging storage pools that helps tracking memory corruption +problems. See section ``Finding memory problems with GNAT Debug Pool'' in +the @cite{GNAT User's Guide}. + +@node GNAT.Debug_Utilities (g-debuti.ads) +@section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) +@cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) +@cindex Debugging + +@noindent +Provides a few useful utilities for debugging purposes, including conversion +to and from string images of address values. Supports both C and Ada formats +for hexadecimal literals. + +@node GNAT.Directory_Operations (g-dirope.ads) +@section @code{GNAT.Directory_Operations} (g-dirope.ads) +@cindex @code{GNAT.Directory_Operations} (g-dirope.ads) +@cindex Directory operations + +@noindent +Provides a set of routines for manipulating directories, including changing +the current directory, making new directories, and scanning the files in a +directory. + +@node GNAT.Dynamic_HTables (g-dynhta.ads) +@section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) +@cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) +@cindex Hash tables + +@noindent +A generic implementation of hash tables that can be used to hash arbitrary +data. Provided in two forms, a simple form with built in hash functions, +and a more complex form in which the hash function is supplied. + +@noindent +This package provides a facility similar to that of @code{GNAT.HTable}, +except that this package declares a type that can be used to define +dynamic instances of the hash table, while an instantiation of +@code{GNAT.HTable} creates a single instance of the hash table. + +@node GNAT.Dynamic_Tables (g-dyntab.ads) +@section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) +@cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) +@cindex Table implementation +@cindex Arrays, extendable + +@noindent +A generic package providing a single dimension array abstraction where the +length of the array can be dynamically modified. + +@noindent +This package provides a facility similar to that of @code{GNAT.Table}, +except that this package declares a type that can be used to define +dynamic instances of the table, while an instantiation of +@code{GNAT.Table} creates a single instance of the table type. + +@node GNAT.Exception_Actions (g-excact.ads) +@section @code{GNAT.Exception_Actions} (@file{g-excact.ads}) +@cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads}) +@cindex Exception actions + +@noindent +Provides callbacks when an exception is raised. Callbacks can be registered +for specific exceptions, or when any exception is raised. This +can be used for instance to force a core dump to ease debugging. + +@node GNAT.Exception_Traces (g-exctra.ads) +@section @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) +@cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) +@cindex Exception traces +@cindex Debugging + +@noindent +Provides an interface allowing to control automatic output upon exception +occurrences. + +@node GNAT.Exceptions (g-except.ads) +@section @code{GNAT.Exceptions} (@file{g-expect.ads}) +@cindex @code{GNAT.Exceptions} (@file{g-expect.ads}) +@cindex Exceptions, Pure +@cindex Pure packages, exceptions + +@noindent +Normally it is not possible to raise an exception with +a message from a subprogram in a pure package, since the +necessary types and subprograms are in @code{Ada.Exceptions} +which is not a pure unit. @code{GNAT.Exceptions} provides a +facility for getting around this limitation for a few +predefined exceptions, and for example allow raising +@code{Constraint_Error} with a message from a pure subprogram. + +@node GNAT.Expect (g-expect.ads) +@section @code{GNAT.Expect} (@file{g-expect.ads}) +@cindex @code{GNAT.Expect} (@file{g-expect.ads}) + +@noindent +Provides a set of subprograms similar to what is available +with the standard Tcl Expect tool. +It allows you to easily spawn and communicate with an external process. +You can send commands or inputs to the process, and compare the output +with some expected regular expression. Currently @code{GNAT.Expect} +is implemented on all native GNAT ports except for OpenVMS@. +It is not implemented for cross ports, and in particular is not +implemented for VxWorks or LynxOS@. + +@node GNAT.Float_Control (g-flocon.ads) +@section @code{GNAT.Float_Control} (@file{g-flocon.ads}) +@cindex @code{GNAT.Float_Control} (@file{g-flocon.ads}) +@cindex Floating-Point Processor + +@noindent +Provides an interface for resetting the floating-point processor into the +mode required for correct semantic operation in Ada. Some third party +library calls may cause this mode to be modified, and the Reset procedure +in this package can be used to reestablish the required mode. + +@node GNAT.Heap_Sort (g-heasor.ads) +@section @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) +@cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) +@cindex Sorting + +@noindent +Provides a general implementation of heap sort usable for sorting arbitrary +data items. Exchange and comparison procedures are provided by passing +access-to-procedure values. The algorithm used is a modified heap sort +that performs approximately N*log(N) comparisons in the worst case. + +@node GNAT.Heap_Sort_A (g-hesora.ads) +@section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) +@cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) +@cindex Sorting + +@noindent +Provides a general implementation of heap sort usable for sorting arbitrary +data items. Move and comparison procedures are provided by passing +access-to-procedure values. The algorithm used is a modified heap sort +that performs approximately N*log(N) comparisons in the worst case. +This differs from @code{GNAT.Heap_Sort} in having a less convenient +interface, but may be slightly more efficient. + +@node GNAT.Heap_Sort_G (g-hesorg.ads) +@section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) +@cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) +@cindex Sorting + +@noindent +Similar to @code{Heap_Sort_A} except that the move and sorting procedures +are provided as generic parameters, this improves efficiency, especially +if the procedures can be inlined, at the expense of duplicating code for +multiple instantiations. + +@node GNAT.HTable (g-htable.ads) +@section @code{GNAT.HTable} (@file{g-htable.ads}) +@cindex @code{GNAT.HTable} (@file{g-htable.ads}) +@cindex Hash tables + +@noindent +A generic implementation of hash tables that can be used to hash arbitrary +data. Provides two approaches, one a simple static approach, and the other +allowing arbitrary dynamic hash tables. + +@node GNAT.IO (g-io.ads) +@section @code{GNAT.IO} (@file{g-io.ads}) +@cindex @code{GNAT.IO} (@file{g-io.ads}) +@cindex Simple I/O +@cindex Input/Output facilities + +@noindent +A simple preelaborable input-output package that provides a subset of +simple Text_IO functions for reading characters and strings from +Standard_Input, and writing characters, strings and integers to either +Standard_Output or Standard_Error. + +@node GNAT.IO_Aux (g-io_aux.ads) +@section @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) +@cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) +@cindex Text_IO +@cindex Input/Output facilities + +Provides some auxiliary functions for use with Text_IO, including a test +for whether a file exists, and functions for reading a line of text. + +@node GNAT.Lock_Files (g-locfil.ads) +@section @code{GNAT.Lock_Files} (@file{g-locfil.ads}) +@cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads}) +@cindex File locking +@cindex Locking using files + +@noindent +Provides a general interface for using files as locks. Can be used for +providing program level synchronization. + +@node GNAT.MD5 (g-md5.ads) +@section @code{GNAT.MD5} (@file{g-md5.ads}) +@cindex @code{GNAT.MD5} (@file{g-md5.ads}) +@cindex Message Digest MD5 + +@noindent +Implements the MD5 Message-Digest Algorithm as described in RFC 1321. + +@node GNAT.Memory_Dump (g-memdum.ads) +@section @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) +@cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) +@cindex Dump Memory + +@noindent +Provides a convenient routine for dumping raw memory to either the +standard output or standard error files. Uses GNAT.IO for actual +output. + +@node GNAT.Most_Recent_Exception (g-moreex.ads) +@section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) +@cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) +@cindex Exception, obtaining most recent + +@noindent +Provides access to the most recently raised exception. Can be used for +various logging purposes, including duplicating functionality of some +Ada 83 implementation dependent extensions. + +@node GNAT.OS_Lib (g-os_lib.ads) +@section @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) +@cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) +@cindex Operating System interface +@cindex Spawn capability + +@noindent +Provides a range of target independent operating system interface functions, +including time/date management, file operations, subprocess management, +including a portable spawn procedure, and access to environment variables +and error return codes. + +@node GNAT.Perfect_Hash_Generators (g-pehage.ads) +@section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads}) +@cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads}) +@cindex Hash functions + +@noindent +Provides a generator of static minimal perfect hash functions. No +collisions occur and each item can be retrieved from the table in one +probe (perfect property). The hash table size corresponds to the exact +size of the key set and no larger (minimal property). The key set has to +be know in advance (static property). The hash functions are also order +preserving. If w2 is inserted after w1 in the generator, their +hashcode are in the same order. These hashing functions are very +convenient for use with realtime applications. + +@node GNAT.Regexp (g-regexp.ads) +@section @code{GNAT.Regexp} (@file{g-regexp.ads}) +@cindex @code{GNAT.Regexp} (@file{g-regexp.ads}) +@cindex Regular expressions +@cindex Pattern matching + +@noindent +A simple implementation of regular expressions, using a subset of regular +expression syntax copied from familiar Unix style utilities. This is the +simples of the three pattern matching packages provided, and is particularly +suitable for ``file globbing'' applications. + +@node GNAT.Registry (g-regist.ads) +@section @code{GNAT.Registry} (@file{g-regist.ads}) +@cindex @code{GNAT.Registry} (@file{g-regist.ads}) +@cindex Windows Registry + +@noindent +This is a high level binding to the Windows registry. It is possible to +do simple things like reading a key value, creating a new key. For full +registry API, but at a lower level of abstraction, refer to the Win32.Winreg +package provided with the Win32Ada binding + +@node GNAT.Regpat (g-regpat.ads) +@section @code{GNAT.Regpat} (@file{g-regpat.ads}) +@cindex @code{GNAT.Regpat} (@file{g-regpat.ads}) +@cindex Regular expressions +@cindex Pattern matching + +@noindent +A complete implementation of Unix-style regular expression matching, copied +from the original V7 style regular expression library written in C by +Henry Spencer (and binary compatible with this C library). + +@node GNAT.Secondary_Stack_Info (g-sestin.ads) +@section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) +@cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) +@cindex Secondary Stack Info + +@noindent +Provide the capability to query the high water mark of the current task's +secondary stack. + +@node GNAT.Semaphores (g-semaph.ads) +@section @code{GNAT.Semaphores} (@file{g-semaph.ads}) +@cindex @code{GNAT.Semaphores} (@file{g-semaph.ads}) +@cindex Semaphores + +@noindent +Provides classic counting and binary semaphores using protected types. + +@node GNAT.Signals (g-signal.ads) +@section @code{GNAT.Signals} (@file{g-signal.ads}) +@cindex @code{GNAT.Signals} (@file{g-signal.ads}) +@cindex Signals + +@noindent +Provides the ability to manipulate the blocked status of signals on supported +targets. + +@node GNAT.Sockets (g-socket.ads) +@section @code{GNAT.Sockets} (@file{g-socket.ads}) +@cindex @code{GNAT.Sockets} (@file{g-socket.ads}) +@cindex Sockets + +@noindent +A high level and portable interface to develop sockets based applications. +This package is based on the sockets thin binding found in +@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented +on all native GNAT ports except for OpenVMS@. It is not implemented +for the LynxOS@ cross port. + +@node GNAT.Source_Info (g-souinf.ads) +@section @code{GNAT.Source_Info} (@file{g-souinf.ads}) +@cindex @code{GNAT.Source_Info} (@file{g-souinf.ads}) +@cindex Source Information + +@noindent +Provides subprograms that give access to source code information known at +compile time, such as the current file name and line number. + +@node GNAT.Spell_Checker (g-speche.ads) +@section @code{GNAT.Spell_Checker} (@file{g-speche.ads}) +@cindex @code{GNAT.Spell_Checker} (@file{g-speche.ads}) +@cindex Spell checking + +@noindent +Provides a function for determining whether one string is a plausible +near misspelling of another string. + +@node GNAT.Spitbol.Patterns (g-spipat.ads) +@section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) +@cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) +@cindex SPITBOL pattern matching +@cindex Pattern matching + +@noindent +A complete implementation of SNOBOL4 style pattern matching. This is the +most elaborate of the pattern matching packages provided. It fully duplicates +the SNOBOL4 dynamic pattern construction and matching capabilities, using the +efficient algorithm developed by Robert Dewar for the SPITBOL system. + +@node GNAT.Spitbol (g-spitbo.ads) +@section @code{GNAT.Spitbol} (@file{g-spitbo.ads}) +@cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads}) +@cindex SPITBOL interface + +@noindent +The top level package of the collection of SPITBOL-style functionality, this +package provides basic SNOBOL4 string manipulation functions, such as +Pad, Reverse, Trim, Substr capability, as well as a generic table function +useful for constructing arbitrary mappings from strings in the style of +the SNOBOL4 TABLE function. + +@node GNAT.Spitbol.Table_Boolean (g-sptabo.ads) +@section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) +@cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) +@cindex Sets of strings +@cindex SPITBOL Tables + +@noindent +A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} +for type @code{Standard.Boolean}, giving an implementation of sets of +string values. + +@node GNAT.Spitbol.Table_Integer (g-sptain.ads) +@section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) +@cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) +@cindex Integer maps +@cindex Maps +@cindex SPITBOL Tables + +@noindent +A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} +for type @code{Standard.Integer}, giving an implementation of maps +from string to integer values. + +@node GNAT.Spitbol.Table_VString (g-sptavs.ads) +@section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) +@cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) +@cindex String maps +@cindex Maps +@cindex SPITBOL Tables + +@noindent +A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for +a variable length string type, giving an implementation of general +maps from strings to strings. + +@node GNAT.Strings (g-string.ads) +@section @code{GNAT.Strings} (@file{g-string.ads}) +@cindex @code{GNAT.Strings} (@file{g-string.ads}) + +@noindent +Common String access types and related subprograms. Basically it +defines a string access and an array of string access types. + +@node GNAT.String_Split (g-strspl.ads) +@section @code{GNAT.String_Split} (@file{g-strspl.ads}) +@cindex @code{GNAT.String_Split} (@file{g-strspl.ads}) +@cindex String splitter + +@noindent +Useful string manipulation routines: given a set of separators, split +a string wherever the separators appear, and provide direct access +to the resulting slices. This package is instantiated from +@code{GNAT.Array_Split}. + +@node GNAT.UTF_32 (g-utf_32.ads) +@section @code{GNAT.UTF_32} (@file{g-table.ads}) +@cindex @code{GNAT.UTF_32} (@file{g-table.ads}) +@cindex Wide character codes + +@noindent +This is a package intended to be used in conjunction with the +@code{Wide_Character} type in Ada 95 and the +@code{Wide_Wide_Character} type in Ada 2005 (available +in @code{GNAT} in Ada 2005 mode). This package contains +Unicode categorization routines, as well as lexical +categorization routines corresponding to the Ada 2005 +lexical rules for identifiers and strings, and also a +lower case to upper case fold routine corresponding to +the Ada 2005 rules for identifier equivalence. + +@node GNAT.Table (g-table.ads) +@section @code{GNAT.Table} (@file{g-table.ads}) +@cindex @code{GNAT.Table} (@file{g-table.ads}) +@cindex Table implementation +@cindex Arrays, extendable + +@noindent +A generic package providing a single dimension array abstraction where the +length of the array can be dynamically modified. + +@noindent +This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, +except that this package declares a single instance of the table type, +while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be +used to define dynamic instances of the table. + +@node GNAT.Task_Lock (g-tasloc.ads) +@section @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) +@cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) +@cindex Task synchronization +@cindex Task locking +@cindex Locking + +@noindent +A very simple facility for locking and unlocking sections of code using a +single global task lock. Appropriate for use in situations where contention +between tasks is very rarely expected. + +@node GNAT.Threads (g-thread.ads) +@section @code{GNAT.Threads} (@file{g-thread.ads}) +@cindex @code{GNAT.Threads} (@file{g-thread.ads}) +@cindex Foreign threads +@cindex Threads, foreign + +@noindent +Provides facilities for creating and destroying threads with explicit calls. +These threads are known to the GNAT run-time system. These subprograms are +exported C-convention procedures intended to be called from foreign code. +By using these primitives rather than directly calling operating systems +routines, compatibility with the Ada tasking run-time is provided. + +@node GNAT.Traceback (g-traceb.ads) +@section @code{GNAT.Traceback} (@file{g-traceb.ads}) +@cindex @code{GNAT.Traceback} (@file{g-traceb.ads}) +@cindex Trace back facilities + +@noindent +Provides a facility for obtaining non-symbolic traceback information, useful +in various debugging situations. + +@node GNAT.Traceback.Symbolic (g-trasym.ads) +@section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) +@cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) +@cindex Trace back facilities + +@noindent +Provides symbolic traceback information that includes the subprogram +name and line number information. + +@node GNAT.Wide_String_Split (g-wistsp.ads) +@section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) +@cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) +@cindex Wide_String splitter + +@noindent +Useful wide string manipulation routines: given a set of separators, split +a wide string wherever the separators appear, and provide direct access +to the resulting slices. This package is instantiated from +@code{GNAT.Array_Split}. + +@node GNAT.Wide_Wide_String_Split (g-zistsp.ads) +@section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads}) +@cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads}) +@cindex Wide_Wide_String splitter + +@noindent +Useful wide wide string manipulation routines: given a set of separators, split +a wide wide string wherever the separators appear, and provide direct access +to the resulting slices. This package is instantiated from +@code{GNAT.Array_Split}. + +@node Interfaces.C.Extensions (i-cexten.ads) +@section @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) +@cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) + +@noindent +This package contains additional C-related definitions, intended +for use with either manually or automatically generated bindings +to C libraries. + +@node Interfaces.C.Streams (i-cstrea.ads) +@section @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) +@cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) +@cindex C streams, interfacing + +@noindent +This package is a binding for the most commonly used operations +on C streams. + +@node Interfaces.CPP (i-cpp.ads) +@section @code{Interfaces.CPP} (@file{i-cpp.ads}) +@cindex @code{Interfaces.CPP} (@file{i-cpp.ads}) +@cindex C++ interfacing +@cindex Interfacing, to C++ + +@noindent +This package provides facilities for use in interfacing to C++. It +is primarily intended to be used in connection with automated tools +for the generation of C++ interfaces. + +@node Interfaces.Os2lib (i-os2lib.ads) +@section @code{Interfaces.Os2lib} (@file{i-os2lib.ads}) +@cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads}) +@cindex Interfacing, to OS/2 +@cindex OS/2 interfacing + +@noindent +This package provides interface definitions to the OS/2 library. +It is a thin binding which is a direct translation of the +various @file{<bse@.h>} files. + +@node Interfaces.Os2lib.Errors (i-os2err.ads) +@section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads}) +@cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads}) +@cindex OS/2 Error codes +@cindex Interfacing, to OS/2 +@cindex OS/2 interfacing + +@noindent +This package provides definitions of the OS/2 error codes. + +@node Interfaces.Os2lib.Synchronization (i-os2syn.ads) +@section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads}) +@cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads}) +@cindex Interfacing, to OS/2 +@cindex Synchronization, OS/2 +@cindex OS/2 synchronization primitives + +@noindent +This is a child package that provides definitions for interfacing +to the @code{OS/2} synchronization primitives. + +@node Interfaces.Os2lib.Threads (i-os2thr.ads) +@section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads}) +@cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads}) +@cindex Interfacing, to OS/2 +@cindex Thread control, OS/2 +@cindex OS/2 thread interfacing + +@noindent +This is a child package that provides definitions for interfacing +to the @code{OS/2} thread primitives. + +@node Interfaces.Packed_Decimal (i-pacdec.ads) +@section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) +@cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) +@cindex IBM Packed Format +@cindex Packed Decimal + +@noindent +This package provides a set of routines for conversions to and +from a packed decimal format compatible with that used on IBM +mainframes. + +@node Interfaces.VxWorks (i-vxwork.ads) +@section @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) +@cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) +@cindex Interfacing to VxWorks +@cindex VxWorks, interfacing + +@noindent +This package provides a limited binding to the VxWorks API. +In particular, it interfaces with the +VxWorks hardware interrupt facilities. + +@node Interfaces.VxWorks.IO (i-vxwoio.ads) +@section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) +@cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) +@cindex Interfacing to VxWorks' I/O +@cindex VxWorks, I/O interfacing +@cindex VxWorks, Get_Immediate +@cindex Get_Immediate, VxWorks + +@noindent +This package provides a binding to the ioctl (IO/Control) +function of VxWorks, defining a set of option values and +function codes. A particular use of this package is +to enable the use of Get_Immediate under VxWorks. + +@node System.Address_Image (s-addima.ads) +@section @code{System.Address_Image} (@file{s-addima.ads}) +@cindex @code{System.Address_Image} (@file{s-addima.ads}) +@cindex Address image +@cindex Image, of an address + +@noindent +This function provides a useful debugging +function that gives an (implementation dependent) +string which identifies an address. + +@node System.Assertions (s-assert.ads) +@section @code{System.Assertions} (@file{s-assert.ads}) +@cindex @code{System.Assertions} (@file{s-assert.ads}) +@cindex Assertions +@cindex Assert_Failure, exception + +@noindent +This package provides the declaration of the exception raised +by an run-time assertion failure, as well as the routine that +is used internally to raise this assertion. + +@node System.Memory (s-memory.ads) +@section @code{System.Memory} (@file{s-memory.ads}) +@cindex @code{System.Memory} (@file{s-memory.ads}) +@cindex Memory allocation + +@noindent +This package provides the interface to the low level routines used +by the generated code for allocation and freeing storage for the +default storage pool (analogous to the C routines malloc and free. +It also provides a reallocation interface analogous to the C routine +realloc. The body of this unit may be modified to provide alternative +allocation mechanisms for the default pool, and in addition, direct +calls to this unit may be made for low level allocation uses (for +example see the body of @code{GNAT.Tables}). + +@node System.Partition_Interface (s-parint.ads) +@section @code{System.Partition_Interface} (@file{s-parint.ads}) +@cindex @code{System.Partition_Interface} (@file{s-parint.ads}) +@cindex Partition interfacing functions + +@noindent +This package provides facilities for partition interfacing. It +is used primarily in a distribution context when using Annex E +with @code{GLADE}. + +@node System.Restrictions (s-restri.ads) +@section @code{System.Restrictions} (@file{s-restri.ads}) +@cindex @code{System.Restrictions} (@file{s-restri.ads}) +@cindex Run-time restrictions access + +@noindent +This package provides facilities for accessing at run-time +the status of restrictions specified at compile time for +the partition. Information is available both with regard +to actual restrictions specified, and with regard to +compiler determined information on which restrictions +are violated by one or more packages in the partition. + +@node System.Rident (s-rident.ads) +@section @code{System.Rident} (@file{s-rident.ads}) +@cindex @code{System.Rident} (@file{s-rident.ads}) +@cindex Restrictions definitions + +@noindent +This package provides definitions of the restrictions +identifiers supported by GNAT, and also the format of +the restrictions provided in package System.Restrictions. +It is not normally necessary to @code{with} this generic package +since the necessary instantiation is included in +package System.Restrictions. + +@node System.Task_Info (s-tasinf.ads) +@section @code{System.Task_Info} (@file{s-tasinf.ads}) +@cindex @code{System.Task_Info} (@file{s-tasinf.ads}) +@cindex Task_Info pragma + +@noindent +This package provides target dependent functionality that is used +to support the @code{Task_Info} pragma + +@node System.Wch_Cnv (s-wchcnv.ads) +@section @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) +@cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) +@cindex Wide Character, Representation +@cindex Wide String, Conversion +@cindex Representation of wide characters + +@noindent +This package provides routines for converting between +wide and wide wide characters and a representation as a value of type +@code{Standard.String}, using a specified wide character +encoding method. It uses definitions in +package @code{System.Wch_Con}. + +@node System.Wch_Con (s-wchcon.ads) +@section @code{System.Wch_Con} (@file{s-wchcon.ads}) +@cindex @code{System.Wch_Con} (@file{s-wchcon.ads}) + +@noindent +This package provides definitions and descriptions of +the various methods used for encoding wide characters +in ordinary strings. These definitions are used by +the package @code{System.Wch_Cnv}. + +@node Interfacing to Other Languages +@chapter Interfacing to Other Languages +@noindent +The facilities in annex B of the Ada 95 Reference Manual are fully +implemented in GNAT, and in addition, a full interface to C++ is +provided. + +@menu +* Interfacing to C:: +* Interfacing to C++:: +* Interfacing to COBOL:: +* Interfacing to Fortran:: +* Interfacing to non-GNAT Ada code:: +@end menu + +@node Interfacing to C +@section Interfacing to C + +@noindent +Interfacing to C with GNAT can use one of two approaches: + +@itemize @bullet +@item +The types in the package @code{Interfaces.C} may be used. +@item +Standard Ada types may be used directly. This may be less portable to +other compilers, but will work on all GNAT compilers, which guarantee +correspondence between the C and Ada types. +@end itemize + +@noindent +Pragma @code{Convention C} may be applied to Ada types, but mostly has no +effect, since this is the default. The following table shows the +correspondence between Ada scalar types and the corresponding C types. + +@table @code +@item Integer +@code{int} +@item Short_Integer +@code{short} +@item Short_Short_Integer +@code{signed char} +@item Long_Integer +@code{long} +@item Long_Long_Integer +@code{long long} +@item Short_Float +@code{float} +@item Float +@code{float} +@item Long_Float +@code{double} +@item Long_Long_Float +This is the longest floating-point type supported by the hardware. +@end table + +@noindent +Additionally, there are the following general correspondences between Ada +and C types: +@itemize @bullet +@item +Ada enumeration types map to C enumeration types directly if pragma +@code{Convention C} is specified, which causes them to have int +length. Without pragma @code{Convention C}, Ada enumeration types map to +8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short}, +@code{int}, respectively) depending on the number of values passed. +This is the only case in which pragma @code{Convention C} affects the +representation of an Ada type. + +@item +Ada access types map to C pointers, except for the case of pointers to +unconstrained types in Ada, which have no direct C equivalent. + +@item +Ada arrays map directly to C arrays. + +@item +Ada records map directly to C structures. + +@item +Packed Ada records map to C structures where all members are bit fields +of the length corresponding to the @code{@var{type}'Size} value in Ada. +@end itemize + +@node Interfacing to C++ +@section Interfacing to C++ + +@noindent +The interface to C++ makes use of the following pragmas, which are +primarily intended to be constructed automatically using a binding generator +tool, although it is possible to construct them by hand. No suitable binding +generator tool is supplied with GNAT though. + +Using these pragmas it is possible to achieve complete +inter-operability between Ada tagged types and C class definitions. +See @ref{Implementation Defined Pragmas}, for more details. + +@table @code +@item pragma CPP_Class ([Entity =>] @var{local_NAME}) +The argument denotes an entity in the current declarative region that is +declared as a tagged or untagged record type. It indicates that the type +corresponds to an externally declared C++ class type, and is to be laid +out the same way that C++ would lay out the type. + +@item pragma CPP_Constructor ([Entity =>] @var{local_NAME}) +This pragma identifies an imported function (imported in the usual way +with pragma @code{Import}) as corresponding to a C++ constructor. + +@item pragma CPP_Vtable @dots{} +One @code{CPP_Vtable} pragma can be present for each component of type +@code{CPP.Interfaces.Vtable_Ptr} in a record to which pragma @code{CPP_Class} +applies. +@end table + +@node Interfacing to COBOL +@section Interfacing to COBOL + +@noindent +Interfacing to COBOL is achieved as described in section B.4 of +the Ada 95 reference manual. + +@node Interfacing to Fortran +@section Interfacing to Fortran + +@noindent +Interfacing to Fortran is achieved as described in section B.5 of the +reference manual. The pragma @code{Convention Fortran}, applied to a +multi-dimensional array causes the array to be stored in column-major +order as required for convenient interface to Fortran. + +@node Interfacing to non-GNAT Ada code +@section Interfacing to non-GNAT Ada code + +It is possible to specify the convention @code{Ada} in a pragma +@code{Import} or pragma @code{Export}. However this refers to +the calling conventions used by GNAT, which may or may not be +similar enough to those used by some other Ada 83 or Ada 95 +compiler to allow interoperation. + +If arguments types are kept simple, and if the foreign compiler generally +follows system calling conventions, then it may be possible to integrate +files compiled by other Ada compilers, provided that the elaboration +issues are adequately addressed (for example by eliminating the +need for any load time elaboration). + +In particular, GNAT running on VMS is designed to +be highly compatible with the DEC Ada 83 compiler, so this is one +case in which it is possible to import foreign units of this type, +provided that the data items passed are restricted to simple scalar +values or simple record types without variants, or simple array +types with fixed bounds. + +@node Specialized Needs Annexes +@chapter Specialized Needs Annexes + +@noindent +Ada 95 defines a number of specialized needs annexes, which are not +required in all implementations. However, as described in this chapter, +GNAT implements all of these special needs annexes: + +@table @asis +@item Systems Programming (Annex C) +The Systems Programming Annex is fully implemented. + +@item Real-Time Systems (Annex D) +The Real-Time Systems Annex is fully implemented. + +@item Distributed Systems (Annex E) +Stub generation is fully implemented in the GNAT compiler. In addition, +a complete compatible PCS is available as part of the GLADE system, +a separate product. When the two +products are used in conjunction, this annex is fully implemented. + +@item Information Systems (Annex F) +The Information Systems annex is fully implemented. + +@item Numerics (Annex G) +The Numerics Annex is fully implemented. + +@item Safety and Security (Annex H) +The Safety and Security annex is fully implemented. +@end table + +@node Implementation of Specific Ada Features +@chapter Implementation of Specific Ada Features + +@noindent +This chapter describes the GNAT implementation of several Ada language +facilities. + +@menu +* Machine Code Insertions:: +* GNAT Implementation of Tasking:: +* GNAT Implementation of Shared Passive Packages:: +* Code Generation for Array Aggregates:: +* The Size of Discriminated Records with Default Discriminants:: +* Strict Conformance to the Ada 95 Reference Manual:: +@end menu + +@node Machine Code Insertions +@section Machine Code Insertions + +@noindent +Package @code{Machine_Code} provides machine code support as described +in the Ada 95 Reference Manual in two separate forms: +@itemize @bullet +@item +Machine code statements, consisting of qualified expressions that +fit the requirements of RM section 13.8. +@item +An intrinsic callable procedure, providing an alternative mechanism of +including machine instructions in a subprogram. +@end itemize + +@noindent +The two features are similar, and both are closely related to the mechanism +provided by the asm instruction in the GNU C compiler. Full understanding +and use of the facilities in this package requires understanding the asm +instruction as described in @cite{Using the GNU Compiler Collection (GCC)} +by Richard Stallman. The relevant section is titled ``Extensions to the C +Language Family'' -> ``Assembler Instructions with C Expression Operands''. + +Calls to the function @code{Asm} and the procedure @code{Asm} have identical +semantic restrictions and effects as described below. Both are provided so +that the procedure call can be used as a statement, and the function call +can be used to form a code_statement. + +The first example given in the GCC documentation is the C @code{asm} +instruction: +@smallexample + asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); +@end smallexample + +@noindent +The equivalent can be written for GNAT as: + +@smallexample @c ada +Asm ("fsinx %1 %0", + My_Float'Asm_Output ("=f", result), + My_Float'Asm_Input ("f", angle)); +@end smallexample + +@noindent +The first argument to @code{Asm} is the assembler template, and is +identical to what is used in GNU C@. This string must be a static +expression. The second argument is the output operand list. It is +either a single @code{Asm_Output} attribute reference, or a list of such +references enclosed in parentheses (technically an array aggregate of +such references). + +The @code{Asm_Output} attribute denotes a function that takes two +parameters. The first is a string, the second is the name of a variable +of the type designated by the attribute prefix. The first (string) +argument is required to be a static expression and designates the +constraint for the parameter (e.g.@: what kind of register is +required). The second argument is the variable to be updated with the +result. The possible values for constraint are the same as those used in +the RTL, and are dependent on the configuration file used to build the +GCC back end. If there are no output operands, then this argument may +either be omitted, or explicitly given as @code{No_Output_Operands}. + +The second argument of @code{@var{my_float}'Asm_Output} functions as +though it were an @code{out} parameter, which is a little curious, but +all names have the form of expressions, so there is no syntactic +irregularity, even though normally functions would not be permitted +@code{out} parameters. The third argument is the list of input +operands. It is either a single @code{Asm_Input} attribute reference, or +a list of such references enclosed in parentheses (technically an array +aggregate of such references). + +The @code{Asm_Input} attribute denotes a function that takes two +parameters. The first is a string, the second is an expression of the +type designated by the prefix. The first (string) argument is required +to be a static expression, and is the constraint for the parameter, +(e.g.@: what kind of register is required). The second argument is the +value to be used as the input argument. The possible values for the +constant are the same as those used in the RTL, and are dependent on +the configuration file used to built the GCC back end. + +If there are no input operands, this argument may either be omitted, or +explicitly given as @code{No_Input_Operands}. The fourth argument, not +present in the above example, is a list of register names, called the +@dfn{clobber} argument. This argument, if given, must be a static string +expression, and is a space or comma separated list of names of registers +that must be considered destroyed as a result of the @code{Asm} call. If +this argument is the null string (the default value), then the code +generator assumes that no additional registers are destroyed. + +The fifth argument, not present in the above example, called the +@dfn{volatile} argument, is by default @code{False}. It can be set to +the literal value @code{True} to indicate to the code generator that all +optimizations with respect to the instruction specified should be +suppressed, and that in particular, for an instruction that has outputs, +the instruction will still be generated, even if none of the outputs are +used. See the full description in the GCC manual for further details. + +The @code{Asm} subprograms may be used in two ways. First the procedure +forms can be used anywhere a procedure call would be valid, and +correspond to what the RM calls ``intrinsic'' routines. Such calls can +be used to intersperse machine instructions with other Ada statements. +Second, the function forms, which return a dummy value of the limited +private type @code{Asm_Insn}, can be used in code statements, and indeed +this is the only context where such calls are allowed. Code statements +appear as aggregates of the form: + +@smallexample @c ada +Asm_Insn'(Asm (@dots{})); +Asm_Insn'(Asm_Volatile (@dots{})); +@end smallexample + +@noindent +In accordance with RM rules, such code statements are allowed only +within subprograms whose entire body consists of such statements. It is +not permissible to intermix such statements with other Ada statements. + +Typically the form using intrinsic procedure calls is more convenient +and more flexible. The code statement form is provided to meet the RM +suggestion that such a facility should be made available. The following +is the exact syntax of the call to @code{Asm}. As usual, if named notation +is used, the arguments may be given in arbitrary order, following the +normal rules for use of positional and named arguments) + +@smallexample +ASM_CALL ::= Asm ( + [Template =>] static_string_EXPRESSION + [,[Outputs =>] OUTPUT_OPERAND_LIST ] + [,[Inputs =>] INPUT_OPERAND_LIST ] + [,[Clobber =>] static_string_EXPRESSION ] + [,[Volatile =>] static_boolean_EXPRESSION] ) + +OUTPUT_OPERAND_LIST ::= + [PREFIX.]No_Output_Operands +| OUTPUT_OPERAND_ATTRIBUTE +| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) + +OUTPUT_OPERAND_ATTRIBUTE ::= + SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) + +INPUT_OPERAND_LIST ::= + [PREFIX.]No_Input_Operands +| INPUT_OPERAND_ATTRIBUTE +| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) + +INPUT_OPERAND_ATTRIBUTE ::= + SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) +@end smallexample + +@noindent +The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} +are declared in the package @code{Machine_Code} and must be referenced +according to normal visibility rules. In particular if there is no +@code{use} clause for this package, then appropriate package name +qualification is required. + +@node GNAT Implementation of Tasking +@section GNAT Implementation of Tasking + +@noindent +This chapter outlines the basic GNAT approach to tasking (in particular, +a multi-layered library for portability) and discusses issues related +to compliance with the Real-Time Systems Annex. + +@menu +* Mapping Ada Tasks onto the Underlying Kernel Threads:: +* Ensuring Compliance with the Real-Time Annex:: +@end menu + +@node Mapping Ada Tasks onto the Underlying Kernel Threads +@subsection Mapping Ada Tasks onto the Underlying Kernel Threads + +@noindent +GNAT's run-time support comprises two layers: + +@itemize @bullet +@item GNARL (GNAT Run-time Layer) +@item GNULL (GNAT Low-level Library) +@end itemize + +@noindent +In GNAT, Ada's tasking services rely on a platform and OS independent +layer known as GNARL@. This code is responsible for implementing the +correct semantics of Ada's task creation, rendezvous, protected +operations etc. + +GNARL decomposes Ada's tasking semantics into simpler lower level +operations such as create a thread, set the priority of a thread, +yield, create a lock, lock/unlock, etc. The spec for these low-level +operations constitutes GNULLI, the GNULL Interface. This interface is +directly inspired from the POSIX real-time API@. + +If the underlying executive or OS implements the POSIX standard +faithfully, the GNULL Interface maps as is to the services offered by +the underlying kernel. Otherwise, some target dependent glue code maps +the services offered by the underlying kernel to the semantics expected +by GNARL@. + +Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the +key point is that each Ada task is mapped on a thread in the underlying +kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. + +In addition Ada task priorities map onto the underlying thread priorities. +Mapping Ada tasks onto the underlying kernel threads has several advantages: + +@itemize @bullet +@item +The underlying scheduler is used to schedule the Ada tasks. This +makes Ada tasks as efficient as kernel threads from a scheduling +standpoint. + +@item +Interaction with code written in C containing threads is eased +since at the lowest level Ada tasks and C threads map onto the same +underlying kernel concept. + +@item +When an Ada task is blocked during I/O the remaining Ada tasks are +able to proceed. + +@item +On multiprocessor systems Ada tasks can execute in parallel. +@end itemize + +@noindent +Some threads libraries offer a mechanism to fork a new process, with the +child process duplicating the threads from the parent. +GNAT does not +support this functionality when the parent contains more than one task. +@cindex Forking a new process + +@node Ensuring Compliance with the Real-Time Annex +@subsection Ensuring Compliance with the Real-Time Annex +@cindex Real-Time Systems Annex compliance + +@noindent +Although mapping Ada tasks onto +the underlying threads has significant advantages, it does create some +complications when it comes to respecting the scheduling semantics +specified in the real-time annex (Annex D). + +For instance the Annex D requirement for the @code{FIFO_Within_Priorities} +scheduling policy states: + +@quotation +@emph{When the active priority of a ready task that is not running +changes, or the setting of its base priority takes effect, the +task is removed from the ready queue for its old active priority +and is added at the tail of the ready queue for its new active +priority, except in the case where the active priority is lowered +due to the loss of inherited priority, in which case the task is +added at the head of the ready queue for its new active priority.} +@end quotation + +@noindent +While most kernels do put tasks at the end of the priority queue when +a task changes its priority, (which respects the main +FIFO_Within_Priorities requirement), almost none keep a thread at the +beginning of its priority queue when its priority drops from the loss +of inherited priority. + +As a result most vendors have provided incomplete Annex D implementations. + +The GNAT run-time, has a nice cooperative solution to this problem +which ensures that accurate FIFO_Within_Priorities semantics are +respected. + +The principle is as follows. When an Ada task T is about to start +running, it checks whether some other Ada task R with the same +priority as T has been suspended due to the loss of priority +inheritance. If this is the case, T yields and is placed at the end of +its priority queue. When R arrives at the front of the queue it +executes. + +Note that this simple scheme preserves the relative order of the tasks +that were ready to execute in the priority queue where R has been +placed at the end. + +@node GNAT Implementation of Shared Passive Packages +@section GNAT Implementation of Shared Passive Packages +@cindex Shared passive packages + +@noindent +GNAT fully implements the pragma @code{Shared_Passive} for +@cindex pragma @code{Shared_Passive} +the purpose of designating shared passive packages. +This allows the use of passive partitions in the +context described in the Ada Reference Manual; i.e. for communication +between separate partitions of a distributed application using the +features in Annex E. +@cindex Annex E +@cindex Distribution Systems Annex + +However, the implementation approach used by GNAT provides for more +extensive usage as follows: + +@table @emph +@item Communication between separate programs + +This allows separate programs to access the data in passive +partitions, using protected objects for synchronization where +needed. The only requirement is that the two programs have a +common shared file system. It is even possible for programs +running on different machines with different architectures +(e.g. different endianness) to communicate via the data in +a passive partition. + +@item Persistence between program runs + +The data in a passive package can persist from one run of a +program to another, so that a later program sees the final +values stored by a previous run of the same program. + +@end table + +@noindent +The implementation approach used is to store the data in files. A +separate stream file is created for each object in the package, and +an access to an object causes the corresponding file to be read or +written. + +The environment variable @code{SHARED_MEMORY_DIRECTORY} should be +@cindex @code{SHARED_MEMORY_DIRECTORY} environment variable +set to the directory to be used for these files. +The files in this directory +have names that correspond to their fully qualified names. For +example, if we have the package + +@smallexample @c ada +package X is + pragma Shared_Passive (X); + Y : Integer; + Z : Float; +end X; +@end smallexample + +@noindent +and the environment variable is set to @code{/stemp/}, then the files created +will have the names: + +@smallexample +/stemp/x.y +/stemp/x.z +@end smallexample + +@noindent +These files are created when a value is initially written to the object, and +the files are retained until manually deleted. This provides the persistence +semantics. If no file exists, it means that no partition has assigned a value +to the variable; in this case the initial value declared in the package +will be used. This model ensures that there are no issues in synchronizing +the elaboration process, since elaboration of passive packages elaborates the +initial values, but does not create the files. + +The files are written using normal @code{Stream_IO} access. +If you want to be able +to communicate between programs or partitions running on different +architectures, then you should use the XDR versions of the stream attribute +routines, since these are architecture independent. + +If active synchronization is required for access to the variables in the +shared passive package, then as described in the Ada Reference Manual, the +package may contain protected objects used for this purpose. In this case +a lock file (whose name is @file{___lock} (three underscores) +is created in the shared memory directory. +@cindex @file{___lock} file (for shared passive packages) +This is used to provide the required locking +semantics for proper protected object synchronization. + +As of January 2003, GNAT supports shared passive packages on all platforms +except for OpenVMS. + +@node Code Generation for Array Aggregates +@section Code Generation for Array Aggregates + +@menu +* Static constant aggregates with static bounds:: +* Constant aggregates with unconstrained nominal types:: +* Aggregates with static bounds:: +* Aggregates with non-static bounds:: +* Aggregates in assignment statements:: +@end menu + +@noindent +Aggregates have a rich syntax and allow the user to specify the values of +complex data structures by means of a single construct. As a result, the +code generated for aggregates can be quite complex and involve loops, case +statements and multiple assignments. In the simplest cases, however, the +compiler will recognize aggregates whose components and constraints are +fully static, and in those cases the compiler will generate little or no +executable code. The following is an outline of the code that GNAT generates +for various aggregate constructs. For further details, you will find it +useful to examine the output produced by the -gnatG flag to see the expanded +source that is input to the code generator. You may also want to examine +the assembly code generated at various levels of optimization. + +The code generated for aggregates depends on the context, the component values, +and the type. In the context of an object declaration the code generated is +generally simpler than in the case of an assignment. As a general rule, static +component values and static subtypes also lead to simpler code. + +@node Static constant aggregates with static bounds +@subsection Static constant aggregates with static bounds + +@noindent +For the declarations: +@smallexample @c ada + type One_Dim is array (1..10) of integer; + ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); +@end smallexample + +@noindent +GNAT generates no executable code: the constant ar0 is placed in static memory. +The same is true for constant aggregates with named associations: + +@smallexample @c ada + Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); + Cr3 : constant One_Dim := (others => 7777); +@end smallexample + +@noindent +The same is true for multidimensional constant arrays such as: + +@smallexample @c ada + type two_dim is array (1..3, 1..3) of integer; + Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); +@end smallexample + +@noindent +The same is true for arrays of one-dimensional arrays: the following are +static: + +@smallexample @c ada +type ar1b is array (1..3) of boolean; +type ar_ar is array (1..3) of ar1b; +None : constant ar1b := (others => false); -- fully static +None2 : constant ar_ar := (1..3 => None); -- fully static +@end smallexample + +@noindent +However, for multidimensional aggregates with named associations, GNAT will +generate assignments and loops, even if all associations are static. The +following two declarations generate a loop for the first dimension, and +individual component assignments for the second dimension: + +@smallexample @c ada +Zero1: constant two_dim := (1..3 => (1..3 => 0)); +Zero2: constant two_dim := (others => (others => 0)); +@end smallexample + +@node Constant aggregates with unconstrained nominal types +@subsection Constant aggregates with unconstrained nominal types + +@noindent +In such cases the aggregate itself establishes the subtype, so that +associations with @code{others} cannot be used. GNAT determines the +bounds for the actual subtype of the aggregate, and allocates the +aggregate statically as well. No code is generated for the following: + +@smallexample @c ada + type One_Unc is array (natural range <>) of integer; + Cr_Unc : constant One_Unc := (12,24,36); +@end smallexample + +@node Aggregates with static bounds +@subsection Aggregates with static bounds + +@noindent +In all previous examples the aggregate was the initial (and immutable) value +of a constant. If the aggregate initializes a variable, then code is generated +for it as a combination of individual assignments and loops over the target +object. The declarations + +@smallexample @c ada + Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); + Cr_Var2 : One_Dim := (others > -1); +@end smallexample + +@noindent +generate the equivalent of + +@smallexample @c ada + Cr_Var1 (1) := 2; + Cr_Var1 (2) := 3; + Cr_Var1 (3) := 5; + Cr_Var1 (4) := 11; + + for I in Cr_Var2'range loop + Cr_Var2 (I) := =-1; + end loop; +@end smallexample + +@node Aggregates with non-static bounds +@subsection Aggregates with non-static bounds + +@noindent +If the bounds of the aggregate are not statically compatible with the bounds +of the nominal subtype of the target, then constraint checks have to be +generated on the bounds. For a multidimensional array, constraint checks may +have to be applied to sub-arrays individually, if they do not have statically +compatible subtypes. + +@node Aggregates in assignment statements +@subsection Aggregates in assignment statements + +@noindent +In general, aggregate assignment requires the construction of a temporary, +and a copy from the temporary to the target of the assignment. This is because +it is not always possible to convert the assignment into a series of individual +component assignments. For example, consider the simple case: + +@smallexample @c ada + A := (A(2), A(1)); +@end smallexample + +@noindent +This cannot be converted into: + +@smallexample @c ada + A(1) := A(2); + A(2) := A(1); +@end smallexample + +@noindent +So the aggregate has to be built first in a separate location, and then +copied into the target. GNAT recognizes simple cases where this intermediate +step is not required, and the assignments can be performed in place, directly +into the target. The following sufficient criteria are applied: + +@itemize @bullet +@item +The bounds of the aggregate are static, and the associations are static. +@item +The components of the aggregate are static constants, names of +simple variables that are not renamings, or expressions not involving +indexed components whose operands obey these rules. +@end itemize + +@noindent +If any of these conditions are violated, the aggregate will be built in +a temporary (created either by the front-end or the code generator) and then +that temporary will be copied onto the target. + + +@node The Size of Discriminated Records with Default Discriminants +@section The Size of Discriminated Records with Default Discriminants + +@noindent +If a discriminated type @code{T} has discriminants with default values, it is +possible to declare an object of this type without providing an explicit +constraint: + +@smallexample @c ada +@group +type Size is range 1..100; + +type Rec (D : Size := 15) is record + Name : String (1..D); +end T; + +Word : Rec; +@end group +@end smallexample + +@noindent +Such an object is said to be @emph{unconstrained}. +The discriminant of the object +can be modified by a full assignment to the object, as long as it preserves the +relation between the value of the discriminant, and the value of the components +that depend on it: + +@smallexample @c ada +@group +Word := (3, "yes"); + +Word := (5, "maybe"); + +Word := (5, "no"); -- raises Constraint_Error +@end group +@end smallexample + +@noindent +In order to support this behavior efficiently, an unconstrained object is +given the maximum size that any value of the type requires. In the case +above, @code{Word} has storage for the discriminant and for +a @code{String} of length 100. +It is important to note that unconstrained objects do not require dynamic +allocation. It would be an improper implementation to place on the heap those +components whose size depends on discriminants. (This improper implementation +was used by some Ada83 compilers, where the @code{Name} component above +would have +been stored as a pointer to a dynamic string). Following the principle that +dynamic storage management should never be introduced implicitly, +an Ada95 compiler should reserve the full size for an unconstrained declared +object, and place it on the stack. + +This maximum size approach +has been a source of surprise to some users, who expect the default +values of the discriminants to determine the size reserved for an +unconstrained object: ``If the default is 15, why should the object occupy +a larger size?'' +The answer, of course, is that the discriminant may be later modified, +and its full range of values must be taken into account. This is why the +declaration: + +@smallexample +@group +type Rec (D : Positive := 15) is record + Name : String (1..D); +end record; + +Too_Large : Rec; +@end group +@end smallexample + +@noindent +is flagged by the compiler with a warning: +an attempt to create @code{Too_Large} will raise @code{Storage_Error}, +because the required size includes @code{Positive'Last} +bytes. As the first example indicates, the proper approach is to declare an +index type of ``reasonable'' range so that unconstrained objects are not too +large. + +One final wrinkle: if the object is declared to be @code{aliased}, or if it is +created in the heap by means of an allocator, then it is @emph{not} +unconstrained: +it is constrained by the default values of the discriminants, and those values +cannot be modified by full assignment. This is because in the presence of +aliasing all views of the object (which may be manipulated by different tasks, +say) must be consistent, so it is imperative that the object, once created, +remain invariant. + +@node Strict Conformance to the Ada 95 Reference Manual +@section Strict Conformance to the Ada 95 Reference Manual + +@noindent +The dynamic semantics defined by the Ada 95 Reference Manual impose a set of +run-time checks to be generated. By default, the GNAT compiler will insert many +run-time checks into the compiled code, including most of those required by the +Ada 95 Reference Manual. However, there are three checks that are not enabled +in the default mode for efficiency reasons: arithmetic overflow checking for +integer operations (including division by zero), checks for access before +elaboration on subprogram calls, and stack overflow checking (most operating +systems do not perform this check by default). + +Strict conformance to the Ada 95 Reference Manual can be achieved by adding +three compiler options for overflow checking for integer operations +(@option{-gnato}), dynamic checks for access-before-elaboration on subprogram +calls and generic instantiations (@option{-gnatE}), and stack overflow +checking (@option{-fstack-check}). + +Note that the result of a floating point arithmetic operation in overflow and +invalid situations, when the @code{Machine_Overflows} attribute of the result +type is @code{False}, is to generate IEEE NaN and infinite values. This is the +case for machines compliant with the IEEE floating-point standard, but on +machines that are not fully compliant with this standard, such as Alpha, the +@option{-mieee} compiler flag must be used for achieving IEEE confirming +behavior (although at the cost of a significant performance penalty), so +infinite and and NaN values are properly generated. + + +@node Project File Reference +@chapter Project File Reference + +@noindent +This chapter describes the syntax and semantics of project files. +Project files specify the options to be used when building a system. +Project files can specify global settings for all tools, +as well as tool-specific settings. +See the chapter on project files in the GNAT Users guide for examples of use. + +@menu +* Reserved Words:: +* Lexical Elements:: +* Declarations:: +* Empty declarations:: +* Typed string declarations:: +* Variables:: +* Expressions:: +* Attributes:: +* Project Attributes:: +* Attribute References:: +* External Values:: +* Case Construction:: +* Packages:: +* Package Renamings:: +* Projects:: +* Project Extensions:: +* Project File Elaboration:: +@end menu + +@node Reserved Words +@section Reserved Words + +@noindent +All Ada95 reserved words are reserved in project files, and cannot be used +as variable names or project names. In addition, the following are +also reserved in project files: + +@itemize +@item @code{extends} + +@item @code{external} + +@item @code{project} + +@end itemize + +@node Lexical Elements +@section Lexical Elements + +@noindent +Rules for identifiers are the same as in Ada95. Identifiers +are case-insensitive. Strings are case sensitive, except where noted. +Comments have the same form as in Ada95. + +@noindent +Syntax: + +@smallexample +simple_name ::= + identifier + +name ::= + simple_name @{. simple_name@} +@end smallexample + +@node Declarations +@section Declarations + +@noindent +Declarations introduce new entities that denote types, variables, attributes, +and packages. Some declarations can only appear immediately within a project +declaration. Others can appear within a project or within a package. + +Syntax: +@smallexample +declarative_item ::= + simple_declarative_item | + typed_string_declaration | + package_declaration + +simple_declarative_item ::= + variable_declaration | + typed_variable_declaration | + attribute_declaration | + case_construction | + empty_declaration +@end smallexample + +@node Empty declarations +@section Empty declarations + +@smallexample +empty_declaration ::= + @b{null} ; +@end smallexample + +An empty declaration is allowed anywhere a declaration is allowed. +It has no effect. + +@node Typed string declarations +@section Typed string declarations + +@noindent +Typed strings are sequences of string literals. Typed strings are the only +named types in project files. They are used in case constructions, where they +provide support for conditional attribute definitions. + +Syntax: +@smallexample +typed_string_declaration ::= + @b{type} <typed_string_>_simple_name @b{is} + ( string_literal @{, string_literal@} ); +@end smallexample + +@noindent +A typed string declaration can only appear immediately within a project +declaration. + +All the string literals in a typed string declaration must be distinct. + +@node Variables +@section Variables + +@noindent +Variables denote values, and appear as constituents of expressions. + +@smallexample +typed_variable_declaration ::= + <typed_variable_>simple_name : <typed_string_>name := string_expression ; + +variable_declaration ::= + <variable_>simple_name := expression; +@end smallexample + +@noindent +The elaboration of a variable declaration introduces the variable and +assigns to it the value of the expression. The name of the variable is +available after the assignment symbol. + +@noindent +A typed_variable can only be declare once. + +@noindent +a non typed variable can be declared multiple times. + +@noindent +Before the completion of its first declaration, the value of variable +is the null string. + +@node Expressions +@section Expressions + +@noindent +An expression is a formula that defines a computation or retrieval of a value. +In a project file the value of an expression is either a string or a list +of strings. A string value in an expression is either a literal, the current +value of a variable, an external value, an attribute reference, or a +concatenation operation. + +Syntax: + +@smallexample +expression ::= + term @{& term@} + +term ::= + string_literal | + string_list | + <variable_>name | + external_value | + attribute_reference + +string_literal ::= + (same as Ada) + +string_list ::= + ( <string_>expression @{ , <string_>expression @} ) +@end smallexample + +@subsection Concatenation +@noindent +The following concatenation functions are defined: + +@smallexample @c ada + function "&" (X : String; Y : String) return String; + function "&" (X : String_List; Y : String) return String_List; + function "&" (X : String_List; Y : String_List) return String_List; +@end smallexample + +@node Attributes +@section Attributes + +@noindent +An attribute declaration defines a property of a project or package. This +property can later be queried by means of an attribute reference. +Attribute values are strings or string lists. + +Some attributes are associative arrays. These attributes are mappings whose +domain is a set of strings. These attributes are declared one association +at a time, by specifying a point in the domain and the corresponding image +of the attribute. They may also be declared as a full associative array, +getting the same associations as the corresponding attribute in an imported +or extended project. + +Attributes that are not associative arrays are called simple attributes. + +Syntax: +@smallexample +attribute_declaration ::= + full_associative_array_declaration | + @b{for} attribute_designator @b{use} expression ; + +full_associative_array_declaration ::= + @b{for} <associative_array_attribute_>simple_name @b{use} + <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ; + +attribute_designator ::= + <simple_attribute_>simple_name | + <associative_array_attribute_>simple_name ( string_literal ) +@end smallexample + +@noindent +Some attributes are project-specific, and can only appear immediately within +a project declaration. Others are package-specific, and can only appear within +the proper package. + +The expression in an attribute definition must be a string or a string_list. +The string literal appearing in the attribute_designator of an associative +array attribute is case-insensitive. + +@node Project Attributes +@section Project Attributes + +@noindent +The following attributes apply to a project. All of them are simple +attributes. + +@table @code +@item Object_Dir +Expression must be a path name. The attribute defines the +directory in which the object files created by the build are to be placed. If +not specified, object files are placed in the project directory. + +@item Exec_Dir +Expression must be a path name. The attribute defines the +directory in which the executables created by the build are to be placed. +If not specified, executables are placed in the object directory. + +@item Source_Dirs +Expression must be a list of path names. The attribute +defines the directories in which the source files for the project are to be +found. If not specified, source files are found in the project directory. + +@item Source_Files +Expression must be a list of file names. The attribute +defines the individual files, in the project directory, which are to be used +as sources for the project. File names are path_names that contain no directory +information. If the project has no sources the attribute must be declared +explicitly with an empty list. + +@item Source_List_File +Expression must a single path name. The attribute +defines a text file that contains a list of source file names to be used +as sources for the project + +@item Library_Dir +Expression must be a path name. The attribute defines the +directory in which a library is to be built. The directory must exist, must +be distinct from the project's object directory, and must be writable. + +@item Library_Name +Expression must be a string that is a legal file name, +without extension. The attribute defines a string that is used to generate +the name of the library to be built by the project. + +@item Library_Kind +Argument must be a string value that must be one of the +following @code{"static"}, @code{"dynamic"} or @code{"relocatable"}. This +string is case-insensitive. If this attribute is not specified, the library is +a static library. Otherwise, the library may be dynamic or relocatable. This +distinction is operating-system dependent. + +@item Library_Version +Expression must be a string value whose interpretation +is platform dependent. On UNIX, it is used only for dynamic/relocatable +libraries as the internal name of the library (the @code{"soname"}). If the +library file name (built from the @code{Library_Name}) is different from the +@code{Library_Version}, then the library file will be a symbolic link to the +actual file whose name will be @code{Library_Version}. + +@item Library_Interface +Expression must be a string list. Each element of the string list +must designate a unit of the project. +If this attribute is present in a Library Project File, then the project +file is a Stand-alone Library_Project_File. + +@item Library_Auto_Init +Expression must be a single string "true" or "false", case-insensitive. +If this attribute is present in a Stand-alone Library Project File, +it indicates if initialization is automatic when the dynamic library +is loaded. + +@item Library_Options +Expression must be a string list. Indicates additional switches that +are to be used when building a shared library. + +@item Library_GCC +Expression must be a single string. Designates an alternative to "gcc" +for building shared libraries. + +@item Library_Src_Dir +Expression must be a path name. The attribute defines the +directory in which the sources of the interfaces of a Stand-alone Library will +be copied. The directory must exist, must be distinct from the project's +object directory and source directories of all projects in the project tree, +and must be writable. + +@item Library_Src_Dir +Expression must be a path name. The attribute defines the +directory in which the ALI files of a Library will +be copied. The directory must exist, must be distinct from the project's +object directory and source directories of all projects in the project tree, +and must be writable. + +@item Library_Symbol_File +Expression must be a single string. Its value is the single file name of a +symbol file to be created when building a stand-alone library when the +symbol policy is either "compliant", "controlled" or "restricted", +on platforms that support symbol control, such as VMS. + +@item Library_Reference_Symbol_File +Expression must be a single string. Its value is the single file name of a +reference symbol file that is read when the symbol policy is either +"compliant" or "controlled", on platforms that support symbol control, +such as VMS, when building a stand-alone library. + +@item Library_Symbol_Policy +Expression must be a single string. Its case-insensitive value can only be +"autonomous", "default", "compliant", "controlled" or "restricted". + +This attribute is not taken into account on all platforms. It controls the +policy for exported symbols and, on some platforms (like VMS) that have the +notions of major and minor IDs built in the library files, it controls +the setting of these IDs. + +"autonomous" or "default": exported symbols are not controlled. + +"compliant": if attribute Library_Reference_Symbol_File is not defined, then +it is equivalent to policy "autonomous". If there are exported symbols in +the reference symbol file that are not in the object files of the interfaces, +the major ID of the library is increased. If there are symbols in the +object files of the interfaces that are not in the reference symbol file, +these symbols are put at the end of the list in the newly created symbol file +and the minor ID is increased. + +"controlled": the attribute Library_Reference_Symbol_File must be defined. +The library will fail to build if the exported symbols in the object files of +the interfaces do not match exactly the symbol in the symbol file. + +"restricted": The attribute Library_Symbol_File must be defined. The library +will fail to build if there are symbols in the symbol file that are not in +the exported symbols of the object files of the interfaces. Additional symbols +in the object files are not added to the symbol file. + +@item Main +Expression must be a list of strings that are legal file names. +These file names designate existing compilation units in the source directory +that are legal main subprograms. + +When a project file is elaborated, as part of the execution of a gnatmake +command, one or several executables are built and placed in the Exec_Dir. +If the gnatmake command does not include explicit file names, the executables +that are built correspond to the files specified by this attribute. + +@item Externally_Built +Expression must be a single string. Its value must be either "true" of "false", +case-insensitive. The default is "false". When the value of this attribute is +"true", no attempt is made to compile the sources or to build the library, +when the project is a library project. + +@item Main_Language +This is a simple attribute. Its value is a string that specifies the +language of the main program. + +@item Languages +Expression must be a string list. Each string designates +a programming language that is known to GNAT. The strings are case-insensitive. + +@item Locally_Removed_Files +This attribute is legal only in a project file that extends another. +Expression must be a list of strings that are legal file names. +Each file name must designate a source that would normally be inherited +by the current project file. It cannot designate an immediate source that is +not inherited. Each of the source files in the list are not considered to +be sources of the project file: they are not inherited. +@end table + +@node Attribute References +@section Attribute References + +@noindent +Attribute references are used to retrieve the value of previously defined +attribute for a package or project. +Syntax: +@smallexample +attribute_reference ::= + attribute_prefix ' <simple_attribute_>simple_name [ ( string_literal ) ] + +attribute_prefix ::= + @b{project} | + <project_simple_name | package_identifier | + <project_>simple_name . package_identifier +@end smallexample + +@noindent +If an attribute has not been specified for a given package or project, its +value is the null string or the empty list. + +@node External Values +@section External Values + +@noindent +An external value is an expression whose value is obtained from the command +that invoked the processing of the current project file (typically a +gnatmake command). + +Syntax: +@smallexample +external_value ::= + @b{external} ( string_literal [, string_literal] ) +@end smallexample + +@noindent +The first string_literal is the string to be used on the command line or +in the environment to specify the external value. The second string_literal, +if present, is the default to use if there is no specification for this +external value either on the command line or in the environment. + +@node Case Construction +@section Case Construction + +@noindent +A case construction supports attribute declarations that depend on the value of +a previously declared variable. + +Syntax: +@smallexample +case_construction ::= + @b{case} <typed_variable_>name @b{is} + @{case_item@} + @b{end case} ; + +case_item ::= + @b{when} discrete_choice_list => + @{case_construction | attribute_declaration | empty_declaration@} + +discrete_choice_list ::= + string_literal @{| string_literal@} | + @b{others} +@end smallexample + +@noindent +All choices in a choice list must be distinct. The choice lists of two +distinct alternatives must be disjoint. Unlike Ada, the choice lists of all +alternatives do not need to include all values of the type. An @code{others} +choice must appear last in the list of alternatives. + +@node Packages +@section Packages + +@noindent +A package provides a grouping of variable declarations and attribute +declarations to be used when invoking various GNAT tools. The name of +the package indicates the tool(s) to which it applies. +Syntax: + +@smallexample +package_declaration ::= + package_specification | package_renaming + +package_specification ::= + @b{package} package_identifier @b{is} + @{simple_declarative_item@} + @b{end} package_identifier ; + +package_identifier ::= + @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} | + @code{Linker} | @code{Finder} | @code{Cross_Reference} | + @code{gnatls} | @code{IDE} | @code{Pretty_Printer} +@end smallexample + +@subsection Package Naming + +@noindent +The attributes of a @code{Naming} package specifies the naming conventions +that apply to the source files in a project. When invoking other GNAT tools, +they will use the sources in the source directories that satisfy these +naming conventions. + +The following attributes apply to a @code{Naming} package: + +@table @code +@item Casing +This is a simple attribute whose value is a string. Legal values of this +string are @code{"lowercase"}, @code{"uppercase"} or @code{"mixedcase"}. +These strings are themselves case insensitive. + +@noindent +If @code{Casing} is not specified, then the default is @code{"lowercase"}. + +@item Dot_Replacement +This is a simple attribute whose string value satisfies the following +requirements: + +@itemize @bullet +@item It must not be empty +@item It cannot start or end with an alphanumeric character +@item It cannot be a single underscore +@item It cannot start with an underscore followed by an alphanumeric +@item It cannot contain a dot @code{'.'} if longer than one character +@end itemize + +@noindent +If @code{Dot_Replacement} is not specified, then the default is @code{"-"}. + +@item Spec_Suffix +This is an associative array attribute, defined on language names, +whose image is a string that must satisfy the following +conditions: + +@itemize @bullet +@item It must not be empty +@item It cannot start with an alphanumeric character +@item It cannot start with an underscore followed by an alphanumeric character +@end itemize + +@noindent +For Ada, the attribute denotes the suffix used in file names that contain +library unit declarations, that is to say units that are package and +subprogram declarations. If @code{Spec_Suffix ("Ada")} is not +specified, then the default is @code{".ads"}. + +For C and C++, the attribute denotes the suffix used in file names that +contain prototypes. + +@item Body_Suffix +This is an associative array attribute defined on language names, +whose image is a string that must satisfy the following +conditions: + +@itemize @bullet +@item It must not be empty +@item It cannot start with an alphanumeric character +@item It cannot start with an underscore followed by an alphanumeric character +@item It cannot be a suffix of @code{Spec_Suffix} +@end itemize + +@noindent +For Ada, the attribute denotes the suffix used in file names that contain +library bodies, that is to say units that are package and subprogram bodies. +If @code{Body_Suffix ("Ada")} is not specified, then the default is +@code{".adb"}. + +For C and C++, the attribute denotes the suffix used in file names that contain +source code. + +@item Separate_Suffix +This is a simple attribute whose value satisfies the same conditions as +@code{Body_Suffix}. + +This attribute is specific to Ada. It denotes the suffix used in file names +that contain separate bodies. If it is not specified, then it defaults to same +value as @code{Body_Suffix ("Ada")}. + +@item Spec +This is an associative array attribute, specific to Ada, defined over +compilation unit names. The image is a string that is the name of the file +that contains that library unit. The file name is case sensitive if the +conventions of the host operating system require it. + +@item Body +This is an associative array attribute, specific to Ada, defined over +compilation unit names. The image is a string that is the name of the file +that contains the library unit body for the named unit. The file name is case +sensitive if the conventions of the host operating system require it. + +@item Specification_Exceptions +This is an associative array attribute defined on language names, +whose value is a list of strings. + +This attribute is not significant for Ada. + +For C and C++, each string in the list denotes the name of a file that +contains prototypes, but whose suffix is not necessarily the +@code{Spec_Suffix} for the language. + +@item Implementation_Exceptions +This is an associative array attribute defined on language names, +whose value is a list of strings. + +This attribute is not significant for Ada. + +For C and C++, each string in the list denotes the name of a file that +contains source code, but whose suffix is not necessarily the +@code{Body_Suffix} for the language. +@end table + +The following attributes of package @code{Naming} are obsolescent. They are +kept as synonyms of other attributes for compatibility with previous versions +of the Project Manager. + +@table @code +@item Specification_Suffix +This is a synonym of @code{Spec_Suffix}. + +@item Implementation_Suffix +This is a synonym of @code{Body_Suffix}. + +@item Specification +This is a synonym of @code{Spec}. + +@item Implementation +This is a synonym of @code{Body}. +@end table + +@subsection package Compiler + +@noindent +The attributes of the @code{Compiler} package specify the compilation options +to be used by the underlying compiler. + +@table @code +@item Default_Switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies the compilation options to be used when compiling a component +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies the +compilation options to be used when compiling the named file. If a file +is not specified in the Switches attribute, it is compiled with the +options specified by Default_Switches of its language, if defined. + +@item Local_Configuration_Pragmas. +This is a simple attribute, whose +value is a path name that designates a file containing configuration pragmas +to be used for all invocations of the compiler for immediate sources of the +project. +@end table + +@subsection package Builder + +@noindent +The attributes of package @code{Builder} specify the compilation, binding, and +linking options to be used when building an executable for a project. The +following attributes apply to package @code{Builder}: + +@table @code +@item Default_Switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when building a main +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when building the named main file. If a main file +is not specified in the Switches attribute, it is built with the +options specified by Default_Switches of its language, if defined. + +@item Global_Configuration_Pragmas +This is a simple attribute, whose +value is a path name that designates a file that contains configuration pragmas +to be used in every build of an executable. If both local and global +configuration pragmas are specified, a compilation makes use of both sets. + + +@item Executable +This is an associative array attribute. Its domain is +a set of main source file names. Its range is a simple string that specifies +the executable file name to be used when linking the specified main source. +If a main source is not specified in the Executable attribute, the executable +file name is deducted from the main source file name. +This attribute has no effect if its value is the empty string. + +@item Executable_Suffix +This is a simple attribute whose value is the suffix to be added to +the executables that don't have an attribute Executable specified. +@end table + +@subsection package Gnatls + +@noindent +The attributes of package @code{Gnatls} specify the tool options to be used +when invoking the library browser @command{gnatls}. +The following attributes apply to package @code{Gnatls}: + +@table @code +@item Switches +This is a single attribute with a string list value. Each non empty string +in the list is an option when invoking @code{gnatls}. +@end table + +@subsection package Binder + +@noindent +The attributes of package @code{Binder} specify the options to be used +when invoking the binder in the construction of an executable. +The following attributes apply to package @code{Binder}: + +@table @code +@item Default_Switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when binding a main +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when binding the named main file. If a main file +is not specified in the Switches attribute, it is bound with the +options specified by Default_Switches of its language, if defined. +@end table + +@subsection package Linker + +@noindent +The attributes of package @code{Linker} specify the options to be used when +invoking the linker in the construction of an executable. +The following attributes apply to package @code{Linker}: + +@table @code +@item Default_Switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when linking a main +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when linking the named main file. If a main file +is not specified in the Switches attribute, it is linked with the +options specified by Default_Switches of its language, if defined. + +@item Linker_Options +This is a string list attribute. Its value specifies additional options that +be given to the linker when linking an executable. This attribute is not +used in the main project, only in projects imported directly or indirectly. + +@end table + +@subsection package Cross_Reference + +@noindent +The attributes of package @code{Cross_Reference} specify the tool options +to be used +when invoking the library tool @command{gnatxref}. +The following attributes apply to package @code{Cross_Reference}: + +@table @code +@item Default_Switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when calling @command{gnatxref} on a source +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when calling @command{gnatxref} on the named main source. +If a source is not specified in the Switches attribute, @command{gnatxref} will +be called with the options specified by Default_Switches of its language, +if defined. +@end table + +@subsection package Finder + +@noindent +The attributes of package @code{Finder} specify the tool options to be used +when invoking the search tool @command{gnatfind}. +The following attributes apply to package @code{Finder}: + +@table @code +@item Default_Switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when calling @command{gnatfind} on a source +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when calling @command{gnatfind} on the named main source. +If a source is not specified in the Switches attribute, @command{gnatfind} will +be called with the options specified by Default_Switches of its language, +if defined. +@end table + +@subsection package Pretty_Printer + +@noindent +The attributes of package @code{Pretty_Printer} +specify the tool options to be used +when invoking the formatting tool @command{gnatpp}. +The following attributes apply to package @code{Pretty_Printer}: + +@table @code +@item Default_switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when calling @command{gnatpp} on a source +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when calling @command{gnatpp} on the named main source. +If a source is not specified in the Switches attribute, @command{gnatpp} will +be called with the options specified by Default_Switches of its language, +if defined. +@end table + +@subsection package gnatstub + +@noindent +The attributes of package @code{gnatstub} +specify the tool options to be used +when invoking the tool @command{gnatstub}. +The following attributes apply to package @code{gnatstub}: + +@table @code +@item Default_switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when calling @command{gnatstub} on a source +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when calling @command{gnatstub} on the named main source. +If a source is not specified in the Switches attribute, @command{gnatpp} will +be called with the options specified by Default_Switches of its language, +if defined. +@end table + +@subsection package Eliminate + +@noindent +The attributes of package @code{Eliminate} +specify the tool options to be used +when invoking the tool @command{gnatelim}. +The following attributes apply to package @code{Eliminate}: + +@table @code +@item Default_switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when calling @command{gnatelim} on a source +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when calling @command{gnatelim} on the named main source. +If a source is not specified in the Switches attribute, @command{gnatelim} will +be called with the options specified by Default_Switches of its language, +if defined. +@end table + +@subsection package Metrics + +@noindent +The attributes of package @code{Metrics} +specify the tool options to be used +when invoking the tool @command{gnatmetric}. +The following attributes apply to package @code{Metrics}: + +@table @code +@item Default_switches +This is an associative array attribute. Its +domain is a set of language names. Its range is a string list that +specifies options to be used when calling @command{gnatmetric} on a source +written in that language, for which no file-specific switches have been +specified. + +@item Switches +This is an associative array attribute. Its domain is +a set of file names. Its range is a string list that specifies +options to be used when calling @command{gnatmetric} on the named main source. +If a source is not specified in the Switches attribute, @command{gnatmetric} +will be called with the options specified by Default_Switches of its language, +if defined. +@end table + +@subsection package IDE + +@noindent +The attributes of package @code{IDE} specify the options to be used when using +an Integrated Development Environment such as @command{GPS}. + +@table @code +@item Remote_Host +This is a simple attribute. Its value is a string that designates the remote +host in a cross-compilation environment, to be used for remote compilation and +debugging. This field should not be specified when running on the local +machine. + +@item Program_Host +This is a simple attribute. Its value is a string that specifies the +name of IP address of the embedded target in a cross-compilation environment, +on which the program should execute. + +@item Communication_Protocol +This is a simple string attribute. Its value is the name of the protocol +to use to communicate with the target in a cross-compilation environment, +e.g. @code{"wtx"} or @code{"vxworks"}. + +@item Compiler_Command +This is an associative array attribute, whose domain is a language name. Its +value is string that denotes the command to be used to invoke the compiler. +The value of @code{Compiler_Command ("Ada")} is expected to be compatible with +gnatmake, in particular in the handling of switches. + +@item Debugger_Command +This is simple attribute, Its value is a string that specifies the name of +the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4. + +@item Default_Switches +This is an associative array attribute. Its indexes are the name of the +external tools that the GNAT Programming System (GPS) is supporting. Its +value is a list of switches to use when invoking that tool. + +@item Gnatlist +This is a simple attribute. Its value is a string that specifies the name +of the @command{gnatls} utility to be used to retrieve information about the +predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. + +@item VCS_Kind +This is a simple attribute. Its value is a string used to specify the +Version Control System (VCS) to be used for this project, e.g CVS, RCS +ClearCase or Perforce. + +@item VCS_File_Check +This is a simple attribute. Its value is a string that specifies the +command used by the VCS to check the validity of a file, either +when the user explicitly asks for a check, or as a sanity check before +doing the check-in. + +@item VCS_Log_Check +This is a simple attribute. Its value is a string that specifies +the command used by the VCS to check the validity of a log file. + +@end table + +@node Package Renamings +@section Package Renamings + +@noindent +A package can be defined by a renaming declaration. The new package renames +a package declared in a different project file, and has the same attributes +as the package it renames. +Syntax: +@smallexample +package_renaming ::== + @b{package} package_identifier @b{renames} + <project_>simple_name.package_identifier ; +@end smallexample + +@noindent +The package_identifier of the renamed package must be the same as the +package_identifier. The project whose name is the prefix of the renamed +package must contain a package declaration with this name. This project +must appear in the context_clause of the enclosing project declaration, +or be the parent project of the enclosing child project. + +@node Projects +@section Projects + +@noindent +A project file specifies a set of rules for constructing a software system. +A project file can be self-contained, or depend on other project files. +Dependencies are expressed through a context clause that names other projects. + +Syntax: + +@smallexample +project ::= + context_clause project_declaration + +project_declaration ::= + simple_project_declaration | project_extension + +simple_project_declaration ::= + @b{project} <project_>simple_name @b{is} + @{declarative_item@} + @b{end} <project_>simple_name; + +context_clause ::= + @{with_clause@} + +with_clause ::= + [@b{limited}] @b{with} path_name @{ , path_name @} ; + +path_name ::= + string_literal +@end smallexample + +@noindent +A path name denotes a project file. A path name can be absolute or relative. +An absolute path name includes a sequence of directories, in the syntax of +the host operating system, that identifies uniquely the project file in the +file system. A relative path name identifies the project file, relative +to the directory that contains the current project, or relative to a +directory listed in the environment variable ADA_PROJECT_PATH. +Path names are case sensitive if file names in the host operating system +are case sensitive. + +The syntax of the environment variable ADA_PROJECT_PATH is a list of +directory names separated by colons (semicolons on Windows). + +A given project name can appear only once in a context_clause. + +It is illegal for a project imported by a context clause to refer, directly +or indirectly, to the project in which this context clause appears (the +dependency graph cannot contain cycles), except when one of the with_clause +in the cycle is a @code{limited with}. + +@node Project Extensions +@section Project Extensions + +@noindent +A project extension introduces a new project, which inherits the declarations +of another project. +Syntax: +@smallexample + +project_extension ::= + @b{project} <project_>simple_name @b{extends} path_name @b{is} + @{declarative_item@} + @b{end} <project_>simple_name; +@end smallexample + +@noindent +The project extension declares a child project. The child project inherits +all the declarations and all the files of the parent project, These inherited +declaration can be overridden in the child project, by means of suitable +declarations. + +@node Project File Elaboration +@section Project File Elaboration + +@noindent +A project file is processed as part of the invocation of a gnat tool that +uses the project option. Elaboration of the process file consists in the +sequential elaboration of all its declarations. The computed values of +attributes and variables in the project are then used to establish the +environment in which the gnat tool will execute. + +@node Obsolescent Features +@chapter Obsolescent Features + +@noindent +This chapter describes features that are provided by GNAT, but are +considered obsolescent since there are preferred ways of achieving +the same effect. These features are provided solely for historical +compatibility purposes. + +@menu +* pragma No_Run_Time:: +* pragma Ravenscar:: +* pragma Restricted_Run_Time:: +@end menu + +@node pragma No_Run_Time +@section pragma No_Run_Time + +The pragma @code{No_Run_Time} is used to achieve an affect similar +to the use of the "Zero Foot Print" configurable run time, but without +requiring a specially configured run time. The result of using this +pragma, which must be used for all units in a partition, is to restrict +the use of any language features requiring run-time support code. The +preferred usage is to use an appropriately configured run-time that +includes just those features that are to be made accessible. + +@node pragma Ravenscar +@section pragma Ravenscar + +The pragma @code{Ravenscar} has exactly the same effect as pragma +@code{Profile (Ravenscar)}. The latter usage is preferred since it +is part of the new Ada 2005 standard. + +@node pragma Restricted_Run_Time +@section pragma Restricted_Run_Time + +The pragma @code{Restricted_Run_Time} has exactly the same effect as +pragma @code{Profile (Restricted)}. The latter usage is +preferred since the Ada 2005 pragma @code{Profile} is intended for +this kind of implementation dependent addition. + +@include fdl.texi +@c GNU Free Documentation License + +@node Index,,GNU Free Documentation License, Top +@unnumbered Index + +@printindex cp + +@contents + +@bye |