diff options
Diffstat (limited to 'gcc-4.7/gcc/ada/gnat_rm.texi')
| -rw-r--r-- | gcc-4.7/gcc/ada/gnat_rm.texi | 18915 |
1 files changed, 0 insertions, 18915 deletions
diff --git a/gcc-4.7/gcc/ada/gnat_rm.texi b/gcc-4.7/gcc/ada/gnat_rm.texi deleted file mode 100644 index 9b10794e5..000000000 --- a/gcc-4.7/gcc/ada/gnat_rm.texi +++ /dev/null @@ -1,18915 +0,0 @@ -\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 GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o -@c o -@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo - -@setfilename gnat_rm.info - -@copying -Copyright @copyright{} 1995-2008, Free Software Foundation, Inc. - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, 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 - -@set EDITION GNAT -@set DEFAULTLANGUAGEVERSION Ada 2005 -@set NONDEFAULTLANGUAGEVERSION Ada 95 - -@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 - -@titlepage -@title GNAT Reference Manual -@subtitle GNAT, The GNU Ada Compiler -@versionsubtitle -@author AdaCore -@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 Compiler@* -GCC version @value{version-GCC}@* - -@noindent -AdaCore - -@menu -* About This Guide:: -* Implementation Defined Pragmas:: -* Implementation Defined Attributes:: -* Implementation Defined Restrictions:: -* 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:: -* Implementation of Ada 2012 Features:: -* 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 Ada_12:: -* Pragma Ada_2012:: -* Pragma Annotate:: -* Pragma Assert:: -* Pragma Assertion_Policy:: -* Pragma Assume_No_Invalid_Values:: -* Pragma Ast_Entry:: -* Pragma C_Pass_By_Copy:: -* Pragma Check:: -* Pragma Check_Name:: -* Pragma Check_Policy:: -* Pragma Comment:: -* Pragma Common_Object:: -* Pragma Compile_Time_Error:: -* Pragma Compile_Time_Warning:: -* Pragma Compiler_Unit:: -* 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 Extensions_Allowed:: -* Pragma External:: -* Pragma External_Name_Casing:: -* Pragma Fast_Math:: -* Pragma Favor_Top_Level:: -* Pragma Finalize_Storage_Only:: -* Pragma Float_Representation:: -* Pragma Ident:: -* Pragma Implemented:: -* Pragma Implicit_Packing:: -* 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 Invariant:: -* 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:: -* Pragma Main_Storage:: -* Pragma No_Body:: -* Pragma No_Return:: -* Pragma No_Strict_Aliasing :: -* Pragma Normalize_Scalars:: -* Pragma Obsolescent:: -* Pragma Optimize_Alignment:: -* Pragma Ordered:: -* Pragma Passive:: -* Pragma Persistent_BSS:: -* Pragma Polling:: -* Pragma Postcondition:: -* Pragma Precondition:: -* Pragma Profile (Ravenscar):: -* Pragma Profile (Restricted):: -* Pragma Psect_Object:: -* Pragma Pure_Function:: -* Pragma Remote_Access_Type:: -* Pragma Restriction_Warnings:: -* Pragma Shared:: -* Pragma Short_Circuit_And_Or:: -* Pragma Short_Descriptors:: -* Pragma Simple_Storage_Pool_Type:: -* Pragma Source_File_Name:: -* Pragma Source_File_Name_Project:: -* Pragma Source_Reference:: -* Pragma Static_Elaboration_Desired:: -* Pragma Stream_Convert:: -* Pragma Style_Checks:: -* Pragma Subtitle:: -* Pragma Suppress:: -* Pragma Suppress_All:: -* Pragma Suppress_Exception_Locations:: -* Pragma Suppress_Initialization:: -* Pragma Task_Info:: -* Pragma Task_Name:: -* Pragma Task_Storage:: -* Pragma Test_Case:: -* Pragma Thread_Local_Storage:: -* Pragma Time_Slice:: -* Pragma Title:: -* Pragma Unchecked_Union:: -* Pragma Unimplemented_Unit:: -* Pragma Universal_Aliasing :: -* Pragma Universal_Data:: -* Pragma Unmodified:: -* Pragma Unreferenced:: -* Pragma Unreferenced_Objects:: -* Pragma Unreserve_All_Interrupts:: -* Pragma Unsuppress:: -* Pragma Use_VADS_Size:: -* Pragma Validity_Checks:: -* Pragma Volatile:: -* Pragma Warnings:: -* Pragma Weak_External:: -* Pragma Wide_Character_Encoding:: - -Implementation Defined Attributes - -* Abort_Signal:: -* Address_Size:: -* Asm_Input:: -* Asm_Output:: -* AST_Entry:: -* Bit:: -* Bit_Position:: -* Compiler_Version:: -* Code_Address:: -* Default_Bit_Order:: -* Descriptor_Size:: -* Elaborated:: -* Elab_Body:: -* Elab_Spec:: -* Elab_Subp_Body:: -* Emax:: -* Enabled:: -* Enum_Rep:: -* Enum_Val:: -* Epsilon:: -* Fixed_Value:: -* Has_Access_Values:: -* Has_Discriminants:: -* Img:: -* Integer_Value:: -* Invalid_Value:: -* Large:: -* Machine_Size:: -* Mantissa:: -* Max_Interrupt_Priority:: -* Max_Priority:: -* Maximum_Alignment:: -* Mechanism_Code:: -* Null_Parameter:: -* Object_Size:: -* Old:: -* Passed_By_Reference:: -* Pool_Address:: -* Range_Length:: -* Result:: -* Safe_Emax:: -* Safe_Large:: -* Simple_Storage_Pool:: -* Small:: -* Storage_Unit:: -* Stub_Type:: -* System_Allocator_Alignment:: -* 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:: - -Implementation Defined Restrictions - -* Partition-Wide Restrictions:: -* Program Unit Level Restrictions:: - -Partition-Wide Restrictions - -* Immediate_Reclamation:: -* Max_Asynchronous_Select_Nesting:: -* Max_Entry_Queue_Length:: -* Max_Protected_Entries:: -* Max_Select_Alternatives:: -* Max_Storage_At_Blocking:: -* Max_Task_Entries:: -* Max_Tasks:: -* No_Abort_Statements:: -* No_Access_Parameter_Allocators:: -* No_Access_Subprograms:: -* No_Allocators:: -* No_Anonymous_Allocators:: -* No_Calendar:: -* No_Coextensions:: -* No_Default_Initialization:: -* No_Delay:: -* No_Dependence:: -* No_Direct_Boolean_Operators:: -* No_Dispatch:: -* No_Dispatching_Calls:: -* No_Dynamic_Attachment:: -* No_Dynamic_Priorities:: -* No_Entry_Calls_In_Elaboration_Code:: -* No_Enumeration_Maps:: -* No_Exception_Handlers:: -* No_Exception_Propagation:: -* No_Exception_Registration:: -* No_Exceptions:: -* No_Finalization:: -* No_Fixed_Point:: -* No_Floating_Point:: -* No_Implicit_Conditionals:: -* No_Implicit_Dynamic_Code:: -* No_Implicit_Heap_Allocations:: -* No_Implicit_Loops:: -* No_Initialize_Scalars:: -* No_IO:: -* No_Local_Allocators:: -* No_Local_Protected_Objects:: -* No_Local_Timing_Events:: -* No_Nested_Finalization:: -* No_Protected_Type_Allocators:: -* No_Protected_Types:: -* No_Recursion:: -* No_Reentrancy:: -* No_Relative_Delay:: -* No_Requeue_Statements:: -* No_Secondary_Stack:: -* No_Select_Statements:: -* No_Specific_Termination_Handlers:: -* No_Specification_of_Aspect:: -* No_Standard_Allocators_After_Elaboration:: -* No_Standard_Storage_Pools:: -* No_Stream_Optimizations:: -* No_Streams:: -* No_Task_Allocators:: -* No_Task_Attributes_Package:: -* No_Task_Hierarchy:: -* No_Task_Termination:: -* No_Tasking:: -* No_Terminate_Alternatives:: -* No_Unchecked_Access:: -* Simple_Barriers:: -* Static_Priorities:: -* Static_Storage_Size:: - -Program Unit Level Restrictions - -* No_Elaboration_Code:: -* No_Entry_Queue:: -* No_Implementation_Aspect_Specifications:: -* No_Implementation_Attributes:: -* No_Implementation_Identifiers:: -* No_Implementation_Pragmas:: -* No_Implementation_Restrictions:: -* No_Implementation_Units:: -* No_Implicit_Aliasing:: -* No_Obsolescent_Features:: -* No_Wide_Characters:: -* SPARK:: - -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:: -* Text Translation:: -* Shared Files:: -* Filenames encoding:: -* 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-chzla1.ads):: -* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads):: -* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads):: -* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads):: -* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads):: -* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads):: -* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads):: -* Ada.Containers.Formal_Vectors (a-cofove.ads):: -* Ada.Command_Line.Environment (a-colien.ads):: -* Ada.Command_Line.Remove (a-colire.ads):: -* Ada.Command_Line.Response_File (a-clrefi.ads):: -* Ada.Direct_IO.C_Streams (a-diocst.ads):: -* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: -* Ada.Exceptions.Last_Chance_Handler (a-elchha.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.Text_IO.Reset_Standard_Files (a-tirsfi.ads):: -* Ada.Wide_Characters.Unicode (a-wichun.ads):: -* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: -* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads):: -* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads):: -* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: -* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.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.Byte_Order_Mark (g-byorma.ads):: -* GNAT.Byte_Swapping (g-bytswa.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.Decode_String (g-decstr.ads):: -* GNAT.Decode_UTF8_String (g-deutst.ads):: -* GNAT.Directory_Operations (g-dirope.ads):: -* GNAT.Directory_Operations.Iteration (g-diopit.ads):: -* GNAT.Dynamic_HTables (g-dynhta.ads):: -* GNAT.Dynamic_Tables (g-dyntab.ads):: -* GNAT.Encode_String (g-encstr.ads):: -* GNAT.Encode_UTF8_String (g-enutst.ads):: -* GNAT.Exception_Actions (g-excact.ads):: -* GNAT.Exception_Traces (g-exctra.ads):: -* GNAT.Exceptions (g-except.ads):: -* GNAT.Expect (g-expect.ads):: -* GNAT.Expect.TTY (g-exptty.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.MBBS_Discrete_Random (g-mbdira.ads):: -* GNAT.MBBS_Float_Random (g-mbflra.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.Random_Numbers (g-rannum.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.Serial_Communications (g-sercom.ads):: -* GNAT.SHA1 (g-sha1.ads):: -* GNAT.SHA224 (g-sha224.ads):: -* GNAT.SHA256 (g-sha256.ads):: -* GNAT.SHA384 (g-sha384.ads):: -* GNAT.SHA512 (g-sha512.ads):: -* GNAT.Signals (g-signal.ads):: -* GNAT.Sockets (g-socket.ads):: -* GNAT.Source_Info (g-souinf.ads):: -* GNAT.Spelling_Checker (g-speche.ads):: -* GNAT.Spelling_Checker_Generic (g-spchge.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.SSE (g-sse.ads):: -* GNAT.SSE.Vector_Types (g-ssvety.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.Time_Stamp (g-timsta.ads):: -* GNAT.Traceback (g-traceb.ads):: -* GNAT.Traceback.Symbolic (g-trasym.ads):: -* GNAT.UTF_32 (g-utf_32.ads):: -* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads):: -* GNAT.Wide_Spelling_Checker (g-wispch.ads):: -* GNAT.Wide_String_Split (g-wistsp.ads):: -* GNAT.Wide_Wide_Spelling_Checker (g-zspche.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.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.Pool_Global (s-pooglo.ads):: -* System.Pool_Local (s-pooloc.ads):: -* System.Restrictions (s-restri.ads):: -* System.Rident (s-rident.ads):: -* System.Strings.Stream_Ops (s-ststop.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 Reference Manual:: - -Implementation of Ada 2012 Features - -Obsolescent Features - -GNU Free Documentation License - -Index -@end menu - -@end ifnottex - -@node About This Guide -@unnumbered About This Guide - -@noindent -This manual contains useful information in writing programs using the -@value{EDITION} compiler. It includes information on implementation dependent -characteristics of @value{EDITION}, including all the information required by -Annex M of the Ada language standard. - -@value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in -Ada 83 compatibility mode. -By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION}, -but you can override with a compiler switch -to explicitly specify the language version. -(Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn, -@value{EDITION} User's Guide}, for details on these switches.) -Throughout this manual, references to ``Ada'' without a year suffix -apply to both the Ada 95 and Ada 2005 versions of the language. - -Ada 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 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, ``@value{EDITION}'' 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 Defined Restrictions}, lists GNAT -implementation-dependent restrictions, 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{Implementation of Ada 2012 Features}, describes the status of the -GNAT implementation of the Ada 2012 language standard. - -@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 Language Reference Manual -@cindex Ada 2005 Language Reference Manual -@noindent -This reference manual assumes a basic familiarity with the Ada 95 language, as -described in the International Standard ANSI/ISO/IEC-8652:1995, -January 1995. -It does not require knowledge of the new features introduced by Ada 2005, -(officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1 -and Amendment 1). -Both reference manuals are included in the GNAT documentation -package. - -@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}, @env{environment variables}, and @var{metasyntactic -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 -@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn, -@value{EDITION} 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 Ada 95 standard. The annotations describe -detailed aspects of the design decision, and in particular contain useful -sections on Ada 83 compatibility. - -@item -@cite{Ada 2005 Reference Manual}, which contains all reference -material for the Ada 2005 programming language. - -@item -@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version -of the Ada 2005 standard. The annotations describe -detailed aspects of the design decision, and in particular contain useful -sections on Ada 83 and Ada 95 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 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 Reference Manual. - -In addition, Ada allows implementations to define additional pragmas -whose meaning is defined by the implementation. GNAT provides a number -of these implementation-defined 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 might 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 Ada_12:: -* Pragma Ada_2012:: -* Pragma Annotate:: -* Pragma Assert:: -* Pragma Assertion_Policy:: -* Pragma Assume_No_Invalid_Values:: -* Pragma Ast_Entry:: -* Pragma C_Pass_By_Copy:: -* Pragma Check:: -* Pragma Check_Name:: -* Pragma Check_Policy:: -* Pragma Comment:: -* Pragma Common_Object:: -* Pragma Compile_Time_Error:: -* Pragma Compile_Time_Warning:: -* Pragma Compiler_Unit:: -* 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 Extensions_Allowed:: -* Pragma External:: -* Pragma External_Name_Casing:: -* Pragma Fast_Math:: -* Pragma Favor_Top_Level:: -* Pragma Finalize_Storage_Only:: -* Pragma Float_Representation:: -* Pragma Ident:: -* Pragma Implemented:: -* Pragma Implicit_Packing:: -* 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 Invariant:: -* 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:: -* Pragma Main_Storage:: -* Pragma No_Body:: -* Pragma No_Return:: -* Pragma No_Strict_Aliasing:: -* Pragma Normalize_Scalars:: -* Pragma Obsolescent:: -* Pragma Optimize_Alignment:: -* Pragma Ordered:: -* Pragma Passive:: -* Pragma Persistent_BSS:: -* Pragma Polling:: -* Pragma Postcondition:: -* Pragma Precondition:: -* Pragma Profile (Ravenscar):: -* Pragma Profile (Restricted):: -* Pragma Psect_Object:: -* Pragma Pure_Function:: -* Pragma Remote_Access_Type:: -* Pragma Restriction_Warnings:: -* Pragma Shared:: -* Pragma Short_Circuit_And_Or:: -* Pragma Short_Descriptors:: -* Pragma Simple_Storage_Pool_Type:: -* Pragma Source_File_Name:: -* Pragma Source_File_Name_Project:: -* Pragma Source_Reference:: -* Pragma Static_Elaboration_Desired:: -* Pragma Stream_Convert:: -* Pragma Style_Checks:: -* Pragma Subtitle:: -* Pragma Suppress:: -* Pragma Suppress_All:: -* Pragma Suppress_Exception_Locations:: -* Pragma Suppress_Initialization:: -* Pragma Task_Info:: -* Pragma Task_Name:: -* Pragma Task_Storage:: -* Pragma Test_Case:: -* Pragma Thread_Local_Storage:: -* Pragma Time_Slice:: -* Pragma Title:: -* Pragma Unchecked_Union:: -* Pragma Unimplemented_Unit:: -* Pragma Universal_Aliasing :: -* Pragma Universal_Data:: -* Pragma Unmodified:: -* Pragma Unreferenced:: -* Pragma Unreferenced_Objects:: -* Pragma Unreserve_All_Interrupts:: -* Pragma Unsuppress:: -* Pragma Use_VADS_Size:: -* Pragma Validity_Checks:: -* Pragma Volatile:: -* Pragma Warnings:: -* Pragma Weak_External:: -* Pragma Wide_Character_Encoding:: -@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 keywords added by Ada 95 -and Ada 2005 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 -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 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 Ada_12 -@unnumberedsec Pragma Ada_12 -@findex Ada_12 -@noindent -Syntax: -@smallexample @c ada -pragma Ada_12; -@end smallexample - -@noindent -A configuration pragma that establishes Ada 2012 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 2012 features, but which is intended to be usable from -Ada 83, Ada 95, or Ada 2005 programs. - -@node Pragma Ada_2012 -@unnumberedsec Pragma Ada_2012 -@findex Ada_2005 -@noindent -Syntax: -@smallexample @c ada -pragma Ada_2012; -@end smallexample - -@noindent -This configuration pragma is a synonym for pragma Ada_12 and has the -same syntax and effect. - -@node Pragma Annotate -@unnumberedsec Pragma Annotate -@findex Annotate -@noindent -Syntax: -@smallexample @c ada -pragma Annotate (IDENTIFIER [,IDENTIFIER @{, ARG@}]); - -ARG ::= NAME | EXPRESSION -@end smallexample - -@noindent -This pragma is used to annotate programs. @var{identifier} identifies -the type of annotation. GNAT verifies that it is an identifier, but does -not otherwise analyze it. The second optional identifier is also left -unanalyzed, and by convention is used to control the action of the tool to -which the annotation is addressed. The remaining @var{arg} arguments -can be either string literals or more generally expressions. -String literals are assumed to be either of type -@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} -depending on the character literals they contain. -All other kinds of arguments 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, except to generate corresponding note -lines in the generated ALI file. For the format of these note lines, see -the compiler source file lib-writ.ads. This pragma is intended for use by -external tools, including ASIS@. The use of pragma Annotate does not -affect the compilation process in any way. This pragma may be used as -a configuration pragma. - -@node Pragma Assert -@unnumberedsec Pragma Assert -@findex Assert -@noindent -Syntax: -@smallexample @c ada -pragma Assert ( - boolean_EXPRESSION - [, 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 @option{-gnata} not used), then there -is no run-time effect (and in particular, any side effects from the -expression will not occur at run time). (The expression is still -analyzed at compile time, 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. - -You should generally avoid side effects in the expression arguments of -this pragma, because 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. 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. - -Note that the implementation defined policy @code{DISABLE}, given in a -pragma Assertion_Policy, can be used to suppress this semantic analysis. - -Note: this is a standard language-defined pragma in versions -of Ada from 2005 on. In GNAT, it is implemented in all versions -of Ada, and the DISABLE policy is an implementation-defined -addition. - - -@node Pragma Assertion_Policy -@unnumberedsec Pragma Assertion_Policy -@findex Debug_Policy -@noindent -Syntax: - -@smallexample @c ada -pragma Assertion_Policy (CHECK | DISABLE | IGNORE); -@end smallexample - -@noindent -If the argument is @code{CHECK}, then pragma @code{Assert} is enabled. -If the argument is @code{IGNORE}, then pragma @code{Assert} is ignored. -This pragma overrides the effect of the @option{-gnata} switch on the -command line. - -The implementation defined policy @code{DISABLE} is like -@code{IGNORE} except that it completely disables semantic -checking of the argument to @code{pragma Assert}. This may -be useful when the pragma argument references subprograms -in a with'ed package which is replaced by a dummy package -for the final build. - -Note: this is a standard language-defined pragma in versions -of Ada from 2005 on. In GNAT, it is implemented in all versions -of Ada, and the DISABLE policy is an implementation-defined -addition. - -@node Pragma Assume_No_Invalid_Values -@unnumberedsec Pragma Assume_No_Invalid_Values -@findex Assume_No_Invalid_Values -@cindex Invalid representations -@cindex Invalid values -@noindent -Syntax: -@smallexample @c ada -pragma Assume_No_Invalid_Values (On | Off); -@end smallexample - -@noindent -This is a configuration pragma that controls the assumptions made by the -compiler about the occurrence of invalid representations (invalid values) -in the code. - -The default behavior (corresponding to an Off argument for this pragma), is -to assume that values may in general be invalid unless the compiler can -prove they are valid. Consider the following example: - -@smallexample @c ada -V1 : Integer range 1 .. 10; -V2 : Integer range 11 .. 20; -... -for J in V2 .. V1 loop - ... -end loop; -@end smallexample - -@noindent -if V1 and V2 have valid values, then the loop is known at compile -time not to execute since the lower bound must be greater than the -upper bound. However in default mode, no such assumption is made, -and the loop may execute. If @code{Assume_No_Invalid_Values (On)} -is given, the compiler will assume that any occurrence of a variable -other than in an explicit @code{'Valid} test always has a valid -value, and the loop above will be optimized away. - -The use of @code{Assume_No_Invalid_Values (On)} is appropriate if -you know your code is free of uninitialized variables and other -possible sources of invalid representations, and may result in -more efficient code. A program that accesses an invalid representation -with this pragma in effect is erroneous, so no guarantees can be made -about its behavior. - -It is peculiar though permissible to use this pragma in conjunction -with validity checking (-gnatVa). In such cases, accessing invalid -values will generally give an exception, though formally the program -is erroneous so there are no guarantees that this will always be the -case, and it is recommended that these two options not be used together. - -@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 the value specified for -@code{Max_Size}. -@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 Check -@unnumberedsec Pragma Check -@cindex Assertions -@cindex Named assertions -@findex Check -@noindent -Syntax: -@smallexample @c ada -pragma Check ( - [Name =>] Identifier, - [Check =>] Boolean_EXPRESSION - [, [Message =>] string_EXPRESSION] ); -@end smallexample - -@noindent -This pragma is similar to the predefined pragma @code{Assert} except that an -extra identifier argument is present. In conjunction with pragma -@code{Check_Policy}, this can be used to define groups of assertions that can -be independently controlled. The identifier @code{Assertion} is special, it -refers to the normal set of pragma @code{Assert} statements. The identifiers -@code{Precondition} and @code{Postcondition} correspond to the pragmas of these -names, so these three names would normally not be used directly in a pragma -@code{Check}. - -Checks introduced by this pragma are normally deactivated by default. They can -be activated either by the command line option @option{-gnata}, which turns on -all checks, or individually controlled using pragma @code{Check_Policy}. - -@node Pragma Check_Name -@unnumberedsec Pragma Check_Name -@cindex Defining check names -@cindex Check names, defining -@findex Check_Name -@noindent -Syntax: -@smallexample @c ada -pragma Check_Name (check_name_IDENTIFIER); -@end smallexample - -@noindent -This is a configuration pragma that defines a new implementation -defined check name (unless IDENTIFIER matches one of the predefined -check names, in which case the pragma has no effect). Check names -are global to a partition, so if two or more configuration pragmas -are present in a partition mentioning the same name, only one new -check name is introduced. - -An implementation defined check name introduced with this pragma may -be used in only three contexts: @code{pragma Suppress}, -@code{pragma Unsuppress}, -and as the prefix of a @code{Check_Name'Enabled} attribute reference. For -any of these three cases, the check name must be visible. A check -name is visible if it is in the configuration pragmas applying to -the current unit, or if it appears at the start of any unit that -is part of the dependency set of the current unit (e.g., units that -are mentioned in @code{with} clauses). - -@node Pragma Check_Policy -@unnumberedsec Pragma Check_Policy -@cindex Controlling assertions -@cindex Assertions, control -@cindex Check pragma control -@cindex Named assertions -@findex Check -@noindent -Syntax: -@smallexample @c ada -pragma Check_Policy - ([Name =>] Identifier, - [Policy =>] POLICY_IDENTIFIER); - -POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE -@end smallexample - -@noindent -This pragma is similar to the predefined pragma @code{Assertion_Policy}, -except that it controls sets of named assertions introduced using the -@code{Check} pragmas. It can be used as a configuration pragma or (unlike -@code{Assertion_Policy}) can be used within a declarative part, in which case -it controls the status to the end of the corresponding construct (in a manner -identical to pragma @code{Suppress)}. - -The identifier given as the first argument corresponds to a name used in -associated @code{Check} pragmas. For example, if the pragma: - -@smallexample @c ada -pragma Check_Policy (Critical_Error, OFF); -@end smallexample - -@noindent -is given, then subsequent @code{Check} pragmas whose first argument is also -@code{Critical_Error} will be disabled. The special identifier @code{Assertion} -controls the behavior of normal @code{Assert} pragmas (thus a pragma -@code{Check_Policy} with this identifier is similar to the normal -@code{Assertion_Policy} pragma except that it can appear within a -declarative part). - -The special identifiers @code{Precondition} and @code{Postcondition} control -the status of preconditions and postconditions. If a @code{Precondition} pragma -is encountered, it is ignored if turned off by a @code{Check_Policy} specifying -that @code{Precondition} checks are @code{Off} or @code{Ignored}. Similarly use -of the name @code{Postcondition} controls whether @code{Postcondition} pragmas -are recognized. - -The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} -to turn on corresponding checks. The default for a set of checks for which no -@code{Check_Policy} is given is @code{OFF} unless the compiler switch -@option{-gnata} is given, which turns on all checks by default. - -The check policy settings @code{CHECK} and @code{IGNORE} are also recognized -as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for -compatibility with the standard @code{Assertion_Policy} pragma. - -The implementation defined policy @code{DISABLE} is like -@code{OFF} except that it completely disables semantic -checking of the argument to the corresponding class of -pragmas. This may be useful when the pragma arguments reference -subprograms in a with'ed package which is replaced by a dummy package -for the final build. - -@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_Error -@unnumberedsec Pragma Compile_Time_Error -@findex Compile_Time_Error -@noindent -Syntax: - -@smallexample @c ada -pragma Compile_Time_Error - (boolean_EXPRESSION, static_string_EXPRESSION); -@end smallexample - -@noindent -This pragma can be used to generate additional compile time -error messages. It -is particularly useful in generics, where errors 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, an error 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 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 -Same as pragma Compile_Time_Error, except a warning is issued instead -of an error message. Note that if this pragma is used in a package that -is with'ed by a client, the client will get the warning even though it -is issued by a with'ed package (normally warnings in with'ed units are -suppressed, but this is a special exception to that rule). - -One typical use is within a generic where compile time known characteristics -of formal parameters are tested, and warnings given appropriately. Another use -with a first parameter of True is to warn a client about use of a package, -for example that it is not fully implemented. - -@node Pragma Compiler_Unit -@unnumberedsec Pragma Compiler_Unit -@findex Compiler_Unit -@noindent -Syntax: - -@smallexample @c ada -pragma Compiler_Unit; -@end smallexample - -@noindent -This pragma is intended only for internal use in the GNAT run-time library. -It indicates that the unit is used as part of the compiler build. The effect -is to disallow constructs (raise with message, conditional expressions etc) -that would cause trouble when bootstrapping using an older version of GNAT. -For the exact list of restrictions, see the compiler sources and references -to Is_Compiler_Unit. - -@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 parameterize 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 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 the C++ class has virtual primitives -then the record must be declared as a tagged record type. - -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}). Such types are implicitly -limited if not explicitly declared as limited or derived from a limited -type, and an error is issued in that case. - -Pragma @code{CPP_Class} is intended primarily for automatic generation -using an automatic binding generator tool. -See @ref{Interfacing to C++} for related information. - -Note: Pragma @code{CPP_Class} is currently obsolete. It is supported -for backward compatibility but its functionality is available -using pragma @code{Import} with @code{Convention} = @code{CPP}. - -@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 - [, [External_Name =>] static_string_EXPRESSION ] - [, [Link_Name =>] static_string_EXPRESSION ]); -@end smallexample - -@noindent -This pragma identifies an imported function (imported in the usual way -with pragma @code{Import}) as corresponding to a C++ constructor. If -@code{External_Name} and @code{Link_Name} are not specified then the -@code{Entity} argument is a name that must have been previously mentioned -in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name -must be of one of the following forms: - -@itemize @bullet -@item -@code{function @var{Fname} return @var{T}} - -@itemize @bullet -@item -@code{function @var{Fname} return @var{T}'Class} - -@item -@code{function @var{Fname} (@dots{}) return @var{T}} -@end itemize - -@item -@code{function @var{Fname} (@dots{}) return @var{T}'Class} -@end itemize - -@noindent -where @var{T} is a limited record type imported from C++ with pragma -@code{Import} and @code{Convention} = @code{CPP}. - -The first two forms import the default constructor, used when an object -of type @var{T} is created on the Ada side with no explicit constructor. -The latter two forms cover all the non-default constructors of the type. -See the GNAT users guide for details. - -If no constructors are imported, it is impossible to create any objects -on the Ada side and the type is implicitly declared abstract. - -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. - -Note: The use of functions returning class-wide types for constructors is -currently obsolete. They are supported for backward compatibility. The -use of functions returning the type T leave the Ada sources more clear -because the imported C++ constructors always return an object of type T; -that is, they never return an object whose type is a descendant of type T. - -@node Pragma CPP_Virtual -@unnumberedsec Pragma CPP_Virtual -@cindex Interfacing to C++ -@findex CPP_Virtual -@noindent -This pragma is now obsolete has has no effect because GNAT generates -the same object layout than the G++ compiler. - -See @ref{Interfacing to C++} for related information. - -@node Pragma CPP_Vtable -@unnumberedsec Pragma CPP_Vtable -@cindex Interfacing with C++ -@findex CPP_Vtable -@noindent -This pragma is now obsolete has has no effect because GNAT generates -the same object layout than the G++ compiler. - -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 @option{-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 | DISABLE | 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 @option{-gnata} switch on the -command line. - -The implementation defined policy @code{DISABLE} is like -@code{IGNORE} except that it completely disables semantic -checking of the argument to @code{pragma Debug}. This may -be useful when the pragma argument references subprograms -in a with'ed package which is replaced by a dummy package -for the final build. - -@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 @option{-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 @ref{Elaboration Order Handling in GNAT,,, -gnat_ugn, @value{EDITION} User's Guide}. - -@node Pragma Eliminate -@unnumberedsec Pragma Eliminate -@cindex Elimination of unused subprograms -@findex Eliminate -@noindent -Syntax: - -@smallexample @c ada -pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR, - [Source_Location =>] STRING_LITERAL); -@end smallexample - -@noindent -The string literal given for the source location is a string which -specifies the line number of the occurrence of the entity, using -the syntax for SOURCE_TRACE given below: - -@smallexample @c ada - SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET] - - LBRACKET ::= [ - RBRACKET ::= ] - - SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER - - LINE_NUMBER ::= DIGIT @{DIGIT@} -@end smallexample - -@noindent -Spaces around the colon in a @code{Source_Reference} are optional. - -The @code{DEFINING_DESIGNATOR} matches the defining designator used in an -explicit subprogram declaration, where the @code{entity} name in this -designator appears on the source line specified by the source location. - -The source trace that is given as the @code{Source_Location} shall obey the -following rules. The @code{FILE_NAME} is the short name (with no directory -information) of an Ada source file, given using exactly the required syntax -for the underlying file system (e.g. case is important if the underlying -operating system is case sensitive). @code{LINE_NUMBER} gives the line -number of the occurrence of the @code{entity} -as a decimal literal without an exponent or point. If an @code{entity} is not -declared in a generic instantiation (this includes generic subprogram -instances), the source trace includes only one source reference. If an entity -is declared inside a generic instantiation, its source trace (when parsing -from left to right) starts with the source location of the declaration of the -entity in the generic unit and ends with the source location of the -instantiation (it is given in square brackets). This approach is recursively -used in case of nested instantiations: the rightmost (nested most deeply in -square brackets) element of the source trace is the location of the outermost -instantiation, the next to left element is the location of the next (first -nested) instantiation in the code of the corresponding generic unit, and so -on, and the leftmost element (that is out of any square brackets) is the -location of the declaration of the entity to eliminate in a generic unit. - -Note that the @code{Source_Location} argument specifies which of a set of -similarly named entities is being eliminated, dealing both with overloading, -and also appearence of the same entity name in different scopes. - -This pragma indicates that the given entity is not used in the program to be -compiled and built. 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 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 -needing to modify the source text. Normally the required set of -@code{Eliminate} pragmas is constructed automatically using the gnatelim tool. - -Any source file change that removes, splits, or -adds lines may make the set of Eliminate pragmas invalid because their -@code{Source_Location} argument values may get out of date. - -Pragma @code{Eliminate} may be used where the referenced entity is a dispatching -operation. In this case all the subprograms to which the given operation can -dispatch are considered to be unused (are never called as a result of a direct -or a dispatching call). - -@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 -| Descriptor [([Class =>] CLASS_NAME)] -| Short_Descriptor [([Class =>] CLASS_NAME)] - -CLASS_NAME ::= ubs | ubsb | uba | s | sb | a -@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 -Passing by descriptor is supported only on the OpenVMS ports of GNAT@. -The default behavior for Export_Function is to accept either 64bit or -32bit descriptors unless short_descriptor is specified, then only 32bit -descriptors are accepted. - -@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 -| Descriptor [([Class =>] CLASS_NAME)] -| Short_Descriptor [([Class =>] CLASS_NAME)] - -CLASS_NAME ::= ubs | ubsb | uba | s | sb | a -@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 -Passing by descriptor is supported only on the OpenVMS ports of GNAT@. -The default behavior for Export_Procedure is to accept either 64bit or -32bit descriptors unless short_descriptor is specified, then only 32bit -descriptors are accepted. - -@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 -| Descriptor [([Class =>] CLASS_NAME)] -| Short_Descriptor [([Class =>] CLASS_NAME)] - -CLASS_NAME ::= ubs | ubsb | uba | s | sb | a -@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 -Passing by descriptor is supported only on the OpenVMS ports of GNAT@. -The default behavior for Export_Valued_Procedure is to accept either 64bit or -32bit descriptors unless short_descriptor is specified, then only 32bit -descriptors are accepted. - -@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 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. -@xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn, @value{EDITION} User's Guide}, -for details. - -@node Pragma Extensions_Allowed -@unnumberedsec Pragma Extensions_Allowed -@cindex Ada Extensions -@cindex GNAT Extensions -@findex Extensions_Allowed -@noindent -Syntax: - -@smallexample @c ada -pragma Extensions_Allowed (On | Off); -@end smallexample - -@noindent -This configuration pragma enables or disables the implementation -extension mode (the use of Off as a parameter cancels the effect -of the @option{-gnatX} command switch). - -In extension mode, the latest version of the Ada language is -implemented (currently Ada 2012), and in addition a small number -of GNAT specific extensions are recognized as follows: - -@table @asis -@item Constrained attribute for generic objects -The @code{Constrained} attribute is permitted for objects of -generic types. The result indicates if the corresponding actual -is constrained. - -@end table - -@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 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 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 Fast_Math -@unnumberedsec Pragma Fast_Math -@findex Fast_Math -@noindent -Syntax: - -@smallexample @c ada -pragma Fast_Math; -@end smallexample - -@noindent -This is a configuration pragma which activates a mode in which speed is -considered more important for floating-point operations than absolutely -accurate adherence to the requirements of the standard. Currently the -following operations are affected: - -@table @asis -@item Complex Multiplication -The normal simple formula for complex multiplication can result in intermediate -overflows for numbers near the end of the range. The Ada standard requires that -this situation be detected and corrected by scaling, but in Fast_Math mode such -cases will simply result in overflow. Note that to take advantage of this you -must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} -under control of the pragma, rather than use the preinstantiated versions. -@end table - -@node Pragma Favor_Top_Level -@unnumberedsec Pragma Favor_Top_Level -@findex Favor_Top_Level -@noindent -Syntax: - -@smallexample @c ada -pragma Favor_Top_Level (type_NAME); -@end smallexample - -@noindent -The named type must be an access-to-subprogram type. This pragma is an -efficiency hint to the compiler, regarding the use of 'Access or -'Unrestricted_Access on nested (non-library-level) subprograms. The -pragma means that nested subprograms are not used with this type, or -are rare, so that the generated code should be efficient in the -top-level case. When this pragma is used, dynamically generated -trampolines may be used on some targets for nested subprograms. -See also the No_Implicit_Dynamic_Code restriction. - -@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. - -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, D float format will be used. -@item -For digits values from 10 to 15, G 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 Implemented -@unnumberedsec Pragma Implemented -@findex Implemented -@noindent -Syntax: - -@smallexample @c ada -pragma Implemented (procedure_LOCAL_NAME, implementation_kind); - -implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any -@end smallexample - -@noindent -This is an Ada 2012 representation pragma which applies to protected, task -and synchronized interface primitives. The use of pragma Implemented provides -a way to impose a static requirement on the overriding operation by adhering -to one of the three implementation kids: entry, protected procedure or any of -the above. - -@smallexample @c ada -type Synch_Iface is synchronized interface; -procedure Prim_Op (Obj : in out Iface) is abstract; -pragma Implemented (Prim_Op, By_Protected_Procedure); - -protected type Prot_1 is new Synch_Iface with - procedure Prim_Op; -- Legal -end Prot_1; - -protected type Prot_2 is new Synch_Iface with - entry Prim_Op; -- Illegal -end Prot_2; - -task type Task_Typ is new Synch_Iface with - entry Prim_Op; -- Illegal -end Task_Typ; -@end smallexample - -@noindent -When applied to the procedure_or_entry_NAME of a requeue statement, pragma -Implemented determines the runtime behavior of the requeue. Implementation kind -By_Entry guarantees that the action of requeueing will proceed from an entry to -another entry. Implementation kind By_Protected_Procedure transforms the -requeue into a dispatching call, thus eliminating the chance of blocking. Kind -By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on -the target's overriding subprogram kind. - -@node Pragma Implicit_Packing -@unnumberedsec Pragma Implicit_Packing -@findex Implicit_Packing -@noindent -Syntax: - -@smallexample @c ada -pragma Implicit_Packing; -@end smallexample - -@noindent -This is a configuration pragma that requests implicit packing for packed -arrays for which a size clause is given but no explicit pragma Pack or -specification of Component_Size is present. It also applies to records -where no record representation clause is present. Consider this example: - -@smallexample @c ada -type R is array (0 .. 7) of Boolean; -for R'Size use 8; -@end smallexample - -@noindent -In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause -does not change the layout of a composite object. So the Size clause in the -above example is normally rejected, since the default layout of the array uses -8-bit components, and thus the array requires a minimum of 64 bits. - -If this declaration is compiled in a region of code covered by an occurrence -of the configuration pragma Implicit_Packing, then the Size clause in this -and similar examples will cause implicit packing and thus be accepted. For -this implicit packing to occur, the type in question must be an array of small -components whose size is known at compile time, and the Size clause must -specify the exact size that corresponds to the length of the array multiplied -by the size in bits of the component type. -@cindex Array packing - -Similarly, the following example shows the use in the record case - -@smallexample @c ada -type r is record - a, b, c, d, e, f, g, h : boolean; - chr : character; -end record; -for r'size use 16; -@end smallexample - -@noindent -Without a pragma Pack, each Boolean field requires 8 bits, so the -minimum size is 72 bits, but with a pragma Pack, 16 bits would be -sufficient. The use of pragma Implicit_Packing allows this record -declaration to compile without an explicit pragma Pack. -@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)] -| Short_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@. -The default behavior for Import_Function is to pass a 64bit descriptor -unless short_descriptor is specified, then a 32bit descriptor is passed. - -@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)] -| Short_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)] -| Short_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 @option{-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 @option{-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 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. The only difference between pragma @code{Interface} -and pragma @code{Import} is that there is special circuitry to allow -both pragmas to appear for the same subprogram entity (normally it -is illegal to have multiple @code{Import} pragmas. This is useful in -maintaining Ada 83/Ada 95 compatibility and is compatible with other -Ada 83 compilers. - -@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 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 spec 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 Invariant -@unnumberedsec Pragma Invariant -@findex Invariant -@noindent -Syntax: - -@smallexample @c ada -pragma Invariant - ([Entity =>] private_type_LOCAL_NAME, - [Check =>] EXPRESSION - [,[Message =>] String_Expression]); -@end smallexample - -@noindent -This pragma provides exactly the same capabilities as the Invariant aspect -defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The Invariant -aspect is fully implemented in Ada 2012 mode, but since it requires the use -of the aspect syntax, which is not available exception in 2012 mode, it is -not possible to use the Invariant aspect in earlier versions of Ada. However -the Invariant pragma may be used in any version of Ada. - -The pragma must appear within the visible part of the package specification, -after the type to which its Entity argument appears. As with the Invariant -aspect, the Check expression is not analyzed until the end of the visible -part of the package, so it may contain forward references. The Message -argument, if present, provides the exception message used if the invariant -is violated. If no Message parameter is provided, a default message that -identifies the line on which the pragma appears is used. - -It is permissible to have multiple Invariants for the same type entity, in -which case they are and'ed together. It is permissible to use this pragma -in Ada 2012 mode, but you cannot have both an invariant aspect and an -invariant pragma for the same entity. - -For further details on the use of this pragma, see the Ada 2012 documentation -of the Invariant aspect. - -@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. - -@node Pragma Machine_Attribute -@unnumberedsec Pragma Machine_Attribute -@findex Machine_Attribute -@noindent -Syntax: - -@smallexample @c ada -pragma Machine_Attribute ( - [Entity =>] LOCAL_NAME, - [Attribute_Name =>] static_string_EXPRESSION - [, [Info =>] static_EXPRESSION] ); -@end smallexample - -@noindent -Machine-dependent attributes can be specified for types and/or -declarations. This pragma is semantically equivalent to -@code{__attribute__((@var{attribute_name}))} (if @var{info} is not -specified) or @code{__attribute__((@var{attribute_name}(@var{info})))} -in GNU C, where @code{@var{attribute_name}} is recognized by the -compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine -specific macro. A string literal for the optional parameter @var{info} -is transformed into an identifier, which may make this pragma unusable -for some attributes. @xref{Target Attributes,, Defining target-specific -uses of @code{__attribute__}, gccint, GNU Compiler Collection (GCC) -Internals}, further information. - -@node Pragma Main -@unnumberedsec Pragma Main -@cindex OpenVMS -@findex Main -@noindent -Syntax: - -@smallexample @c ada -pragma Main - (MAIN_OPTION [, MAIN_OPTION]); - -MAIN_OPTION ::= - [Stack_Size =>] static_integer_EXPRESSION -| [Task_Stack_Size_Default =>] static_integer_EXPRESSION -| [Time_Slicing_Enabled =>] static_boolean_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. - -@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_Body -@unnumberedsec Pragma No_Body -@findex No_Body -@noindent -Syntax: - -@smallexample @c ada -pragma No_Body; -@end smallexample - -@noindent -There are a number of cases in which a package spec does not require a body, -and in fact a body is not permitted. GNAT will not permit the spec to be -compiled if there is a body around. The pragma No_Body allows you to provide -a body file, even in a case where no body is allowed. The body file must -contain only comments and a single No_Body pragma. This is recognized by -the compiler as indicating that no body is logically present. - -This is particularly useful during maintenance when a package is modified in -such a way that a body needed before is no longer needed. The provision of a -dummy body with a No_Body pragma ensures that there is no interference from -earlier versions of the package body. - -@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 @ref{Optimization and Strict -Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}. - -This pragma currently has no effects on access to unconstrained array types. - -@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; - -pragma Obsolescent ( - [Message =>] static_string_EXPRESSION -[,[Version =>] Ada_05]]); - -pragma Obsolescent ( - [Entity =>] NAME -[,[Message =>] static_string_EXPRESSION -[,[Version =>] Ada_05]] ); -@end smallexample - -@noindent -This pragma can occur immediately following a declaration of an entity, -including the case of a record component. If no Entity argument is present, -then this declaration is the one to which the pragma applies. If an Entity -parameter is present, it must either match the name of the entity in this -declaration, or alternatively, the pragma can immediately follow an enumeration -type declaration, where the Entity argument names one of the enumeration -literals. - -This pragma is used to indicate that the named entity -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 or other entities. The pragma can be used at an -intermediate stage when the entity is still present, but will be -removed later. - -The effect of this pragma is to output a warning message on a reference to -an entity thus marked that the subprogram is obsolescent if the appropriate -warning option in the compiler is activated. If the Message parameter is -present, then a second warning message is given containing this text. In -addition, a reference to the entity is considered to be 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 the entity name is the name of the package, and the -pragma 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 Version 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. - -The following examples show typical uses of this pragma: - -@smallexample @c ada -package p is - pragma Obsolescent (p, Message => "use pp instead of p"); -end p; - -package q is - procedure q2; - pragma Obsolescent ("use q2new instead"); - - type R is new integer; - pragma Obsolescent - (Entity => R, - Message => "use RR in Ada 2005", - Version => Ada_05); - - type M is record - F1 : Integer; - F2 : Integer; - pragma Obsolescent; - F3 : Integer; - end record; - - type E is (a, bc, 'd', quack); - pragma Obsolescent (Entity => bc) - pragma Obsolescent (Entity => 'd') - - function "+" - (a, b : character) return character; - pragma Obsolescent (Entity => "+"); -end; -@end smallexample - -@noindent -Note that, as for all pragmas, if you use a pragma argument identifier, -then all subsequent parameters must also use a pragma argument identifier. -So if you specify "Entity =>" for the Entity argument, and a Message -argument is present, it must be preceded by "Message =>". - -@node Pragma Optimize_Alignment -@unnumberedsec Pragma Optimize_Alignment -@findex Optimize_Alignment -@cindex Alignment, default settings -@noindent -Syntax: - -@smallexample @c ada -pragma Optimize_Alignment (TIME | SPACE | OFF); -@end smallexample - -@noindent -This is a configuration pragma which affects the choice of default alignments -for types where no alignment is explicitly specified. There is a time/space -trade-off in the selection of these values. Large alignments result in more -efficient code, at the expense of larger data space, since sizes have to be -increased to match these alignments. Smaller alignments save space, but the -access code is slower. The normal choice of default alignments (which is what -you get if you do not use this pragma, or if you use an argument of OFF), -tries to balance these two requirements. - -Specifying SPACE causes smaller default alignments to be chosen in two cases. -First any packed record is given an alignment of 1. Second, if a size is given -for the type, then the alignment is chosen to avoid increasing this size. For -example, consider: - -@smallexample @c ada - type R is record - X : Integer; - Y : Character; - end record; - - for R'Size use 5*8; -@end smallexample - -@noindent -In the default mode, this type gets an alignment of 4, so that access to the -Integer field X are efficient. But this means that objects of the type end up -with a size of 8 bytes. This is a valid choice, since sizes of objects are -allowed to be bigger than the size of the type, but it can waste space if for -example fields of type R appear in an enclosing record. If the above type is -compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. - -Specifying TIME causes larger default alignments to be chosen in the case of -small types with sizes that are not a power of 2. For example, consider: - -@smallexample @c ada - type R is record - A : Character; - B : Character; - C : Boolean; - end record; - - pragma Pack (R); - for R'Size use 17; -@end smallexample - -@noindent -The default alignment for this record is normally 1, but if this type is -compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set -to 4, which wastes space for objects of the type, since they are now 4 bytes -long, but results in more efficient access when the whole record is referenced. - -As noted above, this is a configuration pragma, and there is a requirement -that all units in a partition be compiled with a consistent setting of the -optimization setting. This would normally be achieved by use of a configuration -pragma file containing the appropriate setting. The exception to this rule is -that units with an explicit configuration pragma in the same file as the source -unit are excluded from the consistency check, as are all predefined units. The -latter are compiled by default in pragma Optimize_Alignment (Off) mode if no -pragma appears at the start of the file. - -@node Pragma Ordered -@unnumberedsec Pragma Ordered -@findex Ordered -@findex pragma @code{Ordered} -@noindent -Syntax: - -@smallexample @c ada -pragma Ordered (enumeration_first_subtype_LOCAL_NAME); -@end smallexample - -@noindent -Most enumeration types are from a conceptual point of view unordered. -For example, consider: - -@smallexample @c ada -type Color is (Red, Blue, Green, Yellow); -@end smallexample - -@noindent -By Ada semantics @code{Blue > Red} and @code{Green > Blue}, -but really these relations make no sense; the enumeration type merely -specifies a set of possible colors, and the order is unimportant. - -For unordered enumeration types, it is generally a good idea if -clients avoid comparisons (other than equality or inequality) and -explicit ranges. (A @emph{client} is a unit where the type is referenced, -other than the unit where the type is declared, its body, and its subunits.) -For example, if code buried in some client says: - -@smallexample @c ada -if Current_Color < Yellow then ... -if Current_Color in Blue .. Green then ... -@end smallexample - -@noindent -then the client code is relying on the order, which is undesirable. -It makes the code hard to read and creates maintenance difficulties if -entries have to be added to the enumeration type. Instead, -the code in the client should list the possibilities, or an -appropriate subtype should be declared in the unit that declares -the original enumeration type. E.g., the following subtype could -be declared along with the type @code{Color}: - -@smallexample @c ada -subtype RBG is Color range Red .. Green; -@end smallexample - -@noindent -and then the client could write: - -@smallexample @c ada -if Current_Color in RBG then ... -if Current_Color = Blue or Current_Color = Green then ... -@end smallexample - -@noindent -However, some enumeration types are legitimately ordered from a conceptual -point of view. For example, if you declare: - -@smallexample @c ada -type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); -@end smallexample - -@noindent -then the ordering imposed by the language is reasonable, and -clients can depend on it, writing for example: - -@smallexample @c ada -if D in Mon .. Fri then ... -if D < Wed then ... -@end smallexample - -@noindent -The pragma @option{Ordered} is provided to mark enumeration types that -are conceptually ordered, alerting the reader that clients may depend -on the ordering. GNAT provides a pragma to mark enumerations as ordered -rather than one to mark them as unordered, since in our experience, -the great majority of enumeration types are conceptually unordered. - -The types @code{Boolean}, @code{Character}, @code{Wide_Character}, -and @code{Wide_Wide_Character} -are considered to be ordered types, so each is declared with a -pragma @code{Ordered} in package @code{Standard}. - -Normally pragma @code{Ordered} serves only as documentation and a guide for -coding standards, but GNAT provides a warning switch @option{-gnatw.u} that -requests warnings for inappropriate uses (comparisons and explicit -subranges) for unordered types. If this switch is used, then any -enumeration type not marked with pragma @code{Ordered} will be considered -as unordered, and will generate warnings for inappropriate uses. - -For additional information please refer to the description of the -@option{-gnatw.u} switch in the @value{EDITION} User's Guide. - -@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 @option{-gnatP} switch. -@xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for -details. - -@node Pragma Postcondition -@unnumberedsec Pragma Postcondition -@cindex Postconditions -@cindex Checks, postconditions -@findex Postconditions -@noindent -Syntax: - -@smallexample @c ada -pragma Postcondition ( - [Check =>] Boolean_Expression - [,[Message =>] String_Expression]); -@end smallexample - -@noindent -The @code{Postcondition} pragma allows specification of automatic -postcondition checks for subprograms. These checks are similar to -assertions, but are automatically inserted just prior to the return -statements of the subprogram with which they are associated (including -implicit returns at the end of procedure bodies and associated -exception handlers). - -In addition, the boolean expression which is the condition which -must be true may contain references to function'Result in the case -of a function to refer to the returned value. - -@code{Postcondition} pragmas may appear either immediately following the -(separate) declaration of a subprogram, or at the start of the -declarations of a subprogram body. Only other pragmas may intervene -(that is appear between the subprogram declaration and its -postconditions, or appear before the postcondition in the -declaration sequence in a subprogram body). In the case of a -postcondition appearing after a subprogram declaration, the -formal arguments of the subprogram are visible, and can be -referenced in the postcondition expressions. - -The postconditions are collected and automatically tested just -before any return (implicit or explicit) in the subprogram body. -A postcondition is only recognized if postconditions are active -at the time the pragma is encountered. The compiler switch @option{gnata} -turns on all postconditions by default, and pragma @code{Check_Policy} -with an identifier of @code{Postcondition} can also be used to -control whether postconditions are active. - -The general approach is that postconditions are placed in the spec -if they represent functional aspects which make sense to the client. -For example we might have: - -@smallexample @c ada - function Direction return Integer; - pragma Postcondition - (Direction'Result = +1 - or else - Direction'Result = -1); -@end smallexample - -@noindent -which serves to document that the result must be +1 or -1, and -will test that this is the case at run time if postcondition -checking is active. - -Postconditions within the subprogram body can be used to -check that some internal aspect of the implementation, -not visible to the client, is operating as expected. -For instance if a square root routine keeps an internal -counter of the number of times it is called, then we -might have the following postcondition: - -@smallexample @c ada - Sqrt_Calls : Natural := 0; - - function Sqrt (Arg : Float) return Float is - pragma Postcondition - (Sqrt_Calls = Sqrt_Calls'Old + 1); - ... - end Sqrt -@end smallexample - -@noindent -As this example, shows, the use of the @code{Old} attribute -is often useful in postconditions to refer to the state on -entry to the subprogram. - -Note that postconditions are only checked on normal returns -from the subprogram. If an abnormal return results from -raising an exception, then the postconditions are not checked. - -If a postcondition fails, then the exception -@code{System.Assertions.Assert_Failure} is raised. If -a message argument was supplied, then the given string -will be used as the exception message. If no message -argument was supplied, then the default message has -the form "Postcondition failed at file:line". The -exception is raised in the context of the subprogram -body, so it is possible to catch postcondition failures -within the subprogram body itself. - -Within a package spec, normal visibility rules -in Ada would prevent forward references within a -postcondition pragma to functions defined later in -the same package. This would introduce undesirable -ordering constraints. To avoid this problem, all -postcondition pragmas are analyzed at the end of -the package spec, allowing forward references. - -The following example shows that this even allows -mutually recursive postconditions as in: - -@smallexample @c ada -package Parity_Functions is - function Odd (X : Natural) return Boolean; - pragma Postcondition - (Odd'Result = - (x = 1 - or else - (x /= 0 and then Even (X - 1)))); - - function Even (X : Natural) return Boolean; - pragma Postcondition - (Even'Result = - (x = 0 - or else - (x /= 1 and then Odd (X - 1)))); - -end Parity_Functions; -@end smallexample - -@noindent -There are no restrictions on the complexity or form of -conditions used within @code{Postcondition} pragmas. -The following example shows that it is even possible -to verify performance behavior. - -@smallexample @c ada -package Sort is - - Performance : constant Float; - -- Performance constant set by implementation - -- to match target architecture behavior. - - procedure Treesort (Arg : String); - -- Sorts characters of argument using N*logN sort - pragma Postcondition - (Float (Clock - Clock'Old) <= - Float (Arg'Length) * - log (Float (Arg'Length)) * - Performance); -end Sort; -@end smallexample - -@noindent -Note: postcondition pragmas associated with subprograms that are -marked as Inline_Always, or those marked as Inline with front-end -inlining (-gnatN option set) are accepted and legality-checked -by the compiler, but are ignored at run-time even if postcondition -checking is enabled. - -@node Pragma Precondition -@unnumberedsec Pragma Precondition -@cindex Preconditions -@cindex Checks, preconditions -@findex Preconditions -@noindent -Syntax: - -@smallexample @c ada -pragma Precondition ( - [Check =>] Boolean_Expression - [,[Message =>] String_Expression]); -@end smallexample - -@noindent -The @code{Precondition} pragma is similar to @code{Postcondition} -except that the corresponding checks take place immediately upon -entry to the subprogram, and if a precondition fails, the exception -is raised in the context of the caller, and the attribute 'Result -cannot be used within the precondition expression. - -Otherwise, the placement and visibility rules are identical to those -described for postconditions. The following is an example of use -within a package spec: - -@smallexample @c ada -package Math_Functions is - ... - function Sqrt (Arg : Float) return Float; - pragma Precondition (Arg >= 0.0) - ... -end Math_Functions; -@end smallexample - -@noindent -@code{Precondition} pragmas may appear either immediately following the -(separate) declaration of a subprogram, or at the start of the -declarations of a subprogram body. Only other pragmas may intervene -(that is appear between the subprogram declaration and its -postconditions, or appear before the postcondition in the -declaration sequence in a subprogram body). - -Note: postcondition pragmas associated with subprograms that are -marked as Inline_Always, or those marked as Inline with front-end -inlining (-gnatN option set) are accepted and legality-checked -by the compiler, but are ignored at run-time even if postcondition -checking is enabled. - -@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 -No task can be queued on a protected entry. -@item Max_Protected_Entries => 1 -@item Max_Task_Entries => 0 -No rendezvous statements are allowed. -@item No_Abort_Statements -@item No_Dynamic_Attachment -@item No_Dynamic_Priorities -@item No_Implicit_Heap_Allocations -@item No_Local_Protected_Objects -@item No_Local_Timing_Events -@item No_Protected_Type_Allocators -@item No_Relative_Delay -@item No_Requeue_Statements -@item No_Select_Statements -@item No_Specific_Termination_Handlers -@item No_Task_Allocators -@item No_Task_Hierarchy -@item No_Task_Termination -@item Simple_Barriers -@end table -@noindent - -The Ravenscar profile also includes the following restrictions that specify -that there are no semantic dependences on the corresponding predefined -packages: - -@table @code -@item No_Dependence => Ada.Asynchronous_Task_Control -@item No_Dependence => Ada.Calendar -@item No_Dependence => Ada.Execution_Time.Group_Budget -@item No_Dependence => Ada.Execution_Time.Timers -@item No_Dependence => Ada.Task_Attributes -@item No_Dependence => System.Multiprocessors.Dispatching_Domains -@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{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. - -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}. - -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). - -Note also that the normal rules excluding optimization of subprograms -in pure units (when parameter types are descended from System.Address, -or when the full view of a parameter type is limited), do not apply -for the Pure_Function case. If you explicitly specify Pure_Function, -the compiler may optimize away calls with identical arguments, and -if that results in unexpected behavior, the proper action is not to -use the pragma for subprograms that are not (conceptually) pure. - -@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 Remote_Access_Type -@unnumberedsec Pragma Remote_Access_Type -@findex Remote_Access_Type -@noindent -Syntax: - -@smallexample @c ada -pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); -@end smallexample - -@noindent -This pragma appears in the formal part of a generic declaration. -It specifies an exception to the RM rule from E.2.2(17/2), which forbids -the use of a remote access to class-wide type as actual for a formal -access type. - -When this pragma applies to a formal access type @code{Entity}, that -type is treated as a remote access to class-wide type in the generic. -It must be a formal general access type, and its designated type must -be the class-wide type of a formal tagged limited private type from the -same generic declaration. - -In the generic unit, the formal type is subject to all restrictions -pertaining to remote access to class-wide types. At instantiation, the -actual type must be a remote access to class-wide type. - -@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 Shared -@unnumberedsec Pragma Shared -@findex Shared - -@noindent -This pragma is provided for compatibility with Ada 83. The syntax and -semantics are identical to pragma Atomic. - -@node Pragma Short_Circuit_And_Or -@unnumberedsec Pragma Short_Circuit_And_Or -@findex Short_Circuit_And_Or - -@noindent -This configuration pragma causes any occurrence of the AND operator applied to -operands of type Standard.Boolean to be short-circuited (i.e. the AND operator -is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This -may be useful in the context of certification protocols requiring the use of -short-circuited logical operators. If this configuration pragma occurs locally -within the file being compiled, it applies only to the file being compiled. -There is no requirement that all units in a partition use this option. - -@node Pragma Short_Descriptors -@unnumberedsec Pragma Short_Descriptors -@findex Short_Descriptors -@noindent -Syntax: - -@smallexample @c ada -pragma Short_Descriptors -@end smallexample - -@noindent -In VMS versions of the compiler, this configuration pragma causes all -occurrences of the mechanism types Descriptor[_xxx] to be treated as -Short_Descriptor[_xxx]. This is helpful in porting legacy applications from a -32-bit environment to a 64-bit environment. This pragma is ignored for non-VMS -versions. - -@node Pragma Simple_Storage_Pool_Type -@unnumberedsec Pragma Simple_Storage_Pool_Type -@findex Simple_Storage_Pool_Type -@cindex Storage pool, simple -@cindex Simple storage pool -@noindent -Syntax: - -@smallexample @c ada -pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); -@end smallexample - -@noindent -A type can be established as a ``simple storage pool type'' by applying -the representation pragma @code{Simple_Storage_Pool_Type} to the type. -A type named in the pragma must be a library-level immutably limited record -type or limited tagged type declared immediately within a package declaration. -The type can also be a limited private type whose full type is allowed as -a simple storage pool type. - -For a simple storage pool type @var{SSP}, nonabstract primitive subprograms -@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that -are subtype conformant with the following subprogram declarations: - -@smallexample @c ada -procedure Allocate - (Pool : in out SSP; - Storage_Address : out System.Address; - Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; - Alignment : System.Storage_Elements.Storage_Count); - -procedure Deallocate - (Pool : in out SSP; - Storage_Address : System.Address; - Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; - Alignment : System.Storage_Elements.Storage_Count); - -function Storage_Size (Pool : SSP) - return System.Storage_Elements.Storage_Count; -@end smallexample - -@noindent -Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and -@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then -applying an unchecked deallocation has no effect other than to set its actual -parameter to null. If @code{Storage_Size} is not declared, then the -@code{Storage_Size} attribute applied to an access type associated with -a pool object of type SSP returns zero. Additional operations can be declared -for a simple storage pool type (such as for supporting a mark/release -storage-management discipline). - -An object of a simple storage pool type can be associated with an access -type by specifying the attribute @code{Simple_Storage_Pool}. For example: - -@smallexample @c ada - -My_Pool : My_Simple_Storage_Pool_Type; - -type Acc is access My_Data_Type; - -for Acc'Simple_Storage_Pool use My_Pool; - -@end smallexample - -@noindent -See attribute @code{Simple_Storage_Pool} for further details. - -@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, - [Index => INTEGER_LITERAL]); - -pragma Source_File_Name ( - [Unit_Name =>] unit_NAME, - Body_File_Name => STRING_LITERAL, - [Index => INTEGER_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. - -The optional Index argument should be used when a file contains multiple -units, and when you do not want to use @code{gnatchop} to separate then -into multiple files (which is the recommended procedure to limit the -number of recompilations that are needed when some sources change). -For instance, if the source file @file{source.ada} contains - -@smallexample @c ada -package B is -... -end B; - -with B; -procedure A is -begin - .. -end A; -@end smallexample - -you could use the following configuration pragmas: - -@smallexample @c ada -pragma Source_File_Name - (B, Spec_File_Name => "source.ada", Index => 1); -pragma Source_File_Name - (A, Body_File_Name => "source.ada", Index => 2); -@end smallexample - -Note that the @code{gnatname} utility can also be used to generate those -configuration pragmas. - -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. - -Note that Source_File_Name pragmas should not be used if you are using -project files. The reason for this rule is that the project manager is not -aware of these pragmas, and so other tools that use the projet file would not -be aware of the intended naming conventions. If you are using project files, -file naming is controlled by Source_File_Name_Project pragmas, which are -usually supplied automatically by the project manager. 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, -@xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide}, -and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION} -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 or Source_File_Name_Project 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 @option{-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 Static_Elaboration_Desired -@unnumberedsec Pragma Static_Elaboration_Desired -@findex Static_Elaboration_Desired -@noindent -Syntax: - -@smallexample @c ada -pragma Static_Elaboration_Desired; -@end smallexample - -@noindent -This pragma is used to indicate that the compiler should attempt to initialize -statically the objects declared in the library unit to which the pragma applies, -when these objects are initialized (explicitly or implicitly) by an aggregate. -In the absence of this pragma, aggregates in object declarations are expanded -into assignments and loops, even when the aggregate components are static -constants. When the aggregate is present the compiler builds a static expression -that requires no run-time code, so that the initialized object can be placed in -read-only data space. If the components are not static, or the aggregate has -more that 100 components, the compiler emits a warning that the pragma cannot -be obeyed. (See also the restriction No_Implicit_Loops, which supports static -construction of larger aggregates with static components that include an others -choice.) - -@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 -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 that -would be used for @code{Standard.String'Output}, and this same representation -is expected when a value of this type is read from the stream. Note that the -value written always includes the bounds, even for Unbounded_String'Write, -since Unbounded_String is not an array type. - -@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 @option{-gnaty} switch to @command{gcc} or @command{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. @xref{Top, -@value{EDITION} User's Guide, About This Guide, gnat_ugn, -@value{EDITION} User's Guide}, for details.) - -Note: the behavior is slightly different in GNAT mode (@option{-gnatg} used). -In this case, ALL_CHECKS implies the standard set of GNAT mode style check -options (i.e. equivalent to -gnatyg). - -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 -@unnumberedsec Pragma Suppress -@findex Suppress -@noindent -Syntax: - -@smallexample @c ada -pragma Suppress (Identifier [, [On =>] Name]); -@end smallexample - -@noindent -This is a standard pragma, and supports all the check names required in -the RM. It is included here because GNAT recognizes one additional check -name: @code{Alignment_Check} which can be used to suppress alignment checks -on addresses used in address clauses. Such checks can also be suppressed -by suppressing range checks, but the specific use of @code{Alignment_Check} -allows suppression of alignment checks without suppressing other range checks. - -Note that pragma Suppress gives the compiler permission to omit -checks, but does not require the compiler to omit checks. The compiler -will generate checks if they are essentially free, even when they are -suppressed. In particular, if the compiler can prove that a certain -check will necessarily fail, it will generate code to do an -unconditional ``raise'', even if checks are suppressed. The compiler -warns in this case. - -Of course, run-time checks are omitted whenever the compiler can prove -that they will not fail, whether or not checks are suppressed. - -@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 appear anywhere within a unit. -The effect is to apply @code{Suppress (All_Checks)} to the unit -in which it appears. This pragma is implemented for compatibility with DEC -Ada 83 usage where it appears at the end of a unit, and for compatibility -with Rational Ada, where it appears as a program unit pragma. -The use of the standard Ada 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 =>] subtype_Name); -@end smallexample - -@noindent -Here subtype_Name is the name introduced by a type declaration -or subtype declaration. -This pragma suppresses any implicit or explicit initialization -for all variables of the given type or subtype, -including initialization resulting from the use of pragmas -Normalize_Scalars or Initialize_Scalars. - -This is considered a representation item, so it cannot be given after -the type is frozen. It applies to all subsequent object declarations, -and also any allocator that creates objects of the type. - -If the pragma is given for the first subtype, then it is considered -to apply to the base type and all its subtypes. If the pragma is given -for other than a first subtype, then it applies only to the given subtype. -The pragma may not be given after the type is frozen. - -@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 spec 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 Test_Case -@unnumberedsec Pragma Test_Case -@cindex Test cases -@findex Test_Case -@noindent -Syntax: - -@smallexample @c ada -pragma Test_Case ( - [Name =>] static_string_Expression - ,[Mode =>] (Nominal | Robustness) - [, Requires => Boolean_Expression] - [, Ensures => Boolean_Expression]); -@end smallexample - -@noindent -The @code{Test_Case} pragma allows defining fine-grain specifications -for use by testing and verification tools. The compiler checks its -validity but the presence of pragma @code{Test_Case} does not lead to -any modification of the code generated by the compiler. - -@code{Test_Case} pragmas may only appear immediately following the -(separate) declaration of a subprogram in a package declaration, inside -a package spec unit. Only other pragmas may intervene (that is appear -between the subprogram declaration and a test case). - -The compiler checks that boolean expressions given in @code{Requires} and -@code{Ensures} are valid, where the rules for @code{Requires} are the -same as the rule for an expression in @code{Precondition} and the rules -for @code{Ensures} are the same as the rule for an expression in -@code{Postcondition}. In particular, attributes @code{'Old} and -@code{'Result} can only be used within the @code{Ensures} -expression. The following is an example of use within a package spec: - -@smallexample @c ada -package Math_Functions is - ... - function Sqrt (Arg : Float) return Float; - pragma Test_Case (Name => "Test 1", - Mode => Nominal, - Requires => Arg < 100, - Ensures => Sqrt'Result < 10); - ... -end Math_Functions; -@end smallexample - -@noindent -The meaning of a test case is that, if the associated subprogram is -executed in a context where @code{Requires} holds, then @code{Ensures} -should hold when the subprogram returns. Mode @code{Nominal} indicates -that the input context should satisfy the precondition of the -subprogram, and the output context should then satisfy its -postcondition. More @code{Robustness} indicates that the pre- and -postcondition of the subprogram should be ignored for this test case. - -@node Pragma Thread_Local_Storage -@unnumberedsec Pragma Thread_Local_Storage -@findex Thread_Local_Storage -@cindex Task specific storage -@cindex TLS (Thread Local Storage) -Syntax: - -@smallexample @c ada -pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); -@end smallexample - -@noindent -This pragma specifies that the specified entity, which must be -a variable declared in a library level package, is to be marked as -"Thread Local Storage" (@code{TLS}). On systems supporting this (which -include Solaris, GNU/Linux and VxWorks 6), this causes each thread -(and hence each Ada task) to see a distinct copy of the variable. - -The variable may not have default initialization, and if there is -an explicit initialization, it must be either @code{null} for an -access variable, or a static expression for a scalar variable. -This provides a low level mechanism similar to that provided by -the @code{Ada.Task_Attributes} package, but much more efficient -and is also useful in writing interface code that will interact -with foreign threads. - -If this pragma is used on a system where @code{TLS} is not supported, -then an error message will be generated and the program will be rejected. - -@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 specify a representation of a record type that is -equivalent to a C union. It was introduced as a GNAT implementation defined -pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this -pragma, making it language defined, and GNAT fully implements this extended -version in all language modes (Ada 83, Ada 95, and Ada 2005). For full -details, consult the Ada 2005 Reference Manual, section B.3.3. - -@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_Aliasing -@unnumberedsec Pragma Universal_Aliasing -@findex Universal_Aliasing -@noindent -Syntax: - -@smallexample @c ada -pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; -@end smallexample - -@noindent -@var{type_LOCAL_NAME} must refer to a type declaration in the current -declarative part. The effect is to inhibit strict type-based aliasing -optimization for the given type. In other words, the effect is as though -access types designating this type were subject to pragma No_Strict_Aliasing. -For a detailed description of the strict aliasing optimization, and the -situations in which it must be suppressed, @xref{Optimization and Strict -Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}. - -@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 Unmodified -@unnumberedsec Pragma Unmodified -@findex Unmodified -@cindex Warnings, unmodified -@noindent -Syntax: - -@smallexample @c ada -pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); -@end smallexample - -@noindent -This pragma signals that the assignable entities (variables, -@code{out} parameters, @code{in out} parameters) whose names are listed are -deliberately not assigned in the current source unit. This -suppresses warnings about the -entities being referenced but not assigned, and in addition a warning will be -generated if one of these entities is in fact assigned 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 modified, even though the spec suggests that it might -be. - -@node Pragma Unreferenced -@unnumberedsec Pragma Unreferenced -@findex Unreferenced -@cindex Warnings, unreferenced -@noindent -Syntax: - -@smallexample @c ada -pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); -pragma Unreferenced (library_unit_NAME @{, library_unit_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 subsequently 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}. - -The second form of pragma @code{Unreferenced} is used within a context -clause. In this case the arguments must be unit names of units previously -mentioned in @code{with} clauses (similar to the usage of pragma -@code{Elaborate_All}. The effect is to suppress warnings about unreferenced -units and unreferenced entities within these units. - -@node Pragma Unreferenced_Objects -@unnumberedsec Pragma Unreferenced_Objects -@findex Unreferenced_Objects -@cindex Warnings, unreferenced -@noindent -Syntax: - -@smallexample @c ada -pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); -@end smallexample - -@noindent -This pragma signals that for the types or subtypes whose names are -listed, objects which are declared with one of these types or subtypes may -not be referenced, and if no references appear, no warnings are given. - -This is particularly useful for objects which are declared solely for their -initialization and finalization effect. Such variables are sometimes referred -to as RAII variables (Resource Acquisition Is Initialization). Using this -pragma on the relevant type (most typically a limited controlled type), the -compiler will automatically suppress unwanted warnings about these variables -not being referenced. - -@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 spec 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 or Ada 2005 programs. This is intended to aid in -the handling of existing 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 @option{-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 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 / Ada 2005 -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); -pragma Warnings (On | Off, LOCAL_NAME); -pragma Warnings (static_string_EXPRESSION); -pragma Warnings (On | Off, 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 may be used as 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 single 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. For a brief summary, use the gnatmake -command with no arguments, which will generate usage information containing -the list of warnings switches supported. For -full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION} -User's Guide}. - -@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. This form of the pragma may -also be used as a configuration pragma. - -The fourth form, with an @code{On|Off} parameter and a string, is used to -control individual messages, based on their text. The string argument -is a pattern that is used to match against the text of individual -warning messages (not including the initial "warning: " tag). - -The pattern may contain asterisks, which match zero or more characters in -the message. For example, you can use -@code{pragma Warnings (Off, "*bits of*unused")} to suppress the warning -message @code{warning: 960 bits of "a" unused}. No other regular -expression notations are permitted. All characters other than asterisk in -these three specific cases are treated as literal characters in the match. - -There are two ways to use the pragma in this form. The OFF form can be used as a -configuration pragma. The effect is to suppress all warnings (if any) -that match the pattern string throughout the compilation. - -The second usage is to suppress a warning locally, and in this case, two -pragmas must appear in sequence: - -@smallexample @c ada -pragma Warnings (Off, Pattern); -@dots{} code where given warning is to be suppressed -pragma Warnings (On, Pattern); -@end smallexample - -@noindent -In this usage, the pattern string must match in the Off and On pragmas, -and at least one matching warning must be suppressed. - -Note: to write a string that will match any warning, use the string -@code{"***"}. It will not work to use a single asterisk or two asterisks -since this looks like an operator name. This form with three asterisks -is similar in effect to specifying @code{pragma Warnings (Off)} except that a -matching @code{pragma Warnings (On, "***")} will be required. This can be -helpful in avoiding forgetting to turn warnings back on. - -Note: the debug flag -gnatd.i (@code{/NOWARNINGS_PRAGMAS} in VMS) can be -used to cause the compiler to entirely ignore all WARNINGS pragmas. This can -be useful in checking whether obsolete pragmas in existing programs are hiding -real problems. - -Note: pragma Warnings does not affect the processing of style messages. See -separate entry for pragma Style_Checks for control of style messages. - -@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 Pragma Wide_Character_Encoding -@unnumberedsec Pragma Wide_Character_Encoding -@findex Wide_Character_Encoding -@noindent -Syntax: - -@smallexample @c ada -pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); -@end smallexample - -@noindent -This pragma specifies the wide character encoding to be used in program -source text appearing subsequently. It is a configuration pragma, but may -also be used at any point that a pragma is allowed, and it is permissible -to have more than one such pragma in a file, allowing multiple encodings -to appear within the same file. - -The argument can be an identifier or a character literal. In the identifier -case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, -@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal -case it is correspondingly one of the characters @samp{h}, @samp{u}, -@samp{s}, @samp{e}, @samp{8}, or @samp{b}. - -Note that when the pragma is used within a file, it affects only the -encoding within that file, and does not affect withed units, specs, -or subunits. - -@node Implementation Defined Attributes -@chapter Implementation Defined Attributes -Ada defines (throughout the Ada 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 Reference Manual. - -In addition, Ada 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:: -* Compiler_Version:: -* Code_Address:: -* Default_Bit_Order:: -* Descriptor_Size:: -* Elaborated:: -* Elab_Body:: -* Elab_Spec:: -* Elab_Subp_Body:: -* Emax:: -* Enabled:: -* Enum_Rep:: -* Enum_Val:: -* Epsilon:: -* Fixed_Value:: -* Has_Access_Values:: -* Has_Discriminants:: -* Img:: -* Integer_Value:: -* Invalid_Value:: -* Large:: -* Machine_Size:: -* Mantissa:: -* Max_Interrupt_Priority:: -* Max_Priority:: -* Maximum_Alignment:: -* Mechanism_Code:: -* Null_Parameter:: -* Object_Size:: -* Old:: -* Passed_By_Reference:: -* Pool_Address:: -* Range_Length:: -* Ref:: -* Result:: -* Safe_Emax:: -* Safe_Large:: -* Simple_Storage_Pool:: -* Small:: -* Storage_Unit:: -* Stub_Type:: -* System_Allocator_Alignment:: -* 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_Position}, 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 Compiler_Version -@unnumberedsec Compiler_Version -@findex Compiler_Version -@noindent -@code{Standard'Compiler_Version} (@code{Standard} is the only allowed -prefix) yields a static string identifying the version of the compiler -being used to compile the unit containing the attribute reference. A -typical result would be something like "@value{EDITION} @i{version} (20090221)". - -@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 and Ada 2005, but the -intended effect 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 Descriptor_Size -@unnumberedsec Descriptor_Size -@cindex Descriptor -@cindex Dope vector -@findex Descriptor_Size -@noindent -Non-static attribute @code{Descriptor_Size} returns the size in bits of the -descriptor allocated for a type. The result is non-zero only for unconstrained -array types and the returned value is of type universal integer. In GNAT, an -array descriptor contains bounds information and is located immediately before -the first element of the array. - -@smallexample @c ada -type Unconstr_Array is array (Positive range <>) of Boolean; -Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); -@end smallexample - -@noindent -The attribute takes into account any additional padding due to type alignment. -In the example above, the descriptor contains two values of type -@code{Positive} representing the low and high bound. Since @code{Positive} has -a size of 31 bits and an alignment of 4, the descriptor size is @code{2 * -Positive'Size + 2} or 64 bits. - -@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 spec 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_Subp_Body -@unnumberedsec Elab_Subp_Body -@findex Elab_Subp_Body -@noindent -This attribute can only be applied to a library level subprogram -name and is only allowed in CodePeer mode. It returns the entity -for the corresponding elaboration procedure for elaborating the body -of the referenced subprogram unit. This is used in the main generated -elaboration procedure by the binder in CodePeer mode only and is unrecognized -otherwise. - -@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 Enabled -@unnumberedsec Enabled -@findex Enabled -@noindent -The @code{Enabled} attribute allows an application program to check at compile -time to see if the designated check is currently enabled. The prefix is a -simple identifier, referencing any predefined check name (other than -@code{All_Checks}) or a check name introduced by pragma Check_Name. If -no argument is given for the attribute, the check is for the general state -of the check, if an argument is given, then it is an entity name, and the -check indicates whether an @code{Suppress} or @code{Unsuppress} has been -given naming the entity (if not, then the argument is ignored). - -Note that instantiations inherit the check status at the point of the -instantiation, so a useful idiom is to have a library package that -introduces a check name with @code{pragma Check_Name}, and then contains -generic packages or subprograms which use the @code{Enabled} attribute -to see if the check is enabled. A user of this package can then issue -a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating -the package or subprogram, controlling whether the check will be present. - -@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 Enum_Val -@unnumberedsec Enum_Val -@cindex Representation of enums -@findex Enum_Val -@noindent -For every enumeration subtype @var{S}, @code{@var{S}'Enum_Val} denotes a -function with the following spec: - -@smallexample @c ada -function @var{S}'Enum_Val (Arg : @i{Universal_Integer) - return @var{S}'Base}; -@end smallexample - -@noindent -The function returns the enumeration value whose representation matches the -argument, or raises Constraint_Error if no enumeration literal of the type -has the matching value. -This will be equal to value of the @code{Val} 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). - -@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 Invalid_Value -@unnumberedsec Invalid_Value -@findex Invalid_Value -@noindent -For every scalar type S, S'Invalid_Value returns an undefined value of the -type. If possible this value is an invalid representation for the type. The -value returned is identical to the value used to initialize an otherwise -uninitialized value of the type if pragma Initialize_Scalars is used, -including the ability to modify the value with the binder -Sxx flag and -relevant environment variables at run time. - -@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). - -@node Old -@unnumberedsec Old -@cindex Capturing Old values -@cindex Postconditions -@noindent -The attribute Prefix'Old can be used within a -subprogram body or within a precondition or -postcondition pragma. The effect is to -refer to the value of the prefix on entry. So for -example if you have an argument of a record type X called Arg1, -you can refer to Arg1.Field'Old which yields the value of -Arg1.Field on entry. The implementation simply involves generating -an object declaration which captures the value on entry. -The prefix must denote an object of a nonlimited type (since limited types -cannot be copied to capture their values) and it must not reference a local -variable (since local variables do not exist at subprogram entry time). Note -that the variable introduced by a quantified expression is a local variable. -The following example shows the use of 'Old to implement -a test of a postcondition: - -@smallexample @c ada -with Old_Pkg; -procedure Old is -begin - Old_Pkg.Incr; -end Old; - -package Old_Pkg is - procedure Incr; -end Old_Pkg; - -package body Old_Pkg is - Count : Natural := 0; - - procedure Incr is - begin - ... code manipulating the value of Count - - pragma Assert (Count = Count'Old + 1); - end Incr; -end Old_Pkg; -@end smallexample - -@noindent -Note that it is allowed to apply 'Old to a constant entity, but this will -result in a warning, since the old and new values will always be the same. - -@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 Pool_Address -@unnumberedsec Pool_Address -@cindex Parameters, when passed by reference -@findex Pool_Address -@noindent -@code{@var{X}'Pool_Address} for any object @var{X} returns the address -of X within its storage pool. This is the same as -@code{@var{X}'Address}, except that for an unconstrained array whose -bounds are allocated just before the first component, -@code{@var{X}'Pool_Address} returns the address of those bounds, -whereas @code{@var{X}'Address} returns the address of the first -component. - -Here, we are interpreting ``storage pool'' broadly to mean ``wherever -the object is allocated'', which could be a user-defined storage pool, -the global heap, on the stack, or in a static memory area. For an -object created by @code{new}, @code{@var{Ptr.all}'Pool_Address} is -what is passed to @code{Allocate} and returned from @code{Deallocate}. - -@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 Ref -@unnumberedsec Ref -@findex Ref -@noindent -The @code{System.Address'Ref} -(@code{System.Address} is the only permissible prefix) -denotes a function identical to -@code{System.Storage_Elements.To_Address} except that -it is a static attribute. See @ref{To_Address} for more details. - -@node Result -@unnumberedsec Result -@findex Result -@noindent -@code{@var{function}'Result} can only be used with in a Postcondition pragma -for a function. The prefix must be the name of the corresponding function. This -is used to refer to the result of the function in the postcondition expression. -For a further discussion of the use of this attribute and examples of its use, -see the description of pragma Postcondition. - -@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 Simple_Storage_Pool -@unnumberedsec Simple_Storage_Pool -@cindex Storage pool, simple -@cindex Simple storage pool -@findex Simple_Storage_Pool -@noindent -For every nonformal, nonderived access-to-object type @var{Acc}, the -representation attribute @code{Simple_Storage_Pool} may be specified -via an attribute_definition_clause (or by specifying the equivalent aspect): - -@smallexample @c ada - -My_Pool : My_Simple_Storage_Pool_Type; - -type Acc is access My_Data_Type; - -for Acc'Simple_Storage_Pool use My_Pool; - -@end smallexample - -@noindent -The name given in an attribute_definition_clause for the -@code{Simple_Storage_Pool} attribute shall denote a variable of -a ``simple storage pool type'' (see pragma @code{Simple_Storage_Pool_Type}). - -The use of this attribute is only allowed for a prefix denoting a type -for which it has been specified. The type of the attribute is the type -of the variable specified as the simple storage pool of the access type, -and the attribute denotes that variable. - -It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} -for the same access type. - -If the @code{Simple_Storage_Pool} attribute has been specified for an access -type, then applying the @code{Storage_Pool} attribute to the type is flagged -with a warning and its evaluation raises the exception @code{Program_Error}. - -If the Simple_Storage_Pool attribute has been specified for an access -type @var{S}, then the evaluation of the attribute @code{@var{S}'Storage_Size} -returns the result of calling @code{Storage_Size (@var{S}'Simple_Storage_Pool)}, -which is intended to indicate the number of storage elements reserved for -the simple storage pool. If the Storage_Size function has not been defined -for the simple storage pool type, then this attribute returns zero. - -If an access type @var{S} has a specified simple storage pool of type -@var{SSP}, then the evaluation of an allocator for that access type calls -the primitive @code{Allocate} procedure for type @var{SSP}, passing -@code{@var{S}'Simple_Storage_Pool} as the pool parameter. The detailed -semantics of such allocators is the same as those defined for allocators -in section 13.11 of the Ada Reference Manual, with the term -``simple storage pool'' substituted for ``storage pool''. - -If an access type @var{S} has a specified simple storage pool of type -@var{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} -for that access type invokes the primitive @code{Deallocate} procedure -for type @var{SSP}, passing @code{@var{S}'Simple_Storage_Pool} as the pool -parameter. The detailed semantics of such unchecked deallocations is the same -as defined in section 13.11.2 of the Ada Reference Manual, except that the -term ``simple storage pool'' is substituted for ``storage pool''. - -@node Small -@unnumberedsec Small -@cindex Ada 83 attributes -@findex Small -@noindent -The @code{Small} attribute is defined in Ada 95 (and Ada 2005) 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 Stub_Type -@unnumberedsec Stub_Type -@findex Stub_Type -@noindent -The GNAT implementation of remote access-to-classwide types is -organized as described in AARM section E.4 (20.t): a value of an RACW type -(designating a remote object) is represented as a normal access -value, pointing to a "stub" object which in turn contains the -necessary information to contact the designated remote object. A -call on any dispatching operation of such a stub object does the -remote call, if necessary, using the information in the stub object -to locate the target partition, etc. - -For a prefix @code{T} that denotes a remote access-to-classwide type, -@code{T'Stub_Type} denotes the type of the corresponding stub objects. - -By construction, the layout of @code{T'Stub_Type} is identical to that of -type @code{RACW_Stub_Type} declared in the internal implementation-defined -unit @code{System.Partition_Interface}. Use of this attribute will create -an implicit dependency on this unit. - -@node System_Allocator_Alignment -@unnumberedsec System_Allocator_Alignment -@cindex Alignment, allocator -@findex System_Allocator_Alignment -@noindent -@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only -permissible prefix) provides the observable guaranted to be honored by -the system allocator (malloc). This is a static value that can be used -in user storage pools based on malloc either to reject allocation -with alignment too large or to enable a realignment circuitry if the -alignment request is larger than this value. - -@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). - -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 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}. - -@node Implementation Defined Restrictions -@chapter Implementation Defined Restrictions - -@noindent -All RM defined Restriction identifiers are implemented: - -@itemize @bullet -@item language-defined restrictions (see 13.12.1) -@item tasking restrictions (see D.7) -@item high integrity restrictions (see H.4) -@end itemize - -@noindent -GNAT implements additional restriction identifiers. All restrictions, whether -language defined or GNAT-specific, are listed in the following. - -@menu -* Partition-Wide Restrictions:: -* Program Unit Level Restrictions:: -@end menu - -@node Partition-Wide Restrictions -@section Partition-Wide Restrictions - -There are two separate lists of 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). - -@menu -* Immediate_Reclamation:: -* Max_Asynchronous_Select_Nesting:: -* Max_Entry_Queue_Length:: -* Max_Protected_Entries:: -* Max_Select_Alternatives:: -* Max_Storage_At_Blocking:: -* Max_Task_Entries:: -* Max_Tasks:: -* No_Abort_Statements:: -* No_Access_Parameter_Allocators:: -* No_Access_Subprograms:: -* No_Allocators:: -* No_Anonymous_Allocators:: -* No_Calendar:: -* No_Coextensions:: -* No_Default_Initialization:: -* No_Delay:: -* No_Dependence:: -* No_Direct_Boolean_Operators:: -* No_Dispatch:: -* No_Dispatching_Calls:: -* No_Dynamic_Attachment:: -* No_Dynamic_Priorities:: -* No_Entry_Calls_In_Elaboration_Code:: -* No_Enumeration_Maps:: -* No_Exception_Handlers:: -* No_Exception_Propagation:: -* No_Exception_Registration:: -* No_Exceptions:: -* No_Finalization:: -* No_Fixed_Point:: -* No_Floating_Point:: -* No_Implicit_Conditionals:: -* No_Implicit_Dynamic_Code:: -* No_Implicit_Heap_Allocations:: -* No_Implicit_Loops:: -* No_Initialize_Scalars:: -* No_IO:: -* No_Local_Allocators:: -* No_Local_Protected_Objects:: -* No_Local_Timing_Events:: -* No_Nested_Finalization:: -* No_Protected_Type_Allocators:: -* No_Protected_Types:: -* No_Recursion:: -* No_Reentrancy:: -* No_Relative_Delay:: -* No_Requeue_Statements:: -* No_Secondary_Stack:: -* No_Select_Statements:: -* No_Specific_Termination_Handlers:: -* No_Specification_of_Aspect:: -* No_Standard_Allocators_After_Elaboration:: -* No_Standard_Storage_Pools:: -* No_Stream_Optimizations:: -* No_Streams:: -* No_Task_Allocators:: -* No_Task_Attributes_Package:: -* No_Task_Hierarchy:: -* No_Task_Termination:: -* No_Tasking:: -* No_Terminate_Alternatives:: -* No_Unchecked_Access:: -* Simple_Barriers:: -* Static_Priorities:: -* Static_Storage_Size:: -@end menu - -@node Immediate_Reclamation -@unnumberedsubsec Immediate_Reclamation -@findex Immediate_Reclamation -[RM H.4] This restriction ensures that, except for storage occupied by -objects created by allocators and not deallocated via unchecked -deallocation, any storage reserved at run time for an object is -immediately reclaimed when the object no longer exists. - -@node Max_Asynchronous_Select_Nesting -@unnumberedsubsec Max_Asynchronous_Select_Nesting -@findex Max_Asynchronous_Select_Nesting -[RM D.7] Specifies the maximum dynamic nesting level of asynchronous -selects. Violations of this restriction with a value of zero are -detected at compile time. Violations of this restriction with values -other than zero cause Storage_Error to be raised. - -@node Max_Entry_Queue_Length -@unnumberedsubsec Max_Entry_Queue_Length -@findex Max_Entry_Queue_Length -[RM D.7] 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. -Note that this restriction is checked at run time. Violation of this -restriction results in the raising of Program_Error exception at the point of -the call. - -@node Max_Protected_Entries -@unnumberedsubsec Max_Protected_Entries -@findex Max_Protected_Entries -[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. - -@node Max_Select_Alternatives -@unnumberedsubsec Max_Select_Alternatives -@findex Max_Select_Alternatives -[RM D.7] Specifies the maximum number of alternatives in a selective accept. - -@node Max_Storage_At_Blocking -@unnumberedsubsec Max_Storage_At_Blocking -@findex Max_Storage_At_Blocking -[RM D.7] Specifies the maximum portion (in storage elements) of a task's -Storage_Size that can be retained by a blocked task. A violation of this -restriction causes Storage_Error to be raised. - -@node Max_Task_Entries -@unnumberedsubsec Max_Task_Entries -@findex Max_Task_Entries -[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. - -@node Max_Tasks -@unnumberedsubsec Max_Tasks -@findex Max_Tasks -[RM D.7] Specifies the maximum number of task that may be created, not -counting the creation of the environment task. Violations of this -restriction with a value of zero are detected at compile -time. Violations of this restriction with values other than zero cause -Storage_Error to be raised. - -@node No_Abort_Statements -@unnumberedsubsec No_Abort_Statements -@findex No_Abort_Statements -[RM D.7] There are no abort_statements, and there are -no calls to Task_Identification.Abort_Task. - -@node No_Access_Parameter_Allocators -@unnumberedsubsec No_Access_Parameter_Allocators -@findex No_Access_Parameter_Allocators -[RM H.4] This restriction ensures at compile time that there are no -occurrences of an allocator as the actual parameter to an access -parameter. - -@node No_Access_Subprograms -@unnumberedsubsec No_Access_Subprograms -@findex No_Access_Subprograms -[RM H.4] This restriction ensures at compile time that there are no -declarations of access-to-subprogram types. - -@node No_Allocators -@unnumberedsubsec No_Allocators -@findex No_Allocators -[RM H.4] This restriction ensures at compile time that there are no -occurrences of an allocator. - -@node No_Anonymous_Allocators -@unnumberedsubsec No_Anonymous_Allocators -@findex No_Anonymous_Allocators -[RM H.4] This restriction ensures at compile time that there are no -occurrences of an allocator of anonymous access type. - -@node No_Calendar -@unnumberedsubsec No_Calendar -@findex No_Calendar -[GNAT] This restriction ensures at compile time that there is no implicit or -explicit dependence on the package @code{Ada.Calendar}. - -@node No_Coextensions -@unnumberedsubsec No_Coextensions -@findex No_Coextensions -[RM H.4] This restriction ensures at compile time that there are no -coextensions. See 3.10.2. - -@node No_Default_Initialization -@unnumberedsubsec No_Default_Initialization -@findex No_Default_Initialization - -[GNAT] This restriction prohibits any instance of default initialization -of variables. The binder implements a consistency rule which prevents -any unit compiled without the restriction from with'ing a unit with the -restriction (this allows the generation of initialization procedures to -be skipped, since you can be sure that no call is ever generated to an -initialization procedure in a unit with the restriction active). If used -in conjunction with Initialize_Scalars or Normalize_Scalars, the effect -is to prohibit all cases of variables declared without a specific -initializer (including the case of OUT scalar parameters). - -@node No_Delay -@unnumberedsubsec No_Delay -@findex No_Delay -[RM H.4] This restriction ensures at compile time that there are no -delay statements and no dependences on package Calendar. - -@node No_Dependence -@unnumberedsubsec No_Dependence -@findex No_Dependence -[RM 13.12.1] This restriction checks at compile time that there are no -dependence on a library unit. - -@node No_Direct_Boolean_Operators -@unnumberedsubsec No_Direct_Boolean_Operators -@findex No_Direct_Boolean_Operators -[GNAT] This restriction ensures that no logical (and/or/xor) 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. - -@node No_Dispatch -@unnumberedsubsec No_Dispatch -@findex No_Dispatch -[RM H.4] This restriction ensures at compile time that there are no -occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. - -@node No_Dispatching_Calls -@unnumberedsubsec No_Dispatching_Calls -@findex No_Dispatching_Calls -[GNAT] 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, classwide membership tests and other classwide -features not involving implicit dispatching. This restriction 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 class-wide objects assignments. The -membership test is allowed in the presence of this restriction, because its -implementation requires no dispatching. -This restriction is comparable to the official Ada restriction -@code{No_Dispatch} except that it is a bit less restrictive in that it allows -all classwide constructs that do not imply 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 - C : T'Class := O; -- Error: implicit 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 - -@node No_Dynamic_Attachment -@unnumberedsubsec No_Dynamic_Attachment -@findex No_Dynamic_Attachment -[RM D.7] This restriction ensures that 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). - -@node No_Dynamic_Priorities -@unnumberedsubsec No_Dynamic_Priorities -@findex No_Dynamic_Priorities -[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. - -@node No_Entry_Calls_In_Elaboration_Code -@unnumberedsubsec No_Entry_Calls_In_Elaboration_Code -@findex No_Entry_Calls_In_Elaboration_Code -[GNAT] 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. - -@node No_Enumeration_Maps -@unnumberedsubsec No_Enumeration_Maps -@findex No_Enumeration_Maps -[GNAT] This restriction ensures at compile time that no operations requiring -enumeration maps are used (that is Image and Value attributes applied -to enumeration types). - -@node No_Exception_Handlers -@unnumberedsubsec No_Exception_Handlers -@findex No_Exception_Handlers -[GNAT] 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: - -@smallexample @c ada -procedure Last_Chance_Handler - (Source_Location : System.Address; Line : Integer); -pragma Export (C, Last_Chance_Handler, - "__gnat_last_chance_handler"); -@end smallexample - -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. - -@node No_Exception_Propagation -@unnumberedsubsec No_Exception_Propagation -@findex No_Exception_Propagation -[GNAT] This restriction guarantees that exceptions are never propagated -to an outer subprogram scope. The only case in which an exception may -be raised is when the handler is statically in the same subprogram, so -that the effect of a raise is essentially like a goto statement. Any -other raise statement (implicit or explicit) will be considered -unhandled. Exception handlers are allowed, but may not contain an -exception occurrence identifier (exception choice). In addition, use of -the package GNAT.Current_Exception is not permitted, and reraise -statements (raise with no operand) are not permitted. - -@node No_Exception_Registration -@unnumberedsubsec No_Exception_Registration -@findex No_Exception_Registration -[GNAT] 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. - -@node No_Exceptions -@unnumberedsubsec No_Exceptions -@findex No_Exceptions -[RM H.4] This restriction ensures at compile time that there are no -raise statements and no exception handlers. - -@node No_Finalization -@unnumberedsubsec No_Finalization -@findex No_Finalization -[GNAT] This restriction disables the language features described in -chapter 7.6 of the Ada 2005 RM as well as all form of code generation -performed by the compiler to support these features. The following types -are no longer considered controlled when this restriction is in effect: -@itemize @bullet -@item -@code{Ada.Finalization.Controlled} -@item -@code{Ada.Finalization.Limited_Controlled} -@item -Derivations from @code{Controlled} or @code{Limited_Controlled} -@item -Class-wide types -@item -Protected types -@item -Task types -@item -Array and record types with controlled components -@end itemize -The compiler no longer generates code to initialize, finalize or adjust an -object or a nested component, either declared on the stack or on the heap. The -deallocation of a controlled object no longer finalizes its contents. - -@node No_Fixed_Point -@unnumberedsubsec No_Fixed_Point -@findex No_Fixed_Point -[RM H.4] This restriction ensures at compile time that there are no -occurrences of fixed point types and operations. - -@node No_Floating_Point -@unnumberedsubsec No_Floating_Point -@findex No_Floating_Point -[RM H.4] This restriction ensures at compile time that there are no -occurrences of floating point types and operations. - -@node No_Implicit_Conditionals -@unnumberedsubsec No_Implicit_Conditionals -@findex No_Implicit_Conditionals -[GNAT] 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. - -@node No_Implicit_Dynamic_Code -@unnumberedsubsec No_Implicit_Dynamic_Code -@findex No_Implicit_Dynamic_Code -@cindex trampoline -[GNAT] 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. On some targets, a trampoline is -built for the following features: @code{Access}, -@code{Unrestricted_Access}, or @code{Address} of a nested subprogram; -nested task bodies; primitive operations of nested tagged types. -Trampolines do not work on machines that prevent execution of stack -data. For example, on windows systems, enabling DEP (data execution -protection) will cause trampolines to raise an exception. -Trampolines are also quite slow at run time. - -On many targets, trampolines have been largely eliminated. Look at the -version of system.ads for your target --- if it has -Always_Compatible_Rep equal to False, then trampolines are largely -eliminated. In particular, a trampoline is built for the following -features: @code{Address} of a nested subprogram; -@code{Access} or @code{Unrestricted_Access} of a nested subprogram, -but only if pragma Favor_Top_Level applies, or the access type has a -foreign-language convention; primitive operations of nested tagged -types. - -@node No_Implicit_Heap_Allocations -@unnumberedsubsec No_Implicit_Heap_Allocations -@findex No_Implicit_Heap_Allocations -[RM D.7] No constructs are allowed to cause implicit heap allocation. - -@node No_Implicit_Loops -@unnumberedsubsec No_Implicit_Loops -@findex No_Implicit_Loops -[GNAT] 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. If this restriction is active, it is possible to build -large array aggregates with all static components without generating an -intermediate temporary, and without generating a loop to initialize individual -components. Otherwise, a loop is created for arrays larger than about 5000 -scalar components. - -@node No_Initialize_Scalars -@unnumberedsubsec No_Initialize_Scalars -@findex No_Initialize_Scalars -[GNAT] 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. - -@node No_IO -@unnumberedsubsec No_IO -@findex No_IO -[RM H.4] This restriction ensures at compile time that there are no -dependences on any of the library units Sequential_IO, Direct_IO, -Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. - -@node No_Local_Allocators -@unnumberedsubsec No_Local_Allocators -@findex No_Local_Allocators -[RM H.4] This restriction ensures at compile time that there are no -occurrences of an allocator in subprograms, generic subprograms, tasks, -and entry bodies. - -@node No_Local_Protected_Objects -@unnumberedsubsec No_Local_Protected_Objects -@findex No_Local_Protected_Objects -[RM D.7] This restriction ensures at compile time that protected objects are -only declared at the library level. - -@node No_Local_Timing_Events -@unnumberedsubsec No_Local_Timing_Events -@findex No_Local_Timing_Events -[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are -declared at the library level. - -@node No_Nested_Finalization -@unnumberedsubsec No_Nested_Finalization -@findex No_Nested_Finalization -[RM D.7] All objects requiring finalization are declared at the library level. - -@node No_Protected_Type_Allocators -@unnumberedsubsec No_Protected_Type_Allocators -@findex No_Protected_Type_Allocators -[RM D.7] This restriction ensures at compile time that there are no allocator -expressions that attempt to allocate protected objects. - -@node No_Protected_Types -@unnumberedsubsec No_Protected_Types -@findex No_Protected_Types -[RM H.4] This restriction ensures at compile time that there are no -declarations of protected types or protected objects. - -@node No_Recursion -@unnumberedsubsec No_Recursion -@findex No_Recursion -[RM H.4] A program execution is erroneous if a subprogram is invoked as -part of its execution. - -@node No_Reentrancy -@unnumberedsubsec No_Reentrancy -@findex No_Reentrancy -[RM H.4] A program execution is erroneous if a subprogram is executed by -two tasks at the same time. - -@node No_Relative_Delay -@unnumberedsubsec No_Relative_Delay -@findex No_Relative_Delay -[RM D.7] This restriction ensures at compile time that there are no delay -relative statements and prevents expressions such as @code{delay 1.23;} from -appearing in source code. - -@node No_Requeue_Statements -@unnumberedsubsec No_Requeue_Statements -@findex No_Requeue_Statements -[RM D.7] This restriction ensures at compile time that no requeue statements -are permitted and prevents keyword @code{requeue} from being used in source -code. - -@node No_Secondary_Stack -@unnumberedsubsec No_Secondary_Stack -@findex No_Secondary_Stack -[GNAT] 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. - -@node No_Select_Statements -@unnumberedsubsec No_Select_Statements -@findex No_Select_Statements -[RM D.7] This restriction ensures at compile time no select statements of any -kind are permitted, that is the keyword @code{select} may not appear. - -@node No_Specific_Termination_Handlers -@unnumberedsubsec No_Specific_Termination_Handlers -@findex No_Specific_Termination_Handlers -[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler -or to Ada.Task_Termination.Specific_Handler. - -@node No_Specification_of_Aspect -@unnumberedsubsec No_Specification_of_Aspect -@findex No_Specification_of_Aspect -[RM 13.12.1] This restriction checks at compile time that no aspect -specification, attribute definition clause, or pragma is given for a -given aspect. - -@node No_Standard_Allocators_After_Elaboration -@unnumberedsubsec No_Standard_Allocators_After_Elaboration -@findex No_Standard_Allocators_After_Elaboration -[RM D.7] Specifies that an allocator using a standard storage pool -should never be evaluated at run time after the elaboration of the -library items of the partition has completed. Otherwise, Storage_Error -is raised. - -@node No_Standard_Storage_Pools -@unnumberedsubsec No_Standard_Storage_Pools -@findex No_Standard_Storage_Pools -[GNAT] 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. - -@node No_Stream_Optimizations -@unnumberedsubsec No_Stream_Optimizations -@findex No_Stream_Optimizations -[GNAT] This restriction affects the performance of stream operations on types -@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the -compiler uses block reads and writes when manipulating @code{String} objects -due to their supperior performance. When this restriction is in effect, the -compiler performs all IO operations on a per-character basis. - -@node No_Streams -@unnumberedsubsec No_Streams -@findex No_Streams -[GNAT] This restriction ensures at compile/bind time that there are no -stream objects created and no use of stream attributes. -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 and no -stream attributes are used. - -Note that the use of restriction allows optimization of tagged types, -since they do not need to worry about dispatching stream operations. -To take maximum advantage of this space-saving optimization, any -unit declaring a tagged type should be compiled with the restriction, -though this is not required. - -@node No_Task_Allocators -@unnumberedsubsec No_Task_Allocators -@findex No_Task_Allocators -[RM D.7] There are no allocators for task types -or types containing task subcomponents. - -@node No_Task_Attributes_Package -@unnumberedsubsec No_Task_Attributes_Package -@findex No_Task_Attributes_Package -[GNAT] This restriction ensures at compile time that there are no implicit or -explicit dependencies on the package @code{Ada.Task_Attributes}. - -@node No_Task_Hierarchy -@unnumberedsubsec No_Task_Hierarchy -@findex No_Task_Hierarchy -[RM D.7] All (non-environment) tasks depend -directly on the environment task of the partition. - -@node No_Task_Termination -@unnumberedsubsec No_Task_Termination -@findex No_Task_Termination -[RM D.7] Tasks which terminate are erroneous. - -@node No_Tasking -@unnumberedsubsec No_Tasking -@findex No_Tasking -[GNAT] 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. - -@node No_Terminate_Alternatives -@unnumberedsubsec No_Terminate_Alternatives -@findex No_Terminate_Alternatives -[RM D.7] There are no selective accepts with terminate alternatives. - -@node No_Unchecked_Access -@unnumberedsubsec No_Unchecked_Access -@findex No_Unchecked_Access -[RM H.4] This restriction ensures at compile time that there are no -occurrences of the Unchecked_Access attribute. - -@node Simple_Barriers -@unnumberedsubsec Simple_Barriers -@findex Simple_Barriers -[RM D.7] 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. - -@node Static_Priorities -@unnumberedsubsec Static_Priorities -@findex Static_Priorities -[GNAT] This restriction ensures at compile time that all priority expressions -are static, and that there are no dependences on the package -@code{Ada.Dynamic_Priorities}. - -@node Static_Storage_Size -@unnumberedsubsec Static_Storage_Size -@findex Static_Storage_Size -[GNAT] This restriction ensures at compile time that any expression appearing -in a Storage_Size pragma or attribute definition clause is static. - -@node Program Unit Level Restrictions -@section Program Unit Level Restrictions - -@noindent -The second set of 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. - -@menu -* No_Elaboration_Code:: -* No_Entry_Queue:: -* No_Implementation_Aspect_Specifications:: -* No_Implementation_Attributes:: -* No_Implementation_Identifiers:: -* No_Implementation_Pragmas:: -* No_Implementation_Restrictions:: -* No_Implementation_Units:: -* No_Implicit_Aliasing:: -* No_Obsolescent_Features:: -* No_Wide_Characters:: -* SPARK:: -@end menu - -@node No_Elaboration_Code -@unnumberedsubsec No_Elaboration_Code -@findex No_Elaboration_Code -[GNAT] 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. - -In the case of aggregates with others, if the aggregate has a dynamic -size, there is no way to eliminate the elaboration code (such dynamic -bounds would be incompatible with @code{Preelaborate} in any case). If -the bounds are static, then use of this restriction actually modifies -the code choice of the compiler to avoid generating a loop, and instead -generate the aggregate statically if possible, no matter how many times -the data for the others clause must be repeatedly generated. - -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. - -Note that this the implementation of this restriction requires full -code generation. If it is used in conjunction with "semantics only" -checking, then some cases of violations may be missed. - -@node No_Entry_Queue -@unnumberedsubsec No_Entry_Queue -@findex No_Entry_Queue -[GNAT] 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. - -@node No_Implementation_Aspect_Specifications -@unnumberedsubsec No_Implementation_Aspect_Specifications -@findex No_Implementation_Aspect_Specifications -[RM 13.12.1] This restriction checks at compile time that no -GNAT-defined aspects are present. With this restriction, the only -aspects that can be used are those defined in the Ada Reference Manual. - -@node No_Implementation_Attributes -@unnumberedsubsec No_Implementation_Attributes -@findex No_Implementation_Attributes -[RM 13.12.1] 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 Reference -Manual. - -@node No_Implementation_Identifiers -@unnumberedsubsec No_Implementation_Identifiers -@findex No_Implementation_Identifiers -[RM 13.12.1] This restriction checks at compile time that no -implementation-defined identifiers occur within language-defined -packages. - -@node No_Implementation_Pragmas -@unnumberedsubsec No_Implementation_Pragmas -@findex No_Implementation_Pragmas -[RM 13.12.1] 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 Reference Manual. - -@node No_Implementation_Restrictions -@unnumberedsubsec No_Implementation_Restrictions -@findex No_Implementation_Restrictions -[GNAT] 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 Reference Manual. - -@node No_Implementation_Units -@unnumberedsubsec No_Implementation_Units -@findex No_Implementation_Units -[RM 13.12.1] This restriction checks at compile time that there is no -mention in the context clause of any implementation-defined descendants -of packages Ada, Interfaces, or System. - -@node No_Implicit_Aliasing -@unnumberedsubsec No_Implicit_Aliasing -@findex No_Implicit_Aliasing -[GNAT] This restriction, which is not required to be partition-wide consistent, -requires an explicit aliased keyword for an object to which 'Access, -'Unchecked_Access, or 'Address is applied, and forbids entirely the use of -the 'Unrestricted_Access attribute for objects. Note: the reason that -Unrestricted_Access is forbidden is that it would require the prefix -to be aliased, and in such cases, it can always be replaced by -the standard attribute Unchecked_Access which is preferable. - -@node No_Obsolescent_Features -@unnumberedsubsec No_Obsolescent_Features -@findex No_Obsolescent_Features -[RM 13.12.1] This restriction checks at compile time that no obsolescent -features are used, as defined in Annex J of the Ada Reference Manual. - -@node No_Wide_Characters -@unnumberedsubsec No_Wide_Characters -@findex No_Wide_Characters -[GNAT] 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}. - -@node SPARK -@unnumberedsubsec SPARK -@findex SPARK -[GNAT] This restriction checks at compile time that some constructs -forbidden in SPARK are not present. The SPARK version used as a -reference is the same as the Ada mode for the unit, so a unit compiled -in Ada 95 mode with SPARK restrictions will be checked for constructs -forbidden in SPARK 95. Error messages related to SPARK restriction have -the form: - -@smallexample -violation of restriction "SPARK" at <file> - <error message> -@end smallexample - -This is not a replacement for the semantic checks performed by the -SPARK Examiner tool, as the compiler only deals currently with code, -not at all with SPARK annotations and does not guarantee catching all -cases of constructs forbidden by SPARK. - -Thus it may well be the case that code which -passes the compiler in SPARK mode is rejected by the SPARK Examiner, -e.g. due to the different visibility rules of the Examiner based on -SPARK @code{inherit} annotations. - -This restriction can be useful in providing an initial filter for -code developed using SPARK, or in examining legacy code to see how far -it is from meeting SPARK restrictions. - -@c ------------------------ -@node Implementation Advice -@chapter Implementation Advice -@noindent -The main text of the Ada Reference Manual describes the required -behavior of all Ada compilers, and the GNAT compiler conforms to -these requirements. - -In addition, there are sections throughout the Ada 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 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 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. But note that this can be overridden by use of the implementation -pragma Implicit_Packing in the case of packed arrays. - -@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-stratt-xdr.adb} in the GNAT library. -There is no @file{s-stratt-xdr.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-stratt-default.adb -$ mv s-stratt-xdr.adb s-stratt.adb -@end smallexample - -@item -Rebuild the GNAT run-time library as documented in -@ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} 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 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. Two implementation-defined locking policies are defined, -whose names (@code{Inheritance_Locking} and -@code{Concurrent_Readers_Locking}) follow 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 Ada features that are -potentially implementation dependent and are designated as -implementation-defined. These are mentioned throughout the Ada 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 -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 and 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 (on most 64 bit targets, depending on the C definition of long). -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 @command{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 @option{-z} and @option{-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 @ref{The GNAT Make Program gnatmake,,, gnat_ugn, -@value{EDITION} User's Guide}. - -@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 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 -The implementation defined check name Alignment_Check controls checking of -address clause values for proper alignment (that is, the address supplied -must be consistent with the alignment of the type). - -In addition, a user program can add implementation-defined check names -by means of the pragma Check_Name. - -@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 semantics of operations on invalid representations. -See 13.9.2(10-11). -@end cartouche -@noindent -For assignments and other operations where the use of invalid values cannot -result in erroneous behavior, the compiler ignores the possibility of invalid -values. An exception is raised at the point where an invalid value would -result in erroneous behavior. For example executing: - -@smallexample @c ada -procedure invalidvals is - X : Integer := -1; - Y : Natural range 1 .. 10; - for Y'Address use X'Address; - Z : Natural range 1 .. 10; - A : array (Natural range 1 .. 10) of Integer; -begin - Z := Y; -- no exception - A (Z) := 3; -- exception raised; -end; -@end smallexample - -@noindent -As indicated, an exception is raised on the array assignment, but not -on the simple assignment of the invalid negative value from Y to Z. - -@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 -@xref{Implementation Defined Restrictions}. - -@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 6864, see library file @file{s-rannum.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 6864, see library file @file{s-rannum.ads}. - -@sp 1 -@cartouche -@noindent -@strong{65}. The algorithms for random number generation. See -A.5.2(32). -@end cartouche -@noindent -The algorithm is the Mersenne Twister, as documented in the source file -@file{s-rannum.adb}. This version of the algorithm has a period of -2**19937-1. - -@sp 1 -@cartouche -@noindent -@strong{66}. The string representation of a random number generator's -state. See A.5.2(38). -@end cartouche -@noindent -The value returned by the Image function is the concatenation of -the fixed-width decimal representations of the 624 32-bit integers -of the state vector. - -@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 -Run the compiler with @option{-gnatS} to produce a listing of package -@code{Standard}, has 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}. The interpretation of the @code{Form} parameter in procedure -@code{Create_Directory}. See A.16(56). -@end cartouche -@noindent -The @code{Form} parameter is not used. - -@sp 1 -@cartouche -@noindent -@strong{75}. The interpretation of the @code{Form} parameter in procedure -@code{Create_Path}. See A.16(60). -@end cartouche -@noindent -The @code{Form} parameter is not used. - -@sp 1 -@cartouche -@noindent -@strong{76}. The interpretation of the @code{Form} parameter in procedure -@code{Copy_File}. See A.16(68). -@end cartouche -@noindent -The @code{Form} parameter is case-insensitive. - -Two fields are recognized in the @code{Form} parameter: - -@table @code - -@item preserve=<value> - -@item mode=<value> - -@end table - -@noindent -<value> starts immediately after the character '=' and ends with the -character immediately preceding the next comma (',') or with the last -character of the parameter. - -The only possible values for preserve= are: - -@table @code - -@item no_attributes -Do not try to preserve any file attributes. This is the default if no -preserve= is found in Form. - -@item all_attributes -Try to preserve all file attributes (timestamps, access rights). - -@item timestamps -Preserve the timestamp of the copied file, but not the other file attributes. - -@end table - -@noindent -The only possible values for mode= are: - -@table @code - -@item copy -Only do the copy if the destination file does not already exist. If it already -exists, Copy_File fails. - -@item overwrite -Copy the file in all cases. Overwrite an already existing destination file. - -@item append -Append the original file to the destination file. If the destination file does -not exist, the destination file is a copy of the source file. When mode=append, -the field preserve=, if it exists, is not taken into account. - -@end table - -@noindent -If the Form parameter includes one or both of the fields and the value or -values are incorrect, Copy_file fails with Use_Error. - -Examples of correct Forms: - -@smallexample -Form => "preserve=no_attributes,mode=overwrite" (the default) -Form => "mode=append" -Form => "mode=copy, preserve=all_attributes" -@end smallexample - -@noindent -Examples of incorrect Forms - -@smallexample -Form => "preserve=junk" -Form => "mode=internal, preserve=timestamps" -@end smallexample - -@sp 1 -@cartouche -@noindent -@strong{77}. Implementation-defined convention names. See B.1(11). -@end cartouche -@noindent -The following convention names are supported - -@table @code -@item Ada -Ada -@item Ada_Pass_By_Copy -Allowed for any types except by-reference types such as limited -records. Compatible with convention Ada, but causes any parameters -with this convention to be passed by copy. -@item Ada_Pass_By_Reference -Allowed for any types except by-copy types such as scalars. -Compatible with convention Ada, but causes any parameters -with this convention to be passed by reference. -@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 C_Plus_Plus (or 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 routine with this convention cleans the stack before -exit. This pragma cannot be applied to a dispatching call. -@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{78}. 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{79}. 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{80}. 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 for a body always appear before the options -from the corresponding package spec. - -@sp 1 -@cartouche -@noindent -@strong{81}. 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{82}. 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{83}. 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{84}. 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{85}. 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{86}. 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{87}. 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{88}. 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{89}. The result of the @code{Task_Identification.Image} -attribute. See C.7.1(7). -@end cartouche -@noindent -The result of this attribute is a string that identifies -the object or component that denotes a given task. If a variable @code{Var} -has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}}, -where the suffix -is the hexadecimal representation of the virtual address of the corresponding -task control block. If the variable is an array of tasks, the image of each -task will have the form of an indexed component indicating the position of a -given task in the array, e.g.@: @code{Group(5)_@var{XXXXXXX}}. If the task is a -component of a record, the image of the task will have the form of a selected -component. These rules are fully recursive, so that the image of a task that -is a subcomponent of a composite object corresponds to the expression that -designates this task. -@noindent -If a task is created by an allocator, its image depends on the context. If the -allocator is part of an object declaration, the rules described above are used -to construct its image, and this image is not affected by subsequent -assignments. If the allocator appears within an expression, the image -includes only the name of the task type. -@noindent -If the configuration pragma Discard_Names is present, or if the restriction -No_Implicit_Heap_Allocation is in effect, the image reduces to -the numeric suffix, that is to say the hexadecimal representation of the -virtual address of the control block of the task. -@sp 1 -@cartouche -@noindent -@strong{90}. 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{91}. 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{92}. 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{93}. 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 @option{-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{94}. 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{95}. Implementation-defined execution resources. See D.1(15). -@end cartouche -@noindent -There are no implementation-defined execution resources. - -@sp 1 -@cartouche -@noindent -@strong{96}. 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{97}. 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{98}. 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{99}. 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{100}. 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{101}. Implementation-defined @code{policy_identifiers} allowed -in a pragma @code{Locking_Policy}. See D.3(4). -@end cartouche -@noindent -The two implementation defined policies permitted in GNAT are -@code{Inheritance_Locking} and @code{Conccurent_Readers_Locking}. On -targets that support the @code{Inheritance_Locking} 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. On targets that support the -@code{Conccurent_Readers_Locking} policy, locking is implemented with a -read/write lock allowing multiple propected object functions to enter -concurrently. - -@sp 1 -@cartouche -@noindent -@strong{102}. 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 -Reference Manual D.3(10), - -@sp 1 -@cartouche -@noindent -@strong{103}. 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{104}. Implementation-defined queuing policies. See D.4(1). -@end cartouche -@noindent -There are no implementation-defined queuing policies. - -@sp 1 -@cartouche -@noindent -@strong{105}. 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{106}. 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{107}. 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{108}. 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{109}. 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{110}. 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{111}. 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{112}. 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{113}. 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{114}. 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{115}. 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{116}. 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{117}. 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{118}. 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{119}. 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{120}. 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{121}. 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{122}. 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{123}. 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{124}. 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{125}. 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{126}. 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 conforming behavior (although at the cost -of a significant performance penalty), so infinite and NaN values are -properly generated. - -@sp 1 -@cartouche -@noindent -@strong{127}. 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{128}. 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{129}. 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{130}. 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{131}. 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{132}. 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{133}. 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{134}. 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{135}. 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{136}. 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{137}. 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{138}. 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{139}. 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:: -* Shifts and Rotates:: -* 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 Shifts and Rotates -@section Shifts and Rotates -@cindex Shift_Left -@cindex Shift_Right -@cindex Shift_Right_Arithmetic -@cindex Rotate_Left -@cindex Rotate_Right -@noindent -In standard Ada, the shift and rotate functions are available only -for the predefined modular types in package @code{Interfaces}. However, in -GNAT it is possible to define these functions for any integer -type (signed or modular), as in this example: - -@smallexample @c ada - function Shift_Left - (Value : T; - Amount : Natural) - return T; -@end smallexample - -@noindent -The function name must be one of -Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or -Rotate_Right. T must be an integer type. T'Size must be -8, 16, 32 or 64 bits; if T is modular, the modulus -must be 2**8, 2**16, 2**32 or 2**64. -The result type must be the same as the type of @code{Value}. -The shift amount must be Natural. -The formal parameter names can be anything. - -@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 components are packable (see separate section on pragma -@code{Pack}), then the resulting alignment is 1, unless the layout of the -record makes it profitable to increase it. - -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 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}). It may also specify -a smaller alignment than the default value for enumeration, integer and -fixed point types, as well as for record types, for example - -@smallexample @c ada - type V is record - A : Integer; - 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 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 @option{-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 and Ada 2005, @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 and Ada 2005, -@code{Natural'Size} is -typically 31. This means that code may change in behavior when moving -from Ada 83 to Ada 95 or Ada 2005. 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 Ada 2005, 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 -Reference Manual, 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 array 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. A first case is 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. -A second case is when the subtype of the component is a record type -padded because of its default alignment. For example, if we have: - -@smallexample @c ada -type r is record - i : Integer; - j : Integer; - b : Boolean; -end record; - -type a is array (1 .. 8) of r; -for a'Component_Size use 72; -@end smallexample - -@noindent -then the resulting array has a length of 72 bytes, instead of 96 bytes -if the alignment of the record (4) was obeyed. - -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 -Warnings (Off)} 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 -@item -Any record type padded because of its default alignment -@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 and Ada 2005, -subtype @code{Natural} typically has a size of 31, meaning that if you -pack an array of @code{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 and Ada 2005, @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 nonnegative, 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. - -@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 the special GNAT -check Alignment_Check is suppressed, or if -@code{pragma Restrictions (No_Elaboration_Code)} is in effect. - -Finally, GNAT does not permit overlaying of objects of controlled types or -composite types containing a controlled component. In most cases, the compiler -can detect an attempt at such overlays and will generate a warning at compile -time and a Program_Error exception at run time. - -@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 and Ada 2005 -the effect is implementation defined. Furthermore, the -Ada 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 four 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. - -Note that this treatment applies only to types. If Convention C is given for -an enumeration object, where the enumeration type is not Convention C, then -Object_Size bits are allocated. For example, for a normal enumeration type, -with less than 256 elements, only 8 bits will be allocated for the object. -Since this may be a surprise in terms of what C expects, GNAT will issue a -warning in this situation. The warning can be suppressed by giving an explicit -size clause specifying the desired size. - -@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. - -@item Access types on OpenVMS -For 64-bit OpenVMS systems, access types (other than those for unconstrained -arrays) are 64-bits long. An exception to this rule is for the case of -C-convention access types where there is no explicit size clause present (or -inherited for derived types). In this case, GNAT chooses to make these -pointers 32-bits, which provides an easier path for migration of 32-bit legacy -code. size clause specifying 64-bits must be used to obtain a 64-bit pointer. - -@end itemize - -@node Determining the Representations chosen by GNAT -@section Determining the Representations chosen by GNAT -@cindex Representation, determination of -@cindex @option{-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 @option{-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 @option{-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 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 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 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 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 @dots{} GIVING @dots{} REMAINDER @dots{}) - -@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 generic package provides a random number generator suitable for generating -uniformly distributed values of a specified discrete subtype. - -@item Ada.Numerics.Float_Random -This package provides a random number generator suitable for generating -uniformly distributed floating point values in the unit interval. - -@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 and Ada 2005. -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 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 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:: -* Text Translation:: -* Shared Files:: -* Filenames encoding:: -* 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 -the following keywords defined. - -@smallexample -TEXT_TRANSLATION=[YES|NO] -SHARED=[YES|NO] -WCEM=[n|h|u|s|e|8|b] -ENCODING=[UTF8|8BITS] -@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 and Ada 2005, 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 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 @var{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#}. - -Note that brackets coding is not normally used in the context of -Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as -a portable way of encoding source files. In the context of Wide_Text_IO -or Wide_Wide_Text_IO, it can only be used if the file does not contain -any instance of the left bracket character other than to encode wide -character values using the brackets encoding method. In practice it is -expected that some standard wide character encoding method such -as UTF-8 will be used for text input output. - -If brackets notation is used, then any occurrence of a left bracket -in the input file which is not the start of a valid wide character -sequence will cause Constraint_Error to be raised. It is possible to -encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO -input will interpret this as a left bracket. - -However, when a left bracket is output, it will be output as a left bracket -and not as ["5B"]. We make this decision because for normal use of -Wide_Text_IO for outputting messages, it is unpleasant to clobber left -brackets. For example, if we write: - -@smallexample - Put_Line ("Start of output [first run]"); -@end smallexample - -@noindent -we really do not want to have the left bracket in this message clobbered so -that the output reads: - -@smallexample - Start of output ["5B"]first run] -@end smallexample - -@noindent -In practice brackets encoding is reasonably useful for normal Put_Line use -since we won't get confused between left brackets and wide character -sequences in the output. But for input, or when files are written out -and read back in, it really makes better sense to use one of the standard -encoding methods such as UTF-8. - -@end table - -@noindent -For the coding schemes other than UTF-8, Hex, or 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 @var{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 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 Text Translation -@section Text Translation - -@noindent -@samp{Text_Translation=@var{xxx}} may be used as the Form parameter -passed to Text_IO.Create and Text_IO.Open: -@samp{Text_Translation=@var{Yes}} is the default, which means to -translate LF to/from CR/LF on Windows systems. -@samp{Text_Translation=@var{No}} disables this translation; i.e. it -uses binary mode. For output files, @samp{Text_Translation=@var{No}} -may be used to create Unix-style files on -Windows. @samp{Text_Translation=@var{xxx}} has no effect on Unix -systems. - -@node Shared Files -@section Shared Files - -@noindent -Section A.14 of the Ada 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 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 to use Stream_IO -for this purpose (using the stream attributes) - -@node Filenames encoding -@section Filenames encoding - -@noindent -An encoding form parameter can be used to specify the filename -encoding @samp{encoding=@var{xxx}}. - -@itemize @bullet -@item -If the form parameter @samp{encoding=utf8} appears in the form string, the -filename must be encoded in UTF-8. - -@item -If the form parameter @samp{encoding=8bits} appears in the form -string, the filename must be a standard 8bits string. -@end itemize - -In the absence of a @samp{encoding=@var{xxx}} form parameter, the -encoding is controlled by the @samp{GNAT_CODE_PAGE} environment -variable. And if not set @samp{utf8} is assumed. - -@table @samp -@item CP_ACP -The current system Windows ANSI code page. -@item CP_UTF8 -UTF-8 encoding -@end table - -This encoding form parameter is only supported on the Windows -platform. On the other Operating Systems the run-time is supporting -UTF-8 natively. - -@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 UNIX (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-chzla1.ads):: -* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads):: -* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads):: -* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads):: -* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads):: -* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads):: -* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads):: -* Ada.Containers.Formal_Vectors (a-cofove.ads):: -* Ada.Command_Line.Environment (a-colien.ads):: -* Ada.Command_Line.Remove (a-colire.ads):: -* Ada.Command_Line.Response_File (a-clrefi.ads):: -* Ada.Direct_IO.C_Streams (a-diocst.ads):: -* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: -* Ada.Exceptions.Last_Chance_Handler (a-elchha.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.Text_IO.Reset_Standard_Files (a-tirsfi.ads):: -* Ada.Wide_Characters.Unicode (a-wichun.ads):: -* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: -* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads):: -* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads):: -* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: -* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.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.Byte_Order_Mark (g-byorma.ads):: -* GNAT.Byte_Swapping (g-bytswa.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.Decode_String (g-decstr.ads):: -* GNAT.Decode_UTF8_String (g-deutst.ads):: -* GNAT.Directory_Operations (g-dirope.ads):: -* GNAT.Directory_Operations.Iteration (g-diopit.ads):: -* GNAT.Dynamic_HTables (g-dynhta.ads):: -* GNAT.Dynamic_Tables (g-dyntab.ads):: -* GNAT.Encode_String (g-encstr.ads):: -* GNAT.Encode_UTF8_String (g-enutst.ads):: -* GNAT.Exception_Actions (g-excact.ads):: -* GNAT.Exception_Traces (g-exctra.ads):: -* GNAT.Exceptions (g-except.ads):: -* GNAT.Expect (g-expect.ads):: -* GNAT.Expect.TTY (g-exptty.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.MBBS_Discrete_Random (g-mbdira.ads):: -* GNAT.MBBS_Float_Random (g-mbflra.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.Random_Numbers (g-rannum.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.Serial_Communications (g-sercom.ads):: -* GNAT.SHA1 (g-sha1.ads):: -* GNAT.SHA224 (g-sha224.ads):: -* GNAT.SHA256 (g-sha256.ads):: -* GNAT.SHA384 (g-sha384.ads):: -* GNAT.SHA512 (g-sha512.ads):: -* GNAT.Signals (g-signal.ads):: -* GNAT.Sockets (g-socket.ads):: -* GNAT.Source_Info (g-souinf.ads):: -* GNAT.Spelling_Checker (g-speche.ads):: -* GNAT.Spelling_Checker_Generic (g-spchge.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.SSE (g-sse.ads):: -* GNAT.SSE.Vector_Types (g-ssvety.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.Time_Stamp (g-timsta.ads):: -* GNAT.Traceback (g-traceb.ads):: -* GNAT.Traceback.Symbolic (g-trasym.ads):: -* GNAT.UTF_32 (g-utf_32.ads):: -* GNAT.UTF_32_Spelling_Checker (g-u3spch.ads):: -* GNAT.Wide_Spelling_Checker (g-wispch.ads):: -* GNAT.Wide_String_Split (g-wistsp.ads):: -* GNAT.Wide_Wide_Spelling_Checker (g-zspche.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.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.Pool_Global (s-pooglo.ads):: -* System.Pool_Local (s-pooloc.ads):: -* System.Restrictions (s-restri.ads):: -* System.Rident (s-rident.ads):: -* System.Strings.Stream_Ops (s-ststop.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.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.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.3(27)). - -@node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) -@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads}) -@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.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.3(27)). - -@node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) -@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads}) -@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.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.3(27)). - -@node Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) -@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads}) -@cindex @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads}) -@cindex Formal container for doubly linked lists - -@noindent -This child of @code{Ada.Containers} defines a modified version of the Ada 2005 -container for doubly linked lists, meant to facilitate formal verification of -code using such containers. - -@node Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) -@section @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads}) -@cindex @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads}) -@cindex Formal container for hashed maps - -@noindent -This child of @code{Ada.Containers} defines a modified version of the Ada 2005 -container for hashed maps, meant to facilitate formal verification of -code using such containers. - -@node Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) -@section @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads}) -@cindex @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads}) -@cindex Formal container for hashed sets - -@noindent -This child of @code{Ada.Containers} defines a modified version of the Ada 2005 -container for hashed sets, meant to facilitate formal verification of -code using such containers. - -@node Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) -@section @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads}) -@cindex @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads}) -@cindex Formal container for ordered maps - -@noindent -This child of @code{Ada.Containers} defines a modified version of the Ada 2005 -container for ordered maps, meant to facilitate formal verification of -code using such containers. - -@node Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) -@section @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads}) -@cindex @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads}) -@cindex Formal container for ordered sets - -@noindent -This child of @code{Ada.Containers} defines a modified version of the Ada 2005 -container for ordered sets, meant to facilitate formal verification of -code using such containers. - -@node Ada.Containers.Formal_Vectors (a-cofove.ads) -@section @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads}) -@cindex @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads}) -@cindex Formal container for vectors - -@noindent -This child of @code{Ada.Containers} defines a modified version of the Ada 2005 -container for vectors, meant to facilitate formal verification of -code using such containers. - -@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.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.Response_File (a-clrefi.ads) -@section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads}) -@cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads}) -@cindex Response file for command line -@cindex Command line, response file -@cindex Command line, handling long command lines - -@noindent -This child of @code{Ada.Command_Line} provides a mechanism facilities for -getting command line arguments from a text file, called a "response file". -Using a response file allow passing a set of arguments to an executable longer -than the maximum allowed by the system on the command line. - -@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.Last_Chance_Handler (a-elchha.ads) -@section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads}) -@cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads}) -@cindex Null_Occurrence, testing for - -@noindent -This child subprogram is used for handling otherwise unhandled -exceptions (hence the name last chance), and perform clean ups before -terminating the program. Note that this subprogram never returns. - -@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.Text_IO.Reset_Standard_Files (a-tirsfi.ads) -@section @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads}) -@cindex @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads}) -@cindex @code{Text_IO} resetting standard files - -@noindent -This procedure is used to reset the status of the standard files used -by Ada.Text_IO. This is useful in a situation (such as a restart in an -embedded application) where the status of the files may change during -execution (for example a standard input file may be redefined to be -interactive). - -@node Ada.Wide_Characters.Unicode (a-wichun.ads) -@section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads}) -@cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads}) -@cindex Unicode categorization, Wide_Character - -@noindent -This package provides subprograms that allow categorization of -Wide_Character values according to Unicode categories. - -@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_Text_IO.Reset_Standard_Files (a-wrstfi.ads) -@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads}) -@cindex @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads}) -@cindex @code{Wide_Text_IO} resetting standard files - -@noindent -This procedure is used to reset the status of the standard files used -by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an -embedded application) where the status of the files may change during -execution (for example a standard input file may be redefined to be -interactive). - -@node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) -@section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads}) -@cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads}) -@cindex Unicode categorization, Wide_Wide_Character - -@noindent -This package provides subprograms that allow categorization of -Wide_Wide_Character values according to Unicode categories. - -@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 Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) -@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads}) -@cindex @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads}) -@cindex @code{Wide_Wide_Text_IO} resetting standard files - -@noindent -This procedure is used to reset the status of the standard files used -by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a -restart in an embedded application) where the status of the files may -change during execution (for example a standard input file may be -redefined to be interactive). - -@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.Byte_Order_Mark (g-byorma.ads) -@section @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads}) -@cindex @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads}) -@cindex UTF-8 representation -@cindex Wide characte representations - -@noindent -Provides a routine which given a string, reads the start of the string to -see whether it is one of the standard byte order marks (BOM's) which signal -the encoding of the string. The routine includes detection of special XML -sequences for various UCS input formats. - -@node GNAT.Byte_Swapping (g-bytswa.ads) -@section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads}) -@cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads}) -@cindex Byte swapping -@cindex Endian - -@noindent -General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. -Machine-specific implementations are available in some cases. - -@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@. - -@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 / Ada 2005 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. @xref{The GNAT Debug Pool Facility,,, gnat_ugn, -@value{EDITION} 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.Decode_String (g-decstr.ads) -@section @code{GNAT.Decode_String} (@file{g-decstr.ads}) -@cindex @code{GNAT.Decode_String} (@file{g-decstr.ads}) -@cindex Decoding strings -@cindex String decoding -@cindex Wide character encoding -@cindex UTF-8 -@cindex Unicode - -@noindent -A generic package providing routines for decoding wide character and wide wide -character strings encoded as sequences of 8-bit characters using a specified -encoding method. Includes validation routines, and also routines for stepping -to next or previous encoded character in an encoded string. -Useful in conjunction with Unicode character coding. Note there is a -preinstantiation for UTF-8. See next entry. - -@node GNAT.Decode_UTF8_String (g-deutst.ads) -@section @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads}) -@cindex @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads}) -@cindex Decoding strings -@cindex Decoding UTF-8 strings -@cindex UTF-8 string decoding -@cindex Wide character decoding -@cindex UTF-8 -@cindex Unicode - -@noindent -A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. - -@node GNAT.Directory_Operations (g-dirope.ads) -@section @code{GNAT.Directory_Operations} (@file{g-dirope.ads}) -@cindex @code{GNAT.Directory_Operations} (@file{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.Directory_Operations.Iteration (g-diopit.ads) -@section @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads}) -@cindex @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads}) -@cindex Directory operations iteration - -@noindent -A child unit of GNAT.Directory_Operations providing additional operations -for iterating through directories. - -@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.Encode_String (g-encstr.ads) -@section @code{GNAT.Encode_String} (@file{g-encstr.ads}) -@cindex @code{GNAT.Encode_String} (@file{g-encstr.ads}) -@cindex Encoding strings -@cindex String encoding -@cindex Wide character encoding -@cindex UTF-8 -@cindex Unicode - -@noindent -A generic package providing routines for encoding wide character and wide -wide character strings as sequences of 8-bit characters using a specified -encoding method. Useful in conjunction with Unicode character coding. -Note there is a preinstantiation for UTF-8. See next entry. - -@node GNAT.Encode_UTF8_String (g-enutst.ads) -@section @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads}) -@cindex @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads}) -@cindex Encoding strings -@cindex Encoding UTF-8 strings -@cindex UTF-8 string encoding -@cindex Wide character encoding -@cindex UTF-8 -@cindex Unicode - -@noindent -A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. - -@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.Expect.TTY (g-exptty.ads) -@section @code{GNAT.Expect.TTY} (@file{g-exptty.ads}) -@cindex @code{GNAT.Expect.TTY} (@file{g-exptty.ads}) - -@noindent -As GNAT.Expect but using pseudo-terminal. -Currently @code{GNAT.Expect.TTY} 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.MBBS_Discrete_Random (g-mbdira.ads) -@section @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads}) -@cindex @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads}) -@cindex Random number generation - -@noindent -The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses -a modified version of the Blum-Blum-Shub generator. - -@node GNAT.MBBS_Float_Random (g-mbflra.ads) -@section @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads}) -@cindex @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads}) -@cindex Random number generation - -@noindent -The original implementation of @code{Ada.Numerics.Float_Random}. Uses -a modified version of the Blum-Blum-Shub generator. - -@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.Random_Numbers (g-rannum.ads) -@section @code{GNAT.Random_Numbers} (@file{g-rannum.ads}) -@cindex @code{GNAT.Random_Numbers} (@file{g-rannum.ads}) -@cindex Random number generation - -@noindent -Provides random number capabilities which extend those available in the -standard Ada library and are more convenient to use. - -@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.Serial_Communications (g-sercom.ads) -@section @code{GNAT.Serial_Communications} (@file{g-sercom.ads}) -@cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads}) -@cindex Serial_Communications - -@noindent -Provides a simple interface to send and receive data over a serial -port. This is only supported on GNU/Linux and Windows. - -@node GNAT.SHA1 (g-sha1.ads) -@section @code{GNAT.SHA1} (@file{g-sha1.ads}) -@cindex @code{GNAT.SHA1} (@file{g-sha1.ads}) -@cindex Secure Hash Algorithm SHA-1 - -@noindent -Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 -and RFC 3174. - -@node GNAT.SHA224 (g-sha224.ads) -@section @code{GNAT.SHA224} (@file{g-sha224.ads}) -@cindex @code{GNAT.SHA224} (@file{g-sha224.ads}) -@cindex Secure Hash Algorithm SHA-224 - -@noindent -Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3. - -@node GNAT.SHA256 (g-sha256.ads) -@section @code{GNAT.SHA256} (@file{g-sha256.ads}) -@cindex @code{GNAT.SHA256} (@file{g-sha256.ads}) -@cindex Secure Hash Algorithm SHA-256 - -@noindent -Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3. - -@node GNAT.SHA384 (g-sha384.ads) -@section @code{GNAT.SHA384} (@file{g-sha384.ads}) -@cindex @code{GNAT.SHA384} (@file{g-sha384.ads}) -@cindex Secure Hash Algorithm SHA-384 - -@noindent -Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3. - -@node GNAT.SHA512 (g-sha512.ads) -@section @code{GNAT.SHA512} (@file{g-sha512.ads}) -@cindex @code{GNAT.SHA512} (@file{g-sha512.ads}) -@cindex Secure Hash Algorithm SHA-512 - -@noindent -Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3. - -@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.Spelling_Checker (g-speche.ads) -@section @code{GNAT.Spelling_Checker} (@file{g-speche.ads}) -@cindex @code{GNAT.Spelling_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.Spelling_Checker_Generic (g-spchge.ads) -@section @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads}) -@cindex @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads}) -@cindex Spell checking - -@noindent -Provides a generic function that can be instantiated with a string type 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.SSE (g-sse.ads) -@section @code{GNAT.SSE} (@file{g-sse.ads}) -@cindex @code{GNAT.SSE} (@file{g-sse.ads}) - -@noindent -Root of a set of units aimed at offering Ada bindings to a subset of -the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of -targets. It exposes vector component types together with a general -introduction to the binding contents and use. - -@node GNAT.SSE.Vector_Types (g-ssvety.ads) -@section @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads}) -@cindex @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads}) - -@noindent -SSE vector types for use with SSE related intrinsics. - -@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.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.Time_Stamp (g-timsta.ads) -@section @code{GNAT.Time_Stamp} (@file{g-timsta.ads}) -@cindex @code{GNAT.Time_Stamp} (@file{g-timsta.ads}) -@cindex Time stamp -@cindex Current time - -@noindent -Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that -represents the current date and time in ISO 8601 format. This is a very simple -routine with minimal code and there are no dependencies on any other unit. - -@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 dealing with foreign threads which need to be known -by the GNAT run-time system. Consult the documentation of this package for -further details if your program has threads that are created by a non-Ada -environment which then accesses Ada code. - -@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 - -@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.UTF_32_Spelling_Checker (g-u3spch.ads) -@section @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads}) -@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads}) -@cindex Spell checking - -@noindent -Provides a function for determining whether one wide wide string is a plausible -near misspelling of another wide wide string, where the strings are represented -using the UTF_32_String type defined in System.Wch_Cnv. - -@node GNAT.Wide_Spelling_Checker (g-wispch.ads) -@section @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads}) -@cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads}) -@cindex Spell checking - -@noindent -Provides a function for determining whether one wide string is a plausible -near misspelling of another wide string. - -@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_Spelling_Checker (g-zspche.ads) -@section @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads}) -@cindex @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads}) -@cindex Spell checking - -@noindent -Provides a function for determining whether one wide wide string is a plausible -near misspelling of another wide wide string. - -@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.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.Pool_Global (s-pooglo.ads) -@section @code{System.Pool_Global} (@file{s-pooglo.ads}) -@cindex @code{System.Pool_Global} (@file{s-pooglo.ads}) -@cindex Storage pool, global -@cindex Global storage pool - -@noindent -This package provides a storage pool that is equivalent to the default -storage pool used for access types for which no pool is specifically -declared. It uses malloc/free to allocate/free and does not attempt to -do any automatic reclamation. - -@node System.Pool_Local (s-pooloc.ads) -@section @code{System.Pool_Local} (@file{s-pooloc.ads}) -@cindex @code{System.Pool_Local} (@file{s-pooloc.ads}) -@cindex Storage pool, local -@cindex Local storage pool - -@noindent -This package provides a storage pool that is intended for use with locally -defined access types. It uses malloc/free for allocate/free, and maintains -a list of allocated blocks, so that all storage allocated for the pool can -be freed automatically when the pool is finalized. - -@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.Strings.Stream_Ops (s-ststop.ads) -@section @code{System.Strings.Stream_Ops} (@file{s-ststop.ads}) -@cindex @code{System.Strings.Stream_Ops} (@file{s-ststop.ads}) -@cindex Stream operations -@cindex String stream operations - -@noindent -This package provides a set of stream subprograms for standard string types. -It is intended primarily to support implicit use of such subprograms when -stream attributes are applied to string types, but the subprograms in this -package can be used directly by application programs. - -@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 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. - -Note: Pragma @code{CPP_Class} is currently obsolete. It is supported -for backward compatibility but its functionality is available -using pragma @code{Import} with @code{Convention} = @code{CPP}. - -@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. -@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 Reference Manual. - -@node Interfacing to Fortran -@section Interfacing to Fortran - -@noindent -Interfacing to Fortran is achieved as described in section B.5 of the -Ada 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 / Ada 95 / Ada 2005 -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 and Ada 2005 define a number of Specialized Needs Annexes, which are not -required in all implementations. However, as described in this chapter, -GNAT implements all of these 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 / High-Integrity Systems (Annex H) -The Safety and Security Annex (termed the High-Integrity Systems Annex -in Ada 2005) 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 Reference Manual:: -@end menu - -@node Machine Code Insertions -@section Machine Code Insertions -@cindex Machine Code insertions - -@noindent -Package @code{Machine_Code} provides machine code support as described -in the Ada 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, see @ref{Extended Asm,, Assembler Instructions with C Expression -Operands, gcc, Using the GNU Compiler Collection (GCC)}. - -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. @xref{Extended Asm,, Assembler Instructions with C Expression Operands, -gcc, Using the GNU Compiler Collection (GCC)}, for the full description. -Generally it is strongly advisable to use Volatile for any ASM statement -that is missing either input or output operands, or when two or more ASM -statements appear in sequence, to avoid unwanted optimizations. A warning -is generated if this advice is not followed. - -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, Windows, 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 Ada 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 Reference Manual -@section Strict Conformance to the Ada Reference Manual - -@noindent -The dynamic semantics defined by the Ada 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 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 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 NaN values are properly generated. - - -@node Implementation of Ada 2012 Features -@chapter Implementation of Ada 2012 Features -@cindex Ada 2012 implementation status - -This chapter contains a complete list of Ada 2012 features that have been -implemented as of GNAT version 6.4. Generally, these features are only -available if the @option{-gnat12} (Ada 2012 features enabled) flag is set -@cindex @option{-gnat12} option -or if the configuration pragma @code{Ada_2012} is used. -@cindex pragma @code{Ada_2012} -@cindex configuration pragma @code{Ada_2012} -@cindex @code{Ada_2012} configuration pragma -However, new pragmas, attributes, and restrictions are -unconditionally available, since the Ada 95 standard allows the addition of -new pragmas, attributes, and restrictions (there are exceptions, which are -documented in the individual descriptions), and also certain packages -were made available in earlier versions of Ada. - -An ISO date (YYYY-MM-DD) appears in parentheses on the description line. -This date shows the implementation date of the feature. Any wavefront -subsequent to this date will contain the indicated feature, as will any -subsequent releases. A date of 0000-00-00 means that GNAT has always -implemented the feature, or implemented it as soon as it appeared as a -binding interpretation. - -Each feature corresponds to an Ada Issue (``AI'') approved by the Ada -standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. -The features are ordered based on the relevant sections of the Ada -Reference Manual (``RM''). When a given AI relates to multiple points -in the RM, the earliest is used. - -A complete description of the AIs may be found in -@url{www.ada-auth.org/ai05-summary.html}. - -@itemize @bullet - -@item -@emph{AI-0176 Quantified expressions (2010-09-29)} -@cindex AI-0176 (Ada 2012 feature) - -@noindent - Both universally and existentially quantified expressions are implemented. - They use the new syntax for iterators proposed in AI05-139-2, as well as - the standard Ada loop syntax. - -@noindent - RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) - -@item -@emph{AI-0079 Allow @i{other_format} characters in source (2010-07-10)} -@cindex AI-0079 (Ada 2012 feature) - -@noindent - Wide characters in the unicode category @i{other_format} are now allowed in - source programs between tokens, but not within a token such as an identifier. - -@noindent - RM References: 2.01 (4/2) 2.02 (7) - -@item -@emph{AI-0091 Do not allow @i{other_format} in identifiers (0000-00-00)} -@cindex AI-0091 (Ada 2012 feature) - -@noindent - Wide characters in the unicode category @i{other_format} are not permitted - within an identifier, since this can be a security problem. The error - message for this case has been improved to be more specific, but GNAT has - never allowed such characters to appear in identifiers. - -@noindent - RM References: 2.03 (3.1/2) 2.03 (4/2) 2.03 (5/2) 2.03 (5.1/2) 2.03 (5.2/2) 2.03 (5.3/2) 2.09 (2/2) - -@item -@emph{AI-0100 Placement of pragmas (2010-07-01)} -@cindex AI-0100 (Ada 2012 feature) - -@noindent - This AI is an earlier version of AI-163. It simplifies the rules - for legal placement of pragmas. In the case of lists that allow pragmas, if - the list may have no elements, then the list may consist solely of pragmas. - -@noindent - RM References: 2.08 (7) - -@item -@emph{AI-0163 Pragmas in place of null (2010-07-01)} -@cindex AI-0163 (Ada 2012 feature) - -@noindent - A statement sequence may be composed entirely of pragmas. It is no longer - necessary to add a dummy @code{null} statement to make the sequence legal. - -@noindent - RM References: 2.08 (7) 2.08 (16) - - -@item -@emph{AI-0080 ``View of'' not needed if clear from context (0000-00-00)} -@cindex AI-0080 (Ada 2012 feature) - -@noindent - This is an editorial change only, described as non-testable in the AI. - -@noindent - RM References: 3.01 (7) - - -@item -@emph{AI-0183 Aspect specifications (2010-08-16)} -@cindex AI-0183 (Ada 2012 feature) - -@noindent - Aspect specifications have been fully implemented except for pre and post- - conditions, and type invariants, which have their own separate AI's. All - forms of declarations listed in the AI are supported. The following is a - list of the aspects supported (with GNAT implementation aspects marked) - -@multitable {@code{Preelaborable_Initialization}} {--GNAT} -@item @code{Ada_2005} @tab -- GNAT -@item @code{Ada_2012} @tab -- GNAT -@item @code{Address} @tab -@item @code{Alignment} @tab -@item @code{Atomic} @tab -@item @code{Atomic_Components} @tab -@item @code{Bit_Order} @tab -@item @code{Component_Size} @tab -@item @code{Discard_Names} @tab -@item @code{External_Tag} @tab -@item @code{Favor_Top_Level} @tab -- GNAT -@item @code{Inline} @tab -@item @code{Inline_Always} @tab -- GNAT -@item @code{Invariant} @tab -@item @code{Machine_Radix} @tab -@item @code{No_Return} @tab -@item @code{Object_Size} @tab -- GNAT -@item @code{Pack} @tab -@item @code{Persistent_BSS} @tab -- GNAT -@item @code{Post} @tab -@item @code{Pre} @tab -@item @code{Predicate} @tab -@item @code{Preelaborable_Initialization} @tab -@item @code{Pure_Function} @tab -- GNAT -@item @code{Remote_Access_Type} @tab -- GNAT -@item @code{Shared} @tab -- GNAT -@item @code{Size} @tab -@item @code{Storage_Pool} @tab -@item @code{Storage_Size} @tab -@item @code{Stream_Size} @tab -@item @code{Suppress} @tab -@item @code{Suppress_Debug_Info} @tab -- GNAT -@item @code{Test_Case} @tab -- GNAT -@item @code{Unchecked_Union} @tab -@item @code{Universal_Aliasing} @tab -- GNAT -@item @code{Unmodified} @tab -- GNAT -@item @code{Unreferenced} @tab -- GNAT -@item @code{Unreferenced_Objects} @tab -- GNAT -@item @code{Unsuppress} @tab -@item @code{Value_Size} @tab -- GNAT -@item @code{Volatile} @tab -@item @code{Volatile_Components} -@item @code{Warnings} @tab -- GNAT -@end multitable - -@noindent - Note that for aspects with an expression, e.g. @code{Size}, the expression is - treated like a default expression (visibility is analyzed at the point of - occurrence of the aspect, but evaluation of the expression occurs at the - freeze point of the entity involved. - -@noindent - RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) - 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 - (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) - 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) - 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) - 13.03.01 (0) - - -@item -@emph{AI-0128 Inequality is a primitive operation (0000-00-00)} -@cindex AI-0128 (Ada 2012 feature) - -@noindent - If an equality operator ("=") is declared for a type, then the implicitly - declared inequality operator ("/=") is a primitive operation of the type. - This is the only reasonable interpretation, and is the one always implemented - by GNAT, but the RM was not entirely clear in making this point. - -@noindent - RM References: 3.02.03 (6) 6.06 (6) - -@item -@emph{AI-0003 Qualified expressions as names (2010-07-11)} -@cindex AI-0003 (Ada 2012 feature) - -@noindent - In Ada 2012, a qualified expression is considered to be syntactically a name, - meaning that constructs such as @code{A'(F(X)).B} are now legal. This is - useful in disambiguating some cases of overloading. - -@noindent - RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) - 5.04 (7) - -@item -@emph{AI-0120 Constant instance of protected object (0000-00-00)} -@cindex AI-0120 (Ada 2012 feature) - -@noindent - This is an RM editorial change only. The section that lists objects that are - constant failed to include the current instance of a protected object - within a protected function. This has always been treated as a constant - in GNAT. - -@noindent - RM References: 3.03 (21) - -@item -@emph{AI-0008 General access to constrained objects (0000-00-00)} -@cindex AI-0008 (Ada 2012 feature) - -@noindent - The wording in the RM implied that if you have a general access to a - constrained object, it could be used to modify the discriminants. This was - obviously not intended. @code{Constraint_Error} should be raised, and GNAT - has always done so in this situation. - -@noindent - RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) - - -@item -@emph{AI-0093 Additional rules use immutably limited (0000-00-00)} -@cindex AI-0093 (Ada 2012 feature) - -@noindent - This is an editorial change only, to make more widespread use of the Ada 2012 - ``immutably limited''. - -@noindent - RM References: 3.03 (23.4/3) - - - -@item -@emph{AI-0096 Deriving from formal private types (2010-07-20)} -@cindex AI-0096 (Ada 2012 feature) - -@noindent - In general it is illegal for a type derived from a formal limited type to be - nonlimited. This AI makes an exception to this rule: derivation is legal - if it appears in the private part of the generic, and the formal type is not - tagged. If the type is tagged, the legality check must be applied to the - private part of the package. - -@noindent - RM References: 3.04 (5.1/2) 6.02 (7) - - -@item -@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} -@cindex AI-0181 (Ada 2012 feature) - -@noindent - From Ada 2005 on, soft hyphen is considered a non-graphic character, which - means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the - @code{Image} and @code{Value} attributes for the character types. Strictly - speaking this is an inconsistency with Ada 95, but in practice the use of - these attributes is so obscure that it will not cause problems. - -@noindent - RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) - - -@item -@emph{AI-0182 Additional forms for @code{Character'Value} (0000-00-00)} -@cindex AI-0182 (Ada 2012 feature) - -@noindent - This AI allows @code{Character'Value} to accept the string @code{'?'} where - @code{?} is any character including non-graphic control characters. GNAT has - always accepted such strings. It also allows strings such as - @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this - permission and raises @code{Constraint_Error}, as is certainly still - permitted. - -@noindent - RM References: 3.05 (56/2) - - -@item -@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} -@cindex AI-0214 (Ada 2012 feature) - -@noindent - Ada 2012 relaxes the restriction that forbids discriminants of tagged types - to have default expressions by allowing them when the type is limited. It - is often useful to define a default value for a discriminant even though - it can't be changed by assignment. - -@noindent - RM References: 3.07 (9.1/2) 3.07.02 (3) - - -@item -@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} -@cindex AI-0102 (Ada 2012 feature) - -@noindent - It is illegal to assign an anonymous access constant to an anonymous access - variable. The RM did not have a clear rule to prevent this, but GNAT has - always generated an error for this usage. - -@noindent - RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) - - -@item -@emph{AI-0158 Generalizing membership tests (2010-09-16)} -@cindex AI-0158 (Ada 2012 feature) - -@noindent - This AI extends the syntax of membership tests to simplify complex conditions - that can be expressed as membership in a subset of values of any type. It - introduces syntax for a list of expressions that may be used in loop contexts - as well. - -@noindent - RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) - - -@item -@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} -@cindex AI-0173 (Ada 2012 feature) - -@noindent - The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked - with the tag of an abstract type, and @code{False} otherwise. - -@noindent - RM References: 3.09 (7.4/2) 3.09 (12.4/2) - - - -@item -@emph{AI-0076 function with controlling result (0000-00-00)} -@cindex AI-0076 (Ada 2012 feature) - -@noindent - This is an editorial change only. The RM defines calls with controlling - results, but uses the term ``function with controlling result'' without an - explicit definition. - -@noindent - RM References: 3.09.02 (2/2) - - -@item -@emph{AI-0126 Dispatching with no declared operation (0000-00-00)} -@cindex AI-0126 (Ada 2012 feature) - -@noindent - This AI clarifies dispatching rules, and simply confirms that dispatching - executes the operation of the parent type when there is no explicitly or - implicitly declared operation for the descendant type. This has always been - the case in all versions of GNAT. - -@noindent - RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) - - -@item -@emph{AI-0097 Treatment of abstract null extension (2010-07-19)} -@cindex AI-0097 (Ada 2012 feature) - -@noindent - The RM as written implied that in some cases it was possible to create an - object of an abstract type, by having an abstract extension inherit a non- - abstract constructor from its parent type. This mistake has been corrected - in GNAT and in the RM, and this construct is now illegal. - -@noindent - RM References: 3.09.03 (4/2) - - -@item -@emph{AI-0203 Extended return cannot be abstract (0000-00-00)} -@cindex AI-0203 (Ada 2012 feature) - -@noindent - A return_subtype_indication cannot denote an abstract subtype. GNAT has never - permitted such usage. - -@noindent - RM References: 3.09.03 (8/3) - - -@item -@emph{AI-0198 Inheriting abstract operators (0000-00-00)} -@cindex AI-0198 (Ada 2012 feature) - -@noindent - This AI resolves a conflict between two rules involving inherited abstract - operations and predefined operators. If a derived numeric type inherits - an abstract operator, it overrides the predefined one. This interpretation - was always the one implemented in GNAT. - -@noindent - RM References: 3.09.03 (4/3) - -@item -@emph{AI-0073 Functions returning abstract types (2010-07-10)} -@cindex AI-0073 (Ada 2012 feature) - -@noindent - This AI covers a number of issues regarding returning abstract types. In - particular generic functions cannot have abstract result types or access - result types designated an abstract type. There are some other cases which - are detailed in the AI. Note that this binding interpretation has not been - retrofitted to operate before Ada 2012 mode, since it caused a significant - number of regressions. - -@noindent - RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) - - -@item -@emph{AI-0070 Elaboration of interface types (0000-00-00)} -@cindex AI-0070 (Ada 2012 feature) - -@noindent - This is an editorial change only, there are no testable consequences short of - checking for the absence of generated code for an interface declaration. - -@noindent - RM References: 3.09.04 (18/2) - - -@item -@emph{AI-0208 Characteristics of incomplete views (0000-00-00)} -@cindex AI-0208 (Ada 2012 feature) - -@noindent - The wording in the Ada 2005 RM concerning characteristics of incomplete views - was incorrect and implied that some programs intended to be legal were now - illegal. GNAT had never considered such programs illegal, so it has always - implemented the intent of this AI. - -@noindent - RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) - - -@item -@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} -@cindex AI-0162 (Ada 2012 feature) - -@noindent - Incomplete types are made more useful by allowing them to be completed by - private types and private extensions. - -@noindent - RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) - - - -@item -@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} -@cindex AI-0098 (Ada 2012 feature) - -@noindent - An unintentional omission in the RM implied some inconsistent restrictions on - the use of anonymous access to subprogram values. These restrictions were not - intentional, and have never been enforced by GNAT. - -@noindent - RM References: 3.10.01 (6) 3.10.01 (9.2/2) - - -@item -@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} -@cindex AI-0199 (Ada 2012 feature) - -@noindent - A choice list in a record aggregate can include several components of - (distinct) anonymous access types as long as they have matching designated - subtypes. - -@noindent - RM References: 4.03.01 (16) - - -@item -@emph{AI-0220 Needed components for aggregates (0000-00-00)} -@cindex AI-0220 (Ada 2012 feature) - -@noindent - This AI addresses a wording problem in the RM that appears to permit some - complex cases of aggregates with non-static discriminants. GNAT has always - implemented the intended semantics. - -@noindent - RM References: 4.03.01 (17) - -@item -@emph{AI-0147 Conditional expressions (2009-03-29)} -@cindex AI-0147 (Ada 2012 feature) - -@noindent - Conditional expressions are permitted. The form of such an expression is: - -@smallexample - (@b{if} @i{expr} @b{then} @i{expr} @{@b{elsif} @i{expr} @b{then} @i{expr}@} [@b{else} @i{expr}]) -@end smallexample - - The parentheses can be omitted in contexts where parentheses are present - anyway, such as subprogram arguments and pragma arguments. If the @b{else} - clause is omitted, @b{else True} is assumed; - thus @code{(@b{if} A @b{then} B)} is a way to conveniently represent - @emph{(A implies B)} in standard logic. - -@noindent - RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) - 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) - - -@item -@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} -@cindex AI-0037 (Ada 2012 feature) - -@noindent - This AI confirms that an association of the form @code{Indx => <>} in an - array aggregate must raise @code{Constraint_Error} if @code{Indx} - is out of range. The RM specified a range check on other associations, but - not when the value of the association was defaulted. GNAT has always inserted - a constraint check on the index value. - -@noindent - RM References: 4.03.03 (29) - - -@item -@emph{AI-0123 Composability of equality (2010-04-13)} -@cindex AI-0123 (Ada 2012 feature) - -@noindent - Equality of untagged record composes, so that the predefined equality for a - composite type that includes a component of some untagged record type - @code{R} uses the equality operation of @code{R} (which may be user-defined - or predefined). This makes the behavior of untagged records identical to that - of tagged types in this respect. - - This change is an incompatibility with previous versions of Ada, but it - corrects a non-uniformity that was often a source of confusion. Analysis of - a large number of industrial programs indicates that in those rare cases - where a composite type had an untagged record component with a user-defined - equality, either there was no use of the composite equality, or else the code - expected the same composability as for tagged types, and thus had a bug that - would be fixed by this change. - -@noindent - RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) - 8.05.04 (8) - - -@item -@emph{AI-0088 The value of exponentiation (0000-00-00)} -@cindex AI-0088 (Ada 2012 feature) - -@noindent - This AI clarifies the equivalence rule given for the dynamic semantics of - exponentiation: the value of the operation can be obtained by repeated - multiplication, but the operation can be implemented otherwise (for example - using the familiar divide-by-two-and-square algorithm, even if this is less - accurate), and does not imply repeated reads of a volatile base. - -@noindent - RM References: 4.05.06 (11) - -@item -@emph{AI-0188 Case expressions (2010-01-09)} -@cindex AI-0188 (Ada 2012 feature) - -@noindent - Case expressions are permitted. This allows use of constructs such as: -@smallexample - X := (@b{case} Y @b{is when} 1 => 2, @b{when} 2 => 3, @b{when others} => 31) -@end smallexample - -@noindent - RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) - -@item -@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} -@cindex AI-0104 (Ada 2012 feature) - -@noindent - The assignment @code{Ptr := @b{new not null} Some_Ptr;} will raise - @code{Constraint_Error} because the default value of the allocated object is - @b{null}. This useless construct is illegal in Ada 2012. - -@noindent - RM References: 4.08 (2) - -@item -@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} -@cindex AI-0157 (Ada 2012 feature) - -@noindent - Allocation and Deallocation from an empty storage pool (i.e. allocation or - deallocation of a pointer for which a static storage size clause of zero - has been given) is now illegal and is detected as such. GNAT - previously gave a warning but not an error. - -@noindent - RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) - -@item -@emph{AI-0179 Statement not required after label (2010-04-10)} -@cindex AI-0179 (Ada 2012 feature) - -@noindent - It is not necessary to have a statement following a label, so a label - can appear at the end of a statement sequence without the need for putting a - null statement afterwards, but it is not allowable to have only labels and - no real statements in a statement sequence. - -@noindent - RM References: 5.01 (2) - - -@item -@emph{AI-139-2 Syntactic sugar for iterators (2010-09-29)} -@cindex AI-139-2 (Ada 2012 feature) - -@noindent - The new syntax for iterating over arrays and containers is now implemented. - Iteration over containers is for now limited to read-only iterators. Only - default iterators are supported, with the syntax: @code{@b{for} Elem @b{of} C}. - -@noindent - RM References: 5.05 - -@item -@emph{AI-0134 Profiles must match for full conformance (0000-00-00)} -@cindex AI-0134 (Ada 2012 feature) - -@noindent - For full conformance, the profiles of anonymous-access-to-subprogram - parameters must match. GNAT has always enforced this rule. - -@noindent - RM References: 6.03.01 (18) - -@item -@emph{AI-0207 Mode conformance and access constant (0000-00-00)} -@cindex AI-0207 (Ada 2012 feature) - -@noindent - This AI confirms that access_to_constant indication must match for mode - conformance. This was implemented in GNAT when the qualifier was originally - introduced in Ada 2005. - -@noindent - RM References: 6.03.01 (16/2) - - -@item -@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} -@cindex AI-0046 (Ada 2012 feature) - -@noindent - For full conformance, in the case of access parameters, the null exclusion - must match (either both or neither must have @code{@b{not null}}). - -@noindent - RM References: 6.03.02 (18) - - -@item -@emph{AI-0118 The association of parameter associations (0000-00-00)} -@cindex AI-0118 (Ada 2012 feature) - -@noindent - This AI clarifies the rules for named associations in subprogram calls and - generic instantiations. The rules have been in place since Ada 83. - -@noindent - RM References: 6.04.01 (2) 12.03 (9) - - -@item -@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} -@cindex AI-0196 (Ada 2012 feature) - -@noindent - Null exclusion checks are not made for @code{@b{out}} parameters when - evaluating the actual parameters. GNAT has never generated these checks. - -@noindent - RM References: 6.04.01 (13) - -@item -@emph{AI-0015 Constant return objects (0000-00-00)} -@cindex AI-0015 (Ada 2012 feature) - -@noindent - The return object declared in an @i{extended_return_statement} may be - declared constant. This was always intended, and GNAT has always allowed it. - -@noindent - RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) - 6.05 (5.7/2) - - -@item -@emph{AI-0032 Extended return for class-wide functions (0000-00-00)} -@cindex AI-0032 (Ada 2012 feature) - -@noindent - If a function returns a class-wide type, the object of an extended return - statement can be declared with a specific type that is covered by the class- - wide type. This has been implemented in GNAT since the introduction of - extended returns. Note AI-0103 complements this AI by imposing matching - rules for constrained return types. - -@noindent - RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) - 6.05 (8/2) - -@item -@emph{AI-0103 Static matching for extended return (2010-07-23)} -@cindex AI-0103 (Ada 2012 feature) - -@noindent - If the return subtype of a function is an elementary type or a constrained - type, the subtype indication in an extended return statement must match - statically this return subtype. - -@noindent - RM References: 6.05 (5.2/2) - - -@item -@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} -@cindex AI-0058 (Ada 2012 feature) - -@noindent - The RM had some incorrect wording implying wrong treatment of abnormal - completion in an extended return. GNAT has always implemented the intended - correct semantics as described by this AI. - -@noindent - RM References: 6.05 (22/2) - - -@item -@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} -@cindex AI-0050 (Ada 2012 feature) - -@noindent - The implementation permissions for raising @code{Constraint_Error} early on a function call when it was clear an exception would be raised were over-permissive and allowed mishandling of discriminants in some cases. GNAT did - not take advantage of these incorrect permissions in any case. - -@noindent - RM References: 6.05 (24/2) - - -@item -@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} -@cindex AI-0125 (Ada 2012 feature) - -@noindent - In Ada 2012, the declaration of a primitive operation of a type extension - or private extension can also override an inherited primitive that is not - visible at the point of this declaration. - -@noindent - RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) - -@item -@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} -@cindex AI-0062 (Ada 2012 feature) - -@noindent - A full constant may have a null exclusion even if its associated deferred - constant does not. GNAT has always allowed this. - -@noindent - RM References: 7.04 (6/2) 7.04 (7.1/2) - - -@item -@emph{AI-0178 Incomplete views are limited (0000-00-00)} -@cindex AI-0178 (Ada 2012 feature) - -@noindent - This AI clarifies the role of incomplete views and plugs an omission in the - RM. GNAT always correctly restricted the use of incomplete views and types. - -@noindent - RM References: 7.05 (3/2) 7.05 (6/2) - -@item -@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} -@cindex AI-0087 (Ada 2012 feature) - -@noindent - The actual for a formal nonlimited derived type cannot be limited. In - particular, a formal derived type that extends a limited interface but which - is not explicitly limited cannot be instantiated with a limited type. - -@noindent - RM References: 7.05 (5/2) 12.05.01 (5.1/2) - -@item -@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} -@cindex AI-0099 (Ada 2012 feature) - -@noindent - This AI clarifies that ``needs finalization'' is part of dynamic semantics, - and therefore depends on the run-time characteristics of an object (i.e. its - tag) and not on its nominal type. As the AI indicates: ``we do not expect - this to affect any implementation''. - -@noindent - RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) - - - -@item -@emph{AI-0064 Redundant finalization rule (0000-00-00)} -@cindex AI-0064 (Ada 2012 feature) - -@noindent - This is an editorial change only. The intended behavior is already checked - by an existing ACATS test, which GNAT has always executed correctly. - -@noindent - RM References: 7.06.01 (17.1/1) - -@item -@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} -@cindex AI-0026 (Ada 2012 feature) - -@noindent - Record representation clauses concerning Unchecked_Union types cannot mention - the discriminant of the type. The type of a component declared in the variant - part of an Unchecked_Union cannot be controlled, have controlled components, - nor have protected or task parts. If an Unchecked_Union type is declared - within the body of a generic unit or its descendants, then the type of a - component declared in the variant part cannot be a formal private type or a - formal private extension declared within the same generic unit. - -@noindent - RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) - - -@item -@emph{AI-0205 Extended return declares visible name (0000-00-00)} -@cindex AI-0205 (Ada 2012 feature) - -@noindent - This AI corrects a simple omission in the RM. Return objects have always - been visible within an extended return statement. - -@noindent - RM References: 8.03 (17) - - -@item -@emph{AI-0042 Overriding versus implemented-by (0000-00-00)} -@cindex AI-0042 (Ada 2012 feature) - -@noindent - This AI fixes a wording gap in the RM. An operation of a synchronized - interface can be implemented by a protected or task entry, but the abstract - operation is not being overridden in the usual sense, and it must be stated - separately that this implementation is legal. This has always been the case - in GNAT. - -@noindent - RM References: 9.01 (9.2/2) 9.04 (11.1/2) - -@item -@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} -@cindex AI-0030 (Ada 2012 feature) - -@noindent - Requeue is permitted to a protected, synchronized or task interface primitive - providing it is known that the overriding operation is an entry. Otherwise - the requeue statement has the same effect as a procedure call. Use of pragma - @code{Implemented} provides a way to impose a static requirement on the - overriding operation by adhering to one of the implementation kinds: entry, - protected procedure or any of the above. - -@noindent - RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) - 9.05.04 (6) 9.05.04 (7) 9.05.04 (12) - - -@item -@emph{AI-0201 Independence of atomic object components (2010-07-22)} -@cindex AI-0201 (Ada 2012 feature) - -@noindent - If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} - attribute, then individual components may not be addressable by independent - tasks. However, if the representation clause has no effect (is confirming), - then independence is not compromised. Furthermore, in GNAT, specification of - other appropriately addressable component sizes (e.g. 16 for 8-bit - characters) also preserves independence. GNAT now gives very clear warnings - both for the declaration of such a type, and for any assignment to its components. - -@noindent - RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) - -@item -@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} -@cindex AI-0009 (Ada 2012 feature) - -@noindent - This AI introduces the new pragmas @code{Independent} and - @code{Independent_Components}, - which control guaranteeing independence of access to objects and components. - The AI also requires independence not unaffected by confirming rep clauses. - -@noindent - RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) - C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) - - -@item -@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)} -@cindex AI-0072 (Ada 2012 feature) - -@noindent - This AI clarifies that task signalling for reading @code{'Terminated} only - occurs if the result is True. GNAT semantics has always been consistent with - this notion of task signalling. - -@noindent - RM References: 9.10 (6.1/1) - -@item -@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} -@cindex AI-0108 (Ada 2012 feature) - -@noindent - This AI confirms that an incomplete type from a limited view does not have - discriminants. This has always been the case in GNAT. - -@noindent - RM References: 10.01.01 (12.3/2) - -@item -@emph{AI-0129 Limited views and incomplete types (0000-00-00)} -@cindex AI-0129 (Ada 2012 feature) - -@noindent - This AI clarifies the description of limited views: a limited view of a - package includes only one view of a type that has an incomplete declaration - and a full declaration (there is no possible ambiguity in a client package). - This AI also fixes an omission: a nested package in the private part has no - limited view. GNAT always implemented this correctly. - -@noindent - RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) - - - -@item -@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} -@cindex AI-0077 (Ada 2012 feature) - -@noindent - This AI clarifies that a declaration does not include a context clause, - and confirms that it is illegal to have a context in which both a limited - and a nonlimited view of a package are accessible. Such double visibility - was always rejected by GNAT. - -@noindent - RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) - -@item -@emph{AI-0122 Private with and children of generics (0000-00-00)} -@cindex AI-0122 (Ada 2012 feature) - -@noindent - This AI clarifies the visibility of private children of generic units within - instantiations of a parent. GNAT has always handled this correctly. - -@noindent - RM References: 10.01.02 (12/2) - - - -@item -@emph{AI-0040 Limited with clauses on descendant (0000-00-00)} -@cindex AI-0040 (Ada 2012 feature) - -@noindent - This AI confirms that a limited with clause in a child unit cannot name - an ancestor of the unit. This has always been checked in GNAT. - -@noindent - RM References: 10.01.02 (20/2) - -@item -@emph{AI-0132 Placement of library unit pragmas (0000-00-00)} -@cindex AI-0132 (Ada 2012 feature) - -@noindent - This AI fills a gap in the description of library unit pragmas. The pragma - clearly must apply to a library unit, even if it does not carry the name - of the enclosing unit. GNAT has always enforced the required check. - -@noindent - RM References: 10.01.05 (7) - - -@item -@emph{AI-0034 Categorization of limited views (0000-00-00)} -@cindex AI-0034 (Ada 2012 feature) - -@noindent - The RM makes certain limited with clauses illegal because of categorization - considerations, when the corresponding normal with would be legal. This is - not intended, and GNAT has always implemented the recommended behavior. - -@noindent - RM References: 10.02.01 (11/1) 10.02.01 (17/2) - - -@item -@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} -@cindex AI-0035 (Ada 2012 feature) - -@noindent - This AI remedies some inconsistencies in the legality rules for Pure units. - Derived access types are legal in a pure unit (on the assumption that the - rule for a zero storage pool size has been enforced on the ancestor type). - The rules are enforced in generic instances and in subunits. GNAT has always - implemented the recommended behavior. - -@noindent - RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) - - -@item -@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} -@cindex AI-0219 (Ada 2012 feature) - -@noindent - This AI refines the rules for the cases with limited parameters which do not - allow the implementations to omit ``redundant''. GNAT now properly conforms - to the requirements of this binding interpretation. - -@noindent - RM References: 10.02.01 (18/2) - -@item -@emph{AI-0043 Rules about raising exceptions (0000-00-00)} -@cindex AI-0043 (Ada 2012 feature) - -@noindent - This AI covers various omissions in the RM regarding the raising of - exceptions. GNAT has always implemented the intended semantics. - -@noindent - RM References: 11.04.01 (10.1/2) 11 (2) - - -@item -@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} -@cindex AI-0200 (Ada 2012 feature) - -@noindent - This AI plugs a gap in the RM which appeared to allow some obviously intended - illegal instantiations. GNAT has never allowed these instantiations. - -@noindent - RM References: 12.07 (16) - - -@item -@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} -@cindex AI-0112 (Ada 2012 feature) - -@noindent - This AI concerns giving names to various representation aspects, but the - practical effect is simply to make the use of duplicate - @code{Atomic}[@code{_Components}], - @code{Volatile}[@code{_Components}] and - @code{Independent}[@code{_Components}] pragmas illegal, and GNAT - now performs this required check. - -@noindent - RM References: 13.01 (8) - -@item -@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} -@cindex AI-0106 (Ada 2012 feature) - -@noindent - The RM appeared to allow representation pragmas on generic formal parameters, - but this was not intended, and GNAT has never permitted this usage. - -@noindent - RM References: 13.01 (9.1/1) - - -@item -@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} -@cindex AI-0012 (Ada 2012 feature) - -@noindent - It is now illegal to give an inappropriate component size or a pragma - @code{Pack} that attempts to change the component size in the case of atomic - or aliased components. Previously GNAT ignored such an attempt with a - warning. - -@noindent - RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) - - -@item -@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} -@cindex AI-0039 (Ada 2012 feature) - -@noindent - The RM permitted the use of dynamic expressions (such as @code{ptr.@b{all})} - for stream attributes, but these were never useful and are now illegal. GNAT - has always regarded such expressions as illegal. - -@noindent - RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) - - -@item -@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} -@cindex AI-0095 (Ada 2012 feature) - -@noindent - The prefix of @code{'Address} cannot statically denote a subprogram with - convention @code{Intrinsic}. The use of the @code{Address} attribute raises - @code{Program_Error} if the prefix denotes a subprogram with convention - @code{Intrinsic}. - -@noindent - RM References: 13.03 (11/1) - - -@item -@emph{AI-0116 Alignment of class-wide objects (0000-00-00)} -@cindex AI-0116 (Ada 2012 feature) - -@noindent - This AI requires that the alignment of a class-wide object be no greater - than the alignment of any type in the class. GNAT has always followed this - recommendation. - -@noindent - RM References: 13.03 (29) 13.11 (16) - - -@item -@emph{AI-0146 Type invariants (2009-09-21)} -@cindex AI-0146 (Ada 2012 feature) - -@noindent - Type invariants may be specified for private types using the aspect notation. - Aspect @code{Invariant} may be specified for any private type, - @code{Invariant'Class} can - only be specified for tagged types, and is inherited by any descendent of the - tagged types. The invariant is a boolean expression that is tested for being - true in the following situations: conversions to the private type, object - declarations for the private type that are default initialized, and - [@b{in}] @b{out} - parameters and returned result on return from any primitive operation for - the type that is visible to a client. - -@noindent - RM References: 13.03.03 (00) - -@item -@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} -@cindex AI-0078 (Ada 2012 feature) - -@noindent - In Ada 2012, compilers are required to support unchecked conversion where the - target alignment is a multiple of the source alignment. GNAT always supported - this case (and indeed all cases of differing alignments, doing copies where - required if the alignment was reduced). - -@noindent - RM References: 13.09 (7) - - -@item -@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} -@cindex AI-0195 (Ada 2012 feature) - -@noindent - The handling of invalid values is now designated to be implementation - defined. This is a documentation change only, requiring Annex M in the GNAT - Reference Manual to document this handling. - In GNAT, checks for invalid values are made - only when necessary to avoid erroneous behavior. Operations like assignments - which cannot cause erroneous behavior ignore the possibility of invalid - values and do not do a check. The date given above applies only to the - documentation change, this behavior has always been implemented by GNAT. - -@noindent - RM References: 13.09.01 (10) - -@item -@emph{AI-0193 Alignment of allocators (2010-09-16)} -@cindex AI-0193 (Ada 2012 feature) - -@noindent - This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, - analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead - of size. - -@noindent - RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) - 13.11.01 (2) 13.11.01 (3) - - -@item -@emph{AI-0177 Parameterized expressions (2010-07-10)} -@cindex AI-0177 (Ada 2012 feature) - -@noindent - The new Ada 2012 notion of parameterized expressions is implemented. The form - is: -@smallexample - @i{function specification} @b{is} (@i{expression}) -@end smallexample - -@noindent - This is exactly equivalent to the - corresponding function body that returns the expression, but it can appear - in a package spec. Note that the expression must be parenthesized. - -@noindent - RM References: 13.11.01 (3/2) - -@item -@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} -@cindex AI-0033 (Ada 2012 feature) - -@noindent - Neither of these two pragmas may appear within a generic template, because - the generic might be instantiated at other than the library level. - -@noindent - RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) - - -@item -@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} -@cindex AI-0161 (Ada 2012 feature) - -@noindent - A new restriction @code{No_Default_Stream_Attributes} prevents the use of any - of the default stream attributes for elementary types. If this restriction is - in force, then it is necessary to provide explicit subprograms for any - stream attributes used. - -@noindent - RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) - -@item -@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} -@cindex AI-0194 (Ada 2012 feature) - -@noindent - The @code{Stream_Size} attribute returns the default number of bits in the - stream representation of the given type. - This value is not affected by the presence - of stream subprogram attributes for the type. GNAT has always implemented - this interpretation. - -@noindent - RM References: 13.13.02 (1.2/2) - -@item -@emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)} -@cindex AI-0109 (Ada 2012 feature) - -@noindent - This AI is an editorial change only. It removes the need for a tag check - that can never fail. - -@noindent - RM References: 13.13.02 (34/2) - -@item -@emph{AI-0007 Stream read and private scalar types (0000-00-00)} -@cindex AI-0007 (Ada 2012 feature) - -@noindent - The RM as written appeared to limit the possibilities of declaring read - attribute procedures for private scalar types. This limitation was not - intended, and has never been enforced by GNAT. - -@noindent - RM References: 13.13.02 (50/2) 13.13.02 (51/2) - - -@item -@emph{AI-0065 Remote access types and external streaming (0000-00-00)} -@cindex AI-0065 (Ada 2012 feature) - -@noindent - This AI clarifies the fact that all remote access types support external - streaming. This fixes an obvious oversight in the definition of the - language, and GNAT always implemented the intended correct rules. - -@noindent - RM References: 13.13.02 (52/2) - -@item -@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} -@cindex AI-0019 (Ada 2012 feature) - -@noindent - The RM suggests that primitive subprograms of a specific tagged type are - frozen when the tagged type is frozen. This would be an incompatible change - and is not intended. GNAT has never attempted this kind of freezing and its - behavior is consistent with the recommendation of this AI. - -@noindent - RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) - -@item -@emph{AI-0017 Freezing and incomplete types (0000-00-00)} -@cindex AI-0017 (Ada 2012 feature) - -@noindent - So-called ``Taft-amendment types'' (i.e., types that are completed in package - bodies) are not frozen by the occurrence of bodies in the - enclosing declarative part. GNAT always implemented this properly. - -@noindent - RM References: 13.14 (3/1) - - -@item -@emph{AI-0060 Extended definition of remote access types (0000-00-00)} -@cindex AI-0060 (Ada 2012 feature) - -@noindent - This AI extends the definition of remote access types to include access - to limited, synchronized, protected or task class-wide interface types. - GNAT already implemented this extension. - -@noindent - RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) - -@item -@emph{AI-0114 Classification of letters (0000-00-00)} -@cindex AI-0114 (Ada 2012 feature) - -@noindent - The code points 170 (@code{FEMININE ORDINAL INDICATOR}), - 181 (@code{MICRO SIGN}), and - 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered - lower case letters by Unicode. - However, they are not allowed in identifiers, and they - return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. - This behavior is consistent with that defined in Ada 95. - -@noindent - RM References: A.03.02 (59) A.04.06 (7) - - -@item -@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} -@cindex AI-0185 (Ada 2012 feature) - -@noindent - Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide - classification functions for @code{Wide_Character} and - @code{Wide_Wide_Character}, as well as providing - case folding routines for @code{Wide_[Wide_]Character} and - @code{Wide_[Wide_]String}. - -@noindent - RM References: A.03.05 (0) A.03.06 (0) - - -@item -@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} -@cindex AI-0031 (Ada 2012 feature) - -@noindent - A new version of @code{Find_Token} is added to all relevant string packages, - with an extra parameter @code{From}. Instead of starting at the first - character of the string, the search for a matching Token starts at the - character indexed by the value of @code{From}. - These procedures are available in all versions of Ada - but if used in versions earlier than Ada 2012 they will generate a warning - that an Ada 2012 subprogram is being used. - -@noindent - RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) - A.04.05 (46) - - -@item -@emph{AI-0056 Index on null string returns zero (0000-00-00)} -@cindex AI-0056 (Ada 2012 feature) - -@noindent - The wording in the Ada 2005 RM implied an incompatible handling of the - @code{Index} functions, resulting in raising an exception instead of - returning zero in some situations. - This was not intended and has been corrected. - GNAT always returned zero, and is thus consistent with this AI. - -@noindent - RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) - - -@item -@emph{AI-0137 String encoding package (2010-03-25)} -@cindex AI-0137 (Ada 2012 feature) - -@noindent - The packages @code{Ada.Strings.UTF_Encoding}, together with its child - packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, - and @code{Wide_Wide_Strings} have been - implemented. These packages (whose documentation can be found in the spec - files @file{a-stuten.ads}, @file{a-suenco.ads}, @file{a-suenst.ads}, - @file{a-suewst.ads}, @file{a-suezst.ads}) allow encoding and decoding of - @code{String}, @code{Wide_String}, and @code{Wide_Wide_String} - values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and - UTF-16), as well as conversions between the different UTF encodings. With - the exception of @code{Wide_Wide_Strings}, these packages are available in - Ada 95 and Ada 2005 mode as well as Ada 2012 mode. - The @code{Wide_Wide_Strings package} - is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 - mode since it uses @code{Wide_Wide_Character}). - -@noindent - RM References: A.04.11 - -@item -@emph{AI-0038 Minor errors in Text_IO (0000-00-00)} -@cindex AI-0038 (Ada 2012 feature) - -@noindent - These are minor errors in the description on three points. The intent on - all these points has always been clear, and GNAT has always implemented the - correct intended semantics. - -@noindent - RM References: A.10.05 (37) A.10.07 (8/1) A.10.07 (10) A.10.07 (12) A.10.08 (10) A.10.08 (24) - -@item -@emph{AI-0044 Restrictions on container instantiations (0000-00-00)} -@cindex AI-0044 (Ada 2012 feature) - -@noindent - This AI places restrictions on allowed instantiations of generic containers. - These restrictions are not checked by the compiler, so there is nothing to - change in the implementation. This affects only the RM documentation. - -@noindent - RM References: A.18 (4/2) A.18.02 (231/2) A.18.03 (145/2) A.18.06 (56/2) A.18.08 (66/2) A.18.09 (79/2) A.18.26 (5/2) A.18.26 (9/2) - -@item -@emph{AI-0127 Adding Locale Capabilities (2010-09-29)} -@cindex AI-0127 (Ada 2012 feature) - -@noindent - This package provides an interface for identifying the current locale. - -@noindent - RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 - A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 - - - -@item -@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} -@cindex AI-0002 (Ada 2012 feature) - -@noindent - The compiler is not required to support exporting an Ada subprogram with - convention C if there are parameters or a return type of an unconstrained - array type (such as @code{String}). GNAT allows such declarations but - generates warnings. It is possible, but complicated, to write the - corresponding C code and certainly such code would be specific to GNAT and - non-portable. - -@noindent - RM References: B.01 (17) B.03 (62) B.03 (71.1/2) - - -@item -@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} -@cindex AI05-0216 (Ada 2012 feature) - -@noindent - It is clearly the intention that @code{No_Task_Hierarchy} is intended to - forbid tasks declared locally within subprograms, or functions returning task - objects, and that is the implementation that GNAT has always provided. - However the language in the RM was not sufficiently clear on this point. - Thus this is a documentation change in the RM only. - -@noindent - RM References: D.07 (3/3) - -@item -@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} -@cindex AI-0211 (Ada 2012 feature) - -@noindent - The restriction @code{No_Relative_Delays} forbids any calls to the subprogram - @code{Ada.Real_Time.Timing_Events.Set_Handler}. - -@noindent - RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) - -@item -@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} -@cindex AI-0190 (Ada 2012 feature) - -@noindent - This AI introduces a new pragma @code{Default_Storage_Pool}, which can be - used to control storage pools globally. - In particular, you can force every access - type that is used for allocation (@b{new}) to have an explicit storage pool, - or you can declare a pool globally to be used for all access types that lack - an explicit one. - -@noindent - RM References: D.07 (8) - -@item -@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} -@cindex AI-0189 (Ada 2012 feature) - -@noindent - This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, - which says that no dynamic allocation will occur once elaboration is - completed. - In general this requires a run-time check, which is not required, and which - GNAT does not attempt. But the static cases of allocators in a task body or - in the body of the main program are detected and flagged at compile or bind - time. - -@noindent - RM References: D.07 (19.1/2) H.04 (23.3/2) - -@item -@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} -@cindex AI-0171 (Ada 2012 feature) - -@noindent - A new package @code{System.Multiprocessors} is added, together with the - definition of pragma @code{CPU} for controlling task affinity. A new no - dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, - is added to the Ravenscar profile. - -@noindent - RM References: D.13.01 (4/2) D.16 - - -@item -@emph{AI-0210 Correct Timing_Events metric (0000-00-00)} -@cindex AI-0210 (Ada 2012 feature) - -@noindent - This is a documentation only issue regarding wording of metric requirements, - that does not affect the implementation of the compiler. - -@noindent - RM References: D.15 (24/2) - - -@item -@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} -@cindex AI-0206 (Ada 2012 feature) - -@noindent - Remote types packages are now allowed to depend on preelaborated packages. - This was formerly considered illegal. - -@noindent - RM References: E.02.02 (6) - - - -@item -@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} -@cindex AI-0152 (Ada 2012 feature) - -@noindent - Restriction @code{No_Anonymous_Allocators} prevents the use of allocators - where the type of the returned value is an anonymous access type. - -@noindent - RM References: H.04 (8/1) -@end itemize - - -@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 |