| \input texinfo @c -*-texinfo-*- |
| |
| @c %**start of header |
| |
| @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo |
| @c o |
| @c GNAT DOCUMENTATION o |
| @c o |
| @c G N A T _ RM o |
| @c o |
| @c Copyright (C) 1995-2005 Free Software Foundation o |
| @c o |
| @c o |
| @c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o |
| @c o |
| @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo |
| |
| @setfilename gnat_rm.info |
| |
| @set FSFEDITION |
| |
| @settitle GNAT Reference Manual |
| |
| @setchapternewpage odd |
| @syncodeindex fn cp |
| |
| @include gcc-common.texi |
| |
| @dircategory GNU Ada tools |
| @direntry |
| * GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools. |
| @end direntry |
| |
| @copying |
| Copyright @copyright{} 1995-2004, Free Software Foundation |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.2 |
| or any later version published by the Free Software Foundation; |
| with the Invariant Sections being ``GNU Free Documentation License'', |
| with the Front-Cover Texts being ``GNAT Reference Manual'', and with |
| no Back-Cover Texts. A copy of the license is included in the section |
| entitled ``GNU Free Documentation License''. |
| @end copying |
| |
| @titlepage |
| @title GNAT Reference Manual |
| @subtitle GNAT, The GNU Ada 95 Compiler |
| @versionsubtitle |
| @author Ada Core Technologies, Inc. |
| @page |
| @vskip 0pt plus 1filll |
| |
| @insertcopying |
| |
| @end titlepage |
| |
| @ifnottex |
| @node Top, About This Guide, (dir), (dir) |
| @top GNAT Reference Manual |
| |
| @noindent |
| GNAT Reference Manual |
| |
| @noindent |
| GNAT, The GNU Ada 95 Compiler@* |
| GCC version @value{version-GCC}@* |
| |
| @noindent |
| AdaCore |
| |
| @menu |
| * About This Guide:: |
| * Implementation Defined Pragmas:: |
| * Implementation Defined Attributes:: |
| * Implementation Advice:: |
| * Implementation Defined Characteristics:: |
| * Intrinsic Subprograms:: |
| * Representation Clauses and Pragmas:: |
| * Standard Library Routines:: |
| * The Implementation of Standard I/O:: |
| * The GNAT Library:: |
| * Interfacing to Other Languages:: |
| * Specialized Needs Annexes:: |
| * Implementation of Specific Ada Features:: |
| * Project File Reference:: |
| * Obsolescent Features:: |
| * GNU Free Documentation License:: |
| * Index:: |
| |
| --- The Detailed Node Listing --- |
| |
| About This Guide |
| |
| * What This Reference Manual Contains:: |
| * Related Information:: |
| |
| Implementation Defined Pragmas |
| |
| * Pragma Abort_Defer:: |
| * Pragma Ada_83:: |
| * Pragma Ada_95:: |
| * Pragma Ada_05:: |
| * Pragma Ada_2005:: |
| * Pragma Annotate:: |
| * Pragma Assert:: |
| * Pragma Ast_Entry:: |
| * Pragma C_Pass_By_Copy:: |
| * Pragma Comment:: |
| * Pragma Common_Object:: |
| * Pragma Compile_Time_Warning:: |
| * Pragma Complete_Representation:: |
| * Pragma Complex_Representation:: |
| * Pragma Component_Alignment:: |
| * Pragma Convention_Identifier:: |
| * Pragma CPP_Class:: |
| * Pragma CPP_Constructor:: |
| * Pragma CPP_Virtual:: |
| * Pragma CPP_Vtable:: |
| * Pragma Debug:: |
| * Pragma Debug_Policy:: |
| * Pragma Detect_Blocking:: |
| * Pragma Elaboration_Checks:: |
| * Pragma Eliminate:: |
| * Pragma Export_Exception:: |
| * Pragma Export_Function:: |
| * Pragma Export_Object:: |
| * Pragma Export_Procedure:: |
| * Pragma Export_Value:: |
| * Pragma Export_Valued_Procedure:: |
| * Pragma Extend_System:: |
| * Pragma External:: |
| * Pragma External_Name_Casing:: |
| * Pragma Finalize_Storage_Only:: |
| * Pragma Float_Representation:: |
| * Pragma Ident:: |
| * Pragma Import_Exception:: |
| * Pragma Import_Function:: |
| * Pragma Import_Object:: |
| * Pragma Import_Procedure:: |
| * Pragma Import_Valued_Procedure:: |
| * Pragma Initialize_Scalars:: |
| * Pragma Inline_Always:: |
| * Pragma Inline_Generic:: |
| * Pragma Interface:: |
| * Pragma Interface_Name:: |
| * Pragma Interrupt_Handler:: |
| * Pragma Interrupt_State:: |
| * Pragma Keep_Names:: |
| * Pragma License:: |
| * Pragma Link_With:: |
| * Pragma Linker_Alias:: |
| * Pragma Linker_Constructor:: |
| * Pragma Linker_Destructor:: |
| * Pragma Linker_Section:: |
| * Pragma Long_Float:: |
| * Pragma Machine_Attribute:: |
| * Pragma Main_Storage:: |
| * Pragma No_Return:: |
| * Pragma No_Strict_Aliasing :: |
| * Pragma Normalize_Scalars:: |
| * Pragma Obsolescent:: |
| * Pragma Passive:: |
| * Pragma Persistent_BSS:: |
| * Pragma Polling:: |
| * Pragma Profile (Ravenscar):: |
| * Pragma Profile (Restricted):: |
| * Pragma Psect_Object:: |
| * Pragma Pure_Function:: |
| * Pragma Restriction_Warnings:: |
| * Pragma Source_File_Name:: |
| * Pragma Source_File_Name_Project:: |
| * Pragma Source_Reference:: |
| * Pragma Stream_Convert:: |
| * Pragma Style_Checks:: |
| * Pragma Subtitle:: |
| * Pragma Suppress_All:: |
| * Pragma Suppress_Exception_Locations:: |
| * Pragma Suppress_Initialization:: |
| * Pragma Task_Info:: |
| * Pragma Task_Name:: |
| * Pragma Task_Storage:: |
| * Pragma Thread_Body:: |
| * Pragma Time_Slice:: |
| * Pragma Title:: |
| * Pragma Unchecked_Union:: |
| * Pragma Unimplemented_Unit:: |
| * Pragma Universal_Data:: |
| * Pragma Unreferenced:: |
| * Pragma Unreserve_All_Interrupts:: |
| * Pragma Unsuppress:: |
| * Pragma Use_VADS_Size:: |
| * Pragma Validity_Checks:: |
| * Pragma Volatile:: |
| * Pragma Warnings:: |
| * Pragma Weak_External:: |
| |
| Implementation Defined Attributes |
| |
| * Abort_Signal:: |
| * Address_Size:: |
| * Asm_Input:: |
| * Asm_Output:: |
| * AST_Entry:: |
| * Bit:: |
| * Bit_Position:: |
| * Code_Address:: |
| * Default_Bit_Order:: |
| * Elaborated:: |
| * Elab_Body:: |
| * Elab_Spec:: |
| * Emax:: |
| * Enum_Rep:: |
| * Epsilon:: |
| * Fixed_Value:: |
| * Has_Access_Values:: |
| * Has_Discriminants:: |
| * Img:: |
| * Integer_Value:: |
| * Large:: |
| * Machine_Size:: |
| * Mantissa:: |
| * Max_Interrupt_Priority:: |
| * Max_Priority:: |
| * Maximum_Alignment:: |
| * Mechanism_Code:: |
| * Null_Parameter:: |
| * Object_Size:: |
| * Passed_By_Reference:: |
| * Range_Length:: |
| * Safe_Emax:: |
| * Safe_Large:: |
| * Small:: |
| * Storage_Unit:: |
| * Target_Name:: |
| * Tick:: |
| * To_Address:: |
| * Type_Class:: |
| * UET_Address:: |
| * Unconstrained_Array:: |
| * Universal_Literal_String:: |
| * Unrestricted_Access:: |
| * VADS_Size:: |
| * Value_Size:: |
| * Wchar_T_Size:: |
| * Word_Size:: |
| |
| The Implementation of Standard I/O |
| |
| * Standard I/O Packages:: |
| * FORM Strings:: |
| * Direct_IO:: |
| * Sequential_IO:: |
| * Text_IO:: |
| * Wide_Text_IO:: |
| * Wide_Wide_Text_IO:: |
| * Stream_IO:: |
| * Shared Files:: |
| * Open Modes:: |
| * Operations on C Streams:: |
| * Interfacing to C Streams:: |
| |
| The GNAT Library |
| |
| * Ada.Characters.Latin_9 (a-chlat9.ads):: |
| * Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: |
| * Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: |
| * Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads):: |
| * Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads):: |
| * Ada.Command_Line.Remove (a-colire.ads):: |
| * Ada.Command_Line.Environment (a-colien.ads):: |
| * Ada.Direct_IO.C_Streams (a-diocst.ads):: |
| * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: |
| * Ada.Exceptions.Traceback (a-exctra.ads):: |
| * Ada.Sequential_IO.C_Streams (a-siocst.ads):: |
| * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: |
| * Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: |
| * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: |
| * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads):: |
| * Ada.Text_IO.C_Streams (a-tiocst.ads):: |
| * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: |
| * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: |
| * GNAT.Altivec (g-altive.ads):: |
| * GNAT.Altivec.Conversions (g-altcon.ads):: |
| * GNAT.Altivec.Vector_Operations (g-alveop.ads):: |
| * GNAT.Altivec.Vector_Types (g-alvety.ads):: |
| * GNAT.Altivec.Vector_Views (g-alvevi.ads):: |
| * GNAT.Array_Split (g-arrspl.ads):: |
| * GNAT.AWK (g-awk.ads):: |
| * GNAT.Bounded_Buffers (g-boubuf.ads):: |
| * GNAT.Bounded_Mailboxes (g-boumai.ads):: |
| * GNAT.Bubble_Sort (g-bubsor.ads):: |
| * GNAT.Bubble_Sort_A (g-busora.ads):: |
| * GNAT.Bubble_Sort_G (g-busorg.ads):: |
| * GNAT.Calendar (g-calend.ads):: |
| * GNAT.Calendar.Time_IO (g-catiio.ads):: |
| * GNAT.Case_Util (g-casuti.ads):: |
| * GNAT.CGI (g-cgi.ads):: |
| * GNAT.CGI.Cookie (g-cgicoo.ads):: |
| * GNAT.CGI.Debug (g-cgideb.ads):: |
| * GNAT.Command_Line (g-comlin.ads):: |
| * GNAT.Compiler_Version (g-comver.ads):: |
| * GNAT.Ctrl_C (g-ctrl_c.ads):: |
| * GNAT.CRC32 (g-crc32.ads):: |
| * GNAT.Current_Exception (g-curexc.ads):: |
| * GNAT.Debug_Pools (g-debpoo.ads):: |
| * GNAT.Debug_Utilities (g-debuti.ads):: |
| * GNAT.Directory_Operations (g-dirope.ads):: |
| * GNAT.Dynamic_HTables (g-dynhta.ads):: |
| * GNAT.Dynamic_Tables (g-dyntab.ads):: |
| * GNAT.Exception_Actions (g-excact.ads):: |
| * GNAT.Exception_Traces (g-exctra.ads):: |
| * GNAT.Exceptions (g-except.ads):: |
| * GNAT.Expect (g-expect.ads):: |
| * GNAT.Float_Control (g-flocon.ads):: |
| * GNAT.Heap_Sort (g-heasor.ads):: |
| * GNAT.Heap_Sort_A (g-hesora.ads):: |
| * GNAT.Heap_Sort_G (g-hesorg.ads):: |
| * GNAT.HTable (g-htable.ads):: |
| * GNAT.IO (g-io.ads):: |
| * GNAT.IO_Aux (g-io_aux.ads):: |
| * GNAT.Lock_Files (g-locfil.ads):: |
| * GNAT.MD5 (g-md5.ads):: |
| * GNAT.Memory_Dump (g-memdum.ads):: |
| * GNAT.Most_Recent_Exception (g-moreex.ads):: |
| * GNAT.OS_Lib (g-os_lib.ads):: |
| * GNAT.Perfect_Hash_Generators (g-pehage.ads):: |
| * GNAT.Regexp (g-regexp.ads):: |
| * GNAT.Registry (g-regist.ads):: |
| * GNAT.Regpat (g-regpat.ads):: |
| * GNAT.Secondary_Stack_Info (g-sestin.ads):: |
| * GNAT.Semaphores (g-semaph.ads):: |
| * GNAT.Signals (g-signal.ads):: |
| * GNAT.Sockets (g-socket.ads):: |
| * GNAT.Source_Info (g-souinf.ads):: |
| * GNAT.Spell_Checker (g-speche.ads):: |
| * GNAT.Spitbol.Patterns (g-spipat.ads):: |
| * GNAT.Spitbol (g-spitbo.ads):: |
| * GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: |
| * GNAT.Spitbol.Table_Integer (g-sptain.ads):: |
| * GNAT.Spitbol.Table_VString (g-sptavs.ads):: |
| * GNAT.Strings (g-string.ads):: |
| * GNAT.String_Split (g-strspl.ads):: |
| * GNAT.Table (g-table.ads):: |
| * GNAT.Task_Lock (g-tasloc.ads):: |
| * GNAT.Threads (g-thread.ads):: |
| * GNAT.Traceback (g-traceb.ads):: |
| * GNAT.Traceback.Symbolic (g-trasym.ads):: |
| * GNAT.Wide_String_Split (g-wistsp.ads):: |
| * GNAT.Wide_Wide_String_Split (g-zistsp.ads):: |
| * Interfaces.C.Extensions (i-cexten.ads):: |
| * Interfaces.C.Streams (i-cstrea.ads):: |
| * Interfaces.CPP (i-cpp.ads):: |
| * Interfaces.Os2lib (i-os2lib.ads):: |
| * Interfaces.Os2lib.Errors (i-os2err.ads):: |
| * Interfaces.Os2lib.Synchronization (i-os2syn.ads):: |
| * Interfaces.Os2lib.Threads (i-os2thr.ads):: |
| * Interfaces.Packed_Decimal (i-pacdec.ads):: |
| * Interfaces.VxWorks (i-vxwork.ads):: |
| * Interfaces.VxWorks.IO (i-vxwoio.ads):: |
| * System.Address_Image (s-addima.ads):: |
| * System.Assertions (s-assert.ads):: |
| * System.Memory (s-memory.ads):: |
| * System.Partition_Interface (s-parint.ads):: |
| * System.Restrictions (s-restri.ads):: |
| * System.Rident (s-rident.ads):: |
| * System.Task_Info (s-tasinf.ads):: |
| * System.Wch_Cnv (s-wchcnv.ads):: |
| * System.Wch_Con (s-wchcon.ads):: |
| |
| Text_IO |
| |
| * Text_IO Stream Pointer Positioning:: |
| * Text_IO Reading and Writing Non-Regular Files:: |
| * Get_Immediate:: |
| * Treating Text_IO Files as Streams:: |
| * Text_IO Extensions:: |
| * Text_IO Facilities for Unbounded Strings:: |
| |
| Wide_Text_IO |
| |
| * Wide_Text_IO Stream Pointer Positioning:: |
| * Wide_Text_IO Reading and Writing Non-Regular Files:: |
| |
| Wide_Wide_Text_IO |
| |
| * Wide_Wide_Text_IO Stream Pointer Positioning:: |
| * Wide_Wide_Text_IO Reading and Writing Non-Regular Files:: |
| |
| Interfacing to Other Languages |
| |
| * Interfacing to C:: |
| * Interfacing to C++:: |
| * Interfacing to COBOL:: |
| * Interfacing to Fortran:: |
| * Interfacing to non-GNAT Ada code:: |
| |
| Specialized Needs Annexes |
| |
| Implementation of Specific Ada Features |
| * Machine Code Insertions:: |
| * GNAT Implementation of Tasking:: |
| * GNAT Implementation of Shared Passive Packages:: |
| * Code Generation for Array Aggregates:: |
| * The Size of Discriminated Records with Default Discriminants:: |
| * Strict Conformance to the Ada 95 Reference Manual:: |
| |
| Project File Reference |
| |
| Obsolescent Features |
| |
| GNU Free Documentation License |
| |
| Index |
| @end menu |
| |
| @end ifnottex |
| |
| @node About This Guide |
| @unnumbered About This Guide |
| |
| @ifclear PROEDITION |
| @noindent |
| This manual contains useful information in writing programs using the |
| GNAT compiler. It includes information on implementation dependent |
| characteristics of GNAT, including all the information required by Annex |
| M of the standard. |
| @end ifclear |
| |
| @ifset PROEDITION |
| @noindent |
| This manual contains useful information in writing programs using the |
| GNAT Pro compiler. It includes information on implementation dependent |
| characteristics of GNAT Pro, including all the information required by Annex |
| M of the standard. |
| @end ifset |
| |
| Ada 95 is designed to be highly portable. |
| In general, a program will have the same effect even when compiled by |
| different compilers on different platforms. |
| However, since Ada 95 is designed to be used in a |
| wide variety of applications, it also contains a number of system |
| dependent features to be used in interfacing to the external world. |
| @cindex Implementation-dependent features |
| @cindex Portability |
| |
| Note: Any program that makes use of implementation-dependent features |
| may be non-portable. You should follow good programming practice and |
| isolate and clearly document any sections of your program that make use |
| of these features in a non-portable manner. |
| |
| @ifset PROEDITION |
| For ease of exposition, ``GNAT Pro'' will be referred to simply as |
| ``GNAT'' in the remainder of this document. |
| @end ifset |
| |
| @menu |
| * What This Reference Manual Contains:: |
| * Conventions:: |
| * Related Information:: |
| @end menu |
| |
| @node What This Reference Manual Contains |
| @unnumberedsec What This Reference Manual Contains |
| |
| @noindent |
| This reference manual contains the following chapters: |
| |
| @itemize @bullet |
| @item |
| @ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent |
| pragmas, which can be used to extend and enhance the functionality of the |
| compiler. |
| |
| @item |
| @ref{Implementation Defined Attributes}, lists GNAT |
| implementation-dependent attributes which can be used to extend and |
| enhance the functionality of the compiler. |
| |
| @item |
| @ref{Implementation Advice}, provides information on generally |
| desirable behavior which are not requirements that all compilers must |
| follow since it cannot be provided on all systems, or which may be |
| undesirable on some systems. |
| |
| @item |
| @ref{Implementation Defined Characteristics}, provides a guide to |
| minimizing implementation dependent features. |
| |
| @item |
| @ref{Intrinsic Subprograms}, describes the intrinsic subprograms |
| implemented by GNAT, and how they can be imported into user |
| application programs. |
| |
| @item |
| @ref{Representation Clauses and Pragmas}, describes in detail the |
| way that GNAT represents data, and in particular the exact set |
| of representation clauses and pragmas that is accepted. |
| |
| @item |
| @ref{Standard Library Routines}, provides a listing of packages and a |
| brief description of the functionality that is provided by Ada's |
| extensive set of standard library routines as implemented by GNAT@. |
| |
| @item |
| @ref{The Implementation of Standard I/O}, details how the GNAT |
| implementation of the input-output facilities. |
| |
| @item |
| @ref{The GNAT Library}, is a catalog of packages that complement |
| the Ada predefined library. |
| |
| @item |
| @ref{Interfacing to Other Languages}, describes how programs |
| written in Ada using GNAT can be interfaced to other programming |
| languages. |
| |
| @ref{Specialized Needs Annexes}, describes the GNAT implementation of all |
| of the specialized needs annexes. |
| |
| @item |
| @ref{Implementation of Specific Ada Features}, discusses issues related |
| to GNAT's implementation of machine code insertions, tasking, and several |
| other features. |
| |
| @item |
| @ref{Project File Reference}, presents the syntax and semantics |
| of project files. |
| |
| @item |
| @ref{Obsolescent Features} documents implementation dependent features, |
| including pragmas and attributes, which are considered obsolescent, since |
| there are other preferred ways of achieving the same results. These |
| obsolescent forms are retained for backwards compatibility. |
| |
| @end itemize |
| |
| @cindex Ada 95 ISO/ANSI Standard |
| @noindent |
| This reference manual assumes that you are familiar with Ada 95 |
| language, as described in the International Standard |
| ANSI/ISO/IEC-8652:1995, Jan 1995. |
| |
| @node Conventions |
| @unnumberedsec Conventions |
| @cindex Conventions, typographical |
| @cindex Typographical conventions |
| |
| @noindent |
| Following are examples of the typographical and graphic conventions used |
| in this guide: |
| |
| @itemize @bullet |
| @item |
| @code{Functions}, @code{utility program names}, @code{standard names}, |
| and @code{classes}. |
| |
| @item |
| @code{Option flags} |
| |
| @item |
| @file{File Names}, @samp{button names}, and @samp{field names}. |
| |
| @item |
| @code{Variables}. |
| |
| @item |
| @emph{Emphasis}. |
| |
| @item |
| [optional information or parameters] |
| |
| @item |
| Examples are described by text |
| @smallexample |
| and then shown this way. |
| @end smallexample |
| @end itemize |
| |
| @noindent |
| Commands that are entered by the user are preceded in this manual by the |
| characters @samp{$ } (dollar sign followed by space). If your system uses this |
| sequence as a prompt, then the commands will appear exactly as you see them |
| in the manual. If your system uses some other prompt, then the command will |
| appear with the @samp{$} replaced by whatever prompt character you are using. |
| |
| @node Related Information |
| @unnumberedsec Related Information |
| @noindent |
| See the following documents for further information on GNAT: |
| |
| @itemize @bullet |
| @item |
| @cite{GNAT User's Guide}, which provides information on how to use |
| the GNAT compiler system. |
| |
| @item |
| @cite{Ada 95 Reference Manual}, which contains all reference |
| material for the Ada 95 programming language. |
| |
| @item |
| @cite{Ada 95 Annotated Reference Manual}, which is an annotated version |
| of the standard reference manual cited above. The annotations describe |
| detailed aspects of the design decision, and in particular contain useful |
| sections on Ada 83 compatibility. |
| |
| @item |
| @cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms}, |
| which contains specific information on compatibility between GNAT and |
| DEC Ada 83 systems. |
| |
| @item |
| @cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which |
| describes in detail the pragmas and attributes provided by the DEC Ada 83 |
| compiler system. |
| |
| @end itemize |
| |
| @node Implementation Defined Pragmas |
| @chapter Implementation Defined Pragmas |
| |
| @noindent |
| Ada 95 defines a set of pragmas that can be used to supply additional |
| information to the compiler. These language defined pragmas are |
| implemented in GNAT and work as described in the Ada 95 Reference |
| Manual. |
| |
| In addition, Ada 95 allows implementations to define additional pragmas |
| whose meaning is defined by the implementation. GNAT provides a number |
| of these implementation-dependent pragmas which can be used to extend |
| and enhance the functionality of the compiler. This section of the GNAT |
| Reference Manual describes these additional pragmas. |
| |
| Note that any program using these pragmas may not be portable to other |
| compilers (although GNAT implements this set of pragmas on all |
| platforms). Therefore if portability to other compilers is an important |
| consideration, the use of these pragmas should be minimized. |
| |
| @menu |
| * Pragma Abort_Defer:: |
| * Pragma Ada_83:: |
| * Pragma Ada_95:: |
| * Pragma Ada_05:: |
| * Pragma Ada_2005:: |
| * Pragma Annotate:: |
| * Pragma Assert:: |
| * Pragma Ast_Entry:: |
| * Pragma C_Pass_By_Copy:: |
| * Pragma Comment:: |
| * Pragma Common_Object:: |
| * Pragma Compile_Time_Warning:: |
| * Pragma Complete_Representation:: |
| * Pragma Complex_Representation:: |
| * Pragma Component_Alignment:: |
| * Pragma Convention_Identifier:: |
| * Pragma CPP_Class:: |
| * Pragma CPP_Constructor:: |
| * Pragma CPP_Virtual:: |
| * Pragma CPP_Vtable:: |
| * Pragma Debug:: |
| * Pragma Debug_Policy:: |
| * Pragma Detect_Blocking:: |
| * Pragma Elaboration_Checks:: |
| * Pragma Eliminate:: |
| * Pragma Export_Exception:: |
| * Pragma Export_Function:: |
| * Pragma Export_Object:: |
| * Pragma Export_Procedure:: |
| * Pragma Export_Value:: |
| * Pragma Export_Valued_Procedure:: |
| * Pragma Extend_System:: |
| * Pragma External:: |
| * Pragma External_Name_Casing:: |
| * Pragma Finalize_Storage_Only:: |
| * Pragma Float_Representation:: |
| * Pragma Ident:: |
| * Pragma Import_Exception:: |
| * Pragma Import_Function:: |
| * Pragma Import_Object:: |
| * Pragma Import_Procedure:: |
| * Pragma Import_Valued_Procedure:: |
| * Pragma Initialize_Scalars:: |
| * Pragma Inline_Always:: |
| * Pragma Inline_Generic:: |
| * Pragma Interface:: |
| * Pragma Interface_Name:: |
| * Pragma Interrupt_Handler:: |
| * Pragma Interrupt_State:: |
| * Pragma Keep_Names:: |
| * Pragma License:: |
| * Pragma Link_With:: |
| * Pragma Linker_Alias:: |
| * Pragma Linker_Constructor:: |
| * Pragma Linker_Destructor:: |
| * Pragma Linker_Section:: |
| * Pragma Long_Float:: |
| * Pragma Machine_Attribute:: |
| * Pragma Main_Storage:: |
| * Pragma No_Return:: |
| * Pragma No_Strict_Aliasing:: |
| * Pragma Normalize_Scalars:: |
| * Pragma Obsolescent:: |
| * Pragma Passive:: |
| * Pragma Persistent_BSS:: |
| * Pragma Polling:: |
| * Pragma Profile (Ravenscar):: |
| * Pragma Profile (Restricted):: |
| * Pragma Psect_Object:: |
| * Pragma Pure_Function:: |
| * Pragma Restriction_Warnings:: |
| * Pragma Source_File_Name:: |
| * Pragma Source_File_Name_Project:: |
| * Pragma Source_Reference:: |
| * Pragma Stream_Convert:: |
| * Pragma Style_Checks:: |
| * Pragma Subtitle:: |
| * Pragma Suppress_All:: |
| * Pragma Suppress_Exception_Locations:: |
| * Pragma Suppress_Initialization:: |
| * Pragma Task_Info:: |
| * Pragma Task_Name:: |
| * Pragma Task_Storage:: |
| * Pragma Thread_Body:: |
| * Pragma Time_Slice:: |
| * Pragma Title:: |
| * Pragma Unchecked_Union:: |
| * Pragma Unimplemented_Unit:: |
| * Pragma Universal_Data:: |
| * Pragma Unreferenced:: |
| * Pragma Unreserve_All_Interrupts:: |
| * Pragma Unsuppress:: |
| * Pragma Use_VADS_Size:: |
| * Pragma Validity_Checks:: |
| * Pragma Volatile:: |
| * Pragma Warnings:: |
| * Pragma Weak_External:: |
| @end menu |
| |
| @node Pragma Abort_Defer |
| @unnumberedsec Pragma Abort_Defer |
| @findex Abort_Defer |
| @cindex Deferring aborts |
| @noindent |
| Syntax: |
| @smallexample |
| pragma Abort_Defer; |
| @end smallexample |
| |
| @noindent |
| This pragma must appear at the start of the statement sequence of a |
| handled sequence of statements (right after the @code{begin}). It has |
| the effect of deferring aborts for the sequence of statements (but not |
| for the declarations or handlers, if any, associated with this statement |
| sequence). |
| |
| @node Pragma Ada_83 |
| @unnumberedsec Pragma Ada_83 |
| @findex Ada_83 |
| @noindent |
| Syntax: |
| @smallexample @c ada |
| pragma Ada_83; |
| @end smallexample |
| |
| @noindent |
| A configuration pragma that establishes Ada 83 mode for the unit to |
| which it applies, regardless of the mode set by the command line |
| switches. In Ada 83 mode, GNAT attempts to be as compatible with |
| the syntax and semantics of Ada 83, as defined in the original Ada |
| 83 Reference Manual as possible. In particular, the new Ada 95 |
| keywords are not recognized, optional package bodies are allowed, |
| and generics may name types with unknown discriminants without using |
| the @code{(<>)} notation. In addition, some but not all of the additional |
| restrictions of Ada 83 are enforced. |
| |
| Ada 83 mode is intended for two purposes. Firstly, it allows existing |
| legacy Ada 83 code to be compiled and adapted to GNAT with less effort. |
| Secondly, it aids in keeping code backwards compatible with Ada 83. |
| However, there is no guarantee that code that is processed correctly |
| by GNAT in Ada 83 mode will in fact compile and execute with an Ada |
| 83 compiler, since GNAT does not enforce all the additional checks |
| required by Ada 83. |
| |
| @node Pragma Ada_95 |
| @unnumberedsec Pragma Ada_95 |
| @findex Ada_95 |
| @noindent |
| Syntax: |
| @smallexample @c ada |
| pragma Ada_95; |
| @end smallexample |
| |
| @noindent |
| A configuration pragma that establishes Ada 95 mode for the unit to which |
| it applies, regardless of the mode set by the command line switches. |
| This mode is set automatically for the @code{Ada} and @code{System} |
| packages and their children, so you need not specify it in these |
| contexts. This pragma is useful when writing a reusable component that |
| itself uses Ada 95 features, but which is intended to be usable from |
| either Ada 83 or Ada 95 programs. |
| |
| @node Pragma Ada_05 |
| @unnumberedsec Pragma Ada_05 |
| @findex Ada_05 |
| @noindent |
| Syntax: |
| @smallexample @c ada |
| pragma Ada_05; |
| @end smallexample |
| |
| @noindent |
| A configuration pragma that establishes Ada 2005 mode for the unit to which |
| it applies, regardless of the mode set by the command line switches. |
| This mode is set automatically for the @code{Ada} and @code{System} |
| packages and their children, so you need not specify it in these |
| contexts. This pragma is useful when writing a reusable component that |
| itself uses Ada 2005 features, but which is intended to be usable from |
| either Ada 83 or Ada 95 programs. |
| |
| @node Pragma Ada_2005 |
| @unnumberedsec Pragma Ada_2005 |
| @findex Ada_2005 |
| @noindent |
| Syntax: |
| @smallexample @c ada |
| pragma Ada_2005; |
| @end smallexample |
| |
| @noindent |
| This configuration pragma is a synonym for pragma Ada_05 and has the |
| same syntax and effect. |
| |
| @node Pragma Annotate |
| @unnumberedsec Pragma Annotate |
| @findex Annotate |
| @noindent |
| Syntax: |
| @smallexample @c ada |
| pragma Annotate (IDENTIFIER @{, ARG@}); |
| |
| ARG ::= NAME | EXPRESSION |
| @end smallexample |
| |
| @noindent |
| This pragma is used to annotate programs. @var{identifier} identifies |
| the type of annotation. GNAT verifies this is an identifier, but does |
| not otherwise analyze it. The @var{arg} argument |
| can be either a string literal or an |
| expression. String literals are assumed to be of type |
| @code{Standard.String}. Names of entities are simply analyzed as entity |
| names. All other expressions are analyzed as expressions, and must be |
| unambiguous. |
| |
| The analyzed pragma is retained in the tree, but not otherwise processed |
| by any part of the GNAT compiler. This pragma is intended for use by |
| external tools, including ASIS@. |
| |
| @node Pragma Assert |
| @unnumberedsec Pragma Assert |
| @findex Assert |
| @noindent |
| Syntax: |
| @smallexample @c ada |
| pragma Assert ( |
| boolean_EXPRESSION |
| [, static_string_EXPRESSION]); |
| @end smallexample |
| |
| @noindent |
| The effect of this pragma depends on whether the corresponding command |
| line switch is set to activate assertions. The pragma expands into code |
| equivalent to the following: |
| |
| @smallexample @c ada |
| if assertions-enabled then |
| if not boolean_EXPRESSION then |
| System.Assertions.Raise_Assert_Failure |
| (string_EXPRESSION); |
| end if; |
| end if; |
| @end smallexample |
| |
| @noindent |
| The string argument, if given, is the message that will be associated |
| with the exception occurrence if the exception is raised. If no second |
| argument is given, the default message is @samp{@var{file}:@var{nnn}}, |
| where @var{file} is the name of the source file containing the assert, |
| and @var{nnn} is the line number of the assert. A pragma is not a |
| statement, so if a statement sequence contains nothing but a pragma |
| assert, then a null statement is required in addition, as in: |
| |
| @smallexample @c ada |
| @dots{} |
| if J > 3 then |
| pragma Assert (K > 3, "Bad value for K"); |
| null; |
| end if; |
| @end smallexample |
| |
| @noindent |
| Note that, as with the @code{if} statement to which it is equivalent, the |
| type of the expression is either @code{Standard.Boolean}, or any type derived |
| from this standard type. |
| |
| If assertions are disabled (switch @code{-gnata} not used), then there |
| is no effect (and in particular, any side effects from the expression |
| are suppressed). More precisely it is not quite true that the pragma |
| has no effect, since the expression is analyzed, and may cause types |
| to be frozen if they are mentioned here for the first time. |
| |
| If assertions are enabled, then the given expression is tested, and if |
| it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called |
| which results in the raising of @code{Assert_Failure} with the given message. |
| |
| If the boolean expression has side effects, these side effects will turn |
| on and off with the setting of the assertions mode, resulting in |
| assertions that have an effect on the program. You should generally |
| avoid side effects in the expression arguments of this pragma. However, |
| the expressions are analyzed for semantic correctness whether or not |
| assertions are enabled, so turning assertions on and off cannot affect |
| the legality of a program. |
| |
| @node Pragma Ast_Entry |
| @unnumberedsec Pragma Ast_Entry |
| @cindex OpenVMS |
| @findex Ast_Entry |
| @noindent |
| Syntax: |
| @smallexample @c ada |
| pragma AST_Entry (entry_IDENTIFIER); |
| @end smallexample |
| |
| @noindent |
| This pragma is implemented only in the OpenVMS implementation of GNAT@. The |
| argument is the simple name of a single entry; at most one @code{AST_Entry} |
| pragma is allowed for any given entry. This pragma must be used in |
| conjunction with the @code{AST_Entry} attribute, and is only allowed after |
| the entry declaration and in the same task type specification or single task |
| as the entry to which it applies. This pragma specifies that the given entry |
| may be used to handle an OpenVMS asynchronous system trap (@code{AST}) |
| resulting from an OpenVMS system service call. The pragma does not affect |
| normal use of the entry. For further details on this pragma, see the |
| DEC Ada Language Reference Manual, section 9.12a. |
| |
| @node Pragma C_Pass_By_Copy |
| @unnumberedsec Pragma C_Pass_By_Copy |
| @cindex Passing by copy |
| @findex C_Pass_By_Copy |
| @noindent |
| Syntax: |
| @smallexample @c ada |
| pragma C_Pass_By_Copy |
| ([Max_Size =>] static_integer_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| Normally the default mechanism for passing C convention records to C |
| convention subprograms is to pass them by reference, as suggested by RM |
| B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change |
| this default, by requiring that record formal parameters be passed by |
| copy if all of the following conditions are met: |
| |
| @itemize @bullet |
| @item |
| The size of the record type does not exceed@*@var{static_integer_expression}. |
| @item |
| The record type has @code{Convention C}. |
| @item |
| The formal parameter has this record type, and the subprogram has a |
| foreign (non-Ada) convention. |
| @end itemize |
| |
| @noindent |
| If these conditions are met the argument is passed by copy, i.e.@: in a |
| manner consistent with what C expects if the corresponding formal in the |
| C prototype is a struct (rather than a pointer to a struct). |
| |
| You can also pass records by copy by specifying the convention |
| @code{C_Pass_By_Copy} for the record type, or by using the extended |
| @code{Import} and @code{Export} pragmas, which allow specification of |
| passing mechanisms on a parameter by parameter basis. |
| |
| @node Pragma Comment |
| @unnumberedsec Pragma Comment |
| @findex Comment |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Comment (static_string_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| This is almost identical in effect to pragma @code{Ident}. It allows the |
| placement of a comment into the object file and hence into the |
| executable file if the operating system permits such usage. The |
| difference is that @code{Comment}, unlike @code{Ident}, has |
| no limitations on placement of the pragma (it can be placed |
| anywhere in the main source unit), and if more than one pragma |
| is used, all comments are retained. |
| |
| @node Pragma Common_Object |
| @unnumberedsec Pragma Common_Object |
| @findex Common_Object |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Common_Object ( |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Size =>] EXTERNAL_SYMBOL] ); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| @end smallexample |
| |
| @noindent |
| This pragma enables the shared use of variables stored in overlaid |
| linker areas corresponding to the use of @code{COMMON} |
| in Fortran. The single |
| object @var{local_NAME} is assigned to the area designated by |
| the @var{External} argument. |
| You may define a record to correspond to a series |
| of fields. The @var{size} argument |
| is syntax checked in GNAT, but otherwise ignored. |
| |
| @code{Common_Object} is not supported on all platforms. If no |
| support is available, then the code generator will issue a message |
| indicating that the necessary attribute for implementation of this |
| pragma is not available. |
| |
| @node Pragma Compile_Time_Warning |
| @unnumberedsec Pragma Compile_Time_Warning |
| @findex Compile_Time_Warning |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Compile_Time_Warning |
| (boolean_EXPRESSION, static_string_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| This pragma can be used to generate additional compile time warnings. It |
| is particularly useful in generics, where warnings can be issued for |
| specific problematic instantiations. The first parameter is a boolean |
| expression. The pragma is effective only if the value of this expression |
| is known at compile time, and has the value True. The set of expressions |
| whose values are known at compile time includes all static boolean |
| expressions, and also other values which the compiler can determine |
| at compile time (e.g. the size of a record type set by an explicit |
| size representation clause, or the value of a variable which was |
| initialized to a constant and is known not to have been modified). |
| If these conditions are met, a warning message is generated using |
| the value given as the second argument. This string value may contain |
| embedded ASCII.LF characters to break the message into multiple lines. |
| |
| @node Pragma Complete_Representation |
| @unnumberedsec Pragma Complete_Representation |
| @findex Complete_Representation |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Complete_Representation; |
| @end smallexample |
| |
| @noindent |
| This pragma must appear immediately within a record representation |
| clause. Typical placements are before the first component clause |
| or after the last component clause. The effect is to give an error |
| message if any component is missing a component clause. This pragma |
| may be used to ensure that a record representation clause is |
| complete, and that this invariant is maintained if fields are |
| added to the record in the future. |
| |
| @node Pragma Complex_Representation |
| @unnumberedsec Pragma Complex_Representation |
| @findex Complex_Representation |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Complex_Representation |
| ([Entity =>] local_NAME); |
| @end smallexample |
| |
| @noindent |
| The @var{Entity} argument must be the name of a record type which has |
| two fields of the same floating-point type. The effect of this pragma is |
| to force gcc to use the special internal complex representation form for |
| this record, which may be more efficient. Note that this may result in |
| the code for this type not conforming to standard ABI (application |
| binary interface) requirements for the handling of record types. For |
| example, in some environments, there is a requirement for passing |
| records by pointer, and the use of this pragma may result in passing |
| this type in floating-point registers. |
| |
| @node Pragma Component_Alignment |
| @unnumberedsec Pragma Component_Alignment |
| @cindex Alignments of components |
| @findex Component_Alignment |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Component_Alignment ( |
| [Form =>] ALIGNMENT_CHOICE |
| [, [Name =>] type_local_NAME]); |
| |
| ALIGNMENT_CHOICE ::= |
| Component_Size |
| | Component_Size_4 |
| | Storage_Unit |
| | Default |
| @end smallexample |
| |
| @noindent |
| Specifies the alignment of components in array or record types. |
| The meaning of the @var{Form} argument is as follows: |
| |
| @table @code |
| @findex Component_Size |
| @item Component_Size |
| Aligns scalar components and subcomponents of the array or record type |
| on boundaries appropriate to their inherent size (naturally |
| aligned). For example, 1-byte components are aligned on byte boundaries, |
| 2-byte integer components are aligned on 2-byte boundaries, 4-byte |
| integer components are aligned on 4-byte boundaries and so on. These |
| alignment rules correspond to the normal rules for C compilers on all |
| machines except the VAX@. |
| |
| @findex Component_Size_4 |
| @item Component_Size_4 |
| Naturally aligns components with a size of four or fewer |
| bytes. Components that are larger than 4 bytes are placed on the next |
| 4-byte boundary. |
| |
| @findex Storage_Unit |
| @item Storage_Unit |
| Specifies that array or record components are byte aligned, i.e.@: |
| aligned on boundaries determined by the value of the constant |
| @code{System.Storage_Unit}. |
| |
| @cindex OpenVMS |
| @item Default |
| Specifies that array or record components are aligned on default |
| boundaries, appropriate to the underlying hardware or operating system or |
| both. For OpenVMS VAX systems, the @code{Default} choice is the same as |
| the @code{Storage_Unit} choice (byte alignment). For all other systems, |
| the @code{Default} choice is the same as @code{Component_Size} (natural |
| alignment). |
| @end table |
| |
| @noindent |
| If the @code{Name} parameter is present, @var{type_local_NAME} must |
| refer to a local record or array type, and the specified alignment |
| choice applies to the specified type. The use of |
| @code{Component_Alignment} together with a pragma @code{Pack} causes the |
| @code{Component_Alignment} pragma to be ignored. The use of |
| @code{Component_Alignment} together with a record representation clause |
| is only effective for fields not specified by the representation clause. |
| |
| If the @code{Name} parameter is absent, the pragma can be used as either |
| a configuration pragma, in which case it applies to one or more units in |
| accordance with the normal rules for configuration pragmas, or it can be |
| used within a declarative part, in which case it applies to types that |
| are declared within this declarative part, or within any nested scope |
| within this declarative part. In either case it specifies the alignment |
| to be applied to any record or array type which has otherwise standard |
| representation. |
| |
| If the alignment for a record or array type is not specified (using |
| pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep |
| clause), the GNAT uses the default alignment as described previously. |
| |
| @node Pragma Convention_Identifier |
| @unnumberedsec Pragma Convention_Identifier |
| @findex Convention_Identifier |
| @cindex Conventions, synonyms |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Convention_Identifier ( |
| [Name =>] IDENTIFIER, |
| [Convention =>] convention_IDENTIFIER); |
| @end smallexample |
| |
| @noindent |
| This pragma provides a mechanism for supplying synonyms for existing |
| convention identifiers. The @code{Name} identifier can subsequently |
| be used as a synonym for the given convention in other pragmas (including |
| for example pragma @code{Import} or another @code{Convention_Identifier} |
| pragma). As an example of the use of this, suppose you had legacy code |
| which used Fortran77 as the identifier for Fortran. Then the pragma: |
| |
| @smallexample @c ada |
| pragma Convention_Identifier (Fortran77, Fortran); |
| @end smallexample |
| |
| @noindent |
| would allow the use of the convention identifier @code{Fortran77} in |
| subsequent code, avoiding the need to modify the sources. As another |
| example, you could use this to parametrize convention requirements |
| according to systems. Suppose you needed to use @code{Stdcall} on |
| windows systems, and @code{C} on some other system, then you could |
| define a convention identifier @code{Library} and use a single |
| @code{Convention_Identifier} pragma to specify which convention |
| would be used system-wide. |
| |
| @node Pragma CPP_Class |
| @unnumberedsec Pragma CPP_Class |
| @findex CPP_Class |
| @cindex Interfacing with C++ |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma CPP_Class ([Entity =>] local_NAME); |
| @end smallexample |
| |
| @noindent |
| The argument denotes an entity in the current declarative region |
| that is declared as a tagged or untagged record type. It indicates that |
| the type corresponds to an externally declared C++ class type, and is to |
| be laid out the same way that C++ would lay out the type. |
| |
| If (and only if) the type is tagged, at least one component in the |
| record must be of type @code{Interfaces.CPP.Vtable_Ptr}, corresponding |
| to the C++ Vtable (or Vtables in the case of multiple inheritance) used |
| for dispatching. |
| |
| Types for which @code{CPP_Class} is specified do not have assignment or |
| equality operators defined (such operations can be imported or declared |
| as subprograms as required). Initialization is allowed only by |
| constructor functions (see pragma @code{CPP_Constructor}). |
| |
| Pragma @code{CPP_Class} is intended primarily for automatic generation |
| using an automatic binding generator tool. |
| See @ref{Interfacing to C++} for related information. |
| |
| @node Pragma CPP_Constructor |
| @unnumberedsec Pragma CPP_Constructor |
| @cindex Interfacing with C++ |
| @findex CPP_Constructor |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma CPP_Constructor ([Entity =>] local_NAME); |
| @end smallexample |
| |
| @noindent |
| This pragma identifies an imported function (imported in the usual way |
| with pragma @code{Import}) as corresponding to a C++ |
| constructor. The argument is a name that must have been |
| previously mentioned in a pragma @code{Import} |
| with @code{Convention} = @code{CPP}, and must be of one of the following |
| forms: |
| |
| @itemize @bullet |
| @item |
| @code{function @var{Fname} return @var{T}'Class} |
| |
| @item |
| @code{function @var{Fname} (@dots{}) return @var{T}'Class} |
| @end itemize |
| |
| @noindent |
| where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies. |
| |
| The first form is the default constructor, used when an object of type |
| @var{T} is created on the Ada side with no explicit constructor. Other |
| constructors (including the copy constructor, which is simply a special |
| case of the second form in which the one and only argument is of type |
| @var{T}), can only appear in two contexts: |
| |
| @itemize @bullet |
| @item |
| On the right side of an initialization of an object of type @var{T}. |
| @item |
| In an extension aggregate for an object of a type derived from @var{T}. |
| @end itemize |
| |
| @noindent |
| Although the constructor is described as a function that returns a value |
| on the Ada side, it is typically a procedure with an extra implicit |
| argument (the object being initialized) at the implementation |
| level. GNAT issues the appropriate call, whatever it is, to get the |
| object properly initialized. |
| |
| In the case of derived objects, you may use one of two possible forms |
| for declaring and creating an object: |
| |
| @itemize @bullet |
| @item @code{New_Object : Derived_T} |
| @item @code{New_Object : Derived_T := (@var{constructor-call with} @dots{})} |
| @end itemize |
| |
| @noindent |
| In the first case the default constructor is called and extension fields |
| if any are initialized according to the default initialization |
| expressions in the Ada declaration. In the second case, the given |
| constructor is called and the extension aggregate indicates the explicit |
| values of the extension fields. |
| |
| If no constructors are imported, it is impossible to create any objects |
| on the Ada side. If no default constructor is imported, only the |
| initialization forms using an explicit call to a constructor are |
| permitted. |
| |
| Pragma @code{CPP_Constructor} is intended primarily for automatic generation |
| using an automatic binding generator tool. |
| See @ref{Interfacing to C++} for more related information. |
| |
| @node Pragma CPP_Virtual |
| @unnumberedsec Pragma CPP_Virtual |
| @cindex Interfacing to C++ |
| @findex CPP_Virtual |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma CPP_Virtual |
| [Entity =>] ENTITY, |
| [, [Vtable_Ptr =>] vtable_ENTITY,] |
| [, [Position =>] static_integer_EXPRESSION]); |
| @end smallexample |
| |
| @noindent |
| This pragma serves the same function as pragma @code{Import} in that |
| case of a virtual function imported from C++. The @var{Entity} argument |
| must be a |
| primitive subprogram of a tagged type to which pragma @code{CPP_Class} |
| applies. The @var{Vtable_Ptr} argument specifies |
| the Vtable_Ptr component which contains the |
| entry for this virtual function. The @var{Position} argument |
| is the sequential number |
| counting virtual functions for this Vtable starting at 1. |
| |
| The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if |
| there is one Vtable_Ptr present (single inheritance case) and all |
| virtual functions are imported. In that case the compiler can deduce both |
| these values. |
| |
| No @code{External_Name} or @code{Link_Name} arguments are required for a |
| virtual function, since it is always accessed indirectly via the |
| appropriate Vtable entry. |
| |
| Pragma @code{CPP_Virtual} is intended primarily for automatic generation |
| using an automatic binding generator tool. |
| See @ref{Interfacing to C++} for related information. |
| |
| @node Pragma CPP_Vtable |
| @unnumberedsec Pragma CPP_Vtable |
| @cindex Interfacing with C++ |
| @findex CPP_Vtable |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma CPP_Vtable ( |
| [Entity =>] ENTITY, |
| [Vtable_Ptr =>] vtable_ENTITY, |
| [Entry_Count =>] static_integer_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| Given a record to which the pragma @code{CPP_Class} applies, |
| this pragma can be specified for each component of type |
| @code{CPP.Interfaces.Vtable_Ptr}. |
| @var{Entity} is the tagged type, @var{Vtable_Ptr} |
| is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is |
| the number of virtual functions on the C++ side. Not all of these |
| functions need to be imported on the Ada side. |
| |
| You may omit the @code{CPP_Vtable} pragma if there is only one |
| @code{Vtable_Ptr} component in the record and all virtual functions are |
| imported on the Ada side (the default value for the entry count in this |
| case is simply the total number of virtual functions). |
| |
| Pragma @code{CPP_Vtable} is intended primarily for automatic generation |
| using an automatic binding generator tool. |
| See @ref{Interfacing to C++} for related information. |
| |
| @node Pragma Debug |
| @unnumberedsec Pragma Debug |
| @findex Debug |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); |
| |
| PROCEDURE_CALL_WITHOUT_SEMICOLON ::= |
| PROCEDURE_NAME |
| | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART |
| @end smallexample |
| |
| @noindent |
| The procedure call argument has the syntactic form of an expression, meeting |
| the syntactic requirements for pragmas. |
| |
| If debug pragmas are not enabled or if the condition is present and evaluates |
| to False, this pragma has no effect. If debug pragmas are enabled, the |
| semantics of the pragma is exactly equivalent to the procedure call statement |
| corresponding to the argument with a terminating semicolon. Pragmas are |
| permitted in sequences of declarations, so you can use pragma @code{Debug} to |
| intersperse calls to debug procedures in the middle of declarations. Debug |
| pragmas can be enabled either by use of the command line switch @code{-gnata} |
| or by use of the configuration pragma @code{Debug_Policy}. |
| |
| @node Pragma Debug_Policy |
| @unnumberedsec Pragma Debug_Policy |
| @findex Debug_Policy |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Debug_Policy (CHECK | IGNORE); |
| @end smallexample |
| |
| @noindent |
| If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled. |
| If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored. |
| This pragma overrides the effect of the @code{-gnata} switch on the |
| command line. |
| |
| @node Pragma Detect_Blocking |
| @unnumberedsec Pragma Detect_Blocking |
| @findex Detect_Blocking |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Detect_Blocking; |
| @end smallexample |
| |
| @noindent |
| This is a configuration pragma that forces the detection of potentially |
| blocking operations within a protected operation, and to raise Program_Error |
| if that happens. |
| |
| @node Pragma Elaboration_Checks |
| @unnumberedsec Pragma Elaboration_Checks |
| @cindex Elaboration control |
| @findex Elaboration_Checks |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Elaboration_Checks (Dynamic | Static); |
| @end smallexample |
| |
| @noindent |
| This is a configuration pragma that provides control over the |
| elaboration model used by the compilation affected by the |
| pragma. If the parameter is @code{Dynamic}, |
| then the dynamic elaboration |
| model described in the Ada Reference Manual is used, as though |
| the @code{-gnatE} switch had been specified on the command |
| line. If the parameter is @code{Static}, then the default GNAT static |
| model is used. This configuration pragma overrides the setting |
| of the command line. For full details on the elaboration models |
| used by the GNAT compiler, see section ``Elaboration Order |
| Handling in GNAT'' in the @cite{GNAT User's Guide}. |
| |
| @node Pragma Eliminate |
| @unnumberedsec Pragma Eliminate |
| @cindex Elimination of unused subprograms |
| @findex Eliminate |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Eliminate ( |
| [Unit_Name =>] IDENTIFIER | |
| SELECTED_COMPONENT); |
| |
| pragma Eliminate ( |
| [Unit_Name =>] IDENTIFIER | |
| SELECTED_COMPONENT, |
| [Entity =>] IDENTIFIER | |
| SELECTED_COMPONENT | |
| STRING_LITERAL |
| [,OVERLOADING_RESOLUTION]); |
| |
| OVERLOADING_RESOLUTION ::= PARAMETER_AND_RESULT_TYPE_PROFILE | |
| SOURCE_LOCATION |
| |
| PARAMETER_AND_RESULT_TYPE_PROFILE ::= PROCEDURE_PROFILE | |
| FUNCTION_PROFILE |
| |
| PROCEDURE_PROFILE ::= Parameter_Types => PARAMETER_TYPES |
| |
| FUNCTION_PROFILE ::= [Parameter_Types => PARAMETER_TYPES,] |
| Result_Type => result_SUBTYPE_NAME] |
| |
| PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@}) |
| SUBTYPE_NAME ::= STRING_VALUE |
| |
| SOURCE_LOCATION ::= Source_Location => SOURCE_TRACE |
| SOURCE_TRACE ::= STRING_VALUE |
| |
| STRING_VALUE ::= STRING_LITERAL @{& STRING_LITERAL@} |
| @end smallexample |
| |
| @noindent |
| This pragma indicates that the given entity is not used outside the |
| compilation unit it is defined in. The entity must be an explicitly declared |
| subprogram; this includes generic subprogram instances and |
| subprograms declared in generic package instances. |
| |
| If the entity to be eliminated is a library level subprogram, then |
| the first form of pragma @code{Eliminate} is used with only a single argument. |
| In this form, the @code{Unit_Name} argument specifies the name of the |
| library level unit to be eliminated. |
| |
| In all other cases, both @code{Unit_Name} and @code{Entity} arguments |
| are required. If item is an entity of a library package, then the first |
| argument specifies the unit name, and the second argument specifies |
| the particular entity. If the second argument is in string form, it must |
| correspond to the internal manner in which GNAT stores entity names (see |
| compilation unit Namet in the compiler sources for details). |
| |
| The remaining parameters (OVERLOADING_RESOLUTION) are optionally used |
| to distinguish between overloaded subprograms. If a pragma does not contain |
| the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded |
| subprograms denoted by the first two parameters. |
| |
| Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram |
| to be eliminated in a manner similar to that used for the extended |
| @code{Import} and @code{Export} pragmas, except that the subtype names are |
| always given as strings. At the moment, this form of distinguishing |
| overloaded subprograms is implemented only partially, so we do not recommend |
| using it for practical subprogram elimination. |
| |
| Note, that in case of a parameterless procedure its profile is represented |
| as @code{Parameter_Types => ("")} |
| |
| Alternatively, the @code{Source_Location} parameter is used to specify |
| which overloaded alternative is to be eliminated by pointing to the |
| location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the |
| source text. The string literal (or concatenation of string literals) |
| given as SOURCE_TRACE must have the following format: |
| |
| @smallexample @c ada |
| SOURCE_TRACE ::= SOURCE_LOCATION@{LBRACKET SOURCE_LOCATION RBRACKET@} |
| |
| LBRACKET ::= [ |
| RBRACKET ::= ] |
| |
| SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER |
| FILE_NAME ::= STRING_LITERAL |
| LINE_NUMBER ::= DIGIT @{DIGIT@} |
| @end smallexample |
| |
| SOURCE_TRACE should be the short name of the source file (with no directory |
| information), and LINE_NUMBER is supposed to point to the line where the |
| defining name of the subprogram is located. |
| |
| For the subprograms that are not a part of generic instantiations, only one |
| SOURCE_LOCATION is used. If a subprogram is declared in a package |
| instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is |
| the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the |
| second one denotes the declaration of the corresponding subprogram in the |
| generic package. This approach is recursively used to create SOURCE_LOCATIONs |
| in case of nested instantiations. |
| |
| The effect of the pragma is to allow the compiler to eliminate |
| the code or data associated with the named entity. Any reference to |
| an eliminated entity outside the compilation unit it is defined in, |
| causes a compile time or link time error. |
| |
| The intention of pragma @code{Eliminate} is to allow a program to be compiled |
| in a system independent manner, with unused entities eliminated, without |
| the requirement of modifying the source text. Normally the required set |
| of @code{Eliminate} pragmas is constructed automatically using the gnatelim |
| tool. Elimination of unused entities local to a compilation unit is |
| automatic, without requiring the use of pragma @code{Eliminate}. |
| |
| Note that the reason this pragma takes string literals where names might |
| be expected is that a pragma @code{Eliminate} can appear in a context where the |
| relevant names are not visible. |
| |
| Note that any change in the source files that includes removing, splitting of |
| adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION |
| parameter illegal. |
| |
| @node Pragma Export_Exception |
| @unnumberedsec Pragma Export_Exception |
| @cindex OpenVMS |
| @findex Export_Exception |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Export_Exception ( |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL,] |
| [, [Form =>] Ada | VMS] |
| [, [Code =>] static_integer_EXPRESSION]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| @end smallexample |
| |
| @noindent |
| This pragma is implemented only in the OpenVMS implementation of GNAT@. It |
| causes the specified exception to be propagated outside of the Ada program, |
| so that it can be handled by programs written in other OpenVMS languages. |
| This pragma establishes an external name for an Ada exception and makes the |
| name available to the OpenVMS Linker as a global symbol. For further details |
| on this pragma, see the |
| DEC Ada Language Reference Manual, section 13.9a3.2. |
| |
| @node Pragma Export_Function |
| @unnumberedsec Pragma Export_Function |
| @cindex Argument passing mechanisms |
| @findex Export_Function |
| |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Export_Function ( |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Result_Type =>] result_SUBTYPE_MARK] |
| [, [Mechanism =>] MECHANISM] |
| [, [Result_Mechanism =>] MECHANISM_NAME]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| | "" |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= |
| Value |
| | Reference |
| @end smallexample |
| |
| @noindent |
| Use this pragma to make a function externally callable and optionally |
| provide information on mechanisms to be used for passing parameter and |
| result values. We recommend, for the purposes of improving portability, |
| this pragma always be used in conjunction with a separate pragma |
| @code{Export}, which must precede the pragma @code{Export_Function}. |
| GNAT does not require a separate pragma @code{Export}, but if none is |
| present, @code{Convention Ada} is assumed, which is usually |
| not what is wanted, so it is usually appropriate to use this |
| pragma in conjunction with a @code{Export} or @code{Convention} |
| pragma that specifies the desired foreign convention. |
| Pragma @code{Export_Function} |
| (and @code{Export}, if present) must appear in the same declarative |
| region as the function to which they apply. |
| |
| @var{internal_name} must uniquely designate the function to which the |
| pragma applies. If more than one function name exists of this name in |
| the declarative part you must use the @code{Parameter_Types} and |
| @code{Result_Type} parameters is mandatory to achieve the required |
| unique designation. @var{subtype_ mark}s in these parameters must |
| exactly match the subtypes in the corresponding function specification, |
| using positional notation to match parameters with subtype marks. |
| The form with an @code{'Access} attribute can be used to match an |
| anonymous access parameter. |
| |
| @cindex OpenVMS |
| @cindex Passing by descriptor |
| Note that passing by descriptor is not supported, even on the OpenVMS |
| ports of GNAT@. |
| |
| @cindex Suppressing external name |
| Special treatment is given if the EXTERNAL is an explicit null |
| string or a static string expressions that evaluates to the null |
| string. In this case, no external name is generated. This form |
| still allows the specification of parameter mechanisms. |
| |
| @node Pragma Export_Object |
| @unnumberedsec Pragma Export_Object |
| @findex Export_Object |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Export_Object |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Size =>] EXTERNAL_SYMBOL] |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| @end smallexample |
| |
| @noindent |
| This pragma designates an object as exported, and apart from the |
| extended rules for external symbols, is identical in effect to the use of |
| the normal @code{Export} pragma applied to an object. You may use a |
| separate Export pragma (and you probably should from the point of view |
| of portability), but it is not required. @var{Size} is syntax checked, |
| but otherwise ignored by GNAT@. |
| |
| @node Pragma Export_Procedure |
| @unnumberedsec Pragma Export_Procedure |
| @findex Export_Procedure |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Export_Procedure ( |
| [Internal =>] local_NAME |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Mechanism =>] MECHANISM]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| | "" |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= |
| Value |
| | Reference |
| @end smallexample |
| |
| @noindent |
| This pragma is identical to @code{Export_Function} except that it |
| applies to a procedure rather than a function and the parameters |
| @code{Result_Type} and @code{Result_Mechanism} are not permitted. |
| GNAT does not require a separate pragma @code{Export}, but if none is |
| present, @code{Convention Ada} is assumed, which is usually |
| not what is wanted, so it is usually appropriate to use this |
| pragma in conjunction with a @code{Export} or @code{Convention} |
| pragma that specifies the desired foreign convention. |
| |
| @cindex OpenVMS |
| @cindex Passing by descriptor |
| Note that passing by descriptor is not supported, even on the OpenVMS |
| ports of GNAT@. |
| |
| @cindex Suppressing external name |
| Special treatment is given if the EXTERNAL is an explicit null |
| string or a static string expressions that evaluates to the null |
| string. In this case, no external name is generated. This form |
| still allows the specification of parameter mechanisms. |
| |
| @node Pragma Export_Value |
| @unnumberedsec Pragma Export_Value |
| @findex Export_Value |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Export_Value ( |
| [Value =>] static_integer_EXPRESSION, |
| [Link_Name =>] static_string_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| This pragma serves to export a static integer value for external use. |
| The first argument specifies the value to be exported. The Link_Name |
| argument specifies the symbolic name to be associated with the integer |
| value. This pragma is useful for defining a named static value in Ada |
| that can be referenced in assembly language units to be linked with |
| the application. This pragma is currently supported only for the |
| AAMP target and is ignored for other targets. |
| |
| @node Pragma Export_Valued_Procedure |
| @unnumberedsec Pragma Export_Valued_Procedure |
| @findex Export_Valued_Procedure |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Export_Valued_Procedure ( |
| [Internal =>] local_NAME |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Mechanism =>] MECHANISM]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| | "" |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= |
| Value |
| | Reference |
| @end smallexample |
| |
| @noindent |
| This pragma is identical to @code{Export_Procedure} except that the |
| first parameter of @var{local_NAME}, which must be present, must be of |
| mode @code{OUT}, and externally the subprogram is treated as a function |
| with this parameter as the result of the function. GNAT provides for |
| this capability to allow the use of @code{OUT} and @code{IN OUT} |
| parameters in interfacing to external functions (which are not permitted |
| in Ada functions). |
| GNAT does not require a separate pragma @code{Export}, but if none is |
| present, @code{Convention Ada} is assumed, which is almost certainly |
| not what is wanted since the whole point of this pragma is to interface |
| with foreign language functions, so it is usually appropriate to use this |
| pragma in conjunction with a @code{Export} or @code{Convention} |
| pragma that specifies the desired foreign convention. |
| |
| @cindex OpenVMS |
| @cindex Passing by descriptor |
| Note that passing by descriptor is not supported, even on the OpenVMS |
| ports of GNAT@. |
| |
| @cindex Suppressing external name |
| Special treatment is given if the EXTERNAL is an explicit null |
| string or a static string expressions that evaluates to the null |
| string. In this case, no external name is generated. This form |
| still allows the specification of parameter mechanisms. |
| |
| @node Pragma Extend_System |
| @unnumberedsec Pragma Extend_System |
| @cindex @code{system}, extending |
| @cindex Dec Ada 83 |
| @findex Extend_System |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Extend_System ([Name =>] IDENTIFIER); |
| @end smallexample |
| |
| @noindent |
| This pragma is used to provide backwards compatibility with other |
| implementations that extend the facilities of package @code{System}. In |
| GNAT, @code{System} contains only the definitions that are present in |
| the Ada 95 RM@. However, other implementations, notably the DEC Ada 83 |
| implementation, provide many extensions to package @code{System}. |
| |
| For each such implementation accommodated by this pragma, GNAT provides a |
| package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83 |
| implementation, which provides the required additional definitions. You |
| can use this package in two ways. You can @code{with} it in the normal |
| way and access entities either by selection or using a @code{use} |
| clause. In this case no special processing is required. |
| |
| However, if existing code contains references such as |
| @code{System.@var{xxx}} where @var{xxx} is an entity in the extended |
| definitions provided in package @code{System}, you may use this pragma |
| to extend visibility in @code{System} in a non-standard way that |
| provides greater compatibility with the existing code. Pragma |
| @code{Extend_System} is a configuration pragma whose single argument is |
| the name of the package containing the extended definition |
| (e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under |
| control of this pragma will be processed using special visibility |
| processing that looks in package @code{System.Aux_@var{xxx}} where |
| @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in |
| package @code{System}, but not found in package @code{System}. |
| |
| You can use this pragma either to access a predefined @code{System} |
| extension supplied with the compiler, for example @code{Aux_DEC} or |
| you can construct your own extension unit following the above |
| definition. Note that such a package is a child of @code{System} |
| and thus is considered part of the implementation. To compile |
| it you will have to use the appropriate switch for compiling |
| system units. See the GNAT User's Guide for details. |
| |
| @node Pragma External |
| @unnumberedsec Pragma External |
| @findex External |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma External ( |
| [ Convention =>] convention_IDENTIFIER, |
| [ Entity =>] local_NAME |
| [, [External_Name =>] static_string_EXPRESSION ] |
| [, [Link_Name =>] static_string_EXPRESSION ]); |
| @end smallexample |
| |
| @noindent |
| This pragma is identical in syntax and semantics to pragma |
| @code{Export} as defined in the Ada Reference Manual. It is |
| provided for compatibility with some Ada 83 compilers that |
| used this pragma for exactly the same purposes as pragma |
| @code{Export} before the latter was standardized. |
| |
| @node Pragma External_Name_Casing |
| @unnumberedsec Pragma External_Name_Casing |
| @cindex Dec Ada 83 casing compatibility |
| @cindex External Names, casing |
| @cindex Casing of External names |
| @findex External_Name_Casing |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma External_Name_Casing ( |
| Uppercase | Lowercase |
| [, Uppercase | Lowercase | As_Is]); |
| @end smallexample |
| |
| @noindent |
| This pragma provides control over the casing of external names associated |
| with Import and Export pragmas. There are two cases to consider: |
| |
| @table @asis |
| @item Implicit external names |
| Implicit external names are derived from identifiers. The most common case |
| arises when a standard Ada 95 Import or Export pragma is used with only two |
| arguments, as in: |
| |
| @smallexample @c ada |
| pragma Import (C, C_Routine); |
| @end smallexample |
| |
| @noindent |
| Since Ada is a case insensitive language, the spelling of the identifier in |
| the Ada source program does not provide any information on the desired |
| casing of the external name, and so a convention is needed. In GNAT the |
| default treatment is that such names are converted to all lower case |
| letters. This corresponds to the normal C style in many environments. |
| The first argument of pragma @code{External_Name_Casing} can be used to |
| control this treatment. If @code{Uppercase} is specified, then the name |
| will be forced to all uppercase letters. If @code{Lowercase} is specified, |
| then the normal default of all lower case letters will be used. |
| |
| This same implicit treatment is also used in the case of extended DEC Ada 83 |
| compatible Import and Export pragmas where an external name is explicitly |
| specified using an identifier rather than a string. |
| |
| @item Explicit external names |
| Explicit external names are given as string literals. The most common case |
| arises when a standard Ada 95 Import or Export pragma is used with three |
| arguments, as in: |
| |
| @smallexample @c ada |
| pragma Import (C, C_Routine, "C_routine"); |
| @end smallexample |
| |
| @noindent |
| In this case, the string literal normally provides the exact casing required |
| for the external name. The second argument of pragma |
| @code{External_Name_Casing} may be used to modify this behavior. |
| If @code{Uppercase} is specified, then the name |
| will be forced to all uppercase letters. If @code{Lowercase} is specified, |
| then the name will be forced to all lowercase letters. A specification of |
| @code{As_Is} provides the normal default behavior in which the casing is |
| taken from the string provided. |
| @end table |
| |
| @noindent |
| This pragma may appear anywhere that a pragma is valid. In particular, it |
| can be used as a configuration pragma in the @file{gnat.adc} file, in which |
| case it applies to all subsequent compilations, or it can be used as a program |
| unit pragma, in which case it only applies to the current unit, or it can |
| be used more locally to control individual Import/Export pragmas. |
| |
| It is primarily intended for use with OpenVMS systems, where many |
| compilers convert all symbols to upper case by default. For interfacing to |
| such compilers (e.g.@: the DEC C compiler), it may be convenient to use |
| the pragma: |
| |
| @smallexample @c ada |
| pragma External_Name_Casing (Uppercase, Uppercase); |
| @end smallexample |
| |
| @noindent |
| to enforce the upper casing of all external symbols. |
| |
| @node Pragma Finalize_Storage_Only |
| @unnumberedsec Pragma Finalize_Storage_Only |
| @findex Finalize_Storage_Only |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Finalize_Storage_Only (first_subtype_local_NAME); |
| @end smallexample |
| |
| @noindent |
| This pragma allows the compiler not to emit a Finalize call for objects |
| defined at the library level. This is mostly useful for types where |
| finalization is only used to deal with storage reclamation since in most |
| environments it is not necessary to reclaim memory just before terminating |
| execution, hence the name. |
| |
| @node Pragma Float_Representation |
| @unnumberedsec Pragma Float_Representation |
| @cindex OpenVMS |
| @findex Float_Representation |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); |
| |
| FLOAT_REP ::= VAX_Float | IEEE_Float |
| @end smallexample |
| |
| @noindent |
| In the one argument form, this pragma is a configuration pragma which |
| allows control over the internal representation chosen for the predefined |
| floating point types declared in the packages @code{Standard} and |
| @code{System}. On all systems other than OpenVMS, the argument must |
| be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the |
| argument may be @code{VAX_Float} to specify the use of the VAX float |
| format for the floating-point types in Standard. This requires that |
| the standard runtime libraries be recompiled. See the |
| description of the @code{GNAT LIBRARY} command in the OpenVMS version |
| of the GNAT Users Guide for details on the use of this command. |
| |
| The two argument form specifies the representation to be used for |
| the specified floating-point type. On all systems other than OpenVMS, |
| the argument must |
| be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the |
| argument may be @code{VAX_Float} to specify the use of the VAX float |
| format, as follows: |
| |
| @itemize @bullet |
| @item |
| For digits values up to 6, F float format will be used. |
| @item |
| For digits values from 7 to 9, G float format will be used. |
| @item |
| For digits values from 10 to 15, F float format will be used. |
| @item |
| Digits values above 15 are not allowed. |
| @end itemize |
| |
| @node Pragma Ident |
| @unnumberedsec Pragma Ident |
| @findex Ident |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Ident (static_string_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| This pragma provides a string identification in the generated object file, |
| if the system supports the concept of this kind of identification string. |
| This pragma is allowed only in the outermost declarative part or |
| declarative items of a compilation unit. If more than one @code{Ident} |
| pragma is given, only the last one processed is effective. |
| @cindex OpenVMS |
| On OpenVMS systems, the effect of the pragma is identical to the effect of |
| the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the |
| maximum allowed length is 31 characters, so if it is important to |
| maintain compatibility with this compiler, you should obey this length |
| limit. |
| |
| @node Pragma Import_Exception |
| @unnumberedsec Pragma Import_Exception |
| @cindex OpenVMS |
| @findex Import_Exception |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Import_Exception ( |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL,] |
| [, [Form =>] Ada | VMS] |
| [, [Code =>] static_integer_EXPRESSION]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| @end smallexample |
| |
| @noindent |
| This pragma is implemented only in the OpenVMS implementation of GNAT@. |
| It allows OpenVMS conditions (for example, from OpenVMS system services or |
| other OpenVMS languages) to be propagated to Ada programs as Ada exceptions. |
| The pragma specifies that the exception associated with an exception |
| declaration in an Ada program be defined externally (in non-Ada code). |
| For further details on this pragma, see the |
| DEC Ada Language Reference Manual, section 13.9a.3.1. |
| |
| @node Pragma Import_Function |
| @unnumberedsec Pragma Import_Function |
| @findex Import_Function |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Import_Function ( |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Result_Type =>] SUBTYPE_MARK] |
| [, [Mechanism =>] MECHANISM] |
| [, [Result_Mechanism =>] MECHANISM_NAME] |
| [, [First_Optional_Parameter =>] IDENTIFIER]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= |
| Value |
| | Reference |
| | Descriptor [([Class =>] CLASS_NAME)] |
| |
| CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca |
| @end smallexample |
| |
| @noindent |
| This pragma is used in conjunction with a pragma @code{Import} to |
| specify additional information for an imported function. The pragma |
| @code{Import} (or equivalent pragma @code{Interface}) must precede the |
| @code{Import_Function} pragma and both must appear in the same |
| declarative part as the function specification. |
| |
| The @var{Internal} argument must uniquely designate |
| the function to which the |
| pragma applies. If more than one function name exists of this name in |
| the declarative part you must use the @code{Parameter_Types} and |
| @var{Result_Type} parameters to achieve the required unique |
| designation. Subtype marks in these parameters must exactly match the |
| subtypes in the corresponding function specification, using positional |
| notation to match parameters with subtype marks. |
| The form with an @code{'Access} attribute can be used to match an |
| anonymous access parameter. |
| |
| You may optionally use the @var{Mechanism} and @var{Result_Mechanism} |
| parameters to specify passing mechanisms for the |
| parameters and result. If you specify a single mechanism name, it |
| applies to all parameters. Otherwise you may specify a mechanism on a |
| parameter by parameter basis using either positional or named |
| notation. If the mechanism is not specified, the default mechanism |
| is used. |
| |
| @cindex OpenVMS |
| @cindex Passing by descriptor |
| Passing by descriptor is supported only on the OpenVMS ports of GNAT@. |
| |
| @code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@. |
| It specifies that the designated parameter and all following parameters |
| are optional, meaning that they are not passed at the generated code |
| level (this is distinct from the notion of optional parameters in Ada |
| where the parameters are passed anyway with the designated optional |
| parameters). All optional parameters must be of mode @code{IN} and have |
| default parameter values that are either known at compile time |
| expressions, or uses of the @code{'Null_Parameter} attribute. |
| |
| @node Pragma Import_Object |
| @unnumberedsec Pragma Import_Object |
| @findex Import_Object |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Import_Object |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL], |
| [, [Size =>] EXTERNAL_SYMBOL]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| @end smallexample |
| |
| @noindent |
| This pragma designates an object as imported, and apart from the |
| extended rules for external symbols, is identical in effect to the use of |
| the normal @code{Import} pragma applied to an object. Unlike the |
| subprogram case, you need not use a separate @code{Import} pragma, |
| although you may do so (and probably should do so from a portability |
| point of view). @var{size} is syntax checked, but otherwise ignored by |
| GNAT@. |
| |
| @node Pragma Import_Procedure |
| @unnumberedsec Pragma Import_Procedure |
| @findex Import_Procedure |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Import_Procedure ( |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Mechanism =>] MECHANISM] |
| [, [First_Optional_Parameter =>] IDENTIFIER]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= |
| Value |
| | Reference |
| | Descriptor [([Class =>] CLASS_NAME)] |
| |
| CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca |
| @end smallexample |
| |
| @noindent |
| This pragma is identical to @code{Import_Function} except that it |
| applies to a procedure rather than a function and the parameters |
| @code{Result_Type} and @code{Result_Mechanism} are not permitted. |
| |
| @node Pragma Import_Valued_Procedure |
| @unnumberedsec Pragma Import_Valued_Procedure |
| @findex Import_Valued_Procedure |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Import_Valued_Procedure ( |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Parameter_Types =>] PARAMETER_TYPES] |
| [, [Mechanism =>] MECHANISM] |
| [, [First_Optional_Parameter =>] IDENTIFIER]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| |
| PARAMETER_TYPES ::= |
| null |
| | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} |
| |
| TYPE_DESIGNATOR ::= |
| subtype_NAME |
| | subtype_Name ' Access |
| |
| MECHANISM ::= |
| MECHANISM_NAME |
| | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) |
| |
| MECHANISM_ASSOCIATION ::= |
| [formal_parameter_NAME =>] MECHANISM_NAME |
| |
| MECHANISM_NAME ::= |
| Value |
| | Reference |
| | Descriptor [([Class =>] CLASS_NAME)] |
| |
| CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca |
| @end smallexample |
| |
| @noindent |
| This pragma is identical to @code{Import_Procedure} except that the |
| first parameter of @var{local_NAME}, which must be present, must be of |
| mode @code{OUT}, and externally the subprogram is treated as a function |
| with this parameter as the result of the function. The purpose of this |
| capability is to allow the use of @code{OUT} and @code{IN OUT} |
| parameters in interfacing to external functions (which are not permitted |
| in Ada functions). You may optionally use the @code{Mechanism} |
| parameters to specify passing mechanisms for the parameters. |
| If you specify a single mechanism name, it applies to all parameters. |
| Otherwise you may specify a mechanism on a parameter by parameter |
| basis using either positional or named notation. If the mechanism is not |
| specified, the default mechanism is used. |
| |
| Note that it is important to use this pragma in conjunction with a separate |
| pragma Import that specifies the desired convention, since otherwise the |
| default convention is Ada, which is almost certainly not what is required. |
| |
| @node Pragma Initialize_Scalars |
| @unnumberedsec Pragma Initialize_Scalars |
| @findex Initialize_Scalars |
| @cindex debugging with Initialize_Scalars |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Initialize_Scalars; |
| @end smallexample |
| |
| @noindent |
| This pragma is similar to @code{Normalize_Scalars} conceptually but has |
| two important differences. First, there is no requirement for the pragma |
| to be used uniformly in all units of a partition, in particular, it is fine |
| to use this just for some or all of the application units of a partition, |
| without needing to recompile the run-time library. |
| |
| In the case where some units are compiled with the pragma, and some without, |
| then a declaration of a variable where the type is defined in package |
| Standard or is locally declared will always be subject to initialization, |
| as will any declaration of a scalar variable. For composite variables, |
| whether the variable is initialized may also depend on whether the package |
| in which the type of the variable is declared is compiled with the pragma. |
| |
| The other important difference is that you can control the value used |
| for initializing scalar objects. At bind time, you can select several |
| options for initialization. You can |
| initialize with invalid values (similar to Normalize_Scalars, though for |
| Initialize_Scalars it is not always possible to determine the invalid |
| values in complex cases like signed component fields with non-standard |
| sizes). You can also initialize with high or |
| low values, or with a specified bit pattern. See the users guide for binder |
| options for specifying these cases. |
| |
| This means that you can compile a program, and then without having to |
| recompile the program, you can run it with different values being used |
| for initializing otherwise uninitialized values, to test if your program |
| behavior depends on the choice. Of course the behavior should not change, |
| and if it does, then most likely you have an erroneous reference to an |
| uninitialized value. |
| |
| It is even possible to change the value at execution time eliminating even |
| the need to rebind with a different switch using an environment variable. |
| See the GNAT users guide for details. |
| |
| Note that pragma @code{Initialize_Scalars} is particularly useful in |
| conjunction with the enhanced validity checking that is now provided |
| in GNAT, which checks for invalid values under more conditions. |
| Using this feature (see description of the @code{-gnatV} flag in the |
| users guide) in conjunction with pragma @code{Initialize_Scalars} |
| provides a powerful new tool to assist in the detection of problems |
| caused by uninitialized variables. |
| |
| Note: the use of @code{Initialize_Scalars} has a fairly extensive |
| effect on the generated code. This may cause your code to be |
| substantially larger. It may also cause an increase in the amount |
| of stack required, so it is probably a good idea to turn on stack |
| checking (see description of stack checking in the GNAT users guide) |
| when using this pragma. |
| |
| @node Pragma Inline_Always |
| @unnumberedsec Pragma Inline_Always |
| @findex Inline_Always |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Inline_Always (NAME [, NAME]); |
| @end smallexample |
| |
| @noindent |
| Similar to pragma @code{Inline} except that inlining is not subject to |
| the use of option @code{-gnatn} and the inlining happens regardless of |
| whether this option is used. |
| |
| @node Pragma Inline_Generic |
| @unnumberedsec Pragma Inline_Generic |
| @findex Inline_Generic |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Inline_Generic (generic_package_NAME); |
| @end smallexample |
| |
| @noindent |
| This is implemented for compatibility with DEC Ada 83 and is recognized, |
| but otherwise ignored, by GNAT@. All generic instantiations are inlined |
| by default when using GNAT@. |
| |
| @node Pragma Interface |
| @unnumberedsec Pragma Interface |
| @findex Interface |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Interface ( |
| [Convention =>] convention_identifier, |
| [Entity =>] local_NAME |
| [, [External_Name =>] static_string_expression], |
| [, [Link_Name =>] static_string_expression]); |
| @end smallexample |
| |
| @noindent |
| This pragma is identical in syntax and semantics to |
| the standard Ada 95 pragma @code{Import}. It is provided for compatibility |
| with Ada 83. The definition is upwards compatible both with pragma |
| @code{Interface} as defined in the Ada 83 Reference Manual, and also |
| with some extended implementations of this pragma in certain Ada 83 |
| implementations. |
| |
| @node Pragma Interface_Name |
| @unnumberedsec Pragma Interface_Name |
| @findex Interface_Name |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Interface_Name ( |
| [Entity =>] local_NAME |
| [, [External_Name =>] static_string_EXPRESSION] |
| [, [Link_Name =>] static_string_EXPRESSION]); |
| @end smallexample |
| |
| @noindent |
| This pragma provides an alternative way of specifying the interface name |
| for an interfaced subprogram, and is provided for compatibility with Ada |
| 83 compilers that use the pragma for this purpose. You must provide at |
| least one of @var{External_Name} or @var{Link_Name}. |
| |
| @node Pragma Interrupt_Handler |
| @unnumberedsec Pragma Interrupt_Handler |
| @findex Interrupt_Handler |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Interrupt_Handler (procedure_local_NAME); |
| @end smallexample |
| |
| @noindent |
| This program unit pragma is supported for parameterless protected procedures |
| as described in Annex C of the Ada Reference Manual. On the AAMP target |
| the pragma can also be specified for nonprotected parameterless procedures |
| that are declared at the library level (which includes procedures |
| declared at the top level of a library package). In the case of AAMP, |
| when this pragma is applied to a nonprotected procedure, the instruction |
| @code{IERET} is generated for returns from the procedure, enabling |
| maskable interrupts, in place of the normal return instruction. |
| |
| @node Pragma Interrupt_State |
| @unnumberedsec Pragma Interrupt_State |
| @findex Interrupt_State |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Interrupt_State (Name => value, State => SYSTEM | RUNTIME | USER); |
| @end smallexample |
| |
| @noindent |
| Normally certain interrupts are reserved to the implementation. Any attempt |
| to attach an interrupt causes Program_Error to be raised, as described in |
| RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in |
| many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is |
| reserved to the implementation, so that @kbd{Ctrl-C} can be used to |
| interrupt execution. Additionally, signals such as @code{SIGSEGV}, |
| @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific |
| Ada exceptions, or used to implement run-time functions such as the |
| @code{abort} statement and stack overflow checking. |
| |
| Pragma @code{Interrupt_State} provides a general mechanism for overriding |
| such uses of interrupts. It subsumes the functionality of pragma |
| @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not |
| available on OS/2, Windows or VMS. On all other platforms than VxWorks, |
| it applies to signals; on VxWorks, it applies to vectored hardware interrupts |
| and may be used to mark interrupts required by the board support package |
| as reserved. |
| |
| Interrupts can be in one of three states: |
| @itemize @bullet |
| @item System |
| |
| The interrupt is reserved (no Ada handler can be installed), and the |
| Ada run-time may not install a handler. As a result you are guaranteed |
| standard system default action if this interrupt is raised. |
| |
| @item Runtime |
| |
| The interrupt is reserved (no Ada handler can be installed). The run time |
| is allowed to install a handler for internal control purposes, but is |
| not required to do so. |
| |
| @item User |
| |
| The interrupt is unreserved. The user may install a handler to provide |
| some other action. |
| @end itemize |
| |
| @noindent |
| These states are the allowed values of the @code{State} parameter of the |
| pragma. The @code{Name} parameter is a value of the type |
| @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in |
| @code{Ada.Interrupts.Names}. |
| |
| This is a configuration pragma, and the binder will check that there |
| are no inconsistencies between different units in a partition in how a |
| given interrupt is specified. It may appear anywhere a pragma is legal. |
| |
| The effect is to move the interrupt to the specified state. |
| |
| By declaring interrupts to be SYSTEM, you guarantee the standard system |
| action, such as a core dump. |
| |
| By declaring interrupts to be USER, you guarantee that you can install |
| a handler. |
| |
| Note that certain signals on many operating systems cannot be caught and |
| handled by applications. In such cases, the pragma is ignored. See the |
| operating system documentation, or the value of the array @code{Reserved} |
| declared in the specification of package @code{System.OS_Interface}. |
| |
| Overriding the default state of signals used by the Ada runtime may interfere |
| with an application's runtime behavior in the cases of the synchronous signals, |
| and in the case of the signal used to implement the @code{abort} statement. |
| |
| @node Pragma Keep_Names |
| @unnumberedsec Pragma Keep_Names |
| @findex Keep_Names |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Keep_Names ([On =>] enumeration_first_subtype_local_NAME); |
| @end smallexample |
| |
| @noindent |
| The @var{local_NAME} argument |
| must refer to an enumeration first subtype |
| in the current declarative part. The effect is to retain the enumeration |
| literal names for use by @code{Image} and @code{Value} even if a global |
| @code{Discard_Names} pragma applies. This is useful when you want to |
| generally suppress enumeration literal names and for example you therefore |
| use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you |
| want to retain the names for specific enumeration types. |
| |
| @node Pragma License |
| @unnumberedsec Pragma License |
| @findex License |
| @cindex License checking |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma License (Unrestricted | GPL | Modified_GPL | Restricted); |
| @end smallexample |
| |
| @noindent |
| This pragma is provided to allow automated checking for appropriate license |
| conditions with respect to the standard and modified GPL@. A pragma |
| @code{License}, which is a configuration pragma that typically appears at |
| the start of a source file or in a separate @file{gnat.adc} file, specifies |
| the licensing conditions of a unit as follows: |
| |
| @itemize @bullet |
| @item Unrestricted |
| This is used for a unit that can be freely used with no license restrictions. |
| Examples of such units are public domain units, and units from the Ada |
| Reference Manual. |
| |
| @item GPL |
| This is used for a unit that is licensed under the unmodified GPL, and which |
| therefore cannot be @code{with}'ed by a restricted unit. |
| |
| @item Modified_GPL |
| This is used for a unit licensed under the GNAT modified GPL that includes |
| a special exception paragraph that specifically permits the inclusion of |
| the unit in programs without requiring the entire program to be released |
| under the GPL@. |
| |
| @item Restricted |
| This is used for a unit that is restricted in that it is not permitted to |
| depend on units that are licensed under the GPL@. Typical examples are |
| proprietary code that is to be released under more restrictive license |
| conditions. Note that restricted units are permitted to @code{with} units |
| which are licensed under the modified GPL (this is the whole point of the |
| modified GPL). |
| |
| @end itemize |
| |
| @noindent |
| Normally a unit with no @code{License} pragma is considered to have an |
| unknown license, and no checking is done. However, standard GNAT headers |
| are recognized, and license information is derived from them as follows. |
| |
| @itemize @bullet |
| |
| A GNAT license header starts with a line containing 78 hyphens. The following |
| comment text is searched for the appearance of any of the following strings. |
| |
| If the string ``GNU General Public License'' is found, then the unit is assumed |
| to have GPL license, unless the string ``As a special exception'' follows, in |
| which case the license is assumed to be modified GPL@. |
| |
| If one of the strings |
| ``This specification is adapted from the Ada Semantic Interface'' or |
| ``This specification is derived from the Ada Reference Manual'' is found |
| then the unit is assumed to be unrestricted. |
| @end itemize |
| |
| @noindent |
| These default actions means that a program with a restricted license pragma |
| will automatically get warnings if a GPL unit is inappropriately |
| @code{with}'ed. For example, the program: |
| |
| @smallexample @c ada |
| with Sem_Ch3; |
| with GNAT.Sockets; |
| procedure Secret_Stuff is |
| @dots{} |
| end Secret_Stuff |
| @end smallexample |
| |
| @noindent |
| if compiled with pragma @code{License} (@code{Restricted}) in a |
| @file{gnat.adc} file will generate the warning: |
| |
| @smallexample |
| 1. with Sem_Ch3; |
| | |
| >>> license of withed unit "Sem_Ch3" is incompatible |
| |
| 2. with GNAT.Sockets; |
| 3. procedure Secret_Stuff is |
| @end smallexample |
| |
| @noindent |
| Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT |
| compiler and is licensed under the |
| GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT |
| run time, and is therefore licensed under the modified GPL@. |
| |
| @node Pragma Link_With |
| @unnumberedsec Pragma Link_With |
| @findex Link_With |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); |
| @end smallexample |
| |
| @noindent |
| This pragma is provided for compatibility with certain Ada 83 compilers. |
| It has exactly the same effect as pragma @code{Linker_Options} except |
| that spaces occurring within one of the string expressions are treated |
| as separators. For example, in the following case: |
| |
| @smallexample @c ada |
| pragma Link_With ("-labc -ldef"); |
| @end smallexample |
| |
| @noindent |
| results in passing the strings @code{-labc} and @code{-ldef} as two |
| separate arguments to the linker. In addition pragma Link_With allows |
| multiple arguments, with the same effect as successive pragmas. |
| |
| @node Pragma Linker_Alias |
| @unnumberedsec Pragma Linker_Alias |
| @findex Linker_Alias |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Linker_Alias ( |
| [Entity =>] local_NAME |
| [Target =>] static_string_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| @var{local_NAME} must refer to an object that is declared at the library |
| level. This pragma establishes the given entity as a linker alias for the |
| given target. It is equivalent to @code{__attribute__((alias))} in GNU C |
| and causes @var{local_NAME} to be emitted as an alias for the symbol |
| @var{static_string_EXPRESSION} in the object file, that is to say no space |
| is reserved for @var{local_NAME} by the assembler and it will be resolved |
| to the same address as @var{static_string_EXPRESSION} by the linker. |
| |
| The actual linker name for the target must be used (e.g. the fully |
| encoded name with qualification in Ada, or the mangled name in C++), |
| or it must be declared using the C convention with @code{pragma Import} |
| or @code{pragma Export}. |
| |
| Not all target machines support this pragma. On some of them it is accepted |
| only if @code{pragma Weak_External} has been applied to @var{local_NAME}. |
| |
| @smallexample @c ada |
| -- Example of the use of pragma Linker_Alias |
| |
| package p is |
| i : Integer := 1; |
| pragma Export (C, i); |
| |
| new_name_for_i : Integer; |
| pragma Linker_Alias (new_name_for_i, "i"); |
| end p; |
| @end smallexample |
| |
| @node Pragma Linker_Constructor |
| @unnumberedsec Pragma Linker_Constructor |
| @findex Linker_Constructor |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Linker_Constructor (procedure_LOCAL_NAME); |
| @end smallexample |
| |
| @noindent |
| @var{procedure_local_NAME} must refer to a parameterless procedure that |
| is declared at the library level. A procedure to which this pragma is |
| applied will be treated as an initialization routine by the linker. |
| It is equivalent to @code{__attribute__((constructor))} in GNU C and |
| causes @var{procedure_LOCAL_NAME} to be invoked before the entry point |
| of the executable is called (or immediately after the shared library is |
| loaded if the procedure is linked in a shared library), in particular |
| before the Ada run-time environment is set up. |
| |
| Because of these specific contexts, the set of operations such a procedure |
| can perform is very limited and the type of objects it can manipulate is |
| essentially restricted to the elementary types. In particular, it must only |
| contain code to which pragma Restrictions (No_Elaboration_Code) applies. |
| |
| This pragma is used by GNAT to implement auto-initialization of shared Stand |
| Alone Libraries, which provides a related capability without the restrictions |
| listed above. Where possible, the use of Stand Alone Libraries is preferable |
| to the use of this pragma. |
| |
| @node Pragma Linker_Destructor |
| @unnumberedsec Pragma Linker_Destructor |
| @findex Linker_Destructor |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Linker_Destructor (procedure_LOCAL_NAME); |
| @end smallexample |
| |
| @noindent |
| @var{procedure_local_NAME} must refer to a parameterless procedure that |
| is declared at the library level. A procedure to which this pragma is |
| applied will be treated as a finalization routine by the linker. |
| It is equivalent to @code{__attribute__((destructor))} in GNU C and |
| causes @var{procedure_LOCAL_NAME} to be invoked after the entry point |
| of the executable has exited (or immediately before the shared library |
| is unloaded if the procedure is linked in a shared library), in particular |
| after the Ada run-time environment is shut down. |
| |
| See @code{pragma Linker_Constructor} for the set of restrictions that apply |
| because of these specific contexts. |
| |
| @node Pragma Linker_Section |
| @unnumberedsec Pragma Linker_Section |
| @findex Linker_Section |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Linker_Section ( |
| [Entity =>] local_NAME |
| [Section =>] static_string_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| @var{local_NAME} must refer to an object that is declared at the library |
| level. This pragma specifies the name of the linker section for the given |
| entity. It is equivalent to @code{__attribute__((section))} in GNU C and |
| causes @var{local_NAME} to be placed in the @var{static_string_EXPRESSION} |
| section of the executable (assuming the linker doesn't rename the section). |
| |
| The compiler normally places library-level objects in standard sections |
| depending on their type: procedures and functions generally go in the |
| @code{.text} section, initialized variables in the @code{.data} section |
| and uninitialized variables in the @code{.bss} section. |
| |
| Other, special sections may exist on given target machines to map special |
| hardware, for example I/O ports or flash memory. This pragma is a means to |
| defer the final layout of the executable to the linker, thus fully working |
| at the symbolic level with the compiler. |
| |
| Some file formats do not support arbitrary sections so not all target |
| machines support this pragma. The use of this pragma may cause a program |
| execution to be erroneous if it is used to place an entity into an |
| inappropriate section (e.g. a modified variable into the @code{.text} |
| section). See also @code{pragma Persistent_BSS}. |
| |
| @smallexample @c ada |
| -- Example of the use of pragma Linker_Section |
| |
| package IO_Card is |
| Port_A : Integer; |
| pragma Volatile (Port_A); |
| pragma Linker_Section (Port_A, ".bss.port_a"); |
| |
| Port_B : Integer; |
| pragma Volatile (Port_B); |
| pragma Linker_Section (Port_B, ".bss.port_b"); |
| end IO_Card; |
| @end smallexample |
| |
| @node Pragma Long_Float |
| @unnumberedsec Pragma Long_Float |
| @cindex OpenVMS |
| @findex Long_Float |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Long_Float (FLOAT_FORMAT); |
| |
| FLOAT_FORMAT ::= D_Float | G_Float |
| @end smallexample |
| |
| @noindent |
| This pragma is implemented only in the OpenVMS implementation of GNAT@. |
| It allows control over the internal representation chosen for the predefined |
| type @code{Long_Float} and for floating point type representations with |
| @code{digits} specified in the range 7 through 15. |
| For further details on this pragma, see the |
| @cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use |
| this pragma, the standard runtime libraries must be recompiled. See the |
| description of the @code{GNAT LIBRARY} command in the OpenVMS version |
| of the GNAT User's Guide for details on the use of this command. |
| |
| @node Pragma Machine_Attribute |
| @unnumberedsec Pragma Machine_Attribute |
| @findex Machine_Attribute |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Machine_Attribute ( |
| [Attribute_Name =>] string_EXPRESSION, |
| [Entity =>] local_NAME); |
| @end smallexample |
| |
| @noindent |
| Machine-dependent attributes can be specified for types and/or |
| declarations. This pragma is semantically equivalent to |
| @code{__attribute__((@var{string_expression}))} in GNU C, |
| where @code{@var{string_expression}} is |
| recognized by the target macro @code{TARGET_ATTRIBUTE_TABLE} which is |
| defined for each machine. See the GCC manual for further information. |
| It is not possible to specify attributes defined by other languages, |
| only attributes defined by the machine the code is intended to run on. |
| |
| @node Pragma Main_Storage |
| @unnumberedsec Pragma Main_Storage |
| @cindex OpenVMS |
| @findex Main_Storage |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Main_Storage |
| (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); |
| |
| MAIN_STORAGE_OPTION ::= |
| [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION |
| | [TOP_GUARD =>] static_SIMPLE_EXPRESSION |
| |
| @end smallexample |
| |
| @noindent |
| This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
| no effect in GNAT, other than being syntax checked. Note that the pragma |
| also has no effect in DEC Ada 83 for OpenVMS Alpha Systems. |
| |
| @node Pragma No_Return |
| @unnumberedsec Pragma No_Return |
| @findex No_Return |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma No_Return (procedure_local_NAME @{, procedure_local_NAME@}); |
| @end smallexample |
| |
| @noindent |
| Each @var{procedure_local_NAME} argument must refer to one or more procedure |
| declarations in the current declarative part. A procedure to which this |
| pragma is applied may not contain any explicit @code{return} statements. |
| In addition, if the procedure contains any implicit returns from falling |
| off the end of a statement sequence, then execution of that implicit |
| return will cause Program_Error to be raised. |
| |
| One use of this pragma is to identify procedures whose only purpose is to raise |
| an exception. Another use of this pragma is to suppress incorrect warnings |
| about missing returns in functions, where the last statement of a function |
| statement sequence is a call to such a procedure. |
| |
| Note that in Ada 2005 mode, this pragma is part of the language, and is |
| identical in effect to the pragma as implemented in Ada 95 mode. |
| |
| @node Pragma No_Strict_Aliasing |
| @unnumberedsec Pragma No_Strict_Aliasing |
| @findex No_Strict_Aliasing |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; |
| @end smallexample |
| |
| @noindent |
| @var{type_LOCAL_NAME} must refer to an access type |
| declaration in the current declarative part. The effect is to inhibit |
| strict aliasing optimization for the given type. The form with no |
| arguments is a configuration pragma which applies to all access types |
| declared in units to which the pragma applies. For a detailed |
| description of the strict aliasing optimization, and the situations |
| in which it must be suppressed, see section |
| ``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide. |
| |
| @node Pragma Normalize_Scalars |
| @unnumberedsec Pragma Normalize_Scalars |
| @findex Normalize_Scalars |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Normalize_Scalars; |
| @end smallexample |
| |
| @noindent |
| This is a language defined pragma which is fully implemented in GNAT@. The |
| effect is to cause all scalar objects that are not otherwise initialized |
| to be initialized. The initial values are implementation dependent and |
| are as follows: |
| |
| @table @code |
| @item Standard.Character |
| @noindent |
| Objects whose root type is Standard.Character are initialized to |
| Character'Last unless the subtype range excludes NUL (in which case |
| NUL is used). This choice will always generate an invalid value if |
| one exists. |
| |
| @item Standard.Wide_Character |
| @noindent |
| Objects whose root type is Standard.Wide_Character are initialized to |
| Wide_Character'Last unless the subtype range excludes NUL (in which case |
| NUL is used). This choice will always generate an invalid value if |
| one exists. |
| |
| @item Standard.Wide_Wide_Character |
| @noindent |
| Objects whose root type is Standard.Wide_Wide_Character are initialized to |
| the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in |
| which case NUL is used). This choice will always generate an invalid value if |
| one exists. |
| |
| @item Integer types |
| @noindent |
| Objects of an integer type are treated differently depending on whether |
| negative values are present in the subtype. If no negative values are |
| present, then all one bits is used as the initial value except in the |
| special case where zero is excluded from the subtype, in which case |
| all zero bits are used. This choice will always generate an invalid |
| value if one exists. |
| |
| For subtypes with negative values present, the largest negative number |
| is used, except in the unusual case where this largest negative number |
| is in the subtype, and the largest positive number is not, in which case |
| the largest positive value is used. This choice will always generate |
| an invalid value if one exists. |
| |
| @item Floating-Point Types |
| Objects of all floating-point types are initialized to all 1-bits. For |
| standard IEEE format, this corresponds to a NaN (not a number) which is |
| indeed an invalid value. |
| |
| @item Fixed-Point Types |
| Objects of all fixed-point types are treated as described above for integers, |
| with the rules applying to the underlying integer value used to represent |
| the fixed-point value. |
| |
| @item Modular types |
| Objects of a modular type are initialized to all one bits, except in |
| the special case where zero is excluded from the subtype, in which |
| case all zero bits are used. This choice will always generate an |
| invalid value if one exists. |
| |
| @item Enumeration types |
| Objects of an enumeration type are initialized to all one-bits, i.e.@: to |
| the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal |
| whose Pos value is zero, in which case a code of zero is used. This choice |
| will always generate an invalid value if one exists. |
| |
| @end table |
| |
| @node Pragma Obsolescent |
| @unnumberedsec Pragma Obsolescent |
| @findex Obsolescent |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Obsolescent [(static_string_EXPRESSION [,Ada_05])]; |
| @end smallexample |
| |
| @noindent |
| This pragma can occur immediately following a subprogram |
| declaration and indicates that the associated function or procedure |
| is considered obsolescent and should not be used. Typically this is |
| used when an API must be modified by eventually removing or modifying |
| existing subprograms. The pragma can be used at an intermediate stage |
| when the subprogram is still present, but will be removed later. |
| |
| The effect of this pragma is to output a warning message on |
| a call to a program thus marked that the |
| subprogram is obsolescent if the appropriate warning option in the |
| compiler is activated. If a parameter is present, then a second |
| warning message is given containing this text. |
| In addition, a call to such a program is considered a violation of |
| pragma Restrictions (No_Obsolescent_Features). |
| |
| This pragma can also be used as a program unit pragma for a package, |
| in which case it indicates that the entire package is considered |
| obsolescent. In this case a client @code{with}'ing such a package |
| violates the restriction, and the @code{with} statement is |
| flagged with warnings if the warning option is set. |
| |
| If the optional second parameter is present (which must be exactly |
| the identifier Ada_05, no other argument is allowed), then the |
| indication of obsolescence applies only when compiling in Ada 2005 |
| mode. This is primarily intended for dealing with the situations |
| in the predefined library where subprograms or packages |
| have become defined as obsolescent in Ada 2005 |
| (e.g. in Ada.Characters.Handling), but may be used anywhere. |
| |
| @node Pragma Passive |
| @unnumberedsec Pragma Passive |
| @findex Passive |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Passive ([Semaphore | No]); |
| @end smallexample |
| |
| @noindent |
| Syntax checked, but otherwise ignored by GNAT@. This is recognized for |
| compatibility with DEC Ada 83 implementations, where it is used within a |
| task definition to request that a task be made passive. If the argument |
| @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 |
| treats the pragma as an assertion that the containing task is passive |
| and that optimization of context switch with this task is permitted and |
| desired. If the argument @code{No} is present, the task must not be |
| optimized. GNAT does not attempt to optimize any tasks in this manner |
| (since protected objects are available in place of passive tasks). |
| |
| @node Pragma Persistent_BSS |
| @unnumberedsec Pragma Persistent_BSS |
| @findex Persistent_BSS |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Persistent_BSS [local_NAME] |
| @end smallexample |
| |
| @noindent |
| This pragma allows selected objects to be placed in the @code{.persistent_bss} |
| section. On some targets the linker and loader provide for special |
| treatment of this section, allowing a program to be reloaded without |
| affecting the contents of this data (hence the name persistent). |
| |
| There are two forms of usage. If an argument is given, it must be the |
| local name of a library level object, with no explicit initialization |
| and whose type is potentially persistent. If no argument is given, then |
| the pragma is a configuration pragma, and applies to all library level |
| objects with no explicit initialization of potentially persistent types. |
| |
| A potentially persistent type is a scalar type, or a non-tagged, |
| non-discriminated record, all of whose components have no explicit |
| initialization and are themselves of a potentially persistent type, |
| or an array, all of whose constraints are static, and whose component |
| type is potentially persistent. |
| |
| If this pragma is used on a target where this feature is not supported, |
| then the pragma will be ignored. See also @code{pragma Linker_Section}. |
| |
| @node Pragma Polling |
| @unnumberedsec Pragma Polling |
| @findex Polling |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Polling (ON | OFF); |
| @end smallexample |
| |
| @noindent |
| This pragma controls the generation of polling code. This is normally off. |
| If @code{pragma Polling (ON)} is used then periodic calls are generated to |
| the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the |
| runtime library, and can be found in file @file{a-excpol.adb}. |
| |
| Pragma @code{Polling} can appear as a configuration pragma (for example it |
| can be placed in the @file{gnat.adc} file) to enable polling globally, or it |
| can be used in the statement or declaration sequence to control polling |
| more locally. |
| |
| A call to the polling routine is generated at the start of every loop and |
| at the start of every subprogram call. This guarantees that the @code{Poll} |
| routine is called frequently, and places an upper bound (determined by |
| the complexity of the code) on the period between two @code{Poll} calls. |
| |
| The primary purpose of the polling interface is to enable asynchronous |
| aborts on targets that cannot otherwise support it (for example Windows |
| NT), but it may be used for any other purpose requiring periodic polling. |
| The standard version is null, and can be replaced by a user program. This |
| will require re-compilation of the @code{Ada.Exceptions} package that can |
| be found in files @file{a-except.ads} and @file{a-except.adb}. |
| |
| A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT |
| distribution) is used to enable the asynchronous abort capability on |
| targets that do not normally support the capability. The version of |
| @code{Poll} in this file makes a call to the appropriate runtime routine |
| to test for an abort condition. |
| |
| Note that polling can also be enabled by use of the @code{-gnatP} switch. See |
| the @cite{GNAT User's Guide} for details. |
| |
| @node Pragma Profile (Ravenscar) |
| @unnumberedsec Pragma Profile (Ravenscar) |
| @findex Ravenscar |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Profile (Ravenscar); |
| @end smallexample |
| |
| @noindent |
| A configuration pragma that establishes the following set of configuration |
| pragmas: |
| |
| @table @code |
| @item Task_Dispatching_Policy (FIFO_Within_Priorities) |
| [RM D.2.2] Tasks are dispatched following a preemptive |
| priority-ordered scheduling policy. |
| |
| @item Locking_Policy (Ceiling_Locking) |
| [RM D.3] While tasks and interrupts execute a protected action, they inherit |
| the ceiling priority of the corresponding protected object. |
| @c |
| @c @item Detect_Blocking |
| @c This pragma forces the detection of potentially blocking operations within a |
| @c protected operation, and to raise Program_Error if that happens. |
| @end table |
| @noindent |
| |
| plus the following set of restrictions: |
| |
| @table @code |
| @item Max_Entry_Queue_Length = 1 |
| Defines the maximum number of calls that are queued on a (protected) entry. |
| Note that this restrictions is checked at run time. Violation of this |
| restriction results in the raising of Program_Error exception at the point of |
| the call. For the Profile (Ravenscar) the value of Max_Entry_Queue_Length is |
| always 1 and hence no task can be queued on a protected entry. |
| |
| @item Max_Protected_Entries = 1 |
| [RM D.7] Specifies the maximum number of entries per protected type. The |
| bounds of every entry family of a protected unit shall be static, or shall be |
| defined by a discriminant of a subtype whose corresponding bound is static. |
| For the Profile (Ravenscar) the value of Max_Protected_Entries is always 1. |
| |
| @item Max_Task_Entries = 0 |
| [RM D.7] Specifies the maximum number of entries |
| per task. The bounds of every entry family |
| of a task unit shall be static, or shall be |
| defined by a discriminant of a subtype whose |
| corresponding bound is static. A value of zero |
| indicates that no rendezvous are possible. For |
| the Profile (Ravenscar), the value of Max_Task_Entries is always |
| 0 (zero). |
| |
| @item No_Abort_Statements |
| [RM D.7] There are no abort_statements, and there are |
| no calls to Task_Identification.Abort_Task. |
| |
| @item No_Asynchronous_Control |
| [RM D.7] There are no semantic dependences on the package |
| Asynchronous_Task_Control. |
| |
| @item No_Calendar |
| There are no semantic dependencies on the package Ada.Calendar. |
| |
| @item No_Dynamic_Attachment |
| There is no call to any of the operations defined in package Ada.Interrupts |
| (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, |
| Detach_Handler, and Reference). |
| |
| @item No_Dynamic_Priorities |
| [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. |
| |
| @item No_Implicit_Heap_Allocations |
| [RM D.7] No constructs are allowed to cause implicit heap allocation. |
| |
| @item No_Local_Protected_Objects |
| Protected objects and access types that designate |
| such objects shall be declared only at library level. |
| |
| @item No_Protected_Type_Allocators |
| There are no allocators for protected types or |
| types containing protected subcomponents. |
| |
| @item No_Relative_Delay |
| There are no delay_relative statements. |
| |
| @item No_Requeue_Statements |
| Requeue statements are not allowed. |
| |
| @item No_Select_Statements |
| There are no select_statements. |
| |
| @item No_Task_Allocators |
| [RM D.7] There are no allocators for task types |
| or types containing task subcomponents. |
| |
| @item No_Task_Attributes_Package |
| There are no semantic dependencies on the Ada.Task_Attributes package. |
| |
| @item No_Task_Hierarchy |
| [RM D.7] All (non-environment) tasks depend |
| directly on the environment task of the partition. |
| |
| @item No_Task_Termination |
| Tasks which terminate are erroneous. |
| |
| @item Simple_Barriers |
| Entry barrier condition expressions shall be either static |
| boolean expressions or boolean objects which are declared in |
| the protected type which contains the entry. |
| @end table |
| |
| @noindent |
| This set of configuration pragmas and restrictions correspond to the |
| definition of the ``Ravenscar Profile'' for limited tasking, devised and |
| published by the @cite{International Real-Time Ada Workshop}, 1997, |
| and whose most recent description is available at |
| @url{ftp://ftp.openravenscar.org/openravenscar/ravenscar00.pdf}. |
| |
| The original definition of the profile was revised at subsequent IRTAW |
| meetings. It has been included in the ISO |
| @cite{Guide for the Use of the Ada Programming Language in High |
| Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in |
| the next revision of the standard. The formal definition given by |
| the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and |
| AI-305) available at |
| @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00249.TXT} and |
| @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00305.TXT} |
| respectively. |
| |
| The above set is a superset of the restrictions provided by pragma |
| @code{Profile (Restricted)}, it includes six additional restrictions |
| (@code{Simple_Barriers}, @code{No_Select_Statements}, |
| @code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, |
| @code{No_Relative_Delay} and @code{No_Task_Termination}). This means |
| that pragma @code{Profile (Ravenscar)}, like the pragma |
| @code{Profile (Restricted)}, |
| automatically causes the use of a simplified, |
| more efficient version of the tasking run-time system. |
| |
| @node Pragma Profile (Restricted) |
| @unnumberedsec Pragma Profile (Restricted) |
| @findex Restricted Run Time |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Profile (Restricted); |
| @end smallexample |
| |
| @noindent |
| A configuration pragma that establishes the following set of restrictions: |
| |
| @itemize @bullet |
| @item No_Abort_Statements |
| @item No_Entry_Queue |
| @item No_Task_Hierarchy |
| @item No_Task_Allocators |
| @item No_Dynamic_Priorities |
| @item No_Terminate_Alternatives |
| @item No_Dynamic_Attachment |
| @item No_Protected_Type_Allocators |
| @item No_Local_Protected_Objects |
| @item No_Requeue_Statements |
| @item No_Task_Attributes_Package |
| @item Max_Asynchronous_Select_Nesting = 0 |
| @item Max_Task_Entries = 0 |
| @item Max_Protected_Entries = 1 |
| @item Max_Select_Alternatives = 0 |
| @end itemize |
| |
| @noindent |
| This set of restrictions causes the automatic selection of a simplified |
| version of the run time that provides improved performance for the |
| limited set of tasking functionality permitted by this set of restrictions. |
| |
| @node Pragma Psect_Object |
| @unnumberedsec Pragma Psect_Object |
| @findex Psect_Object |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Psect_Object ( |
| [Internal =>] local_NAME, |
| [, [External =>] EXTERNAL_SYMBOL] |
| [, [Size =>] EXTERNAL_SYMBOL]); |
| |
| EXTERNAL_SYMBOL ::= |
| IDENTIFIER |
| | static_string_EXPRESSION |
| @end smallexample |
| |
| @noindent |
| This pragma is identical in effect to pragma @code{Common_Object}. |
| |
| @node Pragma Pure_Function |
| @unnumberedsec Pragma Pure_Function |
| @findex Pure_Function |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Pure_Function ([Entity =>] function_local_NAME); |
| @end smallexample |
| |
| @noindent |
| This pragma appears in the same declarative part as a function |
| declaration (or a set of function declarations if more than one |
| overloaded declaration exists, in which case the pragma applies |
| to all entities). It specifies that the function @code{Entity} is |
| to be considered pure for the purposes of code generation. This means |
| that the compiler can assume that there are no side effects, and |
| in particular that two calls with identical arguments produce the |
| same result. It also means that the function can be used in an |
| address clause. |
| |
| Note that, quite deliberately, there are no static checks to try |
| to ensure that this promise is met, so @code{Pure_Function} can be used |
| with functions that are conceptually pure, even if they do modify |
| global variables. For example, a square root function that is |
| instrumented to count the number of times it is called is still |
| conceptually pure, and can still be optimized, even though it |
| modifies a global variable (the count). Memo functions are another |
| example (where a table of previous calls is kept and consulted to |
| avoid re-computation). |
| |
| @findex Pure |
| Note: Most functions in a @code{Pure} package are automatically pure, and |
| there is no need to use pragma @code{Pure_Function} for such functions. One |
| exception is any function that has at least one formal of type |
| @code{System.Address} or a type derived from it. Such functions are not |
| considered pure by default, since the compiler assumes that the |
| @code{Address} parameter may be functioning as a pointer and that the |
| referenced data may change even if the address value does not. |
| Similarly, imported functions are not considered to be pure by default, |
| since there is no way of checking that they are in fact pure. The use |
| of pragma @code{Pure_Function} for such a function will override these default |
| assumption, and cause the compiler to treat a designated subprogram as pure |
| in these cases. |
| |
| Note: If pragma @code{Pure_Function} is applied to a renamed function, it |
| applies to the underlying renamed function. This can be used to |
| disambiguate cases of overloading where some but not all functions |
| in a set of overloaded functions are to be designated as pure. |
| |
| If pragma @code{Pure_Function} is applied to a library level function, the |
| function is also considered pure from an optimization point of view, but the |
| unit is not a Pure unit in the categorization sense. So for example, a function |
| thus marked is free to @code{with} non-pure units. |
| |
| @node Pragma Restriction_Warnings |
| @unnumberedsec Pragma Restriction_Warnings |
| @findex Restriction_Warnings |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Restriction_Warnings |
| (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); |
| @end smallexample |
| |
| @noindent |
| This pragma allows a series of restriction identifiers to be |
| specified (the list of allowed identifiers is the same as for |
| pragma @code{Restrictions}). For each of these identifiers |
| the compiler checks for violations of the restriction, but |
| generates a warning message rather than an error message |
| if the restriction is violated. |
| |
| @node Pragma Source_File_Name |
| @unnumberedsec Pragma Source_File_Name |
| @findex Source_File_Name |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Source_File_Name ( |
| [Unit_Name =>] unit_NAME, |
| Spec_File_Name => STRING_LITERAL); |
| |
| pragma Source_File_Name ( |
| [Unit_Name =>] unit_NAME, |
| Body_File_Name => STRING_LITERAL); |
| @end smallexample |
| |
| @noindent |
| Use this to override the normal naming convention. It is a configuration |
| pragma, and so has the usual applicability of configuration pragmas |
| (i.e.@: it applies to either an entire partition, or to all units in a |
| compilation, or to a single unit, depending on how it is used. |
| @var{unit_name} is mapped to @var{file_name_literal}. The identifier for |
| the second argument is required, and indicates whether this is the file |
| name for the spec or for the body. |
| |
| Another form of the @code{Source_File_Name} pragma allows |
| the specification of patterns defining alternative file naming schemes |
| to apply to all files. |
| |
| @smallexample @c ada |
| pragma Source_File_Name |
| (Spec_File_Name => STRING_LITERAL |
| [,Casing => CASING_SPEC] |
| [,Dot_Replacement => STRING_LITERAL]); |
| |
| pragma Source_File_Name |
| (Body_File_Name => STRING_LITERAL |
| [,Casing => CASING_SPEC] |
| [,Dot_Replacement => STRING_LITERAL]); |
| |
| pragma Source_File_Name |
| (Subunit_File_Name => STRING_LITERAL |
| [,Casing => CASING_SPEC] |
| [,Dot_Replacement => STRING_LITERAL]); |
| |
| CASING_SPEC ::= Lowercase | Uppercase | Mixedcase |
| @end smallexample |
| |
| @noindent |
| The first argument is a pattern that contains a single asterisk indicating |
| the point at which the unit name is to be inserted in the pattern string |
| to form the file name. The second argument is optional. If present it |
| specifies the casing of the unit name in the resulting file name string. |
| The default is lower case. Finally the third argument allows for systematic |
| replacement of any dots in the unit name by the specified string literal. |
| |
| A pragma Source_File_Name cannot appear after a |
| @ref{Pragma Source_File_Name_Project}. |
| |
| For more details on the use of the @code{Source_File_Name} pragma, |
| see the sections ``Using Other File Names'' and |
| ``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}. |
| |
| @node Pragma Source_File_Name_Project |
| @unnumberedsec Pragma Source_File_Name_Project |
| @findex Source_File_Name_Project |
| @noindent |
| |
| This pragma has the same syntax and semantics as pragma Source_File_Name. |
| It is only allowed as a stand alone configuration pragma. |
| It cannot appear after a @ref{Pragma Source_File_Name}, and |
| most importantly, once pragma Source_File_Name_Project appears, |
| no further Source_File_Name pragmas are allowed. |
| |
| The intention is that Source_File_Name_Project pragmas are always |
| generated by the Project Manager in a manner consistent with the naming |
| specified in a project file, and when naming is controlled in this manner, |
| it is not permissible to attempt to modify this naming scheme using |
| Source_File_Name pragmas (which would not be known to the project manager). |
| |
| @node Pragma Source_Reference |
| @unnumberedsec Pragma Source_Reference |
| @findex Source_Reference |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); |
| @end smallexample |
| |
| @noindent |
| This pragma must appear as the first line of a source file. |
| @var{integer_literal} is the logical line number of the line following |
| the pragma line (for use in error messages and debugging |
| information). @var{string_literal} is a static string constant that |
| specifies the file name to be used in error messages and debugging |
| information. This is most notably used for the output of @code{gnatchop} |
| with the @code{-r} switch, to make sure that the original unchopped |
| source file is the one referred to. |
| |
| The second argument must be a string literal, it cannot be a static |
| string expression other than a string literal. This is because its value |
| is needed for error messages issued by all phases of the compiler. |
| |
| @node Pragma Stream_Convert |
| @unnumberedsec Pragma Stream_Convert |
| @findex Stream_Convert |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Stream_Convert ( |
| [Entity =>] type_local_NAME, |
| [Read =>] function_NAME, |
| [Write =>] function_NAME); |
| @end smallexample |
| |
| @noindent |
| This pragma provides an efficient way of providing stream functions for |
| types defined in packages. Not only is it simpler to use than declaring |
| the necessary functions with attribute representation clauses, but more |
| significantly, it allows the declaration to made in such a way that the |
| stream packages are not loaded unless they are needed. The use of |
| the Stream_Convert pragma adds no overhead at all, unless the stream |
| attributes are actually used on the designated type. |
| |
| The first argument specifies the type for which stream functions are |
| provided. The second parameter provides a function used to read values |
| of this type. It must name a function whose argument type may be any |
| subtype, and whose returned type must be the type given as the first |
| argument to the pragma. |
| |
| The meaning of the @var{Read} |
| parameter is that if a stream attribute directly |
| or indirectly specifies reading of the type given as the first parameter, |
| then a value of the type given as the argument to the Read function is |
| read from the stream, and then the Read function is used to convert this |
| to the required target type. |
| |
| Similarly the @var{Write} parameter specifies how to treat write attributes |
| that directly or indirectly apply to the type given as the first parameter. |
| It must have an input parameter of the type specified by the first parameter, |
| and the return type must be the same as the input type of the Read function. |
| The effect is to first call the Write function to convert to the given stream |
| type, and then write the result type to the stream. |
| |
| The Read and Write functions must not be overloaded subprograms. If necessary |
| renamings can be supplied to meet this requirement. |
| The usage of this attribute is best illustrated by a simple example, taken |
| from the GNAT implementation of package Ada.Strings.Unbounded: |
| |
| @smallexample @c ada |
| function To_Unbounded (S : String) |
| return Unbounded_String |
| renames To_Unbounded_String; |
| |
| pragma Stream_Convert |
| (Unbounded_String, To_Unbounded, To_String); |
| @end smallexample |
| |
| @noindent |
| The specifications of the referenced functions, as given in the Ada 95 |
| Reference Manual are: |
| |
| @smallexample @c ada |
| function To_Unbounded_String (Source : String) |
| return Unbounded_String; |
| |
| function To_String (Source : Unbounded_String) |
| return String; |
| @end smallexample |
| |
| @noindent |
| The effect is that if the value of an unbounded string is written to a |
| stream, then the representation of the item in the stream is in the same |
| format used for @code{Standard.String}, and this same representation is |
| expected when a value of this type is read from the stream. |
| |
| @node Pragma Style_Checks |
| @unnumberedsec Pragma Style_Checks |
| @findex Style_Checks |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Style_Checks (string_LITERAL | ALL_CHECKS | |
| On | Off [, local_NAME]); |
| @end smallexample |
| |
| @noindent |
| This pragma is used in conjunction with compiler switches to control the |
| built in style checking provided by GNAT@. The compiler switches, if set, |
| provide an initial setting for the switches, and this pragma may be used |
| to modify these settings, or the settings may be provided entirely by |
| the use of the pragma. This pragma can be used anywhere that a pragma |
| is legal, including use as a configuration pragma (including use in |
| the @file{gnat.adc} file). |
| |
| The form with a string literal specifies which style options are to be |
| activated. These are additive, so they apply in addition to any previously |
| set style check options. The codes for the options are the same as those |
| used in the @code{-gnaty} switch to @code{gcc} or @code{gnatmake}. |
| For example the following two methods can be used to enable |
| layout checking: |
| |
| @itemize @bullet |
| @item |
| @smallexample @c ada |
| pragma Style_Checks ("l"); |
| @end smallexample |
| |
| @item |
| @smallexample |
| gcc -c -gnatyl @dots{} |
| @end smallexample |
| @end itemize |
| |
| @noindent |
| The form ALL_CHECKS activates all standard checks (its use is equivalent |
| to the use of the @code{gnaty} switch with no options. See GNAT User's |
| Guide for details. |
| |
| The forms with @code{Off} and @code{On} |
| can be used to temporarily disable style checks |
| as shown in the following example: |
| |
| @smallexample @c ada |
| @iftex |
| @leftskip=0cm |
| @end iftex |
| pragma Style_Checks ("k"); -- requires keywords in lower case |
| pragma Style_Checks (Off); -- turn off style checks |
| NULL; -- this will not generate an error message |
| pragma Style_Checks (On); -- turn style checks back on |
| NULL; -- this will generate an error message |
| @end smallexample |
| |
| @noindent |
| Finally the two argument form is allowed only if the first argument is |
| @code{On} or @code{Off}. The effect is to turn of semantic style checks |
| for the specified entity, as shown in the following example: |
| |
| @smallexample @c ada |
| @iftex |
| @leftskip=0cm |
| @end iftex |
| pragma Style_Checks ("r"); -- require consistency of identifier casing |
| Arg : Integer; |
| Rf1 : Integer := ARG; -- incorrect, wrong case |
| pragma Style_Checks (Off, Arg); |
| Rf2 : Integer := ARG; -- OK, no error |
| @end smallexample |
| |
| @node Pragma Subtitle |
| @unnumberedsec Pragma Subtitle |
| @findex Subtitle |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Subtitle ([Subtitle =>] STRING_LITERAL); |
| @end smallexample |
| |
| @noindent |
| This pragma is recognized for compatibility with other Ada compilers |
| but is ignored by GNAT@. |
| |
| @node Pragma Suppress_All |
| @unnumberedsec Pragma Suppress_All |
| @findex Suppress_All |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Suppress_All; |
| @end smallexample |
| |
| @noindent |
| This pragma can only appear immediately following a compilation |
| unit. The effect is to apply @code{Suppress (All_Checks)} to the unit |
| which it follows. This pragma is implemented for compatibility with DEC |
| Ada 83 usage. The use of pragma @code{Suppress (All_Checks)} as a normal |
| configuration pragma is the preferred usage in GNAT@. |
| |
| @node Pragma Suppress_Exception_Locations |
| @unnumberedsec Pragma Suppress_Exception_Locations |
| @findex Suppress_Exception_Locations |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Suppress_Exception_Locations; |
| @end smallexample |
| |
| @noindent |
| In normal mode, a raise statement for an exception by default generates |
| an exception message giving the file name and line number for the location |
| of the raise. This is useful for debugging and logging purposes, but this |
| entails extra space for the strings for the messages. The configuration |
| pragma @code{Suppress_Exception_Locations} can be used to suppress the |
| generation of these strings, with the result that space is saved, but the |
| exception message for such raises is null. This configuration pragma may |
| appear in a global configuration pragma file, or in a specific unit as |
| usual. It is not required that this pragma be used consistently within |
| a partition, so it is fine to have some units within a partition compiled |
| with this pragma and others compiled in normal mode without it. |
| |
| @node Pragma Suppress_Initialization |
| @unnumberedsec Pragma Suppress_Initialization |
| @findex Suppress_Initialization |
| @cindex Suppressing initialization |
| @cindex Initialization, suppression of |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Suppress_Initialization ([Entity =>] type_Name); |
| @end smallexample |
| |
| @noindent |
| This pragma suppresses any implicit or explicit initialization |
| associated with the given type name for all variables of this type. |
| |
| @node Pragma Task_Info |
| @unnumberedsec Pragma Task_Info |
| @findex Task_Info |
| @noindent |
| Syntax |
| |
| @smallexample @c ada |
| pragma Task_Info (EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| This pragma appears within a task definition (like pragma |
| @code{Priority}) and applies to the task in which it appears. The |
| argument must be of type @code{System.Task_Info.Task_Info_Type}. |
| The @code{Task_Info} pragma provides system dependent control over |
| aspects of tasking implementation, for example, the ability to map |
| tasks to specific processors. For details on the facilities available |
| for the version of GNAT that you are using, see the documentation |
| in the specification of package System.Task_Info in the runtime |
| library. |
| |
| @node Pragma Task_Name |
| @unnumberedsec Pragma Task_Name |
| @findex Task_Name |
| @noindent |
| Syntax |
| |
| @smallexample @c ada |
| pragma Task_Name (string_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| This pragma appears within a task definition (like pragma |
| @code{Priority}) and applies to the task in which it appears. The |
| argument must be of type String, and provides a name to be used for |
| the task instance when the task is created. Note that this expression |
| is not required to be static, and in particular, it can contain |
| references to task discriminants. This facility can be used to |
| provide different names for different tasks as they are created, |
| as illustrated in the example below. |
| |
| The task name is recorded internally in the run-time structures |
| and is accessible to tools like the debugger. In addition the |
| routine @code{Ada.Task_Identification.Image} will return this |
| string, with a unique task address appended. |
| |
| @smallexample @c ada |
| -- Example of the use of pragma Task_Name |
| |
| with Ada.Task_Identification; |
| use Ada.Task_Identification; |
| with Text_IO; use Text_IO; |
| procedure t3 is |
| |
| type Astring is access String; |
| |
| task type Task_Typ (Name : access String) is |
| pragma Task_Name (Name.all); |
| end Task_Typ; |
| |
| task body Task_Typ is |
| Nam : constant String := Image (Current_Task); |
| begin |
| Put_Line ("-->" & Nam (1 .. 14) & "<--"); |
| end Task_Typ; |
| |
| type Ptr_Task is access Task_Typ; |
| Task_Var : Ptr_Task; |
| |
| begin |
| Task_Var := |
| new Task_Typ (new String'("This is task 1")); |
| Task_Var := |
| new Task_Typ (new String'("This is task 2")); |
| end; |
| @end smallexample |
| |
| @node Pragma Task_Storage |
| @unnumberedsec Pragma Task_Storage |
| @findex Task_Storage |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Task_Storage ( |
| [Task_Type =>] local_NAME, |
| [Top_Guard =>] static_integer_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| This pragma specifies the length of the guard area for tasks. The guard |
| area is an additional storage area allocated to a task. A value of zero |
| means that either no guard area is created or a minimal guard area is |
| created, depending on the target. This pragma can appear anywhere a |
| @code{Storage_Size} attribute definition clause is allowed for a task |
| type. |
| |
| @node Pragma Thread_Body |
| @unnumberedsec Pragma Thread_Body |
| @findex Thread_Body |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Thread_Body ( |
| [Entity =>] local_NAME, |
| [[Secondary_Stack_Size =>] static_integer_EXPRESSION)]; |
| @end smallexample |
| |
| @noindent |
| This pragma specifies that the subprogram whose name is given as the |
| @code{Entity} argument is a thread body, which will be activated |
| by being called via its Address from foreign code. The purpose is |
| to allow execution and registration of the foreign thread within the |
| Ada run-time system. |
| |
| See the library unit @code{System.Threads} for details on the expansion of |
| a thread body subprogram, including the calls made to subprograms |
| within System.Threads to register the task. This unit also lists the |
| targets and runtime systems for which this pragma is supported. |
| |
| A thread body subprogram may not be called directly from Ada code, and |
| it is not permitted to apply the Access (or Unrestricted_Access) attributes |
| to such a subprogram. The only legitimate way of calling such a subprogram |
| is to pass its Address to foreign code and then make the call from the |
| foreign code. |
| |
| A thread body subprogram may have any parameters, and it may be a function |
| returning a result. The convention of the thread body subprogram may be |
| set in the usual manner using @code{pragma Convention}. |
| |
| The secondary stack size parameter, if given, is used to set the size |
| of secondary stack for the thread. The secondary stack is allocated as |
| a local variable of the expanded thread body subprogram, and thus is |
| allocated out of the main thread stack size. If no secondary stack |
| size parameter is present, the default size (from the declaration in |
| @code{System.Secondary_Stack} is used. |
| |
| @node Pragma Time_Slice |
| @unnumberedsec Pragma Time_Slice |
| @findex Time_Slice |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Time_Slice (static_duration_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| For implementations of GNAT on operating systems where it is possible |
| to supply a time slice value, this pragma may be used for this purpose. |
| It is ignored if it is used in a system that does not allow this control, |
| or if it appears in other than the main program unit. |
| @cindex OpenVMS |
| Note that the effect of this pragma is identical to the effect of the |
| DEC Ada 83 pragma of the same name when operating under OpenVMS systems. |
| |
| @node Pragma Title |
| @unnumberedsec Pragma Title |
| @findex Title |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Title (TITLING_OPTION [, TITLING OPTION]); |
| |
| TITLING_OPTION ::= |
| [Title =>] STRING_LITERAL, |
| | [Subtitle =>] STRING_LITERAL |
| @end smallexample |
| |
| @noindent |
| Syntax checked but otherwise ignored by GNAT@. This is a listing control |
| pragma used in DEC Ada 83 implementations to provide a title and/or |
| subtitle for the program listing. The program listing generated by GNAT |
| does not have titles or subtitles. |
| |
| Unlike other pragmas, the full flexibility of named notation is allowed |
| for this pragma, i.e.@: the parameters may be given in any order if named |
| notation is used, and named and positional notation can be mixed |
| following the normal rules for procedure calls in Ada. |
| |
| @node Pragma Unchecked_Union |
| @unnumberedsec Pragma Unchecked_Union |
| @cindex Unions in C |
| @findex Unchecked_Union |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Unchecked_Union (first_subtype_local_NAME); |
| @end smallexample |
| |
| @noindent |
| This pragma is used to declare that the specified type should be represented |
| in a manner |
| equivalent to a C union type, and is intended only for use in |
| interfacing with C code that uses union types. In Ada terms, the named |
| type must obey the following rules: |
| |
| @itemize @bullet |
| @item |
| It is a non-tagged non-limited record type. |
| @item |
| It has a single discrete discriminant with a default value. |
| @item |
| The component list consists of a single variant part. |
| @item |
| Each variant has a component list with a single component. |
| @item |
| No nested variants are allowed. |
| @item |
| No component has an explicit default value. |
| @item |
| No component has a non-static constraint. |
| @end itemize |
| |
| @noindent |
| In addition, given a type that meets the above requirements, the |
| following restrictions apply to its use throughout the program: |
| |
| @itemize @bullet |
| @item |
| The discriminant name can be mentioned only in an aggregate. |
| @item |
| No subtypes may be created of this type. |
| @item |
| The type may not be constrained by giving a discriminant value. |
| @item |
| The type cannot be passed as the actual for a generic formal with a |
| discriminant. |
| @end itemize |
| |
| @noindent |
| Equality and inequality operations on @code{unchecked_unions} are not |
| available, since there is no discriminant to compare and the compiler |
| does not even know how many bits to compare. It is implementation |
| dependent whether this is detected at compile time as an illegality or |
| whether it is undetected and considered to be an erroneous construct. In |
| GNAT, a direct comparison is illegal, but GNAT does not attempt to catch |
| the composite case (where two composites are compared that contain an |
| unchecked union component), so such comparisons are simply considered |
| erroneous. |
| |
| The layout of the resulting type corresponds exactly to a C union, where |
| each branch of the union corresponds to a single variant in the Ada |
| record. The semantics of the Ada program is not changed in any way by |
| the pragma, i.e.@: provided the above restrictions are followed, and no |
| erroneous incorrect references to fields or erroneous comparisons occur, |
| the semantics is exactly as described by the Ada reference manual. |
| Pragma @code{Suppress (Discriminant_Check)} applies implicitly to the |
| type and the default convention is C. |
| |
| @node Pragma Unimplemented_Unit |
| @unnumberedsec Pragma Unimplemented_Unit |
| @findex Unimplemented_Unit |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Unimplemented_Unit; |
| @end smallexample |
| |
| @noindent |
| If this pragma occurs in a unit that is processed by the compiler, GNAT |
| aborts with the message @samp{@var{xxx} not implemented}, where |
| @var{xxx} is the name of the current compilation unit. This pragma is |
| intended to allow the compiler to handle unimplemented library units in |
| a clean manner. |
| |
| The abort only happens if code is being generated. Thus you can use |
| specs of unimplemented packages in syntax or semantic checking mode. |
| |
| @node Pragma Universal_Data |
| @unnumberedsec Pragma Universal_Data |
| @findex Universal_Data |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Universal_Data [(library_unit_Name)]; |
| @end smallexample |
| |
| @noindent |
| This pragma is supported only for the AAMP target and is ignored for |
| other targets. The pragma specifies that all library-level objects |
| (Counter 0 data) associated with the library unit are to be accessed |
| and updated using universal addressing (24-bit addresses for AAMP5) |
| rather than the default of 16-bit Data Environment (DENV) addressing. |
| Use of this pragma will generally result in less efficient code for |
| references to global data associated with the library unit, but |
| allows such data to be located anywhere in memory. This pragma is |
| a library unit pragma, but can also be used as a configuration pragma |
| (including use in the @file{gnat.adc} file). The functionality |
| of this pragma is also available by applying the -univ switch on the |
| compilations of units where universal addressing of the data is desired. |
| |
| @node Pragma Unreferenced |
| @unnumberedsec Pragma Unreferenced |
| @findex Unreferenced |
| @cindex Warnings, unreferenced |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Unreferenced (local_NAME @{, local_NAME@}); |
| @end smallexample |
| |
| @noindent |
| This pragma signals that the entities whose names are listed are |
| deliberately not referenced in the current source unit. This |
| suppresses warnings about the |
| entities being unreferenced, and in addition a warning will be |
| generated if one of these entities is in fact referenced in the |
| same unit as the pragma (or in the corresponding body, or one |
| of its subunits). |
| |
| This is particularly useful for clearly signaling that a particular |
| parameter is not referenced in some particular subprogram implementation |
| and that this is deliberate. It can also be useful in the case of |
| objects declared only for their initialization or finalization side |
| effects. |
| |
| If @code{local_NAME} identifies more than one matching homonym in the |
| current scope, then the entity most recently declared is the one to which |
| the pragma applies. Note that in the case of accept formals, the pragma |
| Unreferenced may appear immediately after the keyword @code{do} which |
| allows the indication of whether or not accept formals are referenced |
| or not to be given individually for each accept statement. |
| |
| The left hand side of an assignment does not count as a reference for the |
| purpose of this pragma. Thus it is fine to assign to an entity for which |
| pragma Unreferenced is given. |
| |
| Note that if a warning is desired for all calls to a given subprogram, |
| regardless of whether they occur in the same unit as the subprogram |
| declaration, then this pragma should not be used (calls from another |
| unit would not be flagged); pragma Obsolescent can be used instead |
| for this purpose, see @xref{Pragma Obsolescent}. |
| |
| @node Pragma Unreserve_All_Interrupts |
| @unnumberedsec Pragma Unreserve_All_Interrupts |
| @findex Unreserve_All_Interrupts |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Unreserve_All_Interrupts; |
| @end smallexample |
| |
| @noindent |
| Normally certain interrupts are reserved to the implementation. Any attempt |
| to attach an interrupt causes Program_Error to be raised, as described in |
| RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in |
| many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is |
| reserved to the implementation, so that @kbd{Ctrl-C} can be used to |
| interrupt execution. |
| |
| If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in |
| a program, then all such interrupts are unreserved. This allows the |
| program to handle these interrupts, but disables their standard |
| functions. For example, if this pragma is used, then pressing |
| @kbd{Ctrl-C} will not automatically interrupt execution. However, |
| a program can then handle the @code{SIGINT} interrupt as it chooses. |
| |
| For a full list of the interrupts handled in a specific implementation, |
| see the source code for the specification of @code{Ada.Interrupts.Names} in |
| file @file{a-intnam.ads}. This is a target dependent file that contains the |
| list of interrupts recognized for a given target. The documentation in |
| this file also specifies what interrupts are affected by the use of |
| the @code{Unreserve_All_Interrupts} pragma. |
| |
| For a more general facility for controlling what interrupts can be |
| handled, see pragma @code{Interrupt_State}, which subsumes the functionality |
| of the @code{Unreserve_All_Interrupts} pragma. |
| |
| @node Pragma Unsuppress |
| @unnumberedsec Pragma Unsuppress |
| @findex Unsuppress |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); |
| @end smallexample |
| |
| @noindent |
| This pragma undoes the effect of a previous pragma @code{Suppress}. If |
| there is no corresponding pragma @code{Suppress} in effect, it has no |
| effect. The range of the effect is the same as for pragma |
| @code{Suppress}. The meaning of the arguments is identical to that used |
| in pragma @code{Suppress}. |
| |
| One important application is to ensure that checks are on in cases where |
| code depends on the checks for its correct functioning, so that the code |
| will compile correctly even if the compiler switches are set to suppress |
| checks. |
| |
| @node Pragma Use_VADS_Size |
| @unnumberedsec Pragma Use_VADS_Size |
| @cindex @code{Size}, VADS compatibility |
| @findex Use_VADS_Size |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Use_VADS_Size; |
| @end smallexample |
| |
| @noindent |
| This is a configuration pragma. In a unit to which it applies, any use |
| of the 'Size attribute is automatically interpreted as a use of the |
| 'VADS_Size attribute. Note that this may result in incorrect semantic |
| processing of valid Ada 95 programs. This is intended to aid in the |
| handling of legacy code which depends on the interpretation of Size |
| as implemented in the VADS compiler. See description of the VADS_Size |
| attribute for further details. |
| |
| @node Pragma Validity_Checks |
| @unnumberedsec Pragma Validity_Checks |
| @findex Validity_Checks |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); |
| @end smallexample |
| |
| @noindent |
| This pragma is used in conjunction with compiler switches to control the |
| built-in validity checking provided by GNAT@. The compiler switches, if set |
| provide an initial setting for the switches, and this pragma may be used |
| to modify these settings, or the settings may be provided entirely by |
| the use of the pragma. This pragma can be used anywhere that a pragma |
| is legal, including use as a configuration pragma (including use in |
| the @file{gnat.adc} file). |
| |
| The form with a string literal specifies which validity options are to be |
| activated. The validity checks are first set to include only the default |
| reference manual settings, and then a string of letters in the string |
| specifies the exact set of options required. The form of this string |
| is exactly as described for the @code{-gnatVx} compiler switch (see the |
| GNAT users guide for details). For example the following two methods |
| can be used to enable validity checking for mode @code{in} and |
| @code{in out} subprogram parameters: |
| |
| @itemize @bullet |
| @item |
| @smallexample @c ada |
| pragma Validity_Checks ("im"); |
| @end smallexample |
| |
| @item |
| @smallexample |
| gcc -c -gnatVim @dots{} |
| @end smallexample |
| @end itemize |
| |
| @noindent |
| The form ALL_CHECKS activates all standard checks (its use is equivalent |
| to the use of the @code{gnatva} switch. |
| |
| The forms with @code{Off} and @code{On} |
| can be used to temporarily disable validity checks |
| as shown in the following example: |
| |
| @smallexample @c ada |
| @iftex |
| @leftskip=0cm |
| @end iftex |
| pragma Validity_Checks ("c"); -- validity checks for copies |
| pragma Validity_Checks (Off); -- turn off validity checks |
| A := B; -- B will not be validity checked |
| pragma Validity_Checks (On); -- turn validity checks back on |
| A := C; -- C will be validity checked |
| @end smallexample |
| |
| @node Pragma Volatile |
| @unnumberedsec Pragma Volatile |
| @findex Volatile |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Volatile (local_NAME); |
| @end smallexample |
| |
| @noindent |
| This pragma is defined by the Ada 95 Reference Manual, and the GNAT |
| implementation is fully conformant with this definition. The reason it |
| is mentioned in this section is that a pragma of the same name was supplied |
| in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation |
| of pragma Volatile is upwards compatible with the implementation in |
| Dec Ada 83. |
| |
| @node Pragma Warnings |
| @unnumberedsec Pragma Warnings |
| @findex Warnings |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Warnings (On | Off [, local_NAME]); |
| pragma Warnings (static_string_EXPRESSION); |
| @end smallexample |
| |
| @noindent |
| Normally warnings are enabled, with the output being controlled by |
| the command line switch. Warnings (@code{Off}) turns off generation of |
| warnings until a Warnings (@code{On}) is encountered or the end of the |
| current unit. If generation of warnings is turned off using this |
| pragma, then no warning messages are output, regardless of the |
| setting of the command line switches. |
| |
| The form with a single argument is a configuration pragma. |
| |
| If the @var{local_NAME} parameter is present, warnings are suppressed for |
| the specified entity. This suppression is effective from the point where |
| it occurs till the end of the extended scope of the variable (similar to |
| the scope of @code{Suppress}). |
| |
| The form with a static_string_EXPRESSION argument provides more precise |
| control over which warnings are active. The string is a list of letters |
| specifying which warnings are to be activated and which deactivated. The |
| code for these letters is the same as the string used in the command |
| line switch controlling warnings. The following is a brief summary. For |
| full details see the GNAT Users Guide: |
| |
| @smallexample |
| a turn on all optional warnings (except d,h,l) |
| A turn off all optional warnings |
| b turn on warnings for bad fixed value (not multiple of small) |
| B turn off warnings for bad fixed value (not multiple of small) |
| c turn on warnings for constant conditional |
| C turn off warnings for constant conditional |
| d turn on warnings for implicit dereference |
| D turn off warnings for implicit dereference |
| e treat all warnings as errors |
| f turn on warnings for unreferenced formal |
| F turn off warnings for unreferenced formal |
| g turn on warnings for unrecognized pragma |
| G turn off warnings for unrecognized pragma |
| h turn on warnings for hiding variable |
| H turn off warnings for hiding variable |
| i turn on warnings for implementation unit |
| I turn off warnings for implementation unit |
| j turn on warnings for obsolescent (annex J) feature |
| J turn off warnings for obsolescent (annex J) feature |
| k turn on warnings on constant variable |
| K turn off warnings on constant variable |
| l turn on warnings for missing elaboration pragma |
| L turn off warnings for missing elaboration pragma |
| m turn on warnings for variable assigned but not read |
| M turn off warnings for variable assigned but not read |
| n normal warning mode (cancels s/e) |
| o turn on warnings for address clause overlay |
| O turn off warnings for address clause overlay |
| p turn on warnings for ineffective pragma Inline |
| P turn off warnings for ineffective pragma Inline |
| r turn on warnings for redundant construct |
| R turn off warnings for redundant construct |
| s suppress all warnings |
| u turn on warnings for unused entity |
| U turn off warnings for unused entity |
| v turn on warnings for unassigned variable |
| V turn off warnings for unassigned variable |
| x turn on warnings for export/import |
| X turn off warnings for export/import |
| y turn on warnings for Ada 2005 incompatibility |
| Y turn off warnings for Ada 2005 incompatibility |
| z turn on size/align warnings for unchecked conversion |
| Z turn off size/align warnings for unchecked conversion |
| @end smallexample |
| |
| @noindent |
| The specified warnings will be in effect until the end of the program |
| or another pragma Warnings is encountered. The effect of the pragma is |
| cumulative. Initially the set of warnings is the standard default set |
| as possibly modified by compiler switches. Then each pragma Warning |
| modifies this set of warnings as specified. |
| |
| @node Pragma Weak_External |
| @unnumberedsec Pragma Weak_External |
| @findex Weak_External |
| @noindent |
| Syntax: |
| |
| @smallexample @c ada |
| pragma Weak_External ([Entity =>] local_NAME); |
| @end smallexample |
| |
| @noindent |
| @var{local_NAME} must refer to an object that is declared at the library |
| level. This pragma specifies that the given entity should be marked as a |
| weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} |
| in GNU C and causes @var{local_NAME} to be emitted as a weak symbol instead |
| of a regular symbol, that is to say a symbol that does not have to be |
| resolved by the linker if used in conjunction with a pragma Import. |
| |
| When a weak symbol is not resolved by the linker, its address is set to |
| zero. This is useful in writing interfaces to external modules that may |
| or may not be linked in the final executable, for example depending on |
| configuration settings. |
| |
| If a program references at run time an entity to which this pragma has been |
| applied, and the corresponding symbol was not resolved at link time, then |
| the execution of the program is erroneous. It is not erroneous to take the |
| Address of such an entity, for example to guard potential references, |
| as shown in the example below. |
| |
| Some file formats do not support weak symbols so not all target machines |
| support this pragma. |
| |
| @smallexample @c ada |
| -- Example of the use of pragma Weak_External |
| |
| package External_Module is |
| key : Integer; |
| pragma Import (C, key); |
| pragma Weak_External (key); |
| function Present return boolean; |
| end External_Module; |
| |
| with System; use System; |
| package body External_Module is |
| function Present return boolean is |
| begin |
| return key'Address /= System.Null_Address; |
| end Present; |
| end External_Module; |
| @end smallexample |
| |
| @node Implementation Defined Attributes |
| @chapter Implementation Defined Attributes |
| Ada 95 defines (throughout the Ada 95 reference manual, |
| summarized in annex K), |
| a set of attributes that provide useful additional functionality in all |
| areas of the language. These language defined attributes are implemented |
| in GNAT and work as described in the Ada 95 Reference Manual. |
| |
| In addition, Ada 95 allows implementations to define additional |
| attributes whose meaning is defined by the implementation. GNAT provides |
| a number of these implementation-dependent attributes which can be used |
| to extend and enhance the functionality of the compiler. This section of |
| the GNAT reference manual describes these additional attributes. |
| |
| Note that any program using these attributes may not be portable to |
| other compilers (although GNAT implements this set of attributes on all |
| platforms). Therefore if portability to other compilers is an important |
| consideration, you should minimize the use of these attributes. |
| |
| @menu |
| * Abort_Signal:: |
| * Address_Size:: |
| * Asm_Input:: |
| * Asm_Output:: |
| * AST_Entry:: |
| * Bit:: |
| * Bit_Position:: |
| * Code_Address:: |
| * Default_Bit_Order:: |
| * Elaborated:: |
| * Elab_Body:: |
| * Elab_Spec:: |
| * Emax:: |
| * Enum_Rep:: |
| * Epsilon:: |
| * Fixed_Value:: |
| * Has_Access_Values:: |
| * Has_Discriminants:: |
| * Img:: |
| * Integer_Value:: |
| * Large:: |
| * Machine_Size:: |
| * Mantissa:: |
| * Max_Interrupt_Priority:: |
| * Max_Priority:: |
| * Maximum_Alignment:: |
| * Mechanism_Code:: |
| * Null_Parameter:: |
| * Object_Size:: |
| * Passed_By_Reference:: |
| * Range_Length:: |
| * Safe_Emax:: |
| * Safe_Large:: |
| * Small:: |
| * Storage_Unit:: |
| * Target_Name:: |
| * Tick:: |
| * To_Address:: |
| * Type_Class:: |
| * UET_Address:: |
| * Unconstrained_Array:: |
| * Universal_Literal_String:: |
| * Unrestricted_Access:: |
| * VADS_Size:: |
| * Value_Size:: |
| * Wchar_T_Size:: |
| * Word_Size:: |
| @end menu |
| |
| @node Abort_Signal |
| @unnumberedsec Abort_Signal |
| @findex Abort_Signal |
| @noindent |
| @code{Standard'Abort_Signal} (@code{Standard} is the only allowed |
| prefix) provides the entity for the special exception used to signal |
| task abort or asynchronous transfer of control. Normally this attribute |
| should only be used in the tasking runtime (it is highly peculiar, and |
| completely outside the normal semantics of Ada, for a user program to |
| intercept the abort exception). |
| |
| @node Address_Size |
| @unnumberedsec Address_Size |
| @cindex Size of @code{Address} |
| @findex Address_Size |
| @noindent |
| @code{Standard'Address_Size} (@code{Standard} is the only allowed |
| prefix) is a static constant giving the number of bits in an |
| @code{Address}. It is the same value as System.Address'Size, |
| but has the advantage of being static, while a direct |
| reference to System.Address'Size is non-static because Address |
| is a private type. |
| |
| @node Asm_Input |
| @unnumberedsec Asm_Input |
| @findex Asm_Input |
| @noindent |
| The @code{Asm_Input} attribute denotes a function that takes two |
| parameters. The first is a string, the second is an expression of the |
| type designated by the prefix. The first (string) argument is required |
| to be a static expression, and is the constraint for the parameter, |
| (e.g.@: what kind of register is required). The second argument is the |
| value to be used as the input argument. The possible values for the |
| constant are the same as those used in the RTL, and are dependent on |
| the configuration file used to built the GCC back end. |
| @ref{Machine Code Insertions} |
| |
| @node Asm_Output |
| @unnumberedsec Asm_Output |
| @findex Asm_Output |
| @noindent |
| The @code{Asm_Output} attribute denotes a function that takes two |
| parameters. The first is a string, the second is the name of a variable |
| of the type designated by the attribute prefix. The first (string) |
| argument is required to be a static expression and designates the |
| constraint for the parameter (e.g.@: what kind of register is |
| required). The second argument is the variable to be updated with the |
| result. The possible values for constraint are the same as those used in |
| the RTL, and are dependent on the configuration file used to build the |
| GCC back end. If there are no output operands, then this argument may |
| either be omitted, or explicitly given as @code{No_Output_Operands}. |
| @ref{Machine Code Insertions} |
| |
| @node AST_Entry |
| @unnumberedsec AST_Entry |
| @cindex OpenVMS |
| @findex AST_Entry |
| @noindent |
| This attribute is implemented only in OpenVMS versions of GNAT@. Applied to |
| the name of an entry, it yields a value of the predefined type AST_Handler |
| (declared in the predefined package System, as extended by the use of |
| pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to |
| be called when an AST occurs. For further details, refer to the @cite{DEC Ada |
| Language Reference Manual}, section 9.12a. |
| |
| @node Bit |
| @unnumberedsec Bit |
| @findex Bit |
| @code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit |
| offset within the storage unit (byte) that contains the first bit of |
| storage allocated for the object. The value of this attribute is of the |
| type @code{Universal_Integer}, and is always a non-negative number not |
| exceeding the value of @code{System.Storage_Unit}. |
| |
| For an object that is a variable or a constant allocated in a register, |
| the value is zero. (The use of this attribute does not force the |
| allocation of a variable to memory). |
| |
| For an object that is a formal parameter, this attribute applies |
| to either the matching actual parameter or to a copy of the |
| matching actual parameter. |
| |
| For an access object the value is zero. Note that |
| @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the |
| designated object. Similarly for a record component |
| @code{@var{X}.@var{C}'Bit} is subject to a discriminant check and |
| @code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit} |
| are subject to index checks. |
| |
| This attribute is designed to be compatible with the DEC Ada 83 definition |
| and implementation of the @code{Bit} attribute. |
| |
| @node Bit_Position |
| @unnumberedsec Bit_Position |
| @findex Bit_Position |
| @noindent |
| @code{@var{R.C}'Bit}, where @var{R} is a record object and C is one |
| of the fields of the record type, yields the bit |
| offset within the record contains the first bit of |
| storage allocated for the object. The value of this attribute is of the |
| type @code{Universal_Integer}. The value depends only on the field |
| @var{C} and is independent of the alignment of |
| the containing record @var{R}. |
| |
| @node Code_Address |
| @unnumberedsec Code_Address |
| @findex Code_Address |
| @cindex Subprogram address |
| @cindex Address of subprogram code |
| @noindent |
| The @code{'Address} |
| attribute may be applied to subprograms in Ada 95, but the |
| intended effect from the Ada 95 reference manual seems to be to provide |
| an address value which can be used to call the subprogram by means of |
| an address clause as in the following example: |
| |
| @smallexample @c ada |
| procedure K is @dots{} |
| |
| procedure L; |
| for L'Address use K'Address; |
| pragma Import (Ada, L); |
| @end smallexample |
| |
| @noindent |
| A call to @code{L} is then expected to result in a call to @code{K}@. |
| In Ada 83, where there were no access-to-subprogram values, this was |
| a common work around for getting the effect of an indirect call. |
| GNAT implements the above use of @code{Address} and the technique |
| illustrated by the example code works correctly. |
| |
| However, for some purposes, it is useful to have the address of the start |
| of the generated code for the subprogram. On some architectures, this is |
| not necessarily the same as the @code{Address} value described above. |
| For example, the @code{Address} value may reference a subprogram |
| descriptor rather than the subprogram itself. |
| |
| The @code{'Code_Address} attribute, which can only be applied to |
| subprogram entities, always returns the address of the start of the |
| generated code of the specified subprogram, which may or may not be |
| the same value as is returned by the corresponding @code{'Address} |
| attribute. |
| |
| @node Default_Bit_Order |
| @unnumberedsec Default_Bit_Order |
| @cindex Big endian |
| @cindex Little endian |
| @findex Default_Bit_Order |
| @noindent |
| @code{Standard'Default_Bit_Order} (@code{Standard} is the only |
| permissible prefix), provides the value @code{System.Default_Bit_Order} |
| as a @code{Pos} value (0 for @code{High_Order_First}, 1 for |
| @code{Low_Order_First}). This is used to construct the definition of |
| @code{Default_Bit_Order} in package @code{System}. |
| |
| @node Elaborated |
| @unnumberedsec Elaborated |
| @findex Elaborated |
| @noindent |
| The prefix of the @code{'Elaborated} attribute must be a unit name. The |
| value is a Boolean which indicates whether or not the given unit has been |
| elaborated. This attribute is primarily intended for internal use by the |
| generated code for dynamic elaboration checking, but it can also be used |
| in user programs. The value will always be True once elaboration of all |
| units has been completed. An exception is for units which need no |
| elaboration, the value is always False for such units. |
| |
| @node Elab_Body |
| @unnumberedsec Elab_Body |
| @findex Elab_Body |
| @noindent |
| This attribute can only be applied to a program unit name. It returns |
| the entity for the corresponding elaboration procedure for elaborating |
| the body of the referenced unit. This is used in the main generated |
| elaboration procedure by the binder and is not normally used in any |
| other context. However, there may be specialized situations in which it |
| is useful to be able to call this elaboration procedure from Ada code, |
| e.g.@: if it is necessary to do selective re-elaboration to fix some |
| error. |
| |
| @node Elab_Spec |
| @unnumberedsec Elab_Spec |
| @findex Elab_Spec |
| @noindent |
| This attribute can only be applied to a program unit name. It returns |
| the entity for the corresponding elaboration procedure for elaborating |
| the specification of the referenced unit. This is used in the main |
| generated elaboration procedure by the binder and is not normally used |
| in any other context. However, there may be specialized situations in |
| which it is useful to be able to call this elaboration procedure from |
| Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix |
| some error. |
| |
| @node Emax |
| @unnumberedsec Emax |
| @cindex Ada 83 attributes |
| @findex Emax |
| @noindent |
| The @code{Emax} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Enum_Rep |
| @unnumberedsec Enum_Rep |
| @cindex Representation of enums |
| @findex Enum_Rep |
| @noindent |
| For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a |
| function with the following spec: |
| |
| @smallexample @c ada |
| function @var{S}'Enum_Rep (Arg : @var{S}'Base) |
| return @i{Universal_Integer}; |
| @end smallexample |
| |
| @noindent |
| It is also allowable to apply @code{Enum_Rep} directly to an object of an |
| enumeration type or to a non-overloaded enumeration |
| literal. In this case @code{@var{S}'Enum_Rep} is equivalent to |
| @code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the |
| enumeration literal or object. |
| |
| The function returns the representation value for the given enumeration |
| value. This will be equal to value of the @code{Pos} attribute in the |
| absence of an enumeration representation clause. This is a static |
| attribute (i.e.@: the result is static if the argument is static). |
| |
| @code{@var{S}'Enum_Rep} can also be used with integer types and objects, |
| in which case it simply returns the integer value. The reason for this |
| is to allow it to be used for @code{(<>)} discrete formal arguments in |
| a generic unit that can be instantiated with either enumeration types |
| or integer types. Note that if @code{Enum_Rep} is used on a modular |
| type whose upper bound exceeds the upper bound of the largest signed |
| integer type, and the argument is a variable, so that the universal |
| integer calculation is done at run-time, then the call to @code{Enum_Rep} |
| may raise @code{Constraint_Error}. |
| |
| @node Epsilon |
| @unnumberedsec Epsilon |
| @cindex Ada 83 attributes |
| @findex Epsilon |
| @noindent |
| The @code{Epsilon} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Fixed_Value |
| @unnumberedsec Fixed_Value |
| @findex Fixed_Value |
| @noindent |
| For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a |
| function with the following specification: |
| |
| @smallexample @c ada |
| function @var{S}'Fixed_Value (Arg : @i{Universal_Integer}) |
| return @var{S}; |
| @end smallexample |
| |
| @noindent |
| The value returned is the fixed-point value @var{V} such that |
| |
| @smallexample @c ada |
| @var{V} = Arg * @var{S}'Small |
| @end smallexample |
| |
| @noindent |
| The effect is thus similar to first converting the argument to the |
| integer type used to represent @var{S}, and then doing an unchecked |
| conversion to the fixed-point type. The difference is |
| that there are full range checks, to ensure that the result is in range. |
| This attribute is primarily intended for use in implementation of the |
| input-output functions for fixed-point values. |
| |
| @node Has_Access_Values |
| @unnumberedsec Has_Access_Values |
| @cindex Access values, testing for |
| @findex Has_Access_Values |
| @noindent |
| The prefix of the @code{Has_Access_Values} attribute is a type. The result |
| is a Boolean value which is True if the is an access type, or is a composite |
| type with a component (at any nesting depth) that is an access type, and is |
| False otherwise. |
| The intended use of this attribute is in conjunction with generic |
| definitions. If the attribute is applied to a generic private type, it |
| indicates whether or not the corresponding actual type has access values. |
| |
| @node Has_Discriminants |
| @unnumberedsec Has_Discriminants |
| @cindex Discriminants, testing for |
| @findex Has_Discriminants |
| @noindent |
| The prefix of the @code{Has_Discriminants} attribute is a type. The result |
| is a Boolean value which is True if the type has discriminants, and False |
| otherwise. The intended use of this attribute is in conjunction with generic |
| definitions. If the attribute is applied to a generic private type, it |
| indicates whether or not the corresponding actual type has discriminants. |
| |
| @node Img |
| @unnumberedsec Img |
| @findex Img |
| @noindent |
| The @code{Img} attribute differs from @code{Image} in that it may be |
| applied to objects as well as types, in which case it gives the |
| @code{Image} for the subtype of the object. This is convenient for |
| debugging: |
| |
| @smallexample @c ada |
| Put_Line ("X = " & X'Img); |
| @end smallexample |
| |
| @noindent |
| has the same meaning as the more verbose: |
| |
| @smallexample @c ada |
| Put_Line ("X = " & @var{T}'Image (X)); |
| @end smallexample |
| |
| @noindent |
| where @var{T} is the (sub)type of the object @code{X}. |
| |
| @node Integer_Value |
| @unnumberedsec Integer_Value |
| @findex Integer_Value |
| @noindent |
| For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a |
| function with the following spec: |
| |
| @smallexample @c ada |
| function @var{S}'Integer_Value (Arg : @i{Universal_Fixed}) |
| return @var{S}; |
| @end smallexample |
| |
| @noindent |
| The value returned is the integer value @var{V}, such that |
| |
| @smallexample @c ada |
| Arg = @var{V} * @var{T}'Small |
| @end smallexample |
| |
| @noindent |
| where @var{T} is the type of @code{Arg}. |
| The effect is thus similar to first doing an unchecked conversion from |
| the fixed-point type to its corresponding implementation type, and then |
| converting the result to the target integer type. The difference is |
| that there are full range checks, to ensure that the result is in range. |
| This attribute is primarily intended for use in implementation of the |
| standard input-output functions for fixed-point values. |
| |
| @node Large |
| @unnumberedsec Large |
| @cindex Ada 83 attributes |
| @findex Large |
| @noindent |
| The @code{Large} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Machine_Size |
| @unnumberedsec Machine_Size |
| @findex Machine_Size |
| @noindent |
| This attribute is identical to the @code{Object_Size} attribute. It is |
| provided for compatibility with the DEC Ada 83 attribute of this name. |
| |
| @node Mantissa |
| @unnumberedsec Mantissa |
| @cindex Ada 83 attributes |
| @findex Mantissa |
| @noindent |
| The @code{Mantissa} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Max_Interrupt_Priority |
| @unnumberedsec Max_Interrupt_Priority |
| @cindex Interrupt priority, maximum |
| @findex Max_Interrupt_Priority |
| @noindent |
| @code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only |
| permissible prefix), provides the same value as |
| @code{System.Max_Interrupt_Priority}. |
| |
| @node Max_Priority |
| @unnumberedsec Max_Priority |
| @cindex Priority, maximum |
| @findex Max_Priority |
| @noindent |
| @code{Standard'Max_Priority} (@code{Standard} is the only permissible |
| prefix) provides the same value as @code{System.Max_Priority}. |
| |
| @node Maximum_Alignment |
| @unnumberedsec Maximum_Alignment |
| @cindex Alignment, maximum |
| @findex Maximum_Alignment |
| @noindent |
| @code{Standard'Maximum_Alignment} (@code{Standard} is the only |
| permissible prefix) provides the maximum useful alignment value for the |
| target. This is a static value that can be used to specify the alignment |
| for an object, guaranteeing that it is properly aligned in all |
| cases. |
| |
| @node Mechanism_Code |
| @unnumberedsec Mechanism_Code |
| @cindex Return values, passing mechanism |
| @cindex Parameters, passing mechanism |
| @findex Mechanism_Code |
| @noindent |
| @code{@var{function}'Mechanism_Code} yields an integer code for the |
| mechanism used for the result of function, and |
| @code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism |
| used for formal parameter number @var{n} (a static integer value with 1 |
| meaning the first parameter) of @var{subprogram}. The code returned is: |
| |
| @table @asis |
| @item 1 |
| by copy (value) |
| @item 2 |
| by reference |
| @item 3 |
| by descriptor (default descriptor class) |
| @item 4 |
| by descriptor (UBS: unaligned bit string) |
| @item 5 |
| by descriptor (UBSB: aligned bit string with arbitrary bounds) |
| @item 6 |
| by descriptor (UBA: unaligned bit array) |
| @item 7 |
| by descriptor (S: string, also scalar access type parameter) |
| @item 8 |
| by descriptor (SB: string with arbitrary bounds) |
| @item 9 |
| by descriptor (A: contiguous array) |
| @item 10 |
| by descriptor (NCA: non-contiguous array) |
| @end table |
| |
| @noindent |
| Values from 3 through 10 are only relevant to Digital OpenVMS implementations. |
| @cindex OpenVMS |
| |
| @node Null_Parameter |
| @unnumberedsec Null_Parameter |
| @cindex Zero address, passing |
| @findex Null_Parameter |
| @noindent |
| A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of |
| type or subtype @var{T} allocated at machine address zero. The attribute |
| is allowed only as the default expression of a formal parameter, or as |
| an actual expression of a subprogram call. In either case, the |
| subprogram must be imported. |
| |
| The identity of the object is represented by the address zero in the |
| argument list, independent of the passing mechanism (explicit or |
| default). |
| |
| This capability is needed to specify that a zero address should be |
| passed for a record or other composite object passed by reference. |
| There is no way of indicating this without the @code{Null_Parameter} |
| attribute. |
| |
| @node Object_Size |
| @unnumberedsec Object_Size |
| @cindex Size, used for objects |
| @findex Object_Size |
| @noindent |
| The size of an object is not necessarily the same as the size of the type |
| of an object. This is because by default object sizes are increased to be |
| a multiple of the alignment of the object. For example, |
| @code{Natural'Size} is |
| 31, but by default objects of type @code{Natural} will have a size of 32 bits. |
| Similarly, a record containing an integer and a character: |
| |
| @smallexample @c ada |
| type Rec is record |
| I : Integer; |
| C : Character; |
| end record; |
| @end smallexample |
| |
| @noindent |
| will have a size of 40 (that is @code{Rec'Size} will be 40. The |
| alignment will be 4, because of the |
| integer field, and so the default size of record objects for this type |
| will be 64 (8 bytes). |
| |
| The @code{@var{type}'Object_Size} attribute |
| has been added to GNAT to allow the |
| default object size of a type to be easily determined. For example, |
| @code{Natural'Object_Size} is 32, and |
| @code{Rec'Object_Size} (for the record type in the above example) will be |
| 64. Note also that, unlike the situation with the |
| @code{Size} attribute as defined in the Ada RM, the |
| @code{Object_Size} attribute can be specified individually |
| for different subtypes. For example: |
| |
| @smallexample @c ada |
| type R is new Integer; |
| subtype R1 is R range 1 .. 10; |
| subtype R2 is R range 1 .. 10; |
| for R2'Object_Size use 8; |
| @end smallexample |
| |
| @noindent |
| In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both |
| 32 since the default object size for a subtype is the same as the object size |
| for the parent subtype. This means that objects of type @code{R} |
| or @code{R1} will |
| by default be 32 bits (four bytes). But objects of type |
| @code{R2} will be only |
| 8 bits (one byte), since @code{R2'Object_Size} has been set to 8. |
| |
| @node Passed_By_Reference |
| @unnumberedsec Passed_By_Reference |
| @cindex Parameters, when passed by reference |
| @findex Passed_By_Reference |
| @noindent |
| @code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns |
| a value of type @code{Boolean} value that is @code{True} if the type is |
| normally passed by reference and @code{False} if the type is normally |
| passed by copy in calls. For scalar types, the result is always @code{False} |
| and is static. For non-scalar types, the result is non-static. |
| |
| @node Range_Length |
| @unnumberedsec Range_Length |
| @findex Range_Length |
| @noindent |
| @code{@var{type}'Range_Length} for any discrete type @var{type} yields |
| the number of values represented by the subtype (zero for a null |
| range). The result is static for static subtypes. @code{Range_Length} |
| applied to the index subtype of a one dimensional array always gives the |
| same result as @code{Range} applied to the array itself. |
| |
| @node Safe_Emax |
| @unnumberedsec Safe_Emax |
| @cindex Ada 83 attributes |
| @findex Safe_Emax |
| @noindent |
| The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Safe_Large |
| @unnumberedsec Safe_Large |
| @cindex Ada 83 attributes |
| @findex Safe_Large |
| @noindent |
| The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute. |
| |
| @node Small |
| @unnumberedsec Small |
| @cindex Ada 83 attributes |
| @findex Small |
| @noindent |
| The @code{Small} attribute is defined in Ada 95 only for fixed-point types. |
| GNAT also allows this attribute to be applied to floating-point types |
| for compatibility with Ada 83. See |
| the Ada 83 reference manual for an exact description of the semantics of |
| this attribute when applied to floating-point types. |
| |
| @node Storage_Unit |
| @unnumberedsec Storage_Unit |
| @findex Storage_Unit |
| @noindent |
| @code{Standard'Storage_Unit} (@code{Standard} is the only permissible |
| prefix) provides the same value as @code{System.Storage_Unit}. |
| |
| @node Target_Name |
| @unnumberedsec Target_Name |
| @findex Target_Name |
| @noindent |
| @code{Standard'Target_Name} (@code{Standard} is the only permissible |
| prefix) provides a static string value that identifies the target |
| for the current compilation. For GCC implementations, this is the |
| standard gcc target name without the terminating slash (for |
| example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). |
| |
| @node Tick |
| @unnumberedsec Tick |
| @findex Tick |
| @noindent |
| @code{Standard'Tick} (@code{Standard} is the only permissible prefix) |
| provides the same value as @code{System.Tick}, |
| |
| @node To_Address |
| @unnumberedsec To_Address |
| @findex To_Address |
| @noindent |
| The @code{System'To_Address} |
| (@code{System} is the only permissible prefix) |
| denotes a function identical to |
| @code{System.Storage_Elements.To_Address} except that |
| it is a static attribute. This means that if its argument is |
| a static expression, then the result of the attribute is a |
| static expression. The result is that such an expression can be |
| used in contexts (e.g.@: preelaborable packages) which require a |
| static expression and where the function call could not be used |
| (since the function call is always non-static, even if its |
| argument is static). |
| |
| @node Type_Class |
| @unnumberedsec Type_Class |
| @findex Type_Class |
| @noindent |
| @code{@var{type}'Type_Class} for any type or subtype @var{type} yields |
| the value of the type class for the full type of @var{type}. If |
| @var{type} is a generic formal type, the value is the value for the |
| corresponding actual subtype. The value of this attribute is of type |
| @code{System.Aux_DEC.Type_Class}, which has the following definition: |
| |
| @smallexample @c ada |
| type Type_Class is |
| (Type_Class_Enumeration, |
| Type_Class_Integer, |
| Type_Class_Fixed_Point, |
| Type_Class_Floating_Point, |
| Type_Class_Array, |
| Type_Class_Record, |
| Type_Class_Access, |
| Type_Class_Task, |
| Type_Class_Address); |
| @end smallexample |
| |
| @noindent |
| Protected types yield the value @code{Type_Class_Task}, which thus |
| applies to all concurrent types. This attribute is designed to |
| be compatible with the DEC Ada 83 attribute of the same name. |
| |
| @node UET_Address |
| @unnumberedsec UET_Address |
| @findex UET_Address |
| @noindent |
| The @code{UET_Address} attribute can only be used for a prefix which |
| denotes a library package. It yields the address of the unit exception |
| table when zero cost exception handling is used. This attribute is |
| intended only for use within the GNAT implementation. See the unit |
| @code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb} |
| for details on how this attribute is used in the implementation. |
| |
| @node Unconstrained_Array |
| @unnumberedsec Unconstrained_Array |
| @findex Unconstrained_Array |
| @noindent |
| The @code{Unconstrained_Array} attribute can be used with a prefix that |
| denotes any type or subtype. It is a static attribute that yields |
| @code{True} if the prefix designates an unconstrained array, |
| and @code{False} otherwise. In a generic instance, the result is |
| still static, and yields the result of applying this test to the |
| generic actual. |
| |
| @node Universal_Literal_String |
| @unnumberedsec Universal_Literal_String |
| @cindex Named numbers, representation of |
| @findex Universal_Literal_String |
| @noindent |
| The prefix of @code{Universal_Literal_String} must be a named |
| number. The static result is the string consisting of the characters of |
| the number as defined in the original source. This allows the user |
| program to access the actual text of named numbers without intermediate |
| conversions and without the need to enclose the strings in quotes (which |
| would preclude their use as numbers). This is used internally for the |
| construction of values of the floating-point attributes from the file |
| @file{ttypef.ads}, but may also be used by user programs. |
| |
| For example, the following program prints the first 50 digits of pi: |
| |
| @smallexample @c ada |
| with Text_IO; use Text_IO; |
| with Ada.Numerics; |
| procedure Pi is |
| begin |
| Put (Ada.Numerics.Pi'Universal_Literal_String); |
| end; |
| @end smallexample |
| |
| @node Unrestricted_Access |
| @unnumberedsec Unrestricted_Access |
| @cindex @code{Access}, unrestricted |
| @findex Unrestricted_Access |
| @noindent |
| The @code{Unrestricted_Access} attribute is similar to @code{Access} |
| except that all accessibility and aliased view checks are omitted. This |
| is a user-beware attribute. It is similar to |
| @code{Address}, for which it is a desirable replacement where the value |
| desired is an access type. In other words, its effect is identical to |
| first applying the @code{Address} attribute and then doing an unchecked |
| conversion to a desired access type. In GNAT, but not necessarily in |
| other implementations, the use of static chains for inner level |
| subprograms means that @code{Unrestricted_Access} applied to a |
| subprogram yields a value that can be called as long as the subprogram |
| is in scope (normal Ada 95 accessibility rules restrict this usage). |
| |
| It is possible to use @code{Unrestricted_Access} for any type, but care |
| must be exercised if it is used to create pointers to unconstrained |
| objects. In this case, the resulting pointer has the same scope as the |
| context of the attribute, and may not be returned to some enclosing |
| scope. For instance, a function cannot use @code{Unrestricted_Access} |
| to create a unconstrained pointer and then return that value to the |
| caller. |
| |
| @node VADS_Size |
| @unnumberedsec VADS_Size |
| @cindex @code{Size}, VADS compatibility |
| @findex VADS_Size |
| @noindent |
| The @code{'VADS_Size} attribute is intended to make it easier to port |
| legacy code which relies on the semantics of @code{'Size} as implemented |
| by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the |
| same semantic interpretation. In particular, @code{'VADS_Size} applied |
| to a predefined or other primitive type with no Size clause yields the |
| Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on |
| typical machines). In addition @code{'VADS_Size} applied to an object |
| gives the result that would be obtained by applying the attribute to |
| the corresponding type. |
| |
| @node Value_Size |
| @unnumberedsec Value_Size |
| @cindex @code{Size}, setting for not-first subtype |
| @findex Value_Size |
| @code{@var{type}'Value_Size} is the number of bits required to represent |
| a value of the given subtype. It is the same as @code{@var{type}'Size}, |
| but, unlike @code{Size}, may be set for non-first subtypes. |
| |
| @node Wchar_T_Size |
| @unnumberedsec Wchar_T_Size |
| @findex Wchar_T_Size |
| @code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible |
| prefix) provides the size in bits of the C @code{wchar_t} type |
| primarily for constructing the definition of this type in |
| package @code{Interfaces.C}. |
| |
| @node Word_Size |
| @unnumberedsec Word_Size |
| @findex Word_Size |
| @code{Standard'Word_Size} (@code{Standard} is the only permissible |
| prefix) provides the value @code{System.Word_Size}. |
| |
| @c ------------------------ |
| @node Implementation Advice |
| @chapter Implementation Advice |
| @noindent |
| The main text of the Ada 95 Reference Manual describes the required |
| behavior of all Ada 95 compilers, and the GNAT compiler conforms to |
| these requirements. |
| |
| In addition, there are sections throughout the Ada 95 |
| reference manual headed |
| by the phrase ``implementation advice''. These sections are not normative, |
| i.e.@: they do not specify requirements that all compilers must |
| follow. Rather they provide advice on generally desirable behavior. You |
| may wonder why they are not requirements. The most typical answer is |
| that they describe behavior that seems generally desirable, but cannot |
| be provided on all systems, or which may be undesirable on some systems. |
| |
| As far as practical, GNAT follows the implementation advice sections in |
| the Ada 95 Reference Manual. This chapter contains a table giving the |
| reference manual section number, paragraph number and several keywords |
| for each advice. Each entry consists of the text of the advice followed |
| by the GNAT interpretation of this advice. Most often, this simply says |
| ``followed'', which means that GNAT follows the advice. However, in a |
| number of cases, GNAT deliberately deviates from this advice, in which |
| case the text describes what GNAT does and why. |
| |
| @cindex Error detection |
| @unnumberedsec 1.1.3(20): Error Detection |
| @sp 1 |
| @cartouche |
| If an implementation detects the use of an unsupported Specialized Needs |
| Annex feature at run time, it should raise @code{Program_Error} if |
| feasible. |
| @end cartouche |
| Not relevant. All specialized needs annex features are either supported, |
| or diagnosed at compile time. |
| |
| @cindex Child Units |
| @unnumberedsec 1.1.3(31): Child Units |
| @sp 1 |
| @cartouche |
| If an implementation wishes to provide implementation-defined |
| extensions to the functionality of a language-defined library unit, it |
| should normally do so by adding children to the library unit. |
| @end cartouche |
| Followed. |
| |
| @cindex Bounded errors |
| @unnumberedsec 1.1.5(12): Bounded Errors |
| @sp 1 |
| @cartouche |
| If an implementation detects a bounded error or erroneous |
| execution, it should raise @code{Program_Error}. |
| @end cartouche |
| Followed in all cases in which the implementation detects a bounded |
| error or erroneous execution. Not all such situations are detected at |
| runtime. |
| |
| @cindex Pragmas |
| @unnumberedsec 2.8(16): Pragmas |
| @sp 1 |
| @cartouche |
| Normally, implementation-defined pragmas should have no semantic effect |
| for error-free programs; that is, if the implementation-defined pragmas |
| are removed from a working program, the program should still be legal, |
| and should still have the same semantics. |
| @end cartouche |
| The following implementation defined pragmas are exceptions to this |
| rule: |
| |
| @table @code |
| @item Abort_Defer |
| Affects semantics |
| @item Ada_83 |
| Affects legality |
| @item Assert |
| Affects semantics |
| @item CPP_Class |
| Affects semantics |
| @item CPP_Constructor |
| Affects semantics |
| @item CPP_Virtual |
| Affects semantics |
| @item CPP_Vtable |
| Affects semantics |
| @item Debug |
| Affects semantics |
| @item Interface_Name |
| Affects semantics |
| @item Machine_Attribute |
| Affects semantics |
| @item Unimplemented_Unit |
| Affects legality |
| @item Unchecked_Union |
| Affects semantics |
| @end table |
| |
| @noindent |
| In each of the above cases, it is essential to the purpose of the pragma |
| that this advice not be followed. For details see the separate section |
| on implementation defined pragmas. |
| |
| @unnumberedsec 2.8(17-19): Pragmas |
| @sp 1 |
| @cartouche |
| Normally, an implementation should not define pragmas that can |
| make an illegal program legal, except as follows: |
| @end cartouche |
| @sp 1 |
| @cartouche |
| A pragma used to complete a declaration, such as a pragma @code{Import}; |
| @end cartouche |
| @sp 1 |
| @cartouche |
| A pragma used to configure the environment by adding, removing, or |
| replacing @code{library_items}. |
| @end cartouche |
| See response to paragraph 16 of this same section. |
| |
| @cindex Character Sets |
| @cindex Alternative Character Sets |
| @unnumberedsec 3.5.2(5): Alternative Character Sets |
| @sp 1 |
| @cartouche |
| If an implementation supports a mode with alternative interpretations |
| for @code{Character} and @code{Wide_Character}, the set of graphic |
| characters of @code{Character} should nevertheless remain a proper |
| subset of the set of graphic characters of @code{Wide_Character}. Any |
| character set ``localizations'' should be reflected in the results of |
| the subprograms defined in the language-defined package |
| @code{Characters.Handling} (see A.3) available in such a mode. In a mode with |
| an alternative interpretation of @code{Character}, the implementation should |
| also support a corresponding change in what is a legal |
| @code{identifier_letter}. |
| @end cartouche |
| Not all wide character modes follow this advice, in particular the JIS |
| and IEC modes reflect standard usage in Japan, and in these encoding, |
| the upper half of the Latin-1 set is not part of the wide-character |
| subset, since the most significant bit is used for wide character |
| encoding. However, this only applies to the external forms. Internally |
| there is no such restriction. |
| |
| @cindex Integer types |
| @unnumberedsec 3.5.4(28): Integer Types |
| |
| @sp 1 |
| @cartouche |
| An implementation should support @code{Long_Integer} in addition to |
| @code{Integer} if the target machine supports 32-bit (or longer) |
| arithmetic. No other named integer subtypes are recommended for package |
| @code{Standard}. Instead, appropriate named integer subtypes should be |
| provided in the library package @code{Interfaces} (see B.2). |
| @end cartouche |
| @code{Long_Integer} is supported. Other standard integer types are supported |
| so this advice is not fully followed. These types |
| are supported for convenient interface to C, and so that all hardware |
| types of the machine are easily available. |
| @unnumberedsec 3.5.4(29): Integer Types |
| |
| @sp 1 |
| @cartouche |
| An implementation for a two's complement machine should support |
| modular types with a binary modulus up to @code{System.Max_Int*2+2}. An |
| implementation should support a non-binary modules up to @code{Integer'Last}. |
| @end cartouche |
| Followed. |
| |
| @cindex Enumeration values |
| @unnumberedsec 3.5.5(8): Enumeration Values |
| @sp 1 |
| @cartouche |
| For the evaluation of a call on @code{@var{S}'Pos} for an enumeration |
| subtype, if the value of the operand does not correspond to the internal |
| code for any enumeration literal of its type (perhaps due to an |
| un-initialized variable), then the implementation should raise |
| @code{Program_Error}. This is particularly important for enumeration |
| types with noncontiguous internal codes specified by an |
| enumeration_representation_clause. |
| @end cartouche |
| Followed. |
| |
| @cindex Float types |
| @unnumberedsec 3.5.7(17): Float Types |
| @sp 1 |
| @cartouche |
| An implementation should support @code{Long_Float} in addition to |
| @code{Float} if the target machine supports 11 or more digits of |
| precision. No other named floating point subtypes are recommended for |
| package @code{Standard}. Instead, appropriate named floating point subtypes |
| should be provided in the library package @code{Interfaces} (see B.2). |
| @end cartouche |
| @code{Short_Float} and @code{Long_Long_Float} are also provided. The |
| former provides improved compatibility with other implementations |
| supporting this type. The latter corresponds to the highest precision |
| floating-point type supported by the hardware. On most machines, this |
| will be the same as @code{Long_Float}, but on some machines, it will |
| correspond to the IEEE extended form. The notable case is all ia32 |
| (x86) implementations, where @code{Long_Long_Float} corresponds to |
| the 80-bit extended precision format supported in hardware on this |
| processor. Note that the 128-bit format on SPARC is not supported, |
| since this is a software rather than a hardware format. |
| |
| @cindex Multidimensional arrays |
| @cindex Arrays, multidimensional |
| @unnumberedsec 3.6.2(11): Multidimensional Arrays |
| @sp 1 |
| @cartouche |
| An implementation should normally represent multidimensional arrays in |
| row-major order, consistent with the notation used for multidimensional |
| array aggregates (see 4.3.3). However, if a pragma @code{Convention} |
| (@code{Fortran}, @dots{}) applies to a multidimensional array type, then |
| column-major order should be used instead (see B.5, ``Interfacing with |
| Fortran''). |
| @end cartouche |
| Followed. |
| |
| @findex Duration'Small |
| @unnumberedsec 9.6(30-31): Duration'Small |
| @sp 1 |
| @cartouche |
| Whenever possible in an implementation, the value of @code{Duration'Small} |
| should be no greater than 100 microseconds. |
| @end cartouche |
| Followed. (@code{Duration'Small} = 10**(@minus{}9)). |
| |
| @sp 1 |
| @cartouche |
| The time base for @code{delay_relative_statements} should be monotonic; |
| it need not be the same time base as used for @code{Calendar.Clock}. |
| @end cartouche |
| Followed. |
| |
| @unnumberedsec 10.2.1(12): Consistent Representation |
| @sp 1 |
| @cartouche |
| In an implementation, a type declared in a pre-elaborated package should |
| have the same representation in every elaboration of a given version of |
| the package, whether the elaborations occur in distinct executions of |
| the same program, or in executions of distinct programs or partitions |
| that include the given version. |
| @end cartouche |
| Followed, except in the case of tagged types. Tagged types involve |
| implicit pointers to a local copy of a dispatch table, and these pointers |
| have representations which thus depend on a particular elaboration of the |
| package. It is not easy to see how it would be possible to follow this |
| advice without severely impacting efficiency of execution. |
| |
| @cindex Exception information |
| @unnumberedsec 11.4.1(19): Exception Information |
| @sp 1 |
| @cartouche |
| @code{Exception_Message} by default and @code{Exception_Information} |
| should produce information useful for |
| debugging. @code{Exception_Message} should be short, about one |
| line. @code{Exception_Information} can be long. @code{Exception_Message} |
| should not include the |
| @code{Exception_Name}. @code{Exception_Information} should include both |
| the @code{Exception_Name} and the @code{Exception_Message}. |
| @end cartouche |
| Followed. For each exception that doesn't have a specified |
| @code{Exception_Message}, the compiler generates one containing the location |
| of the raise statement. This location has the form ``file:line'', where |
| file is the short file name (without path information) and line is the line |
| number in the file. Note that in the case of the Zero Cost Exception |
| mechanism, these messages become redundant with the Exception_Information that |
| contains a full backtrace of the calling sequence, so they are disabled. |
| To disable explicitly the generation of the source location message, use the |
| Pragma @code{Discard_Names}. |
| |
| @cindex Suppression of checks |
| @cindex Checks, suppression of |
| @unnumberedsec 11.5(28): Suppression of Checks |
| @sp 1 |
| @cartouche |
| The implementation should minimize the code executed for checks that |
| have been suppressed. |
| @end cartouche |
| Followed. |
| |
| @cindex Representation clauses |
| @unnumberedsec 13.1 (21-24): Representation Clauses |
| @sp 1 |
| @cartouche |
| The recommended level of support for all representation items is |
| qualified as follows: |
| @end cartouche |
| @sp 1 |
| @cartouche |
| An implementation need not support representation items containing |
| non-static expressions, except that an implementation should support a |
| representation item for a given entity if each non-static expression in |
| the representation item is a name that statically denotes a constant |
| declared before the entity. |
| @end cartouche |
| Followed. In fact, GNAT goes beyond the recommended level of support |
| by allowing nonstatic expressions in some representation clauses even |
| without the need to declare constants initialized with the values of |
| such expressions. |
| For example: |
| |
| @smallexample @c ada |
| X : Integer; |
| Y : Float; |
| for Y'Address use X'Address;>> |
| @end smallexample |
| |
| |
| @sp 1 |
| @cartouche |
| An implementation need not support a specification for the @code{Size} |
| for a given composite subtype, nor the size or storage place for an |
| object (including a component) of a given composite subtype, unless the |
| constraints on the subtype and its composite subcomponents (if any) are |
| all static constraints. |
| @end cartouche |
| Followed. Size Clauses are not permitted on non-static components, as |
| described above. |
| |
| @sp 1 |
| @cartouche |
| An aliased component, or a component whose type is by-reference, should |
| always be allocated at an addressable location. |
| @end cartouche |
| Followed. |
| |
| @cindex Packed types |
| @unnumberedsec 13.2(6-8): Packed Types |
| @sp 1 |
| @cartouche |
| If a type is packed, then the implementation should try to minimize |
| storage allocated to objects of the type, possibly at the expense of |
| speed of accessing components, subject to reasonable complexity in |
| addressing calculations. |
| @end cartouche |
| @sp 1 |
| @cartouche |
| The recommended level of support pragma @code{Pack} is: |
| |
| For a packed record type, the components should be packed as tightly as |
| possible subject to the Sizes of the component subtypes, and subject to |
| any @code{record_representation_clause} that applies to the type; the |
| implementation may, but need not, reorder components or cross aligned |
| word boundaries to improve the packing. A component whose @code{Size} is |
| greater than the word size may be allocated an integral number of words. |
| @end cartouche |
| Followed. Tight packing of arrays is supported for all component sizes |
| up to 64-bits. If the array component size is 1 (that is to say, if |
| the component is a boolean type or an enumeration type with two values) |
| then values of the type are implicitly initialized to zero. This |
| happens both for objects of the packed type, and for objects that have a |
| subcomponent of the packed type. |
| |
| @sp 1 |
| @cartouche |
| An implementation should support Address clauses for imported |
| subprograms. |
| @end cartouche |
| Followed. |
| @cindex @code{Address} clauses |
| @unnumberedsec 13.3(14-19): Address Clauses |
| |
| @sp 1 |
| @cartouche |
| For an array @var{X}, @code{@var{X}'Address} should point at the first |
| component of the array, and not at the array bounds. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| The recommended level of support for the @code{Address} attribute is: |
| |
| @code{@var{X}'Address} should produce a useful result if @var{X} is an |
| object that is aliased or of a by-reference type, or is an entity whose |
| @code{Address} has been specified. |
| @end cartouche |
| Followed. A valid address will be produced even if none of those |
| conditions have been met. If necessary, the object is forced into |
| memory to ensure the address is valid. |
| |
| @sp 1 |
| @cartouche |
| An implementation should support @code{Address} clauses for imported |
| subprograms. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| Objects (including subcomponents) that are aliased or of a by-reference |
| type should be allocated on storage element boundaries. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| If the @code{Address} of an object is specified, or it is imported or exported, |
| then the implementation should not perform optimizations based on |
| assumptions of no aliases. |
| @end cartouche |
| Followed. |
| |
| @cindex @code{Alignment} clauses |
| @unnumberedsec 13.3(29-35): Alignment Clauses |
| @sp 1 |
| @cartouche |
| The recommended level of support for the @code{Alignment} attribute for |
| subtypes is: |
| |
| An implementation should support specified Alignments that are factors |
| and multiples of the number of storage elements per word, subject to the |
| following: |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An implementation need not support specified @code{Alignment}s for |
| combinations of @code{Size}s and @code{Alignment}s that cannot be easily |
| loaded and stored by available machine instructions. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An implementation need not support specified @code{Alignment}s that are |
| greater than the maximum @code{Alignment} the implementation ever returns by |
| default. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| The recommended level of support for the @code{Alignment} attribute for |
| objects is: |
| |
| Same as above, for subtypes, but in addition: |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| For stand-alone library-level objects of statically constrained |
| subtypes, the implementation should support all @code{Alignment}s |
| supported by the target linker. For example, page alignment is likely to |
| be supported for such objects, but not for subtypes. |
| @end cartouche |
| Followed. |
| |
| @cindex @code{Size} clauses |
| @unnumberedsec 13.3(42-43): Size Clauses |
| @sp 1 |
| @cartouche |
| The recommended level of support for the @code{Size} attribute of |
| objects is: |
| |
| A @code{Size} clause should be supported for an object if the specified |
| @code{Size} is at least as large as its subtype's @code{Size}, and |
| corresponds to a size in storage elements that is a multiple of the |
| object's @code{Alignment} (if the @code{Alignment} is nonzero). |
| @end cartouche |
| Followed. |
| |
| @unnumberedsec 13.3(50-56): Size Clauses |
| @sp 1 |
| @cartouche |
| If the @code{Size} of a subtype is specified, and allows for efficient |
| independent addressability (see 9.10) on the target architecture, then |
| the @code{Size} of the following objects of the subtype should equal the |
| @code{Size} of the subtype: |
| |
| Aliased objects (including components). |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| @code{Size} clause on a composite subtype should not affect the |
| internal layout of components. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| The recommended level of support for the @code{Size} attribute of subtypes is: |
| @end cartouche |
| @sp 1 |
| @cartouche |
| The @code{Size} (if not specified) of a static discrete or fixed point |
| subtype should be the number of bits needed to represent each value |
| belonging to the subtype using an unbiased representation, leaving space |
| for a sign bit only if the subtype contains negative values. If such a |
| subtype is a first subtype, then an implementation should support a |
| specified @code{Size} for it that reflects this representation. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| For a subtype implemented with levels of indirection, the @code{Size} |
| should include the size of the pointers, but not the size of what they |
| point at. |
| @end cartouche |
| Followed. |
| |
| @cindex @code{Component_Size} clauses |
| @unnumberedsec 13.3(71-73): Component Size Clauses |
| @sp 1 |
| @cartouche |
| The recommended level of support for the @code{Component_Size} |
| attribute is: |
| @end cartouche |
| @sp 1 |
| @cartouche |
| An implementation need not support specified @code{Component_Sizes} that are |
| less than the @code{Size} of the component subtype. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An implementation should support specified @code{Component_Size}s that |
| are factors and multiples of the word size. For such |
| @code{Component_Size}s, the array should contain no gaps between |
| components. For other @code{Component_Size}s (if supported), the array |
| should contain no gaps between components when packing is also |
| specified; the implementation should forbid this combination in cases |
| where it cannot support a no-gaps representation. |
| @end cartouche |
| Followed. |
| |
| @cindex Enumeration representation clauses |
| @cindex Representation clauses, enumeration |
| @unnumberedsec 13.4(9-10): Enumeration Representation Clauses |
| @sp 1 |
| @cartouche |
| The recommended level of support for enumeration representation clauses |
| is: |
| |
| An implementation need not support enumeration representation clauses |
| for boolean types, but should at minimum support the internal codes in |
| the range @code{System.Min_Int.System.Max_Int}. |
| @end cartouche |
| Followed. |
| |
| @cindex Record representation clauses |
| @cindex Representation clauses, records |
| @unnumberedsec 13.5.1(17-22): Record Representation Clauses |
| @sp 1 |
| @cartouche |
| The recommended level of support for |
| @*@code{record_representation_clauses} is: |
| |
| An implementation should support storage places that can be extracted |
| with a load, mask, shift sequence of machine code, and set with a load, |
| shift, mask, store sequence, given the available machine instructions |
| and run-time model. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| A storage place should be supported if its size is equal to the |
| @code{Size} of the component subtype, and it starts and ends on a |
| boundary that obeys the @code{Alignment} of the component subtype. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| If the default bit ordering applies to the declaration of a given type, |
| then for a component whose subtype's @code{Size} is less than the word |
| size, any storage place that does not cross an aligned word boundary |
| should be supported. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An implementation may reserve a storage place for the tag field of a |
| tagged type, and disallow other components from overlapping that place. |
| @end cartouche |
| Followed. The storage place for the tag field is the beginning of the tagged |
| record, and its size is Address'Size. GNAT will reject an explicit component |
| clause for the tag field. |
| |
| @sp 1 |
| @cartouche |
| An implementation need not support a @code{component_clause} for a |
| component of an extension part if the storage place is not after the |
| storage places of all components of the parent type, whether or not |
| those storage places had been specified. |
| @end cartouche |
| Followed. The above advice on record representation clauses is followed, |
| and all mentioned features are implemented. |
| |
| @cindex Storage place attributes |
| @unnumberedsec 13.5.2(5): Storage Place Attributes |
| @sp 1 |
| @cartouche |
| If a component is represented using some form of pointer (such as an |
| offset) to the actual data of the component, and this data is contiguous |
| with the rest of the object, then the storage place attributes should |
| reflect the place of the actual data, not the pointer. If a component is |
| allocated discontinuously from the rest of the object, then a warning |
| should be generated upon reference to one of its storage place |
| attributes. |
| @end cartouche |
| Followed. There are no such components in GNAT@. |
| |
| @cindex Bit ordering |
| @unnumberedsec 13.5.3(7-8): Bit Ordering |
| @sp 1 |
| @cartouche |
| The recommended level of support for the non-default bit ordering is: |
| @end cartouche |
| @sp 1 |
| @cartouche |
| If @code{Word_Size} = @code{Storage_Unit}, then the implementation |
| should support the non-default bit ordering in addition to the default |
| bit ordering. |
| @end cartouche |
| Followed. Word size does not equal storage size in this implementation. |
| Thus non-default bit ordering is not supported. |
| |
| @cindex @code{Address}, as private type |
| @unnumberedsec 13.7(37): Address as Private |
| @sp 1 |
| @cartouche |
| @code{Address} should be of a private type. |
| @end cartouche |
| Followed. |
| |
| @cindex Operations, on @code{Address} |
| @cindex @code{Address}, operations of |
| @unnumberedsec 13.7.1(16): Address Operations |
| @sp 1 |
| @cartouche |
| Operations in @code{System} and its children should reflect the target |
| environment semantics as closely as is reasonable. For example, on most |
| machines, it makes sense for address arithmetic to ``wrap around''. |
| Operations that do not make sense should raise @code{Program_Error}. |
| @end cartouche |
| Followed. Address arithmetic is modular arithmetic that wraps around. No |
| operation raises @code{Program_Error}, since all operations make sense. |
| |
| @cindex Unchecked conversion |
| @unnumberedsec 13.9(14-17): Unchecked Conversion |
| @sp 1 |
| @cartouche |
| The @code{Size} of an array object should not include its bounds; hence, |
| the bounds should not be part of the converted data. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| The implementation should not generate unnecessary run-time checks to |
| ensure that the representation of @var{S} is a representation of the |
| target type. It should take advantage of the permission to return by |
| reference when possible. Restrictions on unchecked conversions should be |
| avoided unless required by the target environment. |
| @end cartouche |
| Followed. There are no restrictions on unchecked conversion. A warning is |
| generated if the source and target types do not have the same size since |
| the semantics in this case may be target dependent. |
| |
| @sp 1 |
| @cartouche |
| The recommended level of support for unchecked conversions is: |
| @end cartouche |
| @sp 1 |
| @cartouche |
| Unchecked conversions should be supported and should be reversible in |
| the cases where this clause defines the result. To enable meaningful use |
| of unchecked conversion, a contiguous representation should be used for |
| elementary subtypes, for statically constrained array subtypes whose |
| component subtype is one of the subtypes described in this paragraph, |
| and for record subtypes without discriminants whose component subtypes |
| are described in this paragraph. |
| @end cartouche |
| Followed. |
| |
| @cindex Heap usage, implicit |
| @unnumberedsec 13.11(23-25): Implicit Heap Usage |
| @sp 1 |
| @cartouche |
| An implementation should document any cases in which it dynamically |
| allocates heap storage for a purpose other than the evaluation of an |
| allocator. |
| @end cartouche |
| Followed, the only other points at which heap storage is dynamically |
| allocated are as follows: |
| |
| @itemize @bullet |
| @item |
| At initial elaboration time, to allocate dynamically sized global |
| objects. |
| |
| @item |
| To allocate space for a task when a task is created. |
| |
| @item |
| To extend the secondary stack dynamically when needed. The secondary |
| stack is used for returning variable length results. |
| @end itemize |
| |
| @sp 1 |
| @cartouche |
| A default (implementation-provided) storage pool for an |
| access-to-constant type should not have overhead to support deallocation of |
| individual objects. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| A storage pool for an anonymous access type should be created at the |
| point of an allocator for the type, and be reclaimed when the designated |
| object becomes inaccessible. |
| @end cartouche |
| Followed. |
| |
| @cindex Unchecked deallocation |
| @unnumberedsec 13.11.2(17): Unchecked De-allocation |
| @sp 1 |
| @cartouche |
| For a standard storage pool, @code{Free} should actually reclaim the |
| storage. |
| @end cartouche |
| Followed. |
| |
| @cindex Stream oriented attributes |
| @unnumberedsec 13.13.2(17): Stream Oriented Attributes |
| @sp 1 |
| @cartouche |
| If a stream element is the same size as a storage element, then the |
| normal in-memory representation should be used by @code{Read} and |
| @code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write} |
| should use the smallest number of stream elements needed to represent |
| all values in the base range of the scalar type. |
| @end cartouche |
| |
| Followed. By default, GNAT uses the interpretation suggested by AI-195, |
| which specifies using the size of the first subtype. |
| However, such an implementation is based on direct binary |
| representations and is therefore target- and endianness-dependent. |
| To address this issue, GNAT also supplies an alternate implementation |
| of the stream attributes @code{Read} and @code{Write}, |
| which uses the target-independent XDR standard representation |
| for scalar types. |
| @cindex XDR representation |
| @cindex @code{Read} attribute |
| @cindex @code{Write} attribute |
| @cindex Stream oriented attributes |
| The XDR implementation is provided as an alternative body of the |
| @code{System.Stream_Attributes} package, in the file |
| @file{s-strxdr.adb} in the GNAT library. |
| There is no @file{s-strxdr.ads} file. |
| In order to install the XDR implementation, do the following: |
| @enumerate |
| @item Replace the default implementation of the |
| @code{System.Stream_Attributes} package with the XDR implementation. |
| For example on a Unix platform issue the commands: |
| @smallexample |
| $ mv s-stratt.adb s-strold.adb |
| $ mv s-strxdr.adb s-stratt.adb |
| @end smallexample |
| |
| @item |
| Rebuild the GNAT run-time library as documented in the |
| @cite{GNAT User's Guide} |
| @end enumerate |
| |
| @unnumberedsec A.1(52): Names of Predefined Numeric Types |
| @sp 1 |
| @cartouche |
| If an implementation provides additional named predefined integer types, |
| then the names should end with @samp{Integer} as in |
| @samp{Long_Integer}. If an implementation provides additional named |
| predefined floating point types, then the names should end with |
| @samp{Float} as in @samp{Long_Float}. |
| @end cartouche |
| Followed. |
| |
| @findex Ada.Characters.Handling |
| @unnumberedsec A.3.2(49): @code{Ada.Characters.Handling} |
| @sp 1 |
| @cartouche |
| If an implementation provides a localized definition of @code{Character} |
| or @code{Wide_Character}, then the effects of the subprograms in |
| @code{Characters.Handling} should reflect the localizations. See also |
| 3.5.2. |
| @end cartouche |
| Followed. GNAT provides no such localized definitions. |
| |
| @cindex Bounded-length strings |
| @unnumberedsec A.4.4(106): Bounded-Length String Handling |
| @sp 1 |
| @cartouche |
| Bounded string objects should not be implemented by implicit pointers |
| and dynamic allocation. |
| @end cartouche |
| Followed. No implicit pointers or dynamic allocation are used. |
| |
| @cindex Random number generation |
| @unnumberedsec A.5.2(46-47): Random Number Generation |
| @sp 1 |
| @cartouche |
| Any storage associated with an object of type @code{Generator} should be |
| reclaimed on exit from the scope of the object. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| If the generator period is sufficiently long in relation to the number |
| of distinct initiator values, then each possible value of |
| @code{Initiator} passed to @code{Reset} should initiate a sequence of |
| random numbers that does not, in a practical sense, overlap the sequence |
| initiated by any other value. If this is not possible, then the mapping |
| between initiator values and generator states should be a rapidly |
| varying function of the initiator value. |
| @end cartouche |
| Followed. The generator period is sufficiently long for the first |
| condition here to hold true. |
| |
| @findex Get_Immediate |
| @unnumberedsec A.10.7(23): @code{Get_Immediate} |
| @sp 1 |
| @cartouche |
| The @code{Get_Immediate} procedures should be implemented with |
| unbuffered input. For a device such as a keyboard, input should be |
| @dfn{available} if a key has already been typed, whereas for a disk |
| file, input should always be available except at end of file. For a file |
| associated with a keyboard-like device, any line-editing features of the |
| underlying operating system should be disabled during the execution of |
| @code{Get_Immediate}. |
| @end cartouche |
| Followed on all targets except VxWorks. For VxWorks, there is no way to |
| provide this functionality that does not result in the input buffer being |
| flushed before the @code{Get_Immediate} call. A special unit |
| @code{Interfaces.Vxworks.IO} is provided that contains routines to enable |
| this functionality. |
| |
| @findex Export |
| @unnumberedsec B.1(39-41): Pragma @code{Export} |
| @sp 1 |
| @cartouche |
| If an implementation supports pragma @code{Export} to a given language, |
| then it should also allow the main subprogram to be written in that |
| language. It should support some mechanism for invoking the elaboration |
| of the Ada library units included in the system, and for invoking the |
| finalization of the environment task. On typical systems, the |
| recommended mechanism is to provide two subprograms whose link names are |
| @code{adainit} and @code{adafinal}. @code{adainit} should contain the |
| elaboration code for library units. @code{adafinal} should contain the |
| finalization code. These subprograms should have no effect the second |
| and subsequent time they are called. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| Automatic elaboration of pre-elaborated packages should be |
| provided when pragma @code{Export} is supported. |
| @end cartouche |
| Followed when the main program is in Ada. If the main program is in a |
| foreign language, then |
| @code{adainit} must be called to elaborate pre-elaborated |
| packages. |
| |
| @sp 1 |
| @cartouche |
| For each supported convention @var{L} other than @code{Intrinsic}, an |
| implementation should support @code{Import} and @code{Export} pragmas |
| for objects of @var{L}-compatible types and for subprograms, and pragma |
| @code{Convention} for @var{L}-eligible types and for subprograms, |
| presuming the other language has corresponding features. Pragma |
| @code{Convention} need not be supported for scalar types. |
| @end cartouche |
| Followed. |
| |
| @cindex Package @code{Interfaces} |
| @findex Interfaces |
| @unnumberedsec B.2(12-13): Package @code{Interfaces} |
| @sp 1 |
| @cartouche |
| For each implementation-defined convention identifier, there should be a |
| child package of package Interfaces with the corresponding name. This |
| package should contain any declarations that would be useful for |
| interfacing to the language (implementation) represented by the |
| convention. Any declarations useful for interfacing to any language on |
| the given hardware architecture should be provided directly in |
| @code{Interfaces}. |
| @end cartouche |
| Followed. An additional package not defined |
| in the Ada 95 Reference Manual is @code{Interfaces.CPP}, used |
| for interfacing to C++. |
| |
| @sp 1 |
| @cartouche |
| An implementation supporting an interface to C, COBOL, or Fortran should |
| provide the corresponding package or packages described in the following |
| clauses. |
| @end cartouche |
| Followed. GNAT provides all the packages described in this section. |
| |
| @cindex C, interfacing with |
| @unnumberedsec B.3(63-71): Interfacing with C |
| @sp 1 |
| @cartouche |
| An implementation should support the following interface correspondences |
| between Ada and C@. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada procedure corresponds to a void-returning C function. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada function corresponds to a non-void C function. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada @code{in} scalar parameter is passed as a scalar argument to a C |
| function. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada @code{in} parameter of an access-to-object type with designated |
| type @var{T} is passed as a @code{@var{t}*} argument to a C function, |
| where @var{t} is the C type corresponding to the Ada type @var{T}. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out} |
| parameter of an elementary type @var{T}, is passed as a @code{@var{t}*} |
| argument to a C function, where @var{t} is the C type corresponding to |
| the Ada type @var{T}. In the case of an elementary @code{out} or |
| @code{in out} parameter, a pointer to a temporary copy is used to |
| preserve by-copy semantics. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada parameter of a record type @var{T}, of any mode, is passed as a |
| @code{@var{t}*} argument to a C function, where @var{t} is the C |
| structure corresponding to the Ada type @var{T}. |
| @end cartouche |
| Followed. This convention may be overridden by the use of the C_Pass_By_Copy |
| pragma, or Convention, or by explicitly specifying the mechanism for a given |
| call using an extended import or export pragma. |
| |
| @sp 1 |
| @cartouche |
| An Ada parameter of an array type with component type @var{T}, of any |
| mode, is passed as a @code{@var{t}*} argument to a C function, where |
| @var{t} is the C type corresponding to the Ada type @var{T}. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada parameter of an access-to-subprogram type is passed as a pointer |
| to a C function whose prototype corresponds to the designated |
| subprogram's specification. |
| @end cartouche |
| Followed. |
| |
| @cindex COBOL, interfacing with |
| @unnumberedsec B.4(95-98): Interfacing with COBOL |
| @sp 1 |
| @cartouche |
| An Ada implementation should support the following interface |
| correspondences between Ada and COBOL@. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of |
| the COBOL type corresponding to @var{T}. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of |
| the corresponding COBOL type. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the |
| COBOL type corresponding to the Ada parameter type; for scalars, a local |
| copy is used if necessary to ensure by-copy semantics. |
| @end cartouche |
| Followed. |
| |
| @cindex Fortran, interfacing with |
| @unnumberedsec B.5(22-26): Interfacing with Fortran |
| @sp 1 |
| @cartouche |
| An Ada implementation should support the following interface |
| correspondences between Ada and Fortran: |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada procedure corresponds to a Fortran subroutine. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada function corresponds to a Fortran function. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada parameter of an elementary, array, or record type @var{T} is |
| passed as a @var{T} argument to a Fortran procedure, where @var{T} is |
| the Fortran type corresponding to the Ada type @var{T}, and where the |
| INTENT attribute of the corresponding dummy argument matches the Ada |
| formal parameter mode; the Fortran implementation's parameter passing |
| conventions are used. For elementary types, a local copy is used if |
| necessary to ensure by-copy semantics. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| An Ada parameter of an access-to-subprogram type is passed as a |
| reference to a Fortran procedure whose interface corresponds to the |
| designated subprogram's specification. |
| @end cartouche |
| Followed. |
| |
| @cindex Machine operations |
| @unnumberedsec C.1(3-5): Access to Machine Operations |
| @sp 1 |
| @cartouche |
| The machine code or intrinsic support should allow access to all |
| operations normally available to assembly language programmers for the |
| target environment, including privileged instructions, if any. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| The interfacing pragmas (see Annex B) should support interface to |
| assembler; the default assembler should be associated with the |
| convention identifier @code{Assembler}. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| If an entity is exported to assembly language, then the implementation |
| should allocate it at an addressable location, and should ensure that it |
| is retained by the linking process, even if not otherwise referenced |
| from the Ada code. The implementation should assume that any call to a |
| machine code or assembler subprogram is allowed to read or update every |
| object that is specified as exported. |
| @end cartouche |
| Followed. |
| |
| @unnumberedsec C.1(10-16): Access to Machine Operations |
| @sp 1 |
| @cartouche |
| The implementation should ensure that little or no overhead is |
| associated with calling intrinsic and machine-code subprograms. |
| @end cartouche |
| Followed for both intrinsics and machine-code subprograms. |
| |
| @sp 1 |
| @cartouche |
| It is recommended that intrinsic subprograms be provided for convenient |
| access to any machine operations that provide special capabilities or |
| efficiency and that are not otherwise available through the language |
| constructs. |
| @end cartouche |
| Followed. A full set of machine operation intrinsic subprograms is provided. |
| |
| @sp 1 |
| @cartouche |
| Atomic read-modify-write operations---e.g.@:, test and set, compare and |
| swap, decrement and test, enqueue/dequeue. |
| @end cartouche |
| Followed on any target supporting such operations. |
| |
| @sp 1 |
| @cartouche |
| Standard numeric functions---e.g.@:, sin, log. |
| @end cartouche |
| Followed on any target supporting such operations. |
| |
| @sp 1 |
| @cartouche |
| String manipulation operations---e.g.@:, translate and test. |
| @end cartouche |
| Followed on any target supporting such operations. |
| |
| @sp 1 |
| @cartouche |
| Vector operations---e.g.@:, compare vector against thresholds. |
| @end cartouche |
| Followed on any target supporting such operations. |
| |
| @sp 1 |
| @cartouche |
| Direct operations on I/O ports. |
| @end cartouche |
| Followed on any target supporting such operations. |
| |
| @cindex Interrupt support |
| @unnumberedsec C.3(28): Interrupt Support |
| @sp 1 |
| @cartouche |
| If the @code{Ceiling_Locking} policy is not in effect, the |
| implementation should provide means for the application to specify which |
| interrupts are to be blocked during protected actions, if the underlying |
| system allows for a finer-grain control of interrupt blocking. |
| @end cartouche |
| Followed. The underlying system does not allow for finer-grain control |
| of interrupt blocking. |
| |
| @cindex Protected procedure handlers |
| @unnumberedsec C.3.1(20-21): Protected Procedure Handlers |
| @sp 1 |
| @cartouche |
| Whenever possible, the implementation should allow interrupt handlers to |
| be called directly by the hardware. |
| @end cartouche |
| @c SGI info: |
| @ignore |
| This is never possible under IRIX, so this is followed by default. |
| @end ignore |
| Followed on any target where the underlying operating system permits |
| such direct calls. |
| |
| @sp 1 |
| @cartouche |
| Whenever practical, violations of any |
| implementation-defined restrictions should be detected before run time. |
| @end cartouche |
| Followed. Compile time warnings are given when possible. |
| |
| @cindex Package @code{Interrupts} |
| @findex Interrupts |
| @unnumberedsec C.3.2(25): Package @code{Interrupts} |
| |
| @sp 1 |
| @cartouche |
| If implementation-defined forms of interrupt handler procedures are |
| supported, such as protected procedures with parameters, then for each |
| such form of a handler, a type analogous to @code{Parameterless_Handler} |
| should be specified in a child package of @code{Interrupts}, with the |
| same operations as in the predefined package Interrupts. |
| @end cartouche |
| Followed. |
| |
| @cindex Pre-elaboration requirements |
| @unnumberedsec C.4(14): Pre-elaboration Requirements |
| @sp 1 |
| @cartouche |
| It is recommended that pre-elaborated packages be implemented in such a |
| way that there should be little or no code executed at run time for the |
| elaboration of entities not already covered by the Implementation |
| Requirements. |
| @end cartouche |
| Followed. Executable code is generated in some cases, e.g.@: loops |
| to initialize large arrays. |
| |
| @unnumberedsec C.5(8): Pragma @code{Discard_Names} |
| |
| @sp 1 |
| @cartouche |
| If the pragma applies to an entity, then the implementation should |
| reduce the amount of storage used for storing names associated with that |
| entity. |
| @end cartouche |
| Followed. |
| |
| @cindex Package @code{Task_Attributes} |
| @findex Task_Attributes |
| @unnumberedsec C.7.2(30): The Package Task_Attributes |
| @sp 1 |
| @cartouche |
| Some implementations are targeted to domains in which memory use at run |
| time must be completely deterministic. For such implementations, it is |
| recommended that the storage for task attributes will be pre-allocated |
| statically and not from the heap. This can be accomplished by either |
| placing restrictions on the number and the size of the task's |
| attributes, or by using the pre-allocated storage for the first @var{N} |
| attribute objects, and the heap for the others. In the latter case, |
| @var{N} should be documented. |
| @end cartouche |
| Not followed. This implementation is not targeted to such a domain. |
| |
| @cindex Locking Policies |
| @unnumberedsec D.3(17): Locking Policies |
| |
| @sp 1 |
| @cartouche |
| The implementation should use names that end with @samp{_Locking} for |
| locking policies defined by the implementation. |
| @end cartouche |
| Followed. A single implementation-defined locking policy is defined, |
| whose name (@code{Inheritance_Locking}) follows this suggestion. |
| |
| @cindex Entry queuing policies |
| @unnumberedsec D.4(16): Entry Queuing Policies |
| @sp 1 |
| @cartouche |
| Names that end with @samp{_Queuing} should be used |
| for all implementation-defined queuing policies. |
| @end cartouche |
| Followed. No such implementation-defined queuing policies exist. |
| |
| @cindex Preemptive abort |
| @unnumberedsec D.6(9-10): Preemptive Abort |
| @sp 1 |
| @cartouche |
| Even though the @code{abort_statement} is included in the list of |
| potentially blocking operations (see 9.5.1), it is recommended that this |
| statement be implemented in a way that never requires the task executing |
| the @code{abort_statement} to block. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| On a multi-processor, the delay associated with aborting a task on |
| another processor should be bounded; the implementation should use |
| periodic polling, if necessary, to achieve this. |
| @end cartouche |
| Followed. |
| |
| @cindex Tasking restrictions |
| @unnumberedsec D.7(21): Tasking Restrictions |
| @sp 1 |
| @cartouche |
| When feasible, the implementation should take advantage of the specified |
| restrictions to produce a more efficient implementation. |
| @end cartouche |
| GNAT currently takes advantage of these restrictions by providing an optimized |
| run time when the Ravenscar profile and the GNAT restricted run time set |
| of restrictions are specified. See pragma @code{Profile (Ravenscar)} and |
| pragma @code{Profile (Restricted)} for more details. |
| |
| @cindex Time, monotonic |
| @unnumberedsec D.8(47-49): Monotonic Time |
| @sp 1 |
| @cartouche |
| When appropriate, implementations should provide configuration |
| mechanisms to change the value of @code{Tick}. |
| @end cartouche |
| Such configuration mechanisms are not appropriate to this implementation |
| and are thus not supported. |
| |
| @sp 1 |
| @cartouche |
| It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} |
| be implemented as transformations of the same time base. |
| @end cartouche |
| Followed. |
| |
| @sp 1 |
| @cartouche |
| It is recommended that the @dfn{best} time base which exists in |
| the underlying system be available to the application through |
| @code{Clock}. @dfn{Best} may mean highest accuracy or largest range. |
| @end cartouche |
| Followed. |
| |
| @cindex Partition communication subsystem |
| @cindex PCS |
| @unnumberedsec E.5(28-29): Partition Communication Subsystem |
| @sp 1 |
| @cartouche |
| Whenever possible, the PCS on the called partition should allow for |
| multiple tasks to call the RPC-receiver with different messages and |
| should allow them to block until the corresponding subprogram body |
| returns. |
| @end cartouche |
| Followed by GLADE, a separately supplied PCS that can be used with |
| GNAT. |
| |
| @sp 1 |
| @cartouche |
| The @code{Write} operation on a stream of type @code{Params_Stream_Type} |
| should raise @code{Storage_Error} if it runs out of space trying to |
| write the @code{Item} into the stream. |
| @end cartouche |
| Followed by GLADE, a separately supplied PCS that can be used with |
| GNAT@. |
| |
| @cindex COBOL support |
| @unnumberedsec F(7): COBOL Support |
| @sp 1 |
| @cartouche |
| If COBOL (respectively, C) is widely supported in the target |
| environment, implementations supporting the Information Systems Annex |
| should provide the child package @code{Interfaces.COBOL} (respectively, |
| @code{Interfaces.C}) specified in Annex B and should support a |
| @code{convention_identifier} of COBOL (respectively, C) in the interfacing |
| pragmas (see Annex B), thus allowing Ada programs to interface with |
| programs written in that language. |
| @end cartouche |
| Followed. |
| |
| @cindex Decimal radix support |
| @unnumberedsec F.1(2): Decimal Radix Support |
| @sp 1 |
| @cartouche |
| Packed decimal should be used as the internal representation for objects |
| of subtype @var{S} when @var{S}'Machine_Radix = 10. |
| @end cartouche |
| Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary |
| representations. |
| |
| @cindex Numerics |
| @unnumberedsec G: Numerics |
| @sp 2 |
| @cartouche |
| If Fortran (respectively, C) is widely supported in the target |
| environment, implementations supporting the Numerics Annex |
| should provide the child package @code{Interfaces.Fortran} (respectively, |
| @code{Interfaces.C}) specified in Annex B and should support a |
| @code{convention_identifier} of Fortran (respectively, C) in the interfacing |
| pragmas (see Annex B), thus allowing Ada programs to interface with |
| programs written in that language. |
| @end cartouche |
| Followed. |
| |
| @cindex Complex types |
| @unnumberedsec G.1.1(56-58): Complex Types |
| @sp 2 |
| @cartouche |
| Because the usual mathematical meaning of multiplication of a complex |
| operand and a real operand is that of the scaling of both components of |
| the former by the latter, an implementation should not perform this |
| operation by first promoting the real operand to complex type and then |
| performing a full complex multiplication. In systems that, in the |
| future, support an Ada binding to IEC 559:1989, the latter technique |
| will not generate the required result when one of the components of the |
| complex operand is infinite. (Explicit multiplication of the infinite |
| component by the zero component obtained during promotion yields a NaN |
| that propagates into the final result.) Analogous advice applies in the |
| case of multiplication of a complex operand and a pure-imaginary |
| operand, and in the case of division of a complex operand by a real or |
| pure-imaginary operand. |
| @end cartouche |
| Not followed. |
| |
| @sp 1 |
| @cartouche |
| Similarly, because the usual mathematical meaning of addition of a |
| complex operand and a real operand is that the imaginary operand remains |
| unchanged, an implementation should not perform this operation by first |
| promoting the real operand to complex type and then performing a full |
| complex addition. In implementations in which the @code{Signed_Zeros} |
| attribute of the component type is @code{True} (and which therefore |
| conform to IEC 559:1989 in regard to the handling of the sign of zero in |
| predefined arithmetic operations), the latter technique will not |
| generate the required result when the imaginary component of the complex |
| operand is a negatively signed zero. (Explicit addition of the negative |
| zero to the zero obtained during promotion yields a positive zero.) |
| Analogous advice applies in the case of addition of a complex operand |
| and a pure-imaginary operand, and in the case of subtraction of a |
| complex operand and a real or pure-imaginary operand. |
| @end cartouche |
| Not followed. |
| |
| @sp 1 |
| @cartouche |
| Implementations in which @code{Real'Signed_Zeros} is @code{True} should |
| attempt to provide a rational treatment of the signs of zero results and |
| result components. As one example, the result of the @code{Argument} |
| function should have the sign of the imaginary component of the |
| parameter @code{X} when the point represented by that parameter lies on |
| the positive real axis; as another, the sign of the imaginary component |
| of the @code{Compose_From_Polar} function should be the same as |
| (respectively, the opposite of) that of the @code{Argument} parameter when that |
| parameter has a value of zero and the @code{Modulus} parameter has a |
| nonnegative (respectively, negative) value. |
| @end cartouche |
| Followed. |
| |
| @cindex Complex elementary functions |
| @unnumberedsec G.1.2(49): Complex Elementary Functions |
| @sp 1 |
| @cartouche |
| Implementations in which @code{Complex_Types.Real'Signed_Zeros} is |
| @code{True} should attempt to provide a rational treatment of the signs |
| of zero results and result components. For example, many of the complex |
| elementary functions have components that are odd functions of one of |
| the parameter components; in these cases, the result component should |
| have the sign of the parameter component at the origin. Other complex |
| elementary functions have zero components whose sign is opposite that of |
| a parameter component at the origin, or is always positive or always |
| negative. |
| @end cartouche |
| Followed. |
| |
| @cindex Accuracy requirements |
| @unnumberedsec G.2.4(19): Accuracy Requirements |
| @sp 1 |
| @cartouche |
| The versions of the forward trigonometric functions without a |
| @code{Cycle} parameter should not be implemented by calling the |
| corresponding version with a @code{Cycle} parameter of |
| @code{2.0*Numerics.Pi}, since this will not provide the required |
| accuracy in some portions of the domain. For the same reason, the |
| version of @code{Log} without a @code{Base} parameter should not be |
| implemented by calling the corresponding version with a @code{Base} |
| parameter of @code{Numerics.e}. |
| @end cartouche |
| Followed. |
| |
| @cindex Complex arithmetic accuracy |
| @cindex Accuracy, complex arithmetic |
| @unnumberedsec G.2.6(15): Complex Arithmetic Accuracy |
| |
| @sp 1 |
| @cartouche |
| The version of the @code{Compose_From_Polar} function without a |
| @code{Cycle} parameter should not be implemented by calling the |
| corresponding version with a @code{Cycle} parameter of |
| @code{2.0*Numerics.Pi}, since this will not provide the required |
| accuracy in some portions of the domain. |
| @end cartouche |
| Followed. |
| |
| @c ----------------------------------------- |
| @node Implementation Defined Characteristics |
| @chapter Implementation Defined Characteristics |
| |
| @noindent |
| In addition to the implementation dependent pragmas and attributes, and |
| the implementation advice, there are a number of other features of Ada |
| 95 that are potentially implementation dependent. These are mentioned |
| throughout the Ada 95 Reference Manual, and are summarized in annex M@. |
| |
| A requirement for conforming Ada compilers is that they provide |
| documentation describing how the implementation deals with each of these |
| issues. In this chapter, you will find each point in annex M listed |
| followed by a description in italic font of how GNAT |
| @c SGI info: |
| @ignore |
| in the ProDev Ada |
| implementation on IRIX 5.3 operating system or greater |
| @end ignore |
| handles the implementation dependence. |
| |
| You can use this chapter as a guide to minimizing implementation |
| dependent features in your programs if portability to other compilers |
| and other operating systems is an important consideration. The numbers |
| in each section below correspond to the paragraph number in the Ada 95 |
| Reference Manual. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{2}. Whether or not each recommendation given in Implementation |
| Advice is followed. See 1.1.2(37). |
| @end cartouche |
| @noindent |
| @xref{Implementation Advice}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{3}. Capacity limitations of the implementation. See 1.1.3(3). |
| @end cartouche |
| @noindent |
| The complexity of programs that can be processed is limited only by the |
| total amount of available virtual memory, and disk space for the |
| generated object files. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{4}. Variations from the standard that are impractical to avoid |
| given the implementation's execution environment. See 1.1.3(6). |
| @end cartouche |
| @noindent |
| There are no variations from the standard. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{5}. Which @code{code_statement}s cause external |
| interactions. See 1.1.3(10). |
| @end cartouche |
| @noindent |
| Any @code{code_statement} can potentially cause external interactions. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{6}. The coded representation for the text of an Ada |
| program. See 2.1(4). |
| @end cartouche |
| @noindent |
| See separate section on source representation. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{7}. The control functions allowed in comments. See 2.1(14). |
| @end cartouche |
| @noindent |
| See separate section on source representation. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{8}. The representation for an end of line. See 2.2(2). |
| @end cartouche |
| @noindent |
| See separate section on source representation. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{9}. Maximum supported line length and lexical element |
| length. See 2.2(15). |
| @end cartouche |
| @noindent |
| The maximum line length is 255 characters an the maximum length of a |
| lexical element is also 255 characters. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{10}. Implementation defined pragmas. See 2.8(14). |
| @end cartouche |
| @noindent |
| |
| @xref{Implementation Defined Pragmas}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{11}. Effect of pragma @code{Optimize}. See 2.8(27). |
| @end cartouche |
| @noindent |
| Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} |
| parameter, checks that the optimization flag is set, and aborts if it is |
| not. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{12}. The sequence of characters of the value returned by |
| @code{@var{S}'Image} when some of the graphic characters of |
| @code{@var{S}'Wide_Image} are not defined in @code{Character}. See |
| 3.5(37). |
| @end cartouche |
| @noindent |
| The sequence of characters is as defined by the wide character encoding |
| method used for the source. See section on source representation for |
| further details. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{13}. The predefined integer types declared in |
| @code{Standard}. See 3.5.4(25). |
| @end cartouche |
| @noindent |
| @table @code |
| @item Short_Short_Integer |
| 8 bit signed |
| @item Short_Integer |
| (Short) 16 bit signed |
| @item Integer |
| 32 bit signed |
| @item Long_Integer |
| 64 bit signed (Alpha OpenVMS only) |
| 32 bit signed (all other targets) |
| @item Long_Long_Integer |
| 64 bit signed |
| @end table |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{14}. Any nonstandard integer types and the operators defined |
| for them. See 3.5.4(26). |
| @end cartouche |
| @noindent |
| There are no nonstandard integer types. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{15}. Any nonstandard real types and the operators defined for |
| them. See 3.5.6(8). |
| @end cartouche |
| @noindent |
| There are no nonstandard real types. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{16}. What combinations of requested decimal precision and range |
| are supported for floating point types. See 3.5.7(7). |
| @end cartouche |
| @noindent |
| The precision and range is as defined by the IEEE standard. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{17}. The predefined floating point types declared in |
| @code{Standard}. See 3.5.7(16). |
| @end cartouche |
| @noindent |
| @table @code |
| @item Short_Float |
| 32 bit IEEE short |
| @item Float |
| (Short) 32 bit IEEE short |
| @item Long_Float |
| 64 bit IEEE long |
| @item Long_Long_Float |
| 64 bit IEEE long (80 bit IEEE long on x86 processors) |
| @end table |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{18}. The small of an ordinary fixed point type. See 3.5.9(8). |
| @end cartouche |
| @noindent |
| @code{Fine_Delta} is 2**(@minus{}63) |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{19}. What combinations of small, range, and digits are |
| supported for fixed point types. See 3.5.9(10). |
| @end cartouche |
| @noindent |
| Any combinations are permitted that do not result in a small less than |
| @code{Fine_Delta} and do not result in a mantissa larger than 63 bits. |
| If the mantissa is larger than 53 bits on machines where Long_Long_Float |
| is 64 bits (true of all architectures except ia32), then the output from |
| Text_IO is accurate to only 53 bits, rather than the full mantissa. This |
| is because floating-point conversions are used to convert fixed point. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{20}. The result of @code{Tags.Expanded_Name} for types declared |
| within an unnamed @code{block_statement}. See 3.9(10). |
| @end cartouche |
| @noindent |
| Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a |
| decimal integer are allocated. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{21}. Implementation-defined attributes. See 4.1.4(12). |
| @end cartouche |
| @noindent |
| @xref{Implementation Defined Attributes}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{22}. Any implementation-defined time types. See 9.6(6). |
| @end cartouche |
| @noindent |
| There are no implementation-defined time types. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{23}. The time base associated with relative delays. |
| @end cartouche |
| @noindent |
| See 9.6(20). The time base used is that provided by the C library |
| function @code{gettimeofday}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{24}. The time base of the type @code{Calendar.Time}. See |
| 9.6(23). |
| @end cartouche |
| @noindent |
| The time base used is that provided by the C library function |
| @code{gettimeofday}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{25}. The time zone used for package @code{Calendar} |
| operations. See 9.6(24). |
| @end cartouche |
| @noindent |
| The time zone used by package @code{Calendar} is the current system time zone |
| setting for local time, as accessed by the C library function |
| @code{localtime}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{26}. Any limit on @code{delay_until_statements} of |
| @code{select_statements}. See 9.6(29). |
| @end cartouche |
| @noindent |
| There are no such limits. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{27}. Whether or not two non overlapping parts of a composite |
| object are independently addressable, in the case where packing, record |
| layout, or @code{Component_Size} is specified for the object. See |
| 9.10(1). |
| @end cartouche |
| @noindent |
| Separate components are independently addressable if they do not share |
| overlapping storage units. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{28}. The representation for a compilation. See 10.1(2). |
| @end cartouche |
| @noindent |
| A compilation is represented by a sequence of files presented to the |
| compiler in a single invocation of the @code{gcc} command. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{29}. Any restrictions on compilations that contain multiple |
| compilation_units. See 10.1(4). |
| @end cartouche |
| @noindent |
| No single file can contain more than one compilation unit, but any |
| sequence of files can be presented to the compiler as a single |
| compilation. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{30}. The mechanisms for creating an environment and for adding |
| and replacing compilation units. See 10.1.4(3). |
| @end cartouche |
| @noindent |
| See separate section on compilation model. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{31}. The manner of explicitly assigning library units to a |
| partition. See 10.2(2). |
| @end cartouche |
| @noindent |
| If a unit contains an Ada main program, then the Ada units for the partition |
| are determined by recursive application of the rules in the Ada Reference |
| Manual section 10.2(2-6). In other words, the Ada units will be those that |
| are needed by the main program, and then this definition of need is applied |
| recursively to those units, and the partition contains the transitive |
| closure determined by this relationship. In short, all the necessary units |
| are included, with no need to explicitly specify the list. If additional |
| units are required, e.g.@: by foreign language units, then all units must be |
| mentioned in the context clause of one of the needed Ada units. |
| |
| If the partition contains no main program, or if the main program is in |
| a language other than Ada, then GNAT |
| provides the binder options @code{-z} and @code{-n} respectively, and in |
| this case a list of units can be explicitly supplied to the binder for |
| inclusion in the partition (all units needed by these units will also |
| be included automatically). For full details on the use of these |
| options, refer to the @cite{GNAT User's Guide} sections on Binding |
| and Linking. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{32}. The implementation-defined means, if any, of specifying |
| which compilation units are needed by a given compilation unit. See |
| 10.2(2). |
| @end cartouche |
| @noindent |
| The units needed by a given compilation unit are as defined in |
| the Ada Reference Manual section 10.2(2-6). There are no |
| implementation-defined pragmas or other implementation-defined |
| means for specifying needed units. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{33}. The manner of designating the main subprogram of a |
| partition. See 10.2(7). |
| @end cartouche |
| @noindent |
| The main program is designated by providing the name of the |
| corresponding @file{ALI} file as the input parameter to the binder. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{34}. The order of elaboration of @code{library_items}. See |
| 10.2(18). |
| @end cartouche |
| @noindent |
| The first constraint on ordering is that it meets the requirements of |
| chapter 10 of the Ada 95 Reference Manual. This still leaves some |
| implementation dependent choices, which are resolved by first |
| elaborating bodies as early as possible (i.e.@: in preference to specs |
| where there is a choice), and second by evaluating the immediate with |
| clauses of a unit to determine the probably best choice, and |
| third by elaborating in alphabetical order of unit names |
| where a choice still remains. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{35}. Parameter passing and function return for the main |
| subprogram. See 10.2(21). |
| @end cartouche |
| @noindent |
| The main program has no parameters. It may be a procedure, or a function |
| returning an integer type. In the latter case, the returned integer |
| value is the return code of the program (overriding any value that |
| may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{36}. The mechanisms for building and running partitions. See |
| 10.2(24). |
| @end cartouche |
| @noindent |
| GNAT itself supports programs with only a single partition. The GNATDIST |
| tool provided with the GLADE package (which also includes an implementation |
| of the PCS) provides a completely flexible method for building and running |
| programs consisting of multiple partitions. See the separate GLADE manual |
| for details. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{37}. The details of program execution, including program |
| termination. See 10.2(25). |
| @end cartouche |
| @noindent |
| See separate section on compilation model. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{38}. The semantics of any non-active partitions supported by the |
| implementation. See 10.2(28). |
| @end cartouche |
| @noindent |
| Passive partitions are supported on targets where shared memory is |
| provided by the operating system. See the GLADE reference manual for |
| further details. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{39}. The information returned by @code{Exception_Message}. See |
| 11.4.1(10). |
| @end cartouche |
| @noindent |
| Exception message returns the null string unless a specific message has |
| been passed by the program. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{40}. The result of @code{Exceptions.Exception_Name} for types |
| declared within an unnamed @code{block_statement}. See 11.4.1(12). |
| @end cartouche |
| @noindent |
| Blocks have implementation defined names of the form @code{B@var{nnn}} |
| where @var{nnn} is an integer. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{41}. The information returned by |
| @code{Exception_Information}. See 11.4.1(13). |
| @end cartouche |
| @noindent |
| @code{Exception_Information} returns a string in the following format: |
| |
| @smallexample |
| @emph{Exception_Name:} nnnnn |
| @emph{Message:} mmmmm |
| @emph{PID:} ppp |
| @emph{Call stack traceback locations:} |
| 0xhhhh 0xhhhh 0xhhhh ... 0xhhh |
| @end smallexample |
| |
| @noindent |
| where |
| |
| @itemize @bullet |
| @item |
| @code{nnnn} is the fully qualified name of the exception in all upper |
| case letters. This line is always present. |
| |
| @item |
| @code{mmmm} is the message (this line present only if message is non-null) |
| |
| @item |
| @code{ppp} is the Process Id value as a decimal integer (this line is |
| present only if the Process Id is nonzero). Currently we are |
| not making use of this field. |
| |
| @item |
| The Call stack traceback locations line and the following values |
| are present only if at least one traceback location was recorded. |
| The values are given in C style format, with lower case letters |
| for a-f, and only as many digits present as are necessary. |
| @end itemize |
| |
| @noindent |
| The line terminator sequence at the end of each line, including |
| the last line is a single @code{LF} character (@code{16#0A#}). |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{42}. Implementation-defined check names. See 11.5(27). |
| @end cartouche |
| @noindent |
| No implementation-defined check names are supported. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{43}. The interpretation of each aspect of representation. See |
| 13.1(20). |
| @end cartouche |
| @noindent |
| See separate section on data representations. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{44}. Any restrictions placed upon representation items. See |
| 13.1(20). |
| @end cartouche |
| @noindent |
| See separate section on data representations. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{45}. The meaning of @code{Size} for indefinite subtypes. See |
| 13.3(48). |
| @end cartouche |
| @noindent |
| Size for an indefinite subtype is the maximum possible size, except that |
| for the case of a subprogram parameter, the size of the parameter object |
| is the actual size. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{46}. The default external representation for a type tag. See |
| 13.3(75). |
| @end cartouche |
| @noindent |
| The default external representation for a type tag is the fully expanded |
| name of the type in upper case letters. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{47}. What determines whether a compilation unit is the same in |
| two different partitions. See 13.3(76). |
| @end cartouche |
| @noindent |
| A compilation unit is the same in two different partitions if and only |
| if it derives from the same source file. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{48}. Implementation-defined components. See 13.5.1(15). |
| @end cartouche |
| @noindent |
| The only implementation defined component is the tag for a tagged type, |
| which contains a pointer to the dispatching table. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit |
| ordering. See 13.5.3(5). |
| @end cartouche |
| @noindent |
| @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this |
| implementation, so no non-default bit ordering is supported. The default |
| bit ordering corresponds to the natural endianness of the target architecture. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{50}. The contents of the visible part of package @code{System} |
| and its language-defined children. See 13.7(2). |
| @end cartouche |
| @noindent |
| See the definition of these packages in files @file{system.ads} and |
| @file{s-stoele.ads}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{51}. The contents of the visible part of package |
| @code{System.Machine_Code}, and the meaning of |
| @code{code_statements}. See 13.8(7). |
| @end cartouche |
| @noindent |
| See the definition and documentation in file @file{s-maccod.ads}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{52}. The effect of unchecked conversion. See 13.9(11). |
| @end cartouche |
| @noindent |
| Unchecked conversion between types of the same size |
| results in an uninterpreted transmission of the bits from one type |
| to the other. If the types are of unequal sizes, then in the case of |
| discrete types, a shorter source is first zero or sign extended as |
| necessary, and a shorter target is simply truncated on the left. |
| For all non-discrete types, the source is first copied if necessary |
| to ensure that the alignment requirements of the target are met, then |
| a pointer is constructed to the source value, and the result is obtained |
| by dereferencing this pointer after converting it to be a pointer to the |
| target type. Unchecked conversions where the target subtype is an |
| unconstrained array are not permitted. If the target alignment is |
| greater than the source alignment, then a copy of the result is |
| made with appropriate alignment |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{53}. The manner of choosing a storage pool for an access type |
| when @code{Storage_Pool} is not specified for the type. See 13.11(17). |
| @end cartouche |
| @noindent |
| There are 3 different standard pools used by the compiler when |
| @code{Storage_Pool} is not specified depending whether the type is local |
| to a subprogram or defined at the library level and whether |
| @code{Storage_Size}is specified or not. See documentation in the runtime |
| library units @code{System.Pool_Global}, @code{System.Pool_Size} and |
| @code{System.Pool_Local} in files @file{s-poosiz.ads}, |
| @file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the |
| default pools used. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{54}. Whether or not the implementation provides user-accessible |
| names for the standard pool type(s). See 13.11(17). |
| @end cartouche |
| @noindent |
| |
| See documentation in the sources of the run time mentioned in paragraph |
| @strong{53} . All these pools are accessible by means of @code{with}'ing |
| these units. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{55}. The meaning of @code{Storage_Size}. See 13.11(18). |
| @end cartouche |
| @noindent |
| @code{Storage_Size} is measured in storage units, and refers to the |
| total space available for an access type collection, or to the primary |
| stack space for a task. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{56}. Implementation-defined aspects of storage pools. See |
| 13.11(22). |
| @end cartouche |
| @noindent |
| See documentation in the sources of the run time mentioned in paragraph |
| @strong{53} for details on GNAT-defined aspects of storage pools. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{57}. The set of restrictions allowed in a pragma |
| @code{Restrictions}. See 13.12(7). |
| @end cartouche |
| @noindent |
| All RM defined Restriction identifiers are implemented. The following |
| additional restriction identifiers are provided. There are two separate |
| lists of implementation dependent restriction identifiers. The first |
| set requires consistency throughout a partition (in other words, if the |
| restriction identifier is used for any compilation unit in the partition, |
| then all compilation units in the partition must obey the restriction. |
| |
| @table @code |
| |
| @item Simple_Barriers |
| @findex Simple_Barriers |
| This restriction ensures at compile time that barriers in entry declarations |
| for protected types are restricted to either static boolean expressions or |
| references to simple boolean variables defined in the private part of the |
| protected type. No other form of entry barriers is permitted. This is one |
| of the restrictions of the Ravenscar profile for limited tasking (see also |
| pragma @code{Profile (Ravenscar)}). |
| |
| @item Max_Entry_Queue_Length => Expr |
| @findex Max_Entry_Queue_Length |
| This restriction is a declaration that any protected entry compiled in |
| the scope of the restriction has at most the specified number of |
| tasks waiting on the entry |
| at any one time, and so no queue is required. This restriction is not |
| checked at compile time. A program execution is erroneous if an attempt |
| is made to queue more than the specified number of tasks on such an entry. |
| |
| @item No_Calendar |
| @findex No_Calendar |
| This restriction ensures at compile time that there is no implicit or |
| explicit dependence on the package @code{Ada.Calendar}. |
| |
| @item No_Direct_Boolean_Operators |
| @findex No_Direct_Boolean_Operators |
| This restriction ensures that no logical (and/or/xor) or comparison |
| operators are used on operands of type Boolean (or any type derived |
| from Boolean). This is intended for use in safety critical programs |
| where the certification protocol requires the use of short-circuit |
| (and then, or else) forms for all composite boolean operations. |
| |
| @item No_Dispatching_Calls |
| @findex No_Dispatching_Calls |
| This restriction ensures at compile time that the code generated by the |
| compiler involves no dispatching calls. The use of this restriction allows the |
| safe use of record extensions and membership tests and ensures that the code |
| contains no indirect calls through a dispatching mechanism. (Note that this |
| includes internally-generated calls created by the compiler, for example in |
| the implementation of the predefined attributes on class-wide objects.) The |
| membership test is allowed in the presence of this restriction, because its |
| implementation requires no dispatching. The following example indicates |
| constructs that violate this restriction. |
| |
| @smallexample |
| package Pkg is |
| type T is tagged record |
| Data : Natural; |
| end record; |
| procedure P (X : T); |
| |
| type DT is new T with record |
| More_Data : Natural; |
| end record; |
| procedure Q (X : DT); |
| end Pkg; |
| |
| with Pkg; use Pkg; |
| procedure Example is |
| procedure Test (O : T'Class) is |
| N : Natural := O'Size; -- Error: Dispatching call |
| begin |
| if O in DT'Class then -- OK : Membership test |
| Q (DT (O)); -- OK : Type conversion plus direct call |
| else |
| P (O); -- Error: Dispatching call |
| end if; |
| end Test; |
| |
| Obj : DT; |
| begin |
| P (Obj); -- OK : Direct call |
| P (T (Obj)); -- OK : Type conversion plus direct call |
| P (T'Class (Obj)); -- Error: Dispatching call |
| |
| Test (Obj); -- OK : Type conversion |
| |
| if Obj in T'Class then -- OK : Membership test |
| null; |
| end if; |
| end Example; |
| @end smallexample |
| |
| @item No_Dynamic_Attachment |
| @findex No_Dynamic_Attachment |
| This restriction ensures that there is no call to any of the operations |
| defined in package Ada.Interrupts. |
| |
| @item No_Enumeration_Maps |
| @findex No_Enumeration_Maps |
| This restriction ensures at compile time that no operations requiring |
| enumeration maps are used (that is Image and Value attributes applied |
| to enumeration types). |
| |
| @item No_Entry_Calls_In_Elaboration_Code |
| @findex No_Entry_Calls_In_Elaboration_Code |
| This restriction ensures at compile time that no task or protected entry |
| calls are made during elaboration code. As a result of the use of this |
| restriction, the compiler can assume that no code past an accept statement |
| in a task can be executed at elaboration time. |
| |
| @item No_Exception_Handlers |
| @findex No_Exception_Handlers |
| This restriction ensures at compile time that there are no explicit |
| exception handlers. It also indicates that no exception propagation will |
| be provided. In this mode, exceptions may be raised but will result in |
| an immediate call to the last chance handler, a routine that the user |
| must define with the following profile: |
| |
| procedure Last_Chance_Handler |
| (Source_Location : System.Address; Line : Integer); |
| pragma Export (C, Last_Chance_Handler, |
| "__gnat_last_chance_handler"); |
| |
| The parameter is a C null-terminated string representing a message to be |
| associated with the exception (typically the source location of the raise |
| statement generated by the compiler). The Line parameter when nonzero |
| represents the line number in the source program where the raise occurs. |
| |
| @item No_Exception_Streams |
| @findex No_Exception_Streams |
| This restriction ensures at compile time that no stream operations for |
| types Exception_Id or Exception_Occurrence are used. This also makes it |
| impossible to pass exceptions to or from a partition with this restriction |
| in a distributed environment. If this exception is active, then the generated |
| code is simplified by omitting the otherwise-required global registration |
| of exceptions when they are declared. |
| |
| @item No_Implicit_Conditionals |
| @findex No_Implicit_Conditionals |
| This restriction ensures that the generated code does not contain any |
| implicit conditionals, either by modifying the generated code where possible, |
| or by rejecting any construct that would otherwise generate an implicit |
| conditional. Note that this check does not include run time constraint |
| checks, which on some targets may generate implicit conditionals as |
| well. To control the latter, constraint checks can be suppressed in the |
| normal manner. Constructs generating implicit conditionals include comparisons |
| of composite objects and the Max/Min attributes. |
| |
| @item No_Implicit_Dynamic_Code |
| @findex No_Implicit_Dynamic_Code |
| This restriction prevents the compiler from building ``trampolines''. |
| This is a structure that is built on the stack and contains dynamic |
| code to be executed at run time. A trampoline is needed to indirectly |
| address a nested subprogram (that is a subprogram that is not at the |
| library level). The restriction prevents the use of any of the |
| attributes @code{Address}, @code{Access} or @code{Unrestricted_Access} |
| being applied to a subprogram that is not at the library level. |
| |
| @item No_Implicit_Loops |
| @findex No_Implicit_Loops |
| This restriction ensures that the generated code does not contain any |
| implicit @code{for} loops, either by modifying |
| the generated code where possible, |
| or by rejecting any construct that would otherwise generate an implicit |
| @code{for} loop. |
| |
| @item No_Initialize_Scalars |
| @findex No_Initialize_Scalars |
| This restriction ensures that no unit in the partition is compiled with |
| pragma Initialize_Scalars. This allows the generation of more efficient |
| code, and in particular eliminates dummy null initialization routines that |
| are otherwise generated for some record and array types. |
| |
| @item No_Local_Protected_Objects |
| @findex No_Local_Protected_Objects |
| This restriction ensures at compile time that protected objects are |
| only declared at the library level. |
| |
| @item No_Protected_Type_Allocators |
| @findex No_Protected_Type_Allocators |
| This restriction ensures at compile time that there are no allocator |
| expressions that attempt to allocate protected objects. |
| |
| @item No_Secondary_Stack |
| @findex No_Secondary_Stack |
| This restriction ensures at compile time that the generated code does not |
| contain any reference to the secondary stack. The secondary stack is used |
| to implement functions returning unconstrained objects (arrays or records) |
| on some targets. |
| |
| @item No_Select_Statements |
| @findex No_Select_Statements |
| This restriction ensures at compile time no select statements of any kind |
| are permitted, that is the keyword @code{select} may not appear. |
| This is one of the restrictions of the Ravenscar |
| profile for limited tasking (see also pragma @code{Profile (Ravenscar)}). |
| |
| @item No_Standard_Storage_Pools |
| @findex No_Standard_Storage_Pools |
| This restriction ensures at compile time that no access types |
| use the standard default storage pool. Any access type declared must |
| have an explicit Storage_Pool attribute defined specifying a |
| user-defined storage pool. |
| |
| @item No_Streams |
| @findex No_Streams |
| This restriction ensures at compile/bind time that there are no |
| stream objects created (and therefore no actual stream operations). |
| This restriction does not forbid dependences on the package |
| @code{Ada.Streams}. So it is permissible to with |
| @code{Ada.Streams} (or another package that does so itself) |
| as long as no actual stream objects are created. |
| |
| @item No_Task_Attributes_Package |
| @findex No_Task_Attributes_Package |
| This restriction ensures at compile time that there are no implicit or |
| explicit dependencies on the package @code{Ada.Task_Attributes}. |
| |
| @item No_Task_Termination |
| @findex No_Task_Termination |
| This restriction ensures at compile time that no terminate alternatives |
| appear in any task body. |
| |
| @item No_Tasking |
| @findex No_Tasking |
| This restriction prevents the declaration of tasks or task types throughout |
| the partition. It is similar in effect to the use of @code{Max_Tasks => 0} |
| except that violations are caught at compile time and cause an error message |
| to be output either by the compiler or binder. |
| |
| @item Static_Priorities |
| @findex Static_Priorities |
| This restriction ensures at compile time that all priority expressions |
| are static, and that there are no dependencies on the package |
| @code{Ada.Dynamic_Priorities}. |
| |
| @item Static_Storage_Size |
| @findex Static_Storage_Size |
| This restriction ensures at compile time that any expression appearing |
| in a Storage_Size pragma or attribute definition clause is static. |
| |
| @end table |
| |
| @noindent |
| The second set of implementation dependent restriction identifiers |
| does not require partition-wide consistency. |
| The restriction may be enforced for a single |
| compilation unit without any effect on any of the |
| other compilation units in the partition. |
| |
| @table @code |
| |
| @item No_Elaboration_Code |
| @findex No_Elaboration_Code |
| This restriction ensures at compile time that no elaboration code is |
| generated. Note that this is not the same condition as is enforced |
| by pragma @code{Preelaborate}. There are cases in which pragma |
| @code{Preelaborate} still permits code to be generated (e.g.@: code |
| to initialize a large array to all zeroes), and there are cases of units |
| which do not meet the requirements for pragma @code{Preelaborate}, |
| but for which no elaboration code is generated. Generally, it is |
| the case that preelaborable units will meet the restrictions, with |
| the exception of large aggregates initialized with an others_clause, |
| and exception declarations (which generate calls to a run-time |
| registry procedure). This restriction is enforced on |
| a unit by unit basis, it need not be obeyed consistently |
| throughout a partition. |
| |
| It is not possible to precisely document |
| the constructs which are compatible with this restriction, since, |
| unlike most other restrictions, this is not a restriction on the |
| source code, but a restriction on the generated object code. For |
| example, if the source contains a declaration: |
| |
| @smallexample |
| Val : constant Integer := X; |
| @end smallexample |
| |
| @noindent |
| where X is not a static constant, it may be possible, depending |
| on complex optimization circuitry, for the compiler to figure |
| out the value of X at compile time, in which case this initialization |
| can be done by the loader, and requires no initialization code. It |
| is not possible to document the precise conditions under which the |
| optimizer can figure this out. |
| |
| @item No_Entry_Queue |
| @findex No_Entry_Queue |
| This restriction is a declaration that any protected entry compiled in |
| the scope of the restriction has at most one task waiting on the entry |
| at any one time, and so no queue is required. This restriction is not |
| checked at compile time. A program execution is erroneous if an attempt |
| is made to queue a second task on such an entry. |
| |
| @item No_Implementation_Attributes |
| @findex No_Implementation_Attributes |
| This restriction checks at compile time that no GNAT-defined attributes |
| are present. With this restriction, the only attributes that can be used |
| are those defined in the Ada 95 Reference Manual. |
| |
| @item No_Implementation_Pragmas |
| @findex No_Implementation_Pragmas |
| This restriction checks at compile time that no GNAT-defined pragmas |
| are present. With this restriction, the only pragmas that can be used |
| are those defined in the Ada 95 Reference Manual. |
| |
| @item No_Implementation_Restrictions |
| @findex No_Implementation_Restrictions |
| This restriction checks at compile time that no GNAT-defined restriction |
| identifiers (other than @code{No_Implementation_Restrictions} itself) |
| are present. With this restriction, the only other restriction identifiers |
| that can be used are those defined in the Ada 95 Reference Manual. |
| |
| @item No_Wide_Characters |
| @findex No_Wide_Characters |
| This restriction ensures at compile time that no uses of the types |
| @code{Wide_Character} or @code{Wide_String} or corresponding wide |
| wide types |
| appear, and that no wide or wide wide string or character literals |
| appear in the program (that is literals representing characters not in |
| type @code{Character}. |
| |
| @end table |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{58}. The consequences of violating limitations on |
| @code{Restrictions} pragmas. See 13.12(9). |
| @end cartouche |
| @noindent |
| Restrictions that can be checked at compile time result in illegalities |
| if violated. Currently there are no other consequences of violating |
| restrictions. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{59}. The representation used by the @code{Read} and |
| @code{Write} attributes of elementary types in terms of stream |
| elements. See 13.13.2(9). |
| @end cartouche |
| @noindent |
| The representation is the in-memory representation of the base type of |
| the type, using the number of bits corresponding to the |
| @code{@var{type}'Size} value, and the natural ordering of the machine. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{60}. The names and characteristics of the numeric subtypes |
| declared in the visible part of package @code{Standard}. See A.1(3). |
| @end cartouche |
| @noindent |
| See items describing the integer and floating-point types supported. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{61}. The accuracy actually achieved by the elementary |
| functions. See A.5.1(1). |
| @end cartouche |
| @noindent |
| The elementary functions correspond to the functions available in the C |
| library. Only fast math mode is implemented. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{62}. The sign of a zero result from some of the operators or |
| functions in @code{Numerics.Generic_Elementary_Functions}, when |
| @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46). |
| @end cartouche |
| @noindent |
| The sign of zeroes follows the requirements of the IEEE 754 standard on |
| floating-point. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{63}. The value of |
| @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27). |
| @end cartouche |
| @noindent |
| Maximum image width is 649, see library file @file{a-numran.ads}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{64}. The value of |
| @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27). |
| @end cartouche |
| @noindent |
| Maximum image width is 80, see library file @file{a-nudira.ads}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{65}. The algorithms for random number generation. See |
| A.5.2(32). |
| @end cartouche |
| @noindent |
| The algorithm is documented in the source files @file{a-numran.ads} and |
| @file{a-numran.adb}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{66}. The string representation of a random number generator's |
| state. See A.5.2(38). |
| @end cartouche |
| @noindent |
| See the documentation contained in the file @file{a-numran.adb}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{67}. The minimum time interval between calls to the |
| time-dependent Reset procedure that are guaranteed to initiate different |
| random number sequences. See A.5.2(45). |
| @end cartouche |
| @noindent |
| The minimum period between reset calls to guarantee distinct series of |
| random numbers is one microsecond. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{68}. The values of the @code{Model_Mantissa}, |
| @code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, |
| @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics |
| Annex is not supported. See A.5.3(72). |
| @end cartouche |
| @noindent |
| See the source file @file{ttypef.ads} for the values of all numeric |
| attributes. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{69}. Any implementation-defined characteristics of the |
| input-output packages. See A.7(14). |
| @end cartouche |
| @noindent |
| There are no special implementation defined characteristics for these |
| packages. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See |
| A.9(10). |
| @end cartouche |
| @noindent |
| All type representations are contiguous, and the @code{Buffer_Size} is |
| the value of @code{@var{type}'Size} rounded up to the next storage unit |
| boundary. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{71}. External files for standard input, standard output, and |
| standard error See A.10(5). |
| @end cartouche |
| @noindent |
| These files are mapped onto the files provided by the C streams |
| libraries. See source file @file{i-cstrea.ads} for further details. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{72}. The accuracy of the value produced by @code{Put}. See |
| A.10.9(36). |
| @end cartouche |
| @noindent |
| If more digits are requested in the output than are represented by the |
| precision of the value, zeroes are output in the corresponding least |
| significant digit positions. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and |
| @code{Command_Name}. See A.15(1). |
| @end cartouche |
| @noindent |
| These are mapped onto the @code{argv} and @code{argc} parameters of the |
| main program in the natural manner. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{74}. Implementation-defined convention names. See B.1(11). |
| @end cartouche |
| @noindent |
| The following convention names are supported |
| |
| @table @code |
| @item Ada |
| Ada |
| @item Assembler |
| Assembly language |
| @item Asm |
| Synonym for Assembler |
| @item Assembly |
| Synonym for Assembler |
| @item C |
| C |
| @item C_Pass_By_Copy |
| Allowed only for record types, like C, but also notes that record |
| is to be passed by copy rather than reference. |
| @item COBOL |
| COBOL |
| @item CPP |
| C++ |
| @item Default |
| Treated the same as C |
| @item External |
| Treated the same as C |
| @item Fortran |
| Fortran |
| @item Intrinsic |
| For support of pragma @code{Import} with convention Intrinsic, see |
| separate section on Intrinsic Subprograms. |
| @item Stdcall |
| Stdcall (used for Windows implementations only). This convention correspond |
| to the WINAPI (previously called Pascal convention) C/C++ convention under |
| Windows. A function with this convention cleans the stack before exit. |
| @item DLL |
| Synonym for Stdcall |
| @item Win32 |
| Synonym for Stdcall |
| @item Stubbed |
| Stubbed is a special convention used to indicate that the body of the |
| subprogram will be entirely ignored. Any call to the subprogram |
| is converted into a raise of the @code{Program_Error} exception. If a |
| pragma @code{Import} specifies convention @code{stubbed} then no body need |
| be present at all. This convention is useful during development for the |
| inclusion of subprograms whose body has not yet been written. |
| |
| @end table |
| @noindent |
| In addition, all otherwise unrecognized convention names are also |
| treated as being synonymous with convention C@. In all implementations |
| except for VMS, use of such other names results in a warning. In VMS |
| implementations, these names are accepted silently. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{75}. The meaning of link names. See B.1(36). |
| @end cartouche |
| @noindent |
| Link names are the actual names used by the linker. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{76}. The manner of choosing link names when neither the link |
| name nor the address of an imported or exported entity is specified. See |
| B.1(36). |
| @end cartouche |
| @noindent |
| The default linker name is that which would be assigned by the relevant |
| external language, interpreting the Ada name as being in all lower case |
| letters. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{77}. The effect of pragma @code{Linker_Options}. See B.1(37). |
| @end cartouche |
| @noindent |
| The string passed to @code{Linker_Options} is presented uninterpreted as |
| an argument to the link command, unless it contains Ascii.NUL characters. |
| NUL characters if they appear act as argument separators, so for example |
| |
| @smallexample @c ada |
| pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef"); |
| @end smallexample |
| |
| @noindent |
| causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the |
| linker. The order of linker options is preserved for a given unit. The final |
| list of options passed to the linker is in reverse order of the elaboration |
| order. For example, linker options fo a body always appear before the options |
| from the corresponding package spec. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{78}. The contents of the visible part of package |
| @code{Interfaces} and its language-defined descendants. See B.2(1). |
| @end cartouche |
| @noindent |
| See files with prefix @file{i-} in the distributed library. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{79}. Implementation-defined children of package |
| @code{Interfaces}. The contents of the visible part of package |
| @code{Interfaces}. See B.2(11). |
| @end cartouche |
| @noindent |
| See files with prefix @file{i-} in the distributed library. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{80}. The types @code{Floating}, @code{Long_Floating}, |
| @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and |
| @code{COBOL_Character}; and the initialization of the variables |
| @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in |
| @code{Interfaces.COBOL}. See B.4(50). |
| @end cartouche |
| @noindent |
| @table @code |
| @item Floating |
| Float |
| @item Long_Floating |
| (Floating) Long_Float |
| @item Binary |
| Integer |
| @item Long_Binary |
| Long_Long_Integer |
| @item Decimal_Element |
| Character |
| @item COBOL_Character |
| Character |
| @end table |
| |
| @noindent |
| For initialization, see the file @file{i-cobol.ads} in the distributed library. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{81}. Support for access to machine instructions. See C.1(1). |
| @end cartouche |
| @noindent |
| See documentation in file @file{s-maccod.ads} in the distributed library. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{82}. Implementation-defined aspects of access to machine |
| operations. See C.1(9). |
| @end cartouche |
| @noindent |
| See documentation in file @file{s-maccod.ads} in the distributed library. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{83}. Implementation-defined aspects of interrupts. See C.3(2). |
| @end cartouche |
| @noindent |
| Interrupts are mapped to signals or conditions as appropriate. See |
| definition of unit |
| @code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details |
| on the interrupts supported on a particular target. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{84}. Implementation-defined aspects of pre-elaboration. See |
| C.4(13). |
| @end cartouche |
| @noindent |
| GNAT does not permit a partition to be restarted without reloading, |
| except under control of the debugger. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{85}. The semantics of pragma @code{Discard_Names}. See C.5(7). |
| @end cartouche |
| @noindent |
| Pragma @code{Discard_Names} causes names of enumeration literals to |
| be suppressed. In the presence of this pragma, the Image attribute |
| provides the image of the Pos of the literal, and Value accepts |
| Pos values. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{86}. The result of the @code{Task_Identification.Image} |
| attribute. See C.7.1(7). |
| @end cartouche |
| @noindent |
| The result of this attribute is an 8-digit hexadecimal string |
| representing the virtual address of the task control block. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{87}. The value of @code{Current_Task} when in a protected entry |
| or interrupt handler. See C.7.1(17). |
| @end cartouche |
| @noindent |
| Protected entries or interrupt handlers can be executed by any |
| convenient thread, so the value of @code{Current_Task} is undefined. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{88}. The effect of calling @code{Current_Task} from an entry |
| body or interrupt handler. See C.7.1(19). |
| @end cartouche |
| @noindent |
| The effect of calling @code{Current_Task} from an entry body or |
| interrupt handler is to return the identification of the task currently |
| executing the code. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{89}. Implementation-defined aspects of |
| @code{Task_Attributes}. See C.7.2(19). |
| @end cartouche |
| @noindent |
| There are no implementation-defined aspects of @code{Task_Attributes}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{90}. Values of all @code{Metrics}. See D(2). |
| @end cartouche |
| @noindent |
| The metrics information for GNAT depends on the performance of the |
| underlying operating system. The sources of the run-time for tasking |
| implementation, together with the output from @code{-gnatG} can be |
| used to determine the exact sequence of operating systems calls made |
| to implement various tasking constructs. Together with appropriate |
| information on the performance of the underlying operating system, |
| on the exact target in use, this information can be used to determine |
| the required metrics. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{91}. The declarations of @code{Any_Priority} and |
| @code{Priority}. See D.1(11). |
| @end cartouche |
| @noindent |
| See declarations in file @file{system.ads}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{92}. Implementation-defined execution resources. See D.1(15). |
| @end cartouche |
| @noindent |
| There are no implementation-defined execution resources. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{93}. Whether, on a multiprocessor, a task that is waiting for |
| access to a protected object keeps its processor busy. See D.2.1(3). |
| @end cartouche |
| @noindent |
| On a multi-processor, a task that is waiting for access to a protected |
| object does not keep its processor busy. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{94}. The affect of implementation defined execution resources |
| on task dispatching. See D.2.1(9). |
| @end cartouche |
| @noindent |
| @c SGI info |
| @ignore |
| Tasks map to IRIX threads, and the dispatching policy is as defined by |
| the IRIX implementation of threads. |
| @end ignore |
| Tasks map to threads in the threads package used by GNAT@. Where possible |
| and appropriate, these threads correspond to native threads of the |
| underlying operating system. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{95}. Implementation-defined @code{policy_identifiers} allowed |
| in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3). |
| @end cartouche |
| @noindent |
| There are no implementation-defined policy-identifiers allowed in this |
| pragma. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{96}. Implementation-defined aspects of priority inversion. See |
| D.2.2(16). |
| @end cartouche |
| @noindent |
| Execution of a task cannot be preempted by the implementation processing |
| of delay expirations for lower priority tasks. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{97}. Implementation defined task dispatching. See D.2.2(18). |
| @end cartouche |
| @noindent |
| @c SGI info: |
| @ignore |
| Tasks map to IRIX threads, and the dispatching policy is as defined by |
| the IRIX implementation of threads. |
| @end ignore |
| The policy is the same as that of the underlying threads implementation. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{98}. Implementation-defined @code{policy_identifiers} allowed |
| in a pragma @code{Locking_Policy}. See D.3(4). |
| @end cartouche |
| @noindent |
| The only implementation defined policy permitted in GNAT is |
| @code{Inheritance_Locking}. On targets that support this policy, locking |
| is implemented by inheritance, i.e.@: the task owning the lock operates |
| at a priority equal to the highest priority of any task currently |
| requesting the lock. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{99}. Default ceiling priorities. See D.3(10). |
| @end cartouche |
| @noindent |
| The ceiling priority of protected objects of the type |
| @code{System.Interrupt_Priority'Last} as described in the Ada 95 |
| Reference Manual D.3(10), |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{100}. The ceiling of any protected object used internally by |
| the implementation. See D.3(16). |
| @end cartouche |
| @noindent |
| The ceiling priority of internal protected objects is |
| @code{System.Priority'Last}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{101}. Implementation-defined queuing policies. See D.4(1). |
| @end cartouche |
| @noindent |
| There are no implementation-defined queuing policies. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{102}. On a multiprocessor, any conditions that cause the |
| completion of an aborted construct to be delayed later than what is |
| specified for a single processor. See D.6(3). |
| @end cartouche |
| @noindent |
| The semantics for abort on a multi-processor is the same as on a single |
| processor, there are no further delays. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{103}. Any operations that implicitly require heap storage |
| allocation. See D.7(8). |
| @end cartouche |
| @noindent |
| The only operation that implicitly requires heap storage allocation is |
| task creation. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{104}. Implementation-defined aspects of pragma |
| @code{Restrictions}. See D.7(20). |
| @end cartouche |
| @noindent |
| There are no such implementation-defined aspects. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{105}. Implementation-defined aspects of package |
| @code{Real_Time}. See D.8(17). |
| @end cartouche |
| @noindent |
| There are no implementation defined aspects of package @code{Real_Time}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{106}. Implementation-defined aspects of |
| @code{delay_statements}. See D.9(8). |
| @end cartouche |
| @noindent |
| Any difference greater than one microsecond will cause the task to be |
| delayed (see D.9(7)). |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{107}. The upper bound on the duration of interrupt blocking |
| caused by the implementation. See D.12(5). |
| @end cartouche |
| @noindent |
| The upper bound is determined by the underlying operating system. In |
| no cases is it more than 10 milliseconds. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{108}. The means for creating and executing distributed |
| programs. See E(5). |
| @end cartouche |
| @noindent |
| The GLADE package provides a utility GNATDIST for creating and executing |
| distributed programs. See the GLADE reference manual for further details. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{109}. Any events that can result in a partition becoming |
| inaccessible. See E.1(7). |
| @end cartouche |
| @noindent |
| See the GLADE reference manual for full details on such events. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{110}. The scheduling policies, treatment of priorities, and |
| management of shared resources between partitions in certain cases. See |
| E.1(11). |
| @end cartouche |
| @noindent |
| See the GLADE reference manual for full details on these aspects of |
| multi-partition execution. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{111}. Events that cause the version of a compilation unit to |
| change. See E.3(5). |
| @end cartouche |
| @noindent |
| Editing the source file of a compilation unit, or the source files of |
| any units on which it is dependent in a significant way cause the version |
| to change. No other actions cause the version number to change. All changes |
| are significant except those which affect only layout, capitalization or |
| comments. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{112}. Whether the execution of the remote subprogram is |
| immediately aborted as a result of cancellation. See E.4(13). |
| @end cartouche |
| @noindent |
| See the GLADE reference manual for details on the effect of abort in |
| a distributed application. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{113}. Implementation-defined aspects of the PCS@. See E.5(25). |
| @end cartouche |
| @noindent |
| See the GLADE reference manual for a full description of all implementation |
| defined aspects of the PCS@. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{114}. Implementation-defined interfaces in the PCS@. See |
| E.5(26). |
| @end cartouche |
| @noindent |
| See the GLADE reference manual for a full description of all |
| implementation defined interfaces. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{115}. The values of named numbers in the package |
| @code{Decimal}. See F.2(7). |
| @end cartouche |
| @noindent |
| @table @code |
| @item Max_Scale |
| +18 |
| @item Min_Scale |
| -18 |
| @item Min_Delta |
| 1.0E-18 |
| @item Max_Delta |
| 1.0E+18 |
| @item Max_Decimal_Digits |
| 18 |
| @end table |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{116}. The value of @code{Max_Picture_Length} in the package |
| @code{Text_IO.Editing}. See F.3.3(16). |
| @end cartouche |
| @noindent |
| 64 |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{117}. The value of @code{Max_Picture_Length} in the package |
| @code{Wide_Text_IO.Editing}. See F.3.4(5). |
| @end cartouche |
| @noindent |
| 64 |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{118}. The accuracy actually achieved by the complex elementary |
| functions and by other complex arithmetic operations. See G.1(1). |
| @end cartouche |
| @noindent |
| Standard library functions are used for the complex arithmetic |
| operations. Only fast math mode is currently supported. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{119}. The sign of a zero result (or a component thereof) from |
| any operator or function in @code{Numerics.Generic_Complex_Types}, when |
| @code{Real'Signed_Zeros} is True. See G.1.1(53). |
| @end cartouche |
| @noindent |
| The signs of zero values are as recommended by the relevant |
| implementation advice. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{120}. The sign of a zero result (or a component thereof) from |
| any operator or function in |
| @code{Numerics.Generic_Complex_Elementary_Functions}, when |
| @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45). |
| @end cartouche |
| @noindent |
| The signs of zero values are as recommended by the relevant |
| implementation advice. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{121}. Whether the strict mode or the relaxed mode is the |
| default. See G.2(2). |
| @end cartouche |
| @noindent |
| The strict mode is the default. There is no separate relaxed mode. GNAT |
| provides a highly efficient implementation of strict mode. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{122}. The result interval in certain cases of fixed-to-float |
| conversion. See G.2.1(10). |
| @end cartouche |
| @noindent |
| For cases where the result interval is implementation dependent, the |
| accuracy is that provided by performing all operations in 64-bit IEEE |
| floating-point format. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{123}. The result of a floating point arithmetic operation in |
| overflow situations, when the @code{Machine_Overflows} attribute of the |
| result type is @code{False}. See G.2.1(13). |
| @end cartouche |
| @noindent |
| Infinite and NaN values are produced as dictated by the IEEE |
| floating-point standard. |
| |
| Note that on machines that are not fully compliant with the IEEE |
| floating-point standard, such as Alpha, the @option{-mieee} compiler flag |
| must be used for achieving IEEE confirming behavior (although at the cost |
| of a significant performance penalty), so infinite and NaN values are |
| properly generated. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{124}. The result interval for division (or exponentiation by a |
| negative exponent), when the floating point hardware implements division |
| as multiplication by a reciprocal. See G.2.1(16). |
| @end cartouche |
| @noindent |
| Not relevant, division is IEEE exact. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{125}. The definition of close result set, which determines the |
| accuracy of certain fixed point multiplications and divisions. See |
| G.2.3(5). |
| @end cartouche |
| @noindent |
| Operations in the close result set are performed using IEEE long format |
| floating-point arithmetic. The input operands are converted to |
| floating-point, the operation is done in floating-point, and the result |
| is converted to the target type. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{126}. Conditions on a @code{universal_real} operand of a fixed |
| point multiplication or division for which the result shall be in the |
| perfect result set. See G.2.3(22). |
| @end cartouche |
| @noindent |
| The result is only defined to be in the perfect result set if the result |
| can be computed by a single scaling operation involving a scale factor |
| representable in 64-bits. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{127}. The result of a fixed point arithmetic operation in |
| overflow situations, when the @code{Machine_Overflows} attribute of the |
| result type is @code{False}. See G.2.3(27). |
| @end cartouche |
| @noindent |
| Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point |
| types. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{128}. The result of an elementary function reference in |
| overflow situations, when the @code{Machine_Overflows} attribute of the |
| result type is @code{False}. See G.2.4(4). |
| @end cartouche |
| @noindent |
| IEEE infinite and Nan values are produced as appropriate. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{129}. The value of the angle threshold, within which certain |
| elementary functions, complex arithmetic operations, and complex |
| elementary functions yield results conforming to a maximum relative |
| error bound. See G.2.4(10). |
| @end cartouche |
| @noindent |
| Information on this subject is not yet available. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{130}. The accuracy of certain elementary functions for |
| parameters beyond the angle threshold. See G.2.4(10). |
| @end cartouche |
| @noindent |
| Information on this subject is not yet available. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{131}. The result of a complex arithmetic operation or complex |
| elementary function reference in overflow situations, when the |
| @code{Machine_Overflows} attribute of the corresponding real type is |
| @code{False}. See G.2.6(5). |
| @end cartouche |
| @noindent |
| IEEE infinite and Nan values are produced as appropriate. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{132}. The accuracy of certain complex arithmetic operations and |
| certain complex elementary functions for parameters (or components |
| thereof) beyond the angle threshold. See G.2.6(8). |
| @end cartouche |
| @noindent |
| Information on those subjects is not yet available. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{133}. Information regarding bounded errors and erroneous |
| execution. See H.2(1). |
| @end cartouche |
| @noindent |
| Information on this subject is not yet available. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{134}. Implementation-defined aspects of pragma |
| @code{Inspection_Point}. See H.3.2(8). |
| @end cartouche |
| @noindent |
| Pragma @code{Inspection_Point} ensures that the variable is live and can |
| be examined by the debugger at the inspection point. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{135}. Implementation-defined aspects of pragma |
| @code{Restrictions}. See H.4(25). |
| @end cartouche |
| @noindent |
| There are no implementation-defined aspects of pragma @code{Restrictions}. The |
| use of pragma @code{Restrictions [No_Exceptions]} has no effect on the |
| generated code. Checks must suppressed by use of pragma @code{Suppress}. |
| |
| @sp 1 |
| @cartouche |
| @noindent |
| @strong{136}. Any restrictions on pragma @code{Restrictions}. See |
| H.4(27). |
| @end cartouche |
| @noindent |
| There are no restrictions on pragma @code{Restrictions}. |
| |
| @node Intrinsic Subprograms |
| @chapter Intrinsic Subprograms |
| @cindex Intrinsic Subprograms |
| |
| @menu |
| * Intrinsic Operators:: |
| * Enclosing_Entity:: |
| * Exception_Information:: |
| * Exception_Message:: |
| * Exception_Name:: |
| * File:: |
| * Line:: |
| * Rotate_Left:: |
| * Rotate_Right:: |
| * Shift_Left:: |
| * Shift_Right:: |
| * Shift_Right_Arithmetic:: |
| * Source_Location:: |
| @end menu |
| |
| @noindent |
| GNAT allows a user application program to write the declaration: |
| |
| @smallexample @c ada |
| pragma Import (Intrinsic, name); |
| @end smallexample |
| |
| @noindent |
| providing that the name corresponds to one of the implemented intrinsic |
| subprograms in GNAT, and that the parameter profile of the referenced |
| subprogram meets the requirements. This chapter describes the set of |
| implemented intrinsic subprograms, and the requirements on parameter profiles. |
| Note that no body is supplied; as with other uses of pragma Import, the |
| body is supplied elsewhere (in this case by the compiler itself). Note |
| that any use of this feature is potentially non-portable, since the |
| Ada standard does not require Ada compilers to implement this feature. |
| |
| @node Intrinsic Operators |
| @section Intrinsic Operators |
| @cindex Intrinsic operator |
| |
| @noindent |
| All the predefined numeric operators in package Standard |
| in @code{pragma Import (Intrinsic,..)} |
| declarations. In the binary operator case, the operands must have the same |
| size. The operand or operands must also be appropriate for |
| the operator. For example, for addition, the operands must |
| both be floating-point or both be fixed-point, and the |
| right operand for @code{"**"} must have a root type of |
| @code{Standard.Integer'Base}. |
| You can use an intrinsic operator declaration as in the following example: |
| |
| @smallexample @c ada |
| type Int1 is new Integer; |
| type Int2 is new Integer; |
| |
| function "+" (X1 : Int1; X2 : Int2) return Int1; |
| function "+" (X1 : Int1; X2 : Int2) return Int2; |
| pragma Import (Intrinsic, "+"); |
| @end smallexample |
| |
| @noindent |
| This declaration would permit ``mixed mode'' arithmetic on items |
| of the differing types @code{Int1} and @code{Int2}. |
| It is also possible to specify such operators for private types, if the |
| full views are appropriate arithmetic types. |
| |
| @node Enclosing_Entity |
| @section Enclosing_Entity |
| @cindex Enclosing_Entity |
| @noindent |
| This intrinsic subprogram is used in the implementation of the |
| library routine @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of |
| the current subprogram, package, task, entry, or protected subprogram. |
| |
| @node Exception_Information |
| @section Exception_Information |
| @cindex Exception_Information' |
| @noindent |
| This intrinsic subprogram is used in the implementation of the |
| library routine @code{GNAT.Current_Exception}. The only useful |
| use of the intrinsic import in this case is the one in this unit, |
| so an application program should simply call the function |
| @code{GNAT.Current_Exception.Exception_Information} to obtain |
| the exception information associated with the current exception. |
| |
| @node Exception_Message |
| @section Exception_Message |
| @cindex Exception_Message |
| @noindent |
| This intrinsic subprogram is used in the implementation of the |
| library routine @code{GNAT.Current_Exception}. The only useful |
| use of the intrinsic import in this case is the one in this unit, |
| so an application program should simply call the function |
| @code{GNAT.Current_Exception.Exception_Message} to obtain |
| the message associated with the current exception. |
| |
| @node Exception_Name |
| @section Exception_Name |
| @cindex Exception_Name |
| @noindent |
| This intrinsic subprogram is used in the implementation of the |
| library routine @code{GNAT.Current_Exception}. The only useful |
| use of the intrinsic import in this case is the one in this unit, |
| so an application program should simply call the function |
| @code{GNAT.Current_Exception.Exception_Name} to obtain |
| the name of the current exception. |
| |
| @node File |
| @section File |
| @cindex File |
| @noindent |
| This intrinsic subprogram is used in the implementation of the |
| library routine @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.File} to obtain the name of the current |
| file. |
| |
| @node Line |
| @section Line |
| @cindex Line |
| @noindent |
| This intrinsic subprogram is used in the implementation of the |
| library routine @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.Line} to obtain the number of the current |
| source line. |
| |
| @node Rotate_Left |
| @section Rotate_Left |
| @cindex Rotate_Left |
| @noindent |
| In standard Ada 95, the @code{Rotate_Left} function is available only |
| for the predefined modular types in package @code{Interfaces}. However, in |
| GNAT it is possible to define a Rotate_Left function for a user |
| defined modular type or any signed integer type as in this example: |
| |
| @smallexample @c ada |
| function Shift_Left |
| (Value : My_Modular_Type; |
| Amount : Natural) |
| return My_Modular_Type; |
| @end smallexample |
| |
| @noindent |
| The requirements are that the profile be exactly as in the example |
| above. The only modifications allowed are in the formal parameter |
| names, and in the type of @code{Value} and the return type, which |
| must be the same, and must be either a signed integer type, or |
| a modular integer type with a binary modulus, and the size must |
| be 8. 16, 32 or 64 bits. |
| |
| @node Rotate_Right |
| @section Rotate_Right |
| @cindex Rotate_Right |
| @noindent |
| A @code{Rotate_Right} function can be defined for any user defined |
| binary modular integer type, or signed integer type, as described |
| above for @code{Rotate_Left}. |
| |
| @node Shift_Left |
| @section Shift_Left |
| @cindex Shift_Left |
| @noindent |
| A @code{Shift_Left} function can be defined for any user defined |
| binary modular integer type, or signed integer type, as described |
| above for @code{Rotate_Left}. |
| |
| @node Shift_Right |
| @section Shift_Right |
| @cindex Shift_Right |
| @noindent |
| A @code{Shift_Right} function can be defined for any user defined |
| binary modular integer type, or signed integer type, as described |
| above for @code{Rotate_Left}. |
| |
| @node Shift_Right_Arithmetic |
| @section Shift_Right_Arithmetic |
| @cindex Shift_Right_Arithmetic |
| @noindent |
| A @code{Shift_Right_Arithmetic} function can be defined for any user |
| defined binary modular integer type, or signed integer type, as described |
| above for @code{Rotate_Left}. |
| |
| @node Source_Location |
| @section Source_Location |
| @cindex Source_Location |
| @noindent |
| This intrinsic subprogram is used in the implementation of the |
| library routine @code{GNAT.Source_Info}. The only useful use of the |
| intrinsic import in this case is the one in this unit, so an |
| application program should simply call the function |
| @code{GNAT.Source_Info.Source_Location} to obtain the current |
| source file location. |
| |
| @node Representation Clauses and Pragmas |
| @chapter Representation Clauses and Pragmas |
| @cindex Representation Clauses |
| |
| @menu |
| * Alignment Clauses:: |
| * Size Clauses:: |
| * Storage_Size Clauses:: |
| * Size of Variant Record Objects:: |
| * Biased Representation :: |
| * Value_Size and Object_Size Clauses:: |
| * Component_Size Clauses:: |
| * Bit_Order Clauses:: |
| * Effect of Bit_Order on Byte Ordering:: |
| * Pragma Pack for Arrays:: |
| * Pragma Pack for Records:: |
| * Record Representation Clauses:: |
| * Enumeration Clauses:: |
| * Address Clauses:: |
| * Effect of Convention on Representation:: |
| * Determining the Representations chosen by GNAT:: |
| @end menu |
| |
| @noindent |
| @cindex Representation Clause |
| @cindex Representation Pragma |
| @cindex Pragma, representation |
| This section describes the representation clauses accepted by GNAT, and |
| their effect on the representation of corresponding data objects. |
| |
| GNAT fully implements Annex C (Systems Programming). This means that all |
| the implementation advice sections in chapter 13 are fully implemented. |
| However, these sections only require a minimal level of support for |
| representation clauses. GNAT provides much more extensive capabilities, |
| and this section describes the additional capabilities provided. |
| |
| @node Alignment Clauses |
| @section Alignment Clauses |
| @cindex Alignment Clause |
| |
| @noindent |
| GNAT requires that all alignment clauses specify a power of 2, and all |
| default alignments are always a power of 2. The default alignment |
| values are as follows: |
| |
| @itemize @bullet |
| @item @emph{Primitive Types}. |
| For primitive types, the alignment is the minimum of the actual size of |
| objects of the type divided by @code{Storage_Unit}, |
| and the maximum alignment supported by the target. |
| (This maximum alignment is given by the GNAT-specific attribute |
| @code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.) |
| @cindex @code{Maximum_Alignment} attribute |
| For example, for type @code{Long_Float}, the object size is 8 bytes, and the |
| default alignment will be 8 on any target that supports alignments |
| this large, but on some targets, the maximum alignment may be smaller |
| than 8, in which case objects of type @code{Long_Float} will be maximally |
| aligned. |
| |
| @item @emph{Arrays}. |
| For arrays, the alignment is equal to the alignment of the component type |
| for the normal case where no packing or component size is given. If the |
| array is packed, and the packing is effective (see separate section on |
| packed arrays), then the alignment will be one for long packed arrays, |
| or arrays whose length is not known at compile time. For short packed |
| arrays, which are handled internally as modular types, the alignment |
| will be as described for primitive types, e.g.@: a packed array of length |
| 31 bits will have an object size of four bytes, and an alignment of 4. |
| |
| @item @emph{Records}. |
| For the normal non-packed case, the alignment of a record is equal to |
| the maximum alignment of any of its components. For tagged records, this |
| includes the implicit access type used for the tag. If a pragma @code{Pack} is |
| used and all fields are packable (see separate section on pragma @code{Pack}), |
| then the resulting alignment is 1. |
| |
| A special case is when: |
| @itemize @bullet |
| @item |
| the size of the record is given explicitly, or a |
| full record representation clause is given, and |
| @item |
| the size of the record is 2, 4, or 8 bytes. |
| @end itemize |
| @noindent |
| In this case, an alignment is chosen to match the |
| size of the record. For example, if we have: |
| |
| @smallexample @c ada |
| type Small is record |
| A, B : Character; |
| end record; |
| for Small'Size use 16; |
| @end smallexample |
| |
| @noindent |
| then the default alignment of the record type @code{Small} is 2, not 1. This |
| leads to more efficient code when the record is treated as a unit, and also |
| allows the type to specified as @code{Atomic} on architectures requiring |
| strict alignment. |
| |
| @end itemize |
| |
| @noindent |
| An alignment clause may |
| always specify a larger alignment than the default value, up to some |
| maximum value dependent on the target (obtainable by using the |
| attribute reference @code{Standard'Maximum_Alignment}). |
| The only case where |
| it is permissible to specify a smaller alignment than the default value |
| is for a record with a record representation clause. |
| In this case, packable fields for which a component clause is |
| given still result in a default alignment corresponding to the original |
| type, but this may be overridden, since these components in fact only |
| require an alignment of one byte. For example, given |
| |
| @smallexample @c ada |
| type V is record |
| A : Integer; |
| end record; |
| |
| for V use record |
| A at 0 range 0 .. 31; |
| end record; |
| |
| for V'alignment use 1; |
| @end smallexample |
| |
| @noindent |
| @cindex Alignment, default |
| The default alignment for the type @code{V} is 4, as a result of the |
| Integer field in the record, but since this field is placed with a |
| component clause, it is permissible, as shown, to override the default |
| alignment of the record with a smaller value. |
| |
| @node Size Clauses |
| @section Size Clauses |
| @cindex Size Clause |
| |
| @noindent |
| The default size for a type @code{T} is obtainable through the |
| language-defined attribute @code{T'Size} and also through the |
| equivalent GNAT-defined attribute @code{T'Value_Size}. |
| For objects of type @code{T}, GNAT will generally increase the type size |
| so that the object size (obtainable through the GNAT-defined attribute |
| @code{T'Object_Size}) |
| is a multiple of @code{T'Alignment * Storage_Unit}. |
| For example |
| |
| @smallexample @c ada |
| type Smallint is range 1 .. 6; |
| |
| type Rec is record |
| Y1 : integer; |
| Y2 : boolean; |
| end record; |
| @end smallexample |
| |
| @noindent |
| In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, |
| as specified by the RM rules, |
| but objects of this type will have a size of 8 |
| (@code{Smallint'Object_Size} = 8), |
| since objects by default occupy an integral number |
| of storage units. On some targets, notably older |
| versions of the Digital Alpha, the size of stand |
| alone objects of this type may be 32, reflecting |
| the inability of the hardware to do byte load/stores. |
| |
| Similarly, the size of type @code{Rec} is 40 bits |
| (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but |
| the alignment is 4, so objects of this type will have |
| their size increased to 64 bits so that it is a multiple |
| of the alignment (in bits). This decision is |
| in accordance with the specific Implementation Advice in RM 13.3(43): |
| |
| @quotation |
| A @code{Size} clause should be supported for an object if the specified |
| @code{Size} is at least as large as its subtype's @code{Size}, and corresponds |
| to a size in storage elements that is a multiple of the object's |
| @code{Alignment} (if the @code{Alignment} is nonzero). |
| @end quotation |
| |
| @noindent |
| An explicit size clause may be used to override the default size by |
| increasing it. For example, if we have: |
| |
| @smallexample @c ada |
| type My_Boolean is new Boolean; |
| for My_Boolean'Size use 32; |
| @end smallexample |
| |
| @noindent |
| then values of this type will always be 32 bits long. In the case of |
| discrete types, the size can be increased up to 64 bits, with the effect |
| that the entire specified field is used to hold the value, sign- or |
| zero-extended as appropriate. If more than 64 bits is specified, then |
| padding space is allocated after the value, and a warning is issued that |
| there are unused bits. |
| |
| Similarly the size of records and arrays may be increased, and the effect |
| is to add padding bits after the value. This also causes a warning message |
| to be generated. |
| |
| The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a |
| Size in bits, this corresponds to an object of size 256 megabytes (minus |
| one). This limitation is true on all targets. The reason for this |
| limitation is that it improves the quality of the code in many cases |
| if it is known that a Size value can be accommodated in an object of |
| type Integer. |
| |
| @node Storage_Size Clauses |
| @section Storage_Size Clauses |
| @cindex Storage_Size Clause |
| |
| @noindent |
| For tasks, the @code{Storage_Size} clause specifies the amount of space |
| to be allocated for the task stack. This cannot be extended, and if the |
| stack is exhausted, then @code{Storage_Error} will be raised (if stack |
| checking is enabled). Use a @code{Storage_Size} attribute definition clause, |
| or a @code{Storage_Size} pragma in the task definition to set the |
| appropriate required size. A useful technique is to include in every |
| task definition a pragma of the form: |
| |
| @smallexample @c ada |
| pragma Storage_Size (Default_Stack_Size); |
| @end smallexample |
| |
| @noindent |
| Then @code{Default_Stack_Size} can be defined in a global package, and |
| modified as required. Any tasks requiring stack sizes different from the |
| default can have an appropriate alternative reference in the pragma. |
| |
| You can also use the @code{-d} binder switch to modify the default stack |
| size. |
| |
| For access types, the @code{Storage_Size} clause specifies the maximum |
| space available for allocation of objects of the type. If this space is |
| exceeded then @code{Storage_Error} will be raised by an allocation attempt. |
| In the case where the access type is declared local to a subprogram, the |
| use of a @code{Storage_Size} clause triggers automatic use of a special |
| predefined storage pool (@code{System.Pool_Size}) that ensures that all |
| space for the pool is automatically reclaimed on exit from the scope in |
| which the type is declared. |
| |
| A special case recognized by the compiler is the specification of a |
| @code{Storage_Size} of zero for an access type. This means that no |
| items can be allocated from the pool, and this is recognized at compile |
| time, and all the overhead normally associated with maintaining a fixed |
| size storage pool is eliminated. Consider the following example: |
| |
| @smallexample @c ada |
| procedure p is |
| type R is array (Natural) of Character; |
| type P is access all R; |
| for P'Storage_Size use 0; |
| -- Above access type intended only for interfacing purposes |
| |
| y : P; |
| |
| procedure g (m : P); |
| pragma Import (C, g); |
| |
| -- @dots{} |
| |
| begin |
| -- @dots{} |
| y := new R; |
| end; |
| @end smallexample |
| |
| @noindent |
| As indicated in this example, these dummy storage pools are often useful in |
| connection with interfacing where no object will ever be allocated. If you |
| compile the above example, you get the warning: |
| |
| @smallexample |
| p.adb:16:09: warning: allocation from empty storage pool |
| p.adb:16:09: warning: Storage_Error will be raised at run time |
| @end smallexample |
| |
| @noindent |
| Of course in practice, there will not be any explicit allocators in the |
| case of such an access declaration. |
| |
| @node Size of Variant Record Objects |
| @section Size of Variant Record Objects |
| @cindex Size, variant record objects |
| @cindex Variant record objects, size |
| |
| @noindent |
| In the case of variant record objects, there is a question whether Size gives |
| information about a particular variant, or the maximum size required |
| for any variant. Consider the following program |
| |
| @smallexample @c ada |
| with Text_IO; use Text_IO; |
| procedure q is |
| type R1 (A : Boolean := False) is record |
| case A is |
| when True => X : Character; |
| when False => null; |
| end case; |
| end record; |
| |
| V1 : R1 (False); |
| V2 : R1; |
| |
| begin |
| Put_Line (Integer'Image (V1'Size)); |
| Put_Line (Integer'Image (V2'Size)); |
| end q; |
| @end smallexample |
| |
| @noindent |
| Here we are dealing with a variant record, where the True variant |
| requires 16 bits, and the False variant requires 8 bits. |
| In the above example, both V1 and V2 contain the False variant, |
| which is only 8 bits long. However, the result of running the |
| program is: |
| |
| @smallexample |
| 8 |
| 16 |
| @end smallexample |
| |
| @noindent |
| The reason for the difference here is that the discriminant value of |
| V1 is fixed, and will always be False. It is not possible to assign |
| a True variant value to V1, therefore 8 bits is sufficient. On the |
| other hand, in the case of V2, the initial discriminant value is |
| False (from the default), but it is possible to assign a True |
| variant value to V2, therefore 16 bits must be allocated for V2 |
| in the general case, even fewer bits may be needed at any particular |
| point during the program execution. |
| |
| As can be seen from the output of this program, the @code{'Size} |
| attribute applied to such an object in GNAT gives the actual allocated |
| size of the variable, which is the largest size of any of the variants. |
| The Ada Reference Manual is not completely clear on what choice should |
| be made here, but the GNAT behavior seems most consistent with the |
| language in the RM@. |
| |
| In some cases, it may be desirable to obtain the size of the current |
| variant, rather than the size of the largest variant. This can be |
| achieved in GNAT by making use of the fact that in the case of a |
| subprogram parameter, GNAT does indeed return the size of the current |
| variant (because a subprogram has no way of knowing how much space |
| is actually allocated for the actual). |
| |
| Consider the following modified version of the above program: |
| |
| @smallexample @c ada |
| with Text_IO; use Text_IO; |
| procedure q is |
| type R1 (A : Boolean := False) is record |
| case A is |
| when True => X : Character; |
| when False => null; |
| end case; |
| end record; |
| |
| V2 : R1; |
| |
| function Size (V : R1) return Integer is |
| begin |
| return V'Size; |
| end Size; |
| |
| begin |
| Put_Line (Integer'Image (V2'Size)); |
| Put_Line (Integer'IMage (Size (V2))); |
| V2 := (True, 'x'); |
| Put_Line (Integer'Image (V2'Size)); |
| Put_Line (Integer'IMage (Size (V2))); |
| end q; |
| @end smallexample |
| |
| @noindent |
| The output from this program is |
| |
| @smallexample |
| 16 |
| 8 |
| 16 |
| 16 |
| @end smallexample |
| |
| @noindent |
| Here we see that while the @code{'Size} attribute always returns |
| the maximum size, regardless of the current variant value, the |
| @code{Size} function does indeed return the size of the current |
| variant value. |
| |
| @node Biased Representation |
| @section Biased Representation |
| @cindex Size for biased representation |
| @cindex Biased representation |
| |
| @noindent |
| In the case of scalars with a range starting at other than zero, it is |
| possible in some cases to specify a size smaller than the default minimum |
| value, and in such cases, GNAT uses an unsigned biased representation, |
| in which zero is used to represent the lower bound, and successive values |
| represent successive values of the type. |
| |
| For example, suppose we have the declaration: |
| |
| @smallexample @c ada |
| type Small is range -7 .. -4; |
| for Small'Size use 2; |
| @end smallexample |
| |
| @noindent |
| Although the default size of type @code{Small} is 4, the @code{Size} |
| clause is accepted by GNAT and results in the following representation |
| scheme: |
| |
| @smallexample |
| -7 is represented as 2#00# |
| -6 is represented as 2#01# |
| -5 is represented as 2#10# |
| -4 is represented as 2#11# |
| @end smallexample |
| |
| @noindent |
| Biased representation is only used if the specified @code{Size} clause |
| cannot be accepted in any other manner. These reduced sizes that force |
| biased representation can be used for all discrete types except for |
| enumeration types for which a representation clause is given. |
| |
| @node Value_Size and Object_Size Clauses |
| @section Value_Size and Object_Size Clauses |
| @findex Value_Size |
| @findex Object_Size |
| @cindex Size, of objects |
| |
| @noindent |
| In Ada 95, @code{T'Size} for a type @code{T} is the minimum number of bits |
| required to hold values of type @code{T}. Although this interpretation was |
| allowed in Ada 83, it was not required, and this requirement in practice |
| can cause some significant difficulties. For example, in most Ada 83 |
| compilers, @code{Natural'Size} was 32. However, in Ada 95, |
| @code{Natural'Size} is |
| typically 31. This means that code may change in behavior when moving |
| from Ada 83 to Ada 95. For example, consider: |
| |
| @smallexample @c ada |
| type Rec is record; |
| A : Natural; |
| B : Natural; |
| end record; |
| |
| for Rec use record |
| at 0 range 0 .. Natural'Size - 1; |
| at 0 range Natural'Size .. 2 * Natural'Size - 1; |
| end record; |
| @end smallexample |
| |
| @noindent |
| In the above code, since the typical size of @code{Natural} objects |
| is 32 bits and @code{Natural'Size} is 31, the above code can cause |
| unexpected inefficient packing in Ada 95, and in general there are |
| cases where the fact that the object size can exceed the |
| size of the type causes surprises. |
| |
| To help get around this problem GNAT provides two implementation |
| defined attributes, @code{Value_Size} and @code{Object_Size}. When |
| applied to a type, these attributes yield the size of the type |
| (corresponding to the RM defined size attribute), and the size of |
| objects of the type respectively. |
| |
| The @code{Object_Size} is used for determining the default size of |
| objects and components. This size value can be referred to using the |
| @code{Object_Size} attribute. The phrase ``is used'' here means that it is |
| the basis of the determination of the size. The backend is free to |
| pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone |
| character might be stored in 32 bits on a machine with no efficient |
| byte access instructions such as the Alpha. |
| |
| The default rules for the value of @code{Object_Size} for |
| discrete types are as follows: |
| |
| @itemize @bullet |
| @item |
| The @code{Object_Size} for base subtypes reflect the natural hardware |
| size in bits (run the compiler with @option{-gnatS} to find those values |
| for numeric types). Enumeration types and fixed-point base subtypes have |
| 8, 16, 32 or 64 bits for this size, depending on the range of values |
| to be stored. |
| |
| @item |
| The @code{Object_Size} of a subtype is the same as the |
| @code{Object_Size} of |
| the type from which it is obtained. |
| |
| @item |
| The @code{Object_Size} of a derived base type is copied from the parent |
| base type, and the @code{Object_Size} of a derived first subtype is copied |
| from the parent first subtype. |
| @end itemize |
| |
| @noindent |
| The @code{Value_Size} attribute |
| is the (minimum) number of bits required to store a value |
| of the type. |
| This value is used to determine how tightly to pack |
| records or arrays with components of this type, and also affects |
| the semantics of unchecked conversion (unchecked conversions where |
| the @code{Value_Size} values differ generate a warning, and are potentially |
| target dependent). |
| |
| The default rules for the value of @code{Value_Size} are as follows: |
| |
| @itemize @bullet |
| @item |
| The @code{Value_Size} for a base subtype is the minimum number of bits |
| required to store all values of the type (including the sign bit |
| only if negative values are possible). |
| |
| @item |
| If a subtype statically matches the first subtype of a given type, then it has |
| by default the same @code{Value_Size} as the first subtype. This is a |
| consequence of RM 13.1(14) (``if two subtypes statically match, |
| then their subtype-specific aspects are the same''.) |
| |
| @item |
| All other subtypes have a @code{Value_Size} corresponding to the minimum |
| number of bits required to store all values of the subtype. For |
| dynamic bounds, it is assumed that the value can range down or up |
| to the corresponding bound of the ancestor |
| @end itemize |
| |
| @noindent |
| The RM defined attribute @code{Size} corresponds to the |
| @code{Value_Size} attribute. |
| |
| The @code{Size} attribute may be defined for a first-named subtype. This sets |
| the @code{Value_Size} of |
| the first-named subtype to the given value, and the |
| @code{Object_Size} of this first-named subtype to the given value padded up |
| to an appropriate boundary. It is a consequence of the default rules |
| above that this @code{Object_Size} will apply to all further subtypes. On the |
| other hand, @code{Value_Size} is affected only for the first subtype, any |
| dynamic subtypes obtained from it directly, and any statically matching |
| subtypes. The @code{Value_Size} of any other static subtypes is not affected. |
| |
| @code{Value_Size} and |
| @code{Object_Size} may be explicitly set for any subtype using |
| an attribute definition clause. Note that the use of these attributes |
| can cause the RM 13.1(14) rule to be violated. If two access types |
| reference aliased objects whose subtypes have differing @code{Object_Size} |
| values as a result of explicit attribute definition clauses, then it |
| is erroneous to convert from one access subtype to the other. |
| |
| At the implementation level, Esize stores the Object_Size and the |
| RM_Size field stores the @code{Value_Size} (and hence the value of the |
| @code{Size} attribute, |
| which, as noted above, is equivalent to @code{Value_Size}). |
| |
| To get a feel for the difference, consider the following examples (note |
| that in each case the base is @code{Short_Short_Integer} with a size of 8): |
| |
| @smallexample |
| Object_Size Value_Size |
| |
| type x1 is range 0 .. 5; 8 3 |
| |
| type x2 is range 0 .. 5; |
| for x2'size use 12; 16 12 |
| |
| subtype x3 is x2 range 0 .. 3; 16 2 |
| |
| subtype x4 is x2'base range 0 .. 10; 8 4 |
| |
| subtype x5 is x2 range 0 .. dynamic; 16 3* |
| |
| subtype x6 is x2'base range 0 .. dynamic; 8 3* |
| |
| @end smallexample |
| |
| @noindent |
| Note: the entries marked ``3*'' are not actually specified by the Ada 95 RM, |
| but it seems in the spirit of the RM rules to allocate the minimum number |
| of bits (here 3, given the range for @code{x2}) |
| known to be large enough to hold the given range of values. |
| |
| So far, so good, but GNAT has to obey the RM rules, so the question is |
| under what conditions must the RM @code{Size} be used. |
| The following is a list |
| of the occasions on which the RM @code{Size} must be used: |
| |
| @itemize @bullet |
| @item |
| Component size for packed arrays or records |
| |
| @item |
| Value of the attribute @code{Size} for a type |
| |
| @item |
| Warning about sizes not matching for unchecked conversion |
| @end itemize |
| |
| @noindent |
| For record types, the @code{Object_Size} is always a multiple of the |
| alignment of the type (this is true for all types). In some cases the |
| @code{Value_Size} can be smaller. Consider: |
| |
| @smallexample |
| type R is record |
| X : Integer; |
| Y : Character; |
| end record; |
| @end smallexample |
| |
| @noindent |
| On a typical 32-bit architecture, the X component will be four bytes, and |
| require four-byte alignment, and the Y component will be one byte. In this |
| case @code{R'Value_Size} will be 40 (bits) since this is the minimum size |
| required to store a value of this type, and for example, it is permissible |
| to have a component of type R in an outer record whose component size is |
| specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits), |
| since it must be rounded up so that this value is a multiple of the |
| alignment (4 bytes = 32 bits). |
| |
| @noindent |
| For all other types, the @code{Object_Size} |
| and Value_Size are the same (and equivalent to the RM attribute @code{Size}). |
| Only @code{Size} may be specified for such types. |
| |
| @node Component_Size Clauses |
| @section Component_Size Clauses |
| @cindex Component_Size Clause |
| |
| @noindent |
| Normally, the value specified in a component size clause must be consistent |
| with the subtype of the array component with regard to size and alignment. |
| In other words, the value specified must be at least equal to the size |
| of this subtype, and must be a multiple of the alignment value. |
| |
| In addition, component size clauses are allowed which cause the array |
| to be packed, by specifying a smaller value. The cases in which this |
| is allowed are for component size values in the range 1 through 63. The value |
| specified must not be smaller than the Size of the subtype. GNAT will |
| accurately honor all packing requests in this range. For example, if |
| we have: |
| |
| @smallexample @c ada |
| type r is array (1 .. 8) of Natural; |
| for r'Component_Size use 31; |
| @end smallexample |
| |
| @noindent |
| then the resulting array has a length of 31 bytes (248 bits = 8 * 31). |
| Of course access to the components of such an array is considerably |
| less efficient than if the natural component size of 32 is used. |
| |
| Note that there is no point in giving both a component size clause |
| and a pragma Pack for the same array type. if such duplicate |
| clauses are given, the pragma Pack will be ignored. |
| |
| @node Bit_Order Clauses |
| @section Bit_Order Clauses |
| @cindex Bit_Order Clause |
| @cindex bit ordering |
| @cindex ordering, of bits |
| |
| @noindent |
| For record subtypes, GNAT permits the specification of the @code{Bit_Order} |
| attribute. The specification may either correspond to the default bit |
| order for the target, in which case the specification has no effect and |
| places no additional restrictions, or it may be for the non-standard |
| setting (that is the opposite of the default). |
| |
| In the case where the non-standard value is specified, the effect is |
| to renumber bits within each byte, but the ordering of bytes is not |
| affected. There are certain |
| restrictions placed on component clauses as follows: |
| |
| @itemize @bullet |
| |
| @item Components fitting within a single storage unit. |
| @noindent |
| These are unrestricted, and the effect is merely to renumber bits. For |
| example if we are on a little-endian machine with @code{Low_Order_First} |
| being the default, then the following two declarations have exactly |
| the same effect: |
| |
| @smallexample @c ada |
| type R1 is record |
| A : Boolean; |
| B : Integer range 1 .. 120; |
| end record; |
| |
| for R1 use record |
| A at 0 range 0 .. 0; |
| B at 0 range 1 .. 7; |
| end record; |
| |
| type R2 is record |
| A : Boolean; |
| B : Integer range 1 .. 120; |
| end record; |
| |
| for R2'Bit_Order use High_Order_First; |
| |
| for R2 use record |
| A at 0 range 7 .. 7; |
| B at 0 range 0 .. 6; |
| end record; |
| @end smallexample |
| |
| @noindent |
| The useful application here is to write the second declaration with the |
| @code{Bit_Order} attribute definition clause, and know that it will be treated |
| the same, regardless of whether the target is little-endian or big-endian. |
| |
| @item Components occupying an integral number of bytes. |
| @noindent |
| These are components that exactly fit in two or more bytes. Such component |
| declarations are allowed, but have no effect, since it is important to realize |
| that the @code{Bit_Order} specification does not affect the ordering of bytes. |
| In particular, the following attempt at getting an endian-independent integer |
| does not work: |
| |
| @smallexample @c ada |
| type R2 is record |
| A : Integer; |
| end record; |
| |
| for R2'Bit_Order use High_Order_First; |
| |
| for R2 use record |
| A at 0 range 0 .. 31; |
| end record; |
| @end smallexample |
| |
| @noindent |
| This declaration will result in a little-endian integer on a |
| little-endian machine, and a big-endian integer on a big-endian machine. |
| If byte flipping is required for interoperability between big- and |
| little-endian machines, this must be explicitly programmed. This capability |
| is not provided by @code{Bit_Order}. |
| |
| @item Components that are positioned across byte boundaries |
| @noindent |
| but do not occupy an integral number of bytes. Given that bytes are not |
| reordered, such fields would occupy a non-contiguous sequence of bits |
| in memory, requiring non-trivial code to reassemble. They are for this |
| reason not permitted, and any component clause specifying such a layout |
| will be flagged as illegal by GNAT@. |
| |
| @end itemize |
| |
| @noindent |
| Since the misconception that Bit_Order automatically deals with all |
| endian-related incompatibilities is a common one, the specification of |
| a component field that is an integral number of bytes will always |
| generate a warning. This warning may be suppressed using |
| @code{pragma Suppress} if desired. The following section contains additional |
| details regarding the issue of byte ordering. |
| |
| @node Effect of Bit_Order on Byte Ordering |
| @section Effect of Bit_Order on Byte Ordering |
| @cindex byte ordering |
| @cindex ordering, of bytes |
| |
| @noindent |
| In this section we will review the effect of the @code{Bit_Order} attribute |
| definition clause on byte ordering. Briefly, it has no effect at all, but |
| a detailed example will be helpful. Before giving this |
| example, let us review the precise |
| definition of the effect of defining @code{Bit_Order}. The effect of a |
| non-standard bit order is described in section 15.5.3 of the Ada |
| Reference Manual: |
| |
| @quotation |
| 2 A bit ordering is a method of interpreting the meaning of |
| the storage place attributes. |
| @end quotation |
| |
| @noindent |
| To understand the precise definition of storage place attributes in |
| this context, we visit section 13.5.1 of the manual: |
| |
| @quotation |
| 13 A record_representation_clause (without the mod_clause) |
| specifies the layout. The storage place attributes (see 13.5.2) |
| are taken from the values of the position, first_bit, and last_bit |
| expressions after normalizing those values so that first_bit is |
| less than Storage_Unit. |
| @end quotation |
| |
| @noindent |
| The critical point here is that storage places are taken from |
| the values after normalization, not before. So the @code{Bit_Order} |
| interpretation applies to normalized values. The interpretation |
| is described in the later part of the 15.5.3 paragraph: |
| |
| @quotation |
| 2 A bit ordering is a method of interpreting the meaning of |
| the storage place attributes. High_Order_First (known in the |
| vernacular as ``big endian'') means that the first bit of a |
| storage element (bit 0) is the most significant bit (interpreting |
| the sequence of bits that represent a component as an unsigned |
| integer value). Low_Order_First (known in the vernacular as |
| ``little endian'') means the opposite: the first bit is the |
| least significant. |
| @end quotation |
| |
| @noindent |
| Note that the numbering is with respect to the bits of a storage |
| unit. In other words, the specification affects only the numbering |
| of bits within a single storage unit. |
| |
| We can make the effect clearer by giving an example. |
| |
| Suppose that we have an external device which presents two bytes, the first |
| byte presented, which is the first (low addressed byte) of the two byte |
| record is called Master, and the second byte is called Slave. |
| |
| The left most (most significant bit is called Control for each byte, and |
| the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost |
| (least significant) bit. |
| |
| On a big-endian machine, we can write the following representation clause |
| |
| @smallexample @c ada |
| type Data is record |
| Master_Control : Bit; |
| Master_V1 : Bit; |
| Master_V2 : Bit; |
| Master_V3 : Bit; |
| Master_V4 : Bit; |
| Master_V5 : Bit; |
| Master_V6 : Bit; |
| Master_V7 : Bit; |
| Slave_Control : Bit; |
| Slave_V1 : Bit; |
| Slave_V2 : Bit; |
| Slave_V3 : Bit; |
| Slave_V4 : Bit; |
| Slave_V5 : Bit; |
| Slave_V6 : Bit; |
| Slave_V7 : Bit; |
| end record; |
| |
| for Data use record |
| Master_Control at 0 range 0 .. 0; |
| Master_V1 at 0 range 1 .. 1; |
| Master_V2 at 0 range 2 .. 2; |
| Master_V3 at 0 range 3 .. 3; |
| Master_V4 at 0 range 4 .. 4; |
| Master_V5 at 0 range 5 .. 5; |
| Master_V6 at 0 range 6 .. 6; |
| Master_V7 at 0 range 7 .. 7; |
| Slave_Control at 1 range 0 .. 0; |
| Slave_V1 at 1 range 1 .. 1; |
| Slave_V2 at 1 range 2 .. 2; |
| Slave_V3 at 1 range 3 .. 3; |
| Slave_V4 at 1 range 4 .. 4; |
| Slave_V5 at 1 range 5 .. 5; |
| Slave_V6 at 1 range 6 .. 6; |
| Slave_V7 at 1 range 7 .. 7; |
| end record; |
| @end smallexample |
| |
| @noindent |
| Now if we move this to a little endian machine, then the bit ordering within |
| the byte is backwards, so we have to rewrite the record rep clause as: |
| |
| @smallexample @c ada |
| for Data use record |
| Master_Control at 0 range 7 .. 7; |
| Master_V1 at 0 range 6 .. 6; |
| Master_V2 at 0 range 5 .. 5; |
| Master_V3 at 0 range 4 .. 4; |
| Master_V4 at 0 range 3 .. 3; |
| Master_V5 at 0 range 2 .. 2; |
| Master_V6 at 0 range 1 .. 1; |
| Master_V7 at 0 range 0 .. 0; |
| Slave_Control at 1 range 7 .. 7; |
| Slave_V1 at 1 range 6 .. 6; |
| Slave_V2 at 1 range 5 .. 5; |
| Slave_V3 at 1 range 4 .. 4; |
| Slave_V4 at 1 range 3 .. 3; |
| Slave_V5 at 1 range 2 .. 2; |
| Slave_V6 at 1 range 1 .. 1; |
| Slave_V7 at 1 range 0 .. 0; |
| end record; |
| @end smallexample |
| |
| @noindent |
| It is a nuisance to have to rewrite the clause, especially if |
| the code has to be maintained on both machines. However, |
| this is a case that we can handle with the |
| @code{Bit_Order} attribute if it is implemented. |
| Note that the implementation is not required on byte addressed |
| machines, but it is indeed implemented in GNAT. |
| This means that we can simply use the |
| first record clause, together with the declaration |
| |
| @smallexample @c ada |
| for Data'Bit_Order use High_Order_First; |
| @end smallexample |
| |
| @noindent |
| and the effect is what is desired, namely the layout is exactly the same, |
| independent of whether the code is compiled on a big-endian or little-endian |
| machine. |
| |
| The important point to understand is that byte ordering is not affected. |
| A @code{Bit_Order} attribute definition never affects which byte a field |
| ends up in, only where it ends up in that byte. |
| To make this clear, let us rewrite the record rep clause of the previous |
| example as: |
| |
| @smallexample @c ada |
| for Data'Bit_Order use High_Order_First; |
| for Data use record |
| Master_Control at 0 range 0 .. 0; |
| Master_V1 at 0 range 1 .. 1; |
| Master_V2 at 0 range 2 .. 2; |
| Master_V3 at 0 range 3 .. 3; |
| Master_V4 at 0 range 4 .. 4; |
| Master_V5 at 0 range 5 .. 5; |
| Master_V6 at 0 range 6 .. 6; |
| Master_V7 at 0 range 7 .. 7; |
| Slave_Control at 0 range 8 .. 8; |
| Slave_V1 at 0 range 9 .. 9; |
| Slave_V2 at 0 range 10 .. 10; |
| Slave_V3 at 0 range 11 .. 11; |
| Slave_V4 at 0 range 12 .. 12; |
| Slave_V5 at 0 range 13 .. 13; |
| Slave_V6 at 0 range 14 .. 14; |
| Slave_V7 at 0 range 15 .. 15; |
| end record; |
| @end smallexample |
| |
| @noindent |
| This is exactly equivalent to saying (a repeat of the first example): |
| |
| @smallexample @c ada |
| for Data'Bit_Order use High_Order_First; |
| for Data use record |
| Master_Control at 0 range 0 .. 0; |
| Master_V1 at 0 range 1 .. 1; |
| Master_V2 at 0 range 2 .. 2; |
| Master_V3 at 0 range 3 .. 3; |
| Master_V4 at 0 range 4 .. 4; |
| Master_V5 at 0 range 5 .. 5; |
| Master_V6 at 0 range 6 .. 6; |
| Master_V7 at 0 range 7 .. 7; |
| Slave_Control at 1 range 0 .. 0; |
| Slave_V1 at 1 range 1 .. 1; |
| Slave_V2 at 1 range 2 .. 2; |
| Slave_V3 at 1 range 3 .. 3; |
| Slave_V4 at 1 range 4 .. 4; |
| Slave_V5 at 1 range 5 .. 5; |
| Slave_V6 at 1 range 6 .. 6; |
| Slave_V7 at 1 range 7 .. 7; |
| end record; |
| @end smallexample |
| |
| @noindent |
| Why are they equivalent? Well take a specific field, the @code{Slave_V2} |
| field. The storage place attributes are obtained by normalizing the |
| values given so that the @code{First_Bit} value is less than 8. After |
| normalizing the values (0,10,10) we get (1,2,2) which is exactly what |
| we specified in the other case. |
| |
| Now one might expect that the @code{Bit_Order} attribute might affect |
| bit numbering within the entire record component (two bytes in this |
| case, thus affecting which byte fields end up in), but that is not |
| the way this feature is defined, it only affects numbering of bits, |
| not which byte they end up in. |
| |
| Consequently it never makes sense to specify a starting bit number |
| greater than 7 (for a byte addressable field) if an attribute |
| definition for @code{Bit_Order} has been given, and indeed it |
| may be actively confusing to specify such a value, so the compiler |
| generates a warning for such usage. |
| |
| If you do need to control byte ordering then appropriate conditional |
| values must be used. If in our example, the slave byte came first on |
| some machines we might write: |
| |
| @smallexample @c ada |
| Master_Byte_First constant Boolean := @dots{}; |
| |
| Master_Byte : constant Natural := |
| 1 - Boolean'Pos (Master_Byte_First); |
| Slave_Byte : constant Natural := |
| Boolean'Pos (Master_Byte_First); |
| |
| for Data'Bit_Order use High_Order_First; |
| for Data use record |
| Master_Control at Master_Byte range 0 .. 0; |
| Master_V1 at Master_Byte range 1 .. 1; |
| Master_V2 at Master_Byte range 2 .. 2; |
| Master_V3 at Master_Byte range 3 .. 3; |
| Master_V4 at Master_Byte range 4 .. 4; |
| Master_V5 at Master_Byte range 5 .. 5; |
| Master_V6 at Master_Byte range 6 .. 6; |
| Master_V7 at Master_Byte range 7 .. 7; |
| Slave_Control at Slave_Byte range 0 .. 0; |
| Slave_V1 at Slave_Byte range 1 .. 1; |
| Slave_V2 at Slave_Byte range 2 .. 2; |
| Slave_V3 at Slave_Byte range 3 .. 3; |
| Slave_V4 at Slave_Byte range 4 .. 4; |
| Slave_V5 at Slave_Byte range 5 .. 5; |
| Slave_V6 at Slave_Byte range 6 .. 6; |
| Slave_V7 at Slave_Byte range 7 .. 7; |
| end record; |
| @end smallexample |
| |
| @noindent |
| Now to switch between machines, all that is necessary is |
| to set the boolean constant @code{Master_Byte_First} in |
| an appropriate manner. |
| |
| @node Pragma Pack for Arrays |
| @section Pragma Pack for Arrays |
| @cindex Pragma Pack (for arrays) |
| |
| @noindent |
| Pragma @code{Pack} applied to an array has no effect unless the component type |
| is packable. For a component type to be packable, it must be one of the |
| following cases: |
| |
| @itemize @bullet |
| @item |
| Any scalar type |
| @item |
| Any type whose size is specified with a size clause |
| @item |
| Any packed array type with a static size |
| @end itemize |
| |
| @noindent |
| For all these cases, if the component subtype size is in the range |
| 1 through 63, then the effect of the pragma @code{Pack} is exactly as though a |
| component size were specified giving the component subtype size. |
| For example if we have: |
| |
| @smallexample @c ada |
| type r is range 0 .. 17; |
| |
| type ar is array (1 .. 8) of r; |
| pragma Pack (ar); |
| @end smallexample |
| |
| @noindent |
| Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size}, |
| and the size of the array @code{ar} will be exactly 40 bits. |
| |
| Note that in some cases this rather fierce approach to packing can produce |
| unexpected effects. For example, in Ada 95, type Natural typically has a |
| size of 31, meaning that if you pack an array of Natural, you get 31-bit |
| close packing, which saves a few bits, but results in far less efficient |
| access. Since many other Ada compilers will ignore such a packing request, |
| GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses |
| might not be what is intended. You can easily remove this warning by |
| using an explicit @code{Component_Size} setting instead, which never generates |
| a warning, since the intention of the programmer is clear in this case. |
| |
| GNAT treats packed arrays in one of two ways. If the size of the array is |
| known at compile time and is less than 64 bits, then internally the array |
| is represented as a single modular type, of exactly the appropriate number |
| of bits. If the length is greater than 63 bits, or is not known at compile |
| time, then the packed array is represented as an array of bytes, and the |
| length is always a multiple of 8 bits. |
| |
| Note that to represent a packed array as a modular type, the alignment must |
| be suitable for the modular type involved. For example, on typical machines |
| a 32-bit packed array will be represented by a 32-bit modular integer with |
| an alignment of four bytes. If you explicitly override the default alignment |
| with an alignment clause that is too small, the modular representation |
| cannot be used. For example, consider the following set of declarations: |
| |
| @smallexample @c ada |
| type R is range 1 .. 3; |
| type S is array (1 .. 31) of R; |
| for S'Component_Size use 2; |
| for S'Size use 62; |
| for S'Alignment use 1; |
| @end smallexample |
| |
| @noindent |
| If the alignment clause were not present, then a 62-bit modular |
| representation would be chosen (typically with an alignment of 4 or 8 |
| bytes depending on the target). But the default alignment is overridden |
| with the explicit alignment clause. This means that the modular |
| representation cannot be used, and instead the array of bytes |
| representation must be used, meaning that the length must be a multiple |
| of 8. Thus the above set of declarations will result in a diagnostic |
| rejecting the size clause and noting that the minimum size allowed is 64. |
| |
| @cindex Pragma Pack (for type Natural) |
| @cindex Pragma Pack warning |
| |
| One special case that is worth noting occurs when the base type of the |
| component size is 8/16/32 and the subtype is one bit less. Notably this |
| occurs with subtype @code{Natural}. Consider: |
| |
| @smallexample @c ada |
| type Arr is array (1 .. 32) of Natural; |
| pragma Pack (Arr); |
| @end smallexample |
| |
| @noindent |
| In all commonly used Ada 83 compilers, this pragma Pack would be ignored, |
| since typically @code{Natural'Size} is 32 in Ada 83, and in any case most |
| Ada 83 compilers did not attempt 31 bit packing. |
| |
| In Ada 95, @code{Natural'Size} is required to be 31. Furthermore, GNAT really |
| does pack 31-bit subtype to 31 bits. This may result in a substantial |
| unintended performance penalty when porting legacy Ada 83 code. To help |
| prevent this, GNAT generates a warning in such cases. If you really want 31 |
| bit packing in a case like this, you can set the component size explicitly: |
| |
| @smallexample @c ada |
| type Arr is array (1 .. 32) of Natural; |
| for Arr'Component_Size use 31; |
| @end smallexample |
| |
| @noindent |
| Here 31-bit packing is achieved as required, and no warning is generated, |
| since in this case the programmer intention is clear. |
| |
| @node Pragma Pack for Records |
| @section Pragma Pack for Records |
| @cindex Pragma Pack (for records) |
| |
| @noindent |
| Pragma @code{Pack} applied to a record will pack the components to reduce |
| wasted space from alignment gaps and by reducing the amount of space |
| taken by components. We distinguish between @emph{packable} components and |
| @emph{non-packable} components. |
| Components of the following types are considered packable: |
| @itemize @bullet |
| @item |
| All primitive types are packable. |
| |
| @item |
| Small packed arrays, whose size does not exceed 64 bits, and where the |
| size is statically known at compile time, are represented internally |
| as modular integers, and so they are also packable. |
| |
| @end itemize |
| |
| @noindent |
| All packable components occupy the exact number of bits corresponding to |
| their @code{Size} value, and are packed with no padding bits, i.e.@: they |
| can start on an arbitrary bit boundary. |
| |
| All other types are non-packable, they occupy an integral number of |
| storage units, and |
| are placed at a boundary corresponding to their alignment requirements. |
| |
| For example, consider the record |
| |
| @smallexample @c ada |
| type Rb1 is array (1 .. 13) of Boolean; |
| pragma Pack (rb1); |
| |
| type Rb2 is array (1 .. 65) of Boolean; |
| pragma Pack (rb2); |
| |
| type x2 is record |
| l1 : Boolean; |
| l2 : Duration; |
| l3 : Float; |
| l4 : Boolean; |
| l5 : Rb1; |
| l6 : Rb2; |
| end record; |
| pragma Pack (x2); |
| @end smallexample |
| |
| @noindent |
| The representation for the record x2 is as follows: |
| |
| @smallexample @c ada |
| for x2'Size use 224; |
| for x2 use record |
| l1 at 0 range 0 .. 0; |
| l2 at 0 range 1 .. 64; |
| l3 at 12 range 0 .. 31; |
| l4 at 16 range 0 .. 0; |
| l5 at 16 range 1 .. 13; |
| l6 at 18 range 0 .. 71; |
| end record; |
| @end smallexample |
| |
| @noindent |
| Studying this example, we see that the packable fields @code{l1} |
| and @code{l2} are |
| of length equal to their sizes, and placed at specific bit boundaries (and |
| not byte boundaries) to |
| eliminate padding. But @code{l3} is of a non-packable float type, so |
| it is on the next appropriate alignment boundary. |
| |
| The next two fields are fully packable, so @code{l4} and @code{l5} are |
| minimally packed with no gaps. However, type @code{Rb2} is a packed |
| array that is longer than 64 bits, so it is itself non-packable. Thus |
| the @code{l6} field is aligned to the next byte boundary, and takes an |
| integral number of bytes, i.e.@: 72 bits. |
| |
| @node Record Representation Clauses |
| @section Record Representation Clauses |
| @cindex Record Representation Clause |
| |
| @noindent |
| Record representation clauses may be given for all record types, including |
| types obtained by record extension. Component clauses are allowed for any |
| static component. The restrictions on component clauses depend on the type |
| of the component. |
| |
| @cindex Component Clause |
| For all components of an elementary type, the only restriction on component |
| clauses is that the size must be at least the 'Size value of the type |
| (actually the Value_Size). There are no restrictions due to alignment, |
| and such components may freely cross storage boundaries. |
| |
| Packed arrays with a size up to and including 64 bits are represented |
| internally using a modular type with the appropriate number of bits, and |
| thus the same lack of restriction applies. For example, if you declare: |
| |
| @smallexample @c ada |
| type R is array (1 .. 49) of Boolean; |
| pragma Pack (R); |
| for R'Size use 49; |
| @end smallexample |
| |
| @noindent |
| then a component clause for a component of type R may start on any |
| specified bit boundary, and may specify a value of 49 bits or greater. |
| |
| For packed bit arrays that are longer than 64 bits, there are two |
| cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), |
| including the important case of single bits or boolean values, then |
| there are no limitations on placement of such components, and they |
| may start and end at arbitrary bit boundaries. |
| |
| If the component size is not a power of 2 (e.g. 3 or 5), then |
| an array of this type longer than 64 bits must always be placed on |
| on a storage unit (byte) boundary and occupy an integral number |
| of storage units (bytes). Any component clause that does not |
| meet this requirement will be rejected. |
| |
| Any aliased component, or component of an aliased type, must |
| have its normal alignment and size. A component clause that |
| does not meet this requirement will be rejected. |
| |
| The tag field of a tagged type always occupies an address sized field at |
| the start of the record. No component clause may attempt to overlay this |
| tag. When a tagged type appears as a component, the tag field must have |
| proper alignment |
| |
| In the case of a record extension T1, of a type T, no component clause applied |
| to the type T1 can specify a storage location that would overlap the first |
| T'Size bytes of the record. |
| |
| For all other component types, including non-bit-packed arrays, |
| the component can be placed at an arbitrary bit boundary, |
| so for example, the following is permitted: |
| |
| @smallexample @c ada |
| type R is array (1 .. 10) of Boolean; |
| for R'Size use 80; |
| |
| type Q is record |
| G, H : Boolean; |
| L, M : R; |
| end record; |
| |
| for Q use record |
| G at 0 range 0 .. 0; |
| H at 0 range 1 .. 1; |
| L at 0 range 2 .. 81; |
| R at 0 range 82 .. 161; |
| end record; |
| @end smallexample |
| |
| @noindent |
| Note: the above rules apply to recent releases of GNAT 5. |
| In GNAT 3, there are more severe restrictions on larger components. |
| For non-primitive types, including packed arrays with a size greater than |
| 64 bits, component clauses must respect the alignment requirement of the |
| type, in particular, always starting on a byte boundary, and the length |
| must be a multiple of the storage unit. |
| |
| @node Enumeration Clauses |
| @section Enumeration Clauses |
| |
| The only restriction on enumeration clauses is that the range of values |
| must be representable. For the signed case, if one or more of the |
| representation values are negative, all values must be in the range: |
| |
| @smallexample @c ada |
| System.Min_Int .. System.Max_Int |
| @end smallexample |
| |
| @noindent |
| For the unsigned case, where all values are non negative, the values must |
| be in the range: |
| |
| @smallexample @c ada |
| 0 .. System.Max_Binary_Modulus; |
| @end smallexample |
| |
| @noindent |
| A @emph{confirming} representation clause is one in which the values range |
| from 0 in sequence, i.e.@: a clause that confirms the default representation |
| for an enumeration type. |
| Such a confirming representation |
| is permitted by these rules, and is specially recognized by the compiler so |
| that no extra overhead results from the use of such a clause. |
| |
| If an array has an index type which is an enumeration type to which an |
| enumeration clause has been applied, then the array is stored in a compact |
| manner. Consider the declarations: |
| |
| @smallexample @c ada |
| type r is (A, B, C); |
| for r use (A => 1, B => 5, C => 10); |
| type t is array (r) of Character; |
| @end smallexample |
| |
| @noindent |
| The array type t corresponds to a vector with exactly three elements and |
| has a default size equal to @code{3*Character'Size}. This ensures efficient |
| use of space, but means that accesses to elements of the array will incur |
| the overhead of converting representation values to the corresponding |
| positional values, (i.e.@: the value delivered by the @code{Pos} attribute). |
| |
| @node Address Clauses |
| @section Address Clauses |
| @cindex Address Clause |
| |
| The reference manual allows a general restriction on representation clauses, |
| as found in RM 13.1(22): |
| |
| @quotation |
| An implementation need not support representation |
| items containing nonstatic expressions, except that |
| an implementation should support a representation item |
| for a given entity if each nonstatic expression in the |
| representation item is a name that statically denotes |
| a constant declared before the entity. |
| @end quotation |
| |
| @noindent |
| In practice this is applicable only to address clauses, since this is the |
| only case in which a non-static expression is permitted by the syntax. As |
| the AARM notes in sections 13.1 (22.a-22.h): |
| |
| @display |
| 22.a Reason: This is to avoid the following sort of thing: |
| |
| 22.b X : Integer := F(@dots{}); |
| Y : Address := G(@dots{}); |
| for X'Address use Y; |
| |
| 22.c In the above, we have to evaluate the |
| initialization expression for X before we |
| know where to put the result. This seems |
| like an unreasonable implementation burden. |
| |
| 22.d The above code should instead be written |
| like this: |
| |
| 22.e Y : constant Address := G(@dots{}); |
| X : Integer := F(@dots{}); |
| for X'Address use Y; |
| |
| 22.f This allows the expression ``Y'' to be safely |
| evaluated before X is created. |
| |
| 22.g The constant could be a formal parameter of mode in. |
| |
| 22.h An implementation can support other nonstatic |
| expressions if it wants to. Expressions of type |
| Address are hardly ever static, but their value |
| might be known at compile time anyway in many |
| cases. |
| @end display |
| |
| @noindent |
| GNAT does indeed permit many additional cases of non-static expressions. In |
| particular, if the type involved is elementary there are no restrictions |
| (since in this case, holding a temporary copy of the initialization value, |
| if one is present, is inexpensive). In addition, if there is no implicit or |
| explicit initialization, then there are no restrictions. GNAT will reject |
| only the case where all three of these conditions hold: |
| |
| @itemize @bullet |
| |
| @item |
| The type of the item is non-elementary (e.g.@: a record or array). |
| |
| @item |
| There is explicit or implicit initialization required for the object. |
| Note that access values are always implicitly initialized, and also |
| in GNAT, certain bit-packed arrays (those having a dynamic length or |
| a length greater than 64) will also be implicitly initialized to zero. |
| |
| @item |
| The address value is non-static. Here GNAT is more permissive than the |
| RM, and allows the address value to be the address of a previously declared |
| stand-alone variable, as long as it does not itself have an address clause. |
| |
| @smallexample @c ada |
| Anchor : Some_Initialized_Type; |
| Overlay : Some_Initialized_Type; |
| for Overlay'Address use Anchor'Address; |
| @end smallexample |
| |
| @noindent |
| However, the prefix of the address clause cannot be an array component, or |
| a component of a discriminated record. |
| |
| @end itemize |
| |
| @noindent |
| As noted above in section 22.h, address values are typically non-static. In |
| particular the To_Address function, even if applied to a literal value, is |
| a non-static function call. To avoid this minor annoyance, GNAT provides |
| the implementation defined attribute 'To_Address. The following two |
| expressions have identical values: |
| |
| @findex Attribute |
| @findex To_Address |
| @smallexample @c ada |
| To_Address (16#1234_0000#) |
| System'To_Address (16#1234_0000#); |
| @end smallexample |
| |
| @noindent |
| except that the second form is considered to be a static expression, and |
| thus when used as an address clause value is always permitted. |
| |
| @noindent |
| Additionally, GNAT treats as static an address clause that is an |
| unchecked_conversion of a static integer value. This simplifies the porting |
| of legacy code, and provides a portable equivalent to the GNAT attribute |
| @code{To_Address}. |
| |
| Another issue with address clauses is the interaction with alignment |
| requirements. When an address clause is given for an object, the address |
| value must be consistent with the alignment of the object (which is usually |
| the same as the alignment of the type of the object). If an address clause |
| is given that specifies an inappropriately aligned address value, then the |
| program execution is erroneous. |
| |
| Since this source of erroneous behavior can have unfortunate effects, GNAT |
| checks (at compile time if possible, generating a warning, or at execution |
| time with a run-time check) that the alignment is appropriate. If the |
| run-time check fails, then @code{Program_Error} is raised. This run-time |
| check is suppressed if range checks are suppressed, or if |
| @code{pragma Restrictions (No_Elaboration_Code)} is in effect. |
| |
| @findex Export |
| An address clause cannot be given for an exported object. More |
| understandably the real restriction is that objects with an address |
| clause cannot be exported. This is because such variables are not |
| defined by the Ada program, so there is no external object to export. |
| |
| @findex Import |
| It is permissible to give an address clause and a pragma Import for the |
| same object. In this case, the variable is not really defined by the |
| Ada program, so there is no external symbol to be linked. The link name |
| and the external name are ignored in this case. The reason that we allow this |
| combination is that it provides a useful idiom to avoid unwanted |
| initializations on objects with address clauses. |
| |
| When an address clause is given for an object that has implicit or |
| explicit initialization, then by default initialization takes place. This |
| means that the effect of the object declaration is to overwrite the |
| memory at the specified address. This is almost always not what the |
| programmer wants, so GNAT will output a warning: |
| |
| @smallexample |
| with System; |
| package G is |
| type R is record |
| M : Integer := 0; |
| end record; |
| |
| Ext : R; |
| for Ext'Address use System'To_Address (16#1234_1234#); |
| | |
| >>> warning: implicit initialization of "Ext" may |
| modify overlaid storage |
| >>> warning: use pragma Import for "Ext" to suppress |
| initialization (RM B(24)) |
| |
| end G; |
| @end smallexample |
| |
| @noindent |
| As indicated by the warning message, the solution is to use a (dummy) pragma |
| Import to suppress this initialization. The pragma tell the compiler that the |
| object is declared and initialized elsewhere. The following package compiles |
| without warnings (and the initialization is suppressed): |
| |
| @smallexample @c ada |
| with System; |
| package G is |
| type R is record |
| M : Integer := 0; |
| end record; |
| |
| Ext : R; |
| for Ext'Address use System'To_Address (16#1234_1234#); |
| pragma Import (Ada, Ext); |
| end G; |
| @end smallexample |
| |
| @noindent |
| A final issue with address clauses involves their use for overlaying |
| variables, as in the following example: |
| @cindex Overlaying of objects |
| |
| @smallexample @c ada |
| A : Integer; |
| B : Integer; |
| for B'Address use A'Address; |
| @end smallexample |
| |
| @noindent |
| or alternatively, using the form recommended by the RM: |
| |
| @smallexample @c ada |
| A : Integer; |
| Addr : constant Address := A'Address; |
| B : Integer; |
| for B'Address use Addr; |
| @end smallexample |
| |
| @noindent |
| In both of these cases, @code{A} |
| and @code{B} become aliased to one another via the |
| address clause. This use of address clauses to overlay |
| variables, achieving an effect similar to unchecked |
| conversion was erroneous in Ada 83, but in Ada 95 |
| the effect is implementation defined. Furthermore, the |
| Ada 95 RM specifically recommends that in a situation |
| like this, @code{B} should be subject to the following |
| implementation advice (RM 13.3(19)): |
| |
| @quotation |
| 19 If the Address of an object is specified, or it is imported |
| or exported, then the implementation should not perform |
| optimizations based on assumptions of no aliases. |
| @end quotation |
| |
| @noindent |
| GNAT follows this recommendation, and goes further by also applying |
| this recommendation to the overlaid variable (@code{A} |
| in the above example) in this case. This means that the overlay |
| works "as expected", in that a modification to one of the variables |
| will affect the value of the other. |
| |
| @node Effect of Convention on Representation |
| @section Effect of Convention on Representation |
| @cindex Convention, effect on representation |
| |
| @noindent |
| Normally the specification of a foreign language convention for a type or |
| an object has no effect on the chosen representation. In particular, the |
| representation chosen for data in GNAT generally meets the standard system |
| conventions, and for example records are laid out in a manner that is |
| consistent with C@. This means that specifying convention C (for example) |
| has no effect. |
| |
| There are three exceptions to this general rule: |
| |
| @itemize @bullet |
| |
| @item Convention Fortran and array subtypes |
| If pragma Convention Fortran is specified for an array subtype, then in |
| accordance with the implementation advice in section 3.6.2(11) of the |
| Ada Reference Manual, the array will be stored in a Fortran-compatible |
| column-major manner, instead of the normal default row-major order. |
| |
| @item Convention C and enumeration types |
| GNAT normally stores enumeration types in 8, 16, or 32 bits as required |
| to accommodate all values of the type. For example, for the enumeration |
| type declared by: |
| |
| @smallexample @c ada |
| type Color is (Red, Green, Blue); |
| @end smallexample |
| |
| @noindent |
| 8 bits is sufficient to store all values of the type, so by default, objects |
| of type @code{Color} will be represented using 8 bits. However, normal C |
| convention is to use 32 bits for all enum values in C, since enum values |
| are essentially of type int. If pragma @code{Convention C} is specified for an |
| Ada enumeration type, then the size is modified as necessary (usually to |
| 32 bits) to be consistent with the C convention for enum values. |
| |
| @item Convention C/Fortran and Boolean types |
| In C, the usual convention for boolean values, that is values used for |
| conditions, is that zero represents false, and nonzero values represent |
| true. In Ada, the normal convention is that two specific values, typically |
| 0/1, are used to represent false/true respectively. |
| |
| Fortran has a similar convention for @code{LOGICAL} values (any nonzero |
| value represents true). |
| |
| To accommodate the Fortran and C conventions, if a pragma Convention specifies |
| C or Fortran convention for a derived Boolean, as in the following example: |
| |
| @smallexample @c ada |
| type C_Switch is new Boolean; |
| pragma Convention (C, C_Switch); |
| @end smallexample |
| |
| @noindent |
| then the GNAT generated code will treat any nonzero value as true. For truth |
| values generated by GNAT, the conventional value 1 will be used for True, but |
| when one of these values is read, any nonzero value is treated as True. |
| |
| @end itemize |
| |
| @node Determining the Representations chosen by GNAT |
| @section Determining the Representations chosen by GNAT |
| @cindex Representation, determination of |
| @cindex @code{-gnatR} switch |
| |
| @noindent |
| Although the descriptions in this section are intended to be complete, it is |
| often easier to simply experiment to see what GNAT accepts and what the |
| effect is on the layout of types and objects. |
| |
| As required by the Ada RM, if a representation clause is not accepted, then |
| it must be rejected as illegal by the compiler. However, when a |
| representation clause or pragma is accepted, there can still be questions |
| of what the compiler actually does. For example, if a partial record |
| representation clause specifies the location of some components and not |
| others, then where are the non-specified components placed? Or if pragma |
| @code{Pack} is used on a record, then exactly where are the resulting |
| fields placed? The section on pragma @code{Pack} in this chapter can be |
| used to answer the second question, but it is often easier to just see |
| what the compiler does. |
| |
| For this purpose, GNAT provides the option @code{-gnatR}. If you compile |
| with this option, then the compiler will output information on the actual |
| representations chosen, in a format similar to source representation |
| clauses. For example, if we compile the package: |
| |
| @smallexample @c ada |
| package q is |
| type r (x : boolean) is tagged record |
| case x is |
| when True => S : String (1 .. 100); |
| when False => null; |
| end case; |
| end record; |
| |
| type r2 is new r (false) with record |
| y2 : integer; |
| end record; |
| |
| for r2 use record |
| y2 at 16 range 0 .. 31; |
| end record; |
| |
| type x is record |
| y : character; |
| end record; |
| |
| type x1 is array (1 .. 10) of x; |
| for x1'component_size use 11; |
| |
| type ia is access integer; |
| |
| type Rb1 is array (1 .. 13) of Boolean; |
| pragma Pack (rb1); |
| |
| type Rb2 is array (1 .. 65) of Boolean; |
| pragma Pack (rb2); |
| |
| type x2 is record |
| l1 : Boolean; |
| l2 : Duration; |
| l3 : Float; |
| l4 : Boolean; |
| l5 : Rb1; |
| l6 : Rb2; |
| end record; |
| pragma Pack (x2); |
| end q; |
| @end smallexample |
| |
| @noindent |
| using the switch @code{-gnatR} we obtain the following output: |
| |
| @smallexample |
| Representation information for unit q |
| ------------------------------------- |
| |
| for r'Size use ??; |
| for r'Alignment use 4; |
| for r use record |
| x at 4 range 0 .. 7; |
| _tag at 0 range 0 .. 31; |
| s at 5 range 0 .. 799; |
| end record; |
| |
| for r2'Size use 160; |
| for r2'Alignment use 4; |
| for r2 use record |
| x at 4 range 0 .. 7; |
| _tag at 0 range 0 .. 31; |
| _parent at 0 range 0 .. 63; |
| y2 at 16 range 0 .. 31; |
| end record; |
| |
| for x'Size use 8; |
| for x'Alignment use 1; |
| for x use record |
| y at 0 range 0 .. 7; |
| end record; |
| |
| for x1'Size use 112; |
| for x1'Alignment use 1; |
| for x1'Component_Size use 11; |
| |
| for rb1'Size use 13; |
| for rb1'Alignment use 2; |
| for rb1'Component_Size use 1; |
| |
| for rb2'Size use 72; |
| for rb2'Alignment use 1; |
| for rb2'Component_Size use 1; |
| |
| for x2'Size use 224; |
| for x2'Alignment use 4; |
| for x2 use record |
| l1 at 0 range 0 .. 0; |
| l2 at 0 range 1 .. 64; |
| l3 at 12 range 0 .. 31; |
| l4 at 16 range 0 .. 0; |
| l5 at 16 range 1 .. 13; |
| l6 at 18 range 0 .. 71; |
| end record; |
| @end smallexample |
| |
| @noindent |
| The Size values are actually the Object_Size, i.e.@: the default size that |
| will be allocated for objects of the type. |
| The ?? size for type r indicates that we have a variant record, and the |
| actual size of objects will depend on the discriminant value. |
| |
| The Alignment values show the actual alignment chosen by the compiler |
| for each record or array type. |
| |
| The record representation clause for type r shows where all fields |
| are placed, including the compiler generated tag field (whose location |
| cannot be controlled by the programmer). |
| |
| The record representation clause for the type extension r2 shows all the |
| fields present, including the parent field, which is a copy of the fields |
| of the parent type of r2, i.e.@: r1. |
| |
| The component size and size clauses for types rb1 and rb2 show |
| the exact effect of pragma @code{Pack} on these arrays, and the record |
| representation clause for type x2 shows how pragma @code{Pack} affects |
| this record type. |
| |
| In some cases, it may be useful to cut and paste the representation clauses |
| generated by the compiler into the original source to fix and guarantee |
| the actual representation to be used. |
| |
| @node Standard Library Routines |
| @chapter Standard Library Routines |
| |
| @noindent |
| The Ada 95 Reference Manual contains in Annex A a full description of an |
| extensive set of standard library routines that can be used in any Ada |
| program, and which must be provided by all Ada compilers. They are |
| analogous to the standard C library used by C programs. |
| |
| GNAT implements all of the facilities described in annex A, and for most |
| purposes the description in the Ada 95 |
| reference manual, or appropriate Ada |
| text book, will be sufficient for making use of these facilities. |
| |
| In the case of the input-output facilities, |
| @xref{The Implementation of Standard I/O}, |
| gives details on exactly how GNAT interfaces to the |
| file system. For the remaining packages, the Ada 95 reference manual |
| should be sufficient. The following is a list of the packages included, |
| together with a brief description of the functionality that is provided. |
| |
| For completeness, references are included to other predefined library |
| routines defined in other sections of the Ada 95 reference manual (these are |
| cross-indexed from annex A). |
| |
| @table @code |
| @item Ada (A.2) |
| This is a parent package for all the standard library packages. It is |
| usually included implicitly in your program, and itself contains no |
| useful data or routines. |
| |
| @item Ada.Calendar (9.6) |
| @code{Calendar} provides time of day access, and routines for |
| manipulating times and durations. |
| |
| @item Ada.Characters (A.3.1) |
| This is a dummy parent package that contains no useful entities |
| |
| @item Ada.Characters.Handling (A.3.2) |
| This package provides some basic character handling capabilities, |
| including classification functions for classes of characters (e.g.@: test |
| for letters, or digits). |
| |
| @item Ada.Characters.Latin_1 (A.3.3) |
| This package includes a complete set of definitions of the characters |
| that appear in type CHARACTER@. It is useful for writing programs that |
| will run in international environments. For example, if you want an |
| upper case E with an acute accent in a string, it is often better to use |
| the definition of @code{UC_E_Acute} in this package. Then your program |
| will print in an understandable manner even if your environment does not |
| support these extended characters. |
| |
| @item Ada.Command_Line (A.15) |
| This package provides access to the command line parameters and the name |
| of the current program (analogous to the use of @code{argc} and @code{argv} |
| in C), and also allows the exit status for the program to be set in a |
| system-independent manner. |
| |
| @item Ada.Decimal (F.2) |
| This package provides constants describing the range of decimal numbers |
| implemented, and also a decimal divide routine (analogous to the COBOL |
| verb DIVIDE .. GIVING .. REMAINDER ..) |
| |
| @item Ada.Direct_IO (A.8.4) |
| This package provides input-output using a model of a set of records of |
| fixed-length, containing an arbitrary definite Ada type, indexed by an |
| integer record number. |
| |
| @item Ada.Dynamic_Priorities (D.5) |
| This package allows the priorities of a task to be adjusted dynamically |
| as the task is running. |
| |
| @item Ada.Exceptions (11.4.1) |
| This package provides additional information on exceptions, and also |
| contains facilities for treating exceptions as data objects, and raising |
| exceptions with associated messages. |
| |
| @item Ada.Finalization (7.6) |
| This package contains the declarations and subprograms to support the |
| use of controlled types, providing for automatic initialization and |
| finalization (analogous to the constructors and destructors of C++) |
| |
| @item Ada.Interrupts (C.3.2) |
| This package provides facilities for interfacing to interrupts, which |
| includes the set of signals or conditions that can be raised and |
| recognized as interrupts. |
| |
| @item Ada.Interrupts.Names (C.3.2) |
| This package provides the set of interrupt names (actually signal |
| or condition names) that can be handled by GNAT@. |
| |
| @item Ada.IO_Exceptions (A.13) |
| This package defines the set of exceptions that can be raised by use of |
| the standard IO packages. |
| |
| @item Ada.Numerics |
| This package contains some standard constants and exceptions used |
| throughout the numerics packages. Note that the constants pi and e are |
| defined here, and it is better to use these definitions than rolling |
| your own. |
| |
| @item Ada.Numerics.Complex_Elementary_Functions |
| Provides the implementation of standard elementary functions (such as |
| log and trigonometric functions) operating on complex numbers using the |
| standard @code{Float} and the @code{Complex} and @code{Imaginary} types |
| created by the package @code{Numerics.Complex_Types}. |
| |
| @item Ada.Numerics.Complex_Types |
| This is a predefined instantiation of |
| @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to |
| build the type @code{Complex} and @code{Imaginary}. |
| |
| @item Ada.Numerics.Discrete_Random |
| This package provides a random number generator suitable for generating |
| random integer values from a specified range. |
| |
| @item Ada.Numerics.Float_Random |
| This package provides a random number generator suitable for generating |
| uniformly distributed floating point values. |
| |
| @item Ada.Numerics.Generic_Complex_Elementary_Functions |
| This is a generic version of the package that provides the |
| implementation of standard elementary functions (such as log and |
| trigonometric functions) for an arbitrary complex type. |
| |
| The following predefined instantiations of this package are provided: |
| |
| @table @code |
| @item Short_Float |
| @code{Ada.Numerics.Short_Complex_Elementary_Functions} |
| @item Float |
| @code{Ada.Numerics.Complex_Elementary_Functions} |
| @item Long_Float |
| @code{Ada.Numerics. |
| Long_Complex_Elementary_Functions} |
| @end table |
| |
| @item Ada.Numerics.Generic_Complex_Types |
| This is a generic package that allows the creation of complex types, |
| with associated complex arithmetic operations. |
| |
| The following predefined instantiations of this package exist |
| @table @code |
| @item Short_Float |
| @code{Ada.Numerics.Short_Complex_Complex_Types} |
| @item Float |
| @code{Ada.Numerics.Complex_Complex_Types} |
| @item Long_Float |
| @code{Ada.Numerics.Long_Complex_Complex_Types} |
| @end table |
| |
| @item Ada.Numerics.Generic_Elementary_Functions |
| This is a generic package that provides the implementation of standard |
| elementary functions (such as log an trigonometric functions) for an |
| arbitrary float type. |
| |
| The following predefined instantiations of this package exist |
| |
| @table @code |
| @item Short_Float |
| @code{Ada.Numerics.Short_Elementary_Functions} |
| @item Float |
| @code{Ada.Numerics.Elementary_Functions} |
| @item Long_Float |
| @code{Ada.Numerics.Long_Elementary_Functions} |
| @end table |
| |
| @item Ada.Real_Time (D.8) |
| This package provides facilities similar to those of @code{Calendar}, but |
| operating with a finer clock suitable for real time control. Note that |
| annex D requires that there be no backward clock jumps, and GNAT generally |
| guarantees this behavior, but of course if the external clock on which |
| the GNAT runtime depends is deliberately reset by some external event, |
| then such a backward jump may occur. |
| |
| @item Ada.Sequential_IO (A.8.1) |
| This package provides input-output facilities for sequential files, |
| which can contain a sequence of values of a single type, which can be |
| any Ada type, including indefinite (unconstrained) types. |
| |
| @item Ada.Storage_IO (A.9) |
| This package provides a facility for mapping arbitrary Ada types to and |
| from a storage buffer. It is primarily intended for the creation of new |
| IO packages. |
| |
| @item Ada.Streams (13.13.1) |
| This is a generic package that provides the basic support for the |
| concept of streams as used by the stream attributes (@code{Input}, |
| @code{Output}, @code{Read} and @code{Write}). |
| |
| @item Ada.Streams.Stream_IO (A.12.1) |
| This package is a specialization of the type @code{Streams} defined in |
| package @code{Streams} together with a set of operations providing |
| Stream_IO capability. The Stream_IO model permits both random and |
| sequential access to a file which can contain an arbitrary set of values |
| of one or more Ada types. |
| |
| @item Ada.Strings (A.4.1) |
| This package provides some basic constants used by the string handling |
| packages. |
| |
| @item Ada.Strings.Bounded (A.4.4) |
| This package provides facilities for handling variable length |
| strings. The bounded model requires a maximum length. It is thus |
| somewhat more limited than the unbounded model, but avoids the use of |
| dynamic allocation or finalization. |
| |
| @item Ada.Strings.Fixed (A.4.3) |
| This package provides facilities for handling fixed length strings. |
| |
| @item Ada.Strings.Maps (A.4.2) |
| This package provides facilities for handling character mappings and |
| arbitrarily defined subsets of characters. For instance it is useful in |
| defining specialized translation tables. |
| |
| @item Ada.Strings.Maps.Constants (A.4.6) |
| This package provides a standard set of predefined mappings and |
| predefined character sets. For example, the standard upper to lower case |
| conversion table is found in this package. Note that upper to lower case |
| conversion is non-trivial if you want to take the entire set of |
| characters, including extended characters like E with an acute accent, |
| into account. You should use the mappings in this package (rather than |
| adding 32 yourself) to do case mappings. |
| |
| @item Ada.Strings.Unbounded (A.4.5) |
| This package provides facilities for handling variable length |
| strings. The unbounded model allows arbitrary length strings, but |
| requires the use of dynamic allocation and finalization. |
| |
| @item Ada.Strings.Wide_Bounded (A.4.7) |
| @itemx Ada.Strings.Wide_Fixed (A.4.7) |
| @itemx Ada.Strings.Wide_Maps (A.4.7) |
| @itemx Ada.Strings.Wide_Maps.Constants (A.4.7) |
| @itemx Ada.Strings.Wide_Unbounded (A.4.7) |
| These packages provide analogous capabilities to the corresponding |
| packages without @samp{Wide_} in the name, but operate with the types |
| @code{Wide_String} and @code{Wide_Character} instead of @code{String} |
| and @code{Character}. |
| |
| @item Ada.Strings.Wide_Wide_Bounded (A.4.7) |
| @itemx Ada.Strings.Wide_Wide_Fixed (A.4.7) |
| @itemx Ada.Strings.Wide_Wide_Maps (A.4.7) |
| @itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7) |
| @itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7) |
| These packages provide analogous capabilities to the corresponding |
| packages without @samp{Wide_} in the name, but operate with the types |
| @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead |
| of @code{String} and @code{Character}. |
| |
| @item Ada.Synchronous_Task_Control (D.10) |
| This package provides some standard facilities for controlling task |
| communication in a synchronous manner. |
| |
| @item Ada.Tags |
| This package contains definitions for manipulation of the tags of tagged |
| values. |
| |
| @item Ada.Task_Attributes |
| This package provides the capability of associating arbitrary |
| task-specific data with separate tasks. |
| |
| @item Ada.Text_IO |
| This package provides basic text input-output capabilities for |
| character, string and numeric data. The subpackages of this |
| package are listed next. |
| |
| @item Ada.Text_IO.Decimal_IO |
| Provides input-output facilities for decimal fixed-point types |
| |
| @item Ada.Text_IO.Enumeration_IO |
| Provides input-output facilities for enumeration types. |
| |
| @item Ada.Text_IO.Fixed_IO |
| Provides input-output facilities for ordinary fixed-point types. |
| |
| @item Ada.Text_IO.Float_IO |
| Provides input-output facilities for float types. The following |
| predefined instantiations of this generic package are available: |
| |
| @table @code |
| @item Short_Float |
| @code{Short_Float_Text_IO} |
| @item Float |
| @code{Float_Text_IO} |
| @item Long_Float |
| @code{Long_Float_Text_IO} |
| @end table |
| |
| @item Ada.Text_IO.Integer_IO |
| Provides input-output facilities for integer types. The following |
| predefined instantiations of this generic package are available: |
| |
| @table @code |
| @item Short_Short_Integer |
| @code{Ada.Short_Short_Integer_Text_IO} |
| @item Short_Integer |
| @code{Ada.Short_Integer_Text_IO} |
| @item Integer |
| @code{Ada.Integer_Text_IO} |
| @item Long_Integer |
| @code{Ada.Long_Integer_Text_IO} |
| @item Long_Long_Integer |
| @code{Ada.Long_Long_Integer_Text_IO} |
| @end table |
| |
| @item Ada.Text_IO.Modular_IO |
| Provides input-output facilities for modular (unsigned) types |
| |
| @item Ada.Text_IO.Complex_IO (G.1.3) |
| This package provides basic text input-output capabilities for complex |
| data. |
| |
| @item Ada.Text_IO.Editing (F.3.3) |
| This package contains routines for edited output, analogous to the use |
| of pictures in COBOL@. The picture formats used by this package are a |
| close copy of the facility in COBOL@. |
| |
| @item Ada.Text_IO.Text_Streams (A.12.2) |
| This package provides a facility that allows Text_IO files to be treated |
| as streams, so that the stream attributes can be used for writing |
| arbitrary data, including binary data, to Text_IO files. |
| |
| @item Ada.Unchecked_Conversion (13.9) |
| This generic package allows arbitrary conversion from one type to |
| another of the same size, providing for breaking the type safety in |
| special circumstances. |
| |
| If the types have the same Size (more accurately the same Value_Size), |
| then the effect is simply to transfer the bits from the source to the |
| target type without any modification. This usage is well defined, and |
| for simple types whose representation is typically the same across |
| all implementations, gives a portable method of performing such |
| conversions. |
| |
| If the types do not have the same size, then the result is implementation |
| defined, and thus may be non-portable. The following describes how GNAT |
| handles such unchecked conversion cases. |
| |
| If the types are of different sizes, and are both discrete types, then |
| the effect is of a normal type conversion without any constraint checking. |
| In particular if the result type has a larger size, the result will be |
| zero or sign extended. If the result type has a smaller size, the result |
| will be truncated by ignoring high order bits. |
| |
| If the types are of different sizes, and are not both discrete types, |
| then the conversion works as though pointers were created to the source |
| and target, and the pointer value is converted. The effect is that bits |
| are copied from successive low order storage units and bits of the source |
| up to the length of the target type. |
| |
| A warning is issued if the lengths differ, since the effect in this |
| case is implementation dependent, and the above behavior may not match |
| that of some other compiler. |
| |
| A pointer to one type may be converted to a pointer to another type using |
| unchecked conversion. The only case in which the effect is undefined is |
| when one or both pointers are pointers to unconstrained array types. In |
| this case, the bounds information may get incorrectly transferred, and in |
| particular, GNAT uses double size pointers for such types, and it is |
| meaningless to convert between such pointer types. GNAT will issue a |
| warning if the alignment of the target designated type is more strict |
| than the alignment of the source designated type (since the result may |
| be unaligned in this case). |
| |
| A pointer other than a pointer to an unconstrained array type may be |
| converted to and from System.Address. Such usage is common in Ada 83 |
| programs, but note that Ada.Address_To_Access_Conversions is the |
| preferred method of performing such conversions in Ada 95. Neither |
| unchecked conversion nor Ada.Address_To_Access_Conversions should be |
| used in conjunction with pointers to unconstrained objects, since |
| the bounds information cannot be handled correctly in this case. |
| |
| @item Ada.Unchecked_Deallocation (13.11.2) |
| This generic package allows explicit freeing of storage previously |
| allocated by use of an allocator. |
| |
| @item Ada.Wide_Text_IO (A.11) |
| This package is similar to @code{Ada.Text_IO}, except that the external |
| file supports wide character representations, and the internal types are |
| @code{Wide_Character} and @code{Wide_String} instead of @code{Character} |
| and @code{String}. It contains generic subpackages listed next. |
| |
| @item Ada.Wide_Text_IO.Decimal_IO |
| Provides input-output facilities for decimal fixed-point types |
| |
| @item Ada.Wide_Text_IO.Enumeration_IO |
| Provides input-output facilities for enumeration types. |
| |
| @item Ada.Wide_Text_IO.Fixed_IO |
| Provides input-output facilities for ordinary fixed-point types. |
| |
| @item Ada.Wide_Text_IO.Float_IO |
| Provides input-output facilities for float types. The following |
| predefined instantiations of this generic package are available: |
| |
| @table @code |
| @item Short_Float |
| @code{Short_Float_Wide_Text_IO} |
| @item Float |
| @code{Float_Wide_Text_IO} |
| @item Long_Float |
| @code{Long_Float_Wide_Text_IO} |
| @end table |
| |
| @item Ada.Wide_Text_IO.Integer_IO |
| Provides input-output facilities for integer types. The following |
| predefined instantiations of this generic package are available: |
| |
| @table @code |
| @item Short_Short_Integer |
| @code{Ada.Short_Short_Integer_Wide_Text_IO} |
| @item Short_Integer |
| @code{Ada.Short_Integer_Wide_Text_IO} |
| @item Integer |
| @code{Ada.Integer_Wide_Text_IO} |
| @item Long_Integer |
| @code{Ada.Long_Integer_Wide_Text_IO} |
| @item Long_Long_Integer |
| @code{Ada.Long_Long_Integer_Wide_Text_IO} |
| @end table |
| |
| @item Ada.Wide_Text_IO.Modular_IO |
| Provides input-output facilities for modular (unsigned) types |
| |
| @item Ada.Wide_Text_IO.Complex_IO (G.1.3) |
| This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the |
| external file supports wide character representations. |
| |
| @item Ada.Wide_Text_IO.Editing (F.3.4) |
| This package is similar to @code{Ada.Text_IO.Editing}, except that the |
| types are @code{Wide_Character} and @code{Wide_String} instead of |
| @code{Character} and @code{String}. |
| |
| @item Ada.Wide_Text_IO.Streams (A.12.3) |
| This package is similar to @code{Ada.Text_IO.Streams}, except that the |
| types are @code{Wide_Character} and @code{Wide_String} instead of |
| @code{Character} and @code{String}. |
| |
| @item Ada.Wide_Wide_Text_IO (A.11) |
| This package is similar to @code{Ada.Text_IO}, except that the external |
| file supports wide character representations, and the internal types are |
| @code{Wide_Character} and @code{Wide_String} instead of @code{Character} |
| and @code{String}. It contains generic subpackages listed next. |
| |
| @item Ada.Wide_Wide_Text_IO.Decimal_IO |
| Provides input-output facilities for decimal fixed-point types |
| |
| @item Ada.Wide_Wide_Text_IO.Enumeration_IO |
| Provides input-output facilities for enumeration types. |
| |
| @item Ada.Wide_Wide_Text_IO.Fixed_IO |
| Provides input-output facilities for ordinary fixed-point types. |
| |
| @item Ada.Wide_Wide_Text_IO.Float_IO |
| Provides input-output facilities for float types. The following |
| predefined instantiations of this generic package are available: |
| |
| @table @code |
| @item Short_Float |
| @code{Short_Float_Wide_Wide_Text_IO} |
| @item Float |
| @code{Float_Wide_Wide_Text_IO} |
| @item Long_Float |
| @code{Long_Float_Wide_Wide_Text_IO} |
| @end table |
| |
| @item Ada.Wide_Wide_Text_IO.Integer_IO |
| Provides input-output facilities for integer types. The following |
| predefined instantiations of this generic package are available: |
| |
| @table @code |
| @item Short_Short_Integer |
| @code{Ada.Short_Short_Integer_Wide_Wide_Text_IO} |
| @item Short_Integer |
| @code{Ada.Short_Integer_Wide_Wide_Text_IO} |
| @item Integer |
| @code{Ada.Integer_Wide_Wide_Text_IO} |
| @item Long_Integer |
| @code{Ada.Long_Integer_Wide_Wide_Text_IO} |
| @item Long_Long_Integer |
| @code{Ada.Long_Long_Integer_Wide_Wide_Text_IO} |
| @end table |
| |
| @item Ada.Wide_Wide_Text_IO.Modular_IO |
| Provides input-output facilities for modular (unsigned) types |
| |
| @item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3) |
| This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the |
| external file supports wide character representations. |
| |
| @item Ada.Wide_Wide_Text_IO.Editing (F.3.4) |
| This package is similar to @code{Ada.Text_IO.Editing}, except that the |
| types are @code{Wide_Character} and @code{Wide_String} instead of |
| @code{Character} and @code{String}. |
| |
| @item Ada.Wide_Wide_Text_IO.Streams (A.12.3) |
| This package is similar to @code{Ada.Text_IO.Streams}, except that the |
| types are @code{Wide_Character} and @code{Wide_String} instead of |
| @code{Character} and @code{String}. |
| @end table |
| |
| |
| |
| @node The Implementation of Standard I/O |
| @chapter The Implementation of Standard I/O |
| |
| @noindent |
| GNAT implements all the required input-output facilities described in |
| A.6 through A.14. These sections of the Ada 95 reference manual describe the |
| required behavior of these packages from the Ada point of view, and if |
| you are writing a portable Ada program that does not need to know the |
| exact manner in which Ada maps to the outside world when it comes to |
| reading or writing external files, then you do not need to read this |
| chapter. As long as your files are all regular files (not pipes or |
| devices), and as long as you write and read the files only from Ada, the |
| description in the Ada 95 reference manual is sufficient. |
| |
| However, if you want to do input-output to pipes or other devices, such |
| as the keyboard or screen, or if the files you are dealing with are |
| either generated by some other language, or to be read by some other |
| language, then you need to know more about the details of how the GNAT |
| implementation of these input-output facilities behaves. |
| |
| In this chapter we give a detailed description of exactly how GNAT |
| interfaces to the file system. As always, the sources of the system are |
| available to you for answering questions at an even more detailed level, |
| but for most purposes the information in this chapter will suffice. |
| |
| Another reason that you may need to know more about how input-output is |
| implemented arises when you have a program written in mixed languages |
| where, for example, files are shared between the C and Ada sections of |
| the same program. GNAT provides some additional facilities, in the form |
| of additional child library packages, that facilitate this sharing, and |
| these additional facilities are also described in this chapter. |
| |
| @menu |
| * Standard I/O Packages:: |
| * FORM Strings:: |
| * Direct_IO:: |
| * Sequential_IO:: |
| * Text_IO:: |
| * Wide_Text_IO:: |
| * Wide_Wide_Text_IO:: |
| * Stream_IO:: |
| * Shared Files:: |
| * Open Modes:: |
| * Operations on C Streams:: |
| * Interfacing to C Streams:: |
| @end menu |
| |
| @node Standard I/O Packages |
| @section Standard I/O Packages |
| |
| @noindent |
| The Standard I/O packages described in Annex A for |
| |
| @itemize @bullet |
| @item |
| Ada.Text_IO |
| @item |
| Ada.Text_IO.Complex_IO |
| @item |
| Ada.Text_IO.Text_Streams |
| @item |
| Ada.Wide_Text_IO |
| @item |
| Ada.Wide_Text_IO.Complex_IO |
| @item |
| Ada.Wide_Text_IO.Text_Streams |
| @item |
| Ada.Wide_Wide_Text_IO |
| @item |
| Ada.Wide_Wide_Text_IO.Complex_IO |
| @item |
| Ada.Wide_Wide_Text_IO.Text_Streams |
| @item |
| Ada.Stream_IO |
| @item |
| Ada.Sequential_IO |
| @item |
| Ada.Direct_IO |
| @end itemize |
| |
| @noindent |
| are implemented using the C |
| library streams facility; where |
| |
| @itemize @bullet |
| @item |
| All files are opened using @code{fopen}. |
| @item |
| All input/output operations use @code{fread}/@code{fwrite}. |
| @end itemize |
| |
| @noindent |
| There is no internal buffering of any kind at the Ada library level. The only |
| buffering is that provided at the system level in the implementation of the |
| library routines that support streams. This facilitates shared use of these |
| streams by mixed language programs. Note though that system level buffering is |
| explicitly enabled at elaboration of the standard I/O packages and that can |
| have an impact on mixed language programs, in particular those using I/O before |
| calling the Ada elaboration routine (e.g. adainit). It is recommended to call |
| the Ada elaboration routine before performing any I/O or when impractical, |
| flush the common I/O streams and in particular Standard_Output before |
| elaborating the Ada code. |
| |
| @node FORM Strings |
| @section FORM Strings |
| |
| @noindent |
| The format of a FORM string in GNAT is: |
| |
| @smallexample |
| "keyword=value,keyword=value,@dots{},keyword=value" |
| @end smallexample |
| |
| @noindent |
| where letters may be in upper or lower case, and there are no spaces |
| between values. The order of the entries is not important. Currently |
| there are two keywords defined. |
| |
| @smallexample |
| SHARED=[YES|NO] |
| WCEM=[n|h|u|s\e] |
| @end smallexample |
| |
| @noindent |
| The use of these parameters is described later in this section. |
| |
| @node Direct_IO |
| @section Direct_IO |
| |
| @noindent |
| Direct_IO can only be instantiated for definite types. This is a |
| restriction of the Ada language, which means that the records are fixed |
| length (the length being determined by @code{@var{type}'Size}, rounded |
| up to the next storage unit boundary if necessary). |
| |
| The records of a Direct_IO file are simply written to the file in index |
| sequence, with the first record starting at offset zero, and subsequent |
| records following. There is no control information of any kind. For |
| example, if 32-bit integers are being written, each record takes |
| 4-bytes, so the record at index @var{K} starts at offset |
| (@var{K}@minus{}1)*4. |
| |
| There is no limit on the size of Direct_IO files, they are expanded as |
| necessary to accommodate whatever records are written to the file. |
| |
| @node Sequential_IO |
| @section Sequential_IO |
| |
| @noindent |
| Sequential_IO may be instantiated with either a definite (constrained) |
| or indefinite (unconstrained) type. |
| |
| For the definite type case, the elements written to the file are simply |
| the memory images of the data values with no control information of any |
| kind. The resulting file should be read using the same type, no validity |
| checking is performed on input. |
| |
| For the indefinite type case, the elements written consist of two |
| parts. First is the size of the data item, written as the memory image |
| of a @code{Interfaces.C.size_t} value, followed by the memory image of |
| the data value. The resulting file can only be read using the same |
| (unconstrained) type. Normal assignment checks are performed on these |
| read operations, and if these checks fail, @code{Data_Error} is |
| raised. In particular, in the array case, the lengths must match, and in |
| the variant record case, if the variable for a particular read operation |
| is constrained, the discriminants must match. |
| |
| Note that it is not possible to use Sequential_IO to write variable |
| length array items, and then read the data back into different length |
| arrays. For example, the following will raise @code{Data_Error}: |
| |
| @smallexample @c ada |
| package IO is new Sequential_IO (String); |
| F : IO.File_Type; |
| S : String (1..4); |
| @dots{} |
| IO.Create (F) |
| IO.Write (F, "hello!") |
| IO.Reset (F, Mode=>In_File); |
| IO.Read (F, S); |
| Put_Line (S); |
| |
| @end smallexample |
| |
| @noindent |
| On some Ada implementations, this will print @code{hell}, but the program is |
| clearly incorrect, since there is only one element in the file, and that |
| element is the string @code{hello!}. |
| |
| In Ada 95, this kind of behavior can be legitimately achieved using |
| Stream_IO, and this is the preferred mechanism. In particular, the above |
| program fragment rewritten to use Stream_IO will work correctly. |
| |
| @node Text_IO |
| @section Text_IO |
| |
| @noindent |
| Text_IO files consist of a stream of characters containing the following |
| special control characters: |
| |
| @smallexample |
| LF (line feed, 16#0A#) Line Mark |
| FF (form feed, 16#0C#) Page Mark |
| @end smallexample |
| |
| @noindent |
| A canonical Text_IO file is defined as one in which the following |
| conditions are met: |
| |
| @itemize @bullet |
| @item |
| The character @code{LF} is used only as a line mark, i.e.@: to mark the end |
| of the line. |
| |
| @item |
| The character @code{FF} is used only as a page mark, i.e.@: to mark the |
| end of a page and consequently can appear only immediately following a |
| @code{LF} (line mark) character. |
| |
| @item |
| The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF} |
| (line mark, page mark). In the former case, the page mark is implicitly |
| assumed to be present. |
| @end itemize |
| |
| @noindent |
| A file written using Text_IO will be in canonical form provided that no |
| explicit @code{LF} or @code{FF} characters are written using @code{Put} |
| or @code{Put_Line}. There will be no @code{FF} character at the end of |
| the file unless an explicit @code{New_Page} operation was performed |
| before closing the file. |
| |
| A canonical Text_IO file that is a regular file, i.e.@: not a device or a |
| pipe, can be read using any of the routines in Text_IO@. The |
| semantics in this case will be exactly as defined in the Ada 95 reference |
| manual and all the routines in Text_IO are fully implemented. |
| |
| A text file that does not meet the requirements for a canonical Text_IO |
| file has one of the following: |
| |
| @itemize @bullet |
| @item |
| The file contains @code{FF} characters not immediately following a |
| @code{LF} character. |
| |
| @item |
| The file contains @code{LF} or @code{FF} characters written by |
| @code{Put} or @code{Put_Line}, which are not logically considered to be |
| line marks or page marks. |
| |
| @item |
| The file ends in a character other than @code{LF} or @code{FF}, |
| i.e.@: there is no explicit line mark or page mark at the end of the file. |
| @end itemize |
| |
| @noindent |
| Text_IO can be used to read such non-standard text files but subprograms |
| to do with line or page numbers do not have defined meanings. In |
| particular, a @code{FF} character that does not follow a @code{LF} |
| character may or may not be treated as a page mark from the point of |
| view of page and line numbering. Every @code{LF} character is considered |
| to end a line, and there is an implied @code{LF} character at the end of |
| the file. |
| |
| @menu |
| * Text_IO Stream Pointer Positioning:: |
| * Text_IO Reading and Writing Non-Regular Files:: |
| * Get_Immediate:: |
| * Treating Text_IO Files as Streams:: |
| * Text_IO Extensions:: |
| * Text_IO Facilities for Unbounded Strings:: |
| @end menu |
| |
| @node Text_IO Stream Pointer Positioning |
| @subsection Stream Pointer Positioning |
| |
| @noindent |
| @code{Ada.Text_IO} has a definition of current position for a file that |
| is being read. No internal buffering occurs in Text_IO, and usually the |
| physical position in the stream used to implement the file corresponds |
| to this logical position defined by Text_IO@. There are two exceptions: |
| |
| @itemize @bullet |
| @item |
| After a call to @code{End_Of_Page} that returns @code{True}, the stream |
| is positioned past the @code{LF} (line mark) that precedes the page |
| mark. Text_IO maintains an internal flag so that subsequent read |
| operations properly handle the logical position which is unchanged by |
| the @code{End_Of_Page} call. |
| |
| @item |
| After a call to @code{End_Of_File} that returns @code{True}, if the |
| Text_IO file was positioned before the line mark at the end of file |
| before the call, then the logical position is unchanged, but the stream |
| is physically positioned right at the end of file (past the line mark, |
| and past a possible page mark following the line mark. Again Text_IO |
| maintains internal flags so that subsequent read operations properly |
| handle the logical position. |
| @end itemize |
| |
| @noindent |
| These discrepancies have no effect on the observable behavior of |
| Text_IO, but if a single Ada stream is shared between a C program and |
| Ada program, or shared (using @samp{shared=yes} in the form string) |
| between two Ada files, then the difference may be observable in some |
| situations. |
| |
| @node Text_IO Reading and Writing Non-Regular Files |
| @subsection Reading and Writing Non-Regular Files |
| |
| @noindent |
| A non-regular file is a device (such as a keyboard), or a pipe. Text_IO |
| can be used for reading and writing. Writing is not affected and the |
| sequence of characters output is identical to the normal file case, but |
| for reading, the behavior of Text_IO is modified to avoid undesirable |
| look-ahead as follows: |
| |
| An input file that is not a regular file is considered to have no page |
| marks. Any @code{Ascii.FF} characters (the character normally used for a |
| page mark) appearing in the file are considered to be data |
| characters. In particular: |
| |
| @itemize @bullet |
| @item |
| @code{Get_Line} and @code{Skip_Line} do not test for a page mark |
| following a line mark. If a page mark appears, it will be treated as a |
| data character. |
| |
| @item |
| This avoids the need to wait for an extra character to be typed or |
| entered from the pipe to complete one of these operations. |
| |
| @item |
| @code{End_Of_Page} always returns @code{False} |
| |
| @item |
| @code{End_Of_File} will return @code{False} if there is a page mark at |
| the end of the file. |
| @end itemize |
| |
| @noindent |
| Output to non-regular files is the same as for regular files. Page marks |
| may be written to non-regular files using @code{New_Page}, but as noted |
| above they will not be treated as page marks on input if the output is |
| piped to another Ada program. |
| |
| Another important discrepancy when reading non-regular files is that the end |
| of file indication is not ``sticky''. If an end of file is entered, e.g.@: by |
| pressing the @key{EOT} key, |
| then end of file |
| is signaled once (i.e.@: the test @code{End_Of_File} |
| will yield @code{True}, or a read will |
| raise @code{End_Error}), but then reading can resume |
| to read data past that end of |
| file indication, until another end of file indication is entered. |
| |
| @node Get_Immediate |
| @subsection Get_Immediate |
| @cindex Get_Immediate |
| |
| @noindent |
| Get_Immediate returns the next character (including control characters) |
| from the input file. In particular, Get_Immediate will return LF or FF |
| characters used as line marks or page marks. Such operations leave the |
| file positioned past the control character, and it is thus not treated |
| as having its normal function. This means that page, line and column |
| counts after this kind of Get_Immediate call are set as though the mark |
| did not occur. In the case where a Get_Immediate leaves the file |
| positioned between the line mark and page mark (which is not normally |
| possible), it is undefined whether the FF character will be treated as a |
| page mark. |
| |
| @node Treating Text_IO Files as Streams |
| @subsection Treating Text_IO Files as Streams |
| @cindex Stream files |
| |
| @noindent |
| The package @code{Text_IO.Streams} allows a Text_IO file to be treated |
| as a stream. Data written to a Text_IO file in this stream mode is |
| binary data. If this binary data contains bytes 16#0A# (@code{LF}) or |
| 16#0C# (@code{FF}), the resulting file may have non-standard |
| format. Similarly if read operations are used to read from a Text_IO |
| file treated as a stream, then @code{LF} and @code{FF} characters may be |
| skipped and the effect is similar to that described above for |
| @code{Get_Immediate}. |
| |
| @node Text_IO Extensions |
| @subsection Text_IO Extensions |
| @cindex Text_IO extensions |
| |
| @noindent |
| A package GNAT.IO_Aux in the GNAT library provides some useful extensions |
| to the standard @code{Text_IO} package: |
| |
| @itemize @bullet |
| @item function File_Exists (Name : String) return Boolean; |
| Determines if a file of the given name exists. |
| |
| @item function Get_Line return String; |
| Reads a string from the standard input file. The value returned is exactly |
| the length of the line that was read. |
| |
| @item function Get_Line (File : Ada.Text_IO.File_Type) return String; |
| Similar, except that the parameter File specifies the file from which |
| the string is to be read. |
| |
| @end itemize |
| |
| @node Text_IO Facilities for Unbounded Strings |
| @subsection Text_IO Facilities for Unbounded Strings |
| @cindex Text_IO for unbounded strings |
| @cindex Unbounded_String, Text_IO operations |
| |
| @noindent |
| The package @code{Ada.Strings.Unbounded.Text_IO} |
| in library files @code{a-suteio.ads/adb} contains some GNAT-specific |
| subprograms useful for Text_IO operations on unbounded strings: |
| |
| @itemize @bullet |
| |
| @item function Get_Line (File : File_Type) return Unbounded_String; |
| Reads a line from the specified file |
| and returns the result as an unbounded string. |
| |
| @item procedure Put (File : File_Type; U : Unbounded_String); |
| Writes the value of the given unbounded string to the specified file |
| Similar to the effect of |
| @code{Put (To_String (U))} except that an extra copy is avoided. |
| |
| @item procedure Put_Line (File : File_Type; U : Unbounded_String); |
| Writes the value of the given unbounded string to the specified file, |
| followed by a @code{New_Line}. |
| Similar to the effect of @code{Put_Line (To_String (U))} except |
| that an extra copy is avoided. |
| @end itemize |
| |
| @noindent |
| In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} |
| and is optional. If the parameter is omitted, then the standard input or |
| output file is referenced as appropriate. |
| |
| The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library |
| files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended |
| @code{Wide_Text_IO} functionality for unbounded wide strings. |
| |
| The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library |
| files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended |
| @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. |
| |
| @node Wide_Text_IO |
| @section Wide_Text_IO |
| |
| @noindent |
| @code{Wide_Text_IO} is similar in most respects to Text_IO, except that |
| both input and output files may contain special sequences that represent |
| wide character values. The encoding scheme for a given file may be |
| specified using a FORM parameter: |
| |
| @smallexample |
| WCEM=@var{x} |
| @end smallexample |
| |
| @noindent |
| as part of the FORM string (WCEM = wide character encoding method), |
| where @var{x} is one of the following characters |
| |
| @table @samp |
| @item h |
| Hex ESC encoding |
| @item u |
| Upper half encoding |
| @item s |
| Shift-JIS encoding |
| @item e |
| EUC Encoding |
| @item 8 |
| UTF-8 encoding |
| @item b |
| Brackets encoding |
| @end table |
| |
| @noindent |
| The encoding methods match those that |
| can be used in a source |
| program, but there is no requirement that the encoding method used for |
| the source program be the same as the encoding method used for files, |
| and different files may use different encoding methods. |
| |
| The default encoding method for the standard files, and for opened files |
| for which no WCEM parameter is given in the FORM string matches the |
| wide character encoding specified for the main program (the default |
| being brackets encoding if no coding method was specified with -gnatW). |
| |
| @table @asis |
| @item Hex Coding |
| In this encoding, a wide character is represented by a five character |
| sequence: |
| |
| @smallexample |
| ESC a b c d |
| @end smallexample |
| |
| @noindent |
| where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal |
| characters (using upper case letters) of the wide character code. For |
| example, ESC A345 is used to represent the wide character with code |
| 16#A345#. This scheme is compatible with use of the full |
| @code{Wide_Character} set. |
| |
| @item Upper Half Coding |
| The wide character with encoding 16#abcd#, where the upper bit is on |
| (i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and |
| 16#cd#. The second byte may never be a format control character, but is |
| not required to be in the upper half. This method can be also used for |
| shift-JIS or EUC where the internal coding matches the external coding. |
| |
| @item Shift JIS Coding |
| A wide character is represented by a two character sequence 16#ab# and |
| 16#cd#, with the restrictions described for upper half encoding as |
| described above. The internal character code is the corresponding JIS |
| character according to the standard algorithm for Shift-JIS |
| conversion. Only characters defined in the JIS code set table can be |
| used with this encoding method. |
| |
| @item EUC Coding |
| A wide character is represented by a two character sequence 16#ab# and |
| 16#cd#, with both characters being in the upper half. The internal |
| character code is the corresponding JIS character according to the EUC |
| encoding algorithm. Only characters defined in the JIS code set table |
| can be used with this encoding method. |
| |
| @item UTF-8 Coding |
| A wide character is represented using |
| UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO |
| 10646-1/Am.2. Depending on the character value, the representation |
| is a one, two, or three byte sequence: |
| |
| @smallexample |
| 16#0000#-16#007f#: 2#0xxxxxxx# |
| 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# |
| 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# |
| @end smallexample |
| |
| @noindent |
| where the xxx bits correspond to the left-padded bits of the |
| 16-bit character value. Note that all lower half ASCII characters |
| are represented as ASCII bytes and all upper half characters and |
| other wide characters are represented as sequences of upper-half |
| (The full UTF-8 scheme allows for encoding 31-bit characters as |
| 6-byte sequences, but in this implementation, all UTF-8 sequences |
| of four or more bytes length will raise a Constraint_Error, as |
| will all invalid UTF-8 sequences.) |
| |
| @item Brackets Coding |
| In this encoding, a wide character is represented by the following eight |
| character sequence: |
| |
| @smallexample |
| [ " a b c d " ] |
| @end smallexample |
| |
| @noindent |
| where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal |
| characters (using uppercase letters) of the wide character code. For |
| example, @code{["A345"]} is used to represent the wide character with code |
| @code{16#A345#}. |
| This scheme is compatible with use of the full Wide_Character set. |
| On input, brackets coding can also be used for upper half characters, |
| e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation |
| is only used for wide characters with a code greater than @code{16#FF#}. |
| |
| @end table |
| |
| @noindent |
| For the coding schemes other than Hex and Brackets encoding, |
| not all wide character |
| values can be represented. An attempt to output a character that cannot |
| be represented using the encoding scheme for the file causes |
| Constraint_Error to be raised. An invalid wide character sequence on |
| input also causes Constraint_Error to be raised. |
| |
| @menu |
| * Wide_Text_IO Stream Pointer Positioning:: |
| * Wide_Text_IO Reading and Writing Non-Regular Files:: |
| @end menu |
| |
| @node Wide_Text_IO Stream Pointer Positioning |
| @subsection Stream Pointer Positioning |
| |
| @noindent |
| @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling |
| of stream pointer positioning (@pxref{Text_IO}). There is one additional |
| case: |
| |
| If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the |
| normal lower ASCII set (i.e.@: a character in the range: |
| |
| @smallexample @c ada |
| Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) |
| @end smallexample |
| |
| @noindent |
| then although the logical position of the file pointer is unchanged by |
| the @code{Look_Ahead} call, the stream is physically positioned past the |
| wide character sequence. Again this is to avoid the need for buffering |
| or backup, and all @code{Wide_Text_IO} routines check the internal |
| indication that this situation has occurred so that this is not visible |
| to a normal program using @code{Wide_Text_IO}. However, this discrepancy |
| can be observed if the wide text file shares a stream with another file. |
| |
| @node Wide_Text_IO Reading and Writing Non-Regular Files |
| @subsection Reading and Writing Non-Regular Files |
| |
| @noindent |
| As in the case of Text_IO, when a non-regular file is read, it is |
| assumed that the file contains no page marks (any form characters are |
| treated as data characters), and @code{End_Of_Page} always returns |
| @code{False}. Similarly, the end of file indication is not sticky, so |
| it is possible to read beyond an end of file. |
| |
| @node Wide_Wide_Text_IO |
| @section Wide_Wide_Text_IO |
| |
| @noindent |
| @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that |
| both input and output files may contain special sequences that represent |
| wide wide character values. The encoding scheme for a given file may be |
| specified using a FORM parameter: |
| |
| @smallexample |
| WCEM=@var{x} |
| @end smallexample |
| |
| @noindent |
| as part of the FORM string (WCEM = wide character encoding method), |
| where @var{x} is one of the following characters |
| |
| @table @samp |
| @item h |
| Hex ESC encoding |
| @item u |
| Upper half encoding |
| @item s |
| Shift-JIS encoding |
| @item e |
| EUC Encoding |
| @item 8 |
| UTF-8 encoding |
| @item b |
| Brackets encoding |
| @end table |
| |
| @noindent |
| The encoding methods match those that |
| can be used in a source |
| program, but there is no requirement that the encoding method used for |
| the source program be the same as the encoding method used for files, |
| and different files may use different encoding methods. |
| |
| The default encoding method for the standard files, and for opened files |
| for which no WCEM parameter is given in the FORM string matches the |
| wide character encoding specified for the main program (the default |
| being brackets encoding if no coding method was specified with -gnatW). |
| |
| @table @asis |
| |
| @item UTF-8 Coding |
| A wide character is represented using |
| UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO |
| 10646-1/Am.2. Depending on the character value, the representation |
| is a one, two, three, or four byte sequence: |
| |
| @smallexample |
| 16#000000#-16#00007f#: 2#0xxxxxxx# |
| 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# |
| 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# |
| 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# |
| @end smallexample |
| |
| @noindent |
| where the xxx bits correspond to the left-padded bits of the |
| 21-bit character value. Note that all lower half ASCII characters |
| are represented as ASCII bytes and all upper half characters and |
| other wide characters are represented as sequences of upper-half |
| characters. |
| |
| @item Brackets Coding |
| In this encoding, a wide wide character is represented by the following eight |
| character sequence if is in wide character range |
| |
| @smallexample |
| [ " a b c d " ] |
| @end smallexample |
| |
| and by the following ten character sequence if not |
| |
| @smallexample |
| [ " a b c d e f " ] |
| @end smallexample |
| |
| @noindent |
| where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} |
| are the four or six hexadecimal |
| characters (using uppercase letters) of the wide wide character code. For |
| example, @code{["01A345"]} is used to represent the wide wide character |
| with code @code{16#01A345#}. |
| |
| This scheme is compatible with use of the full Wide_Wide_Character set. |
| On input, brackets coding can also be used for upper half characters, |
| e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation |
| is only used for wide characters with a code greater than @code{16#FF#}. |
| |
| @end table |
| |
| @noindent |
| If is also possible to use the other Wide_Character encoding methods, |
| such as Shift-JIS, but the other schemes cannot support the full range |
| of wide wide characters. |
| An attempt to output a character that cannot |
| be represented using the encoding scheme for the file causes |
| Constraint_Error to be raised. An invalid wide character sequence on |
| input also causes Constraint_Error to be raised. |
| |
| @menu |
| * Wide_Wide_Text_IO Stream Pointer Positioning:: |
| * Wide_Wide_Text_IO Reading and Writing Non-Regular Files:: |
| @end menu |
| |
| @node Wide_Wide_Text_IO Stream Pointer Positioning |
| @subsection Stream Pointer Positioning |
| |
| @noindent |
| @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling |
| of stream pointer positioning (@pxref{Text_IO}). There is one additional |
| case: |
| |
| If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the |
| normal lower ASCII set (i.e.@: a character in the range: |
| |
| @smallexample @c ada |
| Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) |
| @end smallexample |
| |
| @noindent |
| then although the logical position of the file pointer is unchanged by |
| the @code{Look_Ahead} call, the stream is physically positioned past the |
| wide character sequence. Again this is to avoid the need for buffering |
| or backup, and all @code{Wide_Wide_Text_IO} routines check the internal |
| indication that this situation has occurred so that this is not visible |
| to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy |
| can be observed if the wide text file shares a stream with another file. |
| |
| @node Wide_Wide_Text_IO Reading and Writing Non-Regular Files |
| @subsection Reading and Writing Non-Regular Files |
| |
| @noindent |
| As in the case of Text_IO, when a non-regular file is read, it is |
| assumed that the file contains no page marks (any form characters are |
| treated as data characters), and @code{End_Of_Page} always returns |
| @code{False}. Similarly, the end of file indication is not sticky, so |
| it is possible to read beyond an end of file. |
| |
| @node Stream_IO |
| @section Stream_IO |
| |
| @noindent |
| A stream file is a sequence of bytes, where individual elements are |
| written to the file as described in the Ada 95 reference manual. The type |
| @code{Stream_Element} is simply a byte. There are two ways to read or |
| write a stream file. |
| |
| @itemize @bullet |
| @item |
| The operations @code{Read} and @code{Write} directly read or write a |
| sequence of stream elements with no control information. |
| |
| @item |
| The stream attributes applied to a stream file transfer data in the |
| manner described for stream attributes. |
| @end itemize |
| |
| @node Shared Files |
| @section Shared Files |
| |
| @noindent |
| Section A.14 of the Ada 95 Reference Manual allows implementations to |
| provide a wide variety of behavior if an attempt is made to access the |
| same external file with two or more internal files. |
| |
| To provide a full range of functionality, while at the same time |
| minimizing the problems of portability caused by this implementation |
| dependence, GNAT handles file sharing as follows: |
| |
| @itemize @bullet |
| @item |
| In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt |
| to open two or more files with the same full name is considered an error |
| and is not supported. The exception @code{Use_Error} will be |
| raised. Note that a file that is not explicitly closed by the program |
| remains open until the program terminates. |
| |
| @item |
| If the form parameter @samp{shared=no} appears in the form string, the |
| file can be opened or created with its own separate stream identifier, |
| regardless of whether other files sharing the same external file are |
| opened. The exact effect depends on how the C stream routines handle |
| multiple accesses to the same external files using separate streams. |
| |
| @item |
| If the form parameter @samp{shared=yes} appears in the form string for |
| each of two or more files opened using the same full name, the same |
| stream is shared between these files, and the semantics are as described |
| in Ada 95 Reference Manual, Section A.14. |
| @end itemize |
| |
| @noindent |
| When a program that opens multiple files with the same name is ported |
| from another Ada compiler to GNAT, the effect will be that |
| @code{Use_Error} is raised. |
| |
| The documentation of the original compiler and the documentation of the |
| program should then be examined to determine if file sharing was |
| expected, and @samp{shared=@var{xxx}} parameters added to @code{Open} |
| and @code{Create} calls as required. |
| |
| When a program is ported from GNAT to some other Ada compiler, no |
| special attention is required unless the @samp{shared=@var{xxx}} form |
| parameter is used in the program. In this case, you must examine the |
| documentation of the new compiler to see if it supports the required |
| file sharing semantics, and form strings modified appropriately. Of |
| course it may be the case that the program cannot be ported if the |
| target compiler does not support the required functionality. The best |
| approach in writing portable code is to avoid file sharing (and hence |
| the use of the @samp{shared=@var{xxx}} parameter in the form string) |
| completely. |
| |
| One common use of file sharing in Ada 83 is the use of instantiations of |
| Sequential_IO on the same file with different types, to achieve |
| heterogeneous input-output. Although this approach will work in GNAT if |
| @samp{shared=yes} is specified, it is preferable in Ada 95 to use Stream_IO |
| for this purpose (using the stream attributes) |
| |
| @node Open Modes |
| @section Open Modes |
| |
| @noindent |
| @code{Open} and @code{Create} calls result in a call to @code{fopen} |
| using the mode shown in the following table: |
| |
| @sp 2 |
| @center @code{Open} and @code{Create} Call Modes |
| @smallexample |
| @b{OPEN } @b{CREATE} |
| Append_File "r+" "w+" |
| In_File "r" "w+" |
| Out_File (Direct_IO) "r+" "w" |
| Out_File (all other cases) "w" "w" |
| Inout_File "r+" "w+" |
| @end smallexample |
| |
| @noindent |
| If text file translation is required, then either @samp{b} or @samp{t} |
| is added to the mode, depending on the setting of Text. Text file |
| translation refers to the mapping of CR/LF sequences in an external file |
| to LF characters internally. This mapping only occurs in DOS and |
| DOS-like systems, and is not relevant to other systems. |
| |
| A special case occurs with Stream_IO@. As shown in the above table, the |
| file is initially opened in @samp{r} or @samp{w} mode for the |
| @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation |
| subsequently requires switching from reading to writing or vice-versa, |
| then the file is reopened in @samp{r+} mode to permit the required operation. |
| |
| @node Operations on C Streams |
| @section Operations on C Streams |
| The package @code{Interfaces.C_Streams} provides an Ada program with direct |
| access to the C library functions for operations on C streams: |
| |
| @smallexample @c adanocomment |
| package Interfaces.C_Streams is |
| -- Note: the reason we do not use the types that are in |
| -- Interfaces.C is that we want to avoid dragging in the |
| -- code in this unit if possible. |
| subtype chars is System.Address; |
| -- Pointer to null-terminated array of characters |
| subtype FILEs is System.Address; |
| -- Corresponds to the C type FILE* |
| subtype voids is System.Address; |
| -- Corresponds to the C type void* |
| subtype int is Integer; |
| subtype long is Long_Integer; |
| -- Note: the above types are subtypes deliberately, and it |
| -- is part of this spec that the above correspondences are |
| -- guaranteed. This means that it is legitimate to, for |
| -- example, use Integer instead of int. We provide these |
| -- synonyms for clarity, but in some cases it may be |
| -- convenient to use the underlying types (for example to |
| -- avoid an unnecessary dependency of a spec on the spec |
| -- of this unit). |
| type size_t is mod 2 ** Standard'Address_Size; |
| NULL_Stream : constant FILEs; |
| -- Value returned (NULL in C) to indicate an |
| -- fdopen/fopen/tmpfile error |
| ---------------------------------- |
| -- Constants Defined in stdio.h -- |
| ---------------------------------- |
| EOF : constant int; |
| -- Used by a number of routines to indicate error or |
| -- end of file |
| IOFBF : constant int; |
| IOLBF : constant int; |
| IONBF : constant int; |
| -- Used to indicate buffering mode for setvbuf call |
| SEEK_CUR : constant int; |
| SEEK_END : constant int; |
| SEEK_SET : constant int; |
| -- Used to indicate origin for fseek call |
| function stdin return FILEs; |
| function stdout return FILEs; |
| function stderr return FILEs; |
| -- Streams associated with standard files |
| -------------------------- |
| -- Standard C functions -- |
| -------------------------- |
| -- The functions selected below are ones that are |
| -- available in DOS, OS/2, UNIX and Xenix (but not |
| -- necessarily in ANSI C). These are very thin interfaces |
| -- which copy exactly the C headers. For more |
| -- documentation on these functions, see the Microsoft C |
| -- "Run-Time Library Reference" (Microsoft Press, 1990, |
| -- ISBN 1-55615-225-6), which includes useful information |
| -- on system compatibility. |
| procedure clearerr (stream : FILEs); |
| function fclose (stream : FILEs) return int; |
| function fdopen (handle : int; mode : chars) return FILEs; |
| function feof (stream : FILEs) return int; |
| function ferror (stream : FILEs) return int; |
| function fflush (stream : FILEs) return int; |
| function fgetc (stream : FILEs) return int; |
| function fgets (strng : chars; n : int; stream : FILEs) |
| return chars; |
| function fileno (stream : FILEs) return int; |
| function fopen (filename : chars; Mode : chars) |
| return FILEs; |
| -- Note: to maintain target independence, use |
| -- text_translation_required, a boolean variable defined in |
| -- a-sysdep.c to deal with the target dependent text |
| -- translation requirement. If this variable is set, |
| -- then b/t should be appended to the standard mode |
| -- argument to set the text translation mode off or on |
| -- as required. |
| function fputc (C : int; stream : FILEs) return int; |
| function fputs (Strng : chars; Stream : FILEs) return int; |
| function fread |
| (buffer : voids; |
| size : size_t; |
| count : size_t; |
| stream : FILEs) |
| return size_t; |
| function freopen |
| (filename : chars; |
| mode : chars; |
| stream : FILEs) |
| return FILEs; |
| function fseek |
| (stream : FILEs; |
| offset : long; |
| origin : int) |
| return int; |
| function ftell (stream : FILEs) return long; |
| function fwrite |
| (buffer : voids; |
| size : size_t; |
| count : size_t; |
| stream : FILEs) |
| return size_t; |
| function isatty (handle : int) return int; |
| procedure mktemp (template : chars); |
| -- The return value (which is just a pointer to template) |
| -- is discarded |
| procedure rewind (stream : FILEs); |
| function rmtmp return int; |
| function setvbuf |
| (stream : FILEs; |
| buffer : chars; |
| mode : int; |
| size : size_t) |
| return int; |
| |
| function tmpfile return FILEs; |
| function ungetc (c : int; stream : FILEs) return int; |
| function unlink (filename : chars) return int; |
| --------------------- |
| -- Extra functions -- |
| --------------------- |
| -- These functions supply slightly thicker bindings than |
| -- those above. They are derived from functions in the |
| -- C Run-Time Library, but may do a bit more work than |
| -- just directly calling one of the Library functions. |
| function is_regular_file (handle : int) return int; |
| -- Tests if given handle is for a regular file (result 1) |
| -- or for a non-regular file (pipe or device, result 0). |
| --------------------------------- |
| -- Control of Text/Binary Mode -- |
| --------------------------------- |
| -- If text_translation_required is true, then the following |
| -- functions may be used to dynamically switch a file from |
| -- binary to text mode or vice versa. These functions have |
| -- no effect if text_translation_required is false (i.e. in |
| -- normal UNIX mode). Use fileno to get a stream handle. |
| procedure set_binary_mode (handle : int); |
| procedure set_text_mode (handle : int); |
| ---------------------------- |
| -- Full Path Name support -- |
| ---------------------------- |
| procedure full_name (nam : chars; buffer : chars); |
| -- Given a NUL terminated string representing a file |
| -- name, returns in buffer a NUL terminated string |
| -- representing the full path name for the file name. |
| -- On systems where it is relevant the drive is also |
| -- part of the full path name. It is the responsibility |
| -- of the caller to pass an actual parameter for buffer |
| -- that is big enough for any full path name. Use |
| -- max_path_len given below as the size of buffer. |
| max_path_len : integer; |
| -- Maximum length of an allowable full path name on the |
| -- system, including a terminating NUL character. |
| end Interfaces.C_Streams; |
| @end smallexample |
| |
| @node Interfacing to C Streams |
| @section Interfacing to C Streams |
| |
| @noindent |
| The packages in this section permit interfacing Ada files to C Stream |
| operations. |
| |
| @smallexample @c ada |
| with Interfaces.C_Streams; |
| package Ada.Sequential_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Sequential_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Direct_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Direct_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Text_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Text_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Wide_Text_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Wide_Text_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Wide_Wide_Text_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Wide_Wide_Text_IO.C_Streams; |
| |
| with Interfaces.C_Streams; |
| package Ada.Stream_IO.C_Streams is |
| function C_Stream (F : File_Type) |
| return Interfaces.C_Streams.FILEs; |
| procedure Open |
| (File : in out File_Type; |
| Mode : in File_Mode; |
| C_Stream : in Interfaces.C_Streams.FILEs; |
| Form : in String := ""); |
| end Ada.Stream_IO.C_Streams; |
| @end smallexample |
| |
| @noindent |
| In each of these six packages, the @code{C_Stream} function obtains the |
| @code{FILE} pointer from a currently opened Ada file. It is then |
| possible to use the @code{Interfaces.C_Streams} package to operate on |
| this stream, or the stream can be passed to a C program which can |
| operate on it directly. Of course the program is responsible for |
| ensuring that only appropriate sequences of operations are executed. |
| |
| One particular use of relevance to an Ada program is that the |
| @code{setvbuf} function can be used to control the buffering of the |
| stream used by an Ada file. In the absence of such a call the standard |
| default buffering is used. |
| |
| The @code{Open} procedures in these packages open a file giving an |
| existing C Stream instead of a file name. Typically this stream is |
| imported from a C program, allowing an Ada file to operate on an |
| existing C file. |
| |
| @node The GNAT Library |
| @chapter The GNAT Library |
| |
| @noindent |
| The GNAT library contains a number of general and special purpose packages. |
| It represents functionality that the GNAT developers have found useful, and |
| which is made available to GNAT users. The packages described here are fully |
| supported, and upwards compatibility will be maintained in future releases, |
| so you can use these facilities with the confidence that the same functionality |
| will be available in future releases. |
| |
| The chapter here simply gives a brief summary of the facilities available. |
| The full documentation is found in the spec file for the package. The full |
| sources of these library packages, including both spec and body, are provided |
| with all GNAT releases. For example, to find out the full specifications of |
| the SPITBOL pattern matching capability, including a full tutorial and |
| extensive examples, look in the @file{g-spipat.ads} file in the library. |
| |
| For each entry here, the package name (as it would appear in a @code{with} |
| clause) is given, followed by the name of the corresponding spec file in |
| parentheses. The packages are children in four hierarchies, @code{Ada}, |
| @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a |
| GNAT-specific hierarchy. |
| |
| Note that an application program should only use packages in one of these |
| four hierarchies if the package is defined in the Ada Reference Manual, |
| or is listed in this section of the GNAT Programmers Reference Manual. |
| All other units should be considered internal implementation units and |
| should not be directly @code{with}'ed by application code. The use of |
| a @code{with} statement that references one of these internal implementation |
| units makes an application potentially dependent on changes in versions |
| of GNAT, and will generate a warning message. |
| |
| @menu |
| * Ada.Characters.Latin_9 (a-chlat9.ads):: |
| * Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: |
| * Ada.Characters.Wide_Latin_9 (a-cwila9.ads):: |
| * Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads):: |
| * Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads):: |
| * Ada.Command_Line.Remove (a-colire.ads):: |
| * Ada.Command_Line.Environment (a-colien.ads):: |
| * Ada.Direct_IO.C_Streams (a-diocst.ads):: |
| * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads):: |
| * Ada.Exceptions.Traceback (a-exctra.ads):: |
| * Ada.Sequential_IO.C_Streams (a-siocst.ads):: |
| * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads):: |
| * Ada.Strings.Unbounded.Text_IO (a-suteio.ads):: |
| * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads):: |
| * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads):: |
| * Ada.Text_IO.C_Streams (a-tiocst.ads):: |
| * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: |
| * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads):: |
| * GNAT.Altivec (g-altive.ads):: |
| * GNAT.Altivec.Conversions (g-altcon.ads):: |
| * GNAT.Altivec.Vector_Operations (g-alveop.ads):: |
| * GNAT.Altivec.Vector_Types (g-alvety.ads):: |
| * GNAT.Altivec.Vector_Views (g-alvevi.ads):: |
| * GNAT.Array_Split (g-arrspl.ads):: |
| * GNAT.AWK (g-awk.ads):: |
| * GNAT.Bounded_Buffers (g-boubuf.ads):: |
| * GNAT.Bounded_Mailboxes (g-boumai.ads):: |
| * GNAT.Bubble_Sort (g-bubsor.ads):: |
| * GNAT.Bubble_Sort_A (g-busora.ads):: |
| * GNAT.Bubble_Sort_G (g-busorg.ads):: |
| * GNAT.Calendar (g-calend.ads):: |
| * GNAT.Calendar.Time_IO (g-catiio.ads):: |
| * GNAT.CRC32 (g-crc32.ads):: |
| * GNAT.Case_Util (g-casuti.ads):: |
| * GNAT.CGI (g-cgi.ads):: |
| * GNAT.CGI.Cookie (g-cgicoo.ads):: |
| * GNAT.CGI.Debug (g-cgideb.ads):: |
| * GNAT.Command_Line (g-comlin.ads):: |
| * GNAT.Compiler_Version (g-comver.ads):: |
| * GNAT.Ctrl_C (g-ctrl_c.ads):: |
| * GNAT.Current_Exception (g-curexc.ads):: |
| * GNAT.Debug_Pools (g-debpoo.ads):: |
| * GNAT.Debug_Utilities (g-debuti.ads):: |
| * GNAT.Directory_Operations (g-dirope.ads):: |
| * GNAT.Dynamic_HTables (g-dynhta.ads):: |
| * GNAT.Dynamic_Tables (g-dyntab.ads):: |
| * GNAT.Exception_Actions (g-excact.ads):: |
| * GNAT.Exception_Traces (g-exctra.ads):: |
| * GNAT.Exceptions (g-except.ads):: |
| * GNAT.Expect (g-expect.ads):: |
| * GNAT.Float_Control (g-flocon.ads):: |
| * GNAT.Heap_Sort (g-heasor.ads):: |
| * GNAT.Heap_Sort_A (g-hesora.ads):: |
| * GNAT.Heap_Sort_G (g-hesorg.ads):: |
| * GNAT.HTable (g-htable.ads):: |
| * GNAT.IO (g-io.ads):: |
| * GNAT.IO_Aux (g-io_aux.ads):: |
| * GNAT.Lock_Files (g-locfil.ads):: |
| * GNAT.MD5 (g-md5.ads):: |
| * GNAT.Memory_Dump (g-memdum.ads):: |
| * GNAT.Most_Recent_Exception (g-moreex.ads):: |
| * GNAT.OS_Lib (g-os_lib.ads):: |
| * GNAT.Perfect_Hash_Generators (g-pehage.ads):: |
| * GNAT.Regexp (g-regexp.ads):: |
| * GNAT.Registry (g-regist.ads):: |
| * GNAT.Regpat (g-regpat.ads):: |
| * GNAT.Secondary_Stack_Info (g-sestin.ads):: |
| * GNAT.Semaphores (g-semaph.ads):: |
| * GNAT.Signals (g-signal.ads):: |
| * GNAT.Sockets (g-socket.ads):: |
| * GNAT.Source_Info (g-souinf.ads):: |
| * GNAT.Spell_Checker (g-speche.ads):: |
| * GNAT.Spitbol.Patterns (g-spipat.ads):: |
| * GNAT.Spitbol (g-spitbo.ads):: |
| * GNAT.Spitbol.Table_Boolean (g-sptabo.ads):: |
| * GNAT.Spitbol.Table_Integer (g-sptain.ads):: |
| * GNAT.Spitbol.Table_VString (g-sptavs.ads):: |
| * GNAT.Strings (g-string.ads):: |
| * GNAT.String_Split (g-strspl.ads):: |
| * GNAT.UTF_32 (g-utf_32.ads):: |
| * GNAT.Table (g-table.ads):: |
| * GNAT.Task_Lock (g-tasloc.ads):: |
| * GNAT.Threads (g-thread.ads):: |
| * GNAT.Traceback (g-traceb.ads):: |
| * GNAT.Traceback.Symbolic (g-trasym.ads):: |
| * GNAT.Wide_String_Split (g-wistsp.ads):: |
| * GNAT.Wide_Wide_String_Split (g-zistsp.ads):: |
| * Interfaces.C.Extensions (i-cexten.ads):: |
| * Interfaces.C.Streams (i-cstrea.ads):: |
| * Interfaces.CPP (i-cpp.ads):: |
| * Interfaces.Os2lib (i-os2lib.ads):: |
| * Interfaces.Os2lib.Errors (i-os2err.ads):: |
| * Interfaces.Os2lib.Synchronization (i-os2syn.ads):: |
| * Interfaces.Os2lib.Threads (i-os2thr.ads):: |
| * Interfaces.Packed_Decimal (i-pacdec.ads):: |
| * Interfaces.VxWorks (i-vxwork.ads):: |
| * Interfaces.VxWorks.IO (i-vxwoio.ads):: |
| * System.Address_Image (s-addima.ads):: |
| * System.Assertions (s-assert.ads):: |
| * System.Memory (s-memory.ads):: |
| * System.Partition_Interface (s-parint.ads):: |
| * System.Restrictions (s-restri.ads):: |
| * System.Rident (s-rident.ads):: |
| * System.Task_Info (s-tasinf.ads):: |
| * System.Wch_Cnv (s-wchcnv.ads):: |
| * System.Wch_Con (s-wchcon.ads):: |
| @end menu |
| |
| @node Ada.Characters.Latin_9 (a-chlat9.ads) |
| @section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) |
| @cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads}) |
| @cindex Latin_9 constants for Character |
| |
| @noindent |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| RM-defined package @code{Ada.Characters.Latin_1} but with the |
| few modifications required for @code{Latin-9} |
| The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3(27)). |
| |
| @node Ada.Characters.Wide_Latin_1 (a-cwila1.ads) |
| @section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) |
| @cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads}) |
| @cindex Latin_1 constants for Wide_Character |
| |
| @noindent |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| RM-defined package @code{Ada.Characters.Latin_1} but with the |
| types of the constants being @code{Wide_Character} |
| instead of @code{Character}. The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3(27)). |
| |
| @node Ada.Characters.Wide_Latin_9 (a-cwila9.ads) |
| @section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) |
| @cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads}) |
| @cindex Latin_9 constants for Wide_Character |
| |
| @noindent |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| GNAT defined package @code{Ada.Characters.Latin_9} but with the |
| types of the constants being @code{Wide_Character} |
| instead of @code{Character}. The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3(27)). |
| |
| @node Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads) |
| @section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads}) |
| @cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads}) |
| @cindex Latin_1 constants for Wide_Wide_Character |
| |
| @noindent |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| RM-defined package @code{Ada.Characters.Latin_1} but with the |
| types of the constants being @code{Wide_Wide_Character} |
| instead of @code{Character}. The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3(27)). |
| |
| @node Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads) |
| @section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads}) |
| @cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads}) |
| @cindex Latin_9 constants for Wide_Wide_Character |
| |
| @noindent |
| This child of @code{Ada.Characters} |
| provides a set of definitions corresponding to those in the |
| GNAT defined package @code{Ada.Characters.Latin_9} but with the |
| types of the constants being @code{Wide_Wide_Character} |
| instead of @code{Character}. The provision of such a package |
| is specifically authorized by the Ada Reference Manual |
| (RM A.3(27)). |
| |
| @node Ada.Command_Line.Remove (a-colire.ads) |
| @section @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) |
| @cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads}) |
| @cindex Removing command line arguments |
| @cindex Command line, argument removal |
| |
| @noindent |
| This child of @code{Ada.Command_Line} |
| provides a mechanism for logically removing |
| arguments from the argument list. Once removed, an argument is not visible |
| to further calls on the subprograms in @code{Ada.Command_Line} will not |
| see the removed argument. |
| |
| @node Ada.Command_Line.Environment (a-colien.ads) |
| @section @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) |
| @cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads}) |
| @cindex Environment entries |
| |
| @noindent |
| This child of @code{Ada.Command_Line} |
| provides a mechanism for obtaining environment values on systems |
| where this concept makes sense. |
| |
| @node Ada.Direct_IO.C_Streams (a-diocst.ads) |
| @section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) |
| @cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads}) |
| @cindex C Streams, Interfacing with Direct_IO |
| |
| @noindent |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Direct_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) |
| @section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) |
| @cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads}) |
| @cindex Null_Occurrence, testing for |
| |
| @noindent |
| This child subprogram provides a way of testing for the null |
| exception occurrence (@code{Null_Occurrence}) without raising |
| an exception. |
| |
| @node Ada.Exceptions.Traceback (a-exctra.ads) |
| @section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) |
| @cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads}) |
| @cindex Traceback for Exception Occurrence |
| |
| @noindent |
| This child package provides the subprogram (@code{Tracebacks}) to |
| give a traceback array of addresses based on an exception |
| occurrence. |
| |
| @node Ada.Sequential_IO.C_Streams (a-siocst.ads) |
| @section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) |
| @cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads}) |
| @cindex C Streams, Interfacing with Sequential_IO |
| |
| @noindent |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Sequential_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) |
| @section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) |
| @cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads}) |
| @cindex C Streams, Interfacing with Stream_IO |
| |
| @noindent |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Stream_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada.Strings.Unbounded.Text_IO (a-suteio.ads) |
| @section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) |
| @cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads}) |
| @cindex @code{Unbounded_String}, IO support |
| @cindex @code{Text_IO}, extensions for unbounded strings |
| |
| @noindent |
| This package provides subprograms for Text_IO for unbounded |
| strings, avoiding the necessity for an intermediate operation |
| with ordinary strings. |
| |
| @node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) |
| @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) |
| @cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads}) |
| @cindex @code{Unbounded_Wide_String}, IO support |
| @cindex @code{Text_IO}, extensions for unbounded wide strings |
| |
| @noindent |
| This package provides subprograms for Text_IO for unbounded |
| wide strings, avoiding the necessity for an intermediate operation |
| with ordinary wide strings. |
| |
| @node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) |
| @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads}) |
| @cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads}) |
| @cindex @code{Unbounded_Wide_Wide_String}, IO support |
| @cindex @code{Text_IO}, extensions for unbounded wide wide strings |
| |
| @noindent |
| This package provides subprograms for Text_IO for unbounded |
| wide wide strings, avoiding the necessity for an intermediate operation |
| with ordinary wide wide strings. |
| |
| @node Ada.Text_IO.C_Streams (a-tiocst.ads) |
| @section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) |
| @cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads}) |
| @cindex C Streams, Interfacing with @code{Text_IO} |
| |
| @noindent |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Text_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) |
| @section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) |
| @cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads}) |
| @cindex C Streams, Interfacing with @code{Wide_Text_IO} |
| |
| @noindent |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Wide_Text_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) |
| @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads}) |
| @cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads}) |
| @cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO} |
| |
| @noindent |
| This package provides subprograms that allow interfacing between |
| C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be |
| extracted from a file opened on the Ada side, and an Ada file |
| can be constructed from a stream opened on the C side. |
| |
| @node GNAT.Altivec (g-altive.ads) |
| @section @code{GNAT.Altivec} (@file{g-altive.ads}) |
| @cindex @code{GNAT.Altivec} (@file{g-altive.ads}) |
| @cindex AltiVec |
| |
| @noindent |
| This is the root package of the GNAT AltiVec binding. It provides |
| definitions of constants and types common to all the versions of the |
| binding. |
| |
| @node GNAT.Altivec.Conversions (g-altcon.ads) |
| @section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads}) |
| @cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads}) |
| @cindex AltiVec |
| |
| @noindent |
| This package provides the Vector/View conversion routines. |
| |
| @node GNAT.Altivec.Vector_Operations (g-alveop.ads) |
| @section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads}) |
| @cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads}) |
| @cindex AltiVec |
| |
| @noindent |
| This package exposes the Ada interface to the AltiVec operations on |
| vector objects. A soft emulation is included by default in the GNAT |
| library. The hard binding is provided as a separate package. This unit |
| is common to both bindings. |
| |
| @node GNAT.Altivec.Vector_Types (g-alvety.ads) |
| @section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads}) |
| @cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads}) |
| @cindex AltiVec |
| |
| @noindent |
| This package exposes the various vector types part of the Ada binding |
| to AltiVec facilities. |
| |
| @node GNAT.Altivec.Vector_Views (g-alvevi.ads) |
| @section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads}) |
| @cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads}) |
| @cindex AltiVec |
| |
| @noindent |
| This package provides public 'View' data types from/to which private |
| vector representations can be converted via |
| GNAT.Altivec.Conversions. This allows convenient access to individual |
| vector elements and provides a simple way to initialize vector |
| objects. |
| |
| @node GNAT.Array_Split (g-arrspl.ads) |
| @section @code{GNAT.Array_Split} (@file{g-arrspl.ads}) |
| @cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads}) |
| @cindex Array splitter |
| |
| @noindent |
| Useful array-manipulation routines: given a set of separators, split |
| an array wherever the separators appear, and provide direct access |
| to the resulting slices. |
| |
| @node GNAT.AWK (g-awk.ads) |
| @section @code{GNAT.AWK} (@file{g-awk.ads}) |
| @cindex @code{GNAT.AWK} (@file{g-awk.ads}) |
| @cindex Parsing |
| @cindex AWK |
| |
| @noindent |
| Provides AWK-like parsing functions, with an easy interface for parsing one |
| or more files containing formatted data. The file is viewed as a database |
| where each record is a line and a field is a data element in this line. |
| |
| @node GNAT.Bounded_Buffers (g-boubuf.ads) |
| @section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) |
| @cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads}) |
| @cindex Parsing |
| @cindex Bounded Buffers |
| |
| @noindent |
| Provides a concurrent generic bounded buffer abstraction. Instances are |
| useful directly or as parts of the implementations of other abstractions, |
| such as mailboxes. |
| |
| @node GNAT.Bounded_Mailboxes (g-boumai.ads) |
| @section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) |
| @cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads}) |
| @cindex Parsing |
| @cindex Mailboxes |
| |
| @noindent |
| Provides a thread-safe asynchronous intertask mailbox communication facility. |
| |
| @node GNAT.Bubble_Sort (g-bubsor.ads) |
| @section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) |
| @cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads}) |
| @cindex Sorting |
| @cindex Bubble sort |
| |
| @noindent |
| Provides a general implementation of bubble sort usable for sorting arbitrary |
| data items. Exchange and comparison procedures are provided by passing |
| access-to-procedure values. |
| |
| @node GNAT.Bubble_Sort_A (g-busora.ads) |
| @section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) |
| @cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads}) |
| @cindex Sorting |
| @cindex Bubble sort |
| |
| @noindent |
| Provides a general implementation of bubble sort usable for sorting arbitrary |
| data items. Move and comparison procedures are provided by passing |
| access-to-procedure values. This is an older version, retained for |
| compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. |
| |
| @node GNAT.Bubble_Sort_G (g-busorg.ads) |
| @section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) |
| @cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads}) |
| @cindex Sorting |
| @cindex Bubble sort |
| |
| @noindent |
| Similar to @code{Bubble_Sort_A} except that the move and sorting procedures |
| are provided as generic parameters, this improves efficiency, especially |
| if the procedures can be inlined, at the expense of duplicating code for |
| multiple instantiations. |
| |
| @node GNAT.Calendar (g-calend.ads) |
| @section @code{GNAT.Calendar} (@file{g-calend.ads}) |
| @cindex @code{GNAT.Calendar} (@file{g-calend.ads}) |
| @cindex @code{Calendar} |
| |
| @noindent |
| Extends the facilities provided by @code{Ada.Calendar} to include handling |
| of days of the week, an extended @code{Split} and @code{Time_Of} capability. |
| Also provides conversion of @code{Ada.Calendar.Time} values to and from the |
| C @code{timeval} format. |
| |
| @node GNAT.Calendar.Time_IO (g-catiio.ads) |
| @section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) |
| @cindex @code{Calendar} |
| @cindex Time |
| @cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads}) |
| |
| @node GNAT.CRC32 (g-crc32.ads) |
| @section @code{GNAT.CRC32} (@file{g-crc32.ads}) |
| @cindex @code{GNAT.CRC32} (@file{g-crc32.ads}) |
| @cindex CRC32 |
| @cindex Cyclic Redundancy Check |
| |
| @noindent |
| This package implements the CRC-32 algorithm. For a full description |
| of this algorithm see |
| ``Computation of Cyclic Redundancy Checks via Table Look-Up'', |
| @cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013, |
| Aug.@: 1988. Sarwate, D.V@. |
| |
| @noindent |
| Provides an extended capability for formatted output of time values with |
| full user control over the format. Modeled on the GNU Date specification. |
| |
| @node GNAT.Case_Util (g-casuti.ads) |
| @section @code{GNAT.Case_Util} (@file{g-casuti.ads}) |
| @cindex @code{GNAT.Case_Util} (@file{g-casuti.ads}) |
| @cindex Casing utilities |
| @cindex Character handling (@code{GNAT.Case_Util}) |
| |
| @noindent |
| A set of simple routines for handling upper and lower casing of strings |
| without the overhead of the full casing tables |
| in @code{Ada.Characters.Handling}. |
| |
| @node GNAT.CGI (g-cgi.ads) |
| @section @code{GNAT.CGI} (@file{g-cgi.ads}) |
| @cindex @code{GNAT.CGI} (@file{g-cgi.ads}) |
| @cindex CGI (Common Gateway Interface) |
| |
| @noindent |
| This is a package for interfacing a GNAT program with a Web server via the |
| Common Gateway Interface (CGI)@. Basically this package parses the CGI |
| parameters, which are a set of key/value pairs sent by the Web server. It |
| builds a table whose index is the key and provides some services to deal |
| with this table. |
| |
| @node GNAT.CGI.Cookie (g-cgicoo.ads) |
| @section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) |
| @cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads}) |
| @cindex CGI (Common Gateway Interface) cookie support |
| @cindex Cookie support in CGI |
| |
| @noindent |
| This is a package to interface a GNAT program with a Web server via the |
| Common Gateway Interface (CGI). It exports services to deal with Web |
| cookies (piece of information kept in the Web client software). |
| |
| @node GNAT.CGI.Debug (g-cgideb.ads) |
| @section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) |
| @cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads}) |
| @cindex CGI (Common Gateway Interface) debugging |
| |
| @noindent |
| This is a package to help debugging CGI (Common Gateway Interface) |
| programs written in Ada. |
| |
| @node GNAT.Command_Line (g-comlin.ads) |
| @section @code{GNAT.Command_Line} (@file{g-comlin.ads}) |
| @cindex @code{GNAT.Command_Line} (@file{g-comlin.ads}) |
| @cindex Command line |
| |
| @noindent |
| Provides a high level interface to @code{Ada.Command_Line} facilities, |
| including the ability to scan for named switches with optional parameters |
| and expand file names using wild card notations. |
| |
| @node GNAT.Compiler_Version (g-comver.ads) |
| @section @code{GNAT.Compiler_Version} (@file{g-comver.ads}) |
| @cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads}) |
| @cindex Compiler Version |
| @cindex Version, of compiler |
| |
| @noindent |
| Provides a routine for obtaining the version of the compiler used to |
| compile the program. More accurately this is the version of the binder |
| used to bind the program (this will normally be the same as the version |
| of the compiler if a consistent tool set is used to compile all units |
| of a partition). |
| |
| @node GNAT.Ctrl_C (g-ctrl_c.ads) |
| @section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) |
| @cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads}) |
| @cindex Interrupt |
| |
| @noindent |
| Provides a simple interface to handle Ctrl-C keyboard events. |
| |
| @node GNAT.Current_Exception (g-curexc.ads) |
| @section @code{GNAT.Current_Exception} (@file{g-curexc.ads}) |
| @cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads}) |
| @cindex Current exception |
| @cindex Exception retrieval |
| |
| @noindent |
| Provides access to information on the current exception that has been raised |
| without the need for using the Ada-95 exception choice parameter specification |
| syntax. This is particularly useful in simulating typical facilities for |
| obtaining information about exceptions provided by Ada 83 compilers. |
| |
| @node GNAT.Debug_Pools (g-debpoo.ads) |
| @section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) |
| @cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads}) |
| @cindex Debugging |
| @cindex Debug pools |
| @cindex Memory corruption debugging |
| |
| @noindent |
| Provide a debugging storage pools that helps tracking memory corruption |
| problems. See section ``Finding memory problems with GNAT Debug Pool'' in |
| the @cite{GNAT User's Guide}. |
| |
| @node GNAT.Debug_Utilities (g-debuti.ads) |
| @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) |
| @cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads}) |
| @cindex Debugging |
| |
| @noindent |
| Provides a few useful utilities for debugging purposes, including conversion |
| to and from string images of address values. Supports both C and Ada formats |
| for hexadecimal literals. |
| |
| @node GNAT.Directory_Operations (g-dirope.ads) |
| @section @code{GNAT.Directory_Operations} (g-dirope.ads) |
| @cindex @code{GNAT.Directory_Operations} (g-dirope.ads) |
| @cindex Directory operations |
| |
| @noindent |
| Provides a set of routines for manipulating directories, including changing |
| the current directory, making new directories, and scanning the files in a |
| directory. |
| |
| @node GNAT.Dynamic_HTables (g-dynhta.ads) |
| @section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) |
| @cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads}) |
| @cindex Hash tables |
| |
| @noindent |
| A generic implementation of hash tables that can be used to hash arbitrary |
| data. Provided in two forms, a simple form with built in hash functions, |
| and a more complex form in which the hash function is supplied. |
| |
| @noindent |
| This package provides a facility similar to that of @code{GNAT.HTable}, |
| except that this package declares a type that can be used to define |
| dynamic instances of the hash table, while an instantiation of |
| @code{GNAT.HTable} creates a single instance of the hash table. |
| |
| @node GNAT.Dynamic_Tables (g-dyntab.ads) |
| @section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) |
| @cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads}) |
| @cindex Table implementation |
| @cindex Arrays, extendable |
| |
| @noindent |
| A generic package providing a single dimension array abstraction where the |
| length of the array can be dynamically modified. |
| |
| @noindent |
| This package provides a facility similar to that of @code{GNAT.Table}, |
| except that this package declares a type that can be used to define |
| dynamic instances of the table, while an instantiation of |
| @code{GNAT.Table} creates a single instance of the table type. |
| |
| @node GNAT.Exception_Actions (g-excact.ads) |
| @section @code{GNAT.Exception_Actions} (@file{g-excact.ads}) |
| @cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads}) |
| @cindex Exception actions |
| |
| @noindent |
| Provides callbacks when an exception is raised. Callbacks can be registered |
| for specific exceptions, or when any exception is raised. This |
| can be used for instance to force a core dump to ease debugging. |
| |
| @node GNAT.Exception_Traces (g-exctra.ads) |
| @section @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) |
| @cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads}) |
| @cindex Exception traces |
| @cindex Debugging |
| |
| @noindent |
| Provides an interface allowing to control automatic output upon exception |
| occurrences. |
| |
| @node GNAT.Exceptions (g-except.ads) |
| @section @code{GNAT.Exceptions} (@file{g-expect.ads}) |
| @cindex @code{GNAT.Exceptions} (@file{g-expect.ads}) |
| @cindex Exceptions, Pure |
| @cindex Pure packages, exceptions |
| |
| @noindent |
| Normally it is not possible to raise an exception with |
| a message from a subprogram in a pure package, since the |
| necessary types and subprograms are in @code{Ada.Exceptions} |
| which is not a pure unit. @code{GNAT.Exceptions} provides a |
| facility for getting around this limitation for a few |
| predefined exceptions, and for example allow raising |
| @code{Constraint_Error} with a message from a pure subprogram. |
| |
| @node GNAT.Expect (g-expect.ads) |
| @section @code{GNAT.Expect} (@file{g-expect.ads}) |
| @cindex @code{GNAT.Expect} (@file{g-expect.ads}) |
| |
| @noindent |
| Provides a set of subprograms similar to what is available |
| with the standard Tcl Expect tool. |
| It allows you to easily spawn and communicate with an external process. |
| You can send commands or inputs to the process, and compare the output |
| with some expected regular expression. Currently @code{GNAT.Expect} |
| is implemented on all native GNAT ports except for OpenVMS@. |
| It is not implemented for cross ports, and in particular is not |
| implemented for VxWorks or LynxOS@. |
| |
| @node GNAT.Float_Control (g-flocon.ads) |
| @section @code{GNAT.Float_Control} (@file{g-flocon.ads}) |
| @cindex @code{GNAT.Float_Control} (@file{g-flocon.ads}) |
| @cindex Floating-Point Processor |
| |
| @noindent |
| Provides an interface for resetting the floating-point processor into the |
| mode required for correct semantic operation in Ada. Some third party |
| library calls may cause this mode to be modified, and the Reset procedure |
| in this package can be used to reestablish the required mode. |
| |
| @node GNAT.Heap_Sort (g-heasor.ads) |
| @section @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) |
| @cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads}) |
| @cindex Sorting |
| |
| @noindent |
| Provides a general implementation of heap sort usable for sorting arbitrary |
| data items. Exchange and comparison procedures are provided by passing |
| access-to-procedure values. The algorithm used is a modified heap sort |
| that performs approximately N*log(N) comparisons in the worst case. |
| |
| @node GNAT.Heap_Sort_A (g-hesora.ads) |
| @section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) |
| @cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads}) |
| @cindex Sorting |
| |
| @noindent |
| Provides a general implementation of heap sort usable for sorting arbitrary |
| data items. Move and comparison procedures are provided by passing |
| access-to-procedure values. The algorithm used is a modified heap sort |
| that performs approximately N*log(N) comparisons in the worst case. |
| This differs from @code{GNAT.Heap_Sort} in having a less convenient |
| interface, but may be slightly more efficient. |
| |
| @node GNAT.Heap_Sort_G (g-hesorg.ads) |
| @section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) |
| @cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads}) |
| @cindex Sorting |
| |
| @noindent |
| Similar to @code{Heap_Sort_A} except that the move and sorting procedures |
| are provided as generic parameters, this improves efficiency, especially |
| if the procedures can be inlined, at the expense of duplicating code for |
| multiple instantiations. |
| |
| @node GNAT.HTable (g-htable.ads) |
| @section @code{GNAT.HTable} (@file{g-htable.ads}) |
| @cindex @code{GNAT.HTable} (@file{g-htable.ads}) |
| @cindex Hash tables |
| |
| @noindent |
| A generic implementation of hash tables that can be used to hash arbitrary |
| data. Provides two approaches, one a simple static approach, and the other |
| allowing arbitrary dynamic hash tables. |
| |
| @node GNAT.IO (g-io.ads) |
| @section @code{GNAT.IO} (@file{g-io.ads}) |
| @cindex @code{GNAT.IO} (@file{g-io.ads}) |
| @cindex Simple I/O |
| @cindex Input/Output facilities |
| |
| @noindent |
| A simple preelaborable input-output package that provides a subset of |
| simple Text_IO functions for reading characters and strings from |
| Standard_Input, and writing characters, strings and integers to either |
| Standard_Output or Standard_Error. |
| |
| @node GNAT.IO_Aux (g-io_aux.ads) |
| @section @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) |
| @cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads}) |
| @cindex Text_IO |
| @cindex Input/Output facilities |
| |
| Provides some auxiliary functions for use with Text_IO, including a test |
| for whether a file exists, and functions for reading a line of text. |
| |
| @node GNAT.Lock_Files (g-locfil.ads) |
| @section @code{GNAT.Lock_Files} (@file{g-locfil.ads}) |
| @cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads}) |
| @cindex File locking |
| @cindex Locking using files |
| |
| @noindent |
| Provides a general interface for using files as locks. Can be used for |
| providing program level synchronization. |
| |
| @node GNAT.MD5 (g-md5.ads) |
| @section @code{GNAT.MD5} (@file{g-md5.ads}) |
| @cindex @code{GNAT.MD5} (@file{g-md5.ads}) |
| @cindex Message Digest MD5 |
| |
| @noindent |
| Implements the MD5 Message-Digest Algorithm as described in RFC 1321. |
| |
| @node GNAT.Memory_Dump (g-memdum.ads) |
| @section @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) |
| @cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads}) |
| @cindex Dump Memory |
| |
| @noindent |
| Provides a convenient routine for dumping raw memory to either the |
| standard output or standard error files. Uses GNAT.IO for actual |
| output. |
| |
| @node GNAT.Most_Recent_Exception (g-moreex.ads) |
| @section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) |
| @cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads}) |
| @cindex Exception, obtaining most recent |
| |
| @noindent |
| Provides access to the most recently raised exception. Can be used for |
| various logging purposes, including duplicating functionality of some |
| Ada 83 implementation dependent extensions. |
| |
| @node GNAT.OS_Lib (g-os_lib.ads) |
| @section @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) |
| @cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads}) |
| @cindex Operating System interface |
| @cindex Spawn capability |
| |
| @noindent |
| Provides a range of target independent operating system interface functions, |
| including time/date management, file operations, subprocess management, |
| including a portable spawn procedure, and access to environment variables |
| and error return codes. |
| |
| @node GNAT.Perfect_Hash_Generators (g-pehage.ads) |
| @section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads}) |
| @cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads}) |
| @cindex Hash functions |
| |
| @noindent |
| Provides a generator of static minimal perfect hash functions. No |
| collisions occur and each item can be retrieved from the table in one |
| probe (perfect property). The hash table size corresponds to the exact |
| size of the key set and no larger (minimal property). The key set has to |
| be know in advance (static property). The hash functions are also order |
| preserving. If w2 is inserted after w1 in the generator, their |
| hashcode are in the same order. These hashing functions are very |
| convenient for use with realtime applications. |
| |
| @node GNAT.Regexp (g-regexp.ads) |
| @section @code{GNAT.Regexp} (@file{g-regexp.ads}) |
| @cindex @code{GNAT.Regexp} (@file{g-regexp.ads}) |
| @cindex Regular expressions |
| @cindex Pattern matching |
| |
| @noindent |
| A simple implementation of regular expressions, using a subset of regular |
| expression syntax copied from familiar Unix style utilities. This is the |
| simples of the three pattern matching packages provided, and is particularly |
| suitable for ``file globbing'' applications. |
| |
| @node GNAT.Registry (g-regist.ads) |
| @section @code{GNAT.Registry} (@file{g-regist.ads}) |
| @cindex @code{GNAT.Registry} (@file{g-regist.ads}) |
| @cindex Windows Registry |
| |
| @noindent |
| This is a high level binding to the Windows registry. It is possible to |
| do simple things like reading a key value, creating a new key. For full |
| registry API, but at a lower level of abstraction, refer to the Win32.Winreg |
| package provided with the Win32Ada binding |
| |
| @node GNAT.Regpat (g-regpat.ads) |
| @section @code{GNAT.Regpat} (@file{g-regpat.ads}) |
| @cindex @code{GNAT.Regpat} (@file{g-regpat.ads}) |
| @cindex Regular expressions |
| @cindex Pattern matching |
| |
| @noindent |
| A complete implementation of Unix-style regular expression matching, copied |
| from the original V7 style regular expression library written in C by |
| Henry Spencer (and binary compatible with this C library). |
| |
| @node GNAT.Secondary_Stack_Info (g-sestin.ads) |
| @section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) |
| @cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads}) |
| @cindex Secondary Stack Info |
| |
| @noindent |
| Provide the capability to query the high water mark of the current task's |
| secondary stack. |
| |
| @node GNAT.Semaphores (g-semaph.ads) |
| @section @code{GNAT.Semaphores} (@file{g-semaph.ads}) |
| @cindex @code{GNAT.Semaphores} (@file{g-semaph.ads}) |
| @cindex Semaphores |
| |
| @noindent |
| Provides classic counting and binary semaphores using protected types. |
| |
| @node GNAT.Signals (g-signal.ads) |
| @section @code{GNAT.Signals} (@file{g-signal.ads}) |
| @cindex @code{GNAT.Signals} (@file{g-signal.ads}) |
| @cindex Signals |
| |
| @noindent |
| Provides the ability to manipulate the blocked status of signals on supported |
| targets. |
| |
| @node GNAT.Sockets (g-socket.ads) |
| @section @code{GNAT.Sockets} (@file{g-socket.ads}) |
| @cindex @code{GNAT.Sockets} (@file{g-socket.ads}) |
| @cindex Sockets |
| |
| @noindent |
| A high level and portable interface to develop sockets based applications. |
| This package is based on the sockets thin binding found in |
| @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented |
| on all native GNAT ports except for OpenVMS@. It is not implemented |
| for the LynxOS@ cross port. |
| |
| @node GNAT.Source_Info (g-souinf.ads) |
| @section @code{GNAT.Source_Info} (@file{g-souinf.ads}) |
| @cindex @code{GNAT.Source_Info} (@file{g-souinf.ads}) |
| @cindex Source Information |
| |
| @noindent |
| Provides subprograms that give access to source code information known at |
| compile time, such as the current file name and line number. |
| |
| @node GNAT.Spell_Checker (g-speche.ads) |
| @section @code{GNAT.Spell_Checker} (@file{g-speche.ads}) |
| @cindex @code{GNAT.Spell_Checker} (@file{g-speche.ads}) |
| @cindex Spell checking |
| |
| @noindent |
| Provides a function for determining whether one string is a plausible |
| near misspelling of another string. |
| |
| @node GNAT.Spitbol.Patterns (g-spipat.ads) |
| @section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) |
| @cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads}) |
| @cindex SPITBOL pattern matching |
| @cindex Pattern matching |
| |
| @noindent |
| A complete implementation of SNOBOL4 style pattern matching. This is the |
| most elaborate of the pattern matching packages provided. It fully duplicates |
| the SNOBOL4 dynamic pattern construction and matching capabilities, using the |
| efficient algorithm developed by Robert Dewar for the SPITBOL system. |
| |
| @node GNAT.Spitbol (g-spitbo.ads) |
| @section @code{GNAT.Spitbol} (@file{g-spitbo.ads}) |
| @cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads}) |
| @cindex SPITBOL interface |
| |
| @noindent |
| The top level package of the collection of SPITBOL-style functionality, this |
| package provides basic SNOBOL4 string manipulation functions, such as |
| Pad, Reverse, Trim, Substr capability, as well as a generic table function |
| useful for constructing arbitrary mappings from strings in the style of |
| the SNOBOL4 TABLE function. |
| |
| @node GNAT.Spitbol.Table_Boolean (g-sptabo.ads) |
| @section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) |
| @cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads}) |
| @cindex Sets of strings |
| @cindex SPITBOL Tables |
| |
| @noindent |
| A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} |
| for type @code{Standard.Boolean}, giving an implementation of sets of |
| string values. |
| |
| @node GNAT.Spitbol.Table_Integer (g-sptain.ads) |
| @section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) |
| @cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads}) |
| @cindex Integer maps |
| @cindex Maps |
| @cindex SPITBOL Tables |
| |
| @noindent |
| A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} |
| for type @code{Standard.Integer}, giving an implementation of maps |
| from string to integer values. |
| |
| @node GNAT.Spitbol.Table_VString (g-sptavs.ads) |
| @section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) |
| @cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads}) |
| @cindex String maps |
| @cindex Maps |
| @cindex SPITBOL Tables |
| |
| @noindent |
| A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for |
| a variable length string type, giving an implementation of general |
| maps from strings to strings. |
| |
| @node GNAT.Strings (g-string.ads) |
| @section @code{GNAT.Strings} (@file{g-string.ads}) |
| @cindex @code{GNAT.Strings} (@file{g-string.ads}) |
| |
| @noindent |
| Common String access types and related subprograms. Basically it |
| defines a string access and an array of string access types. |
| |
| @node GNAT.String_Split (g-strspl.ads) |
| @section @code{GNAT.String_Split} (@file{g-strspl.ads}) |
| @cindex @code{GNAT.String_Split} (@file{g-strspl.ads}) |
| @cindex String splitter |
| |
| @noindent |
| Useful string manipulation routines: given a set of separators, split |
| a string wherever the separators appear, and provide direct access |
| to the resulting slices. This package is instantiated from |
| @code{GNAT.Array_Split}. |
| |
| @node GNAT.UTF_32 (g-utf_32.ads) |
| @section @code{GNAT.UTF_32} (@file{g-table.ads}) |
| @cindex @code{GNAT.UTF_32} (@file{g-table.ads}) |
| @cindex Wide character codes |
| |
| @noindent |
| This is a package intended to be used in conjunction with the |
| @code{Wide_Character} type in Ada 95 and the |
| @code{Wide_Wide_Character} type in Ada 2005 (available |
| in @code{GNAT} in Ada 2005 mode). This package contains |
| Unicode categorization routines, as well as lexical |
| categorization routines corresponding to the Ada 2005 |
| lexical rules for identifiers and strings, and also a |
| lower case to upper case fold routine corresponding to |
| the Ada 2005 rules for identifier equivalence. |
| |
| @node GNAT.Table (g-table.ads) |
| @section @code{GNAT.Table} (@file{g-table.ads}) |
| @cindex @code{GNAT.Table} (@file{g-table.ads}) |
| @cindex Table implementation |
| @cindex Arrays, extendable |
| |
| @noindent |
| A generic package providing a single dimension array abstraction where the |
| length of the array can be dynamically modified. |
| |
| @noindent |
| This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, |
| except that this package declares a single instance of the table type, |
| while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be |
| used to define dynamic instances of the table. |
| |
| @node GNAT.Task_Lock (g-tasloc.ads) |
| @section @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) |
| @cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads}) |
| @cindex Task synchronization |
| @cindex Task locking |
| @cindex Locking |
| |
| @noindent |
| A very simple facility for locking and unlocking sections of code using a |
| single global task lock. Appropriate for use in situations where contention |
| between tasks is very rarely expected. |
| |
| @node GNAT.Threads (g-thread.ads) |
| @section @code{GNAT.Threads} (@file{g-thread.ads}) |
| @cindex @code{GNAT.Threads} (@file{g-thread.ads}) |
| @cindex Foreign threads |
| @cindex Threads, foreign |
| |
| @noindent |
| Provides facilities for creating and destroying threads with explicit calls. |
| These threads are known to the GNAT run-time system. These subprograms are |
| exported C-convention procedures intended to be called from foreign code. |
| By using these primitives rather than directly calling operating systems |
| routines, compatibility with the Ada tasking run-time is provided. |
| |
| @node GNAT.Traceback (g-traceb.ads) |
| @section @code{GNAT.Traceback} (@file{g-traceb.ads}) |
| @cindex @code{GNAT.Traceback} (@file{g-traceb.ads}) |
| @cindex Trace back facilities |
| |
| @noindent |
| Provides a facility for obtaining non-symbolic traceback information, useful |
| in various debugging situations. |
| |
| @node GNAT.Traceback.Symbolic (g-trasym.ads) |
| @section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) |
| @cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads}) |
| @cindex Trace back facilities |
| |
| @noindent |
| Provides symbolic traceback information that includes the subprogram |
| name and line number information. |
| |
| @node GNAT.Wide_String_Split (g-wistsp.ads) |
| @section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) |
| @cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads}) |
| @cindex Wide_String splitter |
| |
| @noindent |
| Useful wide string manipulation routines: given a set of separators, split |
| a wide string wherever the separators appear, and provide direct access |
| to the resulting slices. This package is instantiated from |
| @code{GNAT.Array_Split}. |
| |
| @node GNAT.Wide_Wide_String_Split (g-zistsp.ads) |
| @section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads}) |
| @cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads}) |
| @cindex Wide_Wide_String splitter |
| |
| @noindent |
| Useful wide wide string manipulation routines: given a set of separators, split |
| a wide wide string wherever the separators appear, and provide direct access |
| to the resulting slices. This package is instantiated from |
| @code{GNAT.Array_Split}. |
| |
| @node Interfaces.C.Extensions (i-cexten.ads) |
| @section @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) |
| @cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads}) |
| |
| @noindent |
| This package contains additional C-related definitions, intended |
| for use with either manually or automatically generated bindings |
| to C libraries. |
| |
| @node Interfaces.C.Streams (i-cstrea.ads) |
| @section @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) |
| @cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads}) |
| @cindex C streams, interfacing |
| |
| @noindent |
| This package is a binding for the most commonly used operations |
| on C streams. |
| |
| @node Interfaces.CPP (i-cpp.ads) |
| @section @code{Interfaces.CPP} (@file{i-cpp.ads}) |
| @cindex @code{Interfaces.CPP} (@file{i-cpp.ads}) |
| @cindex C++ interfacing |
| @cindex Interfacing, to C++ |
| |
| @noindent |
| This package provides facilities for use in interfacing to C++. It |
| is primarily intended to be used in connection with automated tools |
| for the generation of C++ interfaces. |
| |
| @node Interfaces.Os2lib (i-os2lib.ads) |
| @section @code{Interfaces.Os2lib} (@file{i-os2lib.ads}) |
| @cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads}) |
| @cindex Interfacing, to OS/2 |
| @cindex OS/2 interfacing |
| |
| @noindent |
| This package provides interface definitions to the OS/2 library. |
| It is a thin binding which is a direct translation of the |
| various @file{<bse@.h>} files. |
| |
| @node Interfaces.Os2lib.Errors (i-os2err.ads) |
| @section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads}) |
| @cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads}) |
| @cindex OS/2 Error codes |
| @cindex Interfacing, to OS/2 |
| @cindex OS/2 interfacing |
| |
| @noindent |
| This package provides definitions of the OS/2 error codes. |
| |
| @node Interfaces.Os2lib.Synchronization (i-os2syn.ads) |
| @section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads}) |
| @cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads}) |
| @cindex Interfacing, to OS/2 |
| @cindex Synchronization, OS/2 |
| @cindex OS/2 synchronization primitives |
| |
| @noindent |
| This is a child package that provides definitions for interfacing |
| to the @code{OS/2} synchronization primitives. |
| |
| @node Interfaces.Os2lib.Threads (i-os2thr.ads) |
| @section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads}) |
| @cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads}) |
| @cindex Interfacing, to OS/2 |
| @cindex Thread control, OS/2 |
| @cindex OS/2 thread interfacing |
| |
| @noindent |
| This is a child package that provides definitions for interfacing |
| to the @code{OS/2} thread primitives. |
| |
| @node Interfaces.Packed_Decimal (i-pacdec.ads) |
| @section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) |
| @cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads}) |
| @cindex IBM Packed Format |
| @cindex Packed Decimal |
| |
| @noindent |
| This package provides a set of routines for conversions to and |
| from a packed decimal format compatible with that used on IBM |
| mainframes. |
| |
| @node Interfaces.VxWorks (i-vxwork.ads) |
| @section @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) |
| @cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads}) |
| @cindex Interfacing to VxWorks |
| @cindex VxWorks, interfacing |
| |
| @noindent |
| This package provides a limited binding to the VxWorks API. |
| In particular, it interfaces with the |
| VxWorks hardware interrupt facilities. |
| |
| @node Interfaces.VxWorks.IO (i-vxwoio.ads) |
| @section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) |
| @cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads}) |
| @cindex Interfacing to VxWorks' I/O |
| @cindex VxWorks, I/O interfacing |
| @cindex VxWorks, Get_Immediate |
| @cindex Get_Immediate, VxWorks |
| |
| @noindent |
| This package provides a binding to the ioctl (IO/Control) |
| function of VxWorks, defining a set of option values and |
| function codes. A particular use of this package is |
| to enable the use of Get_Immediate under VxWorks. |
| |
| @node System.Address_Image (s-addima.ads) |
| @section @code{System.Address_Image} (@file{s-addima.ads}) |
| @cindex @code{System.Address_Image} (@file{s-addima.ads}) |
| @cindex Address image |
| @cindex Image, of an address |
| |
| @noindent |
| This function provides a useful debugging |
| function that gives an (implementation dependent) |
| string which identifies an address. |
| |
| @node System.Assertions (s-assert.ads) |
| @section @code{System.Assertions} (@file{s-assert.ads}) |
| @cindex @code{System.Assertions} (@file{s-assert.ads}) |
| @cindex Assertions |
| @cindex Assert_Failure, exception |
| |
| @noindent |
| This package provides the declaration of the exception raised |
| by an run-time assertion failure, as well as the routine that |
| is used internally to raise this assertion. |
| |
| @node System.Memory (s-memory.ads) |
| @section @code{System.Memory} (@file{s-memory.ads}) |
| @cindex @code{System.Memory} (@file{s-memory.ads}) |
| @cindex Memory allocation |
| |
| @noindent |
| This package provides the interface to the low level routines used |
| by the generated code for allocation and freeing storage for the |
| default storage pool (analogous to the C routines malloc and free. |
| It also provides a reallocation interface analogous to the C routine |
| realloc. The body of this unit may be modified to provide alternative |
| allocation mechanisms for the default pool, and in addition, direct |
| calls to this unit may be made for low level allocation uses (for |
| example see the body of @code{GNAT.Tables}). |
| |
| @node System.Partition_Interface (s-parint.ads) |
| @section @code{System.Partition_Interface} (@file{s-parint.ads}) |
| @cindex @code{System.Partition_Interface} (@file{s-parint.ads}) |
| @cindex Partition interfacing functions |
| |
| @noindent |
| This package provides facilities for partition interfacing. It |
| is used primarily in a distribution context when using Annex E |
| with @code{GLADE}. |
| |
| @node System.Restrictions (s-restri.ads) |
| @section @code{System.Restrictions} (@file{s-restri.ads}) |
| @cindex @code{System.Restrictions} (@file{s-restri.ads}) |
| @cindex Run-time restrictions access |
| |
| @noindent |
| This package provides facilities for accessing at run-time |
| the status of restrictions specified at compile time for |
| the partition. Information is available both with regard |
| to actual restrictions specified, and with regard to |
| compiler determined information on which restrictions |
| are violated by one or more packages in the partition. |
| |
| @node System.Rident (s-rident.ads) |
| @section @code{System.Rident} (@file{s-rident.ads}) |
| @cindex @code{System.Rident} (@file{s-rident.ads}) |
| @cindex Restrictions definitions |
| |
| @noindent |
| This package provides definitions of the restrictions |
| identifiers supported by GNAT, and also the format of |
| the restrictions provided in package System.Restrictions. |
| It is not normally necessary to @code{with} this generic package |
| since the necessary instantiation is included in |
| package System.Restrictions. |
| |
| @node System.Task_Info (s-tasinf.ads) |
| @section @code{System.Task_Info} (@file{s-tasinf.ads}) |
| @cindex @code{System.Task_Info} (@file{s-tasinf.ads}) |
| @cindex Task_Info pragma |
| |
| @noindent |
| This package provides target dependent functionality that is used |
| to support the @code{Task_Info} pragma |
| |
| @node System.Wch_Cnv (s-wchcnv.ads) |
| @section @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) |
| @cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads}) |
| @cindex Wide Character, Representation |
| @cindex Wide String, Conversion |
| @cindex Representation of wide characters |
| |
| @noindent |
| This package provides routines for converting between |
| wide and wide wide characters and a representation as a value of type |
| @code{Standard.String}, using a specified wide character |
| encoding method. It uses definitions in |
| package @code{System.Wch_Con}. |
| |
| @node System.Wch_Con (s-wchcon.ads) |
| @section @code{System.Wch_Con} (@file{s-wchcon.ads}) |
| @cindex @code{System.Wch_Con} (@file{s-wchcon.ads}) |
| |
| @noindent |
| This package provides definitions and descriptions of |
| the various methods used for encoding wide characters |
| in ordinary strings. These definitions are used by |
| the package @code{System.Wch_Cnv}. |
| |
| @node Interfacing to Other Languages |
| @chapter Interfacing to Other Languages |
| @noindent |
| The facilities in annex B of the Ada 95 Reference Manual are fully |
| implemented in GNAT, and in addition, a full interface to C++ is |
| provided. |
| |
| @menu |
| * Interfacing to C:: |
| * Interfacing to C++:: |
| * Interfacing to COBOL:: |
| * Interfacing to Fortran:: |
| * Interfacing to non-GNAT Ada code:: |
| @end menu |
| |
| @node Interfacing to C |
| @section Interfacing to C |
| |
| @noindent |
| Interfacing to C with GNAT can use one of two approaches: |
| |
| @itemize @bullet |
| @item |
| The types in the package @code{Interfaces.C} may be used. |
| @item |
| Standard Ada types may be used directly. This may be less portable to |
| other compilers, but will work on all GNAT compilers, which guarantee |
| correspondence between the C and Ada types. |
| @end itemize |
| |
| @noindent |
| Pragma @code{Convention C} may be applied to Ada types, but mostly has no |
| effect, since this is the default. The following table shows the |
| correspondence between Ada scalar types and the corresponding C types. |
| |
| @table @code |
| @item Integer |
| @code{int} |
| @item Short_Integer |
| @code{short} |
| @item Short_Short_Integer |
| @code{signed char} |
| @item Long_Integer |
| @code{long} |
| @item Long_Long_Integer |
| @code{long long} |
| @item Short_Float |
| @code{float} |
| @item Float |
| @code{float} |
| @item Long_Float |
| @code{double} |
| @item Long_Long_Float |
| This is the longest floating-point type supported by the hardware. |
| @end table |
| |
| @noindent |
| Additionally, there are the following general correspondences between Ada |
| and C types: |
| @itemize @bullet |
| @item |
| Ada enumeration types map to C enumeration types directly if pragma |
| @code{Convention C} is specified, which causes them to have int |
| length. Without pragma @code{Convention C}, Ada enumeration types map to |
| 8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short}, |
| @code{int}, respectively) depending on the number of values passed. |
| This is the only case in which pragma @code{Convention C} affects the |
| representation of an Ada type. |
| |
| @item |
| Ada access types map to C pointers, except for the case of pointers to |
| unconstrained types in Ada, which have no direct C equivalent. |
| |
| @item |
| Ada arrays map directly to C arrays. |
| |
| @item |
| Ada records map directly to C structures. |
| |
| @item |
| Packed Ada records map to C structures where all members are bit fields |
| of the length corresponding to the @code{@var{type}'Size} value in Ada. |
| @end itemize |
| |
| @node Interfacing to C++ |
| @section Interfacing to C++ |
| |
| @noindent |
| The interface to C++ makes use of the following pragmas, which are |
| primarily intended to be constructed automatically using a binding generator |
| tool, although it is possible to construct them by hand. No suitable binding |
| generator tool is supplied with GNAT though. |
| |
| Using these pragmas it is possible to achieve complete |
| inter-operability between Ada tagged types and C class definitions. |
| See @ref{Implementation Defined Pragmas}, for more details. |
| |
| @table @code |
| @item pragma CPP_Class ([Entity =>] @var{local_NAME}) |
| The argument denotes an entity in the current declarative region that is |
| declared as a tagged or untagged record type. It indicates that the type |
| corresponds to an externally declared C++ class type, and is to be laid |
| out the same way that C++ would lay out the type. |
| |
| @item pragma CPP_Constructor ([Entity =>] @var{local_NAME}) |
| This pragma identifies an imported function (imported in the usual way |
| with pragma @code{Import}) as corresponding to a C++ constructor. |
| |
| @item pragma CPP_Vtable @dots{} |
| One @code{CPP_Vtable} pragma can be present for each component of type |
| @code{CPP.Interfaces.Vtable_Ptr} in a record to which pragma @code{CPP_Class} |
| applies. |
| @end table |
| |
| @node Interfacing to COBOL |
| @section Interfacing to COBOL |
| |
| @noindent |
| Interfacing to COBOL is achieved as described in section B.4 of |
| the Ada 95 reference manual. |
| |
| @node Interfacing to Fortran |
| @section Interfacing to Fortran |
| |
| @noindent |
| Interfacing to Fortran is achieved as described in section B.5 of the |
| reference manual. The pragma @code{Convention Fortran}, applied to a |
| multi-dimensional array causes the array to be stored in column-major |
| order as required for convenient interface to Fortran. |
| |
| @node Interfacing to non-GNAT Ada code |
| @section Interfacing to non-GNAT Ada code |
| |
| It is possible to specify the convention @code{Ada} in a pragma |
| @code{Import} or pragma @code{Export}. However this refers to |
| the calling conventions used by GNAT, which may or may not be |
| similar enough to those used by some other Ada 83 or Ada 95 |
| compiler to allow interoperation. |
| |
| If arguments types are kept simple, and if the foreign compiler generally |
| follows system calling conventions, then it may be possible to integrate |
| files compiled by other Ada compilers, provided that the elaboration |
| issues are adequately addressed (for example by eliminating the |
| need for any load time elaboration). |
| |
| In particular, GNAT running on VMS is designed to |
| be highly compatible with the DEC Ada 83 compiler, so this is one |
| case in which it is possible to import foreign units of this type, |
| provided that the data items passed are restricted to simple scalar |
| values or simple record types without variants, or simple array |
| types with fixed bounds. |
| |
| @node Specialized Needs Annexes |
| @chapter Specialized Needs Annexes |
| |
| @noindent |
| Ada 95 defines a number of specialized needs annexes, which are not |
| required in all implementations. However, as described in this chapter, |
| GNAT implements all of these special needs annexes: |
| |
| @table @asis |
| @item Systems Programming (Annex C) |
| The Systems Programming Annex is fully implemented. |
| |
| @item Real-Time Systems (Annex D) |
| The Real-Time Systems Annex is fully implemented. |
| |
| @item Distributed Systems (Annex E) |
| Stub generation is fully implemented in the GNAT compiler. In addition, |
| a complete compatible PCS is available as part of the GLADE system, |
| a separate product. When the two |
| products are used in conjunction, this annex is fully implemented. |
| |
| @item Information Systems (Annex F) |
| The Information Systems annex is fully implemented. |
| |
| @item Numerics (Annex G) |
| The Numerics Annex is fully implemented. |
| |
| @item Safety and Security (Annex H) |
| The Safety and Security annex is fully implemented. |
| @end table |
| |
| @node Implementation of Specific Ada Features |
| @chapter Implementation of Specific Ada Features |
| |
| @noindent |
| This chapter describes the GNAT implementation of several Ada language |
| facilities. |
| |
| @menu |
| * Machine Code Insertions:: |
| * GNAT Implementation of Tasking:: |
| * GNAT Implementation of Shared Passive Packages:: |
| * Code Generation for Array Aggregates:: |
| * The Size of Discriminated Records with Default Discriminants:: |
| * Strict Conformance to the Ada 95 Reference Manual:: |
| @end menu |
| |
| @node Machine Code Insertions |
| @section Machine Code Insertions |
| |
| @noindent |
| Package @code{Machine_Code} provides machine code support as described |
| in the Ada 95 Reference Manual in two separate forms: |
| @itemize @bullet |
| @item |
| Machine code statements, consisting of qualified expressions that |
| fit the requirements of RM section 13.8. |
| @item |
| An intrinsic callable procedure, providing an alternative mechanism of |
| including machine instructions in a subprogram. |
| @end itemize |
| |
| @noindent |
| The two features are similar, and both are closely related to the mechanism |
| provided by the asm instruction in the GNU C compiler. Full understanding |
| and use of the facilities in this package requires understanding the asm |
| instruction as described in @cite{Using the GNU Compiler Collection (GCC)} |
| by Richard Stallman. The relevant section is titled ``Extensions to the C |
| Language Family'' -> ``Assembler Instructions with C Expression Operands''. |
| |
| Calls to the function @code{Asm} and the procedure @code{Asm} have identical |
| semantic restrictions and effects as described below. Both are provided so |
| that the procedure call can be used as a statement, and the function call |
| can be used to form a code_statement. |
| |
| The first example given in the GCC documentation is the C @code{asm} |
| instruction: |
| @smallexample |
| asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); |
| @end smallexample |
| |
| @noindent |
| The equivalent can be written for GNAT as: |
| |
| @smallexample @c ada |
| Asm ("fsinx %1 %0", |
| My_Float'Asm_Output ("=f", result), |
| My_Float'Asm_Input ("f", angle)); |
| @end smallexample |
| |
| @noindent |
| The first argument to @code{Asm} is the assembler template, and is |
| identical to what is used in GNU C@. This string must be a static |
| expression. The second argument is the output operand list. It is |
| either a single @code{Asm_Output} attribute reference, or a list of such |
| references enclosed in parentheses (technically an array aggregate of |
| such references). |
| |
| The @code{Asm_Output} attribute denotes a function that takes two |
| parameters. The first is a string, the second is the name of a variable |
| of the type designated by the attribute prefix. The first (string) |
| argument is required to be a static expression and designates the |
| constraint for the parameter (e.g.@: what kind of register is |
| required). The second argument is the variable to be updated with the |
| result. The possible values for constraint are the same as those used in |
| the RTL, and are dependent on the configuration file used to build the |
| GCC back end. If there are no output operands, then this argument may |
| either be omitted, or explicitly given as @code{No_Output_Operands}. |
| |
| The second argument of @code{@var{my_float}'Asm_Output} functions as |
| though it were an @code{out} parameter, which is a little curious, but |
| all names have the form of expressions, so there is no syntactic |
| irregularity, even though normally functions would not be permitted |
| @code{out} parameters. The third argument is the list of input |
| operands. It is either a single @code{Asm_Input} attribute reference, or |
| a list of such references enclosed in parentheses (technically an array |
| aggregate of such references). |
| |
| The @code{Asm_Input} attribute denotes a function that takes two |
| parameters. The first is a string, the second is an expression of the |
| type designated by the prefix. The first (string) argument is required |
| to be a static expression, and is the constraint for the parameter, |
| (e.g.@: what kind of register is required). The second argument is the |
| value to be used as the input argument. The possible values for the |
| constant are the same as those used in the RTL, and are dependent on |
| the configuration file used to built the GCC back end. |
| |
| If there are no input operands, this argument may either be omitted, or |
| explicitly given as @code{No_Input_Operands}. The fourth argument, not |
| present in the above example, is a list of register names, called the |
| @dfn{clobber} argument. This argument, if given, must be a static string |
| expression, and is a space or comma separated list of names of registers |
| that must be considered destroyed as a result of the @code{Asm} call. If |
| this argument is the null string (the default value), then the code |
| generator assumes that no additional registers are destroyed. |
| |
| The fifth argument, not present in the above example, called the |
| @dfn{volatile} argument, is by default @code{False}. It can be set to |
| the literal value @code{True} to indicate to the code generator that all |
| optimizations with respect to the instruction specified should be |
| suppressed, and that in particular, for an instruction that has outputs, |
| the instruction will still be generated, even if none of the outputs are |
| used. See the full description in the GCC manual for further details. |
| |
| The @code{Asm} subprograms may be used in two ways. First the procedure |
| forms can be used anywhere a procedure call would be valid, and |
| correspond to what the RM calls ``intrinsic'' routines. Such calls can |
| be used to intersperse machine instructions with other Ada statements. |
| Second, the function forms, which return a dummy value of the limited |
| private type @code{Asm_Insn}, can be used in code statements, and indeed |
| this is the only context where such calls are allowed. Code statements |
| appear as aggregates of the form: |
| |
| @smallexample @c ada |
| Asm_Insn'(Asm (@dots{})); |
| Asm_Insn'(Asm_Volatile (@dots{})); |
| @end smallexample |
| |
| @noindent |
| In accordance with RM rules, such code statements are allowed only |
| within subprograms whose entire body consists of such statements. It is |
| not permissible to intermix such statements with other Ada statements. |
| |
| Typically the form using intrinsic procedure calls is more convenient |
| and more flexible. The code statement form is provided to meet the RM |
| suggestion that such a facility should be made available. The following |
| is the exact syntax of the call to @code{Asm}. As usual, if named notation |
| is used, the arguments may be given in arbitrary order, following the |
| normal rules for use of positional and named arguments) |
| |
| @smallexample |
| ASM_CALL ::= Asm ( |
| [Template =>] static_string_EXPRESSION |
| [,[Outputs =>] OUTPUT_OPERAND_LIST ] |
| [,[Inputs =>] INPUT_OPERAND_LIST ] |
| [,[Clobber =>] static_string_EXPRESSION ] |
| [,[Volatile =>] static_boolean_EXPRESSION] ) |
| |
| OUTPUT_OPERAND_LIST ::= |
| [PREFIX.]No_Output_Operands |
| | OUTPUT_OPERAND_ATTRIBUTE |
| | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) |
| |
| OUTPUT_OPERAND_ATTRIBUTE ::= |
| SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) |
| |
| INPUT_OPERAND_LIST ::= |
| [PREFIX.]No_Input_Operands |
| | INPUT_OPERAND_ATTRIBUTE |
| | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) |
| |
| INPUT_OPERAND_ATTRIBUTE ::= |
| SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) |
| @end smallexample |
| |
| @noindent |
| The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} |
| are declared in the package @code{Machine_Code} and must be referenced |
| according to normal visibility rules. In particular if there is no |
| @code{use} clause for this package, then appropriate package name |
| qualification is required. |
| |
| @node GNAT Implementation of Tasking |
| @section GNAT Implementation of Tasking |
| |
| @noindent |
| This chapter outlines the basic GNAT approach to tasking (in particular, |
| a multi-layered library for portability) and discusses issues related |
| to compliance with the Real-Time Systems Annex. |
| |
| @menu |
| * Mapping Ada Tasks onto the Underlying Kernel Threads:: |
| * Ensuring Compliance with the Real-Time Annex:: |
| @end menu |
| |
| @node Mapping Ada Tasks onto the Underlying Kernel Threads |
| @subsection Mapping Ada Tasks onto the Underlying Kernel Threads |
| |
| @noindent |
| GNAT's run-time support comprises two layers: |
| |
| @itemize @bullet |
| @item GNARL (GNAT Run-time Layer) |
| @item GNULL (GNAT Low-level Library) |
| @end itemize |
| |
| @noindent |
| In GNAT, Ada's tasking services rely on a platform and OS independent |
| layer known as GNARL@. This code is responsible for implementing the |
| correct semantics of Ada's task creation, rendezvous, protected |
| operations etc. |
| |
| GNARL decomposes Ada's tasking semantics into simpler lower level |
| operations such as create a thread, set the priority of a thread, |
| yield, create a lock, lock/unlock, etc. The spec for these low-level |
| operations constitutes GNULLI, the GNULL Interface. This interface is |
| directly inspired from the POSIX real-time API@. |
| |
| If the underlying executive or OS implements the POSIX standard |
| faithfully, the GNULL Interface maps as is to the services offered by |
| the underlying kernel. Otherwise, some target dependent glue code maps |
| the services offered by the underlying kernel to the semantics expected |
| by GNARL@. |
| |
| Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the |
| key point is that each Ada task is mapped on a thread in the underlying |
| kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. |
| |
| In addition Ada task priorities map onto the underlying thread priorities. |
| Mapping Ada tasks onto the underlying kernel threads has several advantages: |
| |
| @itemize @bullet |
| @item |
| The underlying scheduler is used to schedule the Ada tasks. This |
| makes Ada tasks as efficient as kernel threads from a scheduling |
| standpoint. |
| |
| @item |
| Interaction with code written in C containing threads is eased |
| since at the lowest level Ada tasks and C threads map onto the same |
| underlying kernel concept. |
| |
| @item |
| When an Ada task is blocked during I/O the remaining Ada tasks are |
| able to proceed. |
| |
| @item |
| On multiprocessor systems Ada tasks can execute in parallel. |
| @end itemize |
| |
| @noindent |
| Some threads libraries offer a mechanism to fork a new process, with the |
| child process duplicating the threads from the parent. |
| GNAT does not |
| support this functionality when the parent contains more than one task. |
| @cindex Forking a new process |
| |
| @node Ensuring Compliance with the Real-Time Annex |
| @subsection Ensuring Compliance with the Real-Time Annex |
| @cindex Real-Time Systems Annex compliance |
| |
| @noindent |
| Although mapping Ada tasks onto |
| the underlying threads has significant advantages, it does create some |
| complications when it comes to respecting the scheduling semantics |
| specified in the real-time annex (Annex D). |
| |
| For instance the Annex D requirement for the @code{FIFO_Within_Priorities} |
| scheduling policy states: |
| |
| @quotation |
| @emph{When the active priority of a ready task that is not running |
| changes, or the setting of its base priority takes effect, the |
| task is removed from the ready queue for its old active priority |
| and is added at the tail of the ready queue for its new active |
| priority, except in the case where the active priority is lowered |
| due to the loss of inherited priority, in which case the task is |
| added at the head of the ready queue for its new active priority.} |
| @end quotation |
| |
| @noindent |
| While most kernels do put tasks at the end of the priority queue when |
| a task changes its priority, (which respects the main |
| FIFO_Within_Priorities requirement), almost none keep a thread at the |
| beginning of its priority queue when its priority drops from the loss |
| of inherited priority. |
| |
| As a result most vendors have provided incomplete Annex D implementations. |
| |
| The GNAT run-time, has a nice cooperative solution to this problem |
| which ensures that accurate FIFO_Within_Priorities semantics are |
| respected. |
| |
| The principle is as follows. When an Ada task T is about to start |
| running, it checks whether some other Ada task R with the same |
| priority as T has been suspended due to the loss of priority |
| inheritance. If this is the case, T yields and is placed at the end of |
| its priority queue. When R arrives at the front of the queue it |
| executes. |
| |
| Note that this simple scheme preserves the relative order of the tasks |
| that were ready to execute in the priority queue where R has been |
| placed at the end. |
| |
| @node GNAT Implementation of Shared Passive Packages |
| @section GNAT Implementation of Shared Passive Packages |
| @cindex Shared passive packages |
| |
| @noindent |
| GNAT fully implements the pragma @code{Shared_Passive} for |
| @cindex pragma @code{Shared_Passive} |
| the purpose of designating shared passive packages. |
| This allows the use of passive partitions in the |
| context described in the Ada Reference Manual; i.e. for communication |
| between separate partitions of a distributed application using the |
| features in Annex E. |
| @cindex Annex E |
| @cindex Distribution Systems Annex |
| |
| However, the implementation approach used by GNAT provides for more |
| extensive usage as follows: |
| |
| @table @emph |
| @item Communication between separate programs |
| |
| This allows separate programs to access the data in passive |
| partitions, using protected objects for synchronization where |
| needed. The only requirement is that the two programs have a |
| common shared file system. It is even possible for programs |
| running on different machines with different architectures |
| (e.g. different endianness) to communicate via the data in |
| a passive partition. |
| |
| @item Persistence between program runs |
| |
| The data in a passive package can persist from one run of a |
| program to another, so that a later program sees the final |
| values stored by a previous run of the same program. |
| |
| @end table |
| |
| @noindent |
| The implementation approach used is to store the data in files. A |
| separate stream file is created for each object in the package, and |
| an access to an object causes the corresponding file to be read or |
| written. |
| |
| The environment variable @code{SHARED_MEMORY_DIRECTORY} should be |
| @cindex @code{SHARED_MEMORY_DIRECTORY} environment variable |
| set to the directory to be used for these files. |
| The files in this directory |
| have names that correspond to their fully qualified names. For |
| example, if we have the package |
| |
| @smallexample @c ada |
| package X is |
| pragma Shared_Passive (X); |
| Y : Integer; |
| Z : Float; |
| end X; |
| @end smallexample |
| |
| @noindent |
| and the environment variable is set to @code{/stemp/}, then the files created |
| will have the names: |
| |
| @smallexample |
| /stemp/x.y |
| /stemp/x.z |
| @end smallexample |
| |
| @noindent |
| These files are created when a value is initially written to the object, and |
| the files are retained until manually deleted. This provides the persistence |
| semantics. If no file exists, it means that no partition has assigned a value |
| to the variable; in this case the initial value declared in the package |
| will be used. This model ensures that there are no issues in synchronizing |
| the elaboration process, since elaboration of passive packages elaborates the |
| initial values, but does not create the files. |
| |
| The files are written using normal @code{Stream_IO} access. |
| If you want to be able |
| to communicate between programs or partitions running on different |
| architectures, then you should use the XDR versions of the stream attribute |
| routines, since these are architecture independent. |
| |
| If active synchronization is required for access to the variables in the |
| shared passive package, then as described in the Ada Reference Manual, the |
| package may contain protected objects used for this purpose. In this case |
| a lock file (whose name is @file{___lock} (three underscores) |
| is created in the shared memory directory. |
| @cindex @file{___lock} file (for shared passive packages) |
| This is used to provide the required locking |
| semantics for proper protected object synchronization. |
| |
| As of January 2003, GNAT supports shared passive packages on all platforms |
| except for OpenVMS. |
| |
| @node Code Generation for Array Aggregates |
| @section Code Generation for Array Aggregates |
| |
| @menu |
| * Static constant aggregates with static bounds:: |
| * Constant aggregates with unconstrained nominal types:: |
| * Aggregates with static bounds:: |
| * Aggregates with non-static bounds:: |
| * Aggregates in assignment statements:: |
| @end menu |
| |
| @noindent |
| Aggregates have a rich syntax and allow the user to specify the values of |
| complex data structures by means of a single construct. As a result, the |
| code generated for aggregates can be quite complex and involve loops, case |
| statements and multiple assignments. In the simplest cases, however, the |
| compiler will recognize aggregates whose components and constraints are |
| fully static, and in those cases the compiler will generate little or no |
| executable code. The following is an outline of the code that GNAT generates |
| for various aggregate constructs. For further details, you will find it |
| useful to examine the output produced by the -gnatG flag to see the expanded |
| source that is input to the code generator. You may also want to examine |
| the assembly code generated at various levels of optimization. |
| |
| The code generated for aggregates depends on the context, the component values, |
| and the type. In the context of an object declaration the code generated is |
| generally simpler than in the case of an assignment. As a general rule, static |
| component values and static subtypes also lead to simpler code. |
| |
| @node Static constant aggregates with static bounds |
| @subsection Static constant aggregates with static bounds |
| |
| @noindent |
| For the declarations: |
| @smallexample @c ada |
| type One_Dim is array (1..10) of integer; |
| ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); |
| @end smallexample |
| |
| @noindent |
| GNAT generates no executable code: the constant ar0 is placed in static memory. |
| The same is true for constant aggregates with named associations: |
| |
| @smallexample @c ada |
| Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); |
| Cr3 : constant One_Dim := (others => 7777); |
| @end smallexample |
| |
| @noindent |
| The same is true for multidimensional constant arrays such as: |
| |
| @smallexample @c ada |
| type two_dim is array (1..3, 1..3) of integer; |
| Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); |
| @end smallexample |
| |
| @noindent |
| The same is true for arrays of one-dimensional arrays: the following are |
| static: |
| |
| @smallexample @c ada |
| type ar1b is array (1..3) of boolean; |
| type ar_ar is array (1..3) of ar1b; |
| None : constant ar1b := (others => false); -- fully static |
| None2 : constant ar_ar := (1..3 => None); -- fully static |
| @end smallexample |
| |
| @noindent |
| However, for multidimensional aggregates with named associations, GNAT will |
| generate assignments and loops, even if all associations are static. The |
| following two declarations generate a loop for the first dimension, and |
| individual component assignments for the second dimension: |
| |
| @smallexample @c ada |
| Zero1: constant two_dim := (1..3 => (1..3 => 0)); |
| Zero2: constant two_dim := (others => (others => 0)); |
| @end smallexample |
| |
| @node Constant aggregates with unconstrained nominal types |
| @subsection Constant aggregates with unconstrained nominal types |
| |
| @noindent |
| In such cases the aggregate itself establishes the subtype, so that |
| associations with @code{others} cannot be used. GNAT determines the |
| bounds for the actual subtype of the aggregate, and allocates the |
| aggregate statically as well. No code is generated for the following: |
| |
| @smallexample @c ada |
| type One_Unc is array (natural range <>) of integer; |
| Cr_Unc : constant One_Unc := (12,24,36); |
| @end smallexample |
| |
| @node Aggregates with static bounds |
| @subsection Aggregates with static bounds |
| |
| @noindent |
| In all previous examples the aggregate was the initial (and immutable) value |
| of a constant. If the aggregate initializes a variable, then code is generated |
| for it as a combination of individual assignments and loops over the target |
| object. The declarations |
| |
| @smallexample @c ada |
| Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); |
| Cr_Var2 : One_Dim := (others > -1); |
| @end smallexample |
| |
| @noindent |
| generate the equivalent of |
| |
| @smallexample @c ada |
| Cr_Var1 (1) := 2; |
| Cr_Var1 (2) := 3; |
| Cr_Var1 (3) := 5; |
| Cr_Var1 (4) := 11; |
| |
| for I in Cr_Var2'range loop |
| Cr_Var2 (I) := =-1; |
| end loop; |
| @end smallexample |
| |
| @node Aggregates with non-static bounds |
| @subsection Aggregates with non-static bounds |
| |
| @noindent |
| If the bounds of the aggregate are not statically compatible with the bounds |
| of the nominal subtype of the target, then constraint checks have to be |
| generated on the bounds. For a multidimensional array, constraint checks may |
| have to be applied to sub-arrays individually, if they do not have statically |
| compatible subtypes. |
| |
| @node Aggregates in assignment statements |
| @subsection Aggregates in assignment statements |
| |
| @noindent |
| In general, aggregate assignment requires the construction of a temporary, |
| and a copy from the temporary to the target of the assignment. This is because |
| it is not always possible to convert the assignment into a series of individual |
| component assignments. For example, consider the simple case: |
| |
| @smallexample @c ada |
| A := (A(2), A(1)); |
| @end smallexample |
| |
| @noindent |
| This cannot be converted into: |
| |
| @smallexample @c ada |
| A(1) := A(2); |
| A(2) := A(1); |
| @end smallexample |
| |
| @noindent |
| So the aggregate has to be built first in a separate location, and then |
| copied into the target. GNAT recognizes simple cases where this intermediate |
| step is not required, and the assignments can be performed in place, directly |
| into the target. The following sufficient criteria are applied: |
| |
| @itemize @bullet |
| @item |
| The bounds of the aggregate are static, and the associations are static. |
| @item |
| The components of the aggregate are static constants, names of |
| simple variables that are not renamings, or expressions not involving |
| indexed components whose operands obey these rules. |
| @end itemize |
| |
| @noindent |
| If any of these conditions are violated, the aggregate will be built in |
| a temporary (created either by the front-end or the code generator) and then |
| that temporary will be copied onto the target. |
| |
| |
| @node The Size of Discriminated Records with Default Discriminants |
| @section The Size of Discriminated Records with Default Discriminants |
| |
| @noindent |
| If a discriminated type @code{T} has discriminants with default values, it is |
| possible to declare an object of this type without providing an explicit |
| constraint: |
| |
| @smallexample @c ada |
| @group |
| type Size is range 1..100; |
| |
| type Rec (D : Size := 15) is record |
| Name : String (1..D); |
| end T; |
| |
| Word : Rec; |
| @end group |
| @end smallexample |
| |
| @noindent |
| Such an object is said to be @emph{unconstrained}. |
| The discriminant of the object |
| can be modified by a full assignment to the object, as long as it preserves the |
| relation between the value of the discriminant, and the value of the components |
| that depend on it: |
| |
| @smallexample @c ada |
| @group |
| Word := (3, "yes"); |
| |
| Word := (5, "maybe"); |
| |
| Word := (5, "no"); -- raises Constraint_Error |
| @end group |
| @end smallexample |
| |
| @noindent |
| In order to support this behavior efficiently, an unconstrained object is |
| given the maximum size that any value of the type requires. In the case |
| above, @code{Word} has storage for the discriminant and for |
| a @code{String} of length 100. |
| It is important to note that unconstrained objects do not require dynamic |
| allocation. It would be an improper implementation to place on the heap those |
| components whose size depends on discriminants. (This improper implementation |
| was used by some Ada83 compilers, where the @code{Name} component above |
| would have |
| been stored as a pointer to a dynamic string). Following the principle that |
| dynamic storage management should never be introduced implicitly, |
| an Ada95 compiler should reserve the full size for an unconstrained declared |
| object, and place it on the stack. |
| |
| This maximum size approach |
| has been a source of surprise to some users, who expect the default |
| values of the discriminants to determine the size reserved for an |
| unconstrained object: ``If the default is 15, why should the object occupy |
| a larger size?'' |
| The answer, of course, is that the discriminant may be later modified, |
| and its full range of values must be taken into account. This is why the |
| declaration: |
| |
| @smallexample |
| @group |
| type Rec (D : Positive := 15) is record |
| Name : String (1..D); |
| end record; |
| |
| Too_Large : Rec; |
| @end group |
| @end smallexample |
| |
| @noindent |
| is flagged by the compiler with a warning: |
| an attempt to create @code{Too_Large} will raise @code{Storage_Error}, |
| because the required size includes @code{Positive'Last} |
| bytes. As the first example indicates, the proper approach is to declare an |
| index type of ``reasonable'' range so that unconstrained objects are not too |
| large. |
| |
| One final wrinkle: if the object is declared to be @code{aliased}, or if it is |
| created in the heap by means of an allocator, then it is @emph{not} |
| unconstrained: |
| it is constrained by the default values of the discriminants, and those values |
| cannot be modified by full assignment. This is because in the presence of |
| aliasing all views of the object (which may be manipulated by different tasks, |
| say) must be consistent, so it is imperative that the object, once created, |
| remain invariant. |
| |
| @node Strict Conformance to the Ada 95 Reference Manual |
| @section Strict Conformance to the Ada 95 Reference Manual |
| |
| @noindent |
| The dynamic semantics defined by the Ada 95 Reference Manual impose a set of |
| run-time checks to be generated. By default, the GNAT compiler will insert many |
| run-time checks into the compiled code, including most of those required by the |
| Ada 95 Reference Manual. However, there are three checks that are not enabled |
| in the default mode for efficiency reasons: arithmetic overflow checking for |
| integer operations (including division by zero), checks for access before |
| elaboration on subprogram calls, and stack overflow checking (most operating |
| systems do not perform this check by default). |
| |
| Strict conformance to the Ada 95 Reference Manual can be achieved by adding |
| three compiler options for overflow checking for integer operations |
| (@option{-gnato}), dynamic checks for access-before-elaboration on subprogram |
| calls and generic instantiations (@option{-gnatE}), and stack overflow |
| checking (@option{-fstack-check}). |
| |
| Note that the result of a floating point arithmetic operation in overflow and |
| invalid situations, when the @code{Machine_Overflows} attribute of the result |
| type is @code{False}, is to generate IEEE NaN and infinite values. This is the |
| case for machines compliant with the IEEE floating-point standard, but on |
| machines that are not fully compliant with this standard, such as Alpha, the |
| @option{-mieee} compiler flag must be used for achieving IEEE confirming |
| behavior (although at the cost of a significant performance penalty), so |
| infinite and and NaN values are properly generated. |
| |
| |
| @node Project File Reference |
| @chapter Project File Reference |
| |
| @noindent |
| This chapter describes the syntax and semantics of project files. |
| Project files specify the options to be used when building a system. |
| Project files can specify global settings for all tools, |
| as well as tool-specific settings. |
| See the chapter on project files in the GNAT Users guide for examples of use. |
| |
| @menu |
| * Reserved Words:: |
| * Lexical Elements:: |
| * Declarations:: |
| * Empty declarations:: |
| * Typed string declarations:: |
| * Variables:: |
| * Expressions:: |
| * Attributes:: |
| * Project Attributes:: |
| * Attribute References:: |
| * External Values:: |
| * Case Construction:: |
| * Packages:: |
| * Package Renamings:: |
| * Projects:: |
| * Project Extensions:: |
| * Project File Elaboration:: |
| @end menu |
| |
| @node Reserved Words |
| @section Reserved Words |
| |
| @noindent |
| All Ada95 reserved words are reserved in project files, and cannot be used |
| as variable names or project names. In addition, the following are |
| also reserved in project files: |
| |
| @itemize |
| @item @code{extends} |
| |
| @item @code{external} |
| |
| @item @code{project} |
| |
| @end itemize |
| |
| @node Lexical Elements |
| @section Lexical Elements |
| |
| @noindent |
| Rules for identifiers are the same as in Ada95. Identifiers |
| are case-insensitive. Strings are case sensitive, except where noted. |
| Comments have the same form as in Ada95. |
| |
| @noindent |
| Syntax: |
| |
| @smallexample |
| simple_name ::= |
| identifier |
| |
| name ::= |
| simple_name @{. simple_name@} |
| @end smallexample |
| |
| @node Declarations |
| @section Declarations |
| |
| @noindent |
| Declarations introduce new entities that denote types, variables, attributes, |
| and packages. Some declarations can only appear immediately within a project |
| declaration. Others can appear within a project or within a package. |
| |
| Syntax: |
| @smallexample |
| declarative_item ::= |
| simple_declarative_item | |
| typed_string_declaration | |
| package_declaration |
| |
| simple_declarative_item ::= |
| variable_declaration | |
| typed_variable_declaration | |
| attribute_declaration | |
| case_construction | |
| empty_declaration |
| @end smallexample |
| |
| @node Empty declarations |
| @section Empty declarations |
| |
| @smallexample |
| empty_declaration ::= |
| @b{null} ; |
| @end smallexample |
| |
| An empty declaration is allowed anywhere a declaration is allowed. |
| It has no effect. |
| |
| @node Typed string declarations |
| @section Typed string declarations |
| |
| @noindent |
| Typed strings are sequences of string literals. Typed strings are the only |
| named types in project files. They are used in case constructions, where they |
| provide support for conditional attribute definitions. |
| |
| Syntax: |
| @smallexample |
| typed_string_declaration ::= |
| @b{type} <typed_string_>_simple_name @b{is} |
| ( string_literal @{, string_literal@} ); |
| @end smallexample |
| |
| @noindent |
| A typed string declaration can only appear immediately within a project |
| declaration. |
| |
| All the string literals in a typed string declaration must be distinct. |
| |
| @node Variables |
| @section Variables |
| |
| @noindent |
| Variables denote values, and appear as constituents of expressions. |
| |
| @smallexample |
| typed_variable_declaration ::= |
| <typed_variable_>simple_name : <typed_string_>name := string_expression ; |
| |
| variable_declaration ::= |
| <variable_>simple_name := expression; |
| @end smallexample |
| |
| @noindent |
| The elaboration of a variable declaration introduces the variable and |
| assigns to it the value of the expression. The name of the variable is |
| available after the assignment symbol. |
| |
| @noindent |
| A typed_variable can only be declare once. |
| |
| @noindent |
| a non typed variable can be declared multiple times. |
| |
| @noindent |
| Before the completion of its first declaration, the value of variable |
| is the null string. |
| |
| @node Expressions |
| @section Expressions |
| |
| @noindent |
| An expression is a formula that defines a computation or retrieval of a value. |
| In a project file the value of an expression is either a string or a list |
| of strings. A string value in an expression is either a literal, the current |
| value of a variable, an external value, an attribute reference, or a |
| concatenation operation. |
| |
| Syntax: |
| |
| @smallexample |
| expression ::= |
| term @{& term@} |
| |
| term ::= |
| string_literal | |
| string_list | |
| <variable_>name | |
| external_value | |
| attribute_reference |
| |
| string_literal ::= |
| (same as Ada) |
| |
| string_list ::= |
| ( <string_>expression @{ , <string_>expression @} ) |
| @end smallexample |
| |
| @subsection Concatenation |
| @noindent |
| The following concatenation functions are defined: |
| |
| @smallexample @c ada |
| function "&" (X : String; Y : String) return String; |
| function "&" (X : String_List; Y : String) return String_List; |
| function "&" (X : String_List; Y : String_List) return String_List; |
| @end smallexample |
| |
| @node Attributes |
| @section Attributes |
| |
| @noindent |
| An attribute declaration defines a property of a project or package. This |
| property can later be queried by means of an attribute reference. |
| Attribute values are strings or string lists. |
| |
| Some attributes are associative arrays. These attributes are mappings whose |
| domain is a set of strings. These attributes are declared one association |
| at a time, by specifying a point in the domain and the corresponding image |
| of the attribute. They may also be declared as a full associative array, |
| getting the same associations as the corresponding attribute in an imported |
| or extended project. |
| |
| Attributes that are not associative arrays are called simple attributes. |
| |
| Syntax: |
| @smallexample |
| attribute_declaration ::= |
| full_associative_array_declaration | |
| @b{for} attribute_designator @b{use} expression ; |
| |
| full_associative_array_declaration ::= |
| @b{for} <associative_array_attribute_>simple_name @b{use} |
| <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ; |
| |
| attribute_designator ::= |
| <simple_attribute_>simple_name | |
| <associative_array_attribute_>simple_name ( string_literal ) |
| @end smallexample |
| |
| @noindent |
| Some attributes are project-specific, and can only appear immediately within |
| a project declaration. Others are package-specific, and can only appear within |
| the proper package. |
| |
| The expression in an attribute definition must be a string or a string_list. |
| The string literal appearing in the attribute_designator of an associative |
| array attribute is case-insensitive. |
| |
| @node Project Attributes |
| @section Project Attributes |
| |
| @noindent |
| The following attributes apply to a project. All of them are simple |
| attributes. |
| |
| @table @code |
| @item Object_Dir |
| Expression must be a path name. The attribute defines the |
| directory in which the object files created by the build are to be placed. If |
| not specified, object files are placed in the project directory. |
| |
| @item Exec_Dir |
| Expression must be a path name. The attribute defines the |
| directory in which the executables created by the build are to be placed. |
| If not specified, executables are placed in the object directory. |
| |
| @item Source_Dirs |
| Expression must be a list of path names. The attribute |
| defines the directories in which the source files for the project are to be |
| found. If not specified, source files are found in the project directory. |
| |
| @item Source_Files |
| Expression must be a list of file names. The attribute |
| defines the individual files, in the project directory, which are to be used |
| as sources for the project. File names are path_names that contain no directory |
| information. If the project has no sources the attribute must be declared |
| explicitly with an empty list. |
| |
| @item Source_List_File |
| Expression must a single path name. The attribute |
| defines a text file that contains a list of source file names to be used |
| as sources for the project |
| |
| @item Library_Dir |
| Expression must be a path name. The attribute defines the |
| directory in which a library is to be built. The directory must exist, must |
| be distinct from the project's object directory, and must be writable. |
| |
| @item Library_Name |
| Expression must be a string that is a legal file name, |
| without extension. The attribute defines a string that is used to generate |
| the name of the library to be built by the project. |
| |
| @item Library_Kind |
| Argument must be a string value that must be one of the |
| following @code{"static"}, @code{"dynamic"} or @code{"relocatable"}. This |
| string is case-insensitive. If this attribute is not specified, the library is |
| a static library. Otherwise, the library may be dynamic or relocatable. This |
| distinction is operating-system dependent. |
| |
| @item Library_Version |
| Expression must be a string value whose interpretation |
| is platform dependent. On UNIX, it is used only for dynamic/relocatable |
| libraries as the internal name of the library (the @code{"soname"}). If the |
| library file name (built from the @code{Library_Name}) is different from the |
| @code{Library_Version}, then the library file will be a symbolic link to the |
| actual file whose name will be @code{Library_Version}. |
| |
| @item Library_Interface |
| Expression must be a string list. Each element of the string list |
| must designate a unit of the project. |
| If this attribute is present in a Library Project File, then the project |
| file is a Stand-alone Library_Project_File. |
| |
| @item Library_Auto_Init |
| Expression must be a single string "true" or "false", case-insensitive. |
| If this attribute is present in a Stand-alone Library Project File, |
| it indicates if initialization is automatic when the dynamic library |
| is loaded. |
| |
| @item Library_Options |
| Expression must be a string list. Indicates additional switches that |
| are to be used when building a shared library. |
| |
| @item Library_GCC |
| Expression must be a single string. Designates an alternative to "gcc" |
| for building shared libraries. |
| |
| @item Library_Src_Dir |
| Expression must be a path name. The attribute defines the |
| directory in which the sources of the interfaces of a Stand-alone Library will |
| be copied. The directory must exist, must be distinct from the project's |
| object directory and source directories of all projects in the project tree, |
| and must be writable. |
| |
| @item Library_Src_Dir |
| Expression must be a path name. The attribute defines the |
| directory in which the ALI files of a Library will |
| be copied. The directory must exist, must be distinct from the project's |
| object directory and source directories of all projects in the project tree, |
| and must be writable. |
| |
| @item Library_Symbol_File |
| Expression must be a single string. Its value is the single file name of a |
| symbol file to be created when building a stand-alone library when the |
| symbol policy is either "compliant", "controlled" or "restricted", |
| on platforms that support symbol control, such as VMS. |
| |
| @item Library_Reference_Symbol_File |
| Expression must be a single string. Its value is the single file name of a |
| reference symbol file that is read when the symbol policy is either |
| "compliant" or "controlled", on platforms that support symbol control, |
| such as VMS, when building a stand-alone library. |
| |
| @item Library_Symbol_Policy |
| Expression must be a single string. Its case-insensitive value can only be |
| "autonomous", "default", "compliant", "controlled" or "restricted". |
| |
| This attribute is not taken into account on all platforms. It controls the |
| policy for exported symbols and, on some platforms (like VMS) that have the |
| notions of major and minor IDs built in the library files, it controls |
| the setting of these IDs. |
| |
| "autonomous" or "default": exported symbols are not controlled. |
| |
| "compliant": if attribute Library_Reference_Symbol_File is not defined, then |
| it is equivalent to policy "autonomous". If there are exported symbols in |
| the reference symbol file that are not in the object files of the interfaces, |
| the major ID of the library is increased. If there are symbols in the |
| object files of the interfaces that are not in the reference symbol file, |
| these symbols are put at the end of the list in the newly created symbol file |
| and the minor ID is increased. |
| |
| "controlled": the attribute Library_Reference_Symbol_File must be defined. |
| The library will fail to build if the exported symbols in the object files of |
| the interfaces do not match exactly the symbol in the symbol file. |
| |
| "restricted": The attribute Library_Symbol_File must be defined. The library |
| will fail to build if there are symbols in the symbol file that are not in |
| the exported symbols of the object files of the interfaces. Additional symbols |
| in the object files are not added to the symbol file. |
| |
| @item Main |
| Expression must be a list of strings that are legal file names. |
| These file names designate existing compilation units in the source directory |
| that are legal main subprograms. |
| |
| When a project file is elaborated, as part of the execution of a gnatmake |
| command, one or several executables are built and placed in the Exec_Dir. |
| If the gnatmake command does not include explicit file names, the executables |
| that are built correspond to the files specified by this attribute. |
| |
| @item Externally_Built |
| Expression must be a single string. Its value must be either "true" of "false", |
| case-insensitive. The default is "false". When the value of this attribute is |
| "true", no attempt is made to compile the sources or to build the library, |
| when the project is a library project. |
| |
| @item Main_Language |
| This is a simple attribute. Its value is a string that specifies the |
| language of the main program. |
| |
| @item Languages |
| Expression must be a string list. Each string designates |
| a programming language that is known to GNAT. The strings are case-insensitive. |
| |
| @item Locally_Removed_Files |
| This attribute is legal only in a project file that extends another. |
| Expression must be a list of strings that are legal file names. |
| Each file name must designate a source that would normally be inherited |
| by the current project file. It cannot designate an immediate source that is |
| not inherited. Each of the source files in the list are not considered to |
| be sources of the project file: they are not inherited. |
| @end table |
| |
| @node Attribute References |
| @section Attribute References |
| |
| @noindent |
| Attribute references are used to retrieve the value of previously defined |
| attribute for a package or project. |
| Syntax: |
| @smallexample |
| attribute_reference ::= |
| attribute_prefix ' <simple_attribute_>simple_name [ ( string_literal ) ] |
| |
| attribute_prefix ::= |
| @b{project} | |
| <project_simple_name | package_identifier | |
| <project_>simple_name . package_identifier |
| @end smallexample |
| |
| @noindent |
| If an attribute has not been specified for a given package or project, its |
| value is the null string or the empty list. |
| |
| @node External Values |
| @section External Values |
| |
| @noindent |
| An external value is an expression whose value is obtained from the command |
| that invoked the processing of the current project file (typically a |
| gnatmake command). |
| |
| Syntax: |
| @smallexample |
| external_value ::= |
| @b{external} ( string_literal [, string_literal] ) |
| @end smallexample |
| |
| @noindent |
| The first string_literal is the string to be used on the command line or |
| in the environment to specify the external value. The second string_literal, |
| if present, is the default to use if there is no specification for this |
| external value either on the command line or in the environment. |
| |
| @node Case Construction |
| @section Case Construction |
| |
| @noindent |
| A case construction supports attribute declarations that depend on the value of |
| a previously declared variable. |
| |
| Syntax: |
| @smallexample |
| case_construction ::= |
| @b{case} <typed_variable_>name @b{is} |
| @{case_item@} |
| @b{end case} ; |
| |
| case_item ::= |
| @b{when} discrete_choice_list => |
| @{case_construction | attribute_declaration | empty_declaration@} |
| |
| discrete_choice_list ::= |
| string_literal @{| string_literal@} | |
| @b{others} |
| @end smallexample |
| |
| @noindent |
| All choices in a choice list must be distinct. The choice lists of two |
| distinct alternatives must be disjoint. Unlike Ada, the choice lists of all |
| alternatives do not need to include all values of the type. An @code{others} |
| choice must appear last in the list of alternatives. |
| |
| @node Packages |
| @section Packages |
| |
| @noindent |
| A package provides a grouping of variable declarations and attribute |
| declarations to be used when invoking various GNAT tools. The name of |
| the package indicates the tool(s) to which it applies. |
| Syntax: |
| |
| @smallexample |
| package_declaration ::= |
| package_specification | package_renaming |
| |
| package_specification ::= |
| @b{package} package_identifier @b{is} |
| @{simple_declarative_item@} |
| @b{end} package_identifier ; |
| |
| package_identifier ::= |
| @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} | |
| @code{Linker} | @code{Finder} | @code{Cross_Reference} | |
| @code{gnatls} | @code{IDE} | @code{Pretty_Printer} |
| @end smallexample |
| |
| @subsection Package Naming |
| |
| @noindent |
| The attributes of a @code{Naming} package specifies the naming conventions |
| that apply to the source files in a project. When invoking other GNAT tools, |
| they will use the sources in the source directories that satisfy these |
| naming conventions. |
| |
| The following attributes apply to a @code{Naming} package: |
| |
| @table @code |
| @item Casing |
| This is a simple attribute whose value is a string. Legal values of this |
| string are @code{"lowercase"}, @code{"uppercase"} or @code{"mixedcase"}. |
| These strings are themselves case insensitive. |
| |
| @noindent |
| If @code{Casing} is not specified, then the default is @code{"lowercase"}. |
| |
| @item Dot_Replacement |
| This is a simple attribute whose string value satisfies the following |
| requirements: |
| |
| @itemize @bullet |
| @item It must not be empty |
| @item It cannot start or end with an alphanumeric character |
| @item It cannot be a single underscore |
| @item It cannot start with an underscore followed by an alphanumeric |
| @item It cannot contain a dot @code{'.'} if longer than one character |
| @end itemize |
| |
| @noindent |
| If @code{Dot_Replacement} is not specified, then the default is @code{"-"}. |
| |
| @item Spec_Suffix |
| This is an associative array attribute, defined on language names, |
| whose image is a string that must satisfy the following |
| conditions: |
| |
| @itemize @bullet |
| @item It must not be empty |
| @item It cannot start with an alphanumeric character |
| @item It cannot start with an underscore followed by an alphanumeric character |
| @end itemize |
| |
| @noindent |
| For Ada, the attribute denotes the suffix used in file names that contain |
| library unit declarations, that is to say units that are package and |
| subprogram declarations. If @code{Spec_Suffix ("Ada")} is not |
| specified, then the default is @code{".ads"}. |
| |
| For C and C++, the attribute denotes the suffix used in file names that |
| contain prototypes. |
| |
| @item Body_Suffix |
| This is an associative array attribute defined on language names, |
| whose image is a string that must satisfy the following |
| conditions: |
| |
| @itemize @bullet |
| @item It must not be empty |
| @item It cannot start with an alphanumeric character |
| @item It cannot start with an underscore followed by an alphanumeric character |
| @item It cannot be a suffix of @code{Spec_Suffix} |
| @end itemize |
| |
| @noindent |
| For Ada, the attribute denotes the suffix used in file names that contain |
| library bodies, that is to say units that are package and subprogram bodies. |
| If @code{Body_Suffix ("Ada")} is not specified, then the default is |
| @code{".adb"}. |
| |
| For C and C++, the attribute denotes the suffix used in file names that contain |
| source code. |
| |
| @item Separate_Suffix |
| This is a simple attribute whose value satisfies the same conditions as |
| @code{Body_Suffix}. |
| |
| This attribute is specific to Ada. It denotes the suffix used in file names |
| that contain separate bodies. If it is not specified, then it defaults to same |
| value as @code{Body_Suffix ("Ada")}. |
| |
| @item Spec |
| This is an associative array attribute, specific to Ada, defined over |
| compilation unit names. The image is a string that is the name of the file |
| that contains that library unit. The file name is case sensitive if the |
| conventions of the host operating system require it. |
| |
| @item Body |
| This is an associative array attribute, specific to Ada, defined over |
| compilation unit names. The image is a string that is the name of the file |
| that contains the library unit body for the named unit. The file name is case |
| sensitive if the conventions of the host operating system require it. |
| |
| @item Specification_Exceptions |
| This is an associative array attribute defined on language names, |
| whose value is a list of strings. |
| |
| This attribute is not significant for Ada. |
| |
| For C and C++, each string in the list denotes the name of a file that |
| contains prototypes, but whose suffix is not necessarily the |
| @code{Spec_Suffix} for the language. |
| |
| @item Implementation_Exceptions |
| This is an associative array attribute defined on language names, |
| whose value is a list of strings. |
| |
| This attribute is not significant for Ada. |
| |
| For C and C++, each string in the list denotes the name of a file that |
| contains source code, but whose suffix is not necessarily the |
| @code{Body_Suffix} for the language. |
| @end table |
| |
| The following attributes of package @code{Naming} are obsolescent. They are |
| kept as synonyms of other attributes for compatibility with previous versions |
| of the Project Manager. |
| |
| @table @code |
| @item Specification_Suffix |
| This is a synonym of @code{Spec_Suffix}. |
| |
| @item Implementation_Suffix |
| This is a synonym of @code{Body_Suffix}. |
| |
| @item Specification |
| This is a synonym of @code{Spec}. |
| |
| @item Implementation |
| This is a synonym of @code{Body}. |
| @end table |
| |
| @subsection package Compiler |
| |
| @noindent |
| The attributes of the @code{Compiler} package specify the compilation options |
| to be used by the underlying compiler. |
| |
| @table @code |
| @item Default_Switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies the compilation options to be used when compiling a component |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies the |
| compilation options to be used when compiling the named file. If a file |
| is not specified in the Switches attribute, it is compiled with the |
| options specified by Default_Switches of its language, if defined. |
| |
| @item Local_Configuration_Pragmas. |
| This is a simple attribute, whose |
| value is a path name that designates a file containing configuration pragmas |
| to be used for all invocations of the compiler for immediate sources of the |
| project. |
| @end table |
| |
| @subsection package Builder |
| |
| @noindent |
| The attributes of package @code{Builder} specify the compilation, binding, and |
| linking options to be used when building an executable for a project. The |
| following attributes apply to package @code{Builder}: |
| |
| @table @code |
| @item Default_Switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when building a main |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when building the named main file. If a main file |
| is not specified in the Switches attribute, it is built with the |
| options specified by Default_Switches of its language, if defined. |
| |
| @item Global_Configuration_Pragmas |
| This is a simple attribute, whose |
| value is a path name that designates a file that contains configuration pragmas |
| to be used in every build of an executable. If both local and global |
| configuration pragmas are specified, a compilation makes use of both sets. |
| |
| |
| @item Executable |
| This is an associative array attribute. Its domain is |
| a set of main source file names. Its range is a simple string that specifies |
| the executable file name to be used when linking the specified main source. |
| If a main source is not specified in the Executable attribute, the executable |
| file name is deducted from the main source file name. |
| This attribute has no effect if its value is the empty string. |
| |
| @item Executable_Suffix |
| This is a simple attribute whose value is the suffix to be added to |
| the executables that don't have an attribute Executable specified. |
| @end table |
| |
| @subsection package Gnatls |
| |
| @noindent |
| The attributes of package @code{Gnatls} specify the tool options to be used |
| when invoking the library browser @command{gnatls}. |
| The following attributes apply to package @code{Gnatls}: |
| |
| @table @code |
| @item Switches |
| This is a single attribute with a string list value. Each non empty string |
| in the list is an option when invoking @code{gnatls}. |
| @end table |
| |
| @subsection package Binder |
| |
| @noindent |
| The attributes of package @code{Binder} specify the options to be used |
| when invoking the binder in the construction of an executable. |
| The following attributes apply to package @code{Binder}: |
| |
| @table @code |
| @item Default_Switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when binding a main |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when binding the named main file. If a main file |
| is not specified in the Switches attribute, it is bound with the |
| options specified by Default_Switches of its language, if defined. |
| @end table |
| |
| @subsection package Linker |
| |
| @noindent |
| The attributes of package @code{Linker} specify the options to be used when |
| invoking the linker in the construction of an executable. |
| The following attributes apply to package @code{Linker}: |
| |
| @table @code |
| @item Default_Switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when linking a main |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when linking the named main file. If a main file |
| is not specified in the Switches attribute, it is linked with the |
| options specified by Default_Switches of its language, if defined. |
| |
| @item Linker_Options |
| This is a string list attribute. Its value specifies additional options that |
| be given to the linker when linking an executable. This attribute is not |
| used in the main project, only in projects imported directly or indirectly. |
| |
| @end table |
| |
| @subsection package Cross_Reference |
| |
| @noindent |
| The attributes of package @code{Cross_Reference} specify the tool options |
| to be used |
| when invoking the library tool @command{gnatxref}. |
| The following attributes apply to package @code{Cross_Reference}: |
| |
| @table @code |
| @item Default_Switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when calling @command{gnatxref} on a source |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when calling @command{gnatxref} on the named main source. |
| If a source is not specified in the Switches attribute, @command{gnatxref} will |
| be called with the options specified by Default_Switches of its language, |
| if defined. |
| @end table |
| |
| @subsection package Finder |
| |
| @noindent |
| The attributes of package @code{Finder} specify the tool options to be used |
| when invoking the search tool @command{gnatfind}. |
| The following attributes apply to package @code{Finder}: |
| |
| @table @code |
| @item Default_Switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when calling @command{gnatfind} on a source |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when calling @command{gnatfind} on the named main source. |
| If a source is not specified in the Switches attribute, @command{gnatfind} will |
| be called with the options specified by Default_Switches of its language, |
| if defined. |
| @end table |
| |
| @subsection package Pretty_Printer |
| |
| @noindent |
| The attributes of package @code{Pretty_Printer} |
| specify the tool options to be used |
| when invoking the formatting tool @command{gnatpp}. |
| The following attributes apply to package @code{Pretty_Printer}: |
| |
| @table @code |
| @item Default_switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when calling @command{gnatpp} on a source |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when calling @command{gnatpp} on the named main source. |
| If a source is not specified in the Switches attribute, @command{gnatpp} will |
| be called with the options specified by Default_Switches of its language, |
| if defined. |
| @end table |
| |
| @subsection package gnatstub |
| |
| @noindent |
| The attributes of package @code{gnatstub} |
| specify the tool options to be used |
| when invoking the tool @command{gnatstub}. |
| The following attributes apply to package @code{gnatstub}: |
| |
| @table @code |
| @item Default_switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when calling @command{gnatstub} on a source |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when calling @command{gnatstub} on the named main source. |
| If a source is not specified in the Switches attribute, @command{gnatpp} will |
| be called with the options specified by Default_Switches of its language, |
| if defined. |
| @end table |
| |
| @subsection package Eliminate |
| |
| @noindent |
| The attributes of package @code{Eliminate} |
| specify the tool options to be used |
| when invoking the tool @command{gnatelim}. |
| The following attributes apply to package @code{Eliminate}: |
| |
| @table @code |
| @item Default_switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when calling @command{gnatelim} on a source |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when calling @command{gnatelim} on the named main source. |
| If a source is not specified in the Switches attribute, @command{gnatelim} will |
| be called with the options specified by Default_Switches of its language, |
| if defined. |
| @end table |
| |
| @subsection package Metrics |
| |
| @noindent |
| The attributes of package @code{Metrics} |
| specify the tool options to be used |
| when invoking the tool @command{gnatmetric}. |
| The following attributes apply to package @code{Metrics}: |
| |
| @table @code |
| @item Default_switches |
| This is an associative array attribute. Its |
| domain is a set of language names. Its range is a string list that |
| specifies options to be used when calling @command{gnatmetric} on a source |
| written in that language, for which no file-specific switches have been |
| specified. |
| |
| @item Switches |
| This is an associative array attribute. Its domain is |
| a set of file names. Its range is a string list that specifies |
| options to be used when calling @command{gnatmetric} on the named main source. |
| If a source is not specified in the Switches attribute, @command{gnatmetric} |
| will be called with the options specified by Default_Switches of its language, |
| if defined. |
| @end table |
| |
| @subsection package IDE |
| |
| @noindent |
| The attributes of package @code{IDE} specify the options to be used when using |
| an Integrated Development Environment such as @command{GPS}. |
| |
| @table @code |
| @item Remote_Host |
| This is a simple attribute. Its value is a string that designates the remote |
| host in a cross-compilation environment, to be used for remote compilation and |
| debugging. This field should not be specified when running on the local |
| machine. |
| |
| @item Program_Host |
| This is a simple attribute. Its value is a string that specifies the |
| name of IP address of the embedded target in a cross-compilation environment, |
| on which the program should execute. |
| |
| @item Communication_Protocol |
| This is a simple string attribute. Its value is the name of the protocol |
| to use to communicate with the target in a cross-compilation environment, |
| e.g. @code{"wtx"} or @code{"vxworks"}. |
| |
| @item Compiler_Command |
| This is an associative array attribute, whose domain is a language name. Its |
| value is string that denotes the command to be used to invoke the compiler. |
| The value of @code{Compiler_Command ("Ada")} is expected to be compatible with |
| gnatmake, in particular in the handling of switches. |
| |
| @item Debugger_Command |
| This is simple attribute, Its value is a string that specifies the name of |
| the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4. |
| |
| @item Default_Switches |
| This is an associative array attribute. Its indexes are the name of the |
| external tools that the GNAT Programming System (GPS) is supporting. Its |
| value is a list of switches to use when invoking that tool. |
| |
| @item Gnatlist |
| This is a simple attribute. Its value is a string that specifies the name |
| of the @command{gnatls} utility to be used to retrieve information about the |
| predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}. |
| |
| @item VCS_Kind |
| This is a simple attribute. Its value is a string used to specify the |
| Version Control System (VCS) to be used for this project, e.g CVS, RCS |
| ClearCase or Perforce. |
| |
| @item VCS_File_Check |
| This is a simple attribute. Its value is a string that specifies the |
| command used by the VCS to check the validity of a file, either |
| when the user explicitly asks for a check, or as a sanity check before |
| doing the check-in. |
| |
| @item VCS_Log_Check |
| This is a simple attribute. Its value is a string that specifies |
| the command used by the VCS to check the validity of a log file. |
| |
| @end table |
| |
| @node Package Renamings |
| @section Package Renamings |
| |
| @noindent |
| A package can be defined by a renaming declaration. The new package renames |
| a package declared in a different project file, and has the same attributes |
| as the package it renames. |
| Syntax: |
| @smallexample |
| package_renaming ::== |
| @b{package} package_identifier @b{renames} |
| <project_>simple_name.package_identifier ; |
| @end smallexample |
| |
| @noindent |
| The package_identifier of the renamed package must be the same as the |
| package_identifier. The project whose name is the prefix of the renamed |
| package must contain a package declaration with this name. This project |
| must appear in the context_clause of the enclosing project declaration, |
| or be the parent project of the enclosing child project. |
| |
| @node Projects |
| @section Projects |
| |
| @noindent |
| A project file specifies a set of rules for constructing a software system. |
| A project file can be self-contained, or depend on other project files. |
| Dependencies are expressed through a context clause that names other projects. |
| |
| Syntax: |
| |
| @smallexample |
| project ::= |
| context_clause project_declaration |
| |
| project_declaration ::= |
| simple_project_declaration | project_extension |
| |
| simple_project_declaration ::= |
| @b{project} <project_>simple_name @b{is} |
| @{declarative_item@} |
| @b{end} <project_>simple_name; |
| |
| context_clause ::= |
| @{with_clause@} |
| |
| with_clause ::= |
| [@b{limited}] @b{with} path_name @{ , path_name @} ; |
| |
| path_name ::= |
| string_literal |
| @end smallexample |
| |
| @noindent |
| A path name denotes a project file. A path name can be absolute or relative. |
| An absolute path name includes a sequence of directories, in the syntax of |
| the host operating system, that identifies uniquely the project file in the |
| file system. A relative path name identifies the project file, relative |
| to the directory that contains the current project, or relative to a |
| directory listed in the environment variable ADA_PROJECT_PATH. |
| Path names are case sensitive if file names in the host operating system |
| are case sensitive. |
| |
| The syntax of the environment variable ADA_PROJECT_PATH is a list of |
| directory names separated by colons (semicolons on Windows). |
| |
| A given project name can appear only once in a context_clause. |
| |
| It is illegal for a project imported by a context clause to refer, directly |
| or indirectly, to the project in which this context clause appears (the |
| dependency graph cannot contain cycles), except when one of the with_clause |
| in the cycle is a @code{limited with}. |
| |
| @node Project Extensions |
| @section Project Extensions |
| |
| @noindent |
| A project extension introduces a new project, which inherits the declarations |
| of another project. |
| Syntax: |
| @smallexample |
| |
| project_extension ::= |
| @b{project} <project_>simple_name @b{extends} path_name @b{is} |
| @{declarative_item@} |
| @b{end} <project_>simple_name; |
| @end smallexample |
| |
| @noindent |
| The project extension declares a child project. The child project inherits |
| all the declarations and all the files of the parent project, These inherited |
| declaration can be overridden in the child project, by means of suitable |
| declarations. |
| |
| @node Project File Elaboration |
| @section Project File Elaboration |
| |
| @noindent |
| A project file is processed as part of the invocation of a gnat tool that |
| uses the project option. Elaboration of the process file consists in the |
| sequential elaboration of all its declarations. The computed values of |
| attributes and variables in the project are then used to establish the |
| environment in which the gnat tool will execute. |
| |
| @node Obsolescent Features |
| @chapter Obsolescent Features |
| |
| @noindent |
| This chapter describes features that are provided by GNAT, but are |
| considered obsolescent since there are preferred ways of achieving |
| the same effect. These features are provided solely for historical |
| compatibility purposes. |
| |
| @menu |
| * pragma No_Run_Time:: |
| * pragma Ravenscar:: |
| * pragma Restricted_Run_Time:: |
| @end menu |
| |
| @node pragma No_Run_Time |
| @section pragma No_Run_Time |
| |
| The pragma @code{No_Run_Time} is used to achieve an affect similar |
| to the use of the "Zero Foot Print" configurable run time, but without |
| requiring a specially configured run time. The result of using this |
| pragma, which must be used for all units in a partition, is to restrict |
| the use of any language features requiring run-time support code. The |
| preferred usage is to use an appropriately configured run-time that |
| includes just those features that are to be made accessible. |
| |
| @node pragma Ravenscar |
| @section pragma Ravenscar |
| |
| The pragma @code{Ravenscar} has exactly the same effect as pragma |
| @code{Profile (Ravenscar)}. The latter usage is preferred since it |
| is part of the new Ada 2005 standard. |
| |
| @node pragma Restricted_Run_Time |
| @section pragma Restricted_Run_Time |
| |
| The pragma @code{Restricted_Run_Time} has exactly the same effect as |
| pragma @code{Profile (Restricted)}. The latter usage is |
| preferred since the Ada 2005 pragma @code{Profile} is intended for |
| this kind of implementation dependent addition. |
| |
| @include fdl.texi |
| @c GNU Free Documentation License |
| |
| @node Index,,GNU Free Documentation License, Top |
| @unnumbered Index |
| |
| @printindex cp |
| |
| @contents |
| |
| @bye |