gnat_rm.texi

来自「理解和实践操作系统的一本好书」· TEXI 代码 · 共 1,978 行 · 第 1/5 页

compilation unit Namet in the compiler sources for details).

The remaining parameters (OVERLOADING_RESOLUTION) are optionally used
to distinguish between overloaded subprograms. If a pragma does not contain
the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded
subprograms denoted by the first two parameters.

Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram
to be eliminated in a manner similar to that used for the extended
@code{Import} and @code{Export} pragmas, except that the subtype names are
always given as strings. At the moment, this form of distinguishing
overloaded subprograms is implemented only partially, so we do not recommend
using it for practical subprogram elimination.

Note that in case of a parameterless procedure its profile is represented
as @code{Parameter_Types => ("")}

Alternatively, the @code{Source_Location} parameter is used to specify
which overloaded alternative is to be eliminated by pointing to the
location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the
source text. The string literal (or concatenation of string literals)
given as SOURCE_TRACE must have the following format:

@smallexample @c ada
SOURCE_TRACE ::= SOURCE_LOCATION@{LBRACKET SOURCE_LOCATION RBRACKET@}

LBRACKET ::= [
RBRACKET ::= ]

SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER
FILE_NAME       ::= STRING_LITERAL
LINE_NUMBER     ::= DIGIT @{DIGIT@}
@end smallexample

SOURCE_TRACE should be the short name of the source file (with no directory
information), and LINE_NUMBER is supposed to point to the line where the
defining name of the subprogram is located.

For the subprograms that are not a part of generic instantiations, only one
SOURCE_LOCATION is used. If a subprogram is declared in a package
instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is
the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the
second one denotes the declaration of the corresponding subprogram in the
generic package. This approach is recursively used to create SOURCE_LOCATIONs
in case of nested instantiations.

The effect of the pragma is to allow the compiler to eliminate
the code or data associated with the named entity.  Any reference to
an eliminated entity outside the compilation unit it is defined in,
causes a compile time or link time error.

The intention of pragma @code{Eliminate} is to allow a program to be compiled
in a system independent manner, with unused entities eliminated, without
the requirement of modifying the source text.  Normally the required set
of @code{Eliminate} pragmas is constructed automatically using the gnatelim
tool. Elimination of unused entities local to a compilation unit is
automatic, without requiring the use of pragma @code{Eliminate}.

Note that the reason this pragma takes string literals where names might
be expected is that a pragma @code{Eliminate} can appear in a context where the
relevant names are not visible.

Note that any change in the source files that includes removing, splitting of
adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION
parameter illegal.

It is legal to use pragma Eliminate where the referenced entity is a
dispatching operation, but it is not clear what this would mean, since
in general the call does not know which entity is actually being called.
Consequently, a pragma Eliminate for a dispatching operation is ignored.

@node Pragma Export_Exception
@unnumberedsec Pragma Export_Exception
@cindex OpenVMS
@findex Export_Exception
@noindent
Syntax:

@smallexample @c ada
pragma Export_Exception (
     [Internal =>] LOCAL_NAME
  [, [External =>] EXTERNAL_SYMBOL]
  [, [Form     =>] Ada | VMS]
  [, [Code     =>] static_integer_EXPRESSION]);

EXTERNAL_SYMBOL ::=
  IDENTIFIER
| static_string_EXPRESSION
@end smallexample

@noindent
This pragma is implemented only in the OpenVMS implementation of GNAT@.  It
causes the specified exception to be propagated outside of the Ada program,
so that it can be handled by programs written in other OpenVMS languages.
This pragma establishes an external name for an Ada exception and makes the
name available to the OpenVMS Linker as a global symbol.  For further details
on this pragma, see the
DEC Ada Language Reference Manual, section 13.9a3.2.

@node Pragma Export_Function
@unnumberedsec Pragma Export_Function
@cindex Argument passing mechanisms
@findex Export_Function

@noindent
Syntax:

@smallexample @c ada
pragma Export_Function (
     [Internal         =>] LOCAL_NAME
  [, [External         =>] EXTERNAL_SYMBOL]
  [, [Parameter_Types  =>] PARAMETER_TYPES]
  [, [Result_Type      =>] result_SUBTYPE_MARK]
  [, [Mechanism        =>] MECHANISM]
  [, [Result_Mechanism =>] MECHANISM_NAME]);

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)]

CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
@end smallexample

@noindent
Use this pragma to make a function externally callable and optionally
provide information on mechanisms to be used for passing parameter and
result values.  We recommend, for the purposes of improving portability,
this pragma always be used in conjunction with a separate pragma
@code{Export}, which must precede the pragma @code{Export_Function}.
GNAT does not require a separate pragma @code{Export}, but if none is
present, @code{Convention Ada} is assumed, which is usually
not what is wanted, so it is usually appropriate to use this
pragma in conjunction with a @code{Export} or @code{Convention}
pragma that specifies the desired foreign convention.
Pragma @code{Export_Function}
(and @code{Export}, if present) must appear in the same declarative
region as the function to which they apply.

