@c o
@c G N A T _ RM o
@c o
-@c Copyright (C) 1995-2005 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
@setfilename gnat_rm.info
-@set FSFEDITION
-
+@set EDITION GNAT
@settitle GNAT Reference Manual
@setchapternewpage odd
@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::
* 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 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 Polling::
* Pragma Profile (Ravenscar)::
* Pragma Profile (Restricted)::
-* Pragma Propagate_Exceptions::
* Pragma Psect_Object::
* Pragma Pure_Function::
* Pragma Restriction_Warnings::
* 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
* Safe_Large::
* Small::
* Storage_Unit::
+* Stub_Type::
* Target_Name::
* Tick::
* To_Address::
* Wide_Wide_Text_IO::
* Stream_IO::
* Shared Files::
+* Filenames encoding::
* Open Modes::
* Operations on C Streams::
* Interfacing to C Streams::
* 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.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 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
* 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 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 Polling::
* Pragma Profile (Ravenscar)::
* Pragma Profile (Restricted)::
-* Pragma Propagate_Exceptions::
* Pragma Psect_Object::
* Pragma Pure_Function::
* Pragma Restriction_Warnings::
* 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 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
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
@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.
+This pragma is now obsolete has has no effect because GNAT generates
+the same object layout than the G++ compiler.
-The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if
-there is one Vtable_Ptr present (single inheritance case) and all
-virtual functions are imported. In that case the compiler can deduce both
-these values.
-
-No @code{External_Name} or @code{Link_Name} arguments are required for a
-virtual function, since it is always accessed indirectly via the
-appropriate Vtable entry.
-
-Pragma @code{CPP_Virtual} is intended primarily for automatic generation
-using an automatic binding generator tool.
See @ref{Interfacing to C++} for related information.
@node Pragma CPP_Vtable
@cindex Interfacing with C++
@findex CPP_Vtable
@noindent
-Syntax:
-
-@smallexample @c ada
-pragma CPP_Vtable (
- [Entity =>] ENTITY,
- [Vtable_Ptr =>] vtable_ENTITY,
- [Entry_Count =>] static_integer_EXPRESSION);
-@end smallexample
-
-@noindent
-Given a record to which the pragma @code{CPP_Class} applies,
-this pragma can be specified for each component of type
-@code{CPP.Interfaces.Vtable_Ptr}.
-@var{Entity} is the tagged type, @var{Vtable_Ptr}
-is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is
-the number of virtual functions on the C++ side. Not all of these
-functions need to be imported on the Ada side.
-
-You may omit the @code{CPP_Vtable} pragma if there is only one
-@code{Vtable_Ptr} component in the record and all virtual functions are
-imported on the Ada side (the default value for the entry count in this
-case is simply the total number of virtual functions).
+This pragma is now obsolete has has no effect because GNAT generates
+the same object layout than the G++ compiler.
-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
-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
+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
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
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);
+ [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
@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
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
Syntax:
@smallexample @c ada
-pragma Obsolescent [(static_string_EXPRESSION [,Ada_05])];
+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).
-If the optional second parameter is present (which must be exactly
+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 have become defined
-as obsolescent in Ada 2005 (e.g. in Ada.Characters.Handling), but
-may be used anywhere.
+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
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
version of the run time that provides improved performance for the
limited set of tasking functionality permitted by this set of restrictions.
-@node Pragma Propagate_Exceptions
-@unnumberedsec Pragma Propagate_Exceptions
-@findex Propagate_Exceptions
-@cindex Zero Cost Exceptions
-@noindent
-Syntax:
-
-@smallexample @c ada
-pragma Propagate_Exceptions (subprogram_local_NAME);
-@end smallexample
-
-@noindent
-This pragma indicates that the given entity, which is the name of an
-imported foreign-language subprogram may receive an Ada exception,
-and that the exception should be propagated. It is relevant only if
-zero cost exception handling is in use, and is thus never needed if
-the alternative @code{longjmp} / @code{setjmp} implementation of
-exceptions is used (although it is harmless to use it in such cases).
-
-The implementation of fast exceptions always properly propagates
-exceptions through Ada code, as described in the Ada Reference Manual.
-However, this manual is silent about the propagation of exceptions
-through foreign code. For example, consider the
-situation where @code{P1} calls
-@code{P2}, and @code{P2} calls @code{P3}, where
-@code{P1} and @code{P3} are in Ada, but @code{P2} is in C@.
-@code{P3} raises an Ada exception. The question is whether or not
-it will be propagated through @code{P2} and can be handled in
-@code{P1}.
-
-For the @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.
-
@node Pragma Psect_Object
@unnumberedsec Pragma Psect_Object
@findex Psect_Object
disambiguate cases of overloading where some but not all functions
in a set of overloaded functions are to be designated as pure.
+If pragma @code{Pure_Function} is applied to a library level function, the
+function is also considered pure from an optimization point of view, but the
+unit is not a Pure unit in the categorization sense. So for example, a function
+thus marked is free to @code{with} non-pure units.
+
@node Pragma Restriction_Warnings
@unnumberedsec Pragma Restriction_Warnings
@findex Restriction_Warnings
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
@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
@smallexample @c ada
pragma Unreferenced (local_NAME @{, local_NAME@});
+pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
@end smallexample
@noindent
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
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
@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.
+@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 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
* Safe_Large::
* Small::
* Storage_Unit::
+* Stub_Type::
* Target_Name::
* Tick::
* To_Address::
@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
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 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++.
@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
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.
+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
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} 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}.
-
@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
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.
* Wide_Wide_Text_IO::
* Stream_IO::
* Shared Files::
+* Filenames encoding::
* Open Modes::
* Operations on C Streams::
* Interfacing to C Streams::
@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
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
@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
* 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.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)::
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})
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})
@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})
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})
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.
+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 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
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
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
OSDN Git Service
