Node: Implementation Defined Pragmas, Next: Implementation Defined Attributes, Previous: About This Guide, Up: Top
Ada 95 defines a set of pragmas that can be used to supply additional information to the compiler. These language defined pragmas are implemented in GNAT and work as described in the Ada 95 Reference Manual.
In addition, Ada 95 allows implementations to define additional pragmas whose meaning is defined by the implementation. GNAT provides a number of these implementation-dependent pragmas which can be used to extend and enhance the functionality of the compiler. This section of the GNAT Reference Manual describes these additional pragmas.
Note that any program using these pragmas may not be portable to other compilers (although GNAT implements this set of pragmas on all platforms). Therefore if portability to other compilers is an important consideration, the use of these pragmas should be minimized.
pragma Abort_Defer
pragma Abort_Defer;
This pragma must appear at the start of the statement sequence of a
handled sequence of statements (right after the begin). It has
the effect of deferring aborts for the sequence of statements (but not
for the declarations or handlers, if any, associated with this statement
sequence).
pragma Ada_83
Syntax:
pragma Ada_83;
A configuration pragma that establishes Ada 83 mode for the unit to which it applies, regardless of the mode set by the command line switches. In Ada 83 mode, GNAT attempts to be as compatible with the syntax and semantics of Ada 83, as defined in the original Ada 83 Reference Manual as possible. In particular, the new Ada 95 keywords are not recognized, optional package bodies are allowed, and generics may name types with unknown discriminants without using the (<>) notation. In addition, some but not all of the additional restrictions of Ada 83 are enforced.
Ada 83 mode is intended for two purposes. Firstly, it allows existing
legacy Ada 83 code to be compiled and adapted to GNAT with less effort.
Secondly, it aids in keeping code backwards compatible with Ada 83.
However, there is no guarantee that code that is processed correctly
by GNAT in Ada 83 mode will in fact compile and execute with an Ada
83 compiler, since GNAT does not enforce all the additional checks
required by Ada 83.
pragma Ada_95
pragma Ada_95;
A configuration pragma that establishes Ada 95 mode for the unit to which
it applies, regardless of the mode set by the command line switches.
This mode is set automatically for the Ada and System
packages and their children, so you need not specify it in these
contexts. This pragma is useful when writing a reusable component that
itself uses Ada 95 features, but which is intended to be usable from
either Ada 83 or Ada 95 programs.
pragma Annotate
pragma Annotate (IDENTIFIER {, ARG});
ARG ::= NAME | 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.
pragma Assert
pragma Assert (
boolean_EXPRESSION
[, static_string_EXPRESSION])
The effect of this pragma depends on whether the corresponding command line switch is set to activate assertions. 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.
pragma Ast_Entry
pragma AST_Entry (entry_IDENTIFIER);
This pragma is implemented only in the OpenVMS implementation of GNAT. The
argument is the simple name of a single entry; at most one AST_Entry
pragma is allowed for any given entry. This pragma must be used in
conjunction with the AST_Entry attribute, and is only allowed after
the entry declaration and in the same task type specification or single task
as the entry to which it applies. This pragma specifies that the given entry
may be used to handle an OpenVMS asynchronous system trap (AST)
resulting from an OpenVMS system service call. The pragma does not affect
normal use of the entry. For further details on this pragma, see the
DEC Ada Language Reference Manual, section 9.12a.
pragma C_Pass_By_Copy
pragma C_Pass_By_Copy
([Max_Size =>] static_integer_EXPRESSION);
Normally the default mechanism for passing C convention records to C
convention subprograms is to pass them by reference, as suggested by RM
B.3(69). Use the configuration pragma C_Pass_By_Copy to change
this default, by requiring that record formal parameters be passed by
copy if all of the following conditions are met:
Convention C.
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.
pragma Comment
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 limit on the
length of the string argument, and no limitations on placement
of the pragma (it can be placed anywhere in the main source unit).
pragma Common_Object
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.
pragma Complex_Representation
pragma Complex_Representation
([Entity =>] LOCAL_NAME);
The Entity argument must be the name of a record type which has
two fields of the same floating-point type. The effect of this pragma is
to force gcc to use the special internal complex representation form for
this record, which may be more efficient. Note that this may result in
the code for this type not conforming to standard ABI (application
binary interface) requirements for the handling of record types. For
example, in some environments, there is a requirement for passing
records by pointer, and the use of this pragma may result in passing
this type in floating-point registers.
pragma Component_Alignment
pragma Component_Alignment (
[Form =>] ALIGNMENT_CHOICE
[, [Name =>] type_LOCAL_NAME]);
ALIGNMENT_CHOICE ::=
Component_Size
| Component_Size_4
| Storage_Unit
| 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.
pragma CPP_Class
pragma CPP_Class ([Entity =>] LOCAL_NAME);
The argument denotes an entity in the current declarative region that is declared as a tagged or untagged record type. It indicates that the type corresponds to an externally declared C++ class type, and is to be laid out the same way that C++ would lay out the type.
If (and only if) the type is tagged, at least one component in the
record must be of type Interfaces.CPP.Vtable_Ptr, corresponding
to the C++ Vtable (or Vtables in the case of multiple inheritance) used
for dispatching.
Types for which CPP_Class is specified do not have assignment or
equality operators defined (such operations can be imported or declared
as subprograms as required). Initialization is allowed only by
constructor functions (see pragma CPP_Constructor).
Pragma CPP_Class is intended primarily for automatic generation
using an automatic binding generator tool. Ada Core Technologies does
not currently supply such a
tool; See Interfacing to C++ for more details.
pragma CPP_Constructor
pragma CPP_Constructor ([Entity =>] LOCAL_NAME);
This pragma identifies an imported function (imported in the usual way with pragma Import) as corresponding to a C++ constructor. The argument is a name that must have been previously mentioned in a pragma Import with Convention CPP, and must be of one of the following forms:
function Fname return T'Class
function Fname (...) return T'Class
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-function-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. Ada Core Technologies does
not currently supply such a
tool; See Interfacing to C++ for more details.
pragma CPP_Virtual
pragma CPP_Virtual
[Entity =>] ENTITY,
[, [Vtable_Ptr =>] vtable_ENTITY,]
[, [Position =>] static_integer_EXPRESSION])
This pragma serves the same function as pragma Import in that
case of a virtual function imported from C++. The Entity argument
must be a
primitive subprogram of a tagged type to which pragma CPP_Class
applies. The Vtable_Ptr argument specifies
the Vtable_Ptr component which contains the
entry for this virtual function. The Position argument
is the sequential number
counting virtual functions for this Vtable starting at 1.
The Vtable_Ptr and Position arguments may be omitted if
there is one Vtable_Ptr present (single inheritance case) and all
virtual functions are imported. In that case the compiler can deduce both
these values.
No External_Name or Link_Name arguments are required for a
virtual function, since it is always accessed indirectly via the
appropriate Vtable entry.
Pragma CPP_Virtual is intended primarily for automatic generation
using an automatic binding generator tool. Ada Core Technologies does
not currently supply such a
tool; See Interfacing to C++ for more details.
pragma CPP_Vtable
pragma CPP_Vtable (
[Entity =>] ENTITY,
[Vtable_Ptr =>] vtable_ENTITY,
[Entry_Count =>] static_integer_EXPRESSION);
Given a record to which the pragma CPP_Class applies,
this pragma can be specified for each component of type
CPP.Interfaces.Vtable_Ptr.
Entity is the tagged type, Vtable_Ptr
is the record field of type Vtable_Ptr, and Entry_Count is
the number of virtual functions on the C++ side. Not all of these
functions need to be imported on the Ada side.
You may omit the CPP_Vtable pragma if there is only one
Vtable_Ptr component in the record and all virtual functions are
imported on the Ada side (the default value for the entry count in this
case is simply the total number of virtual functions).
Pragma CPP_Vtable is intended primarily for automatic generation
using an automatic binding generator tool. Ada Core Technologies does
not currently supply such a
tool; See Interfacing to C++ for more details.
pragma Debug
pragma Debug (PROCEDURE_CALL_STATEMENT);
If assertions are not enabled on the command line, this pragma has no
effect. If asserts are enabled, the semantics of the pragma is exactly
equivalent to the procedure call. Pragmas are permitted in sequences of
declarations, so you can use pragma Debug to intersperse calls to
debug procedures in the middle of declarations.
pragma Elaboration_Checks
pragma Elaboration_Checks (RM | 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 RM, 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 Users Guide.
pragma Eliminate
pragma Eliminate (
[Unit_Name =>] IDENTIFIER |
SELECTED_COMPONENT);
pragma Eliminate (
[Unit_Name =>] IDENTIFIER |
SELECTED_COMPONENT
[Entity =>] IDENTIFIER |
SELECTED_COMPONENT |
STRING_LITERAL]
[,[Parameter_Types =>] PARAMETER_TYPES]
[,[Result_Type =>] result_SUBTYPE_NAME]]);
PARAMETER_TYPES ::= (SUBTYPE_NAME {, SUBTYPE_NAME})
SUBTYPE_NAME ::= STRING_LITERAL
This pragma indicates that the given entity is not used outside the compilation unit it is defined in. The entity may be either a subprogram or a variable.
If the entity to be eliminated is a library level subprogram, then
the first form of pragma 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. item is an entity of a library package, then the first
argument specifies the unit name, and the second argument specifies
the particular entity. If the second argument is in string form, it must
correspond to the internal manner in which GNAT stores entity names (see
compilation unit Namet in the compiler sources for details).
The third and fourth parameters are optionally used to distinguish
between overloaded subprograms, in a manner similar to that used for
the extended Import and Export pragmas, except that the
subtype names are always given as string literals, again corresponding
to the internal manner in which GNAT stores entity names.
The effect of the pragma is to allow the compiler to eliminate the code or data associated with the named entity. Any reference to an eliminated entity outside the compilation unit it is defined in, causes a compile time or link time error.
The intention of pragma Eliminate is to allow a program to be compiled in a system independent manner, with unused entities eliminated, without the requirement of modifying the source text. Normally the required set of Eliminate pragmas is constructed automatically using the gnatelim tool. Elimination of unused entities local to a compilation unit is automatic, without requiring the use of pragma Eliminate.
Note that the reason this pragma takes string literals where names might
be expected is that a pragma Eliminate can appear in a context where the
relevant names are not visible.
pragma Export_Exception
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.
pragma Export_Function ...
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
| SUBTYPE_MARK {, SUBTYPE_MARK}
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
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.
Passing by descriptor is supported only on the OpenVMS ports of GNAT.
pragma Export_Object ...
pragma Export_Object
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Size =>] EXTERNAL_SYMBOL]
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_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.
pragma Export_Procedure ...
pragma Export_Procedure (
[Internal =>] LOCAL_NAME
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
PARAMETER_TYPES ::=
null
| SUBTYPE_MARK {, SUBTYPE_MARK}
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
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.
pragma Export_Valued_Procedure
pragma Export_Valued_Procedure (
[Internal =>] LOCAL_NAME
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
PARAMETER_TYPES ::=
null
| SUBTYPE_MARK {, SUBTYPE_MARK}
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
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.
pragma Extend_System
pragma Extend_System ([Name =>] IDENTIFIER);
This pragma is used to provide backwards compatibility with other
implementations that extend the facilities of package System. In
GNAT, System contains only the definitions that are present in
the Ada 95 RM. However, other implementations, notably the DEC Ada 83
implementation, provide many extensions to package System.
For each such implementation accommodated by this pragma, GNAT provides a
package Aux_xxx, e.g. Aux_DEC for the DEC Ada 83
implementation, which provides the required additional definitions. You
can use this package in two ways. You can with it in the normal
way and access entities either by selection or using a use
clause. In this case no special processing is required.
However, if existing code contains references such as
System.xxx where xxx is an entity in the extended
definitions provided in package System, you may use this pragma
to extend visibility in System in a non-standard way that
provides greater compatibility with the existing code. Pragma
Extend_System is a configuration pragma whose single argument is
the name of the package containing the extended definition
(e.g. Aux_DEC for the DEC Ada case). A unit compiled under
control of this pragma will be processed using special visibility
processing that looks in package System.Aux_xxx where
Aux_xxx is the pragma argument for any entity referenced in
package System, but not found in package System.
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.
pragma External
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.
pragma External_Name_Casing
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.
pragma Finalize_Storage_Only
pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
This pragma allows the compiler not to emit a Finalize call for objects
defined at the library level. This is mostly useful for types where
finalization is only used to deal with storage reclamation since in most
environments it is not necessary to reclaim memory just before terminating
execution, hence the name.
pragma Float_Representation
pragma Float_Representation (FLOAT_REP);
FLOAT_REP ::= VAX_Float | IEEE_Float
This pragma is implemented only in the OpenVMS implementation of GNAT.
It allows control over the internal representation chosen for the predefined
floating point types declared in the packages Standard and
System. For further details on this pragma, see the
DEC Ada Language Reference Manual, section 3.5.7a. Note that to use this
pragma, the standard runtime libraries must be recompiled. See the
description of the GNAT LIBRARY command in the OpenVMS version
of the GNAT Users Guide for details on the use of this command.
pragma Ident
pragma Ident (static_string_EXPRESSION);
This pragma provides a string identification in the generated object file,
if the system supports the concept of this kind of identification string.
The maximum permitted length of the string literal is 31 characters.
This pragma is allowed only in the outermost declarative part or
declarative items of a compilation unit.
On OpenVMS systems, the effect of the pragma is identical to the effect of
the DEC Ada 83 pragma of the same name.
pragma Import_Exception
pragma Import_Exception (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL,]
[, [Form =>] Ada | VMS]
[, [Code =>] static_integer_EXPRESSION]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_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.
pragma Import_Function ...
pragma Import_Function (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Result_Type =>] SUBTYPE_MARK]
[, [Mechanism =>] MECHANISM]
[, [Result_Mechanism =>] MECHANISM_NAME]
[, [First_Optional_Parameter =>] IDENTIFIER]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
PARAMETER_TYPES ::=
null
| SUBTYPE_MARK {, SUBTYPE_MARK}
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | 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_Name argument must uniquely designate
the function to which the
pragma applies. If more than one function name exists of this name in
the declarative part you must use the Parameter_Types and
Result_Type parameters to achieve the required unique
designation. Subtype marks in these parameters must exactly match the
subtypes in the corresponding function specification, using positional
notation to match parameters with subtype marks.
You may optionally use the Mechanism and Result_Mechanism parameters to specify passing mechanisms for the parameters and result. If you specify a single mechanism name, it applies to all parameters. Otherwise you may specify a mechanism on a parameter by parameter basis using either positional or named notation. If the mechanism is not specified, the default mechanism is used.
Passing by descriptor is supported only on the to OpenVMS ports of GNAT.
First_Optional_Parameter applies only to OpenVMS ports of GNAT.
It specifies that the designated parameter and all following parameters
are optional, meaning that they are not passed at the generated code
level (this is distinct from the notion of optional parameters in Ada
where the parameters are passed anyway with the designated optional
parameters). All optional parameters must be of mode IN and have
default parameter values that are either known at compile time
expressions, or uses of the 'Null_Parameter attribute.
pragma Import_Object
pragma Import_Object
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL],
[, [Size =>] EXTERNAL_SYMBOL])
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_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.
pragma Import_Procedure
pragma Import_Procedure (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]
[, [First_Optional_Parameter =>] IDENTIFIER]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
PARAMETER_TYPES ::=
null
| SUBTYPE_MARK {, SUBTYPE_MARK}
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | 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.
pragma Import_Valued_Procedure ...
pragma Import_Valued_Procedure (
[Internal =>] LOCAL_NAME,
[, [External =>] EXTERNAL_SYMBOL]
[, [Parameter_Types =>] PARAMETER_TYPES]
[, [Mechanism =>] MECHANISM]
[, [First_Optional_Parameter =>] IDENTIFIER]);
EXTERNAL_SYMBOL ::=
IDENTIFIER
| static_string_EXPRESSION
PARAMETER_TYPES ::=
null
| SUBTYPE_MARK {, SUBTYPE_MARK}
MECHANISM ::=
MECHANISM_NAME
| (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
MECHANISM_ASSOCIATION ::=
[formal_parameter_NAME =>] MECHANISM_NAME
MECHANISM_NAME ::=
Value
| Reference
| Descriptor [([Class =>] CLASS_NAME)]
CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | 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.
pragma Initialize_Scalars
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 there is control over the value used for initializing scalar objects. At bind time, you can select whether to initialize with invalid values (like Normalize_Scalars), or with high or low values, or with a specified bit pattern. See the users guide for binder options for specifying these cases.
This means that you can compile a program, and then without having to recompile the program, you can run it with different values being used for initializing otherwise uninitialized values, to test if your program behavior depends on the choice. Of course the behavior should not change, and if it does, then most likely you have an erroneous reference to an uninitialized value.
Note that pragma 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.
pragma Inline_Always
pragma Inline_Always (NAME [, NAME]);
Similar to pragma Inline except that inlining is not subject to
the use of option -gnatn for inter-unit inlining.
pragma Inline_Generic
pragma Inline_Generic (generic_package_NAME)
This is implemented for compatibility with DEC Ada 83 and is recognized,
but otherwise ignored, by GNAT. All generic instantiations are inlined
by default when using GNAT.
pragma Interface
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.
pragma Interface_Name
pragma Interface_Name (
[Entity =>] LOCAL_NAME
[, [External_Name =>] static_string_EXPRESSION]
[, [Link_Name =>] static_string_EXPRESSION]);
This pragma provides an alternative way of specifying the interface name
for an interfaced subprogram, and is provided for compatibility with Ada
83 compilers that use the pragma for this purpose. You must provide at
least one of External_Name or Link_Name.
pragma License
Syntax:
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.
A GNAT license header starts with a line containing 78 hyphens. The following comment text is searched for the appearence of any of the following strings.
If the string "GNU General Public License" is found, then the unit is assumed to have GPL license, unless the string "As a special exception" follows, in which case the license is assumed to be modified GPL.
If one of the strings "This specification is adapated from the Ada Semantic Interface" or "This specification is derived from the Ada Reference Manual" is found then the unit is assumed to be unrestricted.
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.
pragma Link_With
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.
pragma Linker_Alias
pragma Linker_Alias (
[Entity =>] LOCAL_NAME
[Alias =>] static_string_EXPRESSION);
This pragma establishes a linker alias for the given named entity. For
further details on the exact effect, consult the GCC manual.
pragma Linker_Section
pragma Linker_Section (
[Entity =>] LOCAL_NAME
[Section =>] static_string_EXPRESSION);
This pragma specifies the name of the linker section for the given entity.
For further details on the exact effect, consult the GCC manual.
pragma No_Run_Time
pragma No_Run_Time;
This is a configuration pragma that makes sure the user code does not
use nor need anything from the GNAT run time. This is mostly useful in
context where code certification is required. Please consult the High
Integrity product documentation for additional information.
pragma Normalize_Scalars
pragma Normalize_Scalars;
This is a language defined pragma which is fully implemented in GNAT. The effect is to cause all scalar objects that are not otherwise initialized to be initialized. The initial values are implementation dependent and are as follows:
Standard.Character
Standard.Wide_Character
Integer types
subtype Ityp is integer range 1 .. 10;
then objects of type x will be initialized to Integer'First, a negative
number that is certainly outside the range of subtype Ityp.
Real types
Modular types
Enumeration types
pragma Long_Float
pragma Long_Float (FLOAT_FORMAT);
FLOAT_FORMAT ::= D_Float | G_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 .. 15.
For further details on this pragma, see the
DEC Ada Language Reference Manual, section 3.5.7b. Note that to use this
pragma, the standard runtime libraries must be recompiled. See the
description of the GNAT LIBRARY command in the OpenVMS version
of the GNAT Users Guide for details on the use of this command.
pragma Machine_Attribute ...
pragma Machine_Attribute (
[Attribute_Name =>] string_EXPRESSION,
[Entity =>] LOCAL_NAME);
Machine dependent attributes can be specified for types and/or
declarations. Currently only subprogram entities are supported. This
pragma is semantically equivalent to __attribute__((
string_expression)) in GNU C, where string_expression> is
recognized by the GNU C macros VALID_MACHINE_TYPE_ATTRIBUTE and
VALID_MACHINE_DECL_ATTRIBUTE which are defined in the
configuration header file tm.h for each machine. See the GCC
manual for further information.
pragma Main_Storage
pragma Main_Storage
(MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
MAIN_STORAGE_OPTION ::=
[WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
| [TOP_GUARD =>] static_SIMPLE_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.
pragma No_Return
pragma No_Return (procedure_LOCAL_NAME);
procedure_local_NAME must refer to one or more procedure
declarations in the current declarative part. A procedure to which this
pragma is applied may not contain any explicit return statements,
and also may not contain any implicit return statements from falling off
the end of a statement sequence. One use of this pragma is to identify
procedures whose only purpose is to raise an exception.
Another use of this pragma is to suppress incorrect warnings about
missing returns in functions, where the last statement of a function
statement sequence is a call to such a procedure.
pragma Passive
pragma Passive ([Semaphore | No]);
Syntax checked, but otherwise ignored by GNAT. This is recognized for
compatibility with DEC Ada 83 implementations, where it is used within a
task definition to request that a task be made passive. If the argument
Semaphore is present, or no argument is omitted, then DEC Ada 83
treats the pragma as an assertion that the containing task is passive
and that optimization of context switch with this task is permitted and
desired. If the argument No is present, the task must not be
optimized. GNAT does not attempt to optimize any tasks in this manner
(since protected objects are available in place of passive tasks).
pragma Polling
pragma Polling (ON | OFF);
This pragma controls the generation of polling code. This is normally off.
If pragma Polling (ON) is used then periodic calls are generated to
the routine Ada.Exceptions.Poll. This routine is a separate unit in the
runtime library, and can be found in file a-excpol.adb.
Pragma polling can appear as a configuration pragma (for example it can be placed in the gnat.adc file) to enable polling globally, or it can be used in the statement or declaration sequence to control polling more locally.
A call to the polling routine is generated at the start of every loop and at the start of every subprogram call. This guarantees that the Poll routine is called frequently, and places an upper bound (determined by the complexity of the code) on the period between two Poll calls.
The primary purpose of the polling interface is to enable asynchronous aborts on targets that cannot otherwise support it (for example Windows NT), but it may be used for any other purpose requiring periodic polling. The standard version is null, and can be replaced by a user program. This will require re-compilation of the Ada.Exceptions package that can be found in files a-except.ads/adb.
A standard alternative unit (called 4wexcpol.adb in the standard GNAT distribution) is used to enable the asynchronous abort capability on targets that do not normally support the capability. The version of Poll in this file makes a call to the appropriate runtime routine to test for an abort condition.
Note that polling can also be enabled by use of the -gnatP switch. See
the GNAT User's Guide for details.
pragma Propagate_Exceptions
pragma Propagate_Exceptions (subprogram_LOCAL_NAME);
This pragma indicates that the given entity, which is the name of an imported foreign-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.
pragma Psect_Object
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.
pragma Pure_Function
pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
This pragma appears in the same declarative part as a function
declaration (or a set of function declarations if more than one
overloaded declaration exists, in which case the pragma applies
to all entities). If specifies that the function Entity is
to be considered pure for the purposes of code generation. This means
that the compiler can assume that there are no side effects, and
in particular that two calls with identical arguments produce the
same result. It also means that the function can be used in an
address clause.
Note that, quite deliberately, there are no static checks to try to ensure that this promise is met, so Pure_Function can be used with functions that are conceptually pure, even if they do modify global variables. For example, a square root function that is instrumented to count the number of times it is called is still conceptually pure, and can still be optimized, even though it modifies a global variable (the count). Memo functions are another example (where a table of previous calls is kept and consulted to avoid re-computation).
Note: Most functions in a Pure package are automatically pure, and
there is no need to use pragma Pure_Function for such functions. An
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. The use
of pragma Pure_Function for such a function will override this default
assumption, and cause the compiler to treat such a function as pure.
Note: If pragma Pure_Function is applied to a renamed function, it
applies to the underlying renamed function. This can be used to
disambiguate cases of overloading where some but not all functions
in a set of overloaded functions are to be designated as pure.
pragma Ravenscar
pragma Ravenscar
A configuration pragma that establishes the following set of restrictions:
No_Abort_Statements
No_Select_Statements
No_Task_Hierarchy
No_Task_Allocators
No_Dynamic_Priorities
No_Terminate_Alternatives
No_Dynamic_Interrupts
No_Protected_Type_Allocators
No_Local_Protected_Objects
No_Requeue
No_Calendar
No_Relative_Delay
No_Task_Attributes
Static_Storage_Size
Boolean_Entry_Barriers
Max_Asynchronous_Select_Nesting = 0
Max_Task_Entries = 0
Max_Protected_Entries = 1
Max_Select_Alternatives = 0
No_Task_Termination
No_Entry_Queue
This set of restrictions corresponds to the definition of the "Ravenscar Profile" for limited tasking, devised and published by the International Workshop On Real Time Ada", 1997.
The above set is a superset of the restrictions provided by pragma
Restricted_Run_Time, it includes six additional restrictions
(Boolean_Entry_Barriers, No_Select_Statements,
No_Calendar, Static_Storage_Size,
No_Relative_Delay and No_Task_Termination). This means
that pragma Ravenscar, like the pragma Restricted_Run_Time, automatically
causes the use of a simplified, more efficient version of the tasking
run-time system.
pragma Restricted_Run_Time
pragma Restricted_Run_Time
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.
pragma Share_Generic
pragma Share_Generic (NAME {, NAME});
This pragma is recognized for compatibility with other Ada compilers
but is ignored by GNAT. GNAT does not provide the capability for
sharing of generic code. All generic instantiations result in making
an inlined copy of the template with appropriate substitutions.
pragma Source_File_Name
pragma Source_File_Name (
[Unit_Name =>] unit_NAME,
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.
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.
pragma Source_Reference
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.
pragma Stream_Convert
pragma Stream_Convert (
[Entity =>] type_LOCAL_NAME,
[Read =>] function_NAME,
[Write =>] function NAME);
This pragma provides an efficient way of providing stream functions for types defined in packages. Not only is it simpler to use than declaring the necessary functions with attribute representation clauses, but more significantly, it allows the declaration to made in such a way that the stream packages are not loaded unless they are needed. The use of the Stream_Convert pragma adds no overhead at all, unless the stream attributes are actually used on the designated type.
The first argument specifies the type for which stream functions are provided. The second parameter provides a function used to read values of this type. It must name a function whose argument type may be any subtype, and whose returned type must be the type given as the first argument to the pragma.
The meaning of the Read parameter is that if a stream attribute directly or indirectly specifies reading of the type given as the first parameter, then a value of the type given as the argument to the Read function is read from the stream, and then the Read function is used to convert this to the required target type.
Similarly the Write parameter specifies how to treat write attributes that directly or indirectly apply to the type given as the first parameter. It must have an input parameter of the type specified by the first parameter, and the return type must be the same as the input type of the Read function. The effect is to first call the Write function to convert to the given stream type, and then write the result type to the stream.
The Read and Write functions must not be overloaded subprograms. If necessary renamings can be supplied to meet this requirement. The usage of this attribute is best illustrated by a simple example, taken from the GNAT implementation of package Ada.Strings.Unbounded:
function To_Unbounded (S : String)
return Unbounded_String
renames To_Unbounded_String;
pragma Stream_Convert
(Unbounded_String, To_Unbounded, To_String);
The specifications of the referenced functions, as given in the Ada 95 Reference Manual are:
function To_Unbounded_String (Source : String)
return Unbounded_String;
function To_String (Source : Unbounded_String)
return String;
The effect is that if the value of an unbounded string is written to a
stream, then the representation of the item in the stream is in the same
format used for Standard.String, and this same representation is
expected when a value of this type is read from the stream.
pragma Style_Checks
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 on the gcc or gnatmake
line. 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
pragma Subtitle
pragma Subtitle ([Subtitle =>] STRING_LITERAL);
This pragma is recognized for compatibility with other Ada compilers
but is ignored by GNAT.
pragma Suppress_All
pragma Suppress_All;
This pragma can only appear immediately following a compilation
unit. The effect is to apply Suppress (All_Checks) to the unit
which it follows. This pragma is implemented for compatibility with DEC
Ada 83 usage. The use of pragma Suppress (All_Checks) as a normal
configuration pragma is the preferred usage in GNAT.
pragma Suppress_Initialization
pragma Suppress_Initialization ([Entity =>] type_Name);
This pragma suppresses any implicit or explicit initialization
associated with the given type name for all variables of this type.
pragma Task_Info
pragma Task_Info (EXPRESSION);
This pragma appears within a task definition (like pragma
Priority) and applies to the task in which it appears. The
argument must be of type System.Task_Info.Task_Info_Type.
The Task_Info pragma provides system dependent control over
aspect of tasking implementation, for example, the ability to map
tasks to specific processors. For details on the facilities available
for the version of GNAT that you are using, see the documentation
in the specification of package System.Task_Info in the runtime
library.
pragma Task_Name
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;
pragma Task_Storage
pragma Task_Storage
[Task_Type =>] LOCAL_NAME,
[Top_Guard =>] static_integer_EXPRESSION);
This pragma specifies the length of the guard area for tasks. The guard
area is an additional storage area allocated to a task. A value of zero
means that either no guard area is created or a minimal guard area is
created, depending on the target. This pragma can appear anywhere a
Storage_Size attribute definition clause is allowed for a task
type.
pragma Time_Slice
pragma Time_Slice (static_duration_EXPRESSION);
For implementations of GNAT on operating systems where it is possible
to supply a time slice value, this pragma may be used for this purpose.
It is ignored if it is used in a system that does not allow this control,
or if it appears in other than the main program unit.
Note that the effect of this pragma is identical to the effect of the
DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
pragma Title
pragma Title (TITLING_OPTION [, TITLING OPTION]);
TITLING_OPTION ::=
[Title =>] STRING_LITERAL,
| [Subtitle =>] STRING_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.
pragma Unchecked_Union
pragma Unchecked_Union (first_subtype_LOCAL_NAME)
This pragma is used to declare that the specified type should be represented in a manner equivalent to a C union type, and is intended only for use in interfacing with C code that uses union types. In Ada terms, the named type must obey the following rules:
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
pragma Unimplemented_Unit
pragma Unimplemented_Unit;
If this pragma occurs in a unit that is processed by the compiler, GNAT
aborts with the message xxx not implemented, where
xxx is the name of the current compilation unit. This pragma is
intended to allow the compiler to handle unimplemented library units in
a clean manner.
The abort only happens if code is being generated. Thus you can use
specs of unimplemented packages in syntax or semantic checking mode.
pragma Unreserve_All_Interrupts
pragma Unreserve_All_Interrupts;
Normally certain interrupts are reserved to the implementation. Any attempt
to attach an interrupt causes Program_Error to be raised, as described in
RM C.3.2(22). A typical example is the SIGINT interrupt used in
many systems for an Ctrl-C interrupt. Normally this interrupt is
reserved to the implementation, so that Ctrl-C can be used to
interrupt execution.
If the pragma Unreserve_All_Interrupts appears anywhere in any unit in
a program, then all such interrupts are unreserved. This allows the
program to handle these interrupts, but disables their standard
functions. For example, if this pragma is used, then pressing
Ctrl-C will not automatically interrupt execution. However,
a program can then handle the SIGINT interrupt as it chooses.
For a full list of the interrupts handled in a specific implementation,
see the source code for the specification of Ada.Interrupts.Names in
file 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.
pragma Unsuppress
pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
This pragma undoes the effect of a previous pragma Suppress. If
there is no corresponding pragma Suppress in effect, it has no
effect. The range of the effect is the same as for pragma
Suppress. The meaning of the arguments is identical to that used
in pragma Suppress.
One important application is to ensure that checks are on in cases where
code depends on the checks for its correct functioning, so that the code
will compile correctly even if the compiler switches are set to suppress
checks.
pragma Use_VADS_Size
pragma Use_VADS_Size;
This is a configuration pragma. In a unit to which it applies, any use
of the 'Size attribute is automatically interpreted as a use of the
'VADS_Size attribute. Note that this may result in incorrect semantic
processing of valid Ada 95 programs. This is intended to aid in the
handling of legacy code which depends on the interpretation of Size
as implemented in the VADS compiler. See description of the VADS_Size
attribute for further details.
pragma Validity_Checks
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
pragma Volatile
pragma Volatile (local_NAME)
This pragma is defined by the Ada 95 Reference Manual, and the GNAT
implementation is fully conformant with this definition. The reason it
is mentioned in this section is that a pragma of the same name was supplied
in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation
of pragma Volatile is upwards compatible with the implementation in
Dec Ada 83.
pragma Warnings
pragma Warnings (On | Off [, LOCAL_NAME]);
Normally warnings are enabled, with the output being controlled by
the command line switch. Warnings (Off) turns off generation of
warnings until a Warnings (On) is encountered or the end of the
current unit. If generation of warnings is turned off using this
pragma, then no warning messages are output, regardless of the
setting of the command line switches.
The form with a single argument is a configuration pragma.
If the local_name parameter is present, warnings are suppressed for
the specified entity. This suppression is effective from the point where
it occurs till the end of the extended scope of the variable (similar to
the scope of Suppress).
pragma Weak_External
pragma Weak_External ([Entity =>] LOCAL_NAME);
This pragma specifies that the given entity should be marked as a weak external (one that does not have to be resolved) for the linker. For further details, consult the GCC manual.