| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Ada_05; |
A configuration pragma that establishes Ada 2005 mode for the unit to which
it applies, regardless of the mode set by the command line switches.
This mode is set automatically for the 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 2005 features, but which is intended to be usable from
either Ada 83 or Ada 95 programs.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Annotate (IDENTIFIER {, ARG});
ARG ::= NAME | EXPRESSION
|
This 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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. The pragma expands into code equivalent to the following:
if assertions-enabled then
if not boolean_EXPRESSION then
System.Assertions.Raise_Assert_Failure
(string_EXPRESSION);
end if;
end if;
|
The string argument, if given, is the message that will be associated with the exception occurrence if the exception is raised. If no second argument is given, the default message is `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:
... if J > 3 then pragma Assert (K > 3, "Bad value for K"); null; end if; |
Note that, as with the if statement to which it is equivalent, the
type of the expression is either Standard.Boolean, or any type derived
from this standard type.
If assertions are disabled (switch -gnata not used), then there
is no effect (and in particular, any side effects from the expression
are suppressed). More precisely it is not quite true that the pragma
has no effect, since the expression is analyzed, and may cause types
to be frozen if they are mentioned here for the first time.
If assertions are enabled, then the given expression is tested, and if
it is False then System.Assertions.Raise_Assert_Failure is called
which results in the raising of Assert_Failure with the given message.
If the boolean expression has side effects, these side effects will turn on and off with the setting of the assertions mode, resulting in assertions that have an effect on the program. You should generally avoid side effects in the expression arguments of this pragma. However, the expressions are analyzed for semantic correctness whether or not assertions are enabled, so turning assertions on and off cannot affect the legality of a program.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
If these conditions are met the argument is passed by copy, i.e. in a manner consistent with what C expects if the corresponding formal in the C prototype is a struct (rather than a pointer to a struct).
You can also pass records by copy by specifying the convention
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Comment (static_string_EXPRESSION); |
This is almost identical in effect to pragma Ident. It allows the
placement of a comment into the object file and hence into the
executable file if the operating system permits such usage. The
difference is that Comment, unlike Ident, has
no limitations on placement of the pragma (it can be placed
anywhere in the main source unit), and if more than one pragma
is used, all comments are retained.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Common_Object (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Size =>] EXTERNAL_SYMBOL] );
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
|
This 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.
Common_Object is not supported on all platforms. If no
support is available, then the code generator will issue a message
indicating that the necessary attribute for implementation of this
pragma is not available.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Compile_Time_Warning
(boolean_EXPRESSION, static_string_EXPRESSION);
|
This pragma can be used to generate additional compile time warnings. It is particularly useful in generics, where warnings can be issued for specific problematic instantiations. The first parameter is a boolean expression. The pragma is effective only if the value of this expression is known at compile time, and has the value True. The set of expressions whose values are known at compile time includes all static boolean expressions, and also other values which the compiler can determine at compile time (e.g. the size of a record type set by an explicit size representation clause, or the value of a variable which was initialized to a constant and is known not to have been modified). If these conditions are met, a warning message is generated using the value given as the second argument. This string value may contain embedded ASCII.LF characters to break the message into multiple lines.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Component_Alignment (
[Form =>] ALIGNMENT_CHOICE
[, [Name =>] type_LOCAL_NAME]);
ALIGNMENT_CHOICE ::=
Component_Size
| Component_Size_4
| Storage_Unit
| Default
|
Specifies 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).
If the 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Convention_Identifier (
[Name =>] IDENTIFIER,
[Convention =>] convention_IDENTIFIER);
|
This pragma provides a mechanism for supplying synonyms for existing
convention identifiers. The Name identifier can subsequently
be used as a synonym for the given convention in other pragmas (including
for example pragma Import or another Convention_Identifier
pragma). As an example of the use of this, suppose you had legacy code
which used Fortran77 as the identifier for Fortran. Then the pragma:
pragma Convention_Identifier (Fortran77, Fortran); |
would allow the use of the convention identifier Fortran77 in
subsequent code, avoiding the need to modify the sources. As another
example, you could use this to parametrize convention requirements
according to systems. Suppose you needed to use Stdcall on
windows systems, and C on some other system, then you could
define a convention identifier Library and use a single
Convention_Identifier pragma to specify which convention
would be used system-wide.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
See 10.2 Interfacing to C++ for related information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
where T is a tagged type to which the pragma 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:
Although the constructor is described as a function that returns a value on the Ada side, it is typically a procedure with an extra implicit argument (the object being initialized) at the implementation level. GNAT issues the appropriate call, whatever it is, to get the object properly initialized.
In the case of derived objects, you may use one of two possible forms for declaring and creating an object:
New_Object : Derived_T
New_Object : Derived_T := (constructor-call with ...)
In the first case the default constructor is called and extension fields if any are initialized according to the default initialization expressions in the Ada declaration. In the second case, the given constructor is called and the extension aggregate indicates the explicit values of the extension fields.
If no constructors are imported, it is impossible to create any objects on the Ada side. If no default constructor is imported, only the initialization forms using an explicit call to a constructor are permitted.
Pragma CPP_Constructor is intended primarily for automatic generation
using an automatic binding generator tool.
See 10.2 Interfacing to C++ for more related information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
See 10.2 Interfacing to C++ for related information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
See 10.2 Interfacing to C++ for related information.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON); PROCEDURE_CALL_WITHOUT_SEMICOLON ::= PROCEDURE_NAME | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART |
The argument has the syntactic form of an expression, meeting the syntactic requirements for pragmas.
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 Debug to intersperse calls to
debug procedures in the middle of declarations.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Detect_Blocking; |
This is a configuration pragma that forces the detection of potentially blocking operations within a protected operation, and to raise Program_Error if that happens.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Elaboration_Checks (Dynamic | Static); |
This is a configuration pragma that provides control over the
elaboration model used by the compilation affected by the
pragma. If the parameter is Dynamic,
then the dynamic elaboration
model described in the Ada Reference Manual is used, as though
the -gnatE switch had been specified on the command
line. If the parameter is Static, then the default GNAT static
model is used. This configuration pragma overrides the setting
of the command line. For full details on the elaboration models
used by the GNAT compiler, see section "Elaboration Order
Handling in GNAT" in the GNAT User's Guide.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Eliminate (
[Unit_Name =>] IDENTIFIER |
SELECTED_COMPONENT);
pragma Eliminate (
[Unit_Name =>] IDENTIFIER |
SELECTED_COMPONENT,
[Entity =>] IDENTIFIER |
SELECTED_COMPONENT |
STRING_LITERAL
[,OVERLOADING_RESOLUTION]);
OVERLOADING_RESOLUTION ::= PARAMETER_AND_RESULT_TYPE_PROFILE |
SOURCE_LOCATION
PARAMETER_AND_RESULT_TYPE_PROFILE ::= PROCEDURE_PROFILE |
FUNCTION_PROFILE
PROCEDURE_PROFILE ::= Parameter_Types => PARAMETER_TYPES
FUNCTION_PROFILE ::= [Parameter_Types => PARAMETER_TYPES,]
Result_Type => result_SUBTYPE_NAME]
PARAMETER_TYPES ::= (SUBTYPE_NAME {, SUBTYPE_NAME})
SUBTYPE_NAME ::= STRING_VALUE
SOURCE_LOCATION ::= Source_Location => SOURCE_TRACE
SOURCE_TRACE ::= STRING_VALUE
STRING_VALUE ::= STRING_LITERAL {& STRING_LITERAL}
|
This pragma indicates that the given entity is not used outside the compilation unit it is defined in. The entity must be an explicitly declared subprogram; this includes generic subprogram instances and subprograms declared in generic package instances.
If the entity to be eliminated is a library level subprogram, then
the first form of pragma Eliminate is used with only a single argument.
In this form, the Unit_Name argument specifies the name of the
library level unit to be eliminated.
In all other cases, both Unit_Name and Entity arguments
are required. If item is an entity of a library package, then the first
argument specifies the unit name, and the second argument specifies
the particular entity. If the second argument is in string form, it must
correspond to the internal manner in which GNAT stores entity names (see
compilation unit Namet in the compiler sources for details).
The remaining parameters (OVERLOADING_RESOLUTION) are optionally used to distinguish between overloaded subprograms. If a pragma does not contain the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded subprograms denoted by the first two parameters.
Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram
to be eliminated in a manner similar to that used for the extended
Import and Export pragmas, except that the subtype names are
always given as strings. At the moment, this form of distinguishing
overloaded subprograms is implemented only partially, so we do not recommend
using it for practical subprogram elimination.
Note, that in case of a parameterless procedure its profile is represented
as Parameter_Types => ("")
Alternatively, the Source_Location parameter is used to specify
which overloaded alternative is to be eliminated by pointing to the
location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the
source text. The string literal (or concatenation of string literals)
given as SOURCE_TRACE must have the following format:
SOURCE_TRACE ::= SOURCE_LOCATION{LBRACKET SOURCE_LOCATION RBRACKET}
LBRACKET ::= [
RBRACKET ::= ]
SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER
FILE_NAME ::= STRING_LITERAL
LINE_NUMBER ::= DIGIT {DIGIT}
|
SOURCE_TRACE should be the short name of the source file (with no directory information), and LINE_NUMBER is supposed to point to the line where the defining name of the subprogram is located.
For the subprograms that are not a part of generic instantiations, only one SOURCE_LOCATION is used. If a subprogram is declared in a package instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the second one denotes the declaration of the corresponding subprogram in the generic package. This approach is recursively used to create SOURCE_LOCATIONs in case of nested instantiations.
The effect of the pragma is to allow the compiler to eliminate the code or data associated with the named entity. Any reference to an eliminated entity outside the compilation unit it is defined in, causes a compile time or link time error.
The intention of pragma Eliminate is to allow a program to be compiled
in a system independent manner, with unused entities eliminated, without
the requirement of modifying the source text. Normally the required set
of Eliminate pragmas is constructed automatically using the gnatelim
tool. Elimination of unused entities local to a compilation unit is
automatic, without requiring the use of pragma Eliminate.
Note that the reason this pragma takes string literals where names might
be expected is that a pragma Eliminate can appear in a context where the
relevant names are not visible.
Note that any change in the source files that includes removing, splitting of adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION parameter illegal.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Export_Exception (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL,]
[, [Form =>] Ada | VMS]
[, [Code =>] static_integer_EXPRESSION]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
|
This pragma is implemented only in the OpenVMS implementation of GNAT. It causes the specified exception to be propagated outside of the Ada program, so that it can be handled by programs written in other OpenVMS languages. This pragma establishes an external name for an Ada exception and makes the name available to the OpenVMS Linker as a global symbol. For further details on this pragma, see the DEC Ada Language Reference Manual, section 13.9a3.2.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Syntax:
pragma Export_Function (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Result_Type =>] result_SUBTYPE_MARK]
[, [Mechanism =>] MECHANISM]
[, [Result_Mechanism =>] MECHANISM_NAME]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
| ""
PARAMETER_TYPES ::=
null
| TYPE_DESIGNATOR {, TYPE_DESIGNATOR}
TYPE_DESIGNATOR ::=
subtype_NAME
| subtype_Name ' Access
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
|
Use this pragma to make a function externally callable and optionally
provide information on mechanisms to be used for passing parameter and
result values. We recommend, for the purposes of improving portability,
this pragma always be used in conjunction with a separate pragma
Export, which must precede the pragma Export_Function.
GNAT does not require a separate pragma Export, but if none is
present, Convention Ada is assumed, which is usually
not what is wanted, so it is usually appropriate to use this
pragma in conjunction with a Export or Convention
pragma that specifies the desired foreign convention.
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.
The form with an 'Access attribute can be used to match an
anonymous access parameter.
Note that passing by descriptor is not supported, even on the OpenVMS ports of GNAT.
Special treatment is given if the EXTERNAL is an explicit null string or a static string expressions that evaluates to the null string. In this case, no external name is generated. This form still allows the specification of parameter mechanisms.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Export_Object
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Size =>] EXTERNAL_SYMBOL]
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
|
This pragma designates an object as exported, and apart from the
extended rules for external symbols, is identical in effect to the use of
the normal 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Export_Procedure (
[Internal =>] LOCAL_NAME
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
| ""
PARAMETER_TYPES ::=
null
| TYPE_DESIGNATOR {, TYPE_DESIGNATOR}
TYPE_DESIGNATOR ::=
subtype_NAME
| subtype_Name ' Access
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
|
This 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.
GNAT does not require a separate pragma Export, but if none is
present, Convention Ada is assumed, which is usually
not what is wanted, so it is usually appropriate to use this
pragma in conjunction with a Export or Convention
pragma that specifies the desired foreign convention.
Note that passing by descriptor is not supported, even on the OpenVMS ports of GNAT.
Special treatment is given if the EXTERNAL is an explicit null string or a static string expressions that evaluates to the null string. In this case, no external name is generated. This form still allows the specification of parameter mechanisms.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Export_Value ( [Value =>] static_integer_EXPRESSION, [Link_Name =>] static_string_EXPRESSION); |
This pragma serves to export a static integer value for external use. The first argument specifies the value to be exported. The Link_Name argument specifies the symbolic name to be associated with the integer value. This pragma is useful for defining a named static value in Ada that can be referenced in assembly language units to be linked with the application. This pragma is currently supported only for the AAMP target and is ignored for other targets.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Export_Valued_Procedure (
[Internal =>] LOCAL_NAME
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
| ""
PARAMETER_TYPES ::=
null
| TYPE_DESIGNATOR {, TYPE_DESIGNATOR}
TYPE_DESIGNATOR ::=
subtype_NAME
| subtype_Name ' Access
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
|
This 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).
GNAT does not require a separate pragma Export, but if none is
present, Convention Ada is assumed, which is almost certainly
not what is wanted since the whole point of this pragma is to interface
with foreign language functions, so it is usually appropriate to use this
pragma in conjunction with a Export or Convention
pragma that specifies the desired foreign convention.
Note that passing by descriptor is not supported, even on the OpenVMS ports of GNAT.
Special treatment is given if the EXTERNAL is an explicit null string or a static string expressions that evaluates to the null string. In this case, no external name is generated. This form still allows the specification of parameter mechanisms.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
You can use this pragma either to access a predefined System
extension supplied with the compiler, for example Aux_DEC or
you can construct your own extension unit following the above
definition. Note that such a package is a child of System
and thus is considered part of the implementation. To compile
it you will have to use the appropriate switch for compiling
system units. See the GNAT User's Guide for details.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma External ( [ Convention =>] convention_IDENTIFIER, [ Entity =>] local_NAME [, [External_Name =>] static_string_EXPRESSION ] [, [Link_Name =>] static_string_EXPRESSION ]); |
This pragma is identical in syntax and semantics to pragma
Export as defined in the Ada Reference Manual. It is
provided for compatibility with some Ada 83 compilers that
used this pragma for exactly the same purposes as pragma
Export before the latter was standardized.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma External_Name_Casing ( Uppercase | Lowercase [, Uppercase | Lowercase | As_Is]); |
This pragma provides control over the casing of external names associated with Import and Export pragmas. There are two cases to consider:
pragma Import (C, C_Routine); |
Since Ada is a case insensitive language, the spelling of the identifier in
the Ada source program does not provide any information on the desired
casing of the external name, and so a convention is needed. In GNAT the
default treatment is that such names are converted to all lower case
letters. This corresponds to the normal C style in many environments.
The first argument of pragma External_Name_Casing can be used to
control this treatment. If Uppercase is specified, then the name
will be forced to all uppercase letters. If Lowercase is specified,
then the normal default of all lower case letters will be used.
This same implicit treatment is also used in the case of extended DEC Ada 83 compatible Import and Export pragmas where an external name is explicitly specified using an identifier rather than a string.
pragma Import (C, C_Routine, "C_routine"); |
In this case, the string literal normally provides the exact casing required
for the external name. The second argument of pragma
External_Name_Casing may be used to modify this behavior.
If Uppercase is specified, then the name
will be forced to all uppercase letters. If Lowercase is specified,
then the name will be forced to all lowercase letters. A specification of
As_Is provides the normal default behavior in which the casing is
taken from the string provided.
This pragma may appear anywhere that a pragma is valid. In particular, it can be used as a configuration pragma in the `gnat.adc' file, in which case it applies to all subsequent compilations, or it can be used as a program unit pragma, in which case it only applies to the current unit, or it can be used more locally to control individual Import/Export pragmas.
It is primarily intended for use with OpenVMS systems, where many compilers convert all symbols to upper case by default. For interfacing to such compilers (e.g. the DEC C compiler), it may be convenient to use the pragma:
pragma External_Name_Casing (Uppercase, Uppercase); |
to enforce the upper casing of all external symbols.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Float_Representation (FLOAT_REP); FLOAT_REP ::= VAX_Float | IEEE_Float |
This pragma
allows control over the internal representation chosen for the predefined
floating point types declared in the packages Standard and
System. On all systems other than OpenVMS, the argument must
be IEEE_Float and the pragma has no effect. On OpenVMS, the
argument may be VAX_Float to specify the use of the VAX float
format for the floating-point types in Standard. This requires that
the standard runtime libraries be recompiled. See the
description of the GNAT LIBRARY command in the OpenVMS version
of the GNAT Users Guide for details on the use of this command.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
This pragma is allowed only in the outermost declarative part or
declarative items of a compilation unit. If more than one Ident
pragma is given, only the last one processed is effective.
On OpenVMS systems, the effect of the pragma is identical to the effect of
the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the
maximum allowed length is 31 characters, so if it is important to
maintain compatibility with this compiler, you should obey this length
limit.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Import_Exception (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL,]
[, [Form =>] Ada | VMS]
[, [Code =>] static_integer_EXPRESSION]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
|
This pragma is implemented only in the OpenVMS implementation of GNAT. It allows OpenVMS conditions (for example, from OpenVMS system services or other OpenVMS languages) to be propagated to Ada programs as Ada exceptions. The pragma specifies that the exception associated with an exception declaration in an Ada program be defined externally (in non-Ada code). For further details on this pragma, see the DEC Ada Language Reference Manual, section 13.9a.3.1.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Import_Function (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Result_Type =>] SUBTYPE_MARK]
[, [Mechanism =>] MECHANISM]
[, [Result_Mechanism =>] MECHANISM_NAME]
[, [First_Optional_Parameter =>] IDENTIFIER]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
PARAMETER_TYPES ::=
null
| TYPE_DESIGNATOR {, TYPE_DESIGNATOR}
TYPE_DESIGNATOR ::=
subtype_NAME
| subtype_Name ' Access
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
|
This 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 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.
The form with an 'Access attribute can be used to match an
anonymous access parameter.
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 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Import_Object
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL],
[, [Size =>] EXTERNAL_SYMBOL]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
|
This pragma designates an object as imported, and apart from the
extended rules for external symbols, is identical in effect to the use of
the normal 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Import_Procedure (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]
[, [First_Optional_Parameter =>] IDENTIFIER]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
PARAMETER_TYPES ::=
null
| TYPE_DESIGNATOR {, TYPE_DESIGNATOR}
TYPE_DESIGNATOR ::=
subtype_NAME
| subtype_Name ' Access
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
|
This 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Import_Valued_Procedure (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]
[, [First_Optional_Parameter =>] IDENTIFIER]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
PARAMETER_TYPES ::=
null
| TYPE_DESIGNATOR {, TYPE_DESIGNATOR}
TYPE_DESIGNATOR ::=
subtype_NAME
| subtype_Name ' Access
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
|
This 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.
Note that it is important to use this pragma in conjunction with a separate pragma Import that specifies the desired convention, since otherwise the default convention is Ada, which is almost certainly not what is required.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Initialize_Scalars; |
This pragma is similar to Normalize_Scalars conceptually but has
two important differences. First, there is no requirement for the pragma
to be used uniformly in all units of a partition, in particular, it is fine
to use this just for some or all of the application units of a partition,
without needing to recompile the run-time library.
In the case where some units are compiled with the pragma, and some without, then a declaration of a variable where the type is defined in package Standard or is locally declared will always be subject to initialization, as will any declaration of a scalar variable. For composite variables, whether the variable is initialized may also depend on whether the package in which the type of the variable is declared is compiled with the pragma.
The other important difference is that you can control the value used for initializing scalar objects. At bind time, you can select several options for initialization. You can initialize with invalid values (similar to Normalize_Scalars, though for Initialize_Scalars it is not always possible to determine the invalid values in complex cases like signed component fields with non-standard sizes). You can also initialize with high or low values, or with a specified bit pattern. See the users guide for binder options for specifying these cases.
This means that you can compile a program, and then without having to recompile the program, you can run it with different values being used for initializing otherwise uninitialized values, to test if your program behavior depends on the choice. Of course the behavior should not change, and if it does, then most likely you have an erroneous reference to an uninitialized value.
It is even possible to change the value at execution time eliminating even the need to rebind with a different switch using an environment variable. See the GNAT users guide for details.
Note that pragma Initialize_Scalars is particularly useful in
conjunction with the enhanced validity checking that is now provided
in GNAT, which checks for invalid values under more conditions.
Using this feature (see description of the -gnatV flag in the
users guide) in conjunction with pragma Initialize_Scalars
provides a powerful new tool to assist in the detection of problems
caused by uninitialized variables.
Note: the use of Initialize_Scalars has a fairly extensive
effect on the generated code. This may cause your code to be
substantially larger. It may also cause an increase in the amount
of stack required, so it is probably a good idea to turn on stack
checking (see description of stack checking in the GNAT users guide)
when using this pragma.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Inline_Always (NAME [, NAME]); |
Similar to pragma Inline except that inlining is not subject to
the use of option -gnatn and the inlining happens regardless of
whether this option is used.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Interface (
[Convention =>] convention_identifier,
[Entity =>] local_name
[, [External_Name =>] static_string_expression],
[, [Link_Name =>] static_string_expression]);
|
This pragma is identical in syntax and semantics to
the standard Ada 95 pragma Import. It is provided for compatibility
with Ada 83. The definition is upwards compatible both with pragma
Interface as defined in the Ada 83 Reference Manual, and also
with some extended implementations of this pragma in certain Ada 83
implementations.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Interrupt_Handler (procedure_LOCAL_NAME); |
This program unit pragma is supported for parameterless protected procedures
as described in Annex C of the Ada Reference Manual. On the AAMP target
the pragma can also be specified for nonprotected parameterless procedures
that are declared at the library level (which includes procedures
declared at the top level of a library package). In the case of AAMP,
when this pragma is applied to a nonprotected procedure, the instruction
IERET is generated for returns from the procedure, enabling
maskable interrupts, in place of the normal return instruction.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Interrupt_State (Name => value, State => SYSTEM | RUNTIME | USER); |
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. Additionally, signals such as SIGSEGV,
SIGABRT, SIGFPE and SIGILL are often mapped to specific
Ada exceptions, or used to implement run-time functions such as the
abort statement and stack overflow checking.
Pragma Interrupt_State provides a general mechanism for overriding
such uses of interrupts. It subsumes the functionality of pragma
Unreserve_All_Interrupts. Pragma Interrupt_State is not
available on OS/2, Windows or VMS. On all other platforms than VxWorks,
it applies to signals; on VxWorks, it applies to vectored hardware interrupts
and may be used to mark interrupts required by the board support package
as reserved.
Interrupts can be in one of three states:
The interrupt is reserved (no Ada handler can be installed), and the Ada run-time may not install a handler. As a result you are guaranteed standard system default action if this interrupt is raised.
The interrupt is reserved (no Ada handler can be installed). The run time is allowed to install a handler for internal control purposes, but is not required to do so.
The interrupt is unreserved. The user may install a handler to provide some other action.
These states are the allowed values of the State parameter of the
pragma. The Name parameter is a value of the type
Ada.Interrupts.Interrupt_ID. Typically, it is a name declared in
Ada.Interrupts.Names.
This is a configuration pragma, and the binder will check that there are no inconsistencies between different units in a partition in how a given interrupt is specified. It may appear anywhere a pragma is legal.
The effect is to move the interrupt to the specified state.
By declaring interrupts to be SYSTEM, you guarantee the standard system action, such as a core dump.
By declaring interrupts to be USER, you guarantee that you can install a handler.
Note that certain signals on many operating systems cannot be caught and
handled by applications. In such cases, the pragma is ignored. See the
operating system documentation, or the value of the array Reserved
declared in the specification of package System.OS_Interface.
Overriding the default state of signals used by the Ada runtime may interfere
with an application's runtime behavior in the cases of the synchronous signals,
and in the case of the signal used to implement the abort statement.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); |
The LOCAL_NAME argument
must refer to an enumeration first subtype
in the current declarative part. The effect is to retain the enumeration
literal names for use by Image and Value even if a global
Discard_Names pragma applies. This is useful when you want to
generally suppress enumeration literal names and for example you therefore
use a Discard_Names pragma in the `gnat.adc' file, but you
want to retain the names for specific enumeration types.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma License (Unrestricted | GPL | Modified_GPL | Restricted); |
This pragma is provided to allow automated checking for appropriate license
conditions with respect to the standard and modified GPL. A pragma
License, which is a configuration pragma that typically appears at
the start of a source file or in a separate `gnat.adc' file, specifies
the licensing conditions of a unit as follows:
with'ed by a restricted unit.
with units
which are licensed under the modified GPL (this is the whole point of the
modified GPL).
Normally a unit with no License pragma is considered to have an
unknown license, and no checking is done. However, standard GNAT headers
are recognized, and license information is derived from them as follows.
These default actions means that a program with a restricted license pragma
will automatically get warnings if a GPL unit is inappropriately
with'ed. For example, the program:
with Sem_Ch3; with GNAT.Sockets; procedure Secret_Stuff is ... end Secret_Stuff |
if compiled with pragma License (Restricted) in a
`gnat.adc' file will generate the warning:
1. with Sem_Ch3;
|
>>> license of withed unit "Sem_Ch3" is incompatible
2. with GNAT.Sockets;
3. procedure Secret_Stuff is
|
Here we get a warning on Sem_Ch3 since it is part of the GNAT
compiler and is licensed under the
GPL, but no warning for GNAT.Sockets which is part of the GNAT
run time, and is therefore licensed under the modified GPL.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Link_With (static_string_EXPRESSION {,static_string_EXPRESSION});
|
This pragma is provided for compatibility with certain Ada 83 compilers.
It has exactly the same effect as pragma Linker_Options except
that spaces occurring within one of the string expressions are treated
as separators. For example, in the following case:
pragma Link_With ("-labc -ldef");
|
results in passing the strings -labc and -ldef as two
separate arguments to the linker. In addition pragma Link_With allows
multiple arguments, with the same effect as successive pragmas.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Long_Float (FLOAT_FORMAT); FLOAT_FORMAT ::= D_Float | G_Float |
This 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 through 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 User's Guide for details on the use of this command.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Machine_Attribute ( [Attribute_Name =>] string_EXPRESSION, [Entity =>] LOCAL_NAME); |
Machine-dependent attributes can be specified for types and/or
declarations. This pragma is semantically equivalent to
__attribute__((string_expression)) in GNU C,
where string_expression is
recognized by the target macro TARGET_ATTRIBUTE_TABLE which is
defined for each machine. See the GCC manual for further information.
It is not possible to specify attributes defined by other languages,
only attributes defined by the machine the code is intended to run on.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Main_Storage (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); MAIN_STORAGE_OPTION ::= [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION | [TOP_GUARD =>] static_SIMPLE_EXPRESSION |
This pragma is provided for compatibility with OpenVMS VAX Systems. It has no effect in GNAT, other than being syntax checked. Note that the pragma also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
Standard.Wide_Wide_Character
Integer types
For subtypes with negative values present, the largest negative number is used, except in the unusual case where this largest negative number is in the subtype, and the largest positive number is not, in which case the largest positive value is used. This choice will always generate an invalid value if one exists.
Floating-Point Types
Fixed-Point Types
Modular types
Enumeration types
2 ** typ'Size - 1 unless the subtype excludes the literal
whose Pos value is zero, in which case a code of zero is used. This choice
will always generate an invalid value if one exists.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Obsolescent [(static_string_EXPRESSION [,Ada_05])]; |
This pragma must occur immediately following a subprogram declaration. It indicates that the associated function or procedure is considered obsolescent and should not be used. Typically this is used when an API must be modified by eventually removing or modifying existing subprograms. The pragma can be used at an intermediate stage when the subprogram is still present, but will be removed later.
The effect of this pragma is to output a warning message that the subprogram is obsolescent if the appropriate warning option in the compiler is activated. If a parameter is present, then a second warning message is given containing this text.
In addition, a call to such a program is considered a violation of pragma Restrictions (No_Obsolescent_Features).
If the optional second parameter is present (which must be exactly the identifier Ada_05, no other argument is allowed), then the indication of obsolescence applies only when compiling in Ada 2005 mode. This is primarily intended for dealing with the situations in the predefined library where subprograms have become defined as obsolescent in Ada 2005 (e.g. in Ada.Characters.Handling), but may be used anywhere.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 the argument is omitted, then DEC Ada 83
treats the pragma as an assertion that the containing task is passive
and that optimization of context switch with this task is permitted and
desired. If the argument 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).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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' and `a-except.adb'.
A standard alternative unit (in file `4wexcpol.adb' in the standard GNAT
distribution) is used to enable the asynchronous abort capability on
targets that do not normally support the capability. The version of
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Profile (Ravenscar); |
A configuration pragma that establishes the following set of configuration pragmas:
Task_Dispatching_Policy (FIFO_Within_Priorities)
Locking_Policy (Ceiling_Locking)
plus the following set of restrictions:
Max_Entry_Queue_Length = 1
Max_Protected_Entries = 1
Max_Task_Entries = 0
No_Abort_Statements
No_Asynchronous_Control
No_Calendar
No_Dynamic_Attachment
No_Dynamic_Priorities
No_Implicit_Heap_Allocations
No_Local_Protected_Objects
No_Protected_Type_Allocators
No_Relative_Delay
No_Requeue_Statements
No_Select_Statements
No_Task_Allocators
No_Task_Attributes_Package
No_Task_Hierarchy
No_Task_Termination
Simple_Barriers
This set of configuration pragmas and restrictions correspond to the definition of the "Ravenscar Profile" for limited tasking, devised and published by the International Real-Time Ada Workshop, 1997, and whose most recent description is available at ftp://ftp.openravenscar.org/openravenscar/ravenscar00.pdf.
The original definition of the profile was revised at subsequent IRTAW meetings. It has been included in the ISO Guide for the Use of the Ada Programming Language in High Integrity Systems, and has been approved by ISO/IEC/SC22/WG9 for inclusion in the next revision of the standard. The formal definition given by the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and AI-305) available at http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00249.TXT and http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00305.TXT respectively.
The above set is a superset of the restrictions provided by pragma
Profile (Restricted), it includes six additional restrictions
(Simple_Barriers, No_Select_Statements,
No_Calendar, No_Implicit_Heap_Allocations,
No_Relative_Delay and No_Task_Termination). This means
that pragma Profile (Ravenscar), like the pragma
Profile (Restricted),
automatically causes the use of a simplified,
more efficient version of the tasking run-time system.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Profile (Restricted); |
A configuration pragma that establishes the following set of restrictions:
This set of restrictions causes the automatic selection of a simplified version of the run time that provides improved performance for the limited set of tasking functionality permitted by this set of restrictions.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Propagate_Exceptions (subprogram_LOCAL_NAME); |
This pragma indicates that the given entity, which is the name of an
imported foreign-language subprogram may receive an Ada exception,
and that the exception should be propagated. It is relevant only if
zero cost exception handling is in use, and is thus never needed if
the alternative longjmp / setjmp implementation of
exceptions is used (although it is harmless to use it in such cases).
The implementation of fast exceptions always properly propagates
exceptions through Ada code, as described in the Ada Reference Manual.
However, this manual is silent about the propagation of exceptions
through foreign code. For example, consider the
situation where 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Psect_Object (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Size =>] EXTERNAL_SYMBOL]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
|
This pragma is identical in effect to pragma Common_Object.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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). It 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: Most functions in a Pure package are automatically pure, and
there is no need to use pragma Pure_Function for such functions. One
exception is any function that has at least one formal of type
System.Address or a type derived from it. Such functions are not
considered pure by default, since the compiler assumes that the
Address parameter may be functioning as a pointer and that the
referenced data may change even if the address value does not.
Similarly, imported functions are not considered to be pure by default,
since there is no way of checking that they are in fact pure. The use
of pragma Pure_Function for such a function will override these default
assumption, and cause the compiler to treat a designated subprogram as pure
in these cases.
Note: If pragma 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Restriction_Warnings
(restriction_IDENTIFIER {, restriction_IDENTIFIER});
|
This pragma allows a series of restriction identifiers to be
specified (the list of allowed identifiers is the same as for
pragma Restrictions). For each of these identifiers
the compiler checks for violations of the restriction, but
generates a warning message rather than an error message
if the restriction is violated.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Source_File_Name ( [Unit_Name =>] unit_NAME, Spec_File_Name => STRING_LITERAL); pragma Source_File_Name ( [Unit_Name =>] unit_NAME, Body_File_Name => STRING_LITERAL); |
Use this to override the normal naming convention. It is a configuration pragma, and so has the usual applicability of configuration pragmas (i.e. it applies to either an entire partition, or to all units in a compilation, or to a single unit, depending on how it is used. 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.
Another form of the Source_File_Name pragma allows
the specification of patterns defining alternative file naming schemes
to apply to all files.
pragma Source_File_Name (Spec_File_Name => STRING_LITERAL [,Casing => CASING_SPEC] [,Dot_Replacement => STRING_LITERAL]); pragma Source_File_Name (Body_File_Name => STRING_LITERAL [,Casing => CASING_SPEC] [,Dot_Replacement => STRING_LITERAL]); pragma Source_File_Name (Subunit_File_Name => STRING_LITERAL [,Casing => CASING_SPEC] [,Dot_Replacement => STRING_LITERAL]); CASING_SPEC ::= Lowercase | Uppercase | Mixedcase |
The first argument is a pattern that contains a single asterisk indicating the point at which the unit name is to be inserted in the pattern string to form the file name. The second argument is optional. If present it specifies the casing of the unit name in the resulting file name string. The default is lower case. Finally the third argument allows for systematic replacement of any dots in the unit name by the specified string literal.
A pragma Source_File_Name cannot appear after a Pragma Source_File_Name_Project.
For more details on the use of the Source_File_Name pragma,
see the sections "Using Other File Names" and
"Alternative File Naming Schemes" in the GNAT User's Guide.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This pragma has the same syntax and semantics as pragma Source_File_Name. It is only allowed as a stand alone configuration pragma. It cannot appear after a Pragma Source_File_Name, and most importantly, once pragma Source_File_Name_Project appears, no further Source_File_Name pragmas are allowed.
The intention is that Source_File_Name_Project pragmas are always generated by the Project Manager in a manner consistent with the naming specified in a project file, and when naming is controlled in this manner, it is not permissible to attempt to modify this naming scheme using Source_File_Name pragmas (which would not be known to the project manager).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); |
This pragma must appear 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Style_Checks (string_LITERAL | ALL_CHECKS |
On | Off [, LOCAL_NAME]);
|
This pragma is used in conjunction with compiler switches to control the built in style checking provided by GNAT. The compiler switches, if set, provide an initial setting for the switches, and this pragma may be used to modify these settings, or the settings may be provided entirely by the use of the pragma. This pragma can be used anywhere that a pragma is legal, including use as a configuration pragma (including use in the `gnat.adc' file).
The form with a string literal specifies which style options are to be
activated. These are additive, so they apply in addition to any previously
set style check options. The codes for the options are the same as those
used in the -gnaty switch to gcc or gnatmake.
For example the following two methods can be used to enable
layout checking:
pragma Style_Checks ("l");
|
gcc -c -gnatyl ... |
The form ALL_CHECKS activates all standard checks (its use is equivalent
to the use of the gnaty switch with no options. See GNAT User's
Guide for details.
The forms with Off and On
can be used to temporarily disable style checks
as shown in the following example:
pragma Style_Checks ("k"); -- requires keywords in lower case
pragma Style_Checks (Off); -- turn off style checks
NULL; -- this will not generate an error message
pragma Style_Checks (On); -- turn style checks back on
NULL; -- this will generate an error message
|
Finally the two argument form is allowed only if the first argument is
On or Off. The effect is to turn of semantic style checks
for the specified entity, as shown in the following example:
pragma Style_Checks ("r"); -- require consistency of identifier casing
Arg : Integer;
Rf1 : Integer := ARG; -- incorrect, wrong case
pragma Style_Checks (Off, Arg);
Rf2 : Integer := ARG; -- OK, no error
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Subtitle ([Subtitle =>] STRING_LITERAL); |
This pragma is recognized for compatibility with other Ada compilers but is ignored by GNAT.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Suppress_Exception_Locations; |
In normal mode, a raise statement for an exception by default generates
an exception message giving the file name and line number for the location
of the raise. This is useful for debugging and logging purposes, but this
entails extra space for the strings for the messages. The configuration
pragma Suppress_Exception_Locations can be used to suppress the
generation of these strings, with the result that space is saved, but the
exception message for such raises is null. This configuration pragma may
appear in a global configuration pragma file, or in a specific unit as
usual. It is not required that this pragma be used consistently within
a partition, so it is fine to have some units within a partition compiled
with this pragma and others compiled in normal mode without it.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
aspects of tasking implementation, for example, the ability to map
tasks to specific processors. For details on the facilities available
for the version of GNAT that you are using, see the documentation
in the specification of package System.Task_Info in the runtime
library.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Task_Name (string_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 String, and provides a name to be used for
the task instance when the task is created. Note that this expression
is not required to be static, and in particular, it can contain
references to task discriminants. This facility can be used to
provide different names for different tasks as they are created,
as illustrated in the example below.
The task name is recorded internally in the run-time structures
and is accessible to tools like the debugger. In addition the
routine Ada.Task_Identification.Image will return this
string, with a unique task address appended.
-- Example of the use of pragma Task_Name
with Ada.Task_Identification;
use Ada.Task_Identification;
with Text_IO; use Text_IO;
procedure t3 is
type Astring is access String;
task type Task_Typ (Name : access String) is
pragma Task_Name (Name.all);
end Task_Typ;
task body Task_Typ is
Nam : constant String := Image (Current_Task);
begin
Put_Line ("-->" & Nam (1 .. 14) & "<--");
end Task_Typ;
type Ptr_Task is access Task_Typ;
Task_Var : Ptr_Task;
begin
Task_Var :=
new Task_Typ (new String'("This is task 1"));
Task_Var :=
new Task_Typ (new String'("This is task 2"));
end;
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Thread_Body ( [Entity =>] LOCAL_NAME, [[Secondary_Stack_Size =>] static_integer_EXPRESSION)]; |
This pragma specifies that the subprogram whose name is given as the
Entity argument is a thread body, which will be activated
by being called via its Address from foreign code. The purpose is
to allow execution and registration of the foreign thread within the
Ada run-time system.
See the library unit System.Threads for details on the expansion of
a thread body subprogram, including the calls made to subprograms
within System.Threads to register the task. This unit also lists the
targets and runtime systems for which this pragma is supported.
A thread body subprogram may not be called directly from Ada code, and it is not permitted to apply the Access (or Unrestricted_Access) attributes to such a subprogram. The only legitimate way of calling such a subprogram is to pass its Address to foreign code and then make the call from the foreign code.
A thread body subprogram may have any parameters, and it may be a function
returning a result. The convention of the thread body subprogram may be
set in the usual manner using pragma Convention.
The secondary stack size parameter, if given, is used to set the size
of secondary stack for the thread. The secondary stack is allocated as
a local variable of the expanded thread body subprogram, and thus is
allocated out of the main thread stack size. If no secondary stack
size parameter is present, the default size (from the declaration in
System.Secondary_Stack is used.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Title (TITLING_OPTION [, TITLING OPTION]); TITLING_OPTION ::= [Title =>] STRING_LITERAL, | [Subtitle =>] STRING_LITERAL |
Syntax checked but otherwise ignored by GNAT. This is a listing control pragma used in DEC Ada 83 implementations to provide a title and/or subtitle for the program listing. The program listing generated by GNAT does not have titles or subtitles.
Unlike other pragmas, the full flexibility of named notation is allowed for this pragma, i.e. the parameters may be given in any order if named notation is used, and named and positional notation can be mixed following the normal rules for procedure calls in Ada.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
In addition, given a type that meets the above requirements, the following restrictions apply to its use throughout the program:
Equality and inequality operations on 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Universal_Data [(library_unit_Name)]; |
This pragma is supported only for the AAMP target and is ignored for other targets. The pragma specifies that all library-level objects (Counter 0 data) associated with the library unit are to be accessed and updated using universal addressing (24-bit addresses for AAMP5) rather than the default of 16-bit Data Environment (DENV) addressing. Use of this pragma will generally result in less efficient code for references to global data associated with the library unit, but allows such data to be located anywhere in memory. This pragma is a library unit pragma, but can also be used as a configuration pragma (including use in the `gnat.adc' file). The functionality of this pragma is also available by applying the -univ switch on the compilations of units where universal addressing of the data is desired.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Unreferenced (local_Name {, local_Name});
|
This pragma signals that the entities whose names are listed are deliberately not referenced in the current source unit. This suppresses warnings about the entities being unreferenced, and in addition a warning will be generated if one of these entities is in fact referenced in the same unit as the pragma (or in the corresponding body, or one of its subunits).
This is particularly useful for clearly signaling that a particular parameter is not referenced in some particular subprogram implementation and that this is deliberate. It can also be useful in the case of objects declared only for their initialization or finalization side effects.
If 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 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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 a 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 `a-intnam.ads'. This is a target dependent file that contains the
list of interrupts recognized for a given target. The documentation in
this file also specifies what interrupts are affected by the use of
the Unreserve_All_Interrupts pragma.
For a more general facility for controlling what interrupts can be
handled, see pragma Interrupt_State, which subsumes the functionality
of the Unreserve_All_Interrupts pragma.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); |
This pragma is used in conjunction with compiler switches to control the built-in validity checking provided by GNAT. The compiler switches, if set provide an initial setting for the switches, and this pragma may be used to modify these settings, or the settings may be provided entirely by the use of the pragma. This pragma can be used anywhere that a pragma is legal, including use as a configuration pragma (including use in the `gnat.adc' file).
The form with a string literal specifies which validity options are to be
activated. The validity checks are first set to include only the default
reference manual settings, and then a string of letters in the string
specifies the exact set of options required. The form of this string
is exactly as described for the -gnatVx compiler switch (see the
GNAT users guide for details). For example the following two methods
can be used to enable validity checking for mode in and
in out subprogram parameters:
pragma Validity_Checks ("im");
|
gcc -c -gnatVim ... |
The form ALL_CHECKS activates all standard checks (its use is equivalent
to the use of the gnatva switch.
The forms with Off and On
can be used to temporarily disable validity checks
as shown in the following example:
pragma Validity_Checks ("c"); -- validity checks for copies
pragma Validity_Checks (Off); -- turn off validity checks
A := B; -- B will not be validity checked
pragma Validity_Checks (On); -- turn validity checks back on
A := C; -- C will be validity checked
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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).
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |