gnat_rm.texi

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

* Pragma Volatile::
* Pragma Warnings::
* Pragma Weak_External::
* Pragma Wide_Character_Encoding::
@end menu

@node Pragma Abort_Defer
@unnumberedsec Pragma Abort_Defer
@findex Abort_Defer
@cindex Deferring aborts
@noindent
Syntax:
@smallexample
pragma Abort_Defer;
@end smallexample

@noindent
This pragma must appear at the start of the statement sequence of a
handled sequence of statements (right after the @code{begin}).  It has
the effect of deferring aborts for the sequence of statements (but not
for the declarations or handlers, if any, associated with this statement
sequence).

@node Pragma Ada_83
@unnumberedsec Pragma Ada_83
@findex Ada_83
@noindent
Syntax:
@smallexample @c ada
pragma Ada_83;
@end smallexample

@noindent
A configuration pragma that establishes Ada 83 mode for the unit to
which it applies, regardless of the mode set by the command line
switches.  In Ada 83 mode, GNAT attempts to be as compatible with
the syntax and semantics of Ada 83, as defined in the original Ada
83 Reference Manual as possible.  In particular, the keywords added by Ada 95
and Ada 2005 are not recognized, optional package bodies are allowed,
and generics may name types with unknown discriminants without using
the @code{(<>)} notation.  In addition, some but not all of the additional
restrictions of Ada 83 are enforced.

Ada 83 mode is intended for two purposes.  Firstly, it allows existing
Ada 83 code to be compiled and adapted to GNAT with less effort.
Secondly, it aids in keeping code backwards compatible with Ada 83.
However, there is no guarantee that code that is processed correctly
by GNAT in Ada 83 mode will in fact compile and execute with an Ada
83 compiler, since GNAT does not enforce all the additional checks
required by Ada 83.

@node Pragma Ada_95
@unnumberedsec Pragma Ada_95
@findex Ada_95
@noindent
Syntax:
@smallexample @c ada
pragma Ada_95;
@end smallexample

@noindent
A configuration pragma that establishes Ada 95 mode for the unit to which
it applies, regardless of the mode set by the command line switches.
This mode is set automatically for the @code{Ada} and @code{System}
packages and their children, so you need not specify it in these
contexts.  This pragma is useful when writing a reusable component that
itself uses Ada 95 features, but which is intended to be usable from
either Ada 83 or Ada 95 programs.

@node Pragma Ada_05
@unnumberedsec Pragma Ada_05
@findex Ada_05
@noindent
Syntax:
@smallexample @c ada
pragma Ada_05;
@end smallexample

@noindent
A configuration pragma that establishes Ada 2005 mode for the unit to which
it applies, regardless of the mode set by the command line switches.
This mode is set automatically for the @code{Ada} and @code{System}
packages and their children, so you need not specify it in these
contexts.  This pragma is useful when writing a reusable component that
itself uses Ada 2005 features, but which is intended to be usable from
either Ada 83 or Ada 95 programs.

@node Pragma Ada_2005
@unnumberedsec Pragma Ada_2005
@findex Ada_2005
@noindent
Syntax:
@smallexample @c ada
pragma Ada_2005;
@end smallexample

@noindent
This configuration pragma is a synonym for pragma Ada_05 and has the
same syntax and effect.

@node Pragma Annotate
@unnumberedsec Pragma Annotate
@findex Annotate
@noindent
Syntax:
@smallexample @c ada
pragma Annotate (IDENTIFIER @{, ARG@});

ARG ::= NAME | EXPRESSION
@end smallexample

@noindent
This pragma is used to annotate programs.  @var{identifier} identifies
the type of annotation.  GNAT verifies that it is an identifier, but does
not otherwise analyze it.  The @var{arg} argument
can be either a string literal or an
expression.  String literals are assumed to be of type
@code{Standard.String}.  Names of entities are simply analyzed as entity
names.  All other expressions are analyzed as expressions, and must be
unambiguous.

