X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=gcc%2Fada%2Fgnat_rm.texi;fp=gcc%2Fada%2Fgnat_rm.texi;h=0000000000000000000000000000000000000000;hb=6fed43773c9b0ce596dca5686f37ac3fc0fa11c0;hp=0c6866bd1f23ec2b7b432537665947cc8115185d;hpb=27b11d56b743098deb193d510b337ba22dc52e5c;p=msp430-gcc.git diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi deleted file mode 100644 index 0c6866bd..00000000 --- a/gcc/ada/gnat_rm.texi +++ /dev/null @@ -1,11797 +0,0 @@ -\input texinfo @c -*-texinfo-*- - -@c %**start of header - -@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo -@c o -@c GNAT DOCUMENTATION o -@c o -@c G N A T _ RM o -@c o -@c $Revision: 1.3.12.2 $ -@c o -@c Copyright (C) 1992-2001 Ada Core Technologies, Inc. o -@c o -@c GNAT is free software; you can redistribute it and/or modify it under o -@c terms of the GNU General Public License as published by the Free Soft- o -@c ware Foundation; either version 2, or (at your option) any later ver- o -@c sion. GNAT is distributed in the hope that it will be useful, but WITH- o -@c OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY o -@c or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License o -@c for more details. You should have received a copy of the GNU General o -@c Public License distributed with GNAT; see file COPYING. If not, write o -@c to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, o -@c MA 02111-1307, USA. 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 -@settitle GNAT Reference Manual -@setchapternewpage odd -@syncodeindex fn cp - -@titlepage - - -@title GNAT Reference Manual -@subtitle GNAT, The GNU Ada 95 Compiler -@subtitle Version 3.15w -@subtitle Document revision level $Revision: 1.3.12.2 $ -@subtitle Date: $Date: 2002/04/21 13:59:45 $ -@author Ada Core Technologies, Inc. - -@page -@vskip 0pt plus 1filll - - -Copyright @copyright{} 1995-2001, Ada Core Technologies - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 -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''. - -Silicon Graphics and IRIS are registered trademarks -and IRIX is a trademark of Silicon Graphics, Inc. - -IBM PC is a trademark of International -Business Machines Corporation. - -UNIX is a registered trademark of AT&T -Bell Laboratories. -DIGITAL - -VADS is a registered trademark of Rational Software Inc. - -The following are trademarks of Digital Equipment Corporation: -DEC, DEC Ada, DECthreads, Digital, OpenVMS, and VAX@. - -@end titlepage -@ifnottex -@node Top, About This Guide, (dir), (dir) -@top GNAT Reference Manual - - -GNAT Reference Manual - -GNAT, The GNU Ada 95 Compiler - -Version 3.14a - -Date: $Date: 2002/04/21 13:59:45 $ - -Ada Core Technologies, Inc. - - -Copyright @copyright{} 1995-2001, Ada Core Technologies - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 -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". - - -Silicon Graphics and IRIS are registered trademarks -and IRIX is a trademark of Silicon Graphics, Inc. - -IBM PC is a trademark of International -Business Machines Corporation. - -UNIX is a registered trademark of AT&T -Bell Laboratories. -DIGITAL - -VADS is a registered trademark of Rational Software Inc. - -The following are trademarks of Digital Equipment Corporation: -DEC, DEC Ada, DECthreads, Digital, OpenVMS, and VAX@. - -@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:: -* Machine Code Insertions:: -* GNAT Implementation of Tasking:: -* Code generation for array aggregates:: -* Specialized Needs Annexes:: -* Compatibility Guide:: -* GNU Free Documentation License:: -* Index:: - - --- The Detailed Node Listing --- - -About This Guide - -* What This Reference Manual Contains:: -* Related Information:: - -The Implementation of Standard I/O - -* Standard I/O Packages:: -* FORM Strings:: -* Direct_IO:: -* Sequential_IO:: -* Text_IO:: -* Wide_Text_IO:: -* Stream_IO:: -* Shared Files:: -* Open Modes:: -* Operations on C Streams:: -* Interfacing to C Streams:: - -The GNAT Library - -* Ada.Characters.Wide_Latin_1 (a-cwila1.ads):: -* Ada.Command_Line.Remove (a-colire.ads):: -* Ada.Direct_IO.C_Streams (a-diocst.ads):: -* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.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.Text_IO.C_Streams (a-tiocst.ads):: -* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: -* GNAT.AWK (g-awk.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.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_Tables (g-dyntab.ads):: -* GNAT.Exception_Traces (g-exctra.ads):: -* GNAT.Expect (g-expect.ads):: -* GNAT.Float_Control (g-flocon.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.Most_Recent_Exception (g-moreex.ads):: -* GNAT.OS_Lib (g-os_lib.ads):: -* GNAT.Regexp (g-regexp.ads):: -* GNAT.Registry (g-regist.ads):: -* GNAT.Regpat (g-regpat.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.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):: -* 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):: -* System.Address_Image (s-addima.ads):: -* System.Assertions (s-assert.ads):: -* System.Partition_Interface (s-parint.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:: - -Interfacing to Other Languages - -* Interfacing to C:: -* Interfacing to C++:: -* Interfacing to COBOL:: -* Interfacing to Fortran:: -* Interfacing to non-GNAT Ada code:: - -GNAT Implementation of Tasking - -* Mapping Ada Tasks onto the Underlying Kernel Threads:: -* Ensuring Compliance with the Real-Time Annex:: -@end menu - -@end ifnottex - -@node About This Guide -@unnumbered About This Guide - -@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. - -Ada 95 is designed to be highly portable,and guarantees that, for most -programs, Ada 95 compilers behave in exactly the same manner on -different machines. 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. - -@c Maybe put the following in platform-specific section -@ignore -@cindex ProDev Ada -This reference manual discusses how these features are implemented for -use in ProDev Ada running on the IRIX 5.3 or greater operating systems. -@end ignore - -@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. - -@menu -* What This Reference Manual Contains:: -* Conventions:: -* Related Information:: -@end menu - -@node What This Reference Manual Contains -@unnumberedsec What This Reference Manual Contains - -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{Interfacing to Other Languages} describes how programs -written in Ada using GNAT can be interfaced to other programming -languages. - -@item -@ref{Specialized Needs Annexes} describes the GNAT implementation of all -of the special needs annexes. - -@item -@ref{Compatibility Guide} includes sections on compatibility of GNAT with -other Ada 83 and Ada 95 compilation systems, to assist in porting code -from other environments. -@end itemize - -@cindex Ada 95 ISO/ANSI Standard -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 -@samp{Option flags} - -@item -@file{File Names}, @file{button names}, and @file{field names}. - -@item -@var{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 "$ " (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 $ replaced by whatever prompt character you are using. - -@node Related Information -@unnumberedsec Related Information -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. - -@table @code - -@findex Abort_Defer -@cindex Deferring aborts -@item pragma Abort_Defer -@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). - -@item pragma Ada_83 -@findex Ada_83 -@noindent -Syntax: - -@smallexample -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 (<>) 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. - -@findex Ada_95 -@item pragma Ada_95 -@noindent -Syntax: - -@smallexample -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. - -@findex Annotate -@item pragma Annotate -@noindent -Syntax: - -@smallexample -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@. - -@findex Assert -@item pragma Assert -@noindent -Syntax: - -@smallexample -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 -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 -... -if J > 3 then - pragma Assert (K > 3, "Bad value for K"); - null; -end if; -@end smallexample - -@noindent -Note that, as with the if statement to which it is equivalent, the -type of the expression is either 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 System.Assertions.Raise_Assert_Failure is called -which results in the raising of 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. - -@cindex OpenVMS -@findex Ast_Entry -@item pragma Ast_Entry -@noindent -Syntax: - -@smallexample -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. - -@cindex Passing by copy -@findex C_Pass_By_Copy -@item pragma C_Pass_By_Copy -@noindent -Syntax: - -@smallexample -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. - -@findex Comment -@item pragma Comment -@noindent -Syntax: - -@smallexample -pragma Comment (static_string_EXPRESSION); -@end smallexample - -@noindent -This is almost identical in effect to pragma 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 Comment, unlike Ident, has no limit on the -length of the string argument, and no limitations on placement -of the pragma (it can be placed anywhere in the main source unit). - -@findex Common_Object -@item pragma Common_Object -@noindent -Syntax: - -@smallexample -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. - -@findex Complex_Representation -@item pragma Complex_Representation -@noindent -Syntax: - -@smallexample -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. - -@cindex Alignments of components -@findex Component_Alignment -@item pragma Component_Alignment -@noindent -Syntax: - -@smallexample -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 - -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. - -@findex CPP_Class -@cindex Interfacing with C++ -@item pragma CPP_Class -@noindent -Syntax: - -@smallexample -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. Ada Core Technologies does -not currently supply such a -tool; See @ref{Interfacing to C++} for more details. - -@cindex Interfacing with C++ -@findex CPP_Constructor -@item pragma CPP_Constructor -@noindent -Syntax: - -@smallexample -pragma CPP_Constructor ([Entity =>] LOCAL_NAME); -@end smallexample - -@noindent -This pragma identifies an imported function (imported in the usual way -with pragma Import) as corresponding to a C++ -constructor. The argument is a name that must have been -previously mentioned in a pragma -Import with @var{Convention 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 - -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-function-call with} @dots{})} -@end itemize - -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. Ada Core Technologies does -not currently supply such a -tool; See @ref{Interfacing to C++} for more details. - -@cindex Interfacing to C++ -@findex CPP_Virtual -@item pragma CPP_Virtual -@noindent -Syntax: - -@smallexample -pragma CPP_Virtual - [Entity =>] ENTITY, - [, [Vtable_Ptr =>] vtable_ENTITY,] - [, [Position =>] static_integer_EXPRESSION]) -@end smallexample - -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. Ada Core Technologies does -not currently supply such a -tool; See @ref{Interfacing to C++} for more details. - -@cindex Interfacing with C++ -@findex CPP_Vtable -@item pragma CPP_Vtable -@noindent -Syntax: - -@smallexample -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. Ada Core Technologies does -not currently supply such a -tool; See @ref{Interfacing to C++} for more details. - -@findex Debug -@item pragma Debug -@noindent -Syntax: - -@smallexample -pragma Debug (PROCEDURE_CALL_STATEMENT); -@end smallexample - -@noindent -If assertions are not enabled on the command line, this pragma has no -effect. If asserts are enabled, the semantics of the pragma is exactly -equivalent to the procedure call. 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. - -@cindex Elaboration control -@findex Elaboration_Checks -@item pragma Elaboration_Checks -@noindent -Syntax: - -@smallexample -pragma Elaboration_Checks (RM | 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 RM, 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 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 GNAT Users Guide. - -@cindex Elimination of unused subprograms -@findex Eliminate -@item pragma Eliminate -@noindent -Syntax: - -@smallexample -pragma Eliminate ( - [Unit_Name =>] IDENTIFIER | - SELECTED_COMPONENT); - -pragma Eliminate ( - [Unit_Name =>] IDENTIFIER | - SELECTED_COMPONENT - [Entity =>] IDENTIFIER | - SELECTED_COMPONENT | - STRING_LITERAL] - [,[Parameter_Types =>] PARAMETER_TYPES] - [,[Result_Type =>] result_SUBTYPE_NAME]]); - -PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@}) -SUBTYPE_NAME ::= 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 may be either a subprogram -or a variable. - -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. 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 third and fourth parameters are optionally used to distinguish -between overloaded subprograms, 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 string literals, again corresponding -to the internal manner in which GNAT stores entity names. - -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 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 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 Eliminate. - -Note that the reason this pragma takes string literals where names might -be expected is that a pragma Eliminate can appear in a context where the -relevant names are not visible. - -@cindex OpenVMS -@findex Export_Exception -@item pragma Export_Exception -@noindent -Syntax: - -@smallexample -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. - -@cindex Argument passing mechanisms -@findex Export_Function -@item pragma Export_Function @dots{} - -@noindent -Syntax: - -@smallexample -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 -| SUBTYPE_MARK @{, SUBTYPE_MARK@} - -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 - -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. -@cindex OpenVMS -@cindex Passing by descriptor -Passing by descriptor is supported only on the OpenVMS ports of GNAT@. - -@findex Export_Object -@item pragma Export_Object @dots{} -@noindent -Syntax: - -@smallexample -pragma Export_Object - [Internal =>] LOCAL_NAME, - [, [External =>] EXTERNAL_SYMBOL] - [, [Size =>] EXTERNAL_SYMBOL] - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION -@end smallexample - -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@. - -@findex Export_Procedure -@item pragma Export_Procedure @dots{} -@noindent -Syntax: - -@smallexample -pragma Export_Procedure ( - [Internal =>] LOCAL_NAME - [, [External =>] EXTERNAL_SYMBOL] - [, [Parameter_Types =>] PARAMETER_TYPES] - [, [Mechanism =>] MECHANISM]); - -EXTERNAL_SYMBOL ::= - IDENTIFIER -| static_string_EXPRESSION - -PARAMETER_TYPES ::= - null -| SUBTYPE_MARK @{, SUBTYPE_MARK@} - -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{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. - -@findex Export_Valued_Procedure -@item pragma Export_Valued_Procedure -@noindent -Syntax: - -@smallexample -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 -| SUBTYPE_MARK @{, SUBTYPE_MARK@} - -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 - -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 @code{system}, extending -@cindex Dec Ada 83 -@findex Extend_System -@item pragma Extend_System -@noindent -Syntax: - -@smallexample -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. - -@findex External -@item pragma External -@noindent -Syntax: - -@smallexample -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. - -@cindex Dec Ada 83 casing compatibility -@cindex External Names, casing -@cindex Casing of External names -@findex External_Name_Casing -@item pragma External_Name_Casing -@noindent -Syntax: - -@smallexample -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 - 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 -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 @code{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 @code{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 -pragma External_Name_Casing (Uppercase, Uppercase); -@end smallexample - -@noindent -to enforce the upper casing of all external symbols. - -@findex Finalize_Storage_Only -@item pragma Finalize_Storage_Only -@noindent -Syntax: - -@smallexample -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. - -@cindex OpenVMS -@findex Float_Representation -@item pragma Float_Representation -@noindent -Syntax: - -@smallexample -pragma Float_Representation (FLOAT_REP); - -FLOAT_REP ::= VAX_Float | IEEE_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 -floating point types declared in the packages @code{Standard} and -@code{System}. For further details on this pragma, see the -DEC Ada Language Reference Manual, section 3.5.7a. 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 Users Guide for details on the use of this command. - -@findex Ident -@item pragma Ident -@noindent -Syntax: - -@smallexample -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. -The maximum permitted length of the string literal is 31 characters. -This pragma is allowed only in the outermost declarative part or -declarative items of a compilation unit. -@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. - -@cindex OpenVMS -@findex Import_Exception -@item pragma Import_Exception -@noindent -Syntax: - -@smallexample -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. - -@findex Import_Function -@item pragma Import_Function @dots{} -@noindent -Syntax: - -@smallexample -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 -| SUBTYPE_MARK @{, SUBTYPE_MARK@} - -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 - -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_Name} 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. - -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 to 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. - -@findex Import_Object -@item pragma Import_Object -@noindent -Syntax: - -@smallexample -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@. - -@findex Import_Procedure -@item pragma Import_Procedure -@noindent -Syntax: - -@smallexample -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 -| SUBTYPE_MARK @{, SUBTYPE_MARK@} - -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. - -@findex Import_Valued_Procedure -@item pragma Import_Valued_Procedure @dots{} -@noindent -Syntax: - -@smallexample -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 -| SUBTYPE_MARK @{, SUBTYPE_MARK@} - -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. - -@findex Initialize_Scalars -@cindex debugging with Initialize_Scalars -@item pragma Initialize_Scalars -@noindent -Syntax: - -@smallexample -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 there is control over the value used -for initializing scalar objects. At bind time, you can select whether to -initialize with invalid values (like Normalize_Scalars), or 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. - -Note that pragma @code{Initialize_Scalars} is particularly useful in -conjunction with the enhanced validity checking that is now provided -in @code{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. - -@findex Inline_Always -@item pragma Inline_Always -@noindent -Syntax: - -@smallexample -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} for inter-unit inlining. - -@findex Inline_Generic -@item pragma Inline_Generic -@noindent -Syntax: - -@smallexample -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@. - -@findex Interface -@item pragma Interface -@noindent -Syntax: - -@smallexample -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. - -@findex Interface_Name -@item pragma Interface_Name -@noindent -Syntax: - -@smallexample -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}. - -@findex License -@item pragma License -@cindex License checking -@noindent -Syntax: - -@smallexample -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 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@. This is the license used for the GNAT run-time which ensures -that the run-time can be used freely in any program without GPL concerns. - -@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 appearence 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 adapated 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 -with Sem_Ch3; -with GNAT.Sockets; -procedure Secret_Stuff is -... -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@. - -@findex Link_With -@item pragma Link_With -@noindent -Syntax: - -@smallexample -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 -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. - -@findex Linker_Alias -@item pragma Linker_Alias -@noindent -Syntax: - -@smallexample -pragma Linker_Alias ( - [Entity =>] LOCAL_NAME - [Alias =>] static_string_EXPRESSION); -@end smallexample - -@noindent -This pragma establishes a linker alias for the given named entity. For -further details on the exact effect, consult the GCC manual. - -@findex Linker_Section -@item pragma Linker_Section -@noindent -Syntax: - -@smallexample -pragma Linker_Section ( - [Entity =>] LOCAL_NAME - [Section =>] static_string_EXPRESSION); -@end smallexample - -@noindent -This pragma specifies the name of the linker section for the given entity. -For further details on the exact effect, consult the GCC manual. - -@findex No_Run_Time -@item pragma No_Run_Time -@noindent -Syntax: - -@smallexample -pragma No_Run_Time; -@end smallexample - -@noindent -This is a configuration pragma that makes sure the user code does not -use nor need anything from the GNAT run time. This is mostly useful in -context where code certification is required. Please consult the High -Integrity product documentation for additional information. - -@findex Normalize_Scalars -@item pragma Normalize_Scalars -@noindent -Syntax: - -@smallexample -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. This will be out of range of the subtype only if -the subtype range excludes this value. - -@item Standard.Wide_Character -@noindent -Objects whose root type is Standard.Wide_Character are initialized to -Wide_Character'Last. This will be out of range of the subtype only if -the subtype range excludes this value. - -@item Integer types -@noindent -Objects of an integer type are initialized to base_type'First, where -base_type is the base type of the object type. This will be out of range -of the subtype only if the subtype range excludes this value. For example, -if you declare the subtype: - -@smallexample -subtype Ityp is integer range 1 .. 10; -@end smallexample - -@noindent -then objects of type x will be initialized to Integer'First, a negative -number that is certainly outside the range of subtype @code{Ityp}. - -@item Real types -Objects of all real types (fixed and floating) are initialized to -base_type'First, where base_Type is the base type of the object type. -This will be out of range of the subtype only if the subtype range -excludes this value. - -@item Modular types -Objects of a modular type are initialized to typ'Last. This will be out -of range of the subtype only if the subtype excludes this value. - -@item Enumeration types -Objects of an enumeration type are initialized to all one-bits, i.e.@: to -the value 2 ** typ'Size - 1. This will be out of range of the enumeration -subtype in all cases except where the subtype contains exactly -2**8, 2**16, or 2**32. - -@end table - -@cindex OpenVMS -@findex Long_Float -@item pragma Long_Float -@noindent -Syntax: - -@smallexample -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 .. 15. -For further details on this pragma, see the -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 Users Guide for details on the use of this command. - -@findex Machine_Attribute -@item pragma Machine_Attribute @dots{} -@noindent -Syntax: - -@smallexample -pragma Machine_Attribute ( - [Attribute_Name =>] string_EXPRESSION, - [Entity =>] LOCAL_NAME); -@end smallexample - -Machine dependent attributes can be specified for types and/or -declarations. Currently only subprogram entities are supported. This -pragma is semantically equivalent to @code{__attribute__(( -@var{string_expression}))} in GNU C, where @code{string_expression}> is -recognized by the GNU C macros @code{VALID_MACHINE_TYPE_ATTRIBUTE} and -@code{VALID_MACHINE_DECL_ATTRIBUTE} which are defined in the -configuration header file @file{tm.h} for each machine. See the GCC -manual for further information. - -@cindex OpenVMS -@findex Main_Storage -@item pragma Main_Storage -@noindent -Syntax: - -@smallexample -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. - -@findex No_Return -@item pragma No_Return -@noindent -Syntax: - -@smallexample -pragma No_Return (procedure_LOCAL_NAME); -@end smallexample - -@noindent -@var{procedure_local_NAME} 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, -and also may not contain any implicit return statements from falling off -the end of a statement sequence. 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. - -@findex Passive -@item pragma Passive -@noindent -Syntax: - -@smallexample -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 no 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). - -@findex Polling -@item pragma Polling -@noindent -Syntax: - -@smallexample -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 Ada.Exceptions.Poll. This routine is a separate unit in the -runtime library, and can be found in file a-excpol.adb. - -Pragma polling can appear as a configuration pragma (for example it can be -placed in the 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 Poll -routine is called frequently, and places an upper bound (determined by -the complexity of the code) on the period between two 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 Ada.Exceptions package that can be found -in files a-except.ads/adb. - -A standard alternative unit (called 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 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 -gnatP switch. See -the GNAT User's Guide for details. - -@findex Propagate_Exceptions -@cindex Zero Cost Exceptions -@item pragma Propagate_Exceptions -@noindent -Syntax: - -@smallexample -pragma Propagate_Exceptions (subprogram_LOCAL_NAME); -@end smallexample - -@noindent -This pragma indicates that the given entity, which is the name of an -imported foreign-language subprogram may receive an Ada exception, -and that the exception should be propagated. It is relevant only if -zero cost exception handling is in use, and is thus never needed if -the alternative longjmp/setjmp implementation of exceptions is used -(although it is harmless to use it in such cases). - -The implementation of fast exceptions always properly propagates -exceptions through Ada code, as described in the Ada Reference Manual. -However, this manual is silent about the propagation of exceptions -through foreign code. For example, consider the -situation where @code{P1} calls -@code{P2}, and @code{P2} calls @code{P3}, where -@code{P1} and @code{P3} are in Ada, but @code{P2} is in C@. -@code{P3} raises an Ada exception. The question is whether or not -it will be propagated through @code{P2} and can be handled in -@code{P1}. - -For the longjmp/setjmp implementation of exceptions, the answer is -always yes. For some targets on which zero cost exception handling -is implemented, the answer is also always yes. However, there are -some targets, notably in the current version all x86 architecture -targets, in which the answer is that such propagation does not -happen automatically. If such propagation is required on these -targets, it is mandatory to use @code{Propagate_Exceptions} to -name all foreign language routines through which Ada exceptions -may be propagated. - -@findex Psect_Object -@item pragma Psect_Object -@noindent -Syntax: - -@smallexample -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}. - -@findex Pure_Function -@item pragma Pure_Function -@noindent -Syntax: - -@smallexample -pragma Pure_Function ([Entity =>] function_LOCAL_NAME); -@end smallexample - -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). If 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 @var{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. An -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. The use -of pragma Pure_Function for such a function will override this default -assumption, and cause the compiler to treat such a function as pure. - -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. - -@findex Ravenscar -@item pragma Ravenscar -@noindent -Syntax: - -@smallexample -pragma Ravenscar -@end smallexample - -@noindent -A configuration pragma that establishes the following set of restrictions: - -@table @code -@item No_Abort_Statements -[RM D.7] There are no abort_statements, and there are -no calls to Task_Identification.Abort_Task. - -@item No_Select_Statements -There are no select_statements. - -@item No_Task_Hierarchy -[RM D.7] All (non-environment) tasks depend -directly on the environment task of the partition. - -@item No_Task_Allocators -[RM D.7] There are no allocators for task types -or types containing task subcomponents. - -@item No_Dynamic_Priorities -[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. - -@item No_Terminate_Alternatives -[RM D.7] There are no selective_accepts with terminate_alternatives - -@item No_Dynamic_Interrupts -There are no semantic dependencies on Ada.Interrupts. - -@item No_Protected_Type_Allocators -There are no allocators for protected types or -types containing protected subcomponents. - -@item No_Local_Protected_Objects -Protected objects and access types that designate -such objects shall be declared only at library level. - -@item No_Requeue -Requeue statements are not allowed. - -@item No_Calendar -There are no semantic dependencies on the package Ada.Calendar. - -@item No_Relative_Delay -There are no delay_relative_statements. - -@item No_Task_Attributes -There are no semantic dependencies on the Ada.Task_Attributes package and -there are no references to the attributes Callable and Terminated [RM 9.9]. - -@item Static_Storage_Size -The expression for pragma Storage_Size is static. - -@item Boolean_Entry_Barriers -Entry barrier condition expressions shall be boolean -objects which are declared in the protected type -which contains the entry. - -@item Max_Asynchronous_Select_Nesting = 0 -[RM D.7] Specifies the maximum dynamic nesting level of asynchronous_selects. -A value of zero prevents the use of any asynchronous_select. - -@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 Ravenscar pragma, the value of Max_Task_Entries is always -0 (zero). - -@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 Ravenscar pragma the value of -Max_Protected_Entries is always 1. - -@item Max_Select_Alternatives = 0 -[RM D.7] Specifies the maximum number of alternatives in a selective_accept. -For the Ravenscar pragma the value if always 0. - -@item No_Task_Termination -Tasks which terminate are erroneous. - -@item No_Entry_Queue -No task can be queued on a protected entry. Note that this restrictions is -checked at run time. The violation of this restriction generates a -Program_Error exception. -@end table - -@noindent -This set of restrictions corresponds to the definition of the "Ravenscar -Profile" for limited tasking, devised and published by the International -Workshop On Real Time Ada", 1997. - -The above set is a superset of the restrictions provided by pragma -@code{Restricted_Run_Time}, it includes six additional restrictions -(@code{Boolean_Entry_Barriers}, @code{No_Select_Statements}, -@code{No_Calendar}, @code{Static_Storage_Size}, -@code{No_Relative_Delay} and @code{No_Task_Termination}). This means -that pragma Ravenscar, like the pragma Restricted_Run_Time, automatically -causes the use of a simplified, more efficient version of the tasking -run-time system. - -@findex Restricted_Run_Time -@item pragma Restricted_Run_Time -@noindent -Syntax: - -@smallexample -pragma Restricted_Run_Time -@end smallexample - -@noindent -A configuration pragma that establishes the following set of restrictions: - -@itemize @bullet -@item No_Abort_Statements -@item No_Asynchronous_Control -@item No_Entry_Queue -@item No_Task_Hierarchy -@item No_Task_Allocators -@item No_Dynamic_Priorities -@item No_Terminate_Alternatives -@item No_Dynamic_Interrupts -@item No_Protected_Type_Allocators -@item No_Local_Protected_Objects -@item No_Requeue -@item No_Task_Attributes -@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. - -@findex Share_Generic -@item pragma Share_Generic -@noindent -Syntax: - -@smallexample -pragma Share_Generic (NAME @{, NAME@}); -@end smallexample - -@noindent -This pragma is recognized for compatibility with other Ada compilers -but is ignored by GNAT@. GNAT does not provide the capability for -sharing of generic code. All generic instantiations result in making -an inlined copy of the template with appropriate substitutions. - -@findex Source_File_Name -@item pragma Source_File_Name -@noindent -Syntax: - -@smallexample -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 -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. - -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 GNAT User's Guide. - -@findex Source_Reference -@item pragma Source_Reference -@noindent -Syntax: - -@smallexample -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 @samp{-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. - -@findex Stream_Convert -@item pragma Stream_Convert -@noindent -Syntax: - -@smallexample -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 -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 -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. - -@findex Style_Checks -@item pragma Style_Checks -@noindent -Syntax: - -@smallexample -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 on the @code{gcc} or @code{gnatmake} -line. For example the following two methods can be used to enable -layout checking: - -@smallexample -pragma Style_Checks ("l"); -gcc -c -gnatyl ... -@end smallexample - -@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 -@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 -@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 - -@findex Subtitle -@item pragma Subtitle -@noindent -Syntax: - -@smallexample -pragma Subtitle ([Subtitle =>] STRING_LITERAL); -@end smallexample - -@noindent -This pragma is recognized for compatibility with other Ada compilers -but is ignored by GNAT@. - -@findex Suppress_All -@item pragma Suppress_All -@noindent -Syntax: - -@smallexample -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@. - -@findex Suppress_Initialization -@cindex Suppressing initialization -@cindex Initialization, suppression of -@item pragma Suppress_Initialization -@noindent -Syntax: - -@smallexample -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. - -@findex Task_Info -@item pragma Task_Info -@noindent -Syntax - -@smallexample -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 -aspect 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. - -@findex Task_Name -@item pragma Task_Name -@noindent -Syntax - -@smallexample -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 --- 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 - -@findex Task_Storage -@item pragma Task_Storage -Syntax: - -@smallexample -pragma Task_Storage - [Task_Type =>] LOCAL_NAME, - [Top_Guard =>] static_integer_EXPRESSION); -@end smallexample - -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. - -@findex Time_Slice -@item pragma Time_Slice -@noindent -Syntax: - -@smallexample -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. - -@findex Title -@item pragma Title -@noindent -Syntax: - -@smallexample -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. - -@cindex Unions in C -@findex Unchecked_Union -@item pragma Unchecked_Union -@noindent -Syntax: - -@smallexample -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 - -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 - -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 - -@findex Unimplemented_Unit -@item pragma Unimplemented_Unit -@noindent -Syntax: - -@smallexample -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. - -@findex Unreserve_All_Interrupts -@item pragma Unreserve_All_Interrupts -@noindent -Syntax: - -@smallexample -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 an @code{Ctrl-C} interrupt. Normally this interrupt is -reserved to the implementation, so that @code{Ctrl-C} can be used to -interrupt execution. - -If the pragma 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 -@code{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 Ada.Interrupts.Names in -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 Unreserve_All_Interrupts pragma. - -@findex Unsuppress -@item pragma Unsuppress -@noindent -Syntax: - -@smallexample -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. - -@cindex @code{Size}, VADS compatibility -@findex Use_VADS_Size -@item pragma Use_VADS_Size -@noindent -Syntax: - -@smallexample -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. - -@findex Validity_Checks -@item pragma Validity_Checks -@noindent -Syntax: - -@smallexample -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: - -@smallexample -pragma Validity_Checks ("im"); -gcc -c -gnatVim ... -@end smallexample - -@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 -@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 - -@findex Volatile -@item pragma Volatile -@noindent -Syntax: - -@smallexample -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. - -@findex Warnings -@item pragma Warnings -@noindent -Syntax: - -@smallexample -pragma Warnings (On | Off [, LOCAL_NAME]); -@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}). - -@findex Weak_External -@item pragma Weak_External -@noindent -Syntax: - -@smallexample -pragma Weak_External ([Entity =>] LOCAL_NAME); -@end smallexample - -@noindent -This pragma specifies that the given entity should be marked as a weak -external (one that does not have to be resolved) for the linker. For -further details, consult the GCC manual. -@end table - -@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. - -@table @code -@findex Abort_Signal -@item 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). - -@cindex Size of @code{Address} -@findex Address_Size -@item 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 used primarily for constructing the definition of -@code{Memory_Size} in package @code{Standard}, but may be freely used in user -programs and has the advantage of being static, while a direct -reference to System.Address'Size is non-static because Address -is a private type. - -@findex Asm_Input -@item 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} - -@findex Asm_Output -@item 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} - -@cindex OpenVMS -@findex AST_Entry -@item 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 Extend_System (Aux_DEC)). This value enables the given entry to -be called when an AST occurs. For further details, refer to the DEC Ada -Language Reference Manual, section 9.12a. - -@findex Bit -@item 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. - -@findex Bit_Position -@item 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}. - -@findex Code_Address -@cindex Subprogram address -@cindex Address of subprogram code -@item Code_Address -@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 -procedure K is ... - -procedure L; -for L'Address use K'Address; -pragma Import (Ada, L); -@end smallexample - -@noindent -A call to L is then expected to result in a call to 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 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 Address value described above. For example, -the 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. - -@cindex Big endian -@cindex Little endian -@findex Default_Bit_Order -@item 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}. - -@findex Elaborated -@item 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. - -@findex Elab_Body -@item 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. - -@findex Elab_Spec -@item 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. - -@cindex Ada 83 attributes -@findex Emax -@item 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. - -@cindex Representation of enums -@findex Enum_Rep -@item Enum_Rep -@noindent -For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a -function with the following specification: - -@smallexample -function @var{S}'Enum_Rep (Arg : @var{S}'Base) - return Universal_Integer; -@end smallexample - -@noindent -It is also allowable to apply 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). - -@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 (<>) discrete formal arguments in a generic unit that -can be instantiated with either enumeration types or integer types. Note -that if 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}. - -@cindex Ada 83 attributes -@findex Epsilon -@item 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. - -@findex Fixed_Value -@item Fixed_Value -@noindent -For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a -function with the following specification: - -@smallexample -function @var{S}'Fixed_Value (Arg : Universal_Integer) - return @var{S}; -@end smallexample - -@noindent -The value returned is the fixed-point value @var{V} such that - -@smallexample -@var{V} = Arg * @var{S}'Small -@end smallexample - -@noindent -The effect is thus equivalent 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. This attribute is primarily intended -for use in implementation of the input-output functions for fixed-point -values. - -@cindex Discriminants, testing for -@findex Has_Discriminants -@item 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. - -@findex Img -@item 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 -Put_Line ("X = " & X'Img); -@end smallexample - -@noindent -has the same meaning as the more verbose: - -@smallexample -Put_Line ("X = " & @var{type}'Image (X)); -@end smallexample - -where @var{type} is the subtype of the object X@. - -@findex Integer_Value -@item Integer_Value -@noindent -For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a -function with the following specification: - -@smallexample -function @var{S}'Integer_Value (Arg : Universal_Fixed) - return @var{S}; -@end smallexample - -@noindent -The value returned is the integer value @var{V}, such that - -@smallexample -Arg = @var{V} * @var{type}'Small -@end smallexample - -@noindent -The effect is thus equivalent to first doing an unchecked convert from -the fixed-point type to its corresponding implementation type, and then -converting the result to the target integer type. This attribute is -primarily intended for use in implementation of the standard -input-output functions for fixed-point values. - -@cindex Ada 83 attributes -@findex Large -@item 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. - -@findex Machine_Size -@item 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. - -@cindex Ada 83 attributes -@findex Mantissa -@item 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. - -@cindex Interrupt priority, maximum -@findex Max_Interrupt_Priority -@item Max_Interrupt_Priority -@noindent -@code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only -permissible prefix), provides the value -@code{System.Max_Interrupt_Priority} and is intended primarily for -constructing this definition in package @code{System}. - -@cindex Priority, maximum -@findex Max_Priority -@item Max_Priority -@noindent -@code{Standard'Max_Priority} (@code{Standard} is the only permissible -prefix) provides the value @code{System.Max_Priority} and is intended -primarily for constructing this definition in package @code{System}. - -@cindex Alignment, maximum -@findex Maximum_Alignment -@item 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. This is useful when an external object is imported and its -alignment requirements are unknown. - -@cindex Return values, passing mechanism -@cindex Parameters, passing mechanism -@findex Mechanism_Code -@item 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 - -@cindex OpenVMS -Values from 3-10 are only relevant to Digital OpenVMS implementations. - -@cindex Zero address, passing -@findex Null_Parameter -@item 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. - -@cindex Size, used for objects -@findex Object_Size -@item 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 -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 -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. - -@cindex Parameters, when passed by reference -@findex Passed_By_Reference -@item 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. - -@findex Range_Length -@item 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. - -@cindex Ada 83 attributes -@findex Safe_Emax -@item 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. - -@cindex Ada 83 attributes -@findex Safe_Large -@item 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. - -@cindex Ada 83 attributes -@findex Safe_Large -@item 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. - -@cindex Ada 83 attributes -@findex Small -@item 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. - -@findex Storage_Unit -@item Storage_Unit -@noindent -@code{Standard'Storage_Unit} (@code{Standard} is the only permissible -prefix) provides the value @code{System.Storage_Unit} and is intended -primarily for constructing this definition in package @code{System}. - -@findex Tick -@item Tick -@noindent -@code{Standard'Tick} (@code{Standard} is the only permissible prefix) -provides the value of @code{System.Tick} and is intended primarily for -constructing this definition in package @code{System}. - -@findex To_Address -@item 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). - -@findex Type_Class -@item 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 - 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. - -@findex UET_Address -@item 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,a-except.adb} -for details on how this attribute is used in the implementation. - -@cindex Named numbers, representation of -@findex Universal_Literal_String -@item 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. - -@cindex @code{Access}, unrestricted -@findex Unrestricted_Access -@item 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). - -@cindex @code{Size}, VADS compatibility -@findex VADS_Size -@item 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. - -@cindex @code{Size}, setting for not-first subtype -@findex Value_Size -@item 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. - -@findex Wchar_T_Size -@item 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}. - -@findex Word_Size -@item Word_Size -@code{Standard'Word_Size} (@code{Standard} is the only permissible -prefix) provides the value @code{System.Word_Size} and is intended -primarily for constructing this definition in package @code{System}. -@end table -@node Implementation Advice -@chapter Implementation Advice -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. - -@table @strong -@cindex Error detection -@item 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 -@item 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 -@item 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 -@item 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 - -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. - -@item 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 -@item 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 -@item 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. -@item 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 -@item 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 -@item 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 -@item 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}, ...) 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 -@item 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**(-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. - -@item 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 -@item 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 -@item 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 -@item 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. GNAT does not support non-static expressions in representation -clauses unless they are constants declared before the entity. For -example: - -@smallexample -X : typ; -for X'Address use To_address (16#2000#); -@end smallexample - -@noindent -will be rejected, since the To_Address expression is non-static. Instead -write: - -@smallexample -X_Address : constant Address : = -To_Address ((16#2000#); -X : typ; -for X'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 -@item 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. - -@sp 1 -@cartouche -An implementation should support Address clauses for imported -subprograms. -@end cartouche -Followed. -@cindex @code{Address} clauses -@item 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 -@item 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 -@item 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. - -@item 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 -@item 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 -@item 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 -@item 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 -@item 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 -@item 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 -@item 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 -@item 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 -@item 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 -@item 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 de-allocation 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 -@item 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 -@item 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. In particular, the interpretation chosen is that of AI-195, -which specifies that the size to be used is that of the first subtype. - -@item A.1(52): Implementation Advice -@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 -@item 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 -@item 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 -@item 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 -@item 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. - -@findex Export -@item 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 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 -@item 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 -@item 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 -@item 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 ``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 ``BY CONTENT'' data item of -the corresponding COBOL type. -@end cartouche -Followed. - -@sp 1 -@cartouche -Any other Ada parameter is passed as a ``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 -@item 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 -@item 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. - -@item 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 -@item 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 -@item 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 -@item 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 -@item 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. - -@item 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 -@item 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 -@item 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 -@item 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 queueing policies exist. - -@cindex Preemptive abort -@item 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 -@item 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{Ravenscar} and pragma -@code{Restricted_Run_Time} for more details. - -@cindex Time, monotonic -@item 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 -@item 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. For information on GLADE, contact Ada Core Technologies. - -@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@. For information on GLADE, contact Ada Core Technologies. - -@cindex COBOL support -@item 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 -@item 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 -@item 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 -@item 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 -@item 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 -@item 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 -@item 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. - -@end table -@node Implementation Defined Characteristics -@chapter Implementation Defined Characteristics -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**(-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 @file{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 -z and -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 User 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 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. - -@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} contains the expanded name of the exception -in upper case, and no other information. - -@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 -and 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. - -@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 Boolean_Entry_Barriers -@findex Boolean_Entry_Barriers -This restriction ensures at compile time that barriers in entry declarations -for protected types are restricted to 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 Ravenscar). - -@item Max_Entry_Queue_Depth => Expr -@findex Max_Entry_Queue_Depth -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_Dynamic_Interrupts -@findex No_Dynamic_Interrupts -This restriction ensures at compile time that there is no attempt to -dynamically associate interrupts. Only static association is allowed. - -@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. - -@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. The details and use of this restriction are described in -more detail in the High Integrity product documentation. - -@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. The details and use of this restriction are described in -more detail in the GNORT Reference Manual. - -@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_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 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 time that there are no implicit or -explicit dependencies on the package @code{Ada.Streams}. - -@item No_Task_Attributes -@findex No_Task_Attributes -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_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} -appear, and that no wide character literals -appear in the program (that is literals representing characters not in -type @code{Character}. - -@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 Preelaborate. There are cases in which pragma 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 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). Note that this restriction -is enforced on a unit by unit basis, it need not be obeyed consistently -throughout a partition. - -@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. - -@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 Asm -Assembly language -@item Assembler -Assembly language -@item C -C -@item C_Pass_By_Copy -Treated like C, except for record types -@item COBOL -COBOL -@item CPP -C++ -@item Default -Treated the same as C -@item DLL -DLL (used for Windows implementations only) is handled like the Stdcall -convention. This convention is used to access variables and functions -(with Stdcall convention) in a DLL@. -@item Win32 -Win32 (used for Windows implementations only) is handled like the Stdcall -convention. This convention is used to access variables and functions -(with Stdcall convention) in a DLL@. -@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 clean the stack before exit. -@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 -pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef"); -@end smallexample - -@noindent -causes two separate arguments "-labc" and "-ldef" to be passed to the -linker with a guarantee that the order is preserved (no such guarantee -exists for the use of separate Linker_Options pragmas). - -In addition, GNAT allow multiple arguments to @code{Linker_Options} -with exactly the same meaning, so the above pragma could also be -written as: - -@smallexample -pragma Linker_Options ("-labc", "-ldef"); -@end smallexample - -@noindent -The above multiple argument form is a GNAT extension. - -@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 - -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 defied 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 queueing 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. - -@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 - -GNAT allows a user application program to write the declaration: - -@smallexample - 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 predefined operators can be used 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. You can use an intrinsic -operator declaration as in the following example: - -@smallexample - 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 Int1 and Int2. - -@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 - 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 Primitive Types -For primitive types, the alignment is the maximum of the actual size of -objects of the type, and the maximum alignment supported by the target. -For example, for type 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 Long_Float will be maximally -aligned. - -@item 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 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 Pack is -used and all fields are packable (see separate section on pragma Pack), -then the resulting alignment is 1. - -@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 System'Maximum_Alignment). The only case in which -it is permissible to specify a smaller alignment than the default value -is in the case of a record for which a record representation clause is -given. 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 - 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 to a smaller value. - -@node Size Clauses -@section Size Clauses -@cindex Size Clause - -@noindent -The default size of types is as specified in the reference manual. For -objects, GNAT will generally increase the type size so that the object -size is a multiple of storage units, and also a multiple of the -alignment. For example - -@smallexample - type Smallint is range 1 .. 6; - - type Rec is record - y1 : integer; - y2 : boolean; - end record; -@end smallexample - -@noindent -In this example, @code{Smallint} -has a size of 3, as specified by the RM rules, -but objects of this type will have a size of 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, 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. The reason for this decision, which is -in accordance with the specific note in RM 13.3(43): - -@smallexample -A Size clause should be supported for an object if the specified -Size is at least as large as its subtype's Size, and corresponds -to a size in storage elements that is a multiple of the object's -Alignment (if the Alignment is nonzero). -@end smallexample - -@noindent -An explicit size clause may be used to override the default size by -increasing it. For example, if we have: - -@smallexample - type My_Boolean is new Boolean; - for My_Boolean'Size use 32; -@end smallexample - -@noindent -then objects 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**32-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. If the default size of 20K bytes is insufficient, -then you need to 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 - pragma Storage_Size (Default_Stack_Size); -@end smallexample - -@noindent -Then Default_Stack_Size can be defined in a global package, and modified -as required. Any tasks requiring different task stack sizes from the -default can have an appropriate alternative reference in the pragma. - -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 - 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); - - -- ... - - begin - -- ... - 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 -An issue arises in the case of variant record objects of whether Size gives -information about a particular variant, or the maximum size required -for any variant. Consider the following program - -@smallexample -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 -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, @code{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 - 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, the @code{Size} of a discrete type is the minimum number of bits -required to hold values of the type. 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 - type Rec is record; - A : Natural; - B : Natural; - end record; - - for Rec use record - for A use at 0 range 0 .. Natural'Size - 1; - for B use 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 -surprising 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 -dependent 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 fixed-point and -discrete types are as follows: - -@itemize @bullet -@item -The @code{Object_Size} for base subtypes reflect the natural hardware -size in bits (run the utility gnatpsta 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 number of bits required to store a value -of the type. This size can be referred to using the @code{Value_Size} -attribute. 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 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; 12 12 - -subtype x3 is x2 range 0 .. 3; 12 2 - -subtype x4 is x2'base range 0 .. 10; 8 4 - -subtype x5 is x2 range 0 .. dynamic; 12 (7) - -subtype x6 is x2'base range 0 .. dynamic; 8 (7) - -@end smallexample - -@noindent -Note: the entries marked (7) 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 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 types other than discrete and fixed-point 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 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-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 -type r is array (1 .. 8) of Natural; -for r'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. - -@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 - 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 - 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: - -@smallexample -2 A bit ordering is a method of interpreting the meaning of -the storage place attributes. -@end smallexample - -@noindent -To understand the precise definition of storage place attributes in -this context, we visit section 13.5.1 of the manual: - -@smallexample -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 smallexample - -@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: - -@smallexample -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 smallexample - -@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 remaing 7 bits are called V1, V2 .. V7, where V7 is the right most -(least significant bit). - -On a big-endian machine, we can write the following representation clause - -@smallexample - 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 - 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 - -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 @code{GNAT}. -This means that we can simply use the -first record clause, together with the declaration - -@smallexample - 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-endial 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 - 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 - 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 -nromalizing 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 - Master_Byte_First constant Boolean := ...; - - 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 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 fixed-point 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- 63, then the effect of the pragma Pack is exactly as though a -component size were specified giving the component subtype size. -For example if we have: - -@smallexample - 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 Pack that it guesses -might not be what is intended. You can easily remove this warning by -using an explicit 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. - -@node Pragma Pack for Records -@section Pragma Pack for Records -@cindex Pragma Pack (for records) - -@noindent -Pragma 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 package components and non-packable -components. Components of the following types are considered packable: - -@itemize @bullet -@item -All scalar types are packable. - -@item -All fixed-point types are represented internally as integers, and -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 - 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 -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 - 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 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. - -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. - -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. - -@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 - 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 - 0 .. System.Max_Binary_Modulus; -@end smallexample - -@noindent -A "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 - 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): - -@smallexample - 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 smallexample - -@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): - -@smallexample - 22.a Reason: This is to avoid the following sort - of thing: - - 22.b X : Integer := F(...); - Y : Address := G(...); - 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(...); - X : Integer := F(...); - 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 smallexample - -@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. - -@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 - Anchor : Some_Initialized_Type; - Overlay : Some_Initialized_Type; - for Overlay'Address use Anchor'Address; -@end smallexample - -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 - 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 -To_Address. - -@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 so 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 - 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 - -@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 - 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 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 - 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 -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 pack is used on a -record, then exactly where are the resulting fields placed? The section -on pragma 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 -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 Pack on these arrays, and the record -representation clause for type x2 shows how pragma 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 argc and 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 an -trigonometric functions) for an arbitrary complex type. - -The following predefined instantiations of this package exist - -@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. - -@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 package 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.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}. -@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:: -* 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.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 - -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 C library routines that support streams. This -facilitates shared use of these streams by mixed language programs. - -@node FORM Strings -@section FORM Strings - -@noindent -The format of a FORM string in GNAT is: - -@smallexample -"keyword=value,keyword=value,...,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 - -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} - -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 - package IO is new Sequential_IO (String); - F : IO.File_Type; - S : String (1..4); - ... - IO.Create (F) - IO.Write (F, "hello!") - IO.Reset (F, Mode=>In_File); - IO.Read (F, S); - Put_Line (S); - -@end smallexample - -On some Ada implementations, this will print @samp{hell}, but the program is -clearly incorrect, since there is only one element in the file, and that -element is the string @samp{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 - -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 - -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 - -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 - -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 - -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 @code{EOT} key, -then end of file -is signalled 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 and can be successfully -opened (without actually performing the open operation). - -@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 @code{a-swuwti.ads/adb} provides similar extended @code{Wide_Text_IO} -functionality for unbounded 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 - -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 - -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 - -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 illegal 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 - -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 - -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 -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 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 - -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 Table 6.1 - -@sp 2 -@center Table 6-1 @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 - -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 -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 - 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.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 - -In each of these five 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 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.Wide_Latin_1 (a-cwila1.ads):: -* Ada.Command_Line.Remove (a-colire.ads):: -* Ada.Direct_IO.C_Streams (a-diocst.ads):: -* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.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.Text_IO.C_Streams (a-tiocst.ads):: -* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads):: -* GNAT.AWK (g-awk.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.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_Tables (g-dyntab.ads):: -* GNAT.Exception_Traces (g-exctra.ads):: -* GNAT.Expect (g-expect.ads):: -* GNAT.Float_Control (g-flocon.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.Most_Recent_Exception (g-moreex.ads):: -* GNAT.OS_Lib (g-os_lib.ads):: -* GNAT.Regexp (g-regexp.ads):: -* GNAT.Registry (g-regist.ads):: -* GNAT.Regpat (g-regpat.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.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):: -* 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):: -* System.Address_Image (s-addima.ads):: -* System.Assertions (s-assert.ads):: -* System.Partition_Interface (s-parint.ads):: -* System.Task_Info (s-tasinf.ads):: -* System.Wch_Cnv (s-wchcnv.ads):: -* System.Wch_Con (s-wchcon.ads):: -@end menu - -@node Ada.Characters.Wide_Latin_1 (a-cwila1.ads) -@section Ada.Characters.Wide_Latin_1 (a-cwila1.ads) -@cindex Ada.Characters.Wide_Latin_1 (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.Command_Line.Remove (a-colire.ads) -@section Ada.Command_Line.Remove (a-colire.ads) -@cindex Ada.Command_Line.Remove (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.Direct_IO.C_Streams (a-diocst.ads) -@section Ada.Direct_IO.C_Streams (a-diocst.ads) -@cindex Ada.Direct_IO.C_Streams (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 Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) -@cindex Ada.Exceptions.Is_Null_Occurrence (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.Sequential_IO.C_Streams (a-siocst.ads) -@section Ada.Sequential_IO.C_Streams (a-siocst.ads) -@cindex Ada.Sequential_IO.C_Streams (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 Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) -@cindex Ada.Streams.Stream_IO.C_Streams (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 Ada.Strings.Unbounded.Text_IO (a-suteio.ads) -@cindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) -@cindex Unbounded_String, IO support -@cindex 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 Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) -@cindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) -@cindex Unbounded_Wide_String, IO support -@cindex 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.Text_IO.C_Streams (a-tiocst.ads) -@section Ada.Text_IO.C_Streams (a-tiocst.ads) -@cindex Ada.Text_IO.C_Streams (a-tiocst.ads) -@cindex C Streams, Interfacing with 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 Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) -@cindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) -@cindex C Streams, Interfacing with 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 GNAT.AWK (g-awk.ads) -@section GNAT.AWK (g-awk.ads) -@cindex GNAT.AWK (g-awk.ads) -@cindex Parsing - -@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.Bubble_Sort_A (g-busora.ads) -@section GNAT.Bubble_Sort_A (g-busora.ads) -@cindex GNAT.Bubble_Sort_A (g-busora.ads) -@cindex Sorting - -@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. - -@node GNAT.Bubble_Sort_G (g-busorg.ads) -@section GNAT.Bubble_Sort_G (g-busorg.ads) -@cindex GNAT.Bubble_Sort_G (g-busorg.ads) -@cindex Sorting - -@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 GNAT.Calendar (g-calend.ads) -@cindex GNAT.Calendar (g-calend.ads) -@cindex 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 GNAT.Calendar.Time_IO (g-catiio.ads) -@cindex Calendar -@cindex Time -@cindex GNAT.Calendar.Time_IO (g-catiio.ads) - -@node GNAT.CRC32 (g-crc32.ads) -@section GNAT.CRC32 (g-crc32.ads) -@cindex GNAT.CRC32 (g-crc32.ads) -@cindex CRC32 - -@noindent -This package implements the CRC-32 algorithm. For a full description -of this algorithm you should have a look at: -"Computation of Cyclic Redundancy Checks via Table Look-Up", 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 GNAT.Case_Util (g-casuti.ads) -@cindex GNAT.Case_Util (g-casuti.ads) -@cindex Casing utilities - -@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 GNAT.CGI (g-cgi.ads) -@cindex GNAT.CGI (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 parse 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 GNAT.CGI.Cookie (g-cgicoo.ads) -@cindex GNAT.CGI.Cookie (g-cgicoo.ads) -@cindex CGI (Common Gateway Interface) Cookie support - -@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 GNAT.CGI.Debug (g-cgideb.ads) -@cindex GNAT.CGI.Debug (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 GNAT.Command_Line (g-comlin.ads) -@cindex GNAT.Command_Line (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.Current_Exception (g-curexc.ads) -@section GNAT.Current_Exception (g-curexc.ads) -@cindex GNAT.Current_Exception (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 mimicking typical facilities for -obtaining information about exceptions provided by Ada 83 compilers. - -@node GNAT.Debug_Pools (g-debpoo.ads) -@section GNAT.Debug_Pools (g-debpoo.ads) -@cindex GNAT.Debug_Pools (g-debpoo.ads) -@cindex Debugging - -@noindent -Provide a debugging storage pools that helps tracking memory corruption -problems. See section "Finding memory problems with GNAT Debug Pool" in -the GNAT User's guide. - -@node GNAT.Debug_Utilities (g-debuti.ads) -@section GNAT.Debug_Utilities (g-debuti.ads) -@cindex GNAT.Debug_Utilities (g-debuti.ads) -@cindex Debugging - -@noindent -Provides a few useful utilities for debugging purposes, including conversion -to and from string images of address values. - -@node GNAT.Directory_Operations (g-dirope.ads) -@section GNAT.Directory_Operations (g-dirope.ads) -@cindex 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_Tables (g-dyntab.ads) -@section GNAT.Dynamic_Tables (g-dyntab.ads) -@cindex GNAT.Dynamic_Tables (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 GNAT.Table, except -that this package declares a type that can be used to define dynamic -instances of the table, while an instantiation of GNAT.Table creates a -single instance of the table type. - -@node GNAT.Exception_Traces (g-exctra.ads) -@section GNAT.Exception_Traces (g-exctra.ads) -@cindex GNAT.Exception_Traces (g-exctra.ads) -@cindex Exception traces -@cindex Debugging - -@noindent -Provides an interface allowing to control automatic output upon exception -occurrences. - -@node GNAT.Expect (g-expect.ads) -@section GNAT.Expect (g-expect.ads) -@cindex GNAT.Expect (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 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 GNAT.Float_Control (g-flocon.ads) -@cindex GNAT.Float_Control (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_A (g-hesora.ads) -@section GNAT.Heap_Sort_A (g-hesora.ads) -@cindex GNAT.Heap_Sort_A (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. - -@node GNAT.Heap_Sort_G (g-hesorg.ads) -@section GNAT.Heap_Sort_G (g-hesorg.ads) -@cindex GNAT.Heap_Sort_G (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 GNAT.HTable (g-htable.ads) -@cindex GNAT.HTable (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 GNAT.IO (g-io.ads) -@cindex GNAT.IO (g-io.ads) -@cindex Simple I/O -@cindex Input/Output facilities - -@noindent -A simple preealborable 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 GNAT.IO_Aux (g-io_aux.ads) -@cindex GNAT.IO_Aux (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 GNAT.Lock_Files (g-locfil.ads) -@cindex GNAT.Lock_Files (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.Most_Recent_Exception (g-moreex.ads) -@section GNAT.Most_Recent_Exception (g-moreex.ads) -@cindex GNAT.Most_Recent_Exception (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 GNAT.OS_Lib (g-os_lib.ads) -@cindex GNAT.OS_Lib (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.Regexp (g-regexp.ads) -@section GNAT.Regexp (g-regexp.ads) -@cindex GNAT.Regexp (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 GNAT.Registry (g-regist.ads) -@cindex GNAT.Registry (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 GNAT.Regpat (g-regpat.ads) -@cindex GNAT.Regpat (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.Sockets (g-socket.ads) -@section GNAT.Sockets (g-socket.ads) -@cindex GNAT.Sockets (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 GNAT.Sockets.Thin. -Currently GNAT.Sockets 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.Source_Info (g-souinf.ads) -@section GNAT.Source_Info (g-souinf.ads) -@cindex GNAT.Source_Info (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 GNAT.Spell_Checker (g-speche.ads) -@cindex GNAT.Spell_Checker (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 GNAT.Spitbol.Patterns (g-spipat.ads) -@cindex GNAT.Spitbol.Patterns (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 GNAT.Spitbol (g-spitbo.ads) -@cindex GNAT.Spitbol (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 GNAT.Spitbol.Table_Boolean (g-sptabo.ads) -@cindex GNAT.Spitbol.Table_Boolean (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 GNAT.Spitbol.Table_Integer (g-sptain.ads) -@cindex GNAT.Spitbol.Table_Integer (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 GNAT.Spitbol.Table_VString (g-sptavs.ads) -@cindex GNAT.Spitbol.Table_VString (g-sptavs.ads) -@cindex String maps -@cindex Maps -@cindex SPITBOL Tables - -@noindent -A library level of instantiation of GNAT.Spitbol.Patterns.Table for -a variable length string type, giving an implementation of general -maps from strings to strings. - -@node GNAT.Table (g-table.ads) -@section GNAT.Table (g-table.ads) -@cindex GNAT.Table (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 GNAT.Dynamic_Tables, -except that this package declares a single instance of the table type, -while an instantiation of 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 GNAT.Task_Lock (g-tasloc.ads) -@cindex GNAT.Task_Lock (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 GNAT.Threads (g-thread.ads) -@cindex GNAT.Threads (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 runt-time is provided. - -@node GNAT.Traceback (g-traceb.ads) -@section GNAT.Traceback (g-traceb.ads) -@cindex GNAT.Traceback (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 GNAT.Traceback.Symbolic (g-trasym.ads) -@cindex GNAT.Traceback.Symbolic (g-trasym.ads) -@cindex Trace back facilities - -@noindent -Provides symbolic traceback information that includes the subprogram -name and line number information. - -@node Interfaces.C.Extensions (i-cexten.ads) -@section Interfaces.C.Extensions (i-cexten.ads) -@cindex Interfaces.C.Extensions (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 Interfaces.C.Streams (i-cstrea.ads) -@cindex Interfaces.C.Streams (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 Interfaces.CPP (i-cpp.ads) -@cindex Interfaces.CPP (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 Interfaces.Os2lib (i-os2lib.ads) -@cindex Interfaces.Os2lib (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{} files. - -@node Interfaces.Os2lib.Errors (i-os2err.ads) -@section Interfaces.Os2lib.Errors (i-os2err.ads) -@cindex Interfaces.Os2lib.Errors (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 Interfaces.Os2lib.Synchronization (i-os2syn.ads) -@cindex Interfaces.Os2lib.Synchronization (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 Interfaces.Os2lib.Threads (i-os2thr.ads) -@cindex Interfaces.Os2lib.Threads (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 Interfaces.Packed_Decimal (i-pacdec.ads) -@cindex Interfaces.Packed_Decimal (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 Interfaces.VxWorks (i-vxwork.ads) -@cindex Interfaces.VxWorks (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 System.Address_Image (s-addima.ads) -@section System.Address_Image (s-addima.ads) -@cindex System.Address_Image (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 System.Assertions (s-assert.ads) -@cindex System.Assertions (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.Partition_Interface (s-parint.ads) -@section System.Partition_Interface (s-parint.ads) -@cindex System.Partition_Interface (s-parint.ads) -@cindex Partition intefacing 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.Task_Info (s-tasinf.ads) -@section System.Task_Info (s-tasinf.ads) -@cindex System.Task_Info (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 System.Wch_Cnv (s-wchcnv.ads) -@cindex System.Wch_Cnv (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 characters and a representation as a value of type -@code{Standard.String}, using a specified wide character -encoding method. Uses definitions in -package @code{System.Wch_Con} - -@node System.Wch_Con (s-wchcon.ads) -@section System.Wch_Con (s-wchcon.ads) -@cindex System.Wch_Con (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: - -@enumerate -@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 enumerate - -@noindent -Pragma @code{Convention C} maybe 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 - -@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 signed char, short, 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. Ada Core -Technologies does not currently supply a suitable binding generator tool. - -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 Ada in a pragma Import or -pragma 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 Machine Code Insertions -@chapter 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 - -The two features are similar, and both 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 and Porting GNU CC} by Richard -Stallman. 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 GNU CC 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 -Asm ("fsinx %1 %0", - My_Float'Asm_Output ("=f", result), - My_Float'Asm_Input ("f", angle)); -@end smallexample - -The first argument to @code{Asm} is the assembler template, and is -identical to what is used in GNU CC@. 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 -Asm_Insn'(Asm (@dots{})); -Asm_Insn'(Asm_Volatile (@dots{})); -@end smallexample - -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} (of course 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 ::= - 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 ::= - 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 - -@node GNAT Implementation of Tasking -@chapter GNAT Implementation of Tasking -@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 -@section Mapping Ada Tasks onto the Underlying Kernel Threads - -GNAT run-time system comprises two layers: - -@itemize @bullet -@item GNARL (GNAT Run-time Layer) -@item GNULL (GNAT Low-level Library) -@end itemize - -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 - - 1 Ada task = 1 VxWorks task - -In addition Ada task priorities map onto the underlying thread priorities. -Mapping Ada tasks onto the underlying kernel threads has several advantages: - -@enumerate - -@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 multi-processor systems Ada Tasks can execute in parallel. -@end enumerate - -@node Ensuring Compliance with the Real-Time Annex -@section Ensuring Compliance with the Real-Time Annex - -The reader will be quick to notice that while 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 Annex D requires that for the FIFO_Within_Priorities -scheduling policy we have: - -@smallexample -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 smallexample - -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 Code generation for array aggregates -@chapter Code generation for array aggregates - -@menu -* Static constant aggregates with static bounds:: -* Constant aggregates with an unconstrained nominal types:: -* Aggregates with static bounds:: -* Aggregates with non-static bounds:: -* Aggregates in assignments statements:: -@end menu - -Aggregate 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, the user 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. The user will 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 -@section Static constant aggregates with static bounds - - For the declarations: -@smallexample - 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 - -GNAT generates no executable code: the constant ar0 is placed in static memory. -The same is true for constant aggregates with named associations: - -@smallexample - Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1=> 1); - Cr3 : constant One_Dim := (others => 7777); -@end smallexample - - The same is true for multidimensional constant arrays such as: - -@smallexample - 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 - -The same is true for arrays of one-dimensional arrays: the following are -static: - -@smallexample -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 - -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 -Zero1: constant two_dim := (1..3 => (1..3 => 0)); -Zero2: constant two_dim := (others => (others => 0)); -@end smallexample - -@node Constant aggregates with an unconstrained nominal types -@section Constant aggregates with an unconstrained nominal types - -In such cases the aggregate itself establishes the subtype, so that associations -with "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 - type One_Unc is array (natural range <>) of integer; - Cr_Unc : constant One_Unc := (12,24,36); -@end smallexample - -@node Aggregates with static bounds -@section Aggregates with static bounds - -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 - Cr_Var1 : One_Dim := (2, 5, 7, 11); - Cr_Var2 : One_Dim := (others > -1); -@end smallexample - -generate the equivalent of - -@smallexample - 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 -@section Aggregates with non-static bounds - -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 assignments statements -@section Aggregates in assignments statements - -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 -@end smallexample - A := (A(2), A(1)); - -This cannot be converted into: - -@smallexample - A(1) := A(2); - A(2) := A(1); -@end smallexample - -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: - -@enumerate -@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 enumerate - -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 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 @code{GNAT} compiler. In addition, -a complete compatible PCS is available as part of the @code{GLADE} system, -a separate product available from Ada Core Technologies. 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 Compatibility Guide -@chapter Compatibility Guide - -@noindent -This chapter contains sections that describe compatibility issues between -GNAT and other Ada 83 and Ada 95 compilation systems, to aid in porting -applications developed in other Ada environments. - -@menu -* Compatibility with Ada 83:: -* Compatibility with DEC Ada 83:: -* Compatibility with Other Ada 95 Systems:: -* Representation Clauses:: -@end menu - -@node Compatibility with Ada 83 -@section Compatibility with Ada 83 - -@noindent -Ada 95 is designed to be highly upwards compatible with Ada 83. In -particular, the design intention is that the difficulties associated -with moving from Ada 83 to Ada 95 should be no greater than those -that occur when moving from one Ada 83 system to another. - -However, there are a number of points at which there are minor -incompatibilities. The Ada 95 Annotated Reference Manual contains -full details of these issues, -and should be consulted for a complete treatment. -In practice the -following are the most likely issues to be encountered. - -@table @asis -@item Character range -The range of Standard.Character is now the full 256 characters of Latin-1, -whereas in most Ada 83 implementations it was restricted to 128 characters. -This may show up as compile time or runtime errors. The desirable fix is to -adapt the program to accommodate the full character set, but in some cases -it may be convenient to define a subtype or derived type of Character that -covers only the restricted range. - -@item New reserved words -The identifiers @code{abstract}, @code{aliased}, @code{protected}, -@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. -Existing Ada 83 code using any of these identifiers must be edited to -use some alternative name. - -@item Freezing rules -The rules in Ada 95 are slightly different with regard to the point at -which entities are frozen, and representation pragmas and clauses are -not permitted past the freeze point. This shows up most typically in -the form of an error message complaining that a representation item -appears too late, and the appropriate corrective action is to move -the item nearer to the declaration of the entity to which it refers. - -A particular case is that representation pragmas (including the -extended DEC Ada 83 compatibility pragmas such as Export_Procedure), cannot -be applied to a subprogram body. If necessary, a separate subprogram -declaration must be introduced to which the pragma can be applied. - -@item Optional bodies for library packages -In Ada 83, a package that did not require a package body was nevertheless -allowed to have one. This lead to certain surprises in compiling large -systems (situations in which the body could be unexpectedly ignored). In -Ada 95, if a package does not require a body then it is not permitted to -have a body. To fix this problem, simply remove a redundant body if it -is empty, or, if it is non-empty, introduce a dummy declaration into the -spec that makes the body required. One approach is to add a private part -to the package declaration (if necessary), and define a parameterless -procedure called Requires_Body, which must then be given a dummy -procedure body in the package body, which then becomes required. - -@item Numeric_Error is now the same as Constraint_Error -In Ada 95, the exception Numeric_Error is a renaming of Constraint_Error. -This means that it is illegal to have separate exception handlers for -the two exceptions. The fix is simply to remove the handler for the -Numeric_Error case (since even in Ada 83, a compiler was free to raise -Constraint_Error in place of Numeric_Error in all cases). - -@item Indefinite subtypes in generics -In Ada 83, it was permissible to pass an indefinite type (e.g.@: String) as -the actual for a generic formal private type, but then the instantiation -would be illegal if there were any instances of declarations of variables -of this type in the generic body. In Ada 95, to avoid this clear violation -of the contract model, the generic declaration clearly indicates whether -or not such instantiations are permitted. If a generic formal parameter -has explicit unknown discriminants, indicated by using (<>) after the -type name, then it can be instantiated with indefinite types, but no -variables can be declared of this type. Any attempt to declare a variable -will result in an illegality at the time the generic is declared. If the -(<>) notation is not used, then it is illegal to instantiate the generic -with an indefinite type. This will show up as a compile time error, and -the fix is usually simply to add the (<>) to the generic declaration. -@end table - -All implementations of GNAT provide a switch that causes GNAT to operate -in Ada 83 mode. In this mode, some but not all compatibility problems -of the type described above are handled automatically. For example, the -new Ada 95 protected keywords are not recognized in this mode. However, -in practice, it is usually advisable to make the necessary modifications -to the program to remove the need for using this switch. - -@node Compatibility with Other Ada 95 Systems -@section Compatibility with Other Ada 95 Systems - -@noindent -Providing that programs avoid the use of implementation dependent and -implementation defined features of Ada 95, as documented in the Ada 95 -reference manual, there should be a high degree of portability between -GNAT and other Ada 95 systems. The following are specific items which -have proved troublesome in moving GNAT programs to other Ada 95 -compilers, but do not affect porting code to GNAT@. - -@table @asis -@item Ada 83 Pragmas and Attributes -Ada 95 compilers are allowed, but not required, to implement the missing -Ada 83 pragmas and attributes that are no longer defined in Ada 95. -GNAT implements all such pragmas and attributes, eliminating this as -a compatibility concern, but some other Ada 95 compilers reject these -pragmas and attributes. - -@item Special-needs Annexes -GNAT implements the full set of special needs annexes. At the -current time, it is the only Ada 95 compiler to do so. This means that -programs making use of these features may not be portable to other Ada -95 compilation systems. - -@item Representation Clauses -Some other Ada 95 compilers implement only the minimal set of -representation clauses required by the Ada 95 reference manual. GNAT goes -far beyond this minimal set, as described in the next section. -@end table - -@node Representation Clauses -@section Representation Clauses - -@noindent -The Ada 83 reference manual was quite vague in describing both the minimal -required implementation of representation clauses, and also their precise -effects. The Ada 95 reference manual is much more explicit, but the minimal -set of capabilities required in Ada 95 is quite limited. - -GNAT implements the full required set of capabilities described in the -Ada 95 reference manual, but also goes much beyond this, and in particular -an effort has been made to be compatible with existing Ada 83 usage to the -greatest extent possible. - -A few cases exist in which Ada 83 compiler behavior is incompatible with -requirements in the Ada 95 reference manual. These are instances of -intentional or accidental dependence on specific implementation dependent -characteristics of these Ada 83 compilers. The following is a list of -the cases most likely to arise in existing legacy Ada 83 code. - -@table @asis -@item Implicit Packing -Some Ada 83 compilers allowed a Size specification to cause implicit -packing of an array or record. This could cause expensive implicit -conversions for change of representation in the presence of derived -types, and the Ada design intends to avoid this possibility. -Subsequent AI's were issued to make it clear that such implicit -change of representation in response to a Size clause is inadvisable, -and this recommendation is represented explicitly in the Ada 95 RM -as implementation advice that is followed by GNAT@. -The problem will show up as an error -message rejecting the size clause. The fix is simply to provide -the explicit pragma Pack, or for more fine tuned control, provide -a Component_Size clause. - -@item Meaning of Size Attribute -The Size attribute in Ada 95 for discrete types is defined as being the -minimal number of bits required to hold values of the type. For example, -on a 32-bit machine, the size of Natural will typically be 31 and not -32 (since no sign bit is required). Some Ada 83 compilers gave 31, and -some 32 in this situation. This problem will usually show up as a compile -time error, but not always. It is a good idea to check all uses of the -'Size attribute when porting Ada 83 code. The GNAT specific attribute -Object_Size can provide a useful way of duplicating the behavior of -some Ada 83 compiler systems. - -@item Size of Access Types -A common assumption in Ada 83 code is that an access type is in fact a pointer, -and that therefore it will be the same size as a System.Address value. This -assumption is true for GNAT in most cases with one exception. For the case of -a pointer to an unconstrained array type (where the bounds may vary from one -value of the access type to another), the default is to use a "fat pointer", -which is represented as two separate pointers, one to the bounds, and one to -the array. This representation has a number of advantages, including improved -efficiency. However, it may cause some difficulties in porting existing Ada 83 -code which makes the assumption that, for example, pointers fit in 32 bits on -a machine with 32-bit addressing. - -To get around this problem, GNAT also permits the use of "thin pointers" for -access types in this case (where the designated type is an unconstrained array -type). These thin pointers are indeed the same size as a System.Address value. -To specify a thin pointer, use a size clause for the type, for example: - -@smallexample -type X is access all String; -for X'Size use Standard'Address_Size; -@end smallexample - -@noindent -which will cause the type X to be represented using a single pointer. When using -this representation, the bounds are right behind the array. This representation -is slightly less efficient, and does not allow quite such flexibility in the -use of foreign pointers or in using the Unrestricted_Access attribute to create -pointers to non-aliased objects. But for any standard portable use of the access -type it will work in a functionally correct manner and allow porting of existing -code. Note that another way of forcing a thin pointer representation is to use -a component size clause for the element size in an array, or a record -representation clause for an access field in a record. -@end table - -@node Compatibility with DEC Ada 83 -@section Compatibility with DEC Ada 83 - -@noindent -The VMS version of GNAT fully implements all the pragmas and attributes -provided by DEC Ada 83, as well as providing the standard DEC Ada 83 -libraries, including Starlet. In addition, data layouts and parameter -passing conventions are highly compatible. This means that porting -existing DEC Ada 83 code to GNAT in VMS systems should be easier than -most other porting efforts. The following are some of the most -significant differences between GNAT and DEC Ada 83. - -@table @asis -@item Default floating-point representation -In GNAT, the default floating-point format is IEEE, whereas in DEC Ada 83, -it is VMS format. GNAT does implement the necessary pragmas -(Long_Float, Float_Representation) for changing this default. - -@item System -The package System in GNAT exactly corresponds to the definition in the -Ada 95 reference manual, which means that it excludes many of the -DEC Ada 83 extensions. However, a separate package Aux_DEC is provided -that contains the additional definitions, and a special pragma, -Extend_System allows this package to be treated transparently as an -extension of package System. - -@item To_Address -The definitions provided by Aux_DEC are exactly compatible with those -in the DEC Ada 83 version of System, with one exception. DEC Ada provides -the following declarations: - -@smallexample -TO_ADDRESS(INTEGER) -TO_ADDRESS(UNSIGNED_LONGWORD) -TO_ADDRESS(universal_integer) -@end smallexample - -@noindent -The version of TO_ADDRESS taking a universal integer argument is in fact -an extension to Ada 83 not strictly compatible with the reference manual. -In GNAT, we are constrained to be exactly compatible with the standard, -and this means we cannot provide this capability. In DEC Ada 83, the -point of this definition is to deal with a call like: - -@smallexample - TO_ADDRESS (16#12777#); -@end smallexample - -@noindent -Normally, according to the Ada 83 standard, one would expect this to be -ambiguous, since it matches both the INTEGER and UNSIGNED_LONGWORD forms -of TO_ADDRESS@. However, in DEC Ada 83, there is no ambiguity, since the -definition using universal_integer takes precedence. - -In GNAT, since the version with universal_integer cannot be supplied, it is -not possible to be 100% compatible. Since there are many programs using -numeric constants for the argument to TO_ADDRESS, the decision in GNAT was -to change the name of the function in the UNSIGNED_LONGWORD case, so the -declarations provided in the GNAT version of AUX_Dec are: - -@smallexample -function To_Address (X : Integer) return Address; -pragma Pure_Function (To_Address); - -function To_Address_Long (X : Unsigned_Longword) - return Address; -pragma Pure_Function (To_Address_Long); -@end smallexample - -@noindent -This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must -change the name to TO_ADDRESS_LONG@. - -@item Task_Id values -The Task_Id values assigned will be different in the two systems, and GNAT -does not provide a specified value for the Task_Id of the environment task, -which in GNAT is treated like any other declared task. -@end table - -For full details on these and other less significant compatibility issues, -see appendix E of the Digital publication entitled "DEC Ada, Technical -Overview and Comparison on DIGITAL Platforms". - -For GNAT running on other than VMS systems, all the DEC Ada 83 pragmas and -attributes are recognized, although only a subset of them can sensibly -be implemented. The description of pragmas in this reference manual -indicates whether or not they are applicable to non-VMS systems. - -@include fdl.texi -@c GNU Free Documentation License - -@node Index,,GNU Free Documentation License, Top -@unnumbered Index - -@printindex cp - -@contents - -@bye