@var{internal_name} 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 @code{Parameter_Types} and
@code{Result_Type} parameters is mandatory to achieve the required
unique designation.  @var{subtype_mark}s 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 @code{'Access} attribute can be used to match an
anonymous access parameter.

@cindex OpenVMS
@cindex Passing by descriptor
Passing by descriptor is supported only on the OpenVMS ports of GNAT@.

@cindex Suppressing external name
Special treatment is given if the EXTERNAL is an explicit null
string or a static string expressions that evaluates to the null
string. In this case, no external name is generated. This form
still allows the specification of parameter mechanisms.

@node Pragma Export_Object
@unnumberedsec Pragma Export_Object
@findex Export_Object
@noindent
Syntax:

@smallexample @c ada
pragma Export_Object
      [Internal =>] LOCAL_NAME
   [, [External =>] EXTERNAL_SYMBOL]
   [, [Size     =>] EXTERNAL_SYMBOL]

EXTERNAL_SYMBOL ::=
  IDENTIFIER
| static_string_EXPRESSION
@end smallexample

@noindent
This pragma designates an object as exported, and apart from the
extended rules for external symbols, is identical in effect to the use of
the normal @code{Export} pragma applied to an object.  You may use a
separate Export pragma (and you probably should from the point of view
of portability), but it is not required.  @var{Size} is syntax checked,
but otherwise ignored by GNAT@.

@node Pragma Export_Procedure
@unnumberedsec Pragma Export_Procedure
@findex Export_Procedure
@noindent
Syntax:

@smallexample @c ada
pragma Export_Procedure (
     [Internal        =>] LOCAL_NAME
  [, [External        =>] EXTERNAL_SYMBOL]
  [, [Parameter_Types =>] PARAMETER_TYPES]
  [, [Mechanism       =>] MECHANISM]);

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)]

CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
@end smallexample

@noindent
This pragma is identical to @code{Export_Function} except that it
applies to a procedure rather than a function and the parameters
@code{Result_Type} and @code{Result_Mechanism} are not permitted.
GNAT does not require a separate pragma @code{Export}, but if none is
present, @code{Convention Ada} is assumed, which is usually
not what is wanted, so it is usually appropriate to use this
pragma in conjunction with a @code{Export} or @code{Convention}
pragma that specifies the desired foreign convention.

@cindex OpenVMS
@cindex Passing by descriptor
Passing by descriptor is supported only on the OpenVMS ports of GNAT@.

@cindex Suppressing external name
Special treatment is given if the EXTERNAL is an explicit null
string or a static string expressions that evaluates to the null
string. In this case, no external name is generated. This form
still allows the specification of parameter mechanisms.

@node Pragma Export_Value
@unnumberedsec Pragma Export_Value
@findex Export_Value
@noindent
Syntax:

@smallexample @c ada
pragma Export_Value (
  [Value     =>] static_integer_EXPRESSION,
  [Link_Name =>] static_string_EXPRESSION);
@end smallexample

@noindent
This pragma serves to export a static integer value for external use.
The first argument specifies the value to be exported. The Link_Name
argument specifies the symbolic name to be associated with the integer
value. This pragma is useful for defining a named static value in Ada
that can be referenced in assembly language units to be linked with
the application. This pragma is currently supported only for the
AAMP target and is ignored for other targets.

@node Pragma Export_Valued_Procedure
@unnumberedsec Pragma Export_Valued_Procedure
@findex Export_Valued_Procedure
@noindent
Syntax:

@smallexample @c ada
pragma Export_Valued_Procedure (
     [Internal        =>] LOCAL_NAME
  [, [External        =>] EXTERNAL_SYMBOL]
  [, [Parameter_Types =>] PARAMETER_TYPES]
  [, [Mechanism       =>] MECHANISM]);

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)]

CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
@end smallexample

@noindent
This pragma is identical to @code{Export_Procedure} except that the
first parameter of @var{LOCAL_NAME}, which must be present, must be of
mode @code{OUT}, and externally the subprogram is treated as a function
with this parameter as the result of the function.  GNAT provides for
this capability to allow the use of @code{OUT} and @code{IN OUT}
parameters in interfacing to external functions (which are not permitted
in Ada functions).
GNAT does not require a separate pragma @code{Export}, but if none is
present, @code{Convention Ada} is assumed, which is almost certainly
not what is wanted since the whole point of this pragma is to interface
with foreign language functions, so it is usually appropriate to use this
pragma in conjunction with a @code{Export} or @code{Convention}
pragma that specifies the desired foreign convention.

@cindex OpenVMS
@cindex Passing by descriptor
Passing by descriptor is supported only on the OpenVMS ports of GNAT@.

@cindex Suppressing external name
Special treatment is given if the EXTERNAL is an explicit null
string or a static string expressions that evaluates to the null
string. In this case, no external name is generated. This form
still allows the specification of parameter mechanisms.

@node Pragma Extend_System
@unnumberedsec Pragma Extend_System
@cindex @code{system}, extending
@cindex Dec Ada 83
@findex Extend_System
@noindent
Syntax:

@smallexample @c ada
pragma Extend_System ([Name =>] IDENTIFIER);
@end smallexample

@noindent
This pragma is used to provide backwards compatibility with other
implementations that extend the facilities of package @code{System}.  In
GNAT, @code{System} contains only the definitions that are present in
the Ada RM@.  However, other implementations, notably the DEC Ada 83
implementation, provide many extensions to package @code{System}.

For each such implementation accommodated by this pragma, GNAT provides a
package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
implementation, which provides the required additional definitions.  You
can use this package in two ways.  You can @code{with} it in the normal
way and access entities either by selection or using a @code{use}
clause.  In this case no special processing is required.

However, if existing code contains references such as
@code{System.@var{xxx}} where @var{xxx} is an entity in the extended
definitions provided in package @code{System}, you may use this pragma
to extend visibility in @code{System} in a non-standard way that
provides greater compatibility with the existing code.  Pragma
@code{Extend_System} is a configuration pragma whose single argument is
the name of the package containing the extended definition
(e.g.@: @code{Aux_DEC} for the DEC Ada case).  A unit compiled under
control of this pragma will be processed using special visibility
processing that looks in package @code{System.Aux_@var{xxx}} where
@code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
package @code{System}, but not found in package @code{System}.

You can use this pragma either to access a predefined @code{System}
extension supplied with the compiler, for example @code{Aux_DEC} or
you can construct your own extension unit