- (1)
- A pragma Import is used to import an entity defined in a foreign language
into an Ada program, thus allowing a foreign-language subprogram to be called
from Ada, or a foreign-language variable to be accessed from Ada. In
contrast, a pragma Export is used to export an Ada entity to a foreign
language, thus allowing an Ada subprogram to be called from a foreign
language, or an Ada object to be accessed from a foreign language. The
pragmas Import and Export are intended primarily for objects and subprograms,
although implementations are allowed to support other entities.
- (2)
- A pragma Convention is used to specify that an Ada entity should use the
conventions of another language. It is intended primarily for types and
``callback'' subprograms. For example, ``pragma Convention(Fortran,
Matrix);'' implies that Matrix should be represented according to the
conventions of the supported Fortran implementation, namely column-major
order.
- (3)
- A pragma Linker_Options is used to specify the system linker parameters
needed when a given compilation unit is included in a partition.
- (4)
- An interfacing pragma is a representation pragma that is one of the
pragmas Import, Export, or Convention. Their forms, together with that
of the related pragma Linker_Options, are as follows:
(5)
pragma Import(
[Convention =>] convention_identifier, [Entity =>] local_name
[, [External_Name =>] string_expression] [, [Link_Name =>] string_expression]);
(6)
pragma Export(
[Convention =>] convention_identifier, [Entity =>] local_name
[, [External_Name =>] string_expression] [, [Link_Name =>] string_expression]);
(7)
pragma Convention([Convention =>] convention_identifier,[Entity =>] local_name);
(8)
pragma Linker_Options(string_expression);
- (9)
- A pragma Linker_Options is allowed only at the place of a
declarative_item.
Name Resolution Rules
- (10)
- The expected type for a string_expression in an interfacing pragma or in
pragma Linker_Options is String.
Legality Rules
- (11)
- The convention_identifier of an interfacing pragma shall be the name of
a convention. The convention names are implementation defined, except for
certain language-defined ones, such as Ada and Intrinsic, as explained in
6.3.1, ``Conformance Rules''. Additional convention
names generally represent the calling conventions of foreign languages, language
implementations, or specific run-time models. The convention of a callable
entity is its calling convention.
- (12)
- If L is a convention_identifier for a language, then a type T is said to
be compatible with convention L, (alternatively, is said to be an
L-compatible type) if any of the following conditions are met:
- (13)
- T is declared in a language interface package corresponding to L and
is defined to be L-compatible (see B.3, B.3.1,
B.3.2, B.4, B.5),
- (14)
- Convention L has been specified for T in a pragma Convention, and
T is eligible for convention L; that is:
- (15)
- T is an array type with either an unconstrained or
statically-constrained first subtype, and its component
type is L-compatible,
- (16)
- T is a record type that has no discriminants and that only
has components with statically-constrained subtypes, and
each component type is L-compatible,
- (17)
- T is an access-to-object type, and its designated type is
L-compatible,
- (18)
- T is an access-to-subprogram type, and its designated
profile's parameter and result types are all L-compatible.
- (19)
- T is derived from an L-compatible type,
- (20)
- The implementation permits T as an L-compatible type.
- (21)
- If pragma Convention applies to a type, then the type shall either be
compatible with or eligible for the convention specified in the pragma.
- (22)
- A pragma Import shall be the completion of a declaration.
Notwithstanding any rule to the contrary, a pragma Import may serve as the
completion of any kind of (explicit) declaration if supported by an
implementation for that kind of declaration. If a completion is a pragma
Import, then it shall appear in the same declarative_part, package_specification, task_definition or protected_definition as the declaration.
For a library unit, it shall appear in the same compilation, before any
subsequent compilation_units other than pragmas. If the local_name denotes
more than one entity, then the pragma Import is the completion of all of
them.
- (23)
- An entity specified as the Entity argument to a pragma Import (or pragma
Export) is said to be imported (respectively, exported).
- (24)
- The declaration of an imported object shall not include an explicit
initialization expression. Default initializations are not performed.
- (25)
- The type of an imported or exported object shall be compatible with the
convention specified in the corresponding pragma.
- (26)
- For an imported or exported subprogram, the result and parameter types
shall each be compatible with the convention specified in the corresponding
pragma.
- (27)
- The external name and link name string_expressions of a pragma Import or
Export, and the string_expression of a pragma Linker_Options, shall be
static.
Static Semantics
- (28)
- Import, Export, and Convention pragmas are representation pragmas that
specify the convention aspect of representation. In addition, Import and
Export pragmas specify the imported and exported aspects of representation,
respectively.
- (29)
- An interfacing pragma is a program unit pragma when applied to a program
unit (see 10.1.5).
- (30)
- An interfacing pragma defines the convention of the entity denoted by
the local_name. The convention represents the calling convention or
representation convention of the entity. For an access-to-subprogram type,
it represents the calling convention of designated subprograms. In addition:
- (31)
- A pragma Import specifies that the entity is defined externally
(that is, outside the Ada program).
- (32)
- A pragma Export specifies that the entity is used externally.
- (33)
- A pragma Import or Export optionally specifies an entity's
external name, link name, or both.
- (34)
- An external name is a string value for the name used by a foreign
language program either for an entity that an Ada program imports, or for
referring to an entity that an Ada program exports.
- (35)
- A link name is a string value for the name of an exported or imported
entity, based on the conventions of the foreign language's compiler in
interfacing with the system's linker tool.
- (36)
- The meaning of link names is implementation defined. If neither a link
name nor the Address attribute of an imported or exported entity is
specified, then a link name is chosen in an implementation-defined manner,
based on the external name if one is specified.
- (37)
- Pragma Linker_Options has the effect of passing its string argument as a
parameter to the system linker (if one exists), if the immediately enclosing
compilation unit is included in the partition being linked. The
interpretation of the string argument, and the way in which the string
arguments from multiple Linker_Options pragmas are combined, is
implementation defined.
Dynamic Semantics
- (38)
- Notwithstanding what this International Standard says elsewhere, the
elaboration of a declaration denoted by the local_name of a pragma Import
does not create the entity. Such an elaboration has no other effect than to
allow the defining name to denote the external entity.
Implementation Advice
- (39)
- If an implementation supports pragma Export to a given language, then it
should also allow the main subprogram to be written in that language. It
should support some mechanism for invoking the elaboration of the Ada library
units included in the system, and for invoking the finalization of the
environment task. On typical systems, the recommended mechanism is to
provide two subprograms whose link names are "adainit" and "adafinal".
Adainit should contain the elaboration code for library units. Adafinal
should contain the finalization code. These subprograms should have no
effect the second and subsequent time they are called.
- (40)
- Automatic elaboration of preelaborated packages should be provided when
pragma Export is supported.
- (41)
- For each supported convention L other than Intrinsic, an implementation
should support Import and Export pragmas for objects of L-compatible types
and for subprograms, and pragma Convention for L-eligible types and for
subprograms, presuming the other language has corresponding features. Pragma
Convention need not be supported for scalar types.
-
- (42)
(1) Implementations may place restrictions on interfacing pragmas; for
example, requiring each exported entity to be declared at the library
level.
- (43)
(2) A pragma Import specifies the conventions for accessing external
entities. It is possible that the actual entity is written in assembly
language, but reflects the conventions of a particular language. For
example, pragma Import(Ada, ...) can be used to interface to an assembly
language routine that obeys the Ada compiler's calling conventions.
- (44)
(3) To obtain ``call-back'' to an Ada subprogram from a foreign language
environment, pragma Convention should be specified both for the
access-to-subprogram type and the specific subprogram(s) to which
'Access is applied.
- (45)
(4) It is illegal to specify more than one of Import, Export, or
Convention for a given entity.
- (46)
(5) The local_name in an interfacing pragma can denote more than one
entity in the case of overloading. Such a pragma applies to all of the
denoted entities.
- (47)
(6) See also 13.8, ``Machine Code Insertions''.
- (48)
(7) If both External_Name and Link_Name are specified for an Import or
Export pragma, then the External_Name is ignored.
- (49)
(8) An interfacing pragma might result in an effect that violates Ada
semantics.
Examples
- (50)
- Example of interfacing pragmas:
(51)
package Fortran_Library is
function Sqrt (X : Float) return Float;
function Exp (X : Float) return Float;
private
pragma Import(Fortran, Sqrt);
pragma Import(Fortran, Exp);
end Fortran_Library;
-- Email comments, additions, corrections, gripes, kudos, etc. to:
Magnus Kempe -- Magnus.Kempe@di.epfl.ch
Copyright statement
Page last generated: 95-03-12
| 
| 
| 
| 