Optional arguments of pragma Import and Export

Product Family: SCORE Target CPU: PC/Windows, SPARC/Solaris, 1750A, PowerPC, 80x86/Pentium Language: Ada Host: PC/Windows, SPARC/Solaris

Recently I received a question from a SCORE user. She reported that her program build without incident for both PowerPC and 80x86 bare environments; now she attempted to build it for Windows native but got a failure at link time. What was wrong?

The program included a C source like this

int GET5( int value )
{ ... }

and an Ada source like this

package Imports is
   function Get5( Value : in Integer ) return Integer;
   pragma Import( C, Get5, "GET5", "GET5" );
end Imports;

Cutting to the chase, I'll tell you that the problem is one of over-specification. If you had spotted that already, you know what I'll discuss below.

In the Ada file you have "pragma Import( C, Get5, "GET5", "GET5" );". The first two arguments are required; they specify the interface convention and the imported or exported Ada entity and they can and will be checked by the Ada compiler, so no discussion about them.

The third argument is the external name, that is the spelling used at the source level in the foreign language you are importing from. The fourth argument is the link name, that is the spelling at the assembler level of the symbol you are importing. When you specify both the external name and the link name, the external name is in effect ignored and the link name wins. These arguments cannot be verified by the Ada compiler beyond being string literals so it is up to the programmer to ensure that they are correctly specified.

The Ada package quite correctly specifies (as external name) that the spelling at the C source level is "GET5" (note that casing matters); given a particular C source the external name is the same regardless of which target the C source is compiled for.

The Ada package also specify (as link name) that the external label at the assembler level is "GET5" (casing still matters). The external label resulting from compiling a particular source varies however from one target to another. This phenomenon is best known from the name mangling of C++. The naming conventions of each target determines how e.g. C maps a function name to an external label. Most conventions are one-to-one mappings (typically ELF targets including Solaris, PowerPC EABI and SCORE 80x86 cross); others prefix an underscore (including Windows and SunOS pre-Solaris). Here is the reason why the program links for PowerPC and 80x86 bare and fails for Windows native!

When you interface from Ada to actual C sources you should never need to specify the link name, SCORE Ada will perform the mapping from external name to link name for you. The advantage is that your Ada source is not tied to one particular mapping convention. You should thus write "pragma Import( C, Get5, "GET5" );". This import should really work with any Ada (95) compiler.

So when is link name used? Well, rarely. If you really, really want to import a C++ function directly (without creating a function in the C name space calling it) you might need to write something like "pragma Import( C, PlusPlus, "plusplus", "_plusplus_$ii" );". Note that Ada 95 does not have a standardized interface to C++ as C++ was standardized after Ada 95 (and because it is more complicated since different C++ compilers use different mangling schemes). Note also how non-alphanumeric characters like dollar sign can be specified in the link name (but it is a bad idea making such labels yourself because you cannot use them in C/C++ sources).

So why specify any of external name and link name? To be portable! Sensible Ada 95 compilers will default to something close to "GET5" as external name if neither is specified but this is not standardized (and in SCORE the default for convention C is the local Ada name in lowercase i.e. "get5" which is not what is needed here).

In short: Pragma Import and Export should normally be given three arguments when interfacing to high level languages. If you have two or four then double check!