The analyzed pragma is retained in the tree, but not otherwise processed
by any part of the GNAT compiler.  This pragma is intended for use by
external tools, including ASIS@.

@node Pragma Assert
@unnumberedsec Pragma Assert
@findex Assert
@noindent
Syntax:
@smallexample @c ada
pragma Assert (
  boolean_EXPRESSION
  [, static_string_EXPRESSION]);
@end smallexample

@noindent
The effect of this pragma depends on whether the corresponding command
line switch is set to activate assertions.  The pragma expands into code
equivalent to the following:

@smallexample @c ada
if assertions-enabled then
   if not boolean_EXPRESSION then
      System.Assertions.Raise_Assert_Failure
        (string_EXPRESSION);
   end if;
end if;
@end smallexample

@noindent
The string argument, if given, is the message that will be associated
with the exception occurrence if the exception is raised.  If no second
argument is given, the default message is @samp{@var{file}:@var{nnn}},
where @var{file} is the name of the source file containing the assert,
and @var{nnn} is the line number of the assert.  A pragma is not a
statement, so if a statement sequence contains nothing but a pragma
assert, then a null statement is required in addition, as in:

@smallexample @c ada
@dots{}
if J > 3 then
   pragma Assert (K > 3, "Bad value for K");
   null;
end if;
@end smallexample

@noindent
Note that, as with the @code{if} statement to which it is equivalent, the
type of the expression is either @code{Standard.Boolean}, or any type derived
from this standard type.

If assertions are disabled (switch @code{-gnata} not used), then there
is no run-time effect (and in particular, any side effects from the
expression will not occur at run time).  (The expression is still
analyzed at compile time, and may cause types to be frozen if they are
mentioned here for the first time).

If assertions are enabled, then the given expression is tested, and if
it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
which results in the raising of @code{Assert_Failure} with the given message.

You should generally avoid side effects in the expression arguments of
this pragma, because these side effects will turn on and off with the
setting of the assertions mode, resulting in assertions that have an
effect on the program.  However, the expressions are analyzed for
semantic correctness whether or not assertions are enabled, so turning
assertions on and off cannot affect the legality of a program.

@node Pragma Ast_Entry
@unnumberedsec Pragma Ast_Entry
@cindex OpenVMS
@findex Ast_Entry
@noindent
Syntax:
@smallexample @c ada
pragma AST_Entry (entry_IDENTIFIER);
@end smallexample

@noindent
This pragma is implemented only in the OpenVMS implementation of GNAT@.  The
argument is the simple name of a single entry; at most one @code{AST_Entry}
pragma is allowed for any given entry.  This pragma must be used in
conjunction with the @code{AST_Entry} attribute, and is only allowed after
the entry declaration and in the same task type specification or single task
as the entry to which it applies.  This pragma specifies that the given entry
may be used to handle an OpenVMS asynchronous system trap (@code{AST})
resulting from an OpenVMS system service call.  The pragma does not affect
normal use of the entry.  For further details on this pragma, see the
DEC Ada Language Reference Manual, section 9.12a.

@node Pragma C_Pass_By_Copy
@unnumberedsec Pragma C_Pass_By_Copy
@cindex Passing by copy
@findex C_Pass_By_Copy
@noindent
Syntax:
@smallexample @c ada
pragma C_Pass_By_Copy
  ([Max_Size =>] static_integer_EXPRESSION);
@end smallexample

@noindent
Normally the default mechanism for passing C convention records to C
convention subprograms is to pass them by reference, as suggested by RM
B.3(69).  Use the configuration pragma @code{C_Pass_By_Copy} to change
this default, by requiring that record formal parameters be passed by
copy if all of the following conditions are met:

@itemize @bullet
@item
The size of the record type does not exceed the value specified for
@code{Max_Size}.
@item
The record type has @code{Convention C}.
@item
The formal parameter has this record type, and the subprogram has a
foreign (non-Ada) convention.
@end itemize

