@c o
@c G N A T _ RM o
@c o
-@c Copyright (C) 1995-2004 Free Software Foundation o
+@c Copyright (C) 1995-2006 Free Software Foundation o
@c o
@c o
@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@setfilename gnat_rm.info
+
+@set EDITION GNAT
@settitle GNAT Reference Manual
+
@setchapternewpage odd
@syncodeindex fn cp
@end copying
@titlepage
-
@title GNAT Reference Manual
@subtitle GNAT, The GNU Ada 95 Compiler
-@subtitle GCC version @value{version-GCC}
+@versionsubtitle
@author Ada Core Technologies, Inc.
-
@page
@vskip 0pt plus 1filll
GCC version @value{version-GCC}@*
@noindent
-Ada Core Technologies, Inc.
+AdaCore
@menu
* About This Guide::
* Specialized Needs Annexes::
* Implementation of Specific Ada Features::
* Project File Reference::
+* Obsolescent Features::
* GNU Free Documentation License::
* Index::
* Pragma Abort_Defer::
* Pragma Ada_83::
* Pragma Ada_95::
+* Pragma Ada_05::
+* Pragma Ada_2005::
* Pragma Annotate::
* Pragma Assert::
* Pragma Ast_Entry::
* Pragma C_Pass_By_Copy::
* Pragma Comment::
* Pragma Common_Object::
+* Pragma Compile_Time_Error::
* Pragma Compile_Time_Warning::
+* Pragma Complete_Representation::
* Pragma Complex_Representation::
* Pragma Component_Alignment::
* Pragma Convention_Identifier::
* Pragma CPP_Virtual::
* Pragma CPP_Vtable::
* Pragma Debug::
+* Pragma Debug_Policy::
+* Pragma Detect_Blocking::
* Pragma Elaboration_Checks::
* Pragma Eliminate::
* Pragma Export_Exception::
* Pragma License::
* Pragma Link_With::
* Pragma Linker_Alias::
+* Pragma Linker_Constructor::
+* Pragma Linker_Destructor::
* Pragma Linker_Section::
* Pragma Long_Float::
* Pragma Machine_Attribute::
* Pragma Main_Storage::
* Pragma No_Return::
+* Pragma No_Strict_Aliasing ::
* Pragma Normalize_Scalars::
* Pragma Obsolescent::
* Pragma Passive::
+* Pragma Persistent_BSS::
* Pragma Polling::
* Pragma Profile (Ravenscar)::
-* Pragma Propagate_Exceptions::
+* Pragma Profile (Restricted)::
* Pragma Psect_Object::
* Pragma Pure_Function::
-* Pragma Restricted_Run_Time::
* Pragma Restriction_Warnings::
* Pragma Source_File_Name::
* Pragma Source_File_Name_Project::
* Pragma Stream_Convert::
* Pragma Style_Checks::
* Pragma Subtitle::
+* Pragma Suppress::
* Pragma Suppress_All::
* Pragma Suppress_Exception_Locations::
* Pragma Suppress_Initialization::
* Pragma Unimplemented_Unit::
* Pragma Universal_Data::
* Pragma Unreferenced::
+* Pragma Unreferenced_Objects::
* Pragma Unreserve_All_Interrupts::
* Pragma Unsuppress::
* Pragma Use_VADS_Size::
* Pragma Volatile::
* Pragma Warnings::
* Pragma Weak_External::
+* Pragma Wide_Character_Encoding::
Implementation Defined Attributes
* Enum_Rep::
* Epsilon::
* Fixed_Value::
+* Has_Access_Values::
* Has_Discriminants::
* Img::
* Integer_Value::
* Safe_Large::
* Small::
* Storage_Unit::
+* Stub_Type::
* Target_Name::
* Tick::
* To_Address::
* Sequential_IO::
* Text_IO::
* Wide_Text_IO::
+* Wide_Wide_Text_IO::
* Stream_IO::
* Shared Files::
+* Filenames encoding::
* Open Modes::
* Operations on C Streams::
* Interfacing to C Streams::
* Ada.Characters.Latin_9 (a-chlat9.ads)::
* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
+* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
+* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
* Ada.Command_Line.Remove (a-colire.ads)::
* Ada.Command_Line.Environment (a-colien.ads)::
* Ada.Direct_IO.C_Streams (a-diocst.ads)::
* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
* Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
+* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
* Ada.Text_IO.C_Streams (a-tiocst.ads)::
* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
+* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
+* GNAT.Altivec (g-altive.ads)::
+* GNAT.Altivec.Conversions (g-altcon.ads)::
+* GNAT.Altivec.Vector_Operations (g-alveop.ads)::
+* GNAT.Altivec.Vector_Types (g-alvety.ads)::
+* GNAT.Altivec.Vector_Views (g-alvevi.ads)::
* GNAT.Array_Split (g-arrspl.ads)::
* GNAT.AWK (g-awk.ads)::
* GNAT.Bounded_Buffers (g-boubuf.ads)::
* GNAT.Bubble_Sort (g-bubsor.ads)::
* GNAT.Bubble_Sort_A (g-busora.ads)::
* GNAT.Bubble_Sort_G (g-busorg.ads)::
+* GNAT.Byte_Swapping (g-bytswa.ads)::
* GNAT.Calendar (g-calend.ads)::
* GNAT.Calendar.Time_IO (g-catiio.ads)::
* GNAT.Case_Util (g-casuti.ads)::
* GNAT.Memory_Dump (g-memdum.ads)::
* GNAT.Most_Recent_Exception (g-moreex.ads)::
* GNAT.OS_Lib (g-os_lib.ads)::
-* GNAT.Perfect_Hash.Generators (g-pehage.ads)::
+* GNAT.Perfect_Hash_Generators (g-pehage.ads)::
* GNAT.Regexp (g-regexp.ads)::
* GNAT.Registry (g-regist.ads)::
* GNAT.Regpat (g-regpat.ads)::
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
* GNAT.Semaphores (g-semaph.ads)::
+* GNAT.SHA1 (g-sha1.ads)::
* GNAT.Signals (g-signal.ads)::
* GNAT.Sockets (g-socket.ads)::
* GNAT.Source_Info (g-souinf.ads)::
* GNAT.Traceback (g-traceb.ads)::
* GNAT.Traceback.Symbolic (g-trasym.ads)::
* GNAT.Wide_String_Split (g-wistsp.ads)::
+* GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
* Interfaces.C.Extensions (i-cexten.ads)::
* Interfaces.C.Streams (i-cstrea.ads)::
* Interfaces.CPP (i-cpp.ads)::
* Wide_Text_IO Stream Pointer Positioning::
* Wide_Text_IO Reading and Writing Non-Regular Files::
+Wide_Wide_Text_IO
+
+* Wide_Wide_Text_IO Stream Pointer Positioning::
+* Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
+
Interfacing to Other Languages
* Interfacing to C::
* GNAT Implementation of Tasking::
* GNAT Implementation of Shared Passive Packages::
* Code Generation for Array Aggregates::
+* The Size of Discriminated Records with Default Discriminants::
+* Strict Conformance to the Ada 95 Reference Manual::
Project File Reference
+Obsolescent Features
+
GNU Free Documentation License
Index
@node About This Guide
@unnumbered About This Guide
+@ifclear PROEDITION
@noindent
This manual contains useful information in writing programs using the
GNAT compiler. It includes information on implementation dependent
characteristics of GNAT, including all the information required by Annex
M of the standard.
+@end ifclear
+
+@ifset PROEDITION
+@noindent
+This manual contains useful information in writing programs using the
+GNAT Pro compiler. It includes information on implementation dependent
+characteristics of GNAT Pro, including all the information required by Annex
+M of the standard.
+@end ifset
Ada 95 is designed to be highly portable.
In general, a program will have the same effect even when compiled by
isolate and clearly document any sections of your program that make use
of these features in a non-portable manner.
+@ifset PROEDITION
+For ease of exposition, ``GNAT Pro'' will be referred to simply as
+``GNAT'' in the remainder of this document.
+@end ifset
+
@menu
* What This Reference Manual Contains::
* Conventions::
@ref{Project File Reference}, presents the syntax and semantics
of project files.
+@item
+@ref{Obsolescent Features} documents implementation dependent features,
+including pragmas and attributes, which are considered obsolescent, since
+there are other preferred ways of achieving the same results. These
+obsolescent forms are retained for backwards compatibility.
+
@end itemize
@cindex Ada 95 ISO/ANSI Standard
* Pragma Abort_Defer::
* Pragma Ada_83::
* Pragma Ada_95::
+* Pragma Ada_05::
+* Pragma Ada_2005::
* Pragma Annotate::
* Pragma Assert::
* Pragma Ast_Entry::
* Pragma C_Pass_By_Copy::
* Pragma Comment::
* Pragma Common_Object::
+* Pragma Compile_Time_Error::
* Pragma Compile_Time_Warning::
+* Pragma Complete_Representation::
* Pragma Complex_Representation::
* Pragma Component_Alignment::
* Pragma Convention_Identifier::
* Pragma CPP_Virtual::
* Pragma CPP_Vtable::
* Pragma Debug::
+* Pragma Debug_Policy::
+* Pragma Detect_Blocking::
* Pragma Elaboration_Checks::
* Pragma Eliminate::
* Pragma Export_Exception::
* Pragma License::
* Pragma Link_With::
* Pragma Linker_Alias::
+* Pragma Linker_Constructor::
+* Pragma Linker_Destructor::
* Pragma Linker_Section::
* Pragma Long_Float::
* Pragma Machine_Attribute::
* Pragma Main_Storage::
* Pragma No_Return::
+* Pragma No_Strict_Aliasing::
* Pragma Normalize_Scalars::
* Pragma Obsolescent::
* Pragma Passive::
+* Pragma Persistent_BSS::
* Pragma Polling::
* Pragma Profile (Ravenscar)::
-* Pragma Propagate_Exceptions::
+* Pragma Profile (Restricted)::
* Pragma Psect_Object::
* Pragma Pure_Function::
-* Pragma Restricted_Run_Time::
* Pragma Restriction_Warnings::
* Pragma Source_File_Name::
* Pragma Source_File_Name_Project::
* Pragma Stream_Convert::
* Pragma Style_Checks::
* Pragma Subtitle::
+* Pragma Suppress::
* Pragma Suppress_All::
* Pragma Suppress_Exception_Locations::
* Pragma Suppress_Initialization::
* Pragma Unimplemented_Unit::
* Pragma Universal_Data::
* Pragma Unreferenced::
+* Pragma Unreferenced_Objects::
* Pragma Unreserve_All_Interrupts::
* Pragma Unsuppress::
* Pragma Use_VADS_Size::
* Pragma Volatile::
* Pragma Warnings::
* Pragma Weak_External::
+* Pragma Wide_Character_Encoding::
@end menu
@node Pragma Abort_Defer
itself uses Ada 95 features, but which is intended to be usable from
either Ada 83 or Ada 95 programs.
+@node Pragma Ada_05
+@unnumberedsec Pragma Ada_05
+@findex Ada_05
+@noindent
+Syntax:
+@smallexample @c ada
+pragma Ada_05;
+@end smallexample
+
+@noindent
+A configuration pragma that establishes Ada 2005 mode for the unit to which
+it applies, regardless of the mode set by the command line switches.
+This mode is set automatically for the @code{Ada} and @code{System}
+packages and their children, so you need not specify it in these
+contexts. This pragma is useful when writing a reusable component that
+itself uses Ada 2005 features, but which is intended to be usable from
+either Ada 83 or Ada 95 programs.
+
+@node Pragma Ada_2005
+@unnumberedsec Pragma Ada_2005
+@findex Ada_2005
+@noindent
+Syntax:
+@smallexample @c ada
+pragma Ada_2005;
+@end smallexample
+
+@noindent
+This configuration pragma is a synonym for pragma Ada_05 and has the
+same syntax and effect.
+
@node Pragma Annotate
@unnumberedsec Pragma Annotate
@findex Annotate
@smallexample @c ada
pragma Common_Object (
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Size =>] EXTERNAL_SYMBOL] );
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
+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
indicating that the necessary attribute for implementation of this
pragma is not available.
+@node Pragma Compile_Time_Error
+@unnumberedsec Pragma Compile_Time_Error
+@findex Compile_Time_Error
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Compile_Time_Error
+ (boolean_EXPRESSION, static_string_EXPRESSION);
+@end smallexample
+
+@noindent
+This pragma can be used to generate additional compile time
+error messages. It
+is particularly useful in generics, where errrs can be issued for
+specific problematic instantiations. The first parameter is a boolean
+expression. The pragma is effective only if the value of this expression
+is known at compile time, and has the value True. The set of expressions
+whose values are known at compile time includes all static boolean
+expressions, and also other values which the compiler can determine
+at compile time (e.g. the size of a record type set by an explicit
+size representation clause, or the value of a variable which was
+initialized to a constant and is known not to have been modified).
+If these conditions are met, an error message is generated using
+the value given as the second argument. This string value may contain
+embedded ASCII.LF characters to break the message into multiple lines.
+
@node Pragma Compile_Time_Warning
@unnumberedsec Pragma Compile_Time_Warning
@findex Compile_Time_Warning
the value given as the second argument. This string value may contain
embedded ASCII.LF characters to break the message into multiple lines.
+@node Pragma Complete_Representation
+@unnumberedsec Pragma Complete_Representation
+@findex Complete_Representation
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Complete_Representation;
+@end smallexample
+
+@noindent
+This pragma must appear immediately within a record representation
+clause. Typical placements are before the first component clause
+or after the last component clause. The effect is to give an error
+message if any component is missing a component clause. This pragma
+may be used to ensure that a record representation clause is
+complete, and that this invariant is maintained if fields are
+added to the record in the future.
+
@node Pragma Complex_Representation
@unnumberedsec Pragma Complex_Representation
@findex Complex_Representation
@smallexample @c ada
pragma Complex_Representation
- ([Entity =>] LOCAL_NAME);
+ ([Entity =>] local_NAME);
@end smallexample
@noindent
@smallexample @c ada
pragma Component_Alignment (
[Form =>] ALIGNMENT_CHOICE
- [, [Name =>] type_LOCAL_NAME]);
+ [, [Name =>] type_local_NAME]);
ALIGNMENT_CHOICE ::=
Component_Size
@end table
@noindent
-If the @code{Name} parameter is present, @var{type_local_name} must
+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
Syntax:
@smallexample @c ada
-pragma CPP_Class ([Entity =>] LOCAL_NAME);
+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.
+The argument denotes an entity in the current declarative region that is
+declared as a tagged 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.
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}).
+as subprograms as required). Initialization is allowed only by constructor
+functions (see pragma @code{CPP_Constructor}).
Pragma @code{CPP_Class} is intended primarily for automatic generation
using an automatic binding generator tool.
See @ref{Interfacing to C++} for related information.
+Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
+for backward compatibility but its functionality is available
+using pragma @code{Import} with @code{Convention} = @code{CPP}.
+
@node Pragma CPP_Constructor
@unnumberedsec Pragma CPP_Constructor
@cindex Interfacing with C++
Syntax:
@smallexample @c ada
-pragma CPP_Constructor ([Entity =>] LOCAL_NAME);
+pragma CPP_Constructor ([Entity =>] local_NAME
+ [, [External_Name =>] static_string_EXPRESSION ]
+ [, [Link_Name =>] static_string_EXPRESSION ]);
@end smallexample
@noindent
This pragma identifies an imported function (imported in the usual way
-with pragma @code{Import}) as corresponding to a C++
-constructor. The argument is a name that must have been
-previously mentioned in a pragma @code{Import}
-with @code{Convention} = @code{CPP}, and must be of one of the following
-forms:
+with pragma @code{Import}) as corresponding to a C++ constructor. If
+@code{External_Name} and @code{Link_Name} are not specified then the
+@code{Entity} argument is a name that must have been previously mentioned
+in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
+must be of one of the following forms:
@itemize @bullet
@item
@cindex Interfacing to C++
@findex CPP_Virtual
@noindent
-Syntax:
-
-@smallexample @c ada
-pragma CPP_Virtual
- [Entity =>] ENTITY,
- [, [Vtable_Ptr =>] vtable_ENTITY,]
- [, [Position =>] static_integer_EXPRESSION]);
-@end smallexample
-
-@noindent
-This pragma serves the same function as pragma @code{Import} in that
-case of a virtual function imported from C++. The @var{Entity} argument
-must be a
-primitive subprogram of a tagged type to which pragma @code{CPP_Class}
-applies. The @var{Vtable_Ptr} argument specifies
-the Vtable_Ptr component which contains the
-entry for this virtual function. The @var{Position} argument
-is the sequential number
-counting virtual functions for this Vtable starting at 1.
-
-The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if
-there is one Vtable_Ptr present (single inheritance case) and all
-virtual functions are imported. In that case the compiler can deduce both
-these values.
+This pragma is now obsolete has has no effect because GNAT generates
+the same object layout than the G++ compiler.
-No @code{External_Name} or @code{Link_Name} arguments are required for a
-virtual function, since it is always accessed indirectly via the
-appropriate Vtable entry.
-
-Pragma @code{CPP_Virtual} is intended primarily for automatic generation
-using an automatic binding generator tool.
See @ref{Interfacing to C++} for related information.
@node Pragma CPP_Vtable
@cindex Interfacing with C++
@findex CPP_Vtable
@noindent
-Syntax:
-
-@smallexample @c ada
-pragma CPP_Vtable (
- [Entity =>] ENTITY,
- [Vtable_Ptr =>] vtable_ENTITY,
- [Entry_Count =>] static_integer_EXPRESSION);
-@end smallexample
-
-@noindent
-Given a record to which the pragma @code{CPP_Class} applies,
-this pragma can be specified for each component of type
-@code{CPP.Interfaces.Vtable_Ptr}.
-@var{Entity} is the tagged type, @var{Vtable_Ptr}
-is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is
-the number of virtual functions on the C++ side. Not all of these
-functions need to be imported on the Ada side.
+This pragma is now obsolete has has no effect because GNAT generates
+the same object layout than the G++ compiler.
-You may omit the @code{CPP_Vtable} pragma if there is only one
-@code{Vtable_Ptr} component in the record and all virtual functions are
-imported on the Ada side (the default value for the entry count in this
-case is simply the total number of virtual functions).
-
-Pragma @code{CPP_Vtable} is intended primarily for automatic generation
-using an automatic binding generator tool.
See @ref{Interfacing to C++} for related information.
@node Pragma Debug
Syntax:
@smallexample @c ada
-pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON);
+pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
PROCEDURE_NAME
@end smallexample
@noindent
-The argument has the syntactic form of an expression, meeting the
-syntactic requirements for pragmas.
+The procedure call argument has the syntactic form of an expression, meeting
+the syntactic requirements for pragmas.
+
+If debug pragmas are not enabled or if the condition is present and evaluates
+to False, this pragma has no effect. If debug pragmas are enabled, the
+semantics of the pragma is exactly equivalent to the procedure call statement
+corresponding to the argument with a terminating semicolon. Pragmas are
+permitted in sequences of declarations, so you can use pragma @code{Debug} to
+intersperse calls to debug procedures in the middle of declarations. Debug
+pragmas can be enabled either by use of the command line switch @code{-gnata}
+or by use of the configuration pragma @code{Debug_Policy}.
+
+@node Pragma Debug_Policy
+@unnumberedsec Pragma Debug_Policy
+@findex Debug_Policy
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Debug_Policy (CHECK | IGNORE);
+@end smallexample
+
+@noindent
+If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled.
+If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored.
+This pragma overrides the effect of the @code{-gnata} switch on the
+command line.
+
+@node Pragma Detect_Blocking
+@unnumberedsec Pragma Detect_Blocking
+@findex Detect_Blocking
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Detect_Blocking;
+@end smallexample
-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 statement corresponding to the argument
-with a terminating semicolon. Pragmas are permitted in sequences of
-declarations, so you can use pragma @code{Debug} to intersperse calls to
-debug procedures in the middle of declarations.
+@noindent
+This is a configuration pragma that forces the detection of potentially
+blocking operations within a protected operation, and to raise Program_Error
+if that happens.
@node Pragma Elaboration_Checks
@unnumberedsec Pragma Elaboration_Checks
@smallexample @c ada
pragma Export_Exception (
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL,]
[, [Form =>] Ada | VMS]
[, [Code =>] static_integer_EXPRESSION]);
@smallexample @c ada
pragma Export_Function (
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Result_Type =>] result_SUBTYPE_MARK]
@smallexample @c ada
pragma Export_Object
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Size =>] EXTERNAL_SYMBOL]
@smallexample @c ada
pragma Export_Procedure (
- [Internal =>] LOCAL_NAME
+ [Internal =>] local_NAME
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]);
@smallexample @c ada
pragma Export_Valued_Procedure (
- [Internal =>] LOCAL_NAME
+ [Internal =>] local_NAME
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]);
@noindent
This pragma is identical to @code{Export_Procedure} except that the
-first parameter of @var{local_name}, which must be present, must be of
+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}
Syntax:
@smallexample @c ada
-pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
+pragma Finalize_Storage_Only (first_subtype_local_NAME);
@end smallexample
@noindent
Syntax:
@smallexample @c ada
-pragma Float_Representation (FLOAT_REP);
+pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
FLOAT_REP ::= VAX_Float | IEEE_Float
@end smallexample
@noindent
-This pragma
+In the one argument form, this pragma is a configuration pragma which
allows control over the internal representation chosen for the predefined
floating point types declared in the packages @code{Standard} and
@code{System}. On all systems other than OpenVMS, the argument must
description of the @code{GNAT LIBRARY} command in the OpenVMS version
of the GNAT Users Guide for details on the use of this command.
+The two argument form specifies the representation to be used for
+the specified floating-point type. On all systems other than OpenVMS,
+the argument must
+be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
+argument may be @code{VAX_Float} to specify the use of the VAX float
+format, as follows:
+
+@itemize @bullet
+@item
+For digits values up to 6, F float format will be used.
+@item
+For digits values from 7 to 9, G float format will be used.
+@item
+For digits values from 10 to 15, F float format will be used.
+@item
+Digits values above 15 are not allowed.
+@end itemize
+
@node Pragma Ident
@unnumberedsec Pragma Ident
@findex Ident
@smallexample @c ada
pragma Import_Exception (
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL,]
[, [Form =>] Ada | VMS]
[, [Code =>] static_integer_EXPRESSION]);
@smallexample @c ada
pragma Import_Function (
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Result_Type =>] SUBTYPE_MARK]
@smallexample @c ada
pragma Import_Object
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL],
[, [Size =>] EXTERNAL_SYMBOL]);
@smallexample @c ada
pragma Import_Procedure (
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]
@smallexample @c ada
pragma Import_Valued_Procedure (
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]
@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
+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}
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
+The other important difference is that you can control the value used
+for initializing scalar objects. At bind time, you can select several
+options for initialization. You can
+initialize with invalid values (similar to Normalize_Scalars, though for
+Initialize_Scalars it is not always possible to determine the invalid
+values in complex cases like signed component fields with non-standard
+sizes). You can also initialize with high or
low values, or with a specified bit pattern. See the users guide for binder
options for specifying these cases.
and if it does, then most likely you have an erroneous reference to an
uninitialized value.
+It is even possible to change the value at execution time eliminating even
+the need to rebind with a different switch using an environment variable.
+See the GNAT users guide for details.
+
Note that pragma @code{Initialize_Scalars} is particularly useful in
conjunction with the enhanced validity checking that is now provided
in GNAT, which checks for invalid values under more conditions.
@smallexample @c ada
pragma Interface (
[Convention =>] convention_identifier,
- [Entity =>] local_name
+ [Entity =>] local_NAME
[, [External_Name =>] static_string_expression],
[, [Link_Name =>] static_string_expression]);
@end smallexample
@smallexample @c ada
pragma Interface_Name (
- [Entity =>] LOCAL_NAME
+ [Entity =>] local_NAME
[, [External_Name =>] static_string_EXPRESSION]
[, [Link_Name =>] static_string_EXPRESSION]);
@end smallexample
Syntax:
@smallexample @c ada
-pragma Interrupt_Handler (procedure_LOCAL_NAME);
+pragma Interrupt_Handler (procedure_local_NAME);
@end smallexample
@noindent
Syntax:
@smallexample @c ada
-pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
+pragma Keep_Names ([On =>] enumeration_first_subtype_local_NAME);
@end smallexample
@noindent
-The @var{LOCAL_NAME} argument
+The @var{local_NAME} argument
must refer to an enumeration first subtype
in the current declarative part. The effect is to retain the enumeration
literal names for use by @code{Image} and @code{Value} even if a global
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.
+under the GPL@.
@item Restricted
This is used for a unit that is restricted in that it is not permitted to
@smallexample @c ada
pragma Linker_Alias (
- [Entity =>] LOCAL_NAME
- [Alias =>] static_string_EXPRESSION);
+ [Entity =>] local_NAME
+ [Target =>] static_string_EXPRESSION);
+@end smallexample
+
+@noindent
+@var{local_NAME} must refer to an object that is declared at the library
+level. This pragma establishes the given entity as a linker alias for the
+given target. It is equivalent to @code{__attribute__((alias))} in GNU C
+and causes @var{local_NAME} to be emitted as an alias for the symbol
+@var{static_string_EXPRESSION} in the object file, that is to say no space
+is reserved for @var{local_NAME} by the assembler and it will be resolved
+to the same address as @var{static_string_EXPRESSION} by the linker.
+
+The actual linker name for the target must be used (e.g. the fully
+encoded name with qualification in Ada, or the mangled name in C++),
+or it must be declared using the C convention with @code{pragma Import}
+or @code{pragma Export}.
+
+Not all target machines support this pragma. On some of them it is accepted
+only if @code{pragma Weak_External} has been applied to @var{local_NAME}.
+
+@smallexample @c ada
+-- Example of the use of pragma Linker_Alias
+
+package p is
+ i : Integer := 1;
+ pragma Export (C, i);
+
+ new_name_for_i : Integer;
+ pragma Linker_Alias (new_name_for_i, "i");
+end p;
+@end smallexample
+
+@node Pragma Linker_Constructor
+@unnumberedsec Pragma Linker_Constructor
+@findex Linker_Constructor
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Linker_Constructor (procedure_LOCAL_NAME);
+@end smallexample
+
+@noindent
+@var{procedure_local_NAME} must refer to a parameterless procedure that
+is declared at the library level. A procedure to which this pragma is
+applied will be treated as an initialization routine by the linker.
+It is equivalent to @code{__attribute__((constructor))} in GNU C and
+causes @var{procedure_LOCAL_NAME} to be invoked before the entry point
+of the executable is called (or immediately after the shared library is
+loaded if the procedure is linked in a shared library), in particular
+before the Ada run-time environment is set up.
+
+Because of these specific contexts, the set of operations such a procedure
+can perform is very limited and the type of objects it can manipulate is
+essentially restricted to the elementary types. In particular, it must only
+contain code to which pragma Restrictions (No_Elaboration_Code) applies.
+
+This pragma is used by GNAT to implement auto-initialization of shared Stand
+Alone Libraries, which provides a related capability without the restrictions
+listed above. Where possible, the use of Stand Alone Libraries is preferable
+to the use of this pragma.
+
+@node Pragma Linker_Destructor
+@unnumberedsec Pragma Linker_Destructor
+@findex Linker_Destructor
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Linker_Destructor (procedure_LOCAL_NAME);
@end smallexample
@noindent
-This pragma establishes a linker alias for the given named entity. For
-further details on the exact effect, consult the GCC manual.
+@var{procedure_local_NAME} must refer to a parameterless procedure that
+is declared at the library level. A procedure to which this pragma is
+applied will be treated as a finalization routine by the linker.
+It is equivalent to @code{__attribute__((destructor))} in GNU C and
+causes @var{procedure_LOCAL_NAME} to be invoked after the entry point
+of the executable has exited (or immediately before the shared library
+is unloaded if the procedure is linked in a shared library), in particular
+after the Ada run-time environment is shut down.
+
+See @code{pragma Linker_Constructor} for the set of restrictions that apply
+because of these specific contexts.
@node Pragma Linker_Section
@unnumberedsec Pragma Linker_Section
@smallexample @c ada
pragma Linker_Section (
- [Entity =>] LOCAL_NAME
+ [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.
+@var{local_NAME} must refer to an object that is declared at the library
+level. This pragma specifies the name of the linker section for the given
+entity. It is equivalent to @code{__attribute__((section))} in GNU C and
+causes @var{local_NAME} to be placed in the @var{static_string_EXPRESSION}
+section of the executable (assuming the linker doesn't rename the section).
+
+The compiler normally places library-level objects in standard sections
+depending on their type: procedures and functions generally go in the
+@code{.text} section, initialized variables in the @code{.data} section
+and uninitialized variables in the @code{.bss} section.
+
+Other, special sections may exist on given target machines to map special
+hardware, for example I/O ports or flash memory. This pragma is a means to
+defer the final layout of the executable to the linker, thus fully working
+at the symbolic level with the compiler.
+
+Some file formats do not support arbitrary sections so not all target
+machines support this pragma. The use of this pragma may cause a program
+execution to be erroneous if it is used to place an entity into an
+inappropriate section (e.g. a modified variable into the @code{.text}
+section). See also @code{pragma Persistent_BSS}.
+
+@smallexample @c ada
+-- Example of the use of pragma Linker_Section
+
+package IO_Card is
+ Port_A : Integer;
+ pragma Volatile (Port_A);
+ pragma Linker_Section (Port_A, ".bss.port_a");
+
+ Port_B : Integer;
+ pragma Volatile (Port_B);
+ pragma Linker_Section (Port_B, ".bss.port_b");
+end IO_Card;
+@end smallexample
@node Pragma Long_Float
@unnumberedsec Pragma Long_Float
@smallexample @c ada
pragma Machine_Attribute (
[Attribute_Name =>] string_EXPRESSION,
- [Entity =>] LOCAL_NAME);
+ [Entity =>] local_NAME);
@end smallexample
@noindent
-Machine dependent attributes can be specified for types and/or
-declarations. Currently only subprogram entities are supported. This
-pragma is semantically equivalent to
+Machine-dependent attributes can be specified for types and/or
+declarations. This pragma is semantically equivalent to
@code{__attribute__((@var{string_expression}))} in GNU C,
where @code{@var{string_expression}} is
-recognized by the 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.
+recognized by the target macro @code{TARGET_ATTRIBUTE_TABLE} which is
+defined for each machine. See the GCC manual for further information.
+It is not possible to specify attributes defined by other languages,
+only attributes defined by the machine the code is intended to run on.
@node Pragma Main_Storage
@unnumberedsec Pragma Main_Storage
Syntax:
@smallexample @c ada
-pragma No_Return (procedure_LOCAL_NAME);
+pragma No_Return (procedure_local_NAME @{, procedure_local_NAME@});
@end smallexample
@noindent
-@var{procedure_local_NAME} must refer to one or more procedure
+Each @var{procedure_local_NAME} argument must refer to one or more procedure
declarations in the current declarative part. A procedure to which this
-pragma is applied may not contain any explicit @code{return} statements,
-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
+pragma is applied may not contain any explicit @code{return} statements.
+In addition, if the procedure contains any implicit returns from falling
+off the end of a statement sequence, then execution of that implicit
+return will cause Program_Error to be raised.
+
+One use of this pragma is to identify procedures whose only purpose is to raise
+an exception. Another use of this pragma is to suppress incorrect warnings
+about missing returns in functions, where the last statement of a function
statement sequence is a call to such a procedure.
+Note that in Ada 2005 mode, this pragma is part of the language, and is
+identical in effect to the pragma as implemented in Ada 95 mode.
+
+@node Pragma No_Strict_Aliasing
+@unnumberedsec Pragma No_Strict_Aliasing
+@findex No_Strict_Aliasing
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
+@end smallexample
+
+@noindent
+@var{type_LOCAL_NAME} must refer to an access type
+declaration in the current declarative part. The effect is to inhibit
+strict aliasing optimization for the given type. The form with no
+arguments is a configuration pragma which applies to all access types
+declared in units to which the pragma applies. For a detailed
+description of the strict aliasing optimization, and the situations
+in which it must be suppressed, see section
+``Optimization and Strict Aliasing'' in the @value{EDITION} User's Guide.
+
@node Pragma Normalize_Scalars
@unnumberedsec Pragma Normalize_Scalars
@findex Normalize_Scalars
@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.
+Character'Last unless the subtype range excludes NUL (in which case
+NUL is used). This choice will always generate an invalid value if
+one exists.
@item Standard.Wide_Character
@noindent
Objects whose root type is Standard.Wide_Character are initialized to
-Wide_Character'Last. This will be out of range of the subtype only if
-the subtype range excludes this value.
+Wide_Character'Last unless the subtype range excludes NUL (in which case
+NUL is used). This choice will always generate an invalid value if
+one exists.
-@item Integer types
+@item Standard.Wide_Wide_Character
@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 @c ada
-subtype Ityp is integer range 1 .. 10;
-@end smallexample
+Objects whose root type is Standard.Wide_Wide_Character are initialized to
+the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
+which case NUL is used). This choice will always generate an invalid value if
+one exists.
+@item Integer types
@noindent
-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.
+Objects of an integer type are treated differently depending on whether
+negative values are present in the subtype. If no negative values are
+present, then all one bits is used as the initial value except in the
+special case where zero is excluded from the subtype, in which case
+all zero bits are used. This choice will always generate an invalid
+value if one exists.
+
+For subtypes with negative values present, the largest negative number
+is used, except in the unusual case where this largest negative number
+is in the subtype, and the largest positive number is not, in which case
+the largest positive value is used. This choice will always generate
+an invalid value if one exists.
+
+@item Floating-Point Types
+Objects of all floating-point types are initialized to all 1-bits. For
+standard IEEE format, this corresponds to a NaN (not a number) which is
+indeed an invalid value.
+
+@item Fixed-Point Types
+Objects of all fixed-point types are treated as described above for integers,
+with the rules applying to the underlying integer value used to represent
+the fixed-point value.
@item Modular types
-Objects of a modular type are initialized to typ'Last. This will be out
-of range of the subtype only if the subtype excludes this value.
+Objects of a modular type are initialized to all one bits, except in
+the special case where zero is excluded from the subtype, in which
+case all zero bits are used. This choice will always generate an
+invalid value if one exists.
@item Enumeration types
Objects of an enumeration type are initialized to all one-bits, i.e.@: to
-the value @code{2 ** typ'Size - 1}. 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 elements.
+the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
+whose Pos value is zero, in which case a code of zero is used. This choice
+will always generate an invalid value if one exists.
@end table
Syntax:
@smallexample @c ada
-pragma Obsolescent [(static_string_EXPRESSION)];
+pragma Obsolescent
+ (Entity => NAME [, static_string_EXPRESSION [,Ada_05]]);
@end smallexample
@noindent
-This pragma must occur immediately following a subprogram
-declaration. It indicates that the associated function or procedure
+This pragma can occur immediately following a declaration of an entity,
+including the case of a record component, and usually the Entity name
+must match the name of the entity declared by this declaration.
+Alternatively, the pragma can immediately follow an
+enumeration type declaration, where the entity argument names one of the
+enumeration literals.
+
+This pragma is used to indicate that the named entity
is considered obsolescent and should not be used. Typically this is
used when an API must be modified by eventually removing or modifying
-existing subprograms. The pragma can be used at an intermediate stage
-when the subprogram is still present, but will be removed later.
+existing subprograms or other entities. The pragma can be used at an
+intermediate stage when the entity is still present, but will be
+removed later.
-The effect of this pragma is to output a warning message that the
+The effect of this pragma is to output a warning message on
+a call to a program thus marked that the
subprogram is obsolescent if the appropriate warning option in the
-compiler is activated. If a parameter is present, then a second
+compiler is activated. If the string parameter is present, then a second
warning message is given containing this text.
+In addition, a call to such a program is considered a violation of
+pragma Restrictions (No_Obsolescent_Features).
+
+This pragma can also be used as a program unit pragma for a package,
+in which case the entity name is the name of the package, and the
+pragma indicates that the entire package is considered
+obsolescent. In this case a client @code{with}'ing such a package
+violates the restriction, and the @code{with} statement is
+flagged with warnings if the warning option is set.
+
+If the optional third parameter is present (which must be exactly
+the identifier Ada_05, no other argument is allowed), then the
+indication of obsolescence applies only when compiling in Ada 2005
+mode. This is primarily intended for dealing with the situations
+in the predefined library where subprograms or packages
+have become defined as obsolescent in Ada 2005
+(e.g. in Ada.Characters.Handling), but may be used anywhere.
+
+The following examples show typical uses of this pragma:
+
+@smallexample @c ada
+package p is
+ pragma Obsolescent
+ (Entity => p, "use pp instead of p");
+end p;
+
+package q is
+ procedure q2;
+ pragma Obsolescent
+ (Entity => q2, "use q2new instead");
+
+ type R is new integer;
+ pragma Obsolescent
+ (Entity => R, "use RR in Ada 2005", Ada_05);
+
+ type M is record
+ F1 : Integer;
+ F2 : Integer;
+ pragma Obsolescent (Entity => F2);
+ F3 : Integer;
+ end record;
+
+ type E is (a, bc, 'd', quack);
+ pragma Obsolescent (Entity => bc)
+ pragma Obsolescent (Entity => 'd')
+
+ function "+"
+ (a, b : character) return character;
+ pragma Obsolescent (Entity => "+");
+end;
+@end smallexample
+
+@noindent
+In an earlier version of GNAT, the Entity parameter was not required,
+and this form is still accepted for compatibility purposes. If the
+Entity parameter is omitted, then the pragma applies to the declaration
+immediately preceding the pragma (this form cannot be used for the
+enumeration literal case).
@node Pragma Passive
@unnumberedsec Pragma Passive
optimized. GNAT does not attempt to optimize any tasks in this manner
(since protected objects are available in place of passive tasks).
+@node Pragma Persistent_BSS
+@unnumberedsec Pragma Persistent_BSS
+@findex Persistent_BSS
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Persistent_BSS [local_NAME]
+@end smallexample
+
+@noindent
+This pragma allows selected objects to be placed in the @code{.persistent_bss}
+section. On some targets the linker and loader provide for special
+treatment of this section, allowing a program to be reloaded without
+affecting the contents of this data (hence the name persistent).
+
+There are two forms of usage. If an argument is given, it must be the
+local name of a library level object, with no explicit initialization
+and whose type is potentially persistent. If no argument is given, then
+the pragma is a configuration pragma, and applies to all library level
+objects with no explicit initialization of potentially persistent types.
+
+A potentially persistent type is a scalar type, or a non-tagged,
+non-discriminated record, all of whose components have no explicit
+initialization and are themselves of a potentially persistent type,
+or an array, all of whose constraints are static, and whose component
+type is potentially persistent.
+
+If this pragma is used on a target where this feature is not supported,
+then the pragma will be ignored. See also @code{pragma Linker_Section}.
+
@node Pragma Polling
@unnumberedsec Pragma Polling
@findex Polling
definition of the ``Ravenscar Profile'' for limited tasking, devised and
published by the @cite{International Real-Time Ada Workshop}, 1997,
and whose most recent description is available at
-@url{ftp://ftp.openravenscar.org/openravenscar/ravenscar00.pdf}.
+@url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
The original definition of the profile was revised at subsequent IRTAW
meetings. It has been included in the ISO
respectively.
The above set is a superset of the restrictions provided by pragma
-@code{Restricted_Run_Time}, it includes six additional restrictions
+@code{Profile (Restricted)}, it includes six additional restrictions
(@code{Simple_Barriers}, @code{No_Select_Statements},
@code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
@code{No_Relative_Delay} and @code{No_Task_Termination}). This means
that pragma @code{Profile (Ravenscar)}, like the pragma
-@code{Restricted_Run_Time}, automatically causes the use of a simplified,
+@code{Profile (Restricted)},
+automatically causes the use of a simplified,
more efficient version of the tasking run-time system.
-@node Pragma Propagate_Exceptions
-@unnumberedsec Pragma Propagate_Exceptions
-@findex Propagate_Exceptions
-@cindex Zero Cost Exceptions
+@node Pragma Profile (Restricted)
+@unnumberedsec Pragma Profile (Restricted)
+@findex Restricted Run Time
@noindent
Syntax:
@smallexample @c ada
-pragma Propagate_Exceptions (subprogram_LOCAL_NAME);
+pragma Profile (Restricted);
@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 @code{longjmp} / @code{setjmp} implementation of
-exceptions is used (although it is harmless to use it in such cases).
+A configuration pragma that establishes the following set of restrictions:
-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}.
+@itemize @bullet
+@item No_Abort_Statements
+@item No_Entry_Queue
+@item No_Task_Hierarchy
+@item No_Task_Allocators
+@item No_Dynamic_Priorities
+@item No_Terminate_Alternatives
+@item No_Dynamic_Attachment
+@item No_Protected_Type_Allocators
+@item No_Local_Protected_Objects
+@item No_Requeue_Statements
+@item No_Task_Attributes_Package
+@item Max_Asynchronous_Select_Nesting = 0
+@item Max_Task_Entries = 0
+@item Max_Protected_Entries = 1
+@item Max_Select_Alternatives = 0
+@end itemize
-For the @code{longjmp} / @code{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.
+@noindent
+This set of restrictions causes the automatic selection of a simplified
+version of the run time that provides improved performance for the
+limited set of tasking functionality permitted by this set of restrictions.
@node Pragma Psect_Object
@unnumberedsec Pragma Psect_Object
@smallexample @c ada
pragma Psect_Object (
- [Internal =>] LOCAL_NAME,
+ [Internal =>] local_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Size =>] EXTERNAL_SYMBOL]);
Syntax:
@smallexample @c ada
-pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
+pragma Pure_Function ([Entity =>] function_local_NAME);
@end smallexample
@noindent
disambiguate cases of overloading where some but not all functions
in a set of overloaded functions are to be designated as pure.
-@node Pragma Restricted_Run_Time
-@unnumberedsec Pragma Restricted_Run_Time
-@findex Restricted_Run_Time
-@noindent
-Syntax:
-
-@smallexample @c ada
-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_Entry_Queue
-@item No_Task_Hierarchy
-@item No_Task_Allocators
-@item No_Dynamic_Priorities
-@item No_Terminate_Alternatives
-@item No_Dynamic_Attachment
-@item No_Protected_Type_Allocators
-@item No_Local_Protected_Objects
-@item No_Requeue_Statements
-@item No_Task_Attributes_Package
-@item Max_Asynchronous_Select_Nesting = 0
-@item Max_Task_Entries = 0
-@item Max_Protected_Entries = 1
-@item Max_Select_Alternatives = 0
-@end itemize
-
-@noindent
-This set of restrictions causes the automatic selection of a simplified
-version of the run time that provides improved performance for the
-limited set of tasking functionality permitted by this set of restrictions.
+If pragma @code{Pure_Function} is applied to a library level function, the
+function is also considered pure from an optimization point of view, but the
+unit is not a Pure unit in the categorization sense. So for example, a function
+thus marked is free to @code{with} non-pure units.
@node Pragma Restriction_Warnings
@unnumberedsec Pragma Restriction_Warnings
@smallexample @c ada
pragma Stream_Convert (
- [Entity =>] type_LOCAL_NAME,
+ [Entity =>] type_local_NAME,
[Read =>] function_NAME,
[Write =>] function_NAME);
@end smallexample
@smallexample @c ada
pragma Style_Checks (string_LITERAL | ALL_CHECKS |
- On | Off [, LOCAL_NAME]);
+ On | Off [, local_NAME]);
@end smallexample
@noindent
This pragma is recognized for compatibility with other Ada compilers
but is ignored by GNAT@.
+@node Pragma Suppress
+@unnumberedsec Pragma Suppress
+@findex Suppress
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Suppress (Identifier [, [On =>] Name]);
+@end smallexample
+
+@noindent
+This is a standard pragma, and supports all the check names required in
+the RM. It is included here because GNAT recognizes one additional check
+name: @code{Alignment_Check} which can be used to suppress alignment checks
+on addresses used in address clauses. Such checks can also be suppressed
+by suppressing range checks, but the specific use of @code{Alignment_Check}
+allows suppression of alignment checks without suppressing other range checks.
+
@node Pragma Suppress_All
@unnumberedsec Pragma Suppress_All
@findex Suppress_All
@smallexample @c ada
pragma Task_Storage (
- [Task_Type =>] LOCAL_NAME,
+ [Task_Type =>] local_NAME,
[Top_Guard =>] static_integer_EXPRESSION);
@end smallexample
@smallexample @c ada
pragma Thread_Body (
- [Entity =>] LOCAL_NAME,
+ [Entity =>] local_NAME,
[[Secondary_Stack_Size =>] static_integer_EXPRESSION)];
@end smallexample
Syntax:
@smallexample @c ada
-pragma Unchecked_Union (first_subtype_LOCAL_NAME);
+pragma Unchecked_Union (first_subtype_local_NAME);
@end smallexample
@noindent
-This pragma is used to declare that the specified type should be represented
-in a manner
-equivalent to a C union type, and is intended only for use in
-interfacing with C code that uses union types. In Ada terms, the named
-type must obey the following rules:
-
-@itemize @bullet
-@item
-It is a non-tagged non-limited record type.
-@item
-It has a single discrete discriminant with a default value.
-@item
-The component list consists of a single variant part.
-@item
-Each variant has a component list with a single component.
-@item
-No nested variants are allowed.
-@item
-No component has an explicit default value.
-@item
-No component has a non-static constraint.
-@end itemize
-
-@noindent
-In addition, given a type that meets the above requirements, the
-following restrictions apply to its use throughout the program:
-
-@itemize @bullet
-@item
-The discriminant name can be mentioned only in an aggregate.
-@item
-No subtypes may be created of this type.
-@item
-The type may not be constrained by giving a discriminant value.
-@item
-The type cannot be passed as the actual for a generic formal with a
-discriminant.
-@end itemize
-
-@noindent
-Equality and inequality operations on @code{unchecked_unions} are not
-available, since there is no discriminant to compare and the compiler
-does not even know how many bits to compare. It is implementation
-dependent whether this is detected at compile time as an illegality or
-whether it is undetected and considered to be an erroneous construct. In
-GNAT, a direct comparison is illegal, but GNAT does not attempt to catch
-the composite case (where two composites are compared that contain an
-unchecked union component), so such comparisons are simply considered
-erroneous.
-
-The layout of the resulting type corresponds exactly to a C union, where
-each branch of the union corresponds to a single variant in the Ada
-record. The semantics of the Ada program is not changed in any way by
-the pragma, i.e.@: provided the above restrictions are followed, and no
-erroneous incorrect references to fields or erroneous comparisons occur,
-the semantics is exactly as described by the Ada reference manual.
-Pragma @code{Suppress (Discriminant_Check)} applies implicitly to the
-type and the default convention is C.
+This pragma is used to specify a representation of a record type that is
+equivalent to a C union. It was introduced as a GNAT implementation defined
+pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
+pragma, making it language defined, and GNAT fully implements this extended
+version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
+details, consult the Ada 2005 RM, section B.3.3.
@node Pragma Unimplemented_Unit
@unnumberedsec Pragma Unimplemented_Unit
Syntax:
@smallexample @c ada
-pragma Unreferenced (local_Name @{, local_Name@});
+pragma Unreferenced (local_NAME @{, local_NAME@});
+pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
@end smallexample
@noindent
objects declared only for their initialization or finalization side
effects.
-If @code{local_Name} identifies more than one matching homonym in the
+If @code{local_NAME} identifies more than one matching homonym in the
current scope, then the entity most recently declared is the one to which
-the pragma applies.
+the pragma applies. Note that in the case of accept formals, the pragma
+Unreferenced may appear immediately after the keyword @code{do} which
+allows the indication of whether or not accept formals are referenced
+or not to be given individually for each accept statement.
The left hand side of an assignment does not count as a reference for the
purpose of this pragma. Thus it is fine to assign to an entity for which
pragma Unreferenced is given.
+Note that if a warning is desired for all calls to a given subprogram,
+regardless of whether they occur in the same unit as the subprogram
+declaration, then this pragma should not be used (calls from another
+unit would not be flagged); pragma Obsolescent can be used instead
+for this purpose, see @xref{Pragma Obsolescent}.
+
+The second form of pragma @code{Unreferenced} is used within a context
+clause. In this case the arguments must be unit names of units previously
+mentioned in @code{with} clauses (similar to the usage of pragma
+@code{Elaborate_All}. The effect is to suppress warnings about unreferenced
+units.
+
+@node Pragma Unreferenced_Objects
+@unnumberedsec Pragma Unreferenced_Objects
+@findex Unreferenced_Objects
+@cindex Warnings, unreferenced
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
+@end smallexample
+
+@noindent
+This pragma signals that for the types or subtypes whose names are
+listed, objects which are declared with one of these types or subtypes may
+not be referenced, and if no references appear, no warnings are given.
+
+This is particularly useful for objects which are declared solely for their
+initialization and finalization effect. Such variables are sometimes referred
+to as RAII variables (Resource Acquisition Is Initialization). Using this
+pragma on the relevant type (most typically a limited controlled type), the
+compiler will automatically suppress unwanted warnings about these variables
+not being referenced.
+
@node Pragma Unreserve_All_Interrupts
@unnumberedsec Pragma Unreserve_All_Interrupts
@findex Unreserve_All_Interrupts
Syntax:
@smallexample @c ada
-pragma Warnings (On | Off [, LOCAL_NAME]);
+pragma Warnings (On | Off);
+pragma Warnings (On | Off, local_NAME);
+pragma Warnings (static_string_EXPRESSION);
+pragma Warnings (On | Off, static_string_EXPRESSION);
@end smallexample
@noindent
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.
+The form with a single argument may be used as a configuration pragma.
-If the @var{local_name} parameter is present, warnings are suppressed for
+If the @var{local_NAME} parameter is present, warnings are suppressed for
the specified entity. This suppression is effective from the point where
it occurs till the end of the extended scope of the variable (similar to
the scope of @code{Suppress}).
+The form with a single static_string_EXPRESSION argument provides more precise
+control over which warnings are active. The string is a list of letters
+specifying which warnings are to be activated and which deactivated. The
+code for these letters is the same as the string used in the command
+line switch controlling warnings. The following is a brief summary. For
+full details see the GNAT Users Guide:
+
+@smallexample
+a turn on all optional warnings (except d,h,l)
+A turn off all optional warnings
+b turn on warnings for bad fixed value (not multiple of small)
+B turn off warnings for bad fixed value (not multiple of small)
+c turn on warnings for constant conditional
+C turn off warnings for constant conditional
+d turn on warnings for implicit dereference
+D turn off warnings for implicit dereference
+e treat all warnings as errors
+f turn on warnings for unreferenced formal
+F turn off warnings for unreferenced formal
+g turn on warnings for unrecognized pragma
+G turn off warnings for unrecognized pragma
+h turn on warnings for hiding variable
+H turn off warnings for hiding variable
+i turn on warnings for implementation unit
+I turn off warnings for implementation unit
+j turn on warnings for obsolescent (annex J) feature
+J turn off warnings for obsolescent (annex J) feature
+k turn on warnings on constant variable
+K turn off warnings on constant variable
+l turn on warnings for missing elaboration pragma
+L turn off warnings for missing elaboration pragma
+m turn on warnings for variable assigned but not read
+M turn off warnings for variable assigned but not read
+n normal warning mode (cancels -gnatws/-gnatwe)
+o turn on warnings for address clause overlay
+O turn off warnings for address clause overlay
+p turn on warnings for ineffective pragma Inline
+P turn off warnings for ineffective pragma Inline
+q turn on warnings for questionable missing parentheses
+Q turn off warnings for questionable missing parentheses
+r turn on warnings for redundant construct
+R turn off warnings for redundant construct
+s suppress all warnings
+t turn on warnings for tracking deleted code
+T turn off warnings for tracking deleted code
+u turn on warnings for unused entity
+U turn off warnings for unused entity
+v turn on warnings for unassigned variable
+V turn off warnings for unassigned variable
+w turn on warnings for wrong low bound assumption
+W turn off warnings for wrong low bound assumption
+x turn on warnings for export/import
+X turn off warnings for export/import
+y turn on warnings for Ada 2005 incompatibility
+Y turn off warnings for Ada 2005 incompatibility
+z turn on size/align warnings for unchecked conversion
+Z turn off size/align warnings for unchecked conversion
+@end smallexample
+
+@noindent
+The specified warnings will be in effect until the end of the program
+or another pragma Warnings is encountered. The effect of the pragma is
+cumulative. Initially the set of warnings is the standard default set
+as possibly modified by compiler switches. Then each pragma Warning
+modifies this set of warnings as specified. This form of the pragma may
+also be used as a configuration pragma.
+
+The fourth form, with an On|Off parameter and a string, is used to
+control individual messages, based on their text. The string argument
+is a pattern that is used to match against the text of individual
+warning messages (not including the initial "warnings: " tag).
+
+The pattern may start with an asterisk, which matches otherwise unmatched
+characters at the start of the message, and it may also end with an asterisk
+which matches otherwise unmatched characters at the end of the message. For
+example, the string "*alignment*" could be used to match any warnings about
+alignment problems. Within the string, the sequence "*" can be used to match
+any sequence of characters enclosed in quotation marks. No other regular
+expression notations are permitted. All characters other than asterisk in
+these three specific cases are treated as literal characters in the match.
+
+There are two ways to use this pragma. The OFF form can be used as a
+configuration pragma. The effect is to suppress all warnings (if any)
+that match the pattern string throughout the compilation.
+
+The second usage is to suppress a warning locally, and in this case, two
+pragmas must appear in sequence:
+
+@smallexample @c ada
+pragma Warnings (Off, Pattern);
+.. code where given warning is to be suppressed
+pragma Warnings (On, Pattern);
+@end smallexample
+
+@noindent
+In this usage, the pattern string must match in the Off and On pragmas,
+and at least one matching warning must be suppressed.
+
@node Pragma Weak_External
@unnumberedsec Pragma Weak_External
@findex Weak_External
Syntax:
@smallexample @c ada
-pragma Weak_External ([Entity =>] LOCAL_NAME);
+pragma Weak_External ([Entity =>] local_NAME);
+@end smallexample
+
+@noindent
+@var{local_NAME} must refer to an object that is declared at the library
+level. This pragma specifies that the given entity should be marked as a
+weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
+in GNU C and causes @var{local_NAME} to be emitted as a weak symbol instead
+of a regular symbol, that is to say a symbol that does not have to be
+resolved by the linker if used in conjunction with a pragma Import.
+
+When a weak symbol is not resolved by the linker, its address is set to
+zero. This is useful in writing interfaces to external modules that may
+or may not be linked in the final executable, for example depending on
+configuration settings.
+
+If a program references at run time an entity to which this pragma has been
+applied, and the corresponding symbol was not resolved at link time, then
+the execution of the program is erroneous. It is not erroneous to take the
+Address of such an entity, for example to guard potential references,
+as shown in the example below.
+
+Some file formats do not support weak symbols so not all target machines
+support this pragma.
+
+@smallexample @c ada
+-- Example of the use of pragma Weak_External
+
+package External_Module is
+ key : Integer;
+ pragma Import (C, key);
+ pragma Weak_External (key);
+ function Present return boolean;
+end External_Module;
+
+with System; use System;
+package body External_Module is
+ function Present return boolean is
+ begin
+ return key'Address /= System.Null_Address;
+ end Present;
+end External_Module;
+@end smallexample
+
+@node Pragma Wide_Character_Encoding
+@unnumberedsec Pragma Wide_Character_Encoding
+@findex Wide_Character_Encoding
+@noindent
+Syntax:
+
+@smallexample @c ada
+pragma Wide_Character_Encoding (IDENTIFIER | CHRARACTER_LITERAL);
@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.
+This pragma specifies the wide character encoding to be used in program
+source text appearing subsequently. It is a configuration pragma, but may
+also be used at any point that a pragma is allowed, and it is permissible
+to have more than one such pragma in a file, allowing multiple encodings
+to appear within the same file.
+
+The argument can be an identifier or a character literal. In the identifier
+case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
+@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
+case it is correspondingly one of the characters h,u,s,e,8,b.
+
+Note that when the pragma is used within a file, it affects only the
+encoding within that file, and does not affect withed units, specs,
+or subunits.
@node Implementation Defined Attributes
@chapter Implementation Defined Attributes
* Enum_Rep::
* Epsilon::
* Fixed_Value::
+* Has_Access_Values::
* Has_Discriminants::
* Img::
* Integer_Value::
* Safe_Large::
* Small::
* Storage_Unit::
+* Stub_Type::
* Target_Name::
* Tick::
* To_Address::
This attribute is primarily intended for use in implementation of the
input-output functions for fixed-point values.
+@node Has_Access_Values
+@unnumberedsec Has_Access_Values
+@cindex Access values, testing for
+@findex Has_Access_Values
+@noindent
+The prefix of the @code{Has_Access_Values} attribute is a type. The result
+is a Boolean value which is True if the is an access type, or is a composite
+type with a component (at any nesting depth) that is an access type, and is
+False otherwise.
+The intended use of this attribute is in conjunction with generic
+definitions. If the attribute is applied to a generic private type, it
+indicates whether or not the corresponding actual type has access values.
+
@node Has_Discriminants
@unnumberedsec Has_Discriminants
@cindex Discriminants, testing for
@code{R2} will be only
8 bits (one byte), since @code{R2'Object_Size} has been set to 8.
+Although @code{Object_Size} does properly reflect the default object size
+value, it is not necessarily the case that all objects will be of this size
+in a case where it is not specified explicitly. The compiler is free to
+increase the size and alignment of stand alone objects to improve efficiency
+of the generated code and sometimes does so in the case of large composite
+objects. If the size of a stand alone object is critical to the
+application, it should be specified explicitly.
+
@node Passed_By_Reference
@unnumberedsec Passed_By_Reference
@cindex Parameters, when passed by reference
@code{Standard'Storage_Unit} (@code{Standard} is the only permissible
prefix) provides the same value as @code{System.Storage_Unit}.
+@node Stub_Type
+@unnumberedsec Stub_Type
+@findex Stub_Type
+@noindent
+The GNAT implementation of remote access-to-classwide types is
+organized as described in AARM section E.4 (20.t): a value of an RACW type
+(designating a remote object) is represented as a normal access
+value, pointing to a "stub" object which in turn contains the
+necessary information to contact the designated remote object. A
+call on any dispatching operation of such a stub object does the
+remote call, if necessary, using the information in the stub object
+to locate the target partition, etc.
+
+For a prefix @code{T} that denotes a remote access-to-classwide type,
+@code{T'Stub_Type} denotes the type of the corresponding stub objects.
+
+By construction, the layout of @code{T'Stub_Type} is identical to that of
+type @code{RACW_Stub_Type} declared in the internal implementation-defined
+unit @code{System.Partition_Interface}. Use of this attribute will create
+an implicit dependency on this unit.
+
@node Target_Name
@unnumberedsec Target_Name
@findex Target_Name
construction of values of the floating-point attributes from the file
@file{ttypef.ads}, but may also be used by user programs.
+For example, the following program prints the first 50 digits of pi:
+
+@smallexample @c ada
+with Text_IO; use Text_IO;
+with Ada.Numerics;
+procedure Pi is
+begin
+ Put (Ada.Numerics.Pi'Universal_Literal_String);
+end;
+@end smallexample
+
@node Unrestricted_Access
@unnumberedsec Unrestricted_Access
@cindex @code{Access}, unrestricted
is in scope (normal Ada 95 accessibility rules restrict this usage).
It is possible to use @code{Unrestricted_Access} for any type, but care
-must be excercised if it is used to create pointers to unconstrained
+must be exercised if it is used to create pointers to unconstrained
objects. In this case, the resulting pointer has the same scope as the
context of the attribute, and may not be returned to some enclosing
scope. For instance, a function cannot use @code{Unrestricted_Access}
Affects semantics
@item CPP_Constructor
Affects semantics
-@item CPP_Virtual
-Affects semantics
-@item CPP_Vtable
-Affects semantics
@item Debug
Affects semantics
@item Interface_Name
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:
+Followed. In fact, GNAT goes beyond the recommended level of support
+by allowing nonstatic expressions in some representation clauses even
+without the need to declare constants initialized with the values of
+such expressions.
+For example:
@smallexample @c ada
-X : Some_Type;
-for X'Address use To_address (16#2000#);
+ X : Integer;
+ Y : Float;
+ for Y'Address use X'Address;>>
@end smallexample
-@noindent
-will be rejected, since the To_Address expression is non-static. Instead
-write:
-
-@smallexample @c ada
-X_Address : constant Address : = To_Address (16#2000#);
-X : Some_Type;
-for X'Address use X_Address;
-@end smallexample
@sp 1
@cartouche
the given hardware architecture should be provided directly in
@code{Interfaces}.
@end cartouche
-Followed. An additional package not defined
+Followed. An additional package not defined
in the Ada 95 Reference Manual is @code{Interfaces.CPP}, used
for interfacing to C++.
GNAT currently takes advantage of these restrictions by providing an optimized
run time when the Ravenscar profile and the GNAT restricted run time set
of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
-pragma @code{Restricted_Run_Time} for more details.
+pragma @code{Profile (Restricted)} for more details.
@cindex Time, monotonic
@unnumberedsec D.8(47-49): Monotonic Time
@item
@code{ppp} is the Process Id value as a decimal integer (this line is
-present only if the Process Id is non-zero). Currently we are
+present only if the Process Id is nonzero). Currently we are
not making use of this field.
@item
@end cartouche
@noindent
Unchecked conversion between types of the same size
-and results in an uninterpreted transmission of the bits from one type
+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.
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.
+target type. Unchecked conversions where the target subtype is an
+unconstrained array are not permitted. If the target alignment is
+greater than the source alignment, then a copy of the result is
+made with appropriate alignment
@sp 1
@cartouche
where the certification protocol requires the use of short-circuit
(and then, or else) forms for all composite boolean operations.
+@item No_Dispatching_Calls
+@findex No_Dispatching_Calls
+This restriction ensures at compile time that the code generated by the
+compiler involves no dispatching calls. The use of this restriction allows the
+safe use of record extensions, classwide membership tests and other classwide
+features not involving implicit dispatching. This restriction ensures that
+the code contains no indirect calls through a dispatching mechanism. Note that
+this includes internally-generated calls created by the compiler, for example
+in the implementation of class-wide objects assignments. The
+membership test is allowed in the presence of this restriction, because its
+implementation requires no dispatching.
+This restriction is comparable to the official Ada restriction
+@code{No_Dispatch} except that it is a bit less restrictive in that it allows
+all classwide constructs that do not imply dispatching.
+The following example indicates constructs that violate this restriction.
+
+@smallexample
+package Pkg is
+ type T is tagged record
+ Data : Natural;
+ end record;
+ procedure P (X : T);
+
+ type DT is new T with record
+ More_Data : Natural;
+ end record;
+ procedure Q (X : DT);
+end Pkg;
+
+with Pkg; use Pkg;
+procedure Example is
+ procedure Test (O : T'Class) is
+ N : Natural := O'Size;-- Error: Dispatching call
+ C : T'Class := O; -- Error: implicit Dispatching Call
+ begin
+ if O in DT'Class then -- OK : Membership test
+ Q (DT (O)); -- OK : Type conversion plus direct call
+ else
+ P (O); -- Error: Dispatching call
+ end if;
+ end Test;
+
+ Obj : DT;
+begin
+ P (Obj); -- OK : Direct call
+ P (T (Obj)); -- OK : Type conversion plus direct call
+ P (T'Class (Obj)); -- Error: Dispatching call
+
+ Test (Obj); -- OK : Type conversion
+
+ if Obj in T'Class then -- OK : Membership test
+ null;
+ end if;
+end Example;
+@end smallexample
+
@item No_Dynamic_Attachment
@findex No_Dynamic_Attachment
This restriction ensures that there is no call to any of the operations
The parameter is a C null-terminated string representing a message to be
associated with the exception (typically the source location of the raise
- statement generated by the compiler). The Line parameter when non-zero
+ statement generated by the compiler). The Line parameter when nonzero
represents the line number in the source program where the raise occurs.
@item No_Exception_Streams
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.
+conditional. Note that this check does not include run time constraint
+checks, which on some targets may generate implicit conditionals as
+well. To control the latter, constraint checks can be suppressed in the
+normal manner. Constructs generating implicit conditionals include comparisons
+of composite objects and the Max/Min attributes.
@item No_Implicit_Dynamic_Code
@findex No_Implicit_Dynamic_Code
@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}.
+This restriction ensures at compile/bind time that there are no
+stream objects created (and therefore no actual stream operations).
+This restriction does not forbid dependences on the package
+@code{Ada.Streams}. So it is permissible to with
+@code{Ada.Streams} (or another package that does so itself)
+as long as no actual stream objects are created.
@item No_Task_Attributes_Package
@findex No_Task_Attributes_Package
except that violations are caught at compile time and cause an error message
to be output either by the compiler or binder.
-@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
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
+registry procedure). This restriction is enforced on
a unit by unit basis, it need not be obeyed consistently
throughout a partition.
+In the case of aggregates with others, if the aggregate has a dynamic
+size, there is no way to eliminate the elaboration code (such dynamic
+bounds would be incompatible with @code{Preelaborate} in any case. If
+the bounds are static, then use of this restriction actually modifies
+the code choice of the compiler to avoid generating a loop, and instead
+generate the aggregate statically if possible, no matter how many times
+the data for the others clause must be repeatedly generated.
+
+It is not possible to precisely document
+the constructs which are compatible with this restriction, since,
+unlike most other restrictions, this is not a restriction on the
+source code, but a restriction on the generated object code. For
+example, if the source contains a declaration:
+
+@smallexample
+ Val : constant Integer := X;
+@end smallexample
+
+@noindent
+where X is not a static constant, it may be possible, depending
+on complex optimization circuitry, for the compiler to figure
+out the value of X at compile time, in which case this initialization
+can be done by the loader, and requires no initialization code. It
+is not possible to document the precise conditions under which the
+optimizer can figure this out.
+
+Note that this the implementation of this restriction requires full
+code generation. If it is used in conjunction with "semantics only"
+checking, then some cases of violations may be missed.
+
@item No_Entry_Queue
@findex No_Entry_Queue
This restriction is a declaration that any protected entry compiled in
are present. With this restriction, the only other restriction identifiers
that can be used are those defined in the Ada 95 Reference Manual.
+@item No_Wide_Characters
+@findex No_Wide_Characters
+This restriction ensures at compile time that no uses of the types
+@code{Wide_Character} or @code{Wide_String} or corresponding wide
+wide types
+appear, and that no wide or wide wide string or character literals
+appear in the program (that is literals representing characters not in
+type @code{Character}.
+
@end table
@sp 1
is to be passed by copy rather than reference.
@item COBOL
COBOL
-@item CPP
+@item C_Plus_Plus (or CPP)
C++
@item Default
Treated the same as C
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.
-
+The result of this attribute is a string that identifies
+the object or component that denotes a given task. If a variable Var has a task
+type, the image for this task will have the form Var_XXXXXXXX, where the sufffix
+is the hexadecimal representation of the virtual address of the corresponding
+task control block. If the variable is an array of tasks, the image of each
+task will have the form of an indexed component indicating the position of a
+given task in the array, eg. Group(5)_XXXXXXX. If the task is a
+component of a record, the image of the task will have the form of a selected
+component. These rules are fully recursive, so that the image of a task that
+is a subcomponent of a composite object corresponds to the expression that
+designates this task.
+@noindent
+If a task is created by an allocator, its image depends on the context. If the
+allocator is part of an object declaration, the rules described above are used
+to construct its image, and this image is not affected by subsequent assignments. If the allocator appears within an expression, the image
+includes only the name of the task type.
+@noindent
+If the configuration pragma Discard_Names is present, or if the restriction
+No_Implicit_Heap_Allocation is in effect, the image reduces to
+the numeric suffix, that is to say the hexadecimal representation of the
+virtual address of the control block of the task.
@sp 1
@cartouche
@noindent
@noindent
@c SGI info:
@ignore
-Tasks map to IRIX threads, and the dispatching policy is as defied by
+Tasks map to IRIX threads, and the dispatching policy is as defined by
the IRIX implementation of threads.
@end ignore
The policy is the same as that of the underlying threads implementation.
@strong{101}. Implementation-defined queuing policies. See D.4(1).
@end cartouche
@noindent
-There are no implementation-defined queueing policies.
+There are no implementation-defined queuing policies.
@sp 1
@cartouche
result type is @code{False}. See G.2.1(13).
@end cartouche
@noindent
-Infinite and Nan values are produced as dictated by the IEEE
+Infinite and NaN values are produced as dictated by the IEEE
floating-point standard.
+Note that on machines that are not fully compliant with the IEEE
+floating-point standard, such as Alpha, the @option{-mieee} compiler flag
+must be used for achieving IEEE confirming behavior (although at the cost
+of a significant performance penalty), so infinite and NaN values are
+properly generated.
+
@sp 1
@cartouche
@noindent
@noindent
Then @code{Default_Stack_Size} can be defined in a global package, and
-modified as required. Any tasks requiring stack sizes different from the
+modified as required. Any tasks requiring stack sizes different from the
default can have an appropriate alternative reference in the pragma.
+You can also use the @code{-d} binder switch to modify the default stack
+size.
+
For access types, the @code{Storage_Size} clause specifies the maximum
space available for allocation of objects of the type. If this space is
exceeded then @code{Storage_Error} will be raised by an allocation attempt.
@cindex Component_Size Clause
@noindent
-Normally, the value specified in a component clause must be consistent
+Normally, the value specified in a component size clause must be consistent
with the subtype of the array component with regard to size and alignment.
In other words, the value specified must be at least equal to the size
of this subtype, and must be a multiple of the alignment value.
Of course access to the components of such an array is considerably
less efficient than if the natural component size of 32 is used.
+Note that there is no point in giving both a component size clause
+and a pragma Pack for the same array type. if such duplicate
+clauses are given, the pragma Pack will be ignored.
+
@node Bit_Order Clauses
@section Bit_Order Clauses
@cindex Bit_Order Clause
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.
-Packed bit arrays that are longer than 64 bits must always be placed
-on a storage unit (byte) boundary. Any component clause that does not
+For packed bit arrays that are longer than 64 bits, there are two
+cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
+including the important case of single bits or boolean values, then
+there are no limitations on placement of such components, and they
+may start and end at arbitrary bit boundaries.
+
+If the component size is not a power of 2 (e.g. 3 or 5), then
+an array of this type longer than 64 bits must always be placed on
+on a storage unit (byte) boundary and occupy an integral number
+of storage units (bytes). Any component clause that does not
meet this requirement will be rejected.
-The rules for other types are different for GNAT 3 and GNAT 5 versions
-(based on GCC 2 and GCC 3 respectively). In GNAT 5, larger components
-(other than packed arrays)
-may also be placed on arbitrary boundaries, so for example, the following
-is permitted:
+Any aliased component, or component of an aliased type, must
+have its normal alignment and size. A component clause that
+does not meet this requirement will be rejected.
+
+The tag field of a tagged type always occupies an address sized field at
+the start of the record. No component clause may attempt to overlay this
+tag. When a tagged type appears as a component, the tag field must have
+proper alignment
+
+In the case of a record extension T1, of a type T, no component clause applied
+to the type T1 can specify a storage location that would overlap the first
+T'Size bytes of the record.
+
+For all other component types, including non-bit-packed arrays,
+the component can be placed at an arbitrary bit boundary,
+so for example, the following is permitted:
@smallexample @c ada
type R is array (1 .. 10) of Boolean;
@end smallexample
@noindent
+Note: the above rules apply to recent releases of GNAT 5.
In GNAT 3, there are more severe restrictions on larger components.
For non-primitive types, including packed arrays with a size greater than
64 bits, component clauses must respect the alignment requirement of the
type, in particular, always starting on a byte boundary, and the length
must be a multiple of the storage unit.
-The following rules regarding tagged types are enforced in both GNAT 3 and
-GNAT 5:
-
-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
checks (at compile time if possible, generating a warning, or at execution
time with a run-time check) that the alignment is appropriate. If the
run-time check fails, then @code{Program_Error} is raised. This run-time
-check is suppressed if range checks are suppressed, or if
+check is suppressed if range checks are suppressed, or if the special GNAT
+check Alignment_Check is suppressed, or if
@code{pragma Restrictions (No_Elaboration_Code)} is in effect.
@findex Export
consistent with C@. This means that specifying convention C (for example)
has no effect.
-There are three exceptions to this general rule:
+There are four exceptions to this general rule:
@itemize @bullet
values generated by GNAT, the conventional value 1 will be used for True, but
when one of these values is read, any nonzero value is treated as True.
+@item Access types on OpenVMS
+For 64-bit OpenVMS systems, access types (other than those for unconstrained
+arrays) are 64-bits long. An exception to this rule is for the case of
+C-convention access types where there is no explicit size clause present (or
+inherited for derived types). In this case, GNAT chooses to make these
+pointers 32-bits, which provides an easier path for migration of 32-bit legacy
+code. size clause specifying 64-bits must be used to obtain a 64-bit pointer.
+
@end itemize
@node Determining the Representations chosen by GNAT
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
+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.
@code{Wide_String} and @code{Wide_Character} instead of @code{String}
and @code{Character}.
+@item Ada.Strings.Wide_Wide_Bounded (A.4.7)
+@itemx Ada.Strings.Wide_Wide_Fixed (A.4.7)
+@itemx Ada.Strings.Wide_Wide_Maps (A.4.7)
+@itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7)
+@itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7)
+These packages provide analogous capabilities to the corresponding
+packages without @samp{Wide_} in the name, but operate with the types
+@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
+of @code{String} and @code{Character}.
+
@item Ada.Synchronous_Task_Control (D.10)
This package provides some standard facilities for controlling task
communication in a synchronous manner.
This package is similar to @code{Ada.Text_IO.Streams}, except that the
types are @code{Wide_Character} and @code{Wide_String} instead of
@code{Character} and @code{String}.
+
+@item Ada.Wide_Wide_Text_IO (A.11)
+This package is similar to @code{Ada.Text_IO}, except that the external
+file supports wide character representations, and the internal types are
+@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
+and @code{String}. It contains generic subpackages listed next.
+
+@item Ada.Wide_Wide_Text_IO.Decimal_IO
+Provides input-output facilities for decimal fixed-point types
+
+@item Ada.Wide_Wide_Text_IO.Enumeration_IO
+Provides input-output facilities for enumeration types.
+
+@item Ada.Wide_Wide_Text_IO.Fixed_IO
+Provides input-output facilities for ordinary fixed-point types.
+
+@item Ada.Wide_Wide_Text_IO.Float_IO
+Provides input-output facilities for float types. The following
+predefined instantiations of this generic package are available:
+
+@table @code
+@item Short_Float
+@code{Short_Float_Wide_Wide_Text_IO}
+@item Float
+@code{Float_Wide_Wide_Text_IO}
+@item Long_Float
+@code{Long_Float_Wide_Wide_Text_IO}
+@end table
+
+@item Ada.Wide_Wide_Text_IO.Integer_IO
+Provides input-output facilities for integer types. The following
+predefined instantiations of this generic package are available:
+
+@table @code
+@item Short_Short_Integer
+@code{Ada.Short_Short_Integer_Wide_Wide_Text_IO}
+@item Short_Integer
+@code{Ada.Short_Integer_Wide_Wide_Text_IO}
+@item Integer
+@code{Ada.Integer_Wide_Wide_Text_IO}
+@item Long_Integer
+@code{Ada.Long_Integer_Wide_Wide_Text_IO}
+@item Long_Long_Integer
+@code{Ada.Long_Long_Integer_Wide_Wide_Text_IO}
+@end table
+
+@item Ada.Wide_Wide_Text_IO.Modular_IO
+Provides input-output facilities for modular (unsigned) types
+
+@item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3)
+This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
+external file supports wide character representations.
+
+@item Ada.Wide_Wide_Text_IO.Editing (F.3.4)
+This package is similar to @code{Ada.Text_IO.Editing}, except that the
+types are @code{Wide_Character} and @code{Wide_String} instead of
+@code{Character} and @code{String}.
+
+@item Ada.Wide_Wide_Text_IO.Streams (A.12.3)
+This package is similar to @code{Ada.Text_IO.Streams}, except that the
+types are @code{Wide_Character} and @code{Wide_String} instead of
+@code{Character} and @code{String}.
@end table
+
+
@node The Implementation of Standard I/O
@chapter The Implementation of Standard I/O
* Sequential_IO::
* Text_IO::
* Wide_Text_IO::
+* Wide_Wide_Text_IO::
* Stream_IO::
* Shared Files::
+* Filenames encoding::
* Open Modes::
* Operations on C Streams::
* Interfacing to C Streams::
@item
Ada.Text_IO.Complex_IO
@item
-Ada.Text_IO.Text_Streams,
+Ada.Text_IO.Text_Streams
@item
Ada.Wide_Text_IO
@item
-Ada.Wide_Text_IO.Complex_IO,
+Ada.Wide_Text_IO.Complex_IO
@item
Ada.Wide_Text_IO.Text_Streams
@item
+Ada.Wide_Wide_Text_IO
+@item
+Ada.Wide_Wide_Text_IO.Complex_IO
+@item
+Ada.Wide_Wide_Text_IO.Text_Streams
+@item
Ada.Stream_IO
@item
Ada.Sequential_IO
@end itemize
@noindent
-There is no internal buffering of any kind at the Ada library level. The
-only buffering is that provided at the system level in the
-implementation of the C library routines that support streams. This
-facilitates shared use of these streams by mixed language programs.
+There is no internal buffering of any kind at the Ada library level. The only
+buffering is that provided at the system level in the implementation of the
+library routines that support streams. This facilitates shared use of these
+streams by mixed language programs. Note though that system level buffering is
+explicitly enabled at elaboration of the standard I/O packages and that can
+have an impact on mixed language programs, in particular those using I/O before
+calling the Ada elaboration routine (e.g. adainit). It is recommended to call
+the Ada elaboration routine before performing any I/O or when impractical,
+flush the common I/O streams and in particular Standard_Output before
+elaborating the Ada code.
@node FORM Strings
@section FORM Strings
@smallexample
SHARED=[YES|NO]
-WCEM=[n|h|u|s\e]
+WCEM=[n|h|u|s|e|8|b]
@end smallexample
@noindent
files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended
@code{Wide_Text_IO} functionality for unbounded wide strings.
+The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
+files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended
+@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
+
@node Wide_Text_IO
@section Wide_Text_IO
e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
is only used for wide characters with a code greater than @code{16#FF#}.
+Note that brackets coding is not normally used in the context of
+Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
+a portable way of encoding source files. In the context of Wide_Text_IO
+or Wide_Wide_Text_IO, it can only be used if the file does not contain
+any instance of the left bracket character other than to encode wide
+character values using the brackets encoding method. In practice it is
+expected that some standard wide character encoding method such
+as UTF-8 will be used for text input output.
+
+If brackets notation is used, then any occurrence of a left bracket
+in the input file which is not the start of a valid wide character
+sequence will cause Constraint_Error to be raised. It is possible to
+encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO
+input will interpret this as a left bracket.
+
+However, when a left bracket is output, it will be output as a left bracket
+and not as ["5B"]. We make this decision because for normal use of
+Wide_Text_IO for outputting messages, it is unpleasant to clobber left
+brackets. For example, if we write:
+
+@smallexample
+ Put_Line ("Start of output [first run]");
+@end smallexample
+
+@noindent
+we really do not want to have the left bracket in this message clobbered so
+that the output reads:
+
+@smallexample
+ Start of output ["5B"]first run]
+@end smallexample
+
+@noindent
+In practice brackets encoding is reasonably useful for normal Put_Line use
+since we won't get confused between left brackets and wide character
+sequences in the output. But for input, or when files are written out
+and read back in, it really makes better sense to use one of the standard
+encoding methods such as UTF-8.
+
@end table
@noindent
-For the coding schemes other than Hex and Brackets encoding,
+For the coding schemes other than UTF-8, Hex, or Brackets encoding,
not all wide character
values can be represented. An attempt to output a character that cannot
be represented using the encoding scheme for the file causes
@code{False}. Similarly, the end of file indication is not sticky, so
it is possible to read beyond an end of file.
+@node Wide_Wide_Text_IO
+@section Wide_Wide_Text_IO
+
+@noindent
+@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
+both input and output files may contain special sequences that represent
+wide wide character values. The encoding scheme for a given file may be
+specified using a FORM parameter:
+
+@smallexample
+WCEM=@var{x}
+@end smallexample
+
+@noindent
+as part of the FORM string (WCEM = wide character encoding method),
+where @var{x} is one of the following characters
+
+@table @samp
+@item h
+Hex ESC encoding
+@item u
+Upper half encoding
+@item s
+Shift-JIS encoding
+@item e
+EUC Encoding
+@item 8
+UTF-8 encoding
+@item b
+Brackets encoding
+@end table
+
+@noindent
+The encoding methods match those that
+can be used in a source
+program, but there is no requirement that the encoding method used for
+the source program be the same as the encoding method used for files,
+and different files may use different encoding methods.
+
+The default encoding method for the standard files, and for opened files
+for which no WCEM parameter is given in the FORM string matches the
+wide character encoding specified for the main program (the default
+being brackets encoding if no coding method was specified with -gnatW).
+
+@table @asis
+
+@item UTF-8 Coding
+A wide character is represented using
+UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
+10646-1/Am.2. Depending on the character value, the representation
+is a one, two, three, or four byte sequence:
+
+@smallexample
+16#000000#-16#00007f#: 2#0xxxxxxx#
+16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
+16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
+16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
+@end smallexample
+
+@noindent
+where the xxx bits correspond to the left-padded bits of the
+21-bit character value. Note that all lower half ASCII characters
+are represented as ASCII bytes and all upper half characters and
+other wide characters are represented as sequences of upper-half
+characters.
+
+@item Brackets Coding
+In this encoding, a wide wide character is represented by the following eight
+character sequence if is in wide character range
+
+@smallexample
+[ " a b c d " ]
+@end smallexample
+
+and by the following ten character sequence if not
+
+@smallexample
+[ " a b c d e f " ]
+@end smallexample
+
+@noindent
+where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
+are the four or six hexadecimal
+characters (using uppercase letters) of the wide wide character code. For
+example, @code{["01A345"]} is used to represent the wide wide character
+with code @code{16#01A345#}.
+
+This scheme is compatible with use of the full Wide_Wide_Character set.
+On input, brackets coding can also be used for upper half characters,
+e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
+is only used for wide characters with a code greater than @code{16#FF#}.
+
+@end table
+
+@noindent
+If is also possible to use the other Wide_Character encoding methods,
+such as Shift-JIS, but the other schemes cannot support the full range
+of wide wide characters.
+An attempt to output a character that cannot
+be represented using the encoding scheme for the file causes
+Constraint_Error to be raised. An invalid wide character sequence on
+input also causes Constraint_Error to be raised.
+
+@menu
+* Wide_Wide_Text_IO Stream Pointer Positioning::
+* Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
+@end menu
+
+@node Wide_Wide_Text_IO Stream Pointer Positioning
+@subsection Stream Pointer Positioning
+
+@noindent
+@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
+of stream pointer positioning (@pxref{Text_IO}). There is one additional
+case:
+
+If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
+normal lower ASCII set (i.e.@: a character in the range:
+
+@smallexample @c ada
+Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
+@end smallexample
+
+@noindent
+then although the logical position of the file pointer is unchanged by
+the @code{Look_Ahead} call, the stream is physically positioned past the
+wide character sequence. Again this is to avoid the need for buffering
+or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
+indication that this situation has occurred so that this is not visible
+to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
+can be observed if the wide text file shares a stream with another file.
+
+@node Wide_Wide_Text_IO Reading and Writing Non-Regular Files
+@subsection Reading and Writing Non-Regular Files
+
+@noindent
+As in the case of Text_IO, when a non-regular file is read, it is
+assumed that the file contains no page marks (any form characters are
+treated as data characters), and @code{End_Of_Page} always returns
+@code{False}. Similarly, the end of file indication is not sticky, so
+it is possible to read beyond an end of file.
+
@node Stream_IO
@section Stream_IO
@samp{shared=yes} is specified, it is preferable in Ada 95 to use Stream_IO
for this purpose (using the stream attributes)
+@node Filenames encoding
+@section Filenames encoding
+
+@noindent
+An encoding form parameter can be used to specify the filename
+encoding @samp{encoding=@var{xxx}}.
+
+@itemize @bullet
+@item
+If the form parameter @samp{encoding=utf8} appears in the form string, the
+filename must be encoded in UTF-8.
+
+@item
+If the form parameter @samp{encoding=8bits} appears in the form
+string, the filename must be a standard 8bits string.
+@end itemize
+
+In the absence of a @samp{encoding=@var{xxx}} form parameter, the
+value UTF-8 is used. This encoding form parameter is only supported on
+the Windows platform. On the other Operating Systems the runtime is
+supporting UTF-8 natively.
+
@node Open Modes
@section Open Modes
Form : in String := "");
end Ada.Wide_Text_IO.C_Streams;
+ with Interfaces.C_Streams;
+ package Ada.Wide_Wide_Text_IO.C_Streams is
+ function C_Stream (F : File_Type)
+ return Interfaces.C_Streams.FILEs;
+ procedure Open
+ (File : in out File_Type;
+ Mode : in File_Mode;
+ C_Stream : in Interfaces.C_Streams.FILEs;
+ Form : in String := "");
+ end Ada.Wide_Wide_Text_IO.C_Streams;
+
with Interfaces.C_Streams;
package Ada.Stream_IO.C_Streams is
function C_Stream (F : File_Type)
@end smallexample
@noindent
-In each of these five packages, the @code{C_Stream} function obtains the
+In each of these six packages, the @code{C_Stream} function obtains the
@code{FILE} pointer from a currently opened Ada file. It is then
possible to use the @code{Interfaces.C_Streams} package to operate on
this stream, or the stream can be passed to a C program which can
* Ada.Characters.Latin_9 (a-chlat9.ads)::
* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
+* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
+* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
* Ada.Command_Line.Remove (a-colire.ads)::
* Ada.Command_Line.Environment (a-colien.ads)::
* Ada.Direct_IO.C_Streams (a-diocst.ads)::
* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
* Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
+* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
* Ada.Text_IO.C_Streams (a-tiocst.ads)::
* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
+* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
+* GNAT.Altivec (g-altive.ads)::
+* GNAT.Altivec.Conversions (g-altcon.ads)::
+* GNAT.Altivec.Vector_Operations (g-alveop.ads)::
+* GNAT.Altivec.Vector_Types (g-alvety.ads)::
+* GNAT.Altivec.Vector_Views (g-alvevi.ads)::
* GNAT.Array_Split (g-arrspl.ads)::
* GNAT.AWK (g-awk.ads)::
* GNAT.Bounded_Buffers (g-boubuf.ads)::
* GNAT.Bubble_Sort (g-bubsor.ads)::
* GNAT.Bubble_Sort_A (g-busora.ads)::
* GNAT.Bubble_Sort_G (g-busorg.ads)::
+* GNAT.Byte_Swapping (g-bytswa.ads)::
* GNAT.Calendar (g-calend.ads)::
* GNAT.Calendar.Time_IO (g-catiio.ads)::
* GNAT.CRC32 (g-crc32.ads)::
* GNAT.Memory_Dump (g-memdum.ads)::
* GNAT.Most_Recent_Exception (g-moreex.ads)::
* GNAT.OS_Lib (g-os_lib.ads)::
-* GNAT.Perfect_Hash.Generators (g-pehage.ads)::
+* GNAT.Perfect_Hash_Generators (g-pehage.ads)::
* GNAT.Regexp (g-regexp.ads)::
* GNAT.Registry (g-regist.ads)::
* GNAT.Regpat (g-regpat.ads)::
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
* GNAT.Semaphores (g-semaph.ads)::
+* GNAT.SHA1 (g-sha1.ads)::
* GNAT.Signals (g-signal.ads)::
* GNAT.Sockets (g-socket.ads)::
* GNAT.Source_Info (g-souinf.ads)::
* GNAT.Spitbol.Table_VString (g-sptavs.ads)::
* GNAT.Strings (g-string.ads)::
* GNAT.String_Split (g-strspl.ads)::
+* GNAT.UTF_32 (g-utf_32.ads)::
* GNAT.Table (g-table.ads)::
* GNAT.Task_Lock (g-tasloc.ads)::
* GNAT.Threads (g-thread.ads)::
* GNAT.Traceback (g-traceb.ads)::
* GNAT.Traceback.Symbolic (g-trasym.ads)::
* GNAT.Wide_String_Split (g-wistsp.ads)::
+* GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
* Interfaces.C.Extensions (i-cexten.ads)::
* Interfaces.C.Streams (i-cstrea.ads)::
* Interfaces.CPP (i-cpp.ads)::
is specifically authorized by the Ada Reference Manual
(RM A.3(27)).
+@node Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)
+@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
+@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
+@cindex Latin_1 constants for Wide_Wide_Character
+
+@noindent
+This child of @code{Ada.Characters}
+provides a set of definitions corresponding to those in the
+RM-defined package @code{Ada.Characters.Latin_1} but with the
+types of the constants being @code{Wide_Wide_Character}
+instead of @code{Character}. The provision of such a package
+is specifically authorized by the Ada Reference Manual
+(RM A.3(27)).
+
+@node Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)
+@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
+@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
+@cindex Latin_9 constants for Wide_Wide_Character
+
+@noindent
+This child of @code{Ada.Characters}
+provides a set of definitions corresponding to those in the
+GNAT defined package @code{Ada.Characters.Latin_9} but with the
+types of the constants being @code{Wide_Wide_Character}
+instead of @code{Character}. The provision of such a package
+is specifically authorized by the Ada Reference Manual
+(RM A.3(27)).
+
@node Ada.Command_Line.Remove (a-colire.ads)
@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
wide strings, avoiding the necessity for an intermediate operation
with ordinary wide strings.
+@node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
+@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
+@cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
+@cindex @code{Unbounded_Wide_Wide_String}, IO support
+@cindex @code{Text_IO}, extensions for unbounded wide wide strings
+
+@noindent
+This package provides subprograms for Text_IO for unbounded
+wide wide strings, avoiding the necessity for an intermediate operation
+with ordinary wide wide strings.
+
@node Ada.Text_IO.C_Streams (a-tiocst.ads)
@section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
@cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
+@node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
+@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
+@cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
+@cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO}
+
+@noindent
+This package provides subprograms that allow interfacing between
+C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
+extracted from a file opened on the Ada side, and an Ada file
+can be constructed from a stream opened on the C side.
+
+@node GNAT.Altivec (g-altive.ads)
+@section @code{GNAT.Altivec} (@file{g-altive.ads})
+@cindex @code{GNAT.Altivec} (@file{g-altive.ads})
+@cindex AltiVec
+
+@noindent
+This is the root package of the GNAT AltiVec binding. It provides
+definitions of constants and types common to all the versions of the
+binding.
+
+@node GNAT.Altivec.Conversions (g-altcon.ads)
+@section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
+@cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
+@cindex AltiVec
+
+@noindent
+This package provides the Vector/View conversion routines.
+
+@node GNAT.Altivec.Vector_Operations (g-alveop.ads)
+@section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
+@cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
+@cindex AltiVec
+
+@noindent
+This package exposes the Ada interface to the AltiVec operations on
+vector objects. A soft emulation is included by default in the GNAT
+library. The hard binding is provided as a separate package. This unit
+is common to both bindings.
+
+@node GNAT.Altivec.Vector_Types (g-alvety.ads)
+@section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
+@cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
+@cindex AltiVec
+
+@noindent
+This package exposes the various vector types part of the Ada binding
+to AltiVec facilities.
+
+@node GNAT.Altivec.Vector_Views (g-alvevi.ads)
+@section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
+@cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
+@cindex AltiVec
+
+@noindent
+This package provides public 'View' data types from/to which private
+vector representations can be converted via
+GNAT.Altivec.Conversions. This allows convenient access to individual
+vector elements and provides a simple way to initialize vector
+objects.
+
@node GNAT.Array_Split (g-arrspl.ads)
@section @code{GNAT.Array_Split} (@file{g-arrspl.ads})
@cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads})
if the procedures can be inlined, at the expense of duplicating code for
multiple instantiations.
+@node GNAT.Byte_Swapping (g-bytswa.ads)
+@section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
+@cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
+@cindex Byte swapping
+@cindex Endian
+
+@noindent
+General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
+Machine-specific implementations are available in some cases.
+
@node GNAT.Calendar (g-calend.ads)
@section @code{GNAT.Calendar} (@file{g-calend.ads})
@cindex @code{GNAT.Calendar} (@file{g-calend.ads})
including a portable spawn procedure, and access to environment variables
and error return codes.
-@node GNAT.Perfect_Hash.Generators (g-pehage.ads)
-@section @code{GNAT.Perfect_Hash.Generators} (@file{g-pehage.ads})
-@cindex @code{GNAT.Perfect_Hash.Generators} (@file{g-pehage.ads})
+@node GNAT.Perfect_Hash_Generators (g-pehage.ads)
+@section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
+@cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
@cindex Hash functions
@noindent
probe (perfect property). The hash table size corresponds to the exact
size of the key set and no larger (minimal property). The key set has to
be know in advance (static property). The hash functions are also order
-preservering. If w2 is inserted after w1 in the generator, their
+preserving. If w2 is inserted after w1 in the generator, their
hashcode are in the same order. These hashing functions are very
convenient for use with realtime applications.
@noindent
Provides classic counting and binary semaphores using protected types.
+@node GNAT.SHA1 (g-sha1.ads)
+@section @code{GNAT.SHA1} (@file{g-sha1.ads})
+@cindex @code{GNAT.SHA1} (@file{g-sha1.ads})
+@cindex Secure Hash Algorithm SHA-1
+
+@noindent
+Implements the SHA-1 Secure Hash Algorithm as described in RFC 3174.
+
@node GNAT.Signals (g-signal.ads)
@section @code{GNAT.Signals} (@file{g-signal.ads})
@cindex @code{GNAT.Signals} (@file{g-signal.ads})
@cindex String splitter
@noindent
-Useful string-manipulation routines: given a set of separators, split
+Useful string manipulation routines: given a set of separators, split
a string wherever the separators appear, and provide direct access
to the resulting slices. This package is instantiated from
@code{GNAT.Array_Split}.
+@node GNAT.UTF_32 (g-utf_32.ads)
+@section @code{GNAT.UTF_32} (@file{g-table.ads})
+@cindex @code{GNAT.UTF_32} (@file{g-table.ads})
+@cindex Wide character codes
+
+@noindent
+This is a package intended to be used in conjunction with the
+@code{Wide_Character} type in Ada 95 and the
+@code{Wide_Wide_Character} type in Ada 2005 (available
+in @code{GNAT} in Ada 2005 mode). This package contains
+Unicode categorization routines, as well as lexical
+categorization routines corresponding to the Ada 2005
+lexical rules for identifiers and strings, and also a
+lower case to upper case fold routine corresponding to
+the Ada 2005 rules for identifier equivalence.
+
@node GNAT.Table (g-table.ads)
@section @code{GNAT.Table} (@file{g-table.ads})
@cindex @code{GNAT.Table} (@file{g-table.ads})
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.
+routines, compatibility with the Ada tasking run-time is provided.
@node GNAT.Traceback (g-traceb.ads)
@section @code{GNAT.Traceback} (@file{g-traceb.ads})
@cindex Wide_String splitter
@noindent
-Useful wide_string-manipulation routines: given a set of separators, split
-a wide_string wherever the separators appear, and provide direct access
+Useful wide string manipulation routines: given a set of separators, split
+a wide string wherever the separators appear, and provide direct access
+to the resulting slices. This package is instantiated from
+@code{GNAT.Array_Split}.
+
+@node GNAT.Wide_Wide_String_Split (g-zistsp.ads)
+@section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
+@cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
+@cindex Wide_Wide_String splitter
+
+@noindent
+Useful wide wide string manipulation routines: given a set of separators, split
+a wide wide string wherever the separators appear, and provide direct access
to the resulting slices. This package is instantiated from
@code{GNAT.Array_Split}.
@node System.Partition_Interface (s-parint.ads)
@section @code{System.Partition_Interface} (@file{s-parint.ads})
@cindex @code{System.Partition_Interface} (@file{s-parint.ads})
-@cindex Partition intefacing functions
+@cindex Partition interfacing functions
@noindent
This package provides facilities for partition interfacing. It
@noindent
This package provides routines for converting between
-wide characters and a representation as a value of type
+wide and wide wide characters and a representation as a value of type
@code{Standard.String}, using a specified wide character
encoding method. It uses definitions in
package @code{System.Wch_Con}.
generator tool is supplied with GNAT though.
Using these pragmas it is possible to achieve complete
-inter-operability between Ada tagged types and C class definitions.
+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})
+@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
+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})
+Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
+for backward compatibility but its functionality is available
+using pragma @code{Import} with @code{Convention} = @code{CPP}.
+
+@item pragma CPP_Constructor ([Entity =>] @var{local_NAME})
This pragma identifies an imported function (imported in the usual way
with pragma @code{Import}) as corresponding to a C++ constructor.
-
-@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
* GNAT Implementation of Tasking::
* GNAT Implementation of Shared Passive Packages::
* Code Generation for Array Aggregates::
+* The Size of Discriminated Records with Default Discriminants::
+* Strict Conformance to the Ada 95 Reference Manual::
@end menu
@node Machine Code Insertions
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.
+Generally it is strongly advisable to use Volatile for any ASM statement
+that is missing either input or output operands, or when two or more ASM
+statements appear in sequence, to avoid unwanted optimizations. A warning
+is generated if this advice is not followed.
The @code{Asm} subprograms may be used in two ways. First the procedure
forms can be used anywhere a procedure call would be valid, and
@menu
* Static constant aggregates with static bounds::
-* Constant aggregates with an unconstrained nominal types::
+* Constant aggregates with unconstrained nominal types::
* Aggregates with static bounds::
* Aggregates with non-static bounds::
* Aggregates in assignment statements::
@end menu
@noindent
-Aggregate have a rich syntax and allow the user to specify the values of
+Aggregates have a rich syntax and allow the user to specify the values of
complex data structures by means of a single construct. As a result, the
code generated for aggregates can be quite complex and involve loops, case
statements and multiple assignments. In the simplest cases, however, the
compiler will recognize aggregates whose components and constraints are
fully static, and in those cases the compiler will generate little or no
executable code. The following is an outline of the code that GNAT generates
-for various aggregate constructs. For further details, the user will find it
+for various aggregate constructs. For further details, you will find it
useful to examine the output produced by the -gnatG flag to see the expanded
-source that is input to the code generator. The user will also want to examine
+source that is input to the code generator. You may also want to examine
the assembly code generated at various levels of optimization.
The code generated for aggregates depends on the context, the component values,
For the declarations:
@smallexample @c ada
type One_Dim is array (1..10) of integer;
- ar0 : constant One_Dim := ( 1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
+ ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
@end smallexample
@noindent
The same is true for constant aggregates with named associations:
@smallexample @c ada
- Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1=> 1);
+ Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
Cr3 : constant One_Dim := (others => 7777);
@end smallexample
Zero2: constant two_dim := (others => (others => 0));
@end smallexample
-@node Constant aggregates with an unconstrained nominal types
-@subsection Constant aggregates with an unconstrained nominal types
+@node Constant aggregates with unconstrained nominal types
+@subsection Constant aggregates with unconstrained nominal types
@noindent
In such cases the aggregate itself establishes the subtype, so that
object. The declarations
@smallexample @c ada
- Cr_Var1 : One_Dim := (2, 5, 7, 11);
+ Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
Cr_Var2 : One_Dim := (others > -1);
@end smallexample
a temporary (created either by the front-end or the code generator) and then
that temporary will be copied onto the target.
+
+@node The Size of Discriminated Records with Default Discriminants
+@section The Size of Discriminated Records with Default Discriminants
+
+@noindent
+If a discriminated type @code{T} has discriminants with default values, it is
+possible to declare an object of this type without providing an explicit
+constraint:
+
+@smallexample @c ada
+@group
+type Size is range 1..100;
+
+type Rec (D : Size := 15) is record
+ Name : String (1..D);
+end T;
+
+Word : Rec;
+@end group
+@end smallexample
+
+@noindent
+Such an object is said to be @emph{unconstrained}.
+The discriminant of the object
+can be modified by a full assignment to the object, as long as it preserves the
+relation between the value of the discriminant, and the value of the components
+that depend on it:
+
+@smallexample @c ada
+@group
+Word := (3, "yes");
+
+Word := (5, "maybe");
+
+Word := (5, "no"); -- raises Constraint_Error
+@end group
+@end smallexample
+
+@noindent
+In order to support this behavior efficiently, an unconstrained object is
+given the maximum size that any value of the type requires. In the case
+above, @code{Word} has storage for the discriminant and for
+a @code{String} of length 100.
+It is important to note that unconstrained objects do not require dynamic
+allocation. It would be an improper implementation to place on the heap those
+components whose size depends on discriminants. (This improper implementation
+was used by some Ada83 compilers, where the @code{Name} component above
+would have
+been stored as a pointer to a dynamic string). Following the principle that
+dynamic storage management should never be introduced implicitly,
+an Ada95 compiler should reserve the full size for an unconstrained declared
+object, and place it on the stack.
+
+This maximum size approach
+has been a source of surprise to some users, who expect the default
+values of the discriminants to determine the size reserved for an
+unconstrained object: ``If the default is 15, why should the object occupy
+a larger size?''
+The answer, of course, is that the discriminant may be later modified,
+and its full range of values must be taken into account. This is why the
+declaration:
+
+@smallexample
+@group
+type Rec (D : Positive := 15) is record
+ Name : String (1..D);
+end record;
+
+Too_Large : Rec;
+@end group
+@end smallexample
+
+@noindent
+is flagged by the compiler with a warning:
+an attempt to create @code{Too_Large} will raise @code{Storage_Error},
+because the required size includes @code{Positive'Last}
+bytes. As the first example indicates, the proper approach is to declare an
+index type of ``reasonable'' range so that unconstrained objects are not too
+large.
+
+One final wrinkle: if the object is declared to be @code{aliased}, or if it is
+created in the heap by means of an allocator, then it is @emph{not}
+unconstrained:
+it is constrained by the default values of the discriminants, and those values
+cannot be modified by full assignment. This is because in the presence of
+aliasing all views of the object (which may be manipulated by different tasks,
+say) must be consistent, so it is imperative that the object, once created,
+remain invariant.
+
+@node Strict Conformance to the Ada 95 Reference Manual
+@section Strict Conformance to the Ada 95 Reference Manual
+
+@noindent
+The dynamic semantics defined by the Ada 95 Reference Manual impose a set of
+run-time checks to be generated. By default, the GNAT compiler will insert many
+run-time checks into the compiled code, including most of those required by the
+Ada 95 Reference Manual. However, there are three checks that are not enabled
+in the default mode for efficiency reasons: arithmetic overflow checking for
+integer operations (including division by zero), checks for access before
+elaboration on subprogram calls, and stack overflow checking (most operating
+systems do not perform this check by default).
+
+Strict conformance to the Ada 95 Reference Manual can be achieved by adding
+three compiler options for overflow checking for integer operations
+(@option{-gnato}), dynamic checks for access-before-elaboration on subprogram
+calls and generic instantiations (@option{-gnatE}), and stack overflow
+checking (@option{-fstack-check}).
+
+Note that the result of a floating point arithmetic operation in overflow and
+invalid situations, when the @code{Machine_Overflows} attribute of the result
+type is @code{False}, is to generate IEEE NaN and infinite values. This is the
+case for machines compliant with the IEEE floating-point standard, but on
+machines that are not fully compliant with this standard, such as Alpha, the
+@option{-mieee} compiler flag must be used for achieving IEEE confirming
+behavior (although at the cost of a significant performance penalty), so
+infinite and and NaN values are properly generated.
+
+
@node Project File Reference
@chapter Project File Reference
Expression must be a path name. The attribute defines the
directory in which the sources of the interfaces of a Stand-alone Library will
be copied. The directory must exist, must be distinct from the project's
-object directory and source directories, and must be writable.
+object directory and source directories of all projects in the project tree,
+and must be writable.
+
+@item Library_Src_Dir
+Expression must be a path name. The attribute defines the
+directory in which the ALI files of a Library will
+be copied. The directory must exist, must be distinct from the project's
+object directory and source directories of all projects in the project tree,
+and must be writable.
+
+@item Library_Symbol_File
+Expression must be a single string. Its value is the single file name of a
+symbol file to be created when building a stand-alone library when the
+symbol policy is either "compliant", "controlled" or "restricted",
+on platforms that support symbol control, such as VMS.
+
+@item Library_Reference_Symbol_File
+Expression must be a single string. Its value is the single file name of a
+reference symbol file that is read when the symbol policy is either
+"compliant" or "controlled", on platforms that support symbol control,
+such as VMS, when building a stand-alone library.
+
+@item Library_Symbol_Policy
+Expression must be a single string. Its case-insensitive value can only be
+"autonomous", "default", "compliant", "controlled" or "restricted".
+
+This attribute is not taken into account on all platforms. It controls the
+policy for exported symbols and, on some platforms (like VMS) that have the
+notions of major and minor IDs built in the library files, it controls
+the setting of these IDs.
+
+"autonomous" or "default": exported symbols are not controlled.
+
+"compliant": if attribute Library_Reference_Symbol_File is not defined, then
+it is equivalent to policy "autonomous". If there are exported symbols in
+the reference symbol file that are not in the object files of the interfaces,
+the major ID of the library is increased. If there are symbols in the
+object files of the interfaces that are not in the reference symbol file,
+these symbols are put at the end of the list in the newly created symbol file
+and the minor ID is increased.
+
+"controlled": the attribute Library_Reference_Symbol_File must be defined.
+The library will fail to build if the exported symbols in the object files of
+the interfaces do not match exactly the symbol in the symbol file.
+
+"restricted": The attribute Library_Symbol_File must be defined. The library
+will fail to build if there are symbols in the symbol file that are not in
+the exported symbols of the object files of the interfaces. Additional symbols
+in the object files are not added to the symbol file.
@item Main
Expression must be a list of strings that are legal file names.
If the gnatmake command does not include explicit file names, the executables
that are built correspond to the files specified by this attribute.
+@item Externally_Built
+Expression must be a single string. Its value must be either "true" of "false",
+case-insensitive. The default is "false". When the value of this attribute is
+"true", no attempt is made to compile the sources or to build the library,
+when the project is a library project.
+
@item Main_Language
This is a simple attribute. Its value is a string that specifies the
language of the main program.
domain is a set of language names. Its range is a string list that
specifies the compilation options to be used when compiling a component
written in that language, for which no file-specific switches have been
-specified..
+specified.
@item Switches
This is an associative array attribute. Its domain is
a set of file names. Its range is a string list that specifies the
compilation options to be used when compiling the named file. If a file
is not specified in the Switches attribute, it is compiled with the
-settings specified by Default_Switches.
+options specified by Default_Switches of its language, if defined.
@item Local_Configuration_Pragmas.
This is a simple attribute, whose
value is a path name that designates a file containing configuration pragmas
to be used for all invocations of the compiler for immediate sources of the
project.
-
-@item Executable
-This is an associative array attribute. Its domain is
-a set of main source file names. Its range is a simple string that specifies
-the executable file name to be used when linking the specified main source.
-If a main source is not specified in the Executable attribute, the executable
-file name is deducted from the main source file name.
@end table
@subsection package Builder
@table @code
@item Default_Switches
-As above.
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when building a main
+written in that language, for which no file-specific switches have been
+specified.
@item Switches
-As above.
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when building the named main file. If a main file
+is not specified in the Switches attribute, it is built with the
+options specified by Default_Switches of its language, if defined.
@item Global_Configuration_Pragmas
This is a simple attribute, whose
to be used in every build of an executable. If both local and global
configuration pragmas are specified, a compilation makes use of both sets.
+
@item Executable
-This is an associative array attribute, defined over
-compilation unit names. The image is a string that is the name of the
-executable file corresponding to the main source file index.
+This is an associative array attribute. Its domain is
+a set of main source file names. Its range is a simple string that specifies
+the executable file name to be used when linking the specified main source.
+If a main source is not specified in the Executable attribute, the executable
+file name is deducted from the main source file name.
This attribute has no effect if its value is the empty string.
@item Executable_Suffix
-This is a simple attribute whose value is a suffix to be added to
+This is a simple attribute whose value is the suffix to be added to
the executables that don't have an attribute Executable specified.
@end table
@table @code
@item Switches
-As above.
+This is a single attribute with a string list value. Each non empty string
+in the list is an option when invoking @code{gnatls}.
@end table
@subsection package Binder
@table @code
@item Default_Switches
-As above.
-@item Switches
-As above.
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when binding a main
+written in that language, for which no file-specific switches have been
+specified.
+
+@item Switches
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when binding the named main file. If a main file
+is not specified in the Switches attribute, it is bound with the
+options specified by Default_Switches of its language, if defined.
@end table
@subsection package Linker
@table @code
@item Default_Switches
-As above
-@item Switches
-As above.
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when linking a main
+written in that language, for which no file-specific switches have been
+specified.
+
+@item Switches
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when linking the named main file. If a main file
+is not specified in the Switches attribute, it is linked with the
+options specified by Default_Switches of its language, if defined.
+
+@item Linker_Options
+This is a string list attribute. Its value specifies additional options that
+be given to the linker when linking an executable. This attribute is not
+used in the main project, only in projects imported directly or indirectly.
+
@end table
@subsection package Cross_Reference
@table @code
@item Default_Switches
-As above.
-@item Switches
-As above.
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when calling @command{gnatxref} on a source
+written in that language, for which no file-specific switches have been
+specified.
+
+@item Switches
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when calling @command{gnatxref} on the named main source.
+If a source is not specified in the Switches attribute, @command{gnatxref} will
+be called with the options specified by Default_Switches of its language,
+if defined.
@end table
@subsection package Finder
@table @code
@item Default_Switches
-As above.
-@item Switches
-As above.
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when calling @command{gnatfind} on a source
+written in that language, for which no file-specific switches have been
+specified.
+
+@item Switches
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when calling @command{gnatfind} on the named main source.
+If a source is not specified in the Switches attribute, @command{gnatfind} will
+be called with the options specified by Default_Switches of its language,
+if defined.
@end table
@subsection package Pretty_Printer
@table @code
@item Default_switches
-As above.
-@item Switches
-As above.
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when calling @command{gnatpp} on a source
+written in that language, for which no file-specific switches have been
+specified.
+
+@item Switches
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when calling @command{gnatpp} on the named main source.
+If a source is not specified in the Switches attribute, @command{gnatpp} will
+be called with the options specified by Default_Switches of its language,
+if defined.
+@end table
+
+@subsection package gnatstub
+
+@noindent
+The attributes of package @code{gnatstub}
+specify the tool options to be used
+when invoking the tool @command{gnatstub}.
+The following attributes apply to package @code{gnatstub}:
+
+@table @code
+@item Default_switches
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when calling @command{gnatstub} on a source
+written in that language, for which no file-specific switches have been
+specified.
+
+@item Switches
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when calling @command{gnatstub} on the named main source.
+If a source is not specified in the Switches attribute, @command{gnatpp} will
+be called with the options specified by Default_Switches of its language,
+if defined.
+@end table
+
+@subsection package Eliminate
+
+@noindent
+The attributes of package @code{Eliminate}
+specify the tool options to be used
+when invoking the tool @command{gnatelim}.
+The following attributes apply to package @code{Eliminate}:
+
+@table @code
+@item Default_switches
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when calling @command{gnatelim} on a source
+written in that language, for which no file-specific switches have been
+specified.
+
+@item Switches
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when calling @command{gnatelim} on the named main source.
+If a source is not specified in the Switches attribute, @command{gnatelim} will
+be called with the options specified by Default_Switches of its language,
+if defined.
+@end table
+
+@subsection package Metrics
+
+@noindent
+The attributes of package @code{Metrics}
+specify the tool options to be used
+when invoking the tool @command{gnatmetric}.
+The following attributes apply to package @code{Metrics}:
+
+@table @code
+@item Default_switches
+This is an associative array attribute. Its
+domain is a set of language names. Its range is a string list that
+specifies options to be used when calling @command{gnatmetric} on a source
+written in that language, for which no file-specific switches have been
+specified.
+
+@item Switches
+This is an associative array attribute. Its domain is
+a set of file names. Its range is a string list that specifies
+options to be used when calling @command{gnatmetric} on the named main source.
+If a source is not specified in the Switches attribute, @command{gnatmetric}
+will be called with the options specified by Default_Switches of its language,
+if defined.
@end table
@subsection package IDE
predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
@item VCS_Kind
-This is a simple atribute. Is value is a string used to specify the
+This is a simple attribute. Its value is a string used to specify the
Version Control System (VCS) to be used for this project, e.g CVS, RCS
ClearCase or Perforce.
attributes and variables in the project are then used to establish the
environment in which the gnat tool will execute.
+@node Obsolescent Features
+@chapter Obsolescent Features
+
+@noindent
+This chapter describes features that are provided by GNAT, but are
+considered obsolescent since there are preferred ways of achieving
+the same effect. These features are provided solely for historical
+compatibility purposes.
+
+@menu
+* pragma No_Run_Time::
+* pragma Ravenscar::
+* pragma Restricted_Run_Time::
+@end menu
+
+@node pragma No_Run_Time
+@section pragma No_Run_Time
+
+The pragma @code{No_Run_Time} is used to achieve an affect similar
+to the use of the "Zero Foot Print" configurable run time, but without
+requiring a specially configured run time. The result of using this
+pragma, which must be used for all units in a partition, is to restrict
+the use of any language features requiring run-time support code. The
+preferred usage is to use an appropriately configured run-time that
+includes just those features that are to be made accessible.
+
+@node pragma Ravenscar
+@section pragma Ravenscar
+
+The pragma @code{Ravenscar} has exactly the same effect as pragma
+@code{Profile (Ravenscar)}. The latter usage is preferred since it
+is part of the new Ada 2005 standard.
+
+@node pragma Restricted_Run_Time
+@section pragma Restricted_Run_Time
+
+The pragma @code{Restricted_Run_Time} has exactly the same effect as
+pragma @code{Profile (Restricted)}. The latter usage is
+preferred since the Ada 2005 pragma @code{Profile} is intended for
+this kind of implementation dependent addition.
+
@include fdl.texi
@c GNU Free Documentation License
OSDN Git Service
