Contents Index Search Previous Next
B.1 Interfacing Pragmas
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.
Syntax
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.
9.1/1
For pragmas
Import and Export, the argument for Link_Name shall not be given without
the pragma_argument_identifier unless
the argument for External_Name is given.
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
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;
Contents Index Search Previous Next Legal