B.1 Interfacing Aspects
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
An interfacing aspect is a representation aspect that is one of the aspects Import, Export, Link_Name, External_Name, or Convention.
Specifying the Import aspect to have the value True 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, specifying the Export aspect to have the value True 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 Import and Export aspects are intended primarily for objects and subprograms, although implementations are allowed to support other entities. The Link_Name and External_Name aspects are used to specify the link name and external name, respectively, to be used to identify imported or exported entities in the external environment.
The Convention aspect is used to indicate that an Ada entity should use the conventions of another language. It is intended primarily for types and “callback” subprograms. For example, “with Convention => Fortran” on the declaration of an array type Matrix implies that Matrix should be represented according to the conventions of the supported Fortran implementation, namely column-major order.
A pragma Linker_Options is used to specify the system linker parameters necessary when a given compilation unit is included in a partition.
Syntax
4/3The form of a pragma Linker_Options is as follows:
Paragraphs 5 through 7 were moved to Annex J, “Obsolescent Features”.
pragma Linker_Options(string_expression);
A pragma Linker_Options is allowed only at the place of a declarative_item.
This paragraph was deleted.{8652/0058}
Name Resolution Rules
9.2/3The Import and Export aspects are of type Boolean.
The Link_Name and External_Name aspects are of type String.
aspect_definition would cause ambiguities. The expected type for the string_expression in pragma Linker_Options is String.
Legality Rules
11/3The aspect Convention shall be specified by a convention_identifier which 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.
identifier would be changed to convention_name, and we would make its expected type be the enumeration type. We didn't do this because it seems to introduce extra complexity, and because the list of available languages is better represented as the list of children of package Interfaces — a more open-ended sort of list. 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:
- 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),
- Convention L has been specified for T, and T is eligible for convention L; that is:
- T is an enumeration type such that all internal codes (whether assigned by default or explicitly) are within an implementation-defined range that includes at least the range of values 0 .. 2**15–1;
- T is an array type with either an unconstrained or statically-constrained first subtype, and its component type is L-compatible,
- 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,
- T is an access-to-object type, its designated type is L-compatible, and its designated subtype is not an unconstrained array subtype,
- T is an access-to-subprogram type, and its designated profile's parameter and result types are all L-compatible.
- T is derived from an L-compatible type,
- T is an anonymous access type, and T is eligible for convention L,
- The implementation permits T as an L-compatible type.
If the Convention aspect is specified for a type, then the type shall either be compatible with or eligible for the specified convention.
If convention L is specified for a type T, for each component of T that has an anonymous access type, the convention of the anonymous access type is L. If convention L is specified for an object that has an anonymous access type, the convention of the anonymous access type is L.
Notwithstanding any rule to the contrary, a declaration with a True Import aspect shall not have a completion.
An entity with a True Import aspect (or Export aspect) is said to be imported (respectively, exported). An entity shall not be both imported and exported.
The declaration of an imported object shall not include an explicit initialization expression. [Default initializations are not performed.]
The type of an imported or exported object shall be compatible with the specified Convention aspect, if any.
For an imported or exported subprogram, the result and parameter types shall each be compatible with the specified Convention aspect, if any.
The aspect_definition (if any) used to directly specify an Import, Export, External_Name, or Link_Name aspect shall be a static expression. The string_expression of a pragma Linker_Options shall be static. An External_Name or Link_Name aspect shall be specified only for an entity that is either imported or exported.
Static Semantics
Paragraphs 28 and 29 were deleted.
The Convention aspect 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:
- A True Import aspect indicates that the entity is defined externally (that is, outside the Ada program). This aspect is never inherited; if not directly specified, the Import aspect is False.
- A True Export aspect indicates that the entity is used externally. This aspect is never inherited; if not directly specified, the Export aspect is False.
- For an entity with a True Import or Export aspect, an external name, link name, or both may also be specified.
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.
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.
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.
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/3Notwithstanding what this document says elsewhere, the elaboration of a declaration with a True Import aspect does not create the entity. Such an elaboration has no other effect than to allow the defining name to denote the external entity.
Erroneous Execution
38.1/5It is the programmer's responsibility to ensure that the use of interfacing aspects does not violate Ada semantics; otherwise, program execution is erroneous. For example, passing an object with mode in to imported code that modifies it causes erroneous execution. Similarly, calling an imported subprogram that is not pure from a pure package causes erroneous execution.
Implementation Advice
39/3If an implementation supports Export for 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.
Automatic elaboration of preelaborated packages should be provided when specifying the Export aspect as True is supported.
For each supported convention L other than Intrinsic, an implementation should support specifying the Import and Export aspects for objects of L-compatible types and for subprograms, and the Convention aspect for L-eligible types and for subprograms, presuming the other language has corresponding features. Specifying the Convention aspect should be supported for enumeration types whose internal codes fall within the range 0 .. 2**15–1, but no recommendation is made for other scalar types.
identifier. Examples
50/4Example of interfacing aspects:
package Fortran_Library is
function Sqrt (X : Float) return Float
with Import => True, Convention => Fortran;
type Matrix is array (Natural range <>, Natural range <>) of Float
with Convention => Fortran;
function Invert (M : Matrix) return Matrix
with Import => True, Convention => Fortran;
end Fortran_Library;
Extensions to Ada 83
Wording Changes from Ada 95
pragmas Import and Export work like a subprogram call; parameters cannot be omitted unless named notation is used. (Reordering is still not permitted, however.)Incompatibilities With Ada 2005
Extensions to Ada 2005
pragmas Convention, Import, and Export are now obsolescent.