Annotated Ada Reference ManualLegal Information
Contents   Index   References   Search   Previous   Next 

B.1 Interfacing AspectsInterfacing Pragmas

  {AI05-0229-1} An interfacing aspect is a representation aspect that is one of the aspects Import, Export, Link_Name, External_Name, or Convention.
{AI05-0229-1} {AI05-0269-1} Specifying the A pragma 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 a pragma 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 pragmas 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.
Aspect Description for Import: Entity is imported from another language.
Aspect Description for Export: Entity is exported to another language.
Aspect Description for External_Name: Name used to identify an imported or exported entity.
Aspect Description for Link_Name: Linker symbol used to identify an imported or exported entity.
{AI05-0229-1} The A pragma Convention aspect is used to indicate specify that an Ada entity should use the conventions of another language. It is intended primarily for types and “callback” subprograms. For example, “with pragma Convention => (Fortran, Matrix);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.
Aspect Description for Convention: Calling convention or other convention used for interfacing to other languages.
A pragma Linker_Options is used to specify the system linker parameters needed when a given compilation unit is included in a partition.


{AI05-0229-1} The form of a 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 is, are as follows: 
Paragraphs 5 through 7 were moved to Annex J, “Obsolescent Features”. 
{AI05-0229-1}   pragma Import(
     [Convention =>] convention_identifier, [Entity =>] local_name
  [, [External_Name =>] string_expression] [, [Link_Name =>] string_expression]);
{AI05-0229-1}   pragma Export(
     [Convention =>] convention_identifier, [Entity =>] local_name
  [, [External_Name =>] string_expression] [, [Link_Name =>] string_expression]);
{AI05-0229-1}   pragma Convention([Convention =>] convention_identifier,[Entity =>] local_name);
  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} {AI95-00036-01} {AI05-0229-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

  {AI05-0229-1} The Import and Export aspects are of type Boolean.
 {AI05-0229-1} The Link_Name and External_Name aspects are of expected type for a string_expression in an interfacing pragma or in pragma Linker_Options is String.
Ramification: There is no language-defined support for external or link names of type Wide_String, or of other string types. Implementations may, of course, have additional aspects pragmas for that purpose. Note that allowing both String and Wide_String in the same aspect_definition pragma would cause ambiguities. 
   {AI05-0229-1} The expected type for the string_expression in pragma Linker_Options is String.

Legality Rules

 {AI05-0229-1} The aspect Convention shall be specified by a convention_identifier which 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
Implementation defined: Implementation-defined convention names.
Discussion: We considered representing the convention names using an enumeration type declared in System. Then, 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),
{AI05-0229-1} Convention L has been specified for T in a pragma Convention, and T is eligible for convention L; that is:
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,
{AI05-0002-1} T is an access-to-object type, and 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,
The implementation permits T as an L-compatible type.
Discussion: For example, an implementation might permit Integer as a C-compatible type, though the C type to which it corresponds might be different in different environments. 
 {AI05-0229-1} If the pragma Convention aspect is specified for applies to a type, then the type shall either be compatible with or eligible for the specified convention specified in the pragma
Ramification: {AI05-0229-1} If a type is derived from an L-compatible type, the derived type is by default L-compatible, but it is also permitted to specify the pragma Convention aspect for the derived type.
{AI05-0229-1} It is permitted to specify the pragma Convention aspect for an incomplete type, but in the complete declaration each component must be L-compatible.
{AI05-0229-1} If each component of a record type is L-compatible, then the record type itself is only L-compatible if it has a specified a pragma Convention. 
 {AI05-0229-1} A pragma Import shall be the completion of a declaration. Notwithstanding any rule to the contrary, a declaration with a True a pragma Import aspect shall not have a 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
Discussion: {AI05-0229-1} For declarations of deferred constants and subprograms, we explicitly mention that no completion is allowed when aspect pragma Import is True explicitly as a possible completion. For other declarations that require completions, we ignore the possibility of the aspect pragma Import being True. Nevertheless, if an implementation chooses to allow specifying aspect a pragma Import to be True for complete the declaration of a task, protected type, incomplete type, private type, etc., it may do so, and the normal completion is then not allowed for that declaration. 
 {AI05-0229-1} An entity with a True specified as the Entity argument to a pragma Import aspect (or pragma 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.] 
Proof: This follows from the “Notwithstanding ...” wording in the Dynamics Semantics paragraphs below. 
 {AI05-0229-1} The type of an imported or exported object shall be compatible with the specified Convention aspect, if any convention specified in the corresponding pragma.
Ramification: This implies, for example, that importing an Integer object might be illegal, whereas importing an object of type would be permitted. 
 {AI05-0229-1} For an imported or exported subprogram, the result and parameter types shall each be compatible with the specified Convention aspect, if any convention specified in the corresponding pragma.
 {AI05-0229-1} The aspect_definition (if any) used to directly specify an The external name and link name string_expressions of a pragma Import, or Export, External_Name, or Link_Name aspect shall be a static expression. The and 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. 
 {AI05-0229-1} 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.
 {AI05-0229-1} An interfacing pragma is a program unit pragma when applied to a program unit (see 10.1.5).
 {AI05-0229-1} An interfacing pragma defines the convention of the entity denoted by the local_name. The Convention aspect 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: 
A True pragma Import aspect indicates specifies 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 pragma Export aspect indicates specifies 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 A pragma Import or Export aspect, an optionally specifies an entity's 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. 
Implementation defined: The meaning of link names.
Ramification: For example, an implementation might always prepend "_", and then pass it to the system linker.
Implementation defined: The manner of choosing link names when neither the link name nor the address of an imported or exported entity is specified.
Ramification: Normally, this will be the entity's defining name, or some simple transformation thereof. 
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. 
Implementation defined: The effect of pragma Linker_Options.

Dynamic Semantics

 {AI05-0229-1} Notwithstanding what this International Standard says elsewhere, the elaboration of a declaration with a True Import aspect 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.
Ramification: This implies that default initializations are skipped. (Explicit initializations are illegal.) For example, an imported access object is not initialized to null.
This paragraph was deleted.{AI05-0229-1} Note that the local_name in a pragma Import might denote more than one declaration; in that case, the entity of all of those declarations will be the external entity. 
Discussion: {AI05-0229-1} This “notwithstanding” wording is better than saying “unless aspect named by a pragma Import is True ” on every definition of elaboration. It says we recognize the contradiction, and this rule takes precedence. 

Erroneous Execution

   {AI95-00320-01} {AI05-0229-1} It is the programmer's responsibility to ensure that the use of interfacing aspects pragmas does not violate Ada semantics; otherwise, program execution is erroneous.

Implementation Advice

 {AI05-0229-1} If an implementation supports pragma Export for 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.
Implementation Advice: If pragma  Export is supported for a language, the main program should be able to be written in that language. Subprograms named "adainit" and "adafinal" should be provided for elaboration and finalization of the environment task.
Ramification: For example, if the main subprogram is written in C, it can call adainit before the first call to an Ada subprogram, and adafinal after the last. 
 {AI05-0229-1} {AI05-0269-1} Automatic elaboration of preelaborated packages should be provided when specifying the pragma Export aspect as True is supported. 
Implementation Advice: Automatic elaboration of preelaborated packages should be provided when specifying the pragma Export aspect as True is supported.
 {AI05-0229-1} For each supported convention L other than Intrinsic, an implementation should support specifying the Import and Export aspects pragmas for objects of L-compatible types and for subprograms, and the pragma Convention aspect for L-eligible types and for subprograms, presuming the other language has corresponding features. Specifying the Pragma Convention aspect need not be supported for scalar types. 
Implementation Advice: For each supported convention L other than Intrinsic, specifying the aspects pragmas Import and Export should be supported for objects of L-compatible types and for subprograms, and aspect pragma Convention should be supported for L-eligible types and for subprograms.
Reason: {AI05-0229-1} Specifying aspect Pragma Convention is not necessary for scalar types, since the language interface packages declare scalar types corresponding to those provided by the respective foreign languages. 
Implementation Note: {AI95-00114-01} If an implementation supports interfacing to the C++ entities not supported by B.3, it should do so via the convention identifier C_Plus_Plus (in additional to any C++-implementation-specific ones). 
Reason: {AI95-00114-01} The reason for giving the advice about C++ is to encourage uniformity among implementations, given that the name of the language is not syntactically legal as an identifier. We place this advice in the AARM, rather than the RM95 proper, because (as of this writing) C++ is not an international standard, and we don't want to refer to a such a language from an international standard.
1  {AI05-0229-1} Implementations may place restrictions on interfacing aspects pragmas; for example, requiring each exported entity to be declared at the library level. 
Proof: Arbitrary restrictions are allowed by 13.1
Ramification: Such a restriction might be to disallow them altogether. Alternatively, the implementation might allow them only for certain kinds of entities, or only for certain conventions.
2  {AI05-0229-1} The Convention aspect in combination with the A pragma Import aspect indicates 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, with Convention => Ada pragma Import(Ada, ...) can be used to interface to an assembly language routine that obeys the Ada compiler's calling conventions.
3  {AI05-0229-1} To obtain “call-back” to an Ada subprogram from a foreign language environment, the pragma Convention aspect should be specified both for the access-to-subprogram type and the specific subprogram(s) to which 'Access is applied.
Paragraphs 45 and 46 were deleted. 
4  {AI05-0229-1} It is illegal to specify more than one of Import, Export, or Convention for a given entity.
5  {AI05-0229-1} 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.
6  See also 13.8, “Machine Code Insertions”. 
Ramification: {AI05-0229-1} The Intrinsic convention (see 6.3.1) implies that the entity is somehow “built in” to the implementation. Thus, it generally does not make sense for users to specify Intrinsic along with specifying that the entity is imported in a pragma Import. The intention is that only implementations will specify Intrinsic for an imported entity in a pragma Import. The language also defines certain subprograms to be Intrinsic.
Discussion: {AI05-0229-1} There are many imaginable interfacing aspects pragmas that don't make any sense. For example, setting the Convention of a protected procedure to Ada is probably wrong. Rather than enumerating all such cases, however, we leave it up to implementations to decide what is sensible.
7  {AI05-0229-1} If both External_Name and Link_Name are specified for a given entity an Import or Export pragma, then the External_Name is ignored.
This paragraph was deleted.8  {AI95-00320-01} An interfacing pragma might result in an effect that violates Ada semantics. 


Example of interfacing pragmas: 
{AI05-0229-1} {AI05-0269-1} 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 Exp  (X : Floatreturn Matrix
    with Import => True, Convention => Fortran
  pragma Import(Fortran, Sqrt);
  pragma Import(Fortran, Exp);

end Fortran_Library;

Extensions to Ada 83

Interfacing pragmas are new to Ada 95. Pragma Import replaces Ada 83's pragma Interface. Existing implementations can continue to support pragma Interface for upward compatibility.

Wording Changes from Ada 95

{8652/0058} {AI95-00036-01} Corrigendum: Clarified that pragmas Import and Export work like a subprogram call; parameters cannot be omitted unless named notation is used. (Reordering is still not permitted, however.)
{AI95-00320-01} Added wording to say all bets are off if foreign code doesn't follow the semantics promised by the Ada specifications.

Incompatibilities With Ada 2005

{AI05-0002-1} Correction: Access types that designate unconstrained arrays are no longer defined to be L-compatible. Such access-to-arrays require bounds information, which is likely to be incompatible with a foreign language. The change will allow (but not require) compilers to reject bad uses, which probably will not work anyway. Note that implementations can still support any type that it wants as L-compatible; such uses will not be portable, however. As such, there should be little existing code that will be impacted (compilers probably already rejected cases that could not be translated, whether or not the language allowed doing so formally). 

Extensions to Ada 2005

{AI05-0229-1} Aspects Convention, Import, Export, Link_Name, and External_Name are new; pragmas Convention, Import, and Export are now obsolescent. 

Contents   Index   References   Search   Previous   Next 
Ada-Europe Ada 2005 and 2012 Editions sponsored in part by Ada-Europe