Next: , Previous: Pragma Import_Exception, Up: Implementation Defined Pragmas


Pragma Import_Function

Syntax:

     pragma Import_Function (
          [Internal                 =>] LOCAL_NAME,
       [, [External                 =>] EXTERNAL_SYMBOL]
       [, [Parameter_Types          =>] PARAMETER_TYPES]
       [, [Result_Type              =>] SUBTYPE_MARK]
       [, [Mechanism                =>] MECHANISM]
       [, [Result_Mechanism         =>] MECHANISM_NAME]
       [, [First_Optional_Parameter =>] IDENTIFIER]);
     
     EXTERNAL_SYMBOL ::=
       IDENTIFIER
     | static_string_EXPRESSION
     
     PARAMETER_TYPES ::=
       null
     | TYPE_DESIGNATOR {, TYPE_DESIGNATOR}
     
     TYPE_DESIGNATOR ::=
       subtype_NAME
     | subtype_Name ' Access
     
     MECHANISM ::=
       MECHANISM_NAME
     | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION})
     
     MECHANISM_ASSOCIATION ::=
       [formal_parameter_NAME =>] MECHANISM_NAME
     
     MECHANISM_NAME ::=
       Value
     | Reference
     | Descriptor [([Class =>] CLASS_NAME)]
     | Short_Descriptor [([Class =>] CLASS_NAME)]
     
     CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca

This pragma is used in conjunction with a pragma Import to specify additional information for an imported function. The pragma Import (or equivalent pragma Interface) must precede the Import_Function pragma and both must appear in the same declarative part as the function specification.

The Internal argument must uniquely designate the function to which the pragma applies. If more than one function name exists of this name in the declarative part you must use the Parameter_Types and Result_Type parameters to achieve the required unique designation. Subtype marks in these parameters must exactly match the subtypes in the corresponding function specification, using positional notation to match parameters with subtype marks. The form with an 'Access attribute can be used to match an anonymous access parameter.

You may optionally use the Mechanism and Result_Mechanism parameters to specify passing mechanisms for the parameters and result. If you specify a single mechanism name, it applies to all parameters. Otherwise you may specify a mechanism on a parameter by parameter basis using either positional or named notation. If the mechanism is not specified, the default mechanism is used.

Passing by descriptor is supported only on the OpenVMS ports of GNAT. The default behavior for Import_Function is to pass a 64bit descriptor unless short_descriptor is specified, then a 32bit descriptor is passed.

First_Optional_Parameter applies only to OpenVMS ports of GNAT. It specifies that the designated parameter and all following parameters are optional, meaning that they are not passed at the generated code level (this is distinct from the notion of optional parameters in Ada where the parameters are passed anyway with the designated optional parameters). All optional parameters must be of mode IN and have default parameter values that are either known at compile time expressions, or uses of the 'Null_Parameter attribute.