@noindent
If these conditions are met the argument is passed by copy, i.e.@: in a
manner consistent with what C expects if the corresponding formal in the
C prototype is a struct (rather than a pointer to a struct).

You can also pass records by copy by specifying the convention
@code{C_Pass_By_Copy} for the record type, or by using the extended
@code{Import} and @code{Export} pragmas, which allow specification of
passing mechanisms on a parameter by parameter basis.

@node Pragma Check_Name
@unnumberedsec Pragma Check_Name
@cindex Defining check names
@cindex Check names, defining
@findex Check_Name
@noindent
Syntax:
@smallexample @c ada
pragma Check_Name (check_name_IDENTIFIER);
@end smallexample

@noindent
This is a configuration pragma that defines a new implementation
defined check name (unless IDENTIFIER matches one of the predefined
check names, in which case the pragma has no effect). Check names
are global to a partition, so if two more more configuration pragmas
are present in a partition mentioning the same name, only one new
check name is introduced.

An implementation defined check name introduced with this pragma may
be used in only three contexts: @code{pragma Suppress},
@code{pragma Unsuppress},
and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
any of these three cases, the check name must be visible. A check
name is visible if it is in the configuration pragmas applying to
the current unit, or if it appears at the start of any unit that
is part of the dependency set of the current unit (e.g. units that
are mentioned in @code{with} clauses.

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

@smallexample @c ada
pragma Comment (static_string_EXPRESSION);
@end smallexample

@noindent
This is almost identical in effect to pragma @code{Ident}.  It allows the
placement of a comment into the object file and hence into the
executable file if the operating system permits such usage.  The
difference is that @code{Comment}, unlike @code{Ident}, has
no limitations on placement of the pragma (it can be placed
anywhere in the main source unit), and if more than one pragma
is used, all comments are retained.

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

@smallexample @c ada
pragma Common_Object (
     [Internal =>] LOCAL_NAME
  [, [External =>] EXTERNAL_SYMBOL]
  [, [Size     =>] EXTERNAL_SYMBOL] );

EXTERNAL_SYMBOL ::=
  IDENTIFIER
| static_string_EXPRESSION
@end smallexample

@noindent
This pragma enables the shared use of variables stored in overlaid
linker areas corresponding to the use of @code{COMMON}
in Fortran.  The single
object @var{LOCAL_NAME} is assigned to the area designated by
the @var{External} argument.
You may define a record to correspond to a series
of fields.  The @var{Size} argument
is syntax checked in GNAT, but otherwise ignored.

@code{Common_Object} is not supported on all platforms.  If no
support is available, then the code generator will issue a message
indicating that the necessary attribute for implementation of this
pragma is not available.

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

@smallexample @c ada
pragma Compile_Time_Error
         (boolean_EXPRESSION, static_string_EXPRESSION);
@end smallexample

@noindent
This pragma can be used to generate additional compile time
error messages. It
is particularly useful in generics, where errors can be issued for
specific problematic instantiations. The first parameter is a boolean
expression. The pragma is effective only if the value of this expression
is known at compile time, and has the value True. The set of expressions
whose values are known at compile time includes all static boolean
expressions, and also other values which the compiler can determine
at compile time (e.g. the size of a record type set by an explicit
size representation clause, or the value of a variable which was
initialized to a constant and is known not to have been modified).
If these conditions are met, an error message is generated using
the value given as the second argument. This string value may contain
embedded ASCII.LF characters to break the message into multiple lines.

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

@smallexample @c ada
pragma Compile_Time_Warning
         (boolean_EXPRESSION, static_string_EXPRESSION);
@end smallexample

@noindent
Same as pragma Compile_Time_Error, except a warning is issued instead
of an error message.

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

@smallexample @c ada
pragma Complete_Representation;
@end smallexample

@noindent
This pragma must appear immediately within a record representation
clause. Typical placements are before the first component clause
or after the last component clause. The effect is to give an error
message if any component is missing a component clause. This pragma
may be used to ensure that a record representation clause is
complete, and that this invariant is maintained if fields are
added to the record in the future.

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