Ada 95 defines a set of pragmas that can be used to supply additional information to the compiler. These language defined pragmas are implemented in GNAT and work as described in the Ada 95 Reference Manual.
In addition, Ada 95 allows implementations to define additional pragmas whose meaning is defined by the implementation. GNAT provides a number of these implementation-dependent pragmas which can be used to extend and enhance the functionality of the compiler. This section of the GNAT Reference Manual describes these additional pragmas.
Note that any program using these pragmas may not be portable to other compilers (although GNAT implements this set of pragmas on all platforms). Therefore if portability to other compilers is an important consideration, the use of these pragmas should be minimized.
pragma Abort_Defer
pragma Abort_Defer;This pragma must appear at the start of the statement sequence of a handled sequence of statements (right after the
begin
). It has
the effect of deferring aborts for the sequence of statements (but not
for the declarations or handlers, if any, associated with this statement
sequence).
pragma Ada_83
pragma Ada_83;A configuration pragma that establishes Ada 83 mode for the unit to which it applies, regardless of the mode set by the command line switches. In Ada 83 mode, GNAT attempts to be as compatible with the syntax and semantics of Ada 83, as defined in the original Ada 83 Reference Manual as possible. In particular, the new Ada 95 keywords are not recognized, optional package bodies are allowed, and generics may name types with unknown discriminants without using the (<>) notation. In addition, some but not all of the additional restrictions of Ada 83 are enforced. Ada 83 mode is intended for two purposes. Firstly, it allows existing legacy Ada 83 code to be compiled and adapted to GNAT with less effort. Secondly, it aids in keeping code backwards compatible with Ada 83. However, there is no guarantee that code that is processed correctly by GNAT in Ada 83 mode will in fact compile and execute with an Ada 83 compiler, since GNAT does not enforce all the additional checks required by Ada 83.
pragma Ada_95
pragma Ada_95;A configuration pragma that establishes Ada 95 mode for the unit to which it applies, regardless of the mode set by the command line switches. This mode is set automatically for the
Ada
and System
packages and their children, so you need not specify it in these
contexts. This pragma is useful when writing a reusable component that
itself uses Ada 95 features, but which is intended to be usable from
either Ada 83 or Ada 95 programs.
pragma Annotate
pragma Annotate (IDENTIFIER {, ARG}); ARG ::= NAME | EXPRESSIONThis pragma is used to annotate programs. identifier identifies the type of annotation. GNAT verifies this is an identifier, but does not otherwise analyze it. The arg argument can be either a string literal or an expression. String literals are assumed to be of type
Standard.String
. Names of entities are simply analyzed as entity
names. All other expressions are analyzed as expressions, and must be
unambiguous.
The analyzed pragma is retained in the tree, but not otherwise processed
by any part of the GNAT compiler. This pragma is intended for use by
external tools, including ASIS.
pragma Assert
pragma Assert ( boolean_EXPRESSION [, static_string_EXPRESSION])The effect of this pragma depends on whether the corresponding command line switch is set to activate assertions. If assertions are inactive, the pragma has no effect. If assertions are enabled, then the semantics of the pragma is exactly equivalent to:
if not boolean_EXPRESSION then System.Assertions.Raise_Assert_Failure (string_EXPRESSION); end if;The effect of the call is to raise
System.Assertions.Assert_Failure
. The string argument, if given,
is the message associated with the exception occurrence. If no second
argument is given, the default message is `file:nnn',
where file is the name of the source file containing the assert,
and nnn is the line number of the assert. A pragma is not a
statement, so if a statement sequence contains nothing but a pragma
assert, then a null statement is required in addition, as in:
Note that, as with the if statement to which it is equivalent, the
type of the expression is either Standard.Boolean, or any type derived
from this standard type.
... if J > 3 then pragma (Assert (K > 3, "Bad value for K")); null; end if;If the boolean expression has side effects, these side effects will turn on and off with the setting of the assertions mode, resulting in assertions that have an effect on the program. You should generally avoid side effects in the expression arguments of this pragma. However, the expressions are analyzed for semantic correctness whether or not assertions are enabled, so turning assertions on and off cannot affect the legality of a program.
pragma Ast_Entry
pragma AST_Entry (entry_IDENTIFIER);This pragma is implemented only in the OpenVMS implementation of GNAT. The argument is the simple name of a single entry; at most one
AST_Entry
pragma is allowed for any given entry. This pragma must be used in
conjunction with the AST_Entry
attribute, and is only allowed after
the entry declaration and in the same task type specification or single task
as the entry to which it applies. This pragma specifies that the given entry
may be used to handle an OpenVMS asynchronous system trap (AST
)
resulting from an OpenVMS system service call. The pragma does not affect
normal use of the entry. For further details on this pragma, see the
DEC Ada Language Reference Manual, section 9.12a.
pragma C_Pass_By_Copy
pragma C_Pass_By_Copy ([Max_Size =>] static_integer_EXPRESSION);Normally the default mechanism for passing C convention records to C convention subprograms is to pass them by reference, as suggested by RM B.3(69). Use the configuration pragma
C_Pass_By_Copy
to change
this default, by requiring that record formal parameters be passed by
copy if all of the following conditions are met:
Convention C
.
C_Pass_By_Copy
for the record type, or by using the extended
Import
and Export
pragmas, which allow specification of
passing mechanisms on a parameter by parameter basis.
pragma Comment
pragma Comment (static_string_EXPRESSION);Synonymous for pragma Ident.
pragma Common_Object
pragma Common_Object [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL, [, [Size =>] EXTERNAL_SYMBOL] EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSIONThis pragma enables the shared use of variables stored in overlaid linker areas corresponding to the use of
COMMON
in Fortran. The single
object local_name is assigned to the area designated by
the External argument.
You may define a record to correspond to a series
of fields. The size argument
is syntax checked in GNAT, but otherwise ignored.
pragma Complex_Representation
pragma Complex_Representation ([Entity =>] LOCAL_NAME);The Entity argument must be the name of a record type which has two fields of the same floating-point type. The effect of this pragma is to force gcc to use the special internal complex representation form for this record, which may be more efficient. Note that this may result in the code for this type not conforming to standard ABI (application binary interface) requirements for the handling of record types. For example, in some environments, there is a requirement for passing records by pointer, and the use of this pragma may result in passing this type in floating-point registers.
pragma Component_Alignment
pragma Component_Alignment ( [Form =>] ALIGNMENT_CHOICE [, [Name =>] type_LOCAL_NAME]); ALIGNMENT_CHOICE ::= Component_Size | Component_Size_4 | Storage_Unit | DefaultSpecifies the alignment of components in array or record types. The meaning of the Form argument is as follows:
Component_Size
Component_Size_4
Storage_Unit
System.Storage_Unit
.
Default
Default
choice is the same as
the Storage_Unit
choice (byte alignment). For all other systems,
the Default
choice is the same as Component_Size
(natural
alignment).
Name
parameter is present, 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
Component_Alignment
together with a pragma Pack
causes the
Component_Alignment
pragma to be ignored. The use of
Component_Alignment
together with a record representation clause
is only effective for fields not specified by the representation clause.
If the Name
parameter is absent, the pragma can be used as either
a configuration pragma, in which case it applies to one or more units in
accordance with the normal rules for configuration pragmas, or it can be
used within a declarative part, in which case it applies to types that
are declared within this declarative part, or within any nested scope
within this declarative part. In either case it specifies the alignment
to be applied to any record or array type which has otherwise standard
representation.
If the alignment for a record or array type is not specified (using
pragma Pack
, pragma Component_Alignment
, or a record rep
clause), the GNAT uses the default alignment as described previously.
pragma CPP_Class
pragma CPP_Class ([Entity =>] LOCAL_NAME);The argument denotes an entity in the current declarative region that is declared as a tagged or untagged record type. It indicates that the type corresponds to an externally declared C++ class type, and is to be laid out the same way that C++ would lay out the type. If (and only if) the type is tagged, at least one component in the record must be of type
Interfaces.CPP.Vtable_Ptr
, corresponding
to the C++ Vtable (or Vtables in the case of multiple inheritance) used
for dispatching.
Types for which 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 CPP_Constructor
).
Pragma CPP_Class
is intended primarily for automatic generation
using an automatic binding generator tool. Ada Core Technologies does
not currently supply such a
tool; See section Interfacing to C++ for more details.
pragma CPP_Constructor
pragma CPP_Constructor ([Entity =>] LOCAL_NAME);This pragma identifies an imported function (imported in the usual way with pragma Import) as corresponding to a C++ constructor. The argument is a name that must have been previously mentioned in a pragma Import with Convention CPP, and must be of one of the following forms:
function Fname return T'Class
function Fname (...) return T'Class
CPP_Class
applies.
The first form is the default constructor, used when an object of type
T is created on the Ada side with no explicit constructor. Other
constructors (including the copy constructor, which is simply a special
case of the second form in which the one and only argument is of type
T), can only appear in two contexts:
New_Object : Derived_T
New_Object : Derived_T := (constructor-function-call with ...)
CPP_Constructor
is intended primarily for automatic generation
using an automatic binding generator tool. Ada Core Technologies does
not currently supply such a
tool; See section Interfacing to C++ for more details.
pragma CPP_Destructor ([Entity =>] LOCAL_NAME);
Import
with Convention CPP
, and be of the following form:
procedure Fname (obj : in out T'Class);where T is a tagged type to which pragma
CPP_Class
applies. This procedure will be called automatically on scope exit if
any objects of T are created on the Ada side.
Pragma CPP_Destructor
is intended primarily for automatic generation
using an automatic binding generator tool. Ada Core Technologies does
not currently supply such a
tool; See section Interfacing to C++ for more details.
pragma CPP_Virtual
pragma CPP_Virtual [Entity =>] ENTITY, [, [Vtable_Ptr =>] vtable_ENTITY,] [, [Position =>] static_integer_EXPRESSION])This pragma serves the same function as pragma
Import
in that
case of a virtual function imported from C++. The Entity argument
must be a
primitive subprogram of a tagged type to which pragma CPP_Class
applies. The Vtable_Ptr argument specifies
the Vtable_Ptr component which contains the
entry for this virtual function. The Position argument
is the sequential number
counting virtual functions for this Vtable starting at 1.
The Vtable_Ptr
and 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 External_Name
or Link_Name
arguments are required for a
virtual function, since it is always accessed indirectly via the
appropriate Vtable entry.
Pragma CPP_Virtual
is intended primarily for automatic generation
using an automatic binding generator tool. Ada Core Technologies does
not currently supply such a
tool; See section Interfacing to C++ for more details.
pragma CPP_Vtable
pragma CPP_Vtable ( [Entity =>] ENTITY, [Vtable_Ptr =>] vtable_ENTITY, [Entry_Count =>] static_integer_EXPRESSION);Given a record to which the pragma
CPP_Class
applies,
this pragma can be specified for each component of type
CPP.Interfaces.Vtable_Ptr
.
Entity is the tagged type, Vtable_Ptr
is the record field of type Vtable_Ptr
, and 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 CPP_Vtable
pragma if there is only one
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 CPP_Vtable
is intended primarily for automatic generation
using an automatic binding generator tool. Ada Core Technologies does
not currently supply such a
tool; See section Interfacing to C++ for more details.
pragma Debug
pragma Debug (PROCEDURE_CALL_STATEMENT);If assertions are not enabled on the command line, this pragma has no effect. If asserts are enabled, the semantics of the pragma is exactly equivalent to the procedure call. Pragmas are permitted in sequences of declarations, so you can use pragma
Debug
to intersperse calls to
debug procedures in the middle of declarations.
pragma Eliminate
pragma Eliminate ( [Unit_Name =>] IDENTIFIER | SELECTED_COMPONENT [,[Entity =>] IDENTIFIER | SELECTED_COMPONENT | STRING_LITERAL] [,[Parameter_Types =>] PARAMETER_TYPES] [,[Result_Type =>] result_SUBTYPE_MARK]); PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK}This pragma indicates that the given entity is unused in a program. The entity may be either a subprogram or a variable. If the entity to be eliminated is a library level subprogram, then only the first argument, specifying the corresponding unit name, is required. If the item is an entity of a library package, then the first argument specifies the unit name, and the second argument specifies the particular entity. If the second argument is in string form, it must correspond to the internal manner in which GNAT stores entity names (see compilation unit Namet in the compiler sources for details). The third and fourth parameters are optionally used to distinguish between overloaded subprograms, in the same manner as is used for pragma Import_Procedure. The effect of the pragma is to allow the compiler to optionally eliminate the code or data associated with the named entity. If the declaration of the entity would have resulted in side effects, these side effects may or may not occur in the resulting program. Any reference to an eliminated entity may cause a compile time error, link time error, or incorrect results at runtime. The intention of pragma Eliminate is to allow a program to be compiled in a system independent manner, with unused entities eliminated, without the requirement of modifying the source text. Normally the required set of Eliminate pragmas is constructed automatically using the gnatelim tool.
pragma Export_Exception
pragma Export_Exception ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL,] [, [Form =>] Ada | VMS] [, [Code =>] static_integer_EXPRESSION]); EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSIONThis pragma is implemented only in the OpenVMS implementation of GNAT. It causes the specified exception to be propagated outside of the Ada program, so that it can be handled by programs written in other OpenVMS languages. This pragma establishes an external name for an Ada exception and makes the name available to the OpenVMS Linker as a global symbol. For further details on this pragma, see the DEC Ada Language Reference Manual, section 13.9a3.2.
pragma Export_Function ...
pragma Export_Function ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Result_Type =>] result_SUBTYPE_MARK] [, [Mechanism =>] MECHANISM] [, [Result_Mechanism =>] MECHANISM_NAME]); EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSION PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK} MECHANISM ::= MECHANISM_NAME | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) MECHANISM_ASSOCIATION ::= [formal_parameter_NAME =>] MECHANISM_NAME MECHANISM_NAME ::= Value | Reference | Descriptor [([Class =>] CLASS_NAME)] CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | ncaUse this pragma to make a function externally callable and optionally provide information on mechanisms to be used for passing parameter and result values. We recommend, for the purposes of improving portability, this pragma always be used in conjunction with a separate pragma
Export
, which must precede the pragma Export_Function
.
GNAT does not require a separate pragma Export
, but if none is
present, it assumes Convention C
. Pragma Export_Function
(and Export
, if present) must appear in the same declarative
region as the function to which they apply.
internal_name must uniquely designate the function to which the
pragma applies. If more than one function name exists of this name in
the declarative part you must use the Parameter_Types
and
Result_Type
parameters is mandatory to achieve the required
unique designation. subtype_ marks in these parameters must
exactly match the subtypes in the corresponding function specification,
using positional notation to match parameters with subtype marks.
Passing by descriptor is supported only on the OpenVMS ports of GNAT.
pragma Export_Object ...
pragma Export_Object [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Size =>] EXTERNAL_SYMBOL] EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSIONThis pragma designates an object as exported, and apart from the extended rules for external symbols, is identical in effect to the use of the normal
Export
pragma applied to an object. You may use a
separate Export pragma (and you probably should from the point of view
of portability), but it is not required. Size is syntax checked,
but otherwise ignored by GNAT.
pragma Export_Procedure ...
pragma Export_Procedure ( [Internal =>] LOCAL_NAME [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Mechanism =>] MECHANISM]); EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSION PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK} MECHANISM ::= MECHANISM_NAME | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) MECHANISM_ASSOCIATION ::= [formal_parameter_NAME =>] MECHANISM_NAME MECHANISM_NAME ::= Value | Reference | Descriptor [([Class =>] CLASS_NAME)] CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | ncaThis pragma is identical to
Export_Function
except that it
applies to a procedure rather than a function and the parameters
Result_Type
and Result_Mechanism
are not permitted.
pragma Export_Valued_Procedure
pragma Export_Valued_Procedure ( [Internal =>] LOCAL_NAME [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Mechanism =>] MECHANISM]); EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSION PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK} MECHANISM ::= MECHANISM_NAME | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) MECHANISM_ASSOCIATION ::= [formal_parameter_NAME =>] MECHANISM_NAME MECHANISM_NAME ::= Value | Reference | Descriptor [([Class =>] CLASS_NAME)] CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | ncaThis pragma is identical to
Export_Procedure
except that the
first parameter of local_name, which must be present, must be of
mode 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 OUT
and IN OUT
parameters in interfacing to external functions (which are not permitted
in Ada functions).
pragma Extend_System
pragma Extend_System ([Name =>] IDENTIFIER);This pragma is used to provide backwards compatibility with other implementations that extend the facilities of package
System
. In
GNAT, System
contains only the definitions that are present in
the Ada 95 RM. However, other implementations, notably the DEC Ada 83
implementation, provide many extensions to package System
.
For each such implementation accommodated by this pragma, GNAT provides a
package Aux_xxx
, e.g. Aux_DEC
for the DEC Ada 83
implementation, which provides the required additional definitions. You
can use this package in two ways. You can with
it in the normal
way and access entities either by selection or using a use
clause. In this case no special processing is required.
However, if existing code contains references such as
System.xxx
where xxx is an entity in the extended
definitions provided in package System
, you may use this pragma
to extend visibility in System
in a non-standard way that
provides greater compatibility with the existing code. Pragma
Extend_System
is a configuration pragma whose single argument is
the name of the package containing the extended definition
(e.g. Aux_DEC
for the DEC Ada case). A unit compiled under
control of this pragma will be processed using special visibility
processing that looks in package System.Aux_xxx
where
Aux_xxx
is the pragma argument for any entity referenced in
package System
, but not found in package System
.
pragma Finalize_Storage_Only
pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);This pragma allows the compiler not to emit a Finalize call for objects defined at the library level. This is mostly useful for types where finalization is only used to deal with storage reclamation since in most environments it is not necessary to reclaim memory just before terminating execution, hence the name.
pragma Float_Representation
pragma Float_Representation (FLOAT_REP); FLOAT_REP ::= VAX_Float | IEEE_FloatThis pragma is implemented only in the OpenVMS implementation of GNAT. It allows control over the internal representation chosen for the predefined floating point types declared in the packages
Standard
and
System
. For further details on this pragma, see the
DEC Ada Language Reference Manual, section 3.5.7a. Note that to use this
pragma, the standard runtime libraries must be recompiled. See the
description of the GNAT LIBRARY
command in the OpenVMS version
of the GNAT Users Guide for details on the use of this command.
pragma Ident
pragma Ident (static_string_EXPRESSION);This pragma provides a string identification in the generated object file, if the system supports the concept of this kind of identification string. The maximum permitted length of the string literal is 31 characters. This pragma is allowed only in the outermost declarative part or declarative items of a compilation unit. On OpenVMS systems, the effect of the pragma is identical to the effect of the DEC Ada 83 pragma of the same name.
pragma Import_Exception
pragma Import_Exception ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL,] [, [Form =>] Ada | VMS] [, [Code =>] static_integer_EXPRESSION]); EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSIONThis pragma is implemented only in the OpenVMS implementation of GNAT. It allows OpenVMS conditions (for example, from OpenVMS system services or other OpenVMS languages) to be propagated to Ada programs as Ada exceptions. The pragma specifies that the exception associated with an exception declaration in an Ada program be defined externally (in non-Ada code). For further details on this pragma, see the DEC Ada Language Reference Manual, section 13.9a.3.1.
Import_Function ...
pragma Import_Function ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Result_Type =>] SUBTYPE_MARK] [, [Mechanism =>] MECHANISM] [, [Result_Mechanism =>] MECHANISM_NAME] [, [First_Optional_Parameter =>] IDENTIFIER]); EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSION PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK} MECHANISM ::= MECHANISM_NAME | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) MECHANISM_ASSOCIATION ::= [formal_parameter_NAME =>] MECHANISM_NAME MECHANISM_NAME ::= Value | Reference | Descriptor [([Class =>] CLASS_NAME)] CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | ncaThis pragma is used in conjunction with a pragma
Import
to
specify additional information for an imported function. The pragma
Import
(or equivalent pragma Interface
) must precede the
Import_Function
pragma and both must appear in the same
declarative part as the function specification.
The Internal_Name argument must uniquely designate
the function to which the
pragma applies. If more than one function name exists of this name in
the declarative part you must use the Parameter_Types
and
Result_Type parameters to achieve the required unique
designation. Subtype marks in these parameters must exactly match the
subtypes in the corresponding function specification, using positional
notation to match parameters with subtype marks.
You may optionally use the Mechanism and Result_Mechanism
parameters to specify passing mechanisms for the
parameters and result. If you specify a single mechanism name, it
applies to all parameters. Otherwise you may specify a mechanism on a
parameter by parameter basis using either positional or named
notation. If the mechanism is not specified, the default mechanism
is used.
Passing by descriptor is supported only on the to OpenVMS ports of GNAT
First_Optional_Parameter
applies only to OpenVMS ports of GNAT.
It specifies that the designated parameter and all following parameters
are optional, meaning that they are not passed at the generated code
level (this is distinct from the notion of optional parameters in Ada
where the parameters are passed anyway with the designated optional
parameters). All optional parameters must be of mode IN
and have
default parameter values that are either known at compile time
expressions, or uses of the 'Null_Parameter
attribute.
pragma Import_Object
pragma Import_Object [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL], [, [Size =>] EXTERNAL_SYMBOL]) EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSIONThis pragma designates an object as imported, and apart from the extended rules for external symbols, is identical in effect to the use of the normal
Import
pragma applied to an object. Unlike the
subprogram case, you need not use a separate Import
pragma,
although you may do so (and probably should do so from a portability
point of view). size is syntax checked, but otherwise ignored by
GNAT.
pragma Import_Procedure
pragma Import_Procedure ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Mechanism =>] MECHANISM] [, [First_Optional_Parameter =>] IDENTIFIER]); EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSION PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK} MECHANISM ::= MECHANISM_NAME | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) MECHANISM_ASSOCIATION ::= [formal_parameter_NAME =>] MECHANISM_NAME MECHANISM_NAME ::= Value | Reference | Descriptor [([Class =>] CLASS_NAME)] CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | ncaThis pragma is identical to
Import_Function
except that it
applies to a procedure rather than a function and the parameters
Result_Type
and Result_Mechanism
are not permitted.
pragma Import_Valued_Procedure ...
pragma Import_Valued_Procedure ( [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Parameter_Types =>] PARAMETER_TYPES] [, [Mechanism =>] MECHANISM] [, [First_Optional_Parameter =>] IDENTIFIER]); EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSION PARAMETER_TYPES ::= null | SUBTYPE_MARK {, SUBTYPE_MARK} MECHANISM ::= MECHANISM_NAME | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) MECHANISM_ASSOCIATION ::= [formal_parameter_NAME =>] MECHANISM_NAME MECHANISM_NAME ::= Value | Reference | Descriptor [([Class =>] CLASS_NAME)] CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | ncaThis pragma is identical to
Import_Procedure
except that the
first parameter of local_name, which must be present, must be of
mode 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 OUT
and IN OUT
parameters in interfacing to external functions (which are not permitted
in Ada functions). You may optionally use the Mechanism
parameters to specify passing mechanisms for the parameters.
If you specify a single mechanism name, it applies to all parameters.
Otherwise you may specify a mechanism on a parameter by parameter
basis using either positional or named notation. If the mechanism is not
specified, the default mechanism is used.
pragma Inline_Always
pragma Inline_Always (NAME [, NAME]);Similar to pragma
Inline
except that inlining is not subject to
the use of option -gnatn
for inter-unit inlining.
pragma Inline_Generic
pragma Inline_Generic (generic_package_NAME)This is implemented for compatibility with DEC Ada 83 and is recognized, but otherwise ignored, by GNAT. All generic instantiations are inlined by default when using GNAT.
pragma Interface_Name
pragma Interface_Name ( [Entity =>] LOCAL_NAME [, [External_Name =>] static_string_EXPRESSION] [, [Link_Name =>] static_string_EXPRESSION]);This pragma provides an alternative way of specifying the interface name for an interfaced subprogram, and is provided for compatibility with Ada 83 compilers that use the pragma for this purpose. You must provide at least one of External_Name or Link_Name.
pragma Linker_Alias
pragma Linker_Alias ( [Entity =>] LOCAL_NAME [Alias =>] static_string_EXPRESSION);This pragma establishes a linker alias for the given named entity. For further details on the exact effect, consult the GCC manual.
pragma Linker_Section
pragma Linker_Section ( [Entity =>] LOCAL_NAME [Section =>] static_string_EXPRESSION);This pragma specifies the name of the linker section for the given entity. For further details on the exact effect, consult the GCC manual.
pragma No_Runtime
pragma No_Runtime;This is a configuration pragma that makes sure the user code does not use nor need anything from the GNAT run time. This is mostly useful in context where code certification is required. Please consult the GNORT product documentation for additional information.
pragma Normalize_Scalars
pragma Normalize_Scalars;This is a language defined pragma which is fully implemented in GNAT. The effect is to cause all scalar objects that are not otherwise initialized to be initialized. The initial values are implementation dependent and are as follows:
Standard.Character
Standard.Wide_Character
Integer types
subtype Ityp is integer range 1 .. 10;then objects of type x will be initialized to Integer'First, a negative number that is certainly outside the range of subtype
Ityp
.
Real types
Modular types
Enumeration types
pragma Long_Float
pragma Long_Float (FLOAT_FORMAT); FLOAT_FORMAT ::= D_Float | G_FloatThis pragma is implemented only in the OpenVMS implementation of GNAT. It allows control over the internal representation chosen for the predefined type
Long_Float
and for floating point type representations with
digits
specified in the range 7 .. 15.
For further details on this pragma, see the
DEC Ada Language Reference Manual, section 3.5.7b. Note that to use this
pragma, the standard runtime libraries must be recompiled. See the
description of the GNAT LIBRARY
command in the OpenVMS version
of the GNAT Users Guide for details on the use of this command.
pragma Machine_Attribute ...
pragma Machine_Attribute ( [Attribute_Name =>] string_EXPRESSION, [Entity =>] LOCAL_NAME);Machine dependent attributes can be specified for types and/or declarations. Currently only subprogram entities are supported. This pragma is semantically equivalent to
__attribute__((
string_expression))
in GNU C, where string_expression
> is
recognized by the GNU C macros VALID_MACHINE_TYPE_ATTRIBUTE
and
VALID_MACHINE_DECL_ATTRIBUTE
which are defined in the
configuration header file `tm.h' for each machine. See the GCC
manual for further information.
pragma Main_Storage
pragma Main_Storage (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); MAIN_STORAGE_OPTION ::= [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION | [TOP_GUARD =>] static_SIMPLE_EXPRESSIONThis pragma is provided for compatibility with OpenVMS Vax Systems. It has no effect in GNAT, other than being syntax checked. Note that the pragma also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
pragma No_Return
pragma No_Return (procedure_LOCAL_NAME);procedure_local_NAME must refer to one or more procedure declarations in the current declarative part. A procedure to which this pragma is applied may not contain any explicit
return
statements,
and also may not contain any implicit return statements from falling off
the end of a statement sequence. One use of this pragma is to identify
procedures whose only purpose is to raise an exception.
Another use of this pragma is to suppress incorrect warnings about
missing returns in functions, where the last statement of a function
statement sequence is a call to such a procedure.
pragma Passive
pragma Passive ([Semaphore | No]);Syntax checked, but otherwise ignored by GNAT. This is recognized for compatibility with DEC Ada 83 implementations, where it is used within a task definition to request that a task be made passive. If the argument
Semaphore
is present, or no argument is omitted, then DEC Ada 83
treats the pragma as an assertion that the containing task is passive
and that optimization of context switch with this task is permitted and
desired. If the argument No
is present, the task must not be
optimized. GNAT does not attempt to optimize any tasks in this manner
(since protected objects are available in place of passive tasks).
pragma Polling
pragma Polling (ON | OFF);This pragma controls the generation of polling code. This is normally off. If
pragma Polling (ON)
is used then periodic calls are generated to
the routine Ada.Exceptions.Poll. This routine is a separate unit in the
runtime library, and can be found in file a-excpol.adb.
Pragma polling can appear as a configuration pragma (for example it can be
placed in the gnat.adc file) to enable polling globally, or it can be used
in the statement or declaration sequence to control polling more locally.
A call to the polling routine is generated at the start of every loop and
at the start of every subprogram call. This guarantees that the Poll
routine is called frequently, and places an upper bound (determined by
the complexity of the code) on the period between two Poll calls.
The primary purpose of the polling interface is to enable asynchronous
aborts on targets that cannot otherwise support it (for example Windows
NT), but it may be used for any other purpose requiring periodic polling.
The standard version is null, and can be replaced by a user program. This
will require re-compilation of the Ada.Exceptions package that can be found
in files a-except.ads/adb.
A standard alternative unit (called 4wexcpol.adb in the standard GNAT
distribution) is used to enable the asynchronous abort capability on
targets that do not normally support the capability. The version of Poll
in this file makes a call to the appropriate runtime routine to test for
an abort condition.
Note that polling can also be enabled by use of the -gnatP switch. See
the GNAT User's Guide for details.
pragma Propagate_Exceptions
pragma Propagate_Exceptions (subprogram_LOCAL_NAME);This pragma indicates that the given entity, which is the name of an imported foreign-langauge subprogram may receive an Ada exception, and that the exception should be propagated. It is relevant only if zero cost exception handling is in use, and is thus never needed if the alternative longjmp/setjmp implementation of exceptions is used (although it is harmless to use it in such cases). The implementation of fast exceptions always properly propagates exceptions through Ada code, as described in the Ada Reference Manual. However, this manual is silent about the propagation of exceptions through foreign code. For example, consider the situation where
P1
calls
P2
, and P2
calls P3
, where
P1
and P3
are in Ada, but P2
is in C.
P3
raises an Ada exception. The question is whether or not
it will be propagated through P2
and can be handled in
P1
.
For the longjmp/setjmp implementation of exceptions, the answer is
always yes. For some targets on which zero cost exception handling
is implemented, the answer is also always yes. However, there are
some targets, notably in the current version all x86 architecture
targets, in which the answer is that such propagation does not
happen automatically. If such propagation is required on these
targets, it is mandatory to use Propagate_Exceptions
to
name all foreign language routines through which Ada exceptions
may be propagated.
pragma Psect_Object
pragma Psect_Object [Internal =>] LOCAL_NAME, [, [External =>] EXTERNAL_SYMBOL] [, [Size =>] EXTERNAL_SYMBOL] EXTERNAL_SYMBOL ::= IDENTIFIER | static_string_EXPRESSIONThis pragma is identical in effect to pragma
Common_Object
.
Pure_Function
pragma Pure_Function ([Entity =>] function_LOCAL_NAME);This pragma appears in the same declarative part as a function declaration (or a set of function declarations if more than one overloaded declaration exists, in which case the pragma applies to all entities). If specifies that the function
Entity
is
to be considered pure for the purposes of code generation. This means
that the compiler can assume that there are no side effects, and
in particular that two calls with identical arguments produce the
same result. It also means that the function can be used in an
address clause.
Note that, quite deliberately, there are no static checks to try
to ensure that this promise is met, so Pure_Function can be used
with functions that are conceptually pure, even if they do modify
global variables. For example, a square root function that is
instrumented to count the number of times it is called is still
conceptually pure, and can still be optimized, even though it
modifies a global variable (the count). Memo functions are another
example (where a table of previous calls is kept and consulted to
avoid re-computation).
Note: All functions in a Pure
package are automatically pure, and
there is no need to use pragma Pure_Function
in this case.
Note: If pragma Pure_Function
is applied to a renamed function, it
applies to the underlying renamed function. This can be used to
disambiguate cases of overloading where some but not all functions
in a set of overloaded functions are to be designated as pure.
pragma Ravenscar
pragma RavenscarA configuration pragma that establishes the following set of restrictions:
No_Abort_Statements
No_Select_Statements
No_Task_Hierarchy
No_Task_Allocators
No_Dynamic_Priorities
No_Terminate_Alternatives
No_Nested_Finalization
No_IO
No_Streams
No_Exception_Handlers
No_Dynamic_Interrupts
No_Protected_Type_Allocators
No_Local_Protected_Objects
No_Requeue
No_Calendar
No_Relative_Delay
No_Task_Attributes
No_Enumeration_Maps
Static_Storage_Size
Boolean_Entry_Barriers
Max_Asynchronous_Select_Nesting = 0
Max_Task_Entries = 0
Max_Protected_Entries = 1
Max_Select_Alternatives = 0
No_Task_Termination
No_Entry_Queue
Restricted_Run_Time
, it includes eight additional restrictions
(Boolean_Entry_Barriers
, No_Select_Statements
,
No_Exception_Handlers
, No_Calendar
, Static_Storage_Size
,
No_Relative_Delay
, No_Enumeration_Maps
, and
No_Task_Termination
). This means
that pragma Ravenscar, like the pragma Restricted_Run_Time, automatically
causes the use of a simplified, more efficient version of the tasking
run-time system.
pragma Restricted_Run_Time
pragma Restricted_Run_TimeA configuration pragma that establishes the following set of restrictions:
pragma Share_Generic
pragma Share_Generic (NAME {, NAME});This pragma is recognized for compatibility with other Ada compilers but is ignored by GNAT. GNAT does not provide the capability for sharing of generic code. All generic instantiations result in making an inlined copy of the template with appropriate substitutions.
pragma Source_File_Name
pragma Source_File_Name ( [Unit_Name =>] unit_NAME, [FNAME_DESIG =>] static_string_EXPRESSION); FNAME_DESIG => Body_File_Name | Spec_File_NameUse this to override the normal naming convention. It is a configuration pragma, and so has the usual applicability of configuration pragmas (i.e. it applies to either an entire partition, or to all units in a compilation, or to a single unit, depending on how it is used. unit_name is mapped to file_name_literal. The identifier for the second argument is required, and indicates whether this is the file name for the spec or for the body.
pragma Source_Reference
pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);This pragma typically appears as the first line of a source file. integer_literal is the logical line number of the line following the pragma line (for use in error messages and debugging information). string_literal is a static string constant that specifies the file name to be used in error messages and debugging information. This is most notably used for the output of
gnatchop
with the `-r' switch, to make sure that the original unchopped
source file is the one referred to.
The second argument must be a string literal, it cannot be a static
string expression other than a string literal. This is because its value
is needed for error messages issued by all phases of the compiler.
pragma Stream_Convert
pragma Stream_Convert ( [Entity =>] type_LOCAL_NAME, [Read =>] function_NAME, [Write =>] function NAME);This pragma provides an efficient way of providing stream functions for types defined in packages. Not only is it simpler to use than declaring the necessary functions with attribute representation clauses, but more significantly, it allows the declaration to made in such a way that the stream packages are not loaded unless they are needed. The use of the Stream_Convert pragma adds no overhead at all, unless the stream attributes are actually used on the designated type. The first argument specifies the type for which stream functions are provided. The second parameter provides a function used to read values of this type. It must name a function whose argument type may be any subtype, and whose returned type must be the type given as the first argument to the pragma. The meaning of the Read parameter is that if a stream attribute directly or indirectly specifies reading of the type given as the first parameter, then a value of the type given as the argument to the Read function is read from the stream, and then the Read function is used to convert this to the required target type. Similarly the Write parameter specifies how to treat write attributes that directly or indirectly apply to the type given as the first parameter. It must have an input parameter of the type specified by the first parameter, and the return type must be the same as the input type of the Read function. The effect is to first call the Write function to convert to the given stream type, and then write the result type to the stream. The Read and Write functions must not be overloaded subprograms. If necessary renamings can be supplied to meet this requirement. The usage of this attribute is best illustrated by a simple example, taken from the GNAT implementation of package Ada.Strings.Unbounded:
function To_Unbounded (S : String) return Unbounded_String renames To_Unbounded_String; pragma Stream_Convert (Unbounded_String, To_Unbounded, To_String);The specifications of the referenced functions, as given in the Ada 95 Reference Manual are:
function To_Unbounded_String (Source : String) return Unbounded_String; function To_String (Source : Unbounded_String) return String;The effect is that if the value of an unbounded string is written to a stream, then the representation of the item in the stream is in the same format used for
Standard.String
, and this same representation is
expected when a value of this type is read from the stream.
pragma Subtitle
pragma Subtitle ([Subtitle =>] STRING_LITERAL);This pragma is recognized for compatibility with other Ada compilers but is ignored by GNAT.
pragma Suppress_All
pragma Suppress_All;This pragma can only appear immediately following a compilation unit. The effect is to apply
Suppress (All_Checks)
to the unit
which it follows. This pragma is implemented for compatibility with DEC
Ada 83 usage. The use of pragma Suppress (All_Checks)
as a normal
configuration pragma is the preferred usage in GNAT.
pragma Suppress_Initialization
pragma Suppress_Initialization ([Entity =>] type_Name);This pragma suppresses any implicit or explicit initialization associated with the given type name for all variables of this type.
pragma Task_Info
pragma Task_Info (EXPRESSION);This pragma appears within a task definition (like pragma
Priority
) and applies to the task in which it appears. The
argument must be of type System.Task_Info.Task_Info_Type
.
The Task_Info
pragma provides system dependent control over
aspect of tasking implementation, for example, the ability to map
tasks to specific processors. For details on the facilities available
for the version of GNAT that you are using, see the documentation
in the specification of package System.Task_Info in the runtime
library.
pragma Task_Storage
pragma Task_Storage [Task_Type =>] LOCAL_NAME, [Top_Guard =>] static_integer_EXPRESSION);This pragma specifies the length of the guard area for tasks. The guard area is an additional storage area allocated to a task. A value of zero means that either no guard area is created or a minimal guard area is created, depending on the target. This pragma can appear anywhere a
Storage_Size
attribute definition clause is allowed for a task
type.
pragma Time_Slice
pragma Time_Slice (static_duration_EXPRESSION);For implementations of GNAT on operating systems where it is possible to supply a time slice value, this pragma may be used for this purpose. It is ignored if it is used in a system that does not allow this control, or if it appears in other than the main program unit. Note that the effect of this pragma is identical to the effect of the DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
pragma Title
pragma Title (TITLING_OPTION [, TITLING OPTION]); TITLING_OPTION ::= [Title =>] STRING_LITERAL, | [Subtitle =>] STRING_LITERALSyntax checked but otherwise ignored by GNAT. This is a listing control pragma used in DEC Ada 83 implementations to provide a title and/or subtitle for the program listing. The program listing generated by GNAT does not have titles or subtitles. Unlike other pragmas, the full flexibility of named notation is allowed for this pragma, i.e. the parameters may be given in any order if named notation is used, and named and positional notation can be mixed following the normal rules for procedure calls in Ada.
pragma Unchecked_Union
pragma Unchecked_Union (first_subtype_LOCAL_NAME)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:
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 Suppress (Discriminant_Check)
applies implicitly to the
type and the default convention is C
pragma Unimplemented_Unit
pragma Unimplemented_Unit;If this pragma occurs in a unit that is processed by the compiler, GNAT aborts with the message `xxx not implemented', where xxx is the name of the current compilation unit. This pragma is intended to allow the compiler to handle unimplemented library units in a clean manner. The abort only happens if code is being generated. Thus you can use specs of unimplemented packages in syntax or semantic checking mode.
pragma Unreserve_All_Interrupts
pragma Unreserve_All_Interrupts;Normally certain interrupts are reserved to the implementation. Any attempt to attach an interrupt causes Program_Error to be raised, as described in RM C.3.2(22). A typical example is the
SIGINT
interrupt used in
many systems for an Ctrl-C
interrupt. Normally this interrupt is
reserved to the implementation, so that Ctrl-C
can be used to
interrupt execution.
If the pragma Unreserve_All_Interrupts appears anywhere in any unit in
a program, then all such interrupts are unreserved. This allows the
program to handle these interrupts, but disables their standard
functions. For example, if this pragma is used, then pressing
Ctrl-C
will not automatically interrupt execution. However,
a program can then handle the SIGINT
interrupt as it chooses.
For a full list of the interrupts handled in a specific implementation,
see the source code for the specification of Ada.Interrupts.Names in
file s-intnam.ads. This is a target dependent file that contains the
list of interrupts recognized for a given target. The documentation in
this file also specifies what interrupts are affected by the use of
the Unreserve_All_Interrupts pragma.
pragma Unsuppress
pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);This pragma undoes the effect of a previous pragma
Suppress
. If
there is no corresponding pragma Suppress
in effect, it has no
effect. The range of the effect is the same as for pragma
Suppress
. The meaning of the arguments is identical to that used
in pragma Suppress
.
One important application is to ensure that checks are on in cases where
code depends on the checks for its correct functioning, so that the code
will compile correctly even if the compiler switches are set to suppress
checks.
pragma Use_VADS_Size
pragma Use_VADS_Size;This is a configuration pragma. In a unit to which it applies, any use of the 'Size attribute is automatically interpreted as a use of the 'VADS_Size attribute. Note that this may result in incorrect semantic processing of valid Ada 95 programs. This is intended to aid in the handling of legacy code which depends on the interpretation of Size as implemented in the VADS compiler. See description of the VADS_Size attribute for further details.
pragma Volatile
pragma Volatile (local_NAME)This pragma is defined by the Ada 95 Reference Manual, and the GNAT implementation is fully conformant with this definition. The reason it is mentioned in this section is that a pragma of the same name was supplied in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation of pragma Volatile is upwards compatible with the implementation in Dec Ada 83.
pragma Warnings
pragma Warnings (On | Off [, LOCAL_NAME]);Normally warnings are enabled, with the output being controlled by the command line switch. Warnings (
Off
) turns off generation of
warnings until a Warnings (On
) is encountered or the end of the
current unit. If generation of warnings is turned off using this
pragma, then no warning messages are output, regardless of the
setting of the command line switches.
The form with a single argument is a configuration pragma.
If the 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 Suppress
).
pragma Weak_External
pragma Weak_External ([Entity =>] LOCAL_NAME);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.
Go to the first, previous, next, last section, table of contents.