+2017-09-08 Arnaud Charlet <charlet@adacore.com>
+
+ * gnat_rm.texi, gnat_ugn.texi,
+ doc/gnat_ugn/the_gnat_compilation_model.rst,
+ doc/gnat_ugn/getting_started_with_gnat.rst,
+ doc/gnat_ugn/inline_assembler.rst,
+ doc/gnat_ugn/building_executable_programs_with_gnat.rst,
+ doc/gnat_ugn/elaboration_order_handling_in_gnat.rst,
+ doc/gnat_ugn/about_this_guide.rst,
+ doc/gnat_ugn/platform_specific_information.rst,
+ doc/gnat_ugn/example_of_binder_output.rst,
+ doc/gnat_ugn/gnat_and_program_execution.rst,
+ doc/gnat_ugn/gnat_utility_programs.rst,
+ doc/gnat_rm/implementation_of_specific_ada_features.rst,
+ doc/gnat_rm/interfacing_to_other_languages.rst,
+ doc/gnat_rm/implementation_defined_aspects.rst,
+ doc/gnat_rm/intrinsic_subprograms.rst,
+ doc/gnat_rm/implementation_defined_characteristics.rst,
+ doc/gnat_rm/implementation_advice.rst,
+ doc/gnat_rm/implementation_defined_attributes.rst,
+ doc/gnat_rm/compatibility_and_porting_guide.rst,
+ doc/gnat_rm/standard_library_routines.rst,
+ doc/gnat_rm/the_gnat_library.rst,
+ doc/gnat_rm/implementation_defined_pragmas.rst,
+ doc/gnat_rm/representation_clauses_and_pragmas.rst,
+ doc/gnat_rm/standard_and_implementation_defined_restrictions.rst,
+ doc/gnat_rm/obsolescent_features.rst,
+ doc/gnat_rm/about_this_guide.rst,
+ doc/gnat_rm/the_implementation_of_standard_i_o.rst,
+ doc/gnat_rm/implementation_of_ada_2012_features.rst,
+ doc/gnat_ugn.rst,
+ doc/gnat_rm.rst: Update documentation.
+
+2017-09-08 Arnaud Charlet <charlet@adacore.com>
+
+ * s-dwalin.ads, s-dwalin.adb, s-trasym-dwarf.adb, s-objrea.ads,
+ s-objrea.adb, s-tsmona-linux.adb, s-tsmona-mingw.adb: New.
+ * gcc-interface/Makefile.in: Enable s-trasym-dwarf.adb on x86*linux.
+
2017-09-08 Bob Duff <duff@adacore.com>
* s-ststop.ads, s-ststop.adb, rtsfind.ads (String_Input_Tag):
GNAT Reference Manual
=====================
-*GNAT, The GNU Ada Development Environment*
+.. only:: not latex
-.. only:: PRO
+ *GNAT, The GNU Ada Development Environment*
- *GNAT Pro Edition*
+ .. only:: PRO
- | Version |version|
- | Date: |today|
+ *GNAT Pro Edition*
-.. only:: GPL
+ | Version |version|
+ | Date: |today|
- *GNAT GPL Edition*
+ .. only:: GPL
- | Version |version|
- | Date: |today|
+ *GNAT GPL Edition*
-.. only:: FSF
+ | Version |version|
+ | Date: |today|
- .. raw:: texinfo
+ .. only:: FSF
- @include gcc-common.texi
- GCC version @value{version-GCC}@*
+ .. raw:: texinfo
-AdaCore
+ @include gcc-common.texi
+ GCC version @value{version-GCC}@*
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being "GNAT Reference
-Manual", and with no Back-Cover Texts. A copy of the license is
-included in the section entitled :ref:`gnu_fdl`.
+ AdaCore
+
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3 or
+ any later version published by the Free Software Foundation; with no
+ Invariant Sections, with the Front-Cover Texts being "GNAT Reference
+ Manual", and with no Back-Cover Texts. A copy of the license is
+ included in the section entitled :ref:`gnu_fdl`.
.. toctree::
:numbered:
Following are examples of the typographical and graphic conventions used
in this guide:
-* `Functions`, `utility program names`, `standard names`,
- and `classes`.
+* ``Functions``, ``utility program names``, ``standard names``,
+ and ``classes``.
-* `Option flags`
+* ``Option flags``
* :file:`File names`
-* `Variables`
+* ``Variables``
* *Emphasis*
=========================================
The Ada Reference Manual gives an implementation freedom to choose bounds
-that are narrower by `Small` from the given bounds.
+that are narrower by ``Small`` from the given bounds.
For example, if we write
.. code-block:: ada
First, why does this freedom exist, and why would an implementation
take advantage of it? To answer this, take a closer look at the type
-declaration for `F1` above. If the compiler uses the given bounds,
+declaration for ``F1`` above. If the compiler uses the given bounds,
it would need 9 bits to hold the largest positive value (and typically
that means 16 bits on all machines). But if the implementation chooses
the +127.0 bound then it can fit values of the type in 8 bits.
(a) those that narrow the range automatically if they can figure
out that the narrower range will allow storage in a smaller machine unit,
-(b) those that will narrow only if forced to by a `'Size` clause, and
+(b) those that will narrow only if forced to by a ``'Size`` clause, and
(c) those that will never narrow.
the categories (a), (b) or (c) above.
So, how do you get the compiler to do what you want? The answer is give the
-actual bounds you want, and then use a `'Small` clause and a
-`'Size` clause to absolutely pin down what the compiler does.
-E.g., for `F2` above, we will write:
+actual bounds you want, and then use a ``'Small`` clause and a
+``'Size`` clause to absolutely pin down what the compiler does.
+E.g., for ``F2`` above, we will write:
.. code-block:: ada
* *Character literals*
Some uses of character literals are ambiguous. Since Ada 95 has introduced
- `Wide_Character` as a new predefined character type, some uses of
+ ``Wide_Character`` as a new predefined character type, some uses of
character literals that were legal in Ada 83 are illegal in Ada 95.
For example:
for Char in 'A' .. 'Z' loop ... end loop;
The problem is that 'A' and 'Z' could be from either
- `Character` or `Wide_Character`. The simplest correction
+ ``Character`` or ``Wide_Character``. The simplest correction
is to make the type explicit; e.g.:
.. code-block:: ada
* *New reserved words*
- The identifiers `abstract`, `aliased`, `protected`,
- `requeue`, `tagged`, and `until` are reserved in Ada 95.
+ The identifiers ``abstract``, ``aliased``, ``protected``,
+ ``requeue``, ``tagged``, and ``until`` are reserved in Ada 95.
Existing Ada 83 code using any of these identifiers must be edited to
use some alternative name.
body if it is empty, or, if it is non-empty, introduce a dummy declaration
into the spec that makes the body required. One approach is to add a private
part to the package declaration (if necessary), and define a parameterless
- procedure called `Requires_Body`, which must then be given a dummy
+ procedure called ``Requires_Body``, which must then be given a dummy
procedure body in the package body, which then becomes required.
Another approach (assuming that this does not introduce elaboration
- circularities) is to add an `Elaborate_Body` pragma to the package spec,
+ circularities) is to add an ``Elaborate_Body`` pragma to the package spec,
since one effect of this pragma is to require the presence of a package body.
* *Numeric_Error is the same exception as Constraint_Error*
- In Ada 95, the exception `Numeric_Error` is a renaming of `Constraint_Error`.
+ In Ada 95, the exception ``Numeric_Error`` is a renaming of ``Constraint_Error``.
This means that it is illegal to have separate exception handlers for
the two exceptions. The fix is simply to remove the handler for the
- `Numeric_Error` case (since even in Ada 83, a compiler was free to raise
- `Constraint_Error` in place of `Numeric_Error` in all cases).
+ ``Numeric_Error`` case (since even in Ada 83, a compiler was free to raise
+ ``Constraint_Error`` in place of ``Numeric_Error`` in all cases).
* *Indefinite subtypes in generics*
- In Ada 83, it was permissible to pass an indefinite type (e.g, `String`)
+ In Ada 83, it was permissible to pass an indefinite type (e.g, ``String``)
as the actual for a generic formal private type, but then the instantiation
would be illegal if there were any instances of declarations of variables
of this type in the generic body. In Ada 95, to avoid this clear violation
of the methodological principle known as the 'contract model',
the generic declaration explicitly indicates whether
or not such instantiations are permitted. If a generic formal parameter
- has explicit unknown discriminants, indicated by using `(<>)` after the
+ has explicit unknown discriminants, indicated by using ``(<>)`` after the
subtype name, then it can be instantiated with indefinite types, but no
stand-alone variables can be declared of this type. Any attempt to declare
such a variable will result in an illegality at the time the generic is
- declared. If the `(<>)` notation is not used, then it is illegal
+ declared. If the ``(<>)`` notation is not used, then it is illegal
to instantiate the generic with an indefinite type.
This is the potential incompatibility issue when porting Ada 83 code to Ada 95.
It will show up as a compile time error, and
- the fix is usually simply to add the `(<>)` to the generic declaration.
+ the fix is usually simply to add the ``(<>)`` to the generic declaration.
.. _More_deterministic_semantics:
Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not
possible in Ada 83. Fortunately this is extremely rare, but the one
situation that you should be alert to is the change in the predefined type
-`Character` from 7-bit ASCII to 8-bit Latin-1.
+``Character`` from 7-bit ASCII to 8-bit Latin-1.
.. index:: Latin-1
-* *Range of type `Character`*
+* *Range of type ``Character``*
- The range of `Standard.Character` is now the full 256 characters
+ The range of ``Standard.Character`` is now the full 256 characters
of Latin-1, whereas in most Ada 83 implementations it was restricted
to 128 characters. Although some of the effects of
this change will be manifest in compile-time rejection of legal
Ada 83 programs it is possible for a working Ada 83 program to have
a different effect in Ada 95, one that was not permitted in Ada 83.
As an example, the expression
- `Character'Pos(Character'Last)` returned `127` in Ada 83 and now
- delivers `255` as its value.
+ ``Character'Pos(Character'Last)`` returned ``127`` in Ada 83 and now
+ delivers ``255`` as its value.
In general, you should look at the logic of any
character-processing Ada 83 program and see whether it needs to be adapted
to work correctly with Latin-1. Note that the predefined Ada 95 API has a
as identifiers as in Ada 83. However,
in practice, it is usually advisable to make the necessary modifications
to the program to remove the need for using this switch.
- See the `Compiling Different Versions of Ada` section in
+ See the ``Compiling Different Versions of Ada`` section in
the :title:`GNAT User's Guide`.
compilers are allowed, but not required, to implement these missing
elements. In contrast with some other compilers, GNAT implements all
such pragmas and attributes, eliminating this compatibility concern. These
- include `pragma Interface` and the floating point type attributes
- (`Emax`, `Mantissa`, etc.), among other items.
+ include ``pragma Interface`` and the floating point type attributes
+ (``Emax``, ``Mantissa``, etc.), among other items.
.. _Compatibility_between_Ada_95_and_Ada_2005:
* *New reserved words.*
- The words `interface`, `overriding` and `synchronized` are
+ The words ``interface``, ``overriding`` and ``synchronized`` are
reserved in Ada 2005.
A pre-Ada 2005 program that uses any of these as an identifier will be
illegal.
* *New declarations in predefined packages.*
A number of packages in the predefined environment contain new declarations:
- `Ada.Exceptions`, `Ada.Real_Time`, `Ada.Strings`,
- `Ada.Strings.Fixed`, `Ada.Strings.Bounded`,
- `Ada.Strings.Unbounded`, `Ada.Strings.Wide_Fixed`,
- `Ada.Strings.Wide_Bounded`, `Ada.Strings.Wide_Unbounded`,
- `Ada.Tags`, `Ada.Text_IO`, and `Interfaces.C`.
- If an Ada 95 program does a `with` and `use` of any of these
+ ``Ada.Exceptions``, ``Ada.Real_Time``, ``Ada.Strings``,
+ ``Ada.Strings.Fixed``, ``Ada.Strings.Bounded``,
+ ``Ada.Strings.Unbounded``, ``Ada.Strings.Wide_Fixed``,
+ ``Ada.Strings.Wide_Bounded``, ``Ada.Strings.Wide_Unbounded``,
+ ``Ada.Tags``, ``Ada.Text_IO``, and ``Interfaces.C``.
+ If an Ada 95 program does a ``with`` and ``use`` of any of these
packages, the new declarations may cause name clashes.
* *Access parameters.*
are now ambiguous.
The ambiguity may be resolved either by applying a type conversion to the
expression, or by explicitly invoking the operation from package
- `Standard`.
+ ``Standard``.
* *Return-by-reference types.*
Ada compilers are allowed to supplement the language-defined pragmas, and
these are a potential source of non-portability. All GNAT-defined pragmas
-are described in the `Implementation Defined Pragmas` chapter of the
-:title:`GNAT Reference Manual`, and these include several that are specifically
+are described in :ref:`Implementation_Defined_Pragmas`,
+and these include several that are specifically
intended to correspond to other vendors' Ada 83 pragmas.
-For migrating from VADS, the pragma `Use_VADS_Size` may be useful.
+For migrating from VADS, the pragma ``Use_VADS_Size`` may be useful.
For compatibility with HP Ada 83, GNAT supplies the pragmas
-`Extend_System`, `Ident`, `Inline_Generic`,
-`Interface_Name`, `Passive`, `Suppress_All`,
-and `Volatile`.
-Other relevant pragmas include `External` and `Link_With`.
+``Extend_System``, ``Ident``, ``Inline_Generic``,
+``Interface_Name``, ``Passive``, ``Suppress_All``,
+and ``Volatile``.
+Other relevant pragmas include ``External`` and ``Link_With``.
Some vendor-specific
-Ada 83 pragmas (`Share_Generic`, `Subtitle`, and `Title`) are
+Ada 83 pragmas (``Share_Generic``, ``Subtitle``, and ``Title``) are
recognized, thus
avoiding compiler rejection of units that contain such pragmas; they are not
relevant in a GNAT context and hence are not otherwise implemented.
Analogous to pragmas, the set of attributes may be extended by an
implementation. All GNAT-defined attributes are described in
-`Implementation Defined Attributes` section of the
-:title:`GNAT Reference Manual`, and these include several that are specifically intended
+:ref:`Implementation_Defined_Attributes`,
+and these include several that are specifically intended
to correspond to other vendors' Ada 83 attributes. For migrating from VADS,
-the attribute `VADS_Size` may be useful. For compatibility with HP
-Ada 83, GNAT supplies the attributes `Bit`, `Machine_Size` and
-`Type_Class`.
+the attribute ``VADS_Size`` may be useful. For compatibility with HP
+Ada 83, GNAT supplies the attributes ``Bit``, ``Machine_Size`` and
+``Type_Class``.
.. _Libraries:
to invoke a subprogram before its body has been elaborated, or to instantiate
a generic before the generic body has been elaborated. By default GNAT
attempts to choose a safe order (one that will not encounter access before
-elaboration problems) by implicitly inserting `Elaborate` or
-`Elaborate_All` pragmas where
+elaboration problems) by implicitly inserting ``Elaborate`` or
+``Elaborate_All`` pragmas where
needed. However, this can lead to the creation of elaboration circularities
and a resulting rejection of the program by gnatbind. This issue is
-thoroughly described in the `Elaboration Order Handling in GNAT` appendix
+thoroughly described in the *Elaboration Order Handling in GNAT* appendix
in the :title:`GNAT User's Guide`.
In brief, there are several
ways to deal with this situation:
* Modify the program to eliminate the circularities, e.g., by moving
elaboration-time code into explicitly-invoked procedures
-* Constrain the elaboration order by including explicit `Elaborate_Body` or
- `Elaborate` pragmas, and then inhibit the generation of implicit
- `Elaborate_All`
+* Constrain the elaboration order by including explicit ``Elaborate_Body`` or
+ ``Elaborate`` pragmas, and then inhibit the generation of implicit
+ ``Elaborate_All``
pragmas either globally (as an effect of the *-gnatE* switch) or locally
(by selectively suppressing elaboration checks via pragma
- `Suppress(Elaboration_Check)` when it is safe to do so).
+ ``Suppress(Elaboration_Check)`` when it is safe to do so).
.. _Target-specific_aspects:
Reference Manuals as implementation advice that is followed by GNAT.
The problem will show up as an error
message rejecting the size clause. The fix is simply to provide
- the explicit pragma `Pack`, or for more fine tuned control, provide
+ the explicit pragma ``Pack``, or for more fine tuned control, provide
a Component_Size clause.
* *Meaning of Size Attribute*
The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as
the minimal number of bits required to hold values of the type. For example,
- on a 32-bit machine, the size of `Natural` will typically be 31 and not
+ on a 32-bit machine, the size of ``Natural`` will typically be 31 and not
32 (since no sign bit is required). Some Ada 83 compilers gave 31, and
some 32 in this situation. This problem will usually show up as a compile
time error, but not always. It is a good idea to check all uses of the
=============================
"If an implementation detects the use of an unsupported Specialized Needs
- Annex feature at run time, it should raise `Program_Error` if
+ Annex feature at run time, it should raise ``Program_Error`` if
feasible."
Not relevant. All specialized needs annex features are either supported,
============================
"If an implementation detects a bounded error or erroneous
- execution, it should raise `Program_Error`."
+ execution, it should raise ``Program_Error``."
Followed in all cases in which the implementation detects a bounded
error or erroneous execution. Not all such situations are detected at
"Normally, an implementation should not define pragmas that can
make an illegal program legal, except as follows:
- * A pragma used to complete a declaration, such as a pragma `Import`;
+ * A pragma used to complete a declaration, such as a pragma ``Import``;
* A pragma used to configure the environment by adding, removing, or
- replacing `library_items`."
+ replacing ``library_items``."
See :ref:`RM_2_8_16_Pragmas`.
=======================================
"If an implementation supports a mode with alternative interpretations
- for `Character` and `Wide_Character`, the set of graphic
- characters of `Character` should nevertheless remain a proper
- subset of the set of graphic characters of `Wide_Character`. Any
+ for ``Character`` and ``Wide_Character``, the set of graphic
+ characters of ``Character`` should nevertheless remain a proper
+ subset of the set of graphic characters of ``Wide_Character``. Any
character set 'localizations' should be reflected in the results of
the subprograms defined in the language-defined package
- `Characters.Handling` (see A.3) available in such a mode. In a mode with
- an alternative interpretation of `Character`, the implementation should
+ ``Characters.Handling`` (see A.3) available in such a mode. In a mode with
+ an alternative interpretation of ``Character``, the implementation should
also support a corresponding change in what is a legal
- `identifier_letter`."
+ ``identifier_letter``."
Not all wide character modes follow this advice, in particular the JIS
and IEC modes reflect standard usage in Japan, and in these encoding,
RM 3.5.4(28): Integer Types
===========================
- "An implementation should support `Long_Integer` in addition to
- `Integer` if the target machine supports 32-bit (or longer)
+ "An implementation should support ``Long_Integer`` in addition to
+ ``Integer`` if the target machine supports 32-bit (or longer)
arithmetic. No other named integer subtypes are recommended for package
- `Standard`. Instead, appropriate named integer subtypes should be
- provided in the library package `Interfaces` (see B.2)."
+ ``Standard``. Instead, appropriate named integer subtypes should be
+ provided in the library package ``Interfaces`` (see B.2)."
-`Long_Integer` is supported. Other standard integer types are supported
+``Long_Integer`` is supported. Other standard integer types are supported
so this advice is not fully followed. These types
are supported for convenient interface to C, and so that all hardware
types of the machine are easily available.
"An implementation for a two's complement machine should support
modular types with a binary modulus up to ``System.Max_Int*2+2``. An
- implementation should support a non-binary modules up to `Integer'Last`."
+ implementation should support a non-binary modules up to ``Integer'Last``."
Followed.
subtype, if the value of the operand does not correspond to the internal
code for any enumeration literal of its type (perhaps due to an
un-initialized variable), then the implementation should raise
- `Program_Error`. This is particularly important for enumeration
+ ``Program_Error``. This is particularly important for enumeration
types with noncontiguous internal codes specified by an
enumeration_representation_clause."
RM 3.5.7(17): Float Types
=========================
- "An implementation should support `Long_Float` in addition to
- `Float` if the target machine supports 11 or more digits of
+ "An implementation should support ``Long_Float`` in addition to
+ ``Float`` if the target machine supports 11 or more digits of
precision. No other named floating point subtypes are recommended for
- package `Standard`. Instead, appropriate named floating point subtypes
- should be provided in the library package `Interfaces` (see B.2)."
+ package ``Standard``. Instead, appropriate named floating point subtypes
+ should be provided in the library package ``Interfaces`` (see B.2)."
-`Short_Float` and `Long_Long_Float` are also provided. The
+``Short_Float`` and ``Long_Long_Float`` are also provided. The
former provides improved compatibility with other implementations
supporting this type. The latter corresponds to the highest precision
floating-point type supported by the hardware. On most machines, this
-will be the same as `Long_Float`, but on some machines, it will
+will be the same as ``Long_Float``, but on some machines, it will
correspond to the IEEE extended form. The notable case is all ia32
-(x86) implementations, where `Long_Long_Float` corresponds to
+(x86) implementations, where ``Long_Long_Float`` corresponds to
the 80-bit extended precision format supported in hardware on this
processor. Note that the 128-bit format on SPARC is not supported,
since this is a software rather than a hardware format.
"An implementation should normally represent multidimensional arrays in
row-major order, consistent with the notation used for multidimensional
- array aggregates (see 4.3.3). However, if a pragma `Convention`
- (`Fortran`, ...) applies to a multidimensional array type, then
- column-major order should be used instead (see B.5, `Interfacing with Fortran`)."
+ array aggregates (see 4.3.3). However, if a pragma ``Convention``
+ (``Fortran``, ...) applies to a multidimensional array type, then
+ column-major order should be used instead (see B.5, *Interfacing with Fortran*)."
Followed.
RM 9.6(30-31): Duration'Small
=============================
- "Whenever possible in an implementation, the value of `Duration'Small`
+ "Whenever possible in an implementation, the value of ``Duration'Small``
should be no greater than 100 microseconds."
-Followed. (`Duration'Small` = 10**(-9)).
+Followed. (``Duration'Small`` = 10**(-9)).
- "The time base for `delay_relative_statements` should be monotonic;
- it need not be the same time base as used for `Calendar.Clock`."
+ "The time base for ``delay_relative_statements`` should be monotonic;
+ it need not be the same time base as used for ``Calendar.Clock``."
Followed.
RM 11.4.1(19): Exception Information
====================================
- "`Exception_Message` by default and `Exception_Information`
+ "``Exception_Message`` by default and ``Exception_Information``
should produce information useful for
- debugging. `Exception_Message` should be short, about one
- line. `Exception_Information` can be long. `Exception_Message`
+ debugging. ``Exception_Message`` should be short, about one
+ line. ``Exception_Information`` can be long. ``Exception_Message``
should not include the
- `Exception_Name`. `Exception_Information` should include both
- the `Exception_Name` and the `Exception_Message`."
+ ``Exception_Name``. ``Exception_Information`` should include both
+ the ``Exception_Name`` and the ``Exception_Message``."
Followed. For each exception that doesn't have a specified
-`Exception_Message`, the compiler generates one containing the location
+``Exception_Message``, the compiler generates one containing the location
of the raise statement. This location has the form 'file_name:line', where
file_name is the short file name (without path information) and line is the line
number in the file. Note that in the case of the Zero Cost Exception
mechanism, these messages become redundant with the Exception_Information that
contains a full backtrace of the calling sequence, so they are disabled.
To disable explicitly the generation of the source location message, use the
-Pragma `Discard_Names`.
+Pragma ``Discard_Names``.
.. index:: Suppression of checks
for Y'Address use X'Address;>>
- "An implementation need not support a specification for the `Size`
+ "An implementation need not support a specification for the ``Size``
for a given composite subtype, nor the size or storage place for an
object (including a component) of a given composite subtype, unless the
constraints on the subtype and its composite subcomponents (if any) are
speed of accessing components, subject to reasonable complexity in
addressing calculations.
- The recommended level of support pragma `Pack` is:
+ The recommended level of support pragma ``Pack`` is:
For a packed record type, the components should be packed as tightly as
possible subject to the Sizes of the component subtypes, and subject to
- any `record_representation_clause` that applies to the type; the
+ any *record_representation_clause* that applies to the type; the
implementation may, but need not, reorder components or cross aligned
- word boundaries to improve the packing. A component whose `Size` is
+ word boundaries to improve the packing. A component whose ``Size`` is
greater than the word size may be allocated an integral number of words."
Followed. Tight packing of arrays is supported for all component sizes
RM 13.3(14-19): Address Clauses
===============================
- "For an array `X`, ``X'Address`` should point at the first
+ "For an array ``X``, ``X'Address`` should point at the first
component of the array, and not at the array bounds."
Followed.
- "The recommended level of support for the `Address` attribute is:
+ "The recommended level of support for the ``Address`` attribute is:
- ``X'Address`` should produce a useful result if `X` is an
+ ``X'Address`` should produce a useful result if ``X`` is an
object that is aliased or of a by-reference type, or is an entity whose
- `Address` has been specified."
+ ``Address`` has been specified."
Followed. A valid address will be produced even if none of those
conditions have been met. If necessary, the object is forced into
memory to ensure the address is valid.
- "An implementation should support `Address` clauses for imported
+ "An implementation should support ``Address`` clauses for imported
subprograms."
Followed.
Followed.
- "If the `Address` of an object is specified, or it is imported or exported,
+ "If the ``Address`` of an object is specified, or it is imported or exported,
then the implementation should not perform optimizations based on
assumptions of no aliases."
RM 13.3(29-35): Alignment Clauses
=================================
- "The recommended level of support for the `Alignment` attribute for
+ "The recommended level of support for the ``Alignment`` attribute for
subtypes is:
An implementation should support specified Alignments that are factors
Followed.
"An implementation need not support specified Alignments that are
- greater than the maximum `Alignment` the implementation ever returns by
+ greater than the maximum ``Alignment`` the implementation ever returns by
default."
Followed.
- "The recommended level of support for the `Alignment` attribute for
+ "The recommended level of support for the ``Alignment`` attribute for
objects is:
Same as above, for subtypes, but in addition:"
RM 13.3(42-43): Size Clauses
============================
- "The recommended level of support for the `Size` attribute of
+ "The recommended level of support for the ``Size`` attribute of
objects is:
- A `Size` clause should be supported for an object if the specified
- `Size` is at least as large as its subtype's `Size`, and
+ A ``Size`` clause should be supported for an object if the specified
+ ``Size`` is at least as large as its subtype's ``Size``, and
corresponds to a size in storage elements that is a multiple of the
- object's `Alignment` (if the `Alignment` is nonzero)."
+ object's ``Alignment`` (if the ``Alignment`` is nonzero)."
Followed.
RM 13.3(50-56): Size Clauses
============================
- "If the `Size` of a subtype is specified, and allows for efficient
+ "If the ``Size`` of a subtype is specified, and allows for efficient
independent addressability (see 9.10) on the target architecture, then
- the `Size` of the following objects of the subtype should equal the
- `Size` of the subtype:
+ the ``Size`` of the following objects of the subtype should equal the
+ ``Size`` of the subtype:
Aliased objects (including components)."
Followed. But note that this can be overridden by use of the implementation
pragma Implicit_Packing in the case of packed arrays.
- "The recommended level of support for the `Size` attribute of subtypes is:
+ "The recommended level of support for the ``Size`` attribute of subtypes is:
- The `Size` (if not specified) of a static discrete or fixed point
+ The ``Size`` (if not specified) of a static discrete or fixed point
subtype should be the number of bits needed to represent each value
belonging to the subtype using an unbiased representation, leaving space
for a sign bit only if the subtype contains negative values. If such a
subtype is a first subtype, then an implementation should support a
- specified `Size` for it that reflects this representation."
+ specified ``Size`` for it that reflects this representation."
Followed.
- "For a subtype implemented with levels of indirection, the `Size`
+ "For a subtype implemented with levels of indirection, the ``Size``
should include the size of the pointers, but not the size of what they
point at."
RM 13.3(71-73): Component Size Clauses
======================================
- "The recommended level of support for the `Component_Size`
+ "The recommended level of support for the ``Component_Size``
attribute is:
- An implementation need not support specified `Component_Sizes` that are
- less than the `Size` of the component subtype."
+ An implementation need not support specified ``Component_Sizes`` that are
+ less than the ``Size`` of the component subtype."
Followed.
An implementation need not support enumeration representation clauses
for boolean types, but should at minimum support the internal codes in
- the range `System.Min_Int .. System.Max_Int`."
+ the range ``System.Min_Int .. System.Max_Int``."
Followed.
===============================================
"The recommended level of support for
- `record_representation_clauses` is:
+ *record_representation_clause*\ s is:
An implementation should support storage places that can be extracted
with a load, mask, shift sequence of machine code, and set with a load,
Followed.
"A storage place should be supported if its size is equal to the
- `Size` of the component subtype, and it starts and ends on a
- boundary that obeys the `Alignment` of the component subtype."
+ ``Size`` of the component subtype, and it starts and ends on a
+ boundary that obeys the ``Alignment`` of the component subtype."
Followed.
"If the default bit ordering applies to the declaration of a given type,
- then for a component whose subtype's `Size` is less than the word
+ then for a component whose subtype's ``Size`` is less than the word
size, any storage place that does not cross an aligned word boundary
should be supported."
record, and its size is Address'Size. GNAT will reject an explicit component
clause for the tag field.
- "An implementation need not support a `component_clause` for a
+ "An implementation need not support a *component_clause* for a
component of an extension part if the storage place is not after the
storage places of all components of the parent type, whether or not
those storage places had been specified."
"The recommended level of support for the non-default bit ordering is:
- If `Word_Size` = `Storage_Unit`, then the implementation
+ If ``Word_Size`` = ``Storage_Unit``, then the implementation
should support the non-default bit ordering in addition to the default
bit ordering."
Followed.
-.. index:: Operations, on `Address`
+.. index:: Operations, on ``Address``
.. index:: Address, operations of
RM 13.7.1(16): Address Operations
=================================
- "Operations in `System` and its children should reflect the target
+ "Operations in ``System`` and its children should reflect the target
environment semantics as closely as is reasonable. For example, on most
machines, it makes sense for address arithmetic to 'wrap around'.
- Operations that do not make sense should raise `Program_Error`."
+ Operations that do not make sense should raise ``Program_Error``."
Followed. Address arithmetic is modular arithmetic that wraps around. No
-operation raises `Program_Error`, since all operations make sense.
+operation raises ``Program_Error``, since all operations make sense.
.. index:: Unchecked conversion
RM 13.9(14-17): Unchecked Conversion
====================================
- "The `Size` of an array object should not include its bounds; hence,
+ "The ``Size`` of an array object should not include its bounds; hence,
the bounds should not be part of the converted data."
Followed.
"The implementation should not generate unnecessary run-time checks to
- ensure that the representation of `S` is a representation of the
+ ensure that the representation of ``S`` is a representation of the
target type. It should take advantage of the permission to return by
reference when possible. Restrictions on unchecked conversions should be
avoided unless required by the target environment."
RM 13.11.2(17): Unchecked Deallocation
======================================
- "For a standard storage pool, `Free` should actually reclaim the
+ "For a standard storage pool, ``Free`` should actually reclaim the
storage."
Followed.
==========================================
"If a stream element is the same size as a storage element, then the
- normal in-memory representation should be used by `Read` and
- `Write` for scalar objects. Otherwise, `Read` and `Write`
+ normal in-memory representation should be used by ``Read`` and
+ ``Write`` for scalar objects. Otherwise, ``Read`` and ``Write``
should use the smallest number of stream elements needed to represent
all values in the base range of the scalar type."
However, such an implementation is based on direct binary
representations and is therefore target- and endianness-dependent.
To address this issue, GNAT also supplies an alternate implementation
-of the stream attributes `Read` and `Write`,
+of the stream attributes ``Read`` and ``Write``,
which uses the target-independent XDR standard representation
for scalar types.
.. index:: Stream oriented attributes
The XDR implementation is provided as an alternative body of the
-`System.Stream_Attributes` package, in the file
+``System.Stream_Attributes`` package, in the file
:file:`s-stratt-xdr.adb` in the GNAT library.
There is no :file:`s-stratt-xdr.ads` file.
In order to install the XDR implementation, do the following:
* Replace the default implementation of the
- `System.Stream_Attributes` package with the XDR implementation.
+ ``System.Stream_Attributes`` package with the XDR implementation.
For example on a Unix platform issue the commands:
.. code-block:: sh
*
Rebuild the GNAT run-time library as documented in
- the `GNAT and Libraries` section of the :title:`GNAT User's Guide`.
+ the *GNAT and Libraries* section of the :title:`GNAT User's Guide`.
RM A.1(52): Names of Predefined Numeric Types
=============================================
.. index:: Ada.Characters.Handling
-RM A.3.2(49): `Ada.Characters.Handling`
-=======================================
+RM A.3.2(49): ``Ada.Characters.Handling``
+=========================================
- "If an implementation provides a localized definition of `Character`
- or `Wide_Character`, then the effects of the subprograms in
- `Characters.Handling` should reflect the localizations.
+ "If an implementation provides a localized definition of ``Character``
+ or ``Wide_Character``, then the effects of the subprograms in
+ ``Characters.Handling`` should reflect the localizations.
See also 3.5.2."
Followed. GNAT provides no such localized definitions.
RM A.5.2(46-47): Random Number Generation
=========================================
- "Any storage associated with an object of type `Generator` should be
+ "Any storage associated with an object of type ``Generator`` should be
reclaimed on exit from the scope of the object."
Followed.
"If the generator period is sufficiently long in relation to the number
of distinct initiator values, then each possible value of
- `Initiator` passed to `Reset` should initiate a sequence of
+ ``Initiator`` passed to ``Reset`` should initiate a sequence of
random numbers that does not, in a practical sense, overlap the sequence
initiated by any other value. If this is not possible, then the mapping
between initiator values and generator states should be a rapidly
.. index:: Get_Immediate
-RM A.10.7(23): `Get_Immediate`
-==============================
+RM A.10.7(23): ``Get_Immediate``
+================================
- "The `Get_Immediate` procedures should be implemented with
+ "The ``Get_Immediate`` procedures should be implemented with
unbuffered input. For a device such as a keyboard, input should be
available if a key has already been typed, whereas for a disk
file, input should always be available except at end of file. For a file
associated with a keyboard-like device, any line-editing features of the
underlying operating system should be disabled during the execution of
- `Get_Immediate`."
+ ``Get_Immediate``."
Followed on all targets except VxWorks. For VxWorks, there is no way to
provide this functionality that does not result in the input buffer being
-flushed before the `Get_Immediate` call. A special unit
-`Interfaces.Vxworks.IO` is provided that contains routines to enable
+flushed before the ``Get_Immediate`` call. A special unit
+``Interfaces.Vxworks.IO`` is provided that contains routines to enable
this functionality.
.. index:: Export
-RM B.1(39-41): Pragma `Export`
-==============================
+RM B.1(39-41): Pragma ``Export``
+================================
- "If an implementation supports pragma `Export` to a given language,
+ "If an implementation supports pragma ``Export`` 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
+ ``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."
Followed.
"Automatic elaboration of pre-elaborated packages should be
- provided when pragma `Export` is supported."
+ provided when pragma ``Export`` is supported."
Followed when the main program is in Ada. If the main program is in a
foreign language, then
-`adainit` must be called to elaborate pre-elaborated
+``adainit`` must be called to elaborate pre-elaborated
packages.
- "For each supported convention `L` other than `Intrinsic`, an
- implementation should support `Import` and `Export` pragmas
- for objects of `L`-compatible types and for subprograms, and pragma
- `Convention` for `L`-eligible types and for subprograms,
+ "For each supported convention *L* other than ``Intrinsic``, an
+ implementation should support ``Import`` and ``Export`` pragmas
+ for objects of *L*\ -compatible types and for subprograms, and pragma
+ `Convention` for *L*\ -eligible types and for subprograms,
presuming the other language has corresponding features. Pragma
- `Convention` need not be supported for scalar types."
+ ``Convention`` need not be supported for scalar types."
Followed.
.. index:: Interfaces
-RM B.2(12-13): Package `Interfaces`
-===================================
+RM B.2(12-13): Package ``Interfaces``
+=====================================
"For each implementation-defined convention identifier, there should be a
child package of package Interfaces with the corresponding name. This
interfacing to the language (implementation) represented by the
convention. Any declarations useful for interfacing to any language on
the given hardware architecture should be provided directly in
- `Interfaces`."
+ ``Interfaces``."
Followed.
Followed.
- "An Ada `in` scalar parameter is passed as a scalar argument to a C
+ "An Ada ``in`` scalar parameter is passed as a scalar argument to a C
function."
Followed.
- "An Ada `in` parameter of an access-to-object type with designated
- type `T` is passed as a ``t*`` argument to a C function,
- where ``t`` is the C type corresponding to the Ada type `T`."
+ "An Ada ``in`` parameter of an access-to-object type with designated
+ type ``T`` is passed as a ``t*`` argument to a C function,
+ where ``t`` is the C type corresponding to the Ada type ``T``."
Followed.
- "An Ada access `T` parameter, or an Ada `out` or `in out`
- parameter of an elementary type `T`, is passed as a ``t*``
+ "An Ada access ``T`` parameter, or an Ada ``out`` or ``in out``
+ parameter of an elementary type ``T``, is passed as a ``t*``
argument to a C function, where ``t`` is the C type corresponding to
- the Ada type `T`. In the case of an elementary `out` or
- `in out` parameter, a pointer to a temporary copy is used to
+ the Ada type ``T``. In the case of an elementary ``out`` or
+ ``in out`` parameter, a pointer to a temporary copy is used to
preserve by-copy semantics."
Followed.
- "An Ada parameter of a record type `T`, of any mode, is passed as a
+ "An Ada parameter of a record type ``T``, of any mode, is passed as a
``t*`` argument to a C function, where ``t`` is the C
- structure corresponding to the Ada type `T`."
+ structure corresponding to the Ada type ``T``."
Followed. This convention may be overridden by the use of the C_Pass_By_Copy
pragma, or Convention, or by explicitly specifying the mechanism for a given
call using an extended import or export pragma.
- "An Ada parameter of an array type with component type `T`, of any
+ "An Ada parameter of an array type with component type ``T``, of any
mode, is passed as a ``t*`` argument to a C function, where
- ``t`` is the C type corresponding to the Ada type `T`."
+ ``t`` is the C type corresponding to the Ada type ``T``."
Followed.
Followed.
- "An Ada access `T` parameter is passed as a ``BY REFERENCE`` data item of
- the COBOL type corresponding to `T`."
+ "An Ada access ``T`` parameter is passed as a ``BY REFERENCE`` data item of
+ the COBOL type corresponding to ``T``."
Followed.
Followed.
- "An Ada parameter of an elementary, array, or record type `T` is
- passed as a `T` argument to a Fortran procedure, where `T` is
- the Fortran type corresponding to the Ada type `T`, and where the
+ "An Ada parameter of an elementary, array, or record type ``T`` is
+ passed as a ``T`` argument to a Fortran procedure, where ``T`` is
+ the Fortran type corresponding to the Ada type ``T``, and where the
INTENT attribute of the corresponding dummy argument matches the Ada
formal parameter mode; the Fortran implementation's parameter passing
conventions are used. For elementary types, a local copy is used if
"The interfacing pragmas (see Annex B) should support interface to
assembler; the default assembler should be associated with the
- convention identifier `Assembler`."
+ convention identifier ``Assembler``."
Followed.
RM C.3(28): Interrupt Support
=============================
- "If the `Ceiling_Locking` policy is not in effect, the
+ "If the ``Ceiling_Locking`` policy is not in effect, the
implementation should provide means for the application to specify which
interrupts are to be blocked during protected actions, if the underlying
system allows for a finer-grain control of interrupt blocking."
Followed. Compile time warnings are given when possible.
-.. index:: Package `Interrupts`
+.. index:: Package ``Interrupts``
.. index:: Interrupts
-RM C.3.2(25): Package `Interrupts`
-==================================
+RM C.3.2(25): Package ``Interrupts``
+====================================
"If implementation-defined forms of interrupt handler procedures are
supported, such as protected procedures with parameters, then for each
- such form of a handler, a type analogous to `Parameterless_Handler`
- should be specified in a child package of `Interrupts`, with the
+ such form of a handler, a type analogous to ``Parameterless_Handler``
+ should be specified in a child package of ``Interrupts``, with the
same operations as in the predefined package Interrupts."
Followed.
Followed. Executable code is generated in some cases, e.g., loops
to initialize large arrays.
-RM C.5(8): Pragma `Discard_Names`
-=================================
+RM C.5(8): Pragma ``Discard_Names``
+===================================
"If the pragma applies to an entity, then the implementation should
reduce the amount of storage used for storing names associated with that
recommended that the storage for task attributes will be pre-allocated
statically and not from the heap. This can be accomplished by either
placing restrictions on the number and the size of the task's
- attributes, or by using the pre-allocated storage for the first `N`
+ attributes, or by using the pre-allocated storage for the first ``N``
attribute objects, and the heap for the others. In the latter case,
- `N` should be documented."
+ ``N`` should be documented."
Not followed. This implementation is not targeted to such a domain.
locking policies defined by the implementation."
Followed. Two implementation-defined locking policies are defined,
-whose names (`Inheritance_Locking` and
-`Concurrent_Readers_Locking`) follow this suggestion.
+whose names (``Inheritance_Locking`` and
+``Concurrent_Readers_Locking``) follow this suggestion.
.. index:: Entry queuing policies
RM D.6(9-10): Preemptive Abort
==============================
- "Even though the `abort_statement` is included in the list of
+ "Even though the *abort_statement* is included in the list of
potentially blocking operations (see 9.5.1), it is recommended that this
statement be implemented in a way that never requires the task executing
- the `abort_statement` to block."
+ the *abort_statement* to block."
Followed.
GNAT currently takes advantage of these restrictions by providing an optimized
run time when the Ravenscar profile and the GNAT restricted run time set
-of restrictions are specified. See pragma `Profile (Ravenscar)` and
-pragma `Profile (Restricted)` for more details.
+of restrictions are specified. See pragma ``Profile (Ravenscar)`` and
+pragma ``Profile (Restricted)`` for more details.
.. index:: Time, monotonic
=============================
"When appropriate, implementations should provide configuration
- mechanisms to change the value of `Tick`."
+ mechanisms to change the value of ``Tick``."
Such configuration mechanisms are not appropriate to this implementation
and are thus not supported.
- "It is recommended that `Calendar.Clock` and `Real_Time.Clock`
+ "It is recommended that ``Calendar.Clock`` and ``Real_Time.Clock``
be implemented as transformations of the same time base."
Followed.
"It is recommended that the best time base which exists in
the underlying system be available to the application through
- `Clock`. `Best` may mean highest accuracy or largest range."
+ ``Clock``. `Best` may mean highest accuracy or largest range."
Followed.
Followed by GLADE, a separately supplied PCS that can be used with
GNAT.
- "The `Write` operation on a stream of type `Params_Stream_Type`
- should raise `Storage_Error` if it runs out of space trying to
- write the `Item` into the stream."
+ "The ``Write`` operation on a stream of type ``Params_Stream_Type``
+ should raise ``Storage_Error`` if it runs out of space trying to
+ write the ``Item`` into the stream."
Followed by GLADE, a separately supplied PCS that can be used with
GNAT.
"If COBOL (respectively, C) is widely supported in the target
environment, implementations supporting the Information Systems Annex
- should provide the child package `Interfaces.COBOL` (respectively,
- `Interfaces.C`) specified in Annex B and should support a
- `convention_identifier` of COBOL (respectively, C) in the interfacing
+ should provide the child package ``Interfaces.COBOL`` (respectively,
+ ``Interfaces.C``) specified in Annex B and should support a
+ ``convention_identifier`` of COBOL (respectively, C) in the interfacing
pragmas (see Annex B), thus allowing Ada programs to interface with
programs written in that language."
================================
"Packed decimal should be used as the internal representation for objects
- of subtype `S` when `S`'Machine_Radix = 10."
+ of subtype ``S`` when ``S``'Machine_Radix = 10."
-Not followed. GNAT ignores `S`'Machine_Radix and always uses binary
+Not followed. GNAT ignores ``S``'Machine_Radix and always uses binary
representations.
.. index:: Numerics
"If Fortran (respectively, C) is widely supported in the target
environment, implementations supporting the Numerics Annex
- should provide the child package `Interfaces.Fortran` (respectively,
- `Interfaces.C`) specified in Annex B and should support a
- `convention_identifier` of Fortran (respectively, C) in the interfacing
+ should provide the child package ``Interfaces.Fortran`` (respectively,
+ ``Interfaces.C``) specified in Annex B and should support a
+ ``convention_identifier`` of Fortran (respectively, C) in the interfacing
pragmas (see Annex B), thus allowing Ada programs to interface with
programs written in that language."
complex operand and a real operand is that the imaginary operand remains
unchanged, an implementation should not perform this operation by first
promoting the real operand to complex type and then performing a full
- complex addition. In implementations in which the `Signed_Zeros`
- attribute of the component type is `True` (and which therefore
+ complex addition. In implementations in which the ``Signed_Zeros``
+ attribute of the component type is ``True`` (and which therefore
conform to IEC 559:1989 in regard to the handling of the sign of zero in
predefined arithmetic operations), the latter technique will not
generate the required result when the imaginary component of the complex
Not followed.
- "Implementations in which `Real'Signed_Zeros` is `True` should
+ "Implementations in which ``Real'Signed_Zeros`` is ``True`` should
attempt to provide a rational treatment of the signs of zero results and
- result components. As one example, the result of the `Argument`
+ result components. As one example, the result of the ``Argument``
function should have the sign of the imaginary component of the
- parameter `X` when the point represented by that parameter lies on
+ parameter ``X`` when the point represented by that parameter lies on
the positive real axis; as another, the sign of the imaginary component
- of the `Compose_From_Polar` function should be the same as
- (respectively, the opposite of) that of the `Argument` parameter when that
- parameter has a value of zero and the `Modulus` parameter has a
+ of the ``Compose_From_Polar`` function should be the same as
+ (respectively, the opposite of) that of the ``Argument`` parameter when that
+ parameter has a value of zero and the ``Modulus`` parameter has a
nonnegative (respectively, negative) value."
Followed.
RM G.1.2(49): Complex Elementary Functions
==========================================
- "Implementations in which `Complex_Types.Real'Signed_Zeros` is
- `True` should attempt to provide a rational treatment of the signs
+ "Implementations in which ``Complex_Types.Real'Signed_Zeros`` is
+ ``True`` should attempt to provide a rational treatment of the signs
of zero results and result components. For example, many of the complex
elementary functions have components that are odd functions of one of
the parameter components; in these cases, the result component should
===================================
"The versions of the forward trigonometric functions without a
- `Cycle` parameter should not be implemented by calling the
- corresponding version with a `Cycle` parameter of
- `2.0*Numerics.Pi`, since this will not provide the required
+ ``Cycle`` parameter should not be implemented by calling the
+ corresponding version with a ``Cycle`` parameter of
+ ``2.0*Numerics.Pi``, since this will not provide the required
accuracy in some portions of the domain. For the same reason, the
- version of `Log` without a `Base` parameter should not be
- implemented by calling the corresponding version with a `Base`
- parameter of `Numerics.e`."
+ version of ``Log`` without a ``Base`` parameter should not be
+ implemented by calling the corresponding version with a ``Base``
+ parameter of ``Numerics.e``."
Followed.
RM G.2.6(15): Complex Arithmetic Accuracy
=========================================
- "The version of the `Compose_From_Polar` function without a
- `Cycle` parameter should not be implemented by calling the
- corresponding version with a `Cycle` parameter of
- `2.0*Numerics.Pi`, since this will not provide the required
+ "The version of the ``Compose_From_Polar`` function without a
+ ``Cycle`` parameter should not be implemented by calling the
+ corresponding version with a ``Cycle`` parameter of
+ ``2.0*Numerics.Pi``, since this will not provide the required
accuracy in some portions of the domain."
Followed.
RM H.6(15/2): Pragma Partition_Elaboration_Policy
=================================================
- "If the partition elaboration policy is `Sequential` and the
+ "If the partition elaboration policy is ``Sequential`` and the
Environment task becomes permanently blocked during elaboration then the
partition is deadlocked and it is recommended that the partition be
immediately terminated."
*Annotate => ID*
- Equivalent to `pragma Annotate (ID, Entity => Name);`
+ Equivalent to ``pragma Annotate (ID, Entity => Name);``
*Annotate => (ID)*
- Equivalent to `pragma Annotate (ID, Entity => Name);`
+ Equivalent to ``pragma Annotate (ID, Entity => Name);``
*Annotate => (ID ,ID {, ARG})*
- Equivalent to `pragma Annotate (ID, ID {, ARG}, Entity => Name);`
+ Equivalent to ``pragma Annotate (ID, ID {, ARG}, Entity => Name);``
Aspect Async_Readers
====================
================
.. index:: Dimension
-The `Dimension` aspect is used to specify the dimensions of a given
+The ``Dimension`` aspect is used to specify the dimensions of a given
subtype of a dimensioned numeric type. The aspect also specifies a symbol
used when doing formatted output of dimensioned quantities. The syntax is::
This aspect can only be applied to a subtype whose parent type has
-a `Dimension_System` aspect. The aspect must specify values for
+a ``Dimension_System`` aspect. The aspect must specify values for
all dimensions of the system. The rational values are the powers of the
corresponding dimensions that are used by the compiler to verify that
physical (numeric) computations are dimensionally consistent. For example,
the computation of a force must result in dimensions (L => 1, M => 1, T => -2).
For further examples of the usage
-of this aspect, see package `System.Dim.Mks`.
+of this aspect, see package ``System.Dim.Mks``.
Note that when the dimensioned type is an integer type, then any
dimension value must be an integer literal.
=======================
.. index:: Dimension_System
-The `Dimension_System` aspect is used to define a system of
+The ``Dimension_System`` aspect is used to define a system of
dimensions that will be used in subsequent subtype declarations with
-`Dimension` aspects that reference this system. The syntax is::
+``Dimension`` aspects that reference this system. The syntax is::
with Dimension_System => (DIMENSION {, DIMENSION});
This aspect is applied to a type, which must be a numeric derived type
(typically a floating-point type), that
-will represent values within the dimension system. Each `DIMENSION`
+will represent values within the dimension system. Each ``DIMENSION``
corresponds to one particular dimension. A maximum of 7 dimensions may
-be specified. `Unit_Name` is the name of the dimension (for example
-`Meter`). `Unit_Symbol` is the shorthand used for quantities
-of this dimension (for example `m` for `Meter`).
-`Dim_Symbol` gives
+be specified. ``Unit_Name`` is the name of the dimension (for example
+``Meter``). ``Unit_Symbol`` is the shorthand used for quantities
+of this dimension (for example ``m`` for ``Meter``).
+``Dim_Symbol`` gives
the identification within the dimension system (typically this is a
-single letter, e.g. `L` standing for length for unit name `Meter`).
-The `Unit_Symbol` is used in formatted output of dimensioned quantities.
-The `Dim_Symbol` is used in error messages when numeric operations have
+single letter, e.g. ``L`` standing for length for unit name ``Meter``).
+The ``Unit_Symbol`` is used in formatted output of dimensioned quantities.
+The ``Dim_Symbol`` is used in error messages when numeric operations have
inconsistent dimensions.
GNAT provides the standard definition of the International MKS system in
-the run-time package `System.Dim.Mks`. You can easily define
+the run-time package ``System.Dim.Mks``. You can easily define
similar packages for cgs units or British units, and define conversion factors
between values in different systems. The MKS system is characterized by the
following aspect:
(Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
-Note that in the above type definition, we use the `at` symbol (``@``) to
+Note that in the above type definition, we use the ``at`` symbol (``@``) to
represent a theta character (avoiding the use of extended Latin-1
characters in this context).
=========================
.. index:: Disable_Controlled
-The aspect `Disable_Controlled` is defined for controlled record types. If
-active, this aspect causes suppression of all related calls to `Initialize`,
-`Adjust`, and `Finalize`. The intended use is for conditional compilation,
+The aspect ``Disable_Controlled`` is defined for controlled record types. If
+active, this aspect causes suppression of all related calls to ``Initialize``,
+``Adjust``, and ``Finalize``. The intended use is for conditional compilation,
where for example you might want a record to be controlled or not depending on
whether some run-time check is enabled or suppressed.
.. index:: Invariant
This aspect is equivalent to :ref:`pragma Invariant<Pragma-Invariant>`. It is a
-synonym for the language defined aspect `Type_Invariant` except
-that it is separately controllable using pragma `Assertion_Policy`.
+synonym for the language defined aspect ``Type_Invariant`` except
+that it is separately controllable using pragma ``Assertion_Policy``.
Aspect Invariant'Class
======================
.. index:: Invariant'Class
This aspect is equivalent to :ref:`pragma Type_Invariant_Class<Pragma-Type_Invariant_Class>`. It is a
-synonym for the language defined aspect `Type_Invariant'Class` except
-that it is separately controllable using pragma `Assertion_Policy`.
+synonym for the language defined aspect ``Type_Invariant'Class`` except
+that it is separately controllable using pragma ``Assertion_Policy``.
Aspect Iterable
===============
This aspect provides a light-weight mechanism for loops and quantified
expressions over container types, without the overhead imposed by the tampering
checks of standard Ada 2012 iterators. The value of the aspect is an aggregate
-with four named components: `First`, `Next`, `Has_Element`, and `Element` (the
+with four named components: ``First``, ``Next``, ``Has_Element``, and ``Element`` (the
last one being optional). When only 3 components are specified, only the
-`for .. in` form of iteration over cursors is available. When all 4 components
-are specified, both this form and the `for .. of` form of iteration over
+``for .. in`` form of iteration over cursors is available. When all 4 components
+are specified, both this form and the ``for .. of`` form of iteration over
elements are available. The following is a typical example of use:
.. code-block:: ada
Has_Element => Cursor_Has_Element,
[Element => Get_Element]);
-* The value denoted by `First` must denote a primitive operation of the
- container type that returns a `Cursor`, which must a be a type declared in
+* The value denoted by ``First`` must denote a primitive operation of the
+ container type that returns a ``Cursor``, which must a be a type declared in
the container package or visible from it. For example:
.. code-block:: ada
function First_Cursor (Cont : Container) return Cursor;
-* The value of `Next` is a primitive operation of the container type that takes
+* The value of ``Next`` is a primitive operation of the container type that takes
both a container and a cursor and yields a cursor. For example:
.. code-block:: ada
function Advance (Cont : Container; Position : Cursor) return Cursor;
-* The value of `Has_Element` is a primitive operation of the container type
+* The value of ``Has_Element`` is a primitive operation of the container type
that takes both a container and a cursor and yields a boolean. For example:
.. code-block:: ada
function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean;
-* The value of `Element` is a primitive operation of the container type that
- takes both a container and a cursor and yields an `Element_Type`, which must
+* The value of ``Element`` is a primitive operation of the container type that
+ takes both a container and a cursor and yields an ``Element_Type``, which must
be a type declared in the container package or visible from it. For example:
.. code-block:: ada
This aspect is equivalent to :ref:`pragma No_Elaboration_Code_All<Pragma-No_Elaboration_Code_All>`
for a program unit.
+Aspect No_Inline
+================
+.. index:: No_Inline
+
+This boolean aspect is equivalent to :ref:`pragma No_Inline<Pragma-No_Inline>`.
+
Aspect No_Tagged_Streams
========================
.. index:: No_Tagged_Streams
.. index:: Predicate
This aspect is equivalent to :ref:`pragma Predicate<Pragma-Predicate>`. It is thus
-similar to the language defined aspects `Dynamic_Predicate`
-and `Static_Predicate` except that whether the resulting
+similar to the language defined aspects ``Dynamic_Predicate``
+and ``Static_Predicate`` except that whether the resulting
predicate is static or dynamic is controlled by the form of the
expression. It is also separately controllable using pragma
-`Assertion_Policy`.
+``Assertion_Policy``.
Aspect Pure_Function
====================
.. index:: Shared
This boolean aspect is equivalent to :ref:`pragma Shared<Pragma-Shared>`
-and is thus a synonym for aspect `Atomic`.
+and is thus a synonym for aspect ``Atomic``.
Aspect Simple_Storage_Pool
==========================
.. index:: Warnings
This aspect is equivalent to the two argument form of :ref:`pragma Warnings<Pragma_Warnings>`,
-where the first argument is `ON` or `OFF` and the second argument
+where the first argument is ``ON`` or ``OFF`` and the second argument
is the entity.
======================
.. index:: Abort_Signal
-`Standard'Abort_Signal` (`Standard` is the only allowed
+``Standard'Abort_Signal`` (``Standard`` is the only allowed
prefix) provides the entity for the special exception used to signal
task abort or asynchronous transfer of control. Normally this attribute
should only be used in the tasking runtime (it is highly peculiar, and
Attribute Address_Size
======================
-.. index:: Size of `Address`
+.. index:: Size of ``Address``
.. index:: Address_Size
-`Standard'Address_Size` (`Standard` is the only allowed
+``Standard'Address_Size`` (``Standard`` is the only allowed
prefix) is a static constant giving the number of bits in an
-`Address`. It is the same value as System.Address'Size,
+``Address``. It is the same value as System.Address'Size,
but has the advantage of being static, while a direct
reference to System.Address'Size is nonstatic because Address
is a private type.
===================
.. index:: Asm_Input
-The `Asm_Input` attribute denotes a function that takes two
+The ``Asm_Input`` attribute denotes a function that takes two
parameters. The first is a string, the second is an expression of the
type designated by the prefix. The first (string) argument is required
to be a static expression, and is the constraint for the parameter,
====================
.. index:: Asm_Output
-The `Asm_Output` attribute denotes a function that takes two
+The ``Asm_Output`` attribute denotes a function that takes two
parameters. The first is a string, the second is the name of a variable
of the type designated by the attribute prefix. The first (string)
argument is required to be a static expression and designates the
result. The possible values for constraint are the same as those used in
the RTL, and are dependent on the configuration file used to build the
GCC back end. If there are no output operands, then this argument may
-either be omitted, or explicitly given as `No_Output_Operands`.
+either be omitted, or explicitly given as ``No_Output_Operands``.
:ref:`Machine_Code_Insertions`
Attribute Atomic_Always_Lock_Free
=================================
.. index:: Atomic_Always_Lock_Free
-The prefix of the `Atomic_Always_Lock_Free` attribute is a type.
+The prefix of the ``Atomic_Always_Lock_Free`` attribute is a type.
The result is a Boolean value which is True if the type has discriminants,
and False otherwise. The result indicate whether atomic operations are
supported by the target for the given type.
=============
.. index:: Bit
-``obj'Bit``, where `obj` is any object, yields the bit
+``obj'Bit``, where ``obj`` is any object, yields the bit
offset within the storage unit (byte) that contains the first bit of
storage allocated for the object. The value of this attribute is of the
-type `Universal_Integer`, and is always a non-negative number not
-exceeding the value of `System.Storage_Unit`.
+type *universal_integer*, and is always a non-negative number not
+exceeding the value of ``System.Storage_Unit``.
For an object that is a variable or a constant allocated in a register,
the value is zero. (The use of this attribute does not force the
matching actual parameter.
For an access object the value is zero. Note that
-``obj.all'Bit`` is subject to an `Access_Check` for the
+``obj.all'Bit`` is subject to an ``Access_Check`` for the
designated object. Similarly for a record component
``X.C'Bit`` is subject to a discriminant check and
``X(I).Bit`` and ``X(I1..I2)'Bit``
are subject to index checks.
This attribute is designed to be compatible with the DEC Ada 83 definition
-and implementation of the `Bit` attribute.
+and implementation of the ``Bit`` attribute.
Attribute Bit_Position
======================
.. index:: Bit_Position
-``R.C'Bit_Position``, where `R` is a record object and `C` is one
+``R.C'Bit_Position``, where ``R`` is a record object and ``C`` is one
of the fields of the record type, yields the bit
offset within the record contains the first bit of
storage allocated for the object. The value of this attribute is of the
-type `Universal_Integer`. The value depends only on the field
-`C` and is independent of the alignment of
-the containing record `R`.
+type *universal_integer*. The value depends only on the field
+``C`` and is independent of the alignment of
+the containing record ``R``.
Attribute Code_Address
======================
.. index:: Address of subprogram code
-The `'Address`
+The ``'Address``
attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
intended effect seems to be to provide
an address value which can be used to call the subprogram by means of
pragma Import (Ada, L);
-A call to `L` is then expected to result in a call to `K`.
+A call to ``L`` is then expected to result in a call to ``K``.
In Ada 83, where there were no access-to-subprogram values, this was
a common work-around for getting the effect of an indirect call.
-GNAT implements the above use of `Address` and the technique
+GNAT implements the above use of ``Address`` and the technique
illustrated by the example code works correctly.
However, for some purposes, it is useful to have the address of the start
of the generated code for the subprogram. On some architectures, this is
-not necessarily the same as the `Address` value described above.
-For example, the `Address` value may reference a subprogram
+not necessarily the same as the ``Address`` value described above.
+For example, the ``Address`` value may reference a subprogram
descriptor rather than the subprogram itself.
-The `'Code_Address` attribute, which can only be applied to
+The ``'Code_Address`` attribute, which can only be applied to
subprogram entities, always returns the address of the start of the
generated code of the specified subprogram, which may or may not be
-the same value as is returned by the corresponding `'Address`
+the same value as is returned by the corresponding ``'Address``
attribute.
Attribute Compiler_Version
==========================
.. index:: Compiler_Version
-`Standard'Compiler_Version` (`Standard` is the only allowed
+``Standard'Compiler_Version`` (``Standard`` is the only allowed
prefix) yields a static string identifying the version of the compiler
being used to compile the unit containing the attribute reference.
=====================
.. index:: Constrained
-In addition to the usage of this attribute in the Ada RM, `GNAT`
-also permits the use of the `'Constrained` attribute
+In addition to the usage of this attribute in the Ada RM, GNAT
+also permits the use of the ``'Constrained`` attribute
in a generic template
for any type, including types without discriminants. The value of this
attribute in the generic instance when applied to a scalar type or a
-record type without discriminants is always `True`. This usage is
+record type without discriminants is always ``True``. This usage is
compatible with older Ada compilers, including notably DEC Ada.
.. index:: Default_Bit_Order
-`Standard'Default_Bit_Order` (`Standard` is the only
-permissible prefix), provides the value `System.Default_Bit_Order`
-as a `Pos` value (0 for `High_Order_First`, 1 for
-`Low_Order_First`). This is used to construct the definition of
-`Default_Bit_Order` in package `System`.
+``Standard'Default_Bit_Order`` (``Standard`` is the only
+permissible prefix), provides the value ``System.Default_Bit_Order``
+as a ``Pos`` value (0 for ``High_Order_First``, 1 for
+``Low_Order_First``). This is used to construct the definition of
+``Default_Bit_Order`` in package ``System``.
Attribute Default_Scalar_Storage_Order
======================================
.. index:: Default_Scalar_Storage_Order
-`Standard'Default_Scalar_Storage_Order` (`Standard` is the only
+``Standard'Default_Scalar_Storage_Order`` (``Standard`` is the only
permissible prefix), provides the current value of the default scalar storage
-order (as specified using pragma `Default_Scalar_Storage_Order`, or
-equal to `Default_Bit_Order` if unspecified) as a
-`System.Bit_Order` value. This is a static attribute.
+order (as specified using pragma ``Default_Scalar_Storage_Order``, or
+equal to ``Default_Bit_Order`` if unspecified) as a
+``System.Bit_Order`` value. This is a static attribute.
Attribute Deref
===============
.. index:: Deref
-The attribute `typ'Deref(expr)` where `expr` is of type `System.Address` yields
-the variable of type `typ` that is located at the given address. It is similar
-to `(totyp (expr).all)`, where `totyp` is an unchecked conversion from address to
+The attribute ``typ'Deref(expr)`` where ``expr`` is of type ``System.Address`` yields
+the variable of type ``typ`` that is located at the given address. It is similar
+to ``(totyp (expr).all)``, where ``totyp`` is an unchecked conversion from address to
a named access-to-`typ` type, except that it yields a variable, so it can be
used on the left side of an assignment.
.. index:: Descriptor_Size
-Nonstatic attribute `Descriptor_Size` returns the size in bits of the
+Nonstatic attribute ``Descriptor_Size`` returns the size in bits of the
descriptor allocated for a type. The result is non-zero only for unconstrained
array types and the returned value is of type universal integer. In GNAT, an
array descriptor contains bounds information and is located immediately before
The attribute takes into account any additional padding due to type alignment.
In the example above, the descriptor contains two values of type
-`Positive` representing the low and high bound. Since `Positive` has
-a size of 31 bits and an alignment of 4, the descriptor size is `2 * Positive'Size + 2` or 64 bits.
+``Positive`` representing the low and high bound. Since ``Positive`` has
+a size of 31 bits and an alignment of 4, the descriptor size is ``2 * Positive'Size + 2`` or 64 bits.
Attribute Elaborated
====================
.. index:: Elaborated
-The prefix of the `'Elaborated` attribute must be a unit name. The
+The prefix of the ``'Elaborated`` attribute must be a unit name. The
value is a Boolean which indicates whether or not the given unit has been
elaborated. This attribute is primarily intended for internal use by the
generated code for dynamic elaboration checking, but it can also be used
.. index:: Emax
-The `Emax` attribute is provided for compatibility with Ada 83. See
+The ``Emax`` attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
=================
.. index:: Enabled
-The `Enabled` attribute allows an application program to check at compile
+The ``Enabled`` attribute allows an application program to check at compile
time to see if the designated check is currently enabled. The prefix is a
simple identifier, referencing any predefined check name (other than
-`All_Checks`) or a check name introduced by pragma Check_Name. If
+``All_Checks``) or a check name introduced by pragma Check_Name. If
no argument is given for the attribute, the check is for the general state
of the check, if an argument is given, then it is an entity name, and the
-check indicates whether an `Suppress` or `Unsuppress` has been
+check indicates whether an ``Suppress`` or ``Unsuppress`` has been
given naming the entity (if not, then the argument is ignored).
Note that instantiations inherit the check status at the point of the
instantiation, so a useful idiom is to have a library package that
-introduces a check name with `pragma Check_Name`, and then contains
-generic packages or subprograms which use the `Enabled` attribute
+introduces a check name with ``pragma Check_Name``, and then contains
+generic packages or subprograms which use the ``Enabled`` attribute
to see if the check is enabled. A user of this package can then issue
-a `pragma Suppress` or `pragma Unsuppress` before instantiating
+a ``pragma Suppress`` or ``pragma Unsuppress`` before instantiating
the package or subprogram, controlling whether the check will be present.
Attribute Enum_Rep
.. index:: Enum_Rep
-For every enumeration subtype `S`, ``S'Enum_Rep`` denotes a
+For every enumeration subtype ``S``, ``S'Enum_Rep`` denotes a
function with the following spec:
.. code-block:: ada
function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>;
-It is also allowable to apply `Enum_Rep` directly to an object of an
+It is also allowable to apply ``Enum_Rep`` directly to an object of an
enumeration type or to a non-overloaded enumeration
literal. In this case ``S'Enum_Rep`` is equivalent to
-``typ'Enum_Rep(S)`` where `typ` is the type of the
+``typ'Enum_Rep(S)`` where ``typ`` is the type of the
enumeration literal or object.
The function returns the representation value for the given enumeration
-value. This will be equal to value of the `Pos` attribute in the
+value. This will be equal to value of the ``Pos`` attribute in the
absence of an enumeration representation clause. This is a static
attribute (i.e.,:the result is static if the argument is static).
``S'Enum_Rep`` can also be used with integer types and objects,
in which case it simply returns the integer value. The reason for this
-is to allow it to be used for `(<>)` discrete formal arguments in
+is to allow it to be used for ``(<>)`` discrete formal arguments in
a generic unit that can be instantiated with either enumeration types
-or integer types. Note that if `Enum_Rep` is used on a modular
+or integer types. Note that if ``Enum_Rep`` is used on a modular
type whose upper bound exceeds the upper bound of the largest signed
integer type, and the argument is a variable, so that the universal
-integer calculation is done at run time, then the call to `Enum_Rep`
-may raise `Constraint_Error`.
+integer calculation is done at run time, then the call to ``Enum_Rep``
+may raise ``Constraint_Error``.
Attribute Enum_Val
==================
.. index:: Enum_Val
-For every enumeration subtype `S`, ``S'Enum_Val`` denotes a
+For every enumeration subtype ``S``, ``S'Enum_Val`` denotes a
function with the following spec:
.. code-block:: ada
The function returns the enumeration value whose representation matches the
argument, or raises Constraint_Error if no enumeration literal of the type
has the matching value.
-This will be equal to value of the `Val` attribute in the
+This will be equal to value of the ``Val`` attribute in the
absence of an enumeration representation clause. This is a static
attribute (i.e., the result is static if the argument is static).
.. index:: Epsilon
-The `Epsilon` attribute is provided for compatibility with Ada 83. See
+The ``Epsilon`` attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
===================
.. index:: Fast_Math
-`Standard'Fast_Math` (`Standard` is the only allowed
+``Standard'Fast_Math`` (``Standard`` is the only allowed
prefix) yields a static Boolean value that is True if pragma
-`Fast_Math` is active, and False otherwise.
+``Fast_Math`` is active, and False otherwise.
Attribute Finalization_Size
===========================
.. index:: Finalization_Size
-The prefix of attribute `Finalization_Size` must be an object or
+The prefix of attribute ``Finalization_Size`` must be an object or
a non-class-wide type. This attribute returns the size of any hidden data
reserved by the compiler to handle finalization-related actions. The type of
-the attribute is `universal_integer`.
+the attribute is *universal_integer*.
-`Finalization_Size` yields a value of zero for a type with no controlled
+``Finalization_Size`` yields a value of zero for a type with no controlled
parts, an object whose type has no controlled parts, or an object of a
class-wide type whose tag denotes a type with no controlled parts.
=====================
.. index:: Fixed_Value
-For every fixed-point type `S`, ``S'Fixed_Value`` denotes a
+For every fixed-point type ``S``, ``S'Fixed_Value`` denotes a
function with the following specification:
.. code-block:: ada
function S'Fixed_Value (Arg : <Universal_Integer>) return S;
-The value returned is the fixed-point value `V` such that::
+The value returned is the fixed-point value ``V`` such that::
V = Arg * S'Small
The effect is thus similar to first converting the argument to the
-integer type used to represent `S`, and then doing an unchecked
+integer type used to represent ``S``, and then doing an unchecked
conversion to the fixed-point type. The difference is
that there are full range checks, to ensure that the result is in range.
This attribute is primarily intended for use in implementation of the
.. index:: Has_Access_Values
-The prefix of the `Has_Access_Values` attribute is a type. The result
+The prefix of the ``Has_Access_Values`` attribute is a type. The result
is a Boolean value which is True if the is an access type, or is a composite
type with a component (at any nesting depth) that is an access type, and is
False otherwise.
.. index:: Has_Discriminants
-The prefix of the `Has_Discriminants` attribute is a type. The result
+The prefix of the ``Has_Discriminants`` attribute is a type. The result
is a Boolean value which is True if the type has discriminants, and False
otherwise. The intended use of this attribute is in conjunction with generic
definitions. If the attribute is applied to a generic private type, it
=============
.. index:: Img
-The `Img` attribute differs from `Image` in that it is applied
+The ``Img`` attribute differs from ``Image`` in that it is applied
directly to an object, and yields the same result as
-`Image` for the subtype of the object. This is convenient for
+``Image`` for the subtype of the object. This is convenient for
debugging:
.. code-block:: ada
Put_Line ("X = " & T'Image (X));
-where `T` is the (sub)type of the object `X`.
+where ``T`` is the (sub)type of the object ``X``.
-Note that technically, in analogy to `Image`,
-`X'Img` returns a parameterless function
+Note that technically, in analogy to ``Image``,
+``X'Img`` returns a parameterless function
that returns the appropriate string when called. This means that
-`X'Img` can be renamed as a function-returning-string, or used
+``X'Img`` can be renamed as a function-returning-string, or used
in an instantiation as a function parameter.
Attribute Integer_Value
=======================
.. index:: Integer_Value
-For every integer type `S`, ``S'Integer_Value`` denotes a
+For every integer type ``S``, ``S'Integer_Value`` denotes a
function with the following spec:
.. code-block:: ada
function S'Integer_Value (Arg : <Universal_Fixed>) return S;
-The value returned is the integer value `V`, such that::
+The value returned is the integer value ``V``, such that::
Arg = V * T'Small
-where `T` is the type of `Arg`.
+where ``T`` is the type of ``Arg``.
The effect is thus similar to first doing an unchecked conversion from
the fixed-point type to its corresponding implementation type, and then
converting the result to the target integer type. The difference is
.. index:: Large
-The `Large` attribute is provided for compatibility with Ada 83. See
+The ``Large`` attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
=======================
.. index:: Library_Level
-`P'Library_Level`, where P is an entity name,
+``P'Library_Level``, where P is an entity name,
returns a Boolean value which is True if the entity is declared
at the library level, and False otherwise. Note that within a
generic instantition, the name of the generic unit denotes the
===================
.. index:: Lock_Free
-`P'Lock_Free`, where P is a protected object, returns True if a
-pragma `Lock_Free` applies to P.
+``P'Lock_Free``, where P is a protected object, returns True if a
+pragma ``Lock_Free`` applies to P.
Attribute Loop_Entry
====================
X'Loop_Entry [(loop_name)]
-The `Loop_Entry` attribute is used to refer to the value that an
+The ``Loop_Entry`` attribute is used to refer to the value that an
expression had upon entry to a given loop in much the same way that the
-`Old` attribute in a subprogram postcondition can be used to refer
+``Old`` attribute in a subprogram postcondition can be used to refer
to the value an expression had upon entry to the subprogram. The
relevant loop is either identified by the given loop name, or it is the
innermost enclosing loop when no loop name is given.
-A `Loop_Entry` attribute can only occur within a
-`Loop_Variant` or `Loop_Invariant` pragma. A common use of
-`Loop_Entry` is to compare the current value of objects with their
-initial value at loop entry, in a `Loop_Invariant` pragma.
+A ``Loop_Entry`` attribute can only occur within a
+``Loop_Variant`` or ``Loop_Invariant`` pragma. A common use of
+``Loop_Entry`` is to compare the current value of objects with their
+initial value at loop entry, in a ``Loop_Invariant`` pragma.
-The effect of using `X'Loop_Entry` is the same as declaring
-a constant initialized with the initial value of `X` at loop
+The effect of using ``X'Loop_Entry`` is the same as declaring
+a constant initialized with the initial value of ``X`` at loop
entry. This copy is not performed if the loop is not entered, or if the
corresponding pragmas are ignored or disabled.
======================
.. index:: Machine_Size
-This attribute is identical to the `Object_Size` attribute. It is
+This attribute is identical to the ``Object_Size`` attribute. It is
provided for compatibility with the DEC Ada 83 attribute of this name.
Attribute Mantissa
.. index:: Mantissa
-The `Mantissa` attribute is provided for compatibility with Ada 83. See
+The ``Mantissa`` attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
.. index:: Maximum_Alignment
-`Standard'Maximum_Alignment` (`Standard` is the only
+``Standard'Maximum_Alignment`` (``Standard`` is the only
permissible prefix) provides the maximum useful alignment value for the
target. This is a static value that can be used to specify the alignment
for an object, guaranteeing that it is properly aligned in all
.. index:: Mechanism_Code
-``function'Mechanism_Code`` yields an integer code for the
-mechanism used for the result of function, and
-``subprogram'Mechanism_Code (n)`` yields the mechanism
-used for formal parameter number `n` (a static integer value with 1
-meaning the first parameter) of `subprogram`. The code returned is:
+``func'Mechanism_Code`` yields an integer code for the
+mechanism used for the result of function ``func``, and
+``subprog'Mechanism_Code (n)`` yields the mechanism
+used for formal parameter number *n* (a static integer value, with 1
+meaning the first parameter) of subprogram ``subprog``. The code returned is:
.. index:: Null_Parameter
A reference ``T'Null_Parameter`` denotes an imaginary object of
-type or subtype `T` allocated at machine address zero. The attribute
+type or subtype ``T`` allocated at machine address zero. The attribute
is allowed only as the default expression of a formal parameter, or as
an actual expression of a subprogram call. In either case, the
subprogram must be imported.
This capability is needed to specify that a zero address should be
passed for a record or other composite object passed by reference.
-There is no way of indicating this without the `Null_Parameter`
+There is no way of indicating this without the ``Null_Parameter``
attribute.
.. _Attribute-Object_Size:
The size of an object is not necessarily the same as the size of the type
of an object. This is because by default object sizes are increased to be
a multiple of the alignment of the object. For example,
-`Natural'Size` is
-31, but by default objects of type `Natural` will have a size of 32 bits.
+``Natural'Size`` is
+31, but by default objects of type ``Natural`` will have a size of 32 bits.
Similarly, a record containing an integer and a character:
.. code-block:: ada
end record;
-will have a size of 40 (that is `Rec'Size` will be 40). The
+will have a size of 40 (that is ``Rec'Size`` will be 40). The
alignment will be 4, because of the
integer field, and so the default size of record objects for this type
will be 64 (8 bytes).
A consequence of this capability is that different object sizes can be
given to subtypes that would otherwise be considered in Ada to be
statically matching. But it makes no sense to consider such subtypes
-as statically matching. Consequently, in `GNAT` we add a rule
+as statically matching. Consequently, GNAT adds a rule
to the static matching rules that requires object sizes to match.
Consider this example:
In the absence of lines 5 and 6,
-types `R1` and `R2` statically match and
+types ``R1`` and ``R2`` statically match and
hence the conversion on line 12 is legal. But since lines 5 and 6
-cause the object sizes to differ, `GNAT` considers that types
-`R1` and `R2` are not statically matching, and line 12
+cause the object sizes to differ, GNAT considers that types
+``R1`` and ``R2`` are not statically matching, and line 12
generates the diagnostic shown above.
Similar additional checks are performed in other contexts requiring
=============
.. index:: Old
-In addition to the usage of `Old` defined in the Ada 2012 RM (usage
-within `Post` aspect), GNAT also permits the use of this attribute
-in implementation defined pragmas `Postcondition`,
-`Contract_Cases` and `Test_Case`. Also usages of
-`Old` which would be illegal according to the Ada 2012 RM
+In addition to the usage of ``Old`` defined in the Ada 2012 RM (usage
+within ``Post`` aspect), GNAT also permits the use of this attribute
+in implementation defined pragmas ``Postcondition``,
+``Contract_Cases`` and ``Test_Case``. Also usages of
+``Old`` which would be illegal according to the Ada 2012 RM
definition are allowed under control of
-implementation defined pragma `Unevaluated_Use_Of_Old`.
+implementation defined pragma ``Unevaluated_Use_Of_Old``.
Attribute Passed_By_Reference
=============================
.. index:: Passed_By_Reference
-``type'Passed_By_Reference`` for any subtype `type` returns
-a value of type `Boolean` value that is `True` if the type is
-normally passed by reference and `False` if the type is normally
-passed by copy in calls. For scalar types, the result is always `False`
+``typ'Passed_By_Reference`` for any subtype `typ` returns
+a value of type ``Boolean`` value that is ``True`` if the type is
+normally passed by reference and ``False`` if the type is normally
+passed by copy in calls. For scalar types, the result is always ``False``
and is static. For non-scalar types, the result is nonstatic.
Attribute Pool_Address
.. index:: Pool_Address
-``X'Pool_Address`` for any object `X` returns the address
+``X'Pool_Address`` for any object ``X`` returns the address
of X within its storage pool. This is the same as
``X'Address``, except that for an unconstrained array whose
bounds are allocated just before the first component,
``wherever the object is allocated``, which could be a
user-defined storage pool,
the global heap, on the stack, or in a static memory area.
-For an object created by `new`, ``Ptr.all'Pool_Address`` is
-what is passed to `Allocate` and returned from `Deallocate`.
+For an object created by ``new``, ``Ptr.all'Pool_Address`` is
+what is passed to ``Allocate`` and returned from ``Deallocate``.
Attribute Range_Length
======================
.. index:: Range_Length
-``type'Range_Length`` for any discrete type `type` yields
+``typ'Range_Length`` for any discrete type `typ` yields
the number of values represented by the subtype (zero for a null
-range). The result is static for static subtypes. `Range_Length`
+range). The result is static for static subtypes. ``Range_Length``
applied to the index subtype of a one dimensional array always gives the
-same result as `Length` applied to the array itself.
+same result as ``Length`` applied to the array itself.
Attribute Restriction_Set
=========================
In the case of the first form, the only restriction names
allowed are parameterless restrictions that are checked
for consistency at bind time. For a complete list see the
-subtype `System.Rident.Partition_Boolean_Restrictions`.
+subtype ``System.Rident.Partition_Boolean_Restrictions``.
The result returned is True if the restriction is known to
be in effect, and False if the restriction is known not to
.. index:: Safe_Emax
-The `Safe_Emax` attribute is provided for compatibility with Ada 83. See
+The ``Safe_Emax`` attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
.. index:: Safe_Large
-The `Safe_Large` attribute is provided for compatibility with Ada 83. See
+The ``Safe_Large`` attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
.. index:: Safe_Small
-The `Safe_Small` attribute is provided for compatibility with Ada 83. See
+The ``Safe_Small`` attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
.. index:: Scalar_Storage_Order
-For every array or record type `S`, the representation attribute
-`Scalar_Storage_Order` denotes the order in which storage elements
+For every array or record type ``S``, the representation attribute
+``Scalar_Storage_Order`` denotes the order in which storage elements
that make up scalar components are ordered within S. The value given must
be a static expression of type System.Bit_Order. The following is an example
of the use of this feature:
-- the former is used.
-Other properties are as for standard representation attribute `Bit_Order`,
-as defined by Ada RM 13.5.3(4). The default is `System.Default_Bit_Order`.
+Other properties are as for standard representation attribute ``Bit_Order``,
+as defined by Ada RM 13.5.3(4). The default is ``System.Default_Bit_Order``.
-For a record type `T`, if ``T'Scalar_Storage_Order`` is
+For a record type ``T``, if ``T'Scalar_Storage_Order`` is
specified explicitly, it shall be equal to ``T'Bit_Order``. Note:
-this means that if a `Scalar_Storage_Order` attribute definition
-clause is not confirming, then the type's `Bit_Order` shall be
+this means that if a ``Scalar_Storage_Order`` attribute definition
+clause is not confirming, then the type's ``Bit_Order`` shall be
specified explicitly and set to the same value.
Derived types inherit an explicitly set scalar storage order from their parent
storage order for the derived type. For a record extension, the derived type
must have the same scalar storage order as the parent type.
-A component of a record or array type that is a bit-packed array, or that
-does not start on a byte boundary, must have the same scalar storage order
-as the enclosing record or array type.
+A component of a record type that is itself a record or an array and that does
+not start and end on a byte boundary must have have the same scalar storage
+order as the record type. A component of a bit-packed array type that is itself
+a record or an array must have the same scalar storage order as the array type.
-No component of a type that has an explicit `Scalar_Storage_Order`
+No component of a type that has an explicit ``Scalar_Storage_Order``
attribute definition may be aliased.
-A confirming `Scalar_Storage_Order` attribute definition clause (i.e.
-with a value equal to `System.Default_Bit_Order`) has no effect.
+A confirming ``Scalar_Storage_Order`` attribute definition clause (i.e.
+with a value equal to ``System.Default_Bit_Order``) has no effect.
If the opposite storage order is specified, then whenever the value of
-a scalar component of an object of type `S` is read, the storage
+a scalar component of an object of type ``S`` is read, the storage
elements of the enclosing machine scalar are first reversed (before
retrieving the component value, possibly applying some shift and mask
operatings on the enclosing machine scalar), and the opposite operation
are relaxed. Instead, the following rules apply:
* the underlying storage elements are those at positions
- `(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)`
+ ``(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)``
* the sequence of underlying storage elements shall have
a size no greater than the largest machine scalar
* the enclosing machine scalar is defined as the smallest machine
scalar starting at a position no greater than
- `position + first_bit / storage_element_size` and covering
- storage elements at least up to `position + (last_bit + storage_element_size - 1) / storage_element_size`
+ ``position + first_bit / storage_element_size`` and covering
+ storage elements at least up to ``position + (last_bit + storage_element_size - 1) / storage_element_size```
* the position of the component is interpreted relative to that machine
scalar.
If no scalar storage order is specified for a type (either directly, or by
inheritance in the case of a derived type), then the default is normally
the native ordering of the target, but this default can be overridden using
-pragma `Default_Scalar_Storage_Order`.
+pragma ``Default_Scalar_Storage_Order``.
-Note that if a component of `T` is itself of a record or array type,
-the specfied `Scalar_Storage_Order` does *not* apply to that nested type:
+Note that if a component of ``T`` is itself of a record or array type,
+the specfied ``Scalar_Storage_Order`` does *not* apply to that nested type:
an explicit attribute definition clause must be provided for the component
type as well if desired.
.. index:: Simple_Storage_Pool
-For every nonformal, nonderived access-to-object type `Acc`, the
-representation attribute `Simple_Storage_Pool` may be specified
+For every nonformal, nonderived access-to-object type ``Acc``, the
+representation attribute ``Simple_Storage_Pool`` may be specified
via an attribute_definition_clause (or by specifying the equivalent aspect):
.. code-block:: ada
The name given in an attribute_definition_clause for the
-`Simple_Storage_Pool` attribute shall denote a variable of
+``Simple_Storage_Pool`` attribute shall denote a variable of
a 'simple storage pool type' (see pragma `Simple_Storage_Pool_Type`).
The use of this attribute is only allowed for a prefix denoting a type
of the variable specified as the simple storage pool of the access type,
and the attribute denotes that variable.
-It is illegal to specify both `Storage_Pool` and `Simple_Storage_Pool`
+It is illegal to specify both ``Storage_Pool`` and ``Simple_Storage_Pool``
for the same access type.
-If the `Simple_Storage_Pool` attribute has been specified for an access
-type, then applying the `Storage_Pool` attribute to the type is flagged
-with a warning and its evaluation raises the exception `Program_Error`.
+If the ``Simple_Storage_Pool`` attribute has been specified for an access
+type, then applying the ``Storage_Pool`` attribute to the type is flagged
+with a warning and its evaluation raises the exception ``Program_Error``.
If the Simple_Storage_Pool attribute has been specified for an access
-type `S`, then the evaluation of the attribute ``S'Storage_Size``
+type ``S``, then the evaluation of the attribute ``S'Storage_Size``
returns the result of calling ``Storage_Size (S'Simple_Storage_Pool)``,
which is intended to indicate the number of storage elements reserved for
the simple storage pool. If the Storage_Size function has not been defined
for the simple storage pool type, then this attribute returns zero.
-If an access type `S` has a specified simple storage pool of type
-`SSP`, then the evaluation of an allocator for that access type calls
-the primitive `Allocate` procedure for type `SSP`, passing
+If an access type ``S`` has a specified simple storage pool of type
+``SSP``, then the evaluation of an allocator for that access type calls
+the primitive ``Allocate`` procedure for type ``SSP``, passing
``S'Simple_Storage_Pool`` as the pool parameter. The detailed
semantics of such allocators is the same as those defined for allocators
in section 13.11 of the :title:`Ada Reference Manual`, with the term
-`simple storage pool` substituted for `storage pool`.
+*simple storage pool* substituted for *storage pool*.
-If an access type `S` has a specified simple storage pool of type
-`SSP`, then a call to an instance of the `Ada.Unchecked_Deallocation`
-for that access type invokes the primitive `Deallocate` procedure
-for type `SSP`, passing ``S'Simple_Storage_Pool`` as the pool
+If an access type ``S`` has a specified simple storage pool of type
+``SSP``, then a call to an instance of the ``Ada.Unchecked_Deallocation``
+for that access type invokes the primitive ``Deallocate`` procedure
+for type ``SSP``, passing ``S'Simple_Storage_Pool`` as the pool
parameter. The detailed semantics of such unchecked deallocations is the same
as defined in section 13.11.2 of the Ada Reference Manual, except that the
-term 'simple storage pool' is substituted for 'storage pool'.
+term *simple storage pool* is substituted for *storage pool*.
Attribute Small
===============
.. index:: Small
-The `Small` attribute is defined in Ada 95 (and Ada 2005) only for
+The ``Small`` attribute is defined in Ada 95 (and Ada 2005) only for
fixed-point types.
GNAT also allows this attribute to be applied to floating-point types
for compatibility with Ada 83. See
======================
.. index:: Storage_Unit
-`Standard'Storage_Unit` (`Standard` is the only permissible
-prefix) provides the same value as `System.Storage_Unit`.
+``Standard'Storage_Unit`` (``Standard`` is the only permissible
+prefix) provides the same value as ``System.Storage_Unit``.
Attribute Stub_Type
===================
remote call, if necessary, using the information in the stub object
to locate the target partition, etc.
-For a prefix `T` that denotes a remote access-to-classwide type,
-`T'Stub_Type` denotes the type of the corresponding stub objects.
+For a prefix ``T`` that denotes a remote access-to-classwide type,
+``T'Stub_Type`` denotes the type of the corresponding stub objects.
-By construction, the layout of `T'Stub_Type` is identical to that of
-type `RACW_Stub_Type` declared in the internal implementation-defined
-unit `System.Partition_Interface`. Use of this attribute will create
+By construction, the layout of ``T'Stub_Type`` is identical to that of
+type ``RACW_Stub_Type`` declared in the internal implementation-defined
+unit ``System.Partition_Interface``. Use of this attribute will create
an implicit dependency on this unit.
Attribute System_Allocator_Alignment
.. index:: System_Allocator_Alignment
-`Standard'System_Allocator_Alignment` (`Standard` is the only
+``Standard'System_Allocator_Alignment`` (``Standard`` is the only
permissible prefix) provides the observable guaranted to be honored by
the system allocator (malloc). This is a static value that can be used
in user storage pools based on malloc either to reject allocation
=====================
.. index:: Target_Name
-`Standard'Target_Name` (`Standard` is the only permissible
+``Standard'Target_Name`` (``Standard`` is the only permissible
prefix) provides a static string value that identifies the target
for the current compilation. For GCC implementations, this is the
standard gcc target name without the terminating slash (for
====================
.. index:: To_Address
-The `System'To_Address`
-(`System` is the only permissible prefix)
+The ``System'To_Address``
+(``System`` is the only permissible prefix)
denotes a function identical to
-`System.Storage_Elements.To_Address` except that
+``System.Storage_Elements.To_Address`` except that
it is a static attribute. This means that if its argument is
a static expression, then the result of the attribute is a
static expression. This means that such an expression can be
====================
.. index:: Type_Class
-``type'Type_Class`` for any type or subtype `type` yields
-the value of the type class for the full type of `type`. If
-`type` is a generic formal type, the value is the value for the
+``typ'Type_Class`` for any type or subtype `typ` yields
+the value of the type class for the full type of `typ`. If
+`typ` is a generic formal type, the value is the value for the
corresponding actual subtype. The value of this attribute is of type
``System.Aux_DEC.Type_Class``, which has the following definition:
Type_Class_Address);
-Protected types yield the value `Type_Class_Task`, which thus
+Protected types yield the value ``Type_Class_Task``, which thus
applies to all concurrent types. This attribute is designed to
be compatible with the DEC Ada 83 attribute of the same name.
==================
.. index:: Type_Key
-The `Type_Key` attribute is applicable to a type or subtype and
+The ``Type_Key`` attribute is applicable to a type or subtype and
yields a value of type Standard.String containing encoded information
about the type or subtype. This provides improved compatibility with
other implementations that support this attribute.
=============================
.. index:: Unconstrained_Array
-The `Unconstrained_Array` attribute can be used with a prefix that
+The ``Unconstrained_Array`` attribute can be used with a prefix that
denotes any type or subtype. It is a static attribute that yields
-`True` if the prefix designates an unconstrained array,
-and `False` otherwise. In a generic instance, the result is
+``True`` if the prefix designates an unconstrained array,
+and ``False`` otherwise. In a generic instance, the result is
still static, and yields the result of applying this test to the
generic actual.
.. index:: Universal_Literal_String
-The prefix of `Universal_Literal_String` must be a named
+The prefix of ``Universal_Literal_String`` must be a named
number. The static result is the string consisting of the characters of
the number as defined in the original source. This allows the user
program to access the actual text of named numbers without intermediate
.. index:: Unrestricted_Access
-The `Unrestricted_Access` attribute is similar to `Access`
+The ``Unrestricted_Access`` attribute is similar to ``Access``
except that all accessibility and aliased view checks are omitted. This
is a user-beware attribute.
-For objects, it is similar to `Address`, for which it is a
+For objects, it is similar to ``Address``, for which it is a
desirable replacement where the value desired is an access type.
In other words, its effect is similar to first applying the
-`Address` attribute and then doing an unchecked conversion to a
+``Address`` attribute and then doing an unchecked conversion to a
desired access type.
-For subprograms, `P'Unrestricted_Access` may be used where
-`P'Access` would be illegal, to construct a value of a
+For subprograms, ``P'Unrestricted_Access`` may be used where
+``P'Access`` would be illegal, to construct a value of a
less-nested named access type that designates a more-nested
subprogram. This value may be used in indirect calls, so long as the
more-nested subprogram still exists; once the subprogram containing it
called after P2 returns, it would be an erroneous use of a dangling
pointer.
-For objects, it is possible to use `Unrestricted_Access` for any
+For objects, it is possible to use ``Unrestricted_Access`` for any
type. However, if the result is of an access-to-unconstrained array
subtype, then the resulting pointer has the same scope as the context
of the attribute, and must not be returned to some enclosing scope.
-For instance, if a function uses `Unrestricted_Access` to create
+For instance, if a function uses ``Unrestricted_Access`` to create
an access-to-unconstrained-array and returns that value to the caller,
the result will involve dangling pointers. In addition, it is only
valid to create pointers to unconstrained arrays using this attribute
A normal unconstrained array value
or a constrained array object marked as aliased has the bounds in memory
just before the array, so a thin pointer can retrieve both the data and
-the bounds. But in this case, the non-aliased object `X` does not have the
-bounds before the string. If the size clause for type `A`
+the bounds. But in this case, the non-aliased object ``X`` does not have the
+bounds before the string. If the size clause for type ``A``
were not present, then the pointer
would be a fat pointer, where one component is a pointer to the bounds,
and all would be well. But with the size clause present, the conversion from
fat pointer to thin pointer in the call loses the bounds, and so this
-is erroneous, and the program likely raises a `Program_Error` exception.
+is erroneous, and the program likely raises a ``Program_Error`` exception.
In general, it is advisable to completely
avoid mixing the use of thin pointers and the use of
-`Unrestricted_Access` where the designated type is an
+``Unrestricted_Access`` where the designated type is an
unconstrained array. The use of thin pointers should be restricted to
cases of porting legacy code that implicitly assumes the size of pointers,
and such code should not in any case be using this attribute.
or may not notice this attempt, and subsequent references to P may yield
either the value 3 or the value 4 or the assignment may blow up if the
compiler decides to put P in read-only memory. One particular case where
-`Unrestricted_Access` can be used in this way is to modify the
-value of an `IN` parameter:
+``Unrestricted_Access`` can be used in this way is to modify the
+value of an ``in`` parameter:
.. code-block:: ada
In general this is a risky approach. It may appear to "work" but such uses of
-`Unrestricted_Access` are potentially non-portable, even from one version
-of `GNAT` to another, so are best avoided if possible.
+``Unrestricted_Access`` are potentially non-portable, even from one version
+of GNAT to another, so are best avoided if possible.
Attribute Update
================
.. index:: Update
-The `Update` attribute creates a copy of an array or record value
+The ``Update`` attribute creates a copy of an array or record value
with one or more modified components. The syntax is::
PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST )
INDEX_EXPRESSION_LIST ::= ( EXPRESSION {, EXPRESSION } )
-where `PREFIX` is the name of an array or record object, the
-association list in parentheses does not contain an `others`
-choice and the box symbol `<>` may not appear in any
+where ``PREFIX`` is the name of an array or record object, the
+association list in parentheses does not contain an ``others``
+choice and the box symbol ``<>`` may not appear in any
expression. The effect is to yield a copy of the array or record value
which is unchanged apart from the components mentioned in the
association list, which are changed to the indicated value. The
Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
-yields a value for `Avar2` of 1,10,20,20,5 with `Avar1`
+yields a value for ``Avar2`` of 1,10,20,20,5 with ``Avar1``
begin unmodified. Similarly:
.. code-block:: ada
Rvar2 : Rec := Rvar1'Update (B => 20);
-yields a value for `Rvar2` of (A => 1, B => 20, C => 3),
-with `Rvar1` being unmodifed.
+yields a value for ``Rvar2`` of (A => 1, B => 20, C => 3),
+with ``Rvar1`` being unmodifed.
Note that the value of the attribute reference is computed
completely before it is used. This means that if you write:
Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
-then the value of `Avar1` is not modified if `Function_Call`
+then the value of ``Avar1`` is not modified if ``Function_Call``
raises an exception, unlike the effect of a series of direct assignments
-to elements of `Avar1`. In general this requires that
+to elements of ``Avar1``. In general this requires that
two extra complete copies of the object are required, which should be
kept in mind when considering efficiency.
-The `Update` attribute cannot be applied to prefixes of a limited
+The ``Update`` attribute cannot be applied to prefixes of a limited
type, and cannot reference discriminants in the case of a record type.
The accessibility level of an Update attribute result object is defined
as for an aggregate.
=======================
.. index:: Valid_Scalars
-The `'Valid_Scalars` attribute is intended to make it easier to
+The ``'Valid_Scalars`` attribute is intended to make it easier to
check the validity of scalar subcomponents of composite objects. It
-is defined for any prefix `X` that denotes an object.
+is defined for any prefix ``X`` that denotes an object.
The value of this attribute is of the predefined type Boolean.
-`X'Valid_Scalars` yields True if and only if evaluation of
-`P'Valid` yields True for every scalar part P of X or if X has
+``X'Valid_Scalars`` yields True if and only if evaluation of
+``P'Valid`` yields True for every scalar part P of X or if X has
no scalar parts. It is not specified in what order the scalar parts
are checked, nor whether any more are checked after any one of them
-is determined to be invalid. If the prefix `X` is of a class-wide
-type `T'Class` (where `T` is the associated specific type),
-or if the prefix `X` is of a specific tagged type `T`, then
-only the scalar parts of components of `T` are traversed; in other
-words, components of extensions of `T` are not traversed even if
-`T'Class (X)'Tag /= T'Tag` . The compiler will issue a warning if it can
+is determined to be invalid. If the prefix ``X`` is of a class-wide
+type ``T'Class`` (where ``T`` is the associated specific type),
+or if the prefix ``X`` is of a specific tagged type ``T``, then
+only the scalar parts of components of ``T`` are traversed; in other
+words, components of extensions of ``T`` are not traversed even if
+``T'Class (X)'Tag /= T'Tag`` . The compiler will issue a warning if it can
be determined at compile time that the prefix of the attribute has no
scalar parts (e.g., if the prefix is of an access type, an interface type,
an undiscriminated task type, or an undiscriminated protected type).
-For scalar types, `Valid_Scalars` is equivalent to `Valid`. The use
-of this attribute is not permitted for `Unchecked_Union` types for which
+For scalar types, ``Valid_Scalars`` is equivalent to ``Valid``. The use
+of this attribute is not permitted for ``Unchecked_Union`` types for which
in general it is not possible to determine the values of the discriminants.
-Note: `Valid_Scalars` can generate a lot of code, especially in the case
+Note: ``Valid_Scalars`` can generate a lot of code, especially in the case
of a large variant record. If the attribute is called in many places in the
same program applied to objects of the same type, it can reduce program size
to write a function with a single use of the attribute, and then call that
.. index:: VADS_Size
-The `'VADS_Size` attribute is intended to make it easier to port
-legacy code which relies on the semantics of `'Size` as implemented
+The ``'VADS_Size`` attribute is intended to make it easier to port
+legacy code which relies on the semantics of ``'Size`` as implemented
by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
-same semantic interpretation. In particular, `'VADS_Size` applied
+same semantic interpretation. In particular, ``'VADS_Size`` applied
to a predefined or other primitive type with no Size clause yields the
-Object_Size (for example, `Natural'Size` is 32 rather than 31 on
-typical machines). In addition `'VADS_Size` applied to an object
+Object_Size (for example, ``Natural'Size`` is 32 rather than 31 on
+typical machines). In addition ``'VADS_Size`` applied to an object
gives the result that would be obtained by applying the attribute to
the corresponding type.
``type'Value_Size`` is the number of bits required to represent
a value of the given subtype. It is the same as ``type'Size``,
-but, unlike `Size`, may be set for non-first subtypes.
+but, unlike ``Size``, may be set for non-first subtypes.
Attribute Wchar_T_Size
======================
.. index:: Wchar_T_Size
-`Standard'Wchar_T_Size` (`Standard` is the only permissible
-prefix) provides the size in bits of the C `wchar_t` type
+``Standard'Wchar_T_Size`` (``Standard`` is the only permissible
+prefix) provides the size in bits of the C ``wchar_t`` type
primarily for constructing the definition of this type in
-package `Interfaces.C`. The result is a static constant.
+package ``Interfaces.C``. The result is a static constant.
Attribute Word_Size
===================
.. index:: Word_Size
-`Standard'Word_Size` (`Standard` is the only permissible
-prefix) provides the value `System.Word_Size`. The result is
+``Standard'Word_Size`` (``Standard`` is the only permissible
+prefix) provides the value ``System.Word_Size``. The result is
a static constant.
"Which code_statements cause external
interactions. See 1.1.3(10)."
-Any `code_statement` can potentially cause external interactions.
+Any *code_statement* can potentially cause external interactions.
*
"The coded representation for the text of an Ada
See :ref:`Implementation_Defined_Pragmas`.
*
- "Effect of pragma `Optimize`. See 2.8(27)."
+ "Effect of pragma ``Optimize``. See 2.8(27)."
-Pragma `Optimize`, if given with a `Time` or `Space`
+Pragma ``Optimize``, if given with a ``Time`` or ``Space``
parameter, checks that the optimization flag is set, and aborts if it is
not.
*
"The sequence of characters of the value returned by
``S'Image`` when some of the graphic characters of
- ``S'Wide_Image`` are not defined in `Character`. See
+ ``S'Wide_Image`` are not defined in ``Character``. See
3.5(37)."
The sequence of characters is as defined by the wide character encoding
*
"The predefined integer types declared in
- `Standard`. See 3.5.4(25)."
+ ``Standard``. See 3.5.4(25)."
====================== =======================================
Type Representation
*
"The predefined floating point types declared in
- `Standard`. See 3.5.7(16)."
+ ``Standard``. See 3.5.7(16)."
====================== ====================================================
Type Representation
*
"The small of an ordinary fixed point type. See 3.5.9(8)."
-`Fine_Delta` is 2**(-63)
+``Fine_Delta`` is 2**(-63)
*
"What combinations of small, range, and digits are
supported for fixed point types. See 3.5.9(10)."
Any combinations are permitted that do not result in a small less than
-`Fine_Delta` and do not result in a mantissa larger than 63 bits.
+``Fine_Delta`` and do not result in a mantissa larger than 63 bits.
If the mantissa is larger than 53 bits on machines where Long_Long_Float
is 64 bits (true of all architectures except ia32), then the output from
Text_IO is accurate to only 53 bits, rather than the full mantissa. This
*
- "The result of `Tags.Expanded_Name` for types declared
- within an unnamed `block_statement`. See 3.9(10)."
+ "The result of ``Tags.Expanded_Name`` for types declared
+ within an unnamed *block_statement*. See 3.9(10)."
-Block numbers of the form `B`nnn``, where `nnn` is a
+Block numbers of the form :samp:`B{nnn}`, where *nnn* is a
decimal integer are allocated.
*
"The time base associated with relative delays."
See 9.6(20). The time base used is that provided by the C library
-function `gettimeofday`.
+function ``gettimeofday``.
*
- "The time base of the type `Calendar.Time`. See
+ "The time base of the type ``Calendar.Time``. See
9.6(23)."
The time base used is that provided by the C library function
-`gettimeofday`.
+``gettimeofday``.
*
- "The time zone used for package `Calendar`
+ "The time zone used for package ``Calendar``
operations. See 9.6(24)."
-The time zone used by package `Calendar` is the current system time zone
+The time zone used by package ``Calendar`` is the current system time zone
setting for local time, as accessed by the C library function
-`localtime`.
+``localtime``.
*
- "Any limit on `delay_until_statements` of
- `select_statements`. See 9.6(29)."
+ "Any limit on *delay_until_statements* of
+ *select_statements*. See 9.6(29)."
There are no such limits.
*
"Whether or not two non-overlapping parts of a composite
object are independently addressable, in the case where packing, record
- layout, or `Component_Size` is specified for the object. See
+ layout, or ``Component_Size`` is specified for the object. See
9.10(1)."
Separate components are independently addressable if they do not share
this case a list of units can be explicitly supplied to the binder for
inclusion in the partition (all units needed by these units will also
be included automatically). For full details on the use of these
-options, refer to the `GNAT Make Program gnatmake` in the
+options, refer to *GNAT Make Program gnatmake* in the
:title:`GNAT User's Guide`.
*
corresponding :file:`ALI` file as the input parameter to the binder.
*
- "The order of elaboration of `library_items`. See
+ "The order of elaboration of *library_items*. See
10.2(18)."
The first constraint on ordering is that it meets the requirements of
The main program has no parameters. It may be a procedure, or a function
returning an integer type. In the latter case, the returned integer
value is the return code of the program (overriding any value that
-may have been set by a call to `Ada.Command_Line.Set_Exit_Status`).
+may have been set by a call to ``Ada.Command_Line.Set_Exit_Status``).
*
"The mechanisms for building and running partitions. See
further details.
*
- "The information returned by `Exception_Message`. See
+ "The information returned by ``Exception_Message``. See
11.4.1(10)."
Exception message returns the null string unless a specific message has
been passed by the program.
*
- "The result of `Exceptions.Exception_Name` for types
- declared within an unnamed `block_statement`. See 11.4.1(12)."
+ "The result of ``Exceptions.Exception_Name`` for types
+ declared within an unnamed *block_statement*. See 11.4.1(12)."
-Blocks have implementation defined names of the form `B`nnn``
-where `nnn` is an integer.
+Blocks have implementation defined names of the form :samp:`B{nnn}`
+where *nnn* is an integer.
*
"The information returned by
- `Exception_Information`. See 11.4.1(13)."
+ ``Exception_Information``. See 11.4.1(13)."
-`Exception_Information` returns a string in the following format::
+``Exception_Information`` returns a string in the following format::
*Exception_Name:* nnnnn
*Message:* mmmmm
where
- * `nnnn` is the fully qualified name of the exception in all upper
+ * ``nnnn`` is the fully qualified name of the exception in all upper
case letters. This line is always present.
- * `mmmm` is the message (this line present only if message is non-null)
+ * ``mmmm`` is the message (this line present only if message is non-null)
- * `ppp` is the Process Id value as a decimal integer (this line is
+ * ``ppp`` is the Process Id value as a decimal integer (this line is
present only if the Process Id is nonzero). Currently we are
not making use of this field.
the main executable. The values are given in C style format, with lower case
letters for a-f, and only as many digits present as are necessary.
The line terminator sequence at the end of each line, including
- the last line is a single `LF` character (`16#0A#`).
+ the last line is a single ``LF`` character (``16#0A#``).
*
"Implementation-defined check names. See 11.5(27)."
Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks,
Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user
program can add implementation-defined check names by means of the pragma
-Check_Name. See the description of pragma `Suppress` for full details.
+Check_Name. See the description of pragma ``Suppress`` for full details.
*
"The interpretation of each aspect of representation. See
See separate section on data representations.
*
- "The meaning of `Size` for indefinite subtypes. See
+ "The meaning of ``Size`` for indefinite subtypes. See
13.3(48)."
Size for an indefinite subtype is the maximum possible size, except that
which contains a pointer to the dispatching table.
*
- "If `Word_Size` = `Storage_Unit`, the default bit
+ "If ``Word_Size`` = ``Storage_Unit``, the default bit
ordering. See 13.5.3(5)."
-`Word_Size` (32) is not the same as `Storage_Unit` (8) for this
+``Word_Size`` (32) is not the same as ``Storage_Unit`` (8) for this
implementation, so no non-default bit ordering is supported. The default
bit ordering corresponds to the natural endianness of the target architecture.
*
- "The contents of the visible part of package `System`
+ "The contents of the visible part of package ``System``
and its language-defined children. See 13.7(2)."
See the definition of these packages in files :file:`system.ads` and
*
"The contents of the visible part of package
- `System.Machine_Code`, and the meaning of
- `code_statements`. See 13.8(7)."
+ ``System.Machine_Code``, and the meaning of
+ *code_statements*. See 13.8(7)."
See the definition and documentation in file :file:`s-maccod.ads`.
*
"The manner of choosing a storage pool for an access type
- when `Storage_Pool` is not specified for the type. See 13.11(17)."
+ when ``Storage_Pool`` is not specified for the type. See 13.11(17)."
There are 3 different standard pools used by the compiler when
-`Storage_Pool` is not specified depending whether the type is local
+``Storage_Pool`` is not specified depending whether the type is local
to a subprogram or defined at the library level and whether
-`Storage_Size`is specified or not. See documentation in the runtime
-library units `System.Pool_Global`, `System.Pool_Size` and
-`System.Pool_Local` in files :file:`s-poosiz.ads`,
+``Storage_Size``is specified or not. See documentation in the runtime
+library units ``System.Pool_Global``, ``System.Pool_Size`` and
+``System.Pool_Local`` in files :file:`s-poosiz.ads`,
:file:`s-pooglo.ads` and :file:`s-pooloc.ads` for full details on the
default pools used.
names for the standard pool type(s). See 13.11(17)."
See documentation in the sources of the run time mentioned in the previous
-paragraph. All these pools are accessible by means of `with`'ing
+paragraph. All these pools are accessible by means of `with`\ ing
these units.
*
- "The meaning of `Storage_Size`. See 13.11(18)."
+ "The meaning of ``Storage_Size``. See 13.11(18)."
-`Storage_Size` is measured in storage units, and refers to the
+``Storage_Size`` is measured in storage units, and refers to the
total space available for an access type collection, or to the primary
stack space for a task.
*
"The set of restrictions allowed in a pragma
- `Restrictions`. See 13.12(7)."
+ ``Restrictions``. See 13.12(7)."
See :ref:`Standard_and_Implementation_Defined_Restrictions`.
*
"The consequences of violating limitations on
- `Restrictions` pragmas. See 13.12(9)."
+ ``Restrictions`` pragmas. See 13.12(9)."
Restrictions that can be checked at compile time result in illegalities
if violated. Currently there are no other consequences of violating
restrictions.
*
- "The representation used by the `Read` and
- `Write` attributes of elementary types in terms of stream
+ "The representation used by the ``Read`` and
+ ``Write`` attributes of elementary types in terms of stream
elements. See 13.13.2(9)."
The representation is the in-memory representation of the base type of
*
"The names and characteristics of the numeric subtypes
- declared in the visible part of package `Standard`. See A.1(3)."
+ declared in the visible part of package ``Standard``. See A.1(3)."
See items describing the integer and floating-point types supported.
*
- "The string returned by `Character_Set_Version`.
+ "The string returned by ``Character_Set_Version``.
See A.3.5(3)."
-`Ada.Wide_Characters.Handling.Character_Set_Version` returns
+``Ada.Wide_Characters.Handling.Character_Set_Version`` returns
the string "Unicode 4.0", referring to version 4.0 of the
Unicode specification.
*
"The sign of a zero result from some of the operators or
- functions in `Numerics.Generic_Elementary_Functions`, when
- `Float_Type'Signed_Zeros` is `True`. See A.5.1(46)."
+ functions in ``Numerics.Generic_Elementary_Functions``, when
+ ``Float_Type'Signed_Zeros`` is ``True``. See A.5.1(46)."
The sign of zeroes follows the requirements of the IEEE 754 standard on
floating-point.
*
"The value of
- `Numerics.Float_Random.Max_Image_Width`. See A.5.2(27)."
+ ``Numerics.Float_Random.Max_Image_Width``. See A.5.2(27)."
Maximum image width is 6864, see library file :file:`s-rannum.ads`.
*
"The value of
- `Numerics.Discrete_Random.Max_Image_Width`. See A.5.2(27)."
+ ``Numerics.Discrete_Random.Max_Image_Width``. See A.5.2(27)."
Maximum image width is 6864, see library file :file:`s-rannum.ads`.
random numbers is one microsecond.
*
- "The values of the `Model_Mantissa`,
- `Model_Emin`, `Model_Epsilon`, `Model`,
- `Safe_First`, and `Safe_Last` attributes, if the Numerics
+ "The values of the ``Model_Mantissa``,
+ ``Model_Emin``, ``Model_Epsilon``, ``Model``,
+ ``Safe_First``, and ``Safe_Last`` attributes, if the Numerics
Annex is not supported. See A.5.3(72)."
Run the compiler with *-gnatS* to produce a listing of package
-`Standard`, has the values of all numeric attributes.
+``Standard``, has the values of all numeric attributes.
*
"Any implementation-defined characteristics of the
packages.
*
- "The value of `Buffer_Size` in `Storage_IO`. See
+ "The value of ``Buffer_Size`` in ``Storage_IO``. See
A.9(10)."
-All type representations are contiguous, and the `Buffer_Size` is
+All type representations are contiguous, and the ``Buffer_Size`` is
the value of ``type'Size`` rounded up to the next storage unit
boundary.
libraries. See source file :file:`i-cstrea.ads` for further details.
*
- "The accuracy of the value produced by `Put`. See
+ "The accuracy of the value produced by ``Put``. See
A.10.9(36)."
If more digits are requested in the output than are represented by the
significant digit positions.
*
- "The meaning of `Argument_Count`, `Argument`, and
- `Command_Name`. See A.15(1)."
+ "The meaning of ``Argument_Count``, ``Argument``, and
+ ``Command_Name``. See A.15(1)."
-These are mapped onto the `argv` and `argc` parameters of the
+These are mapped onto the ``argv`` and ``argc`` parameters of the
main program in the natural manner.
*
- "The interpretation of the `Form` parameter in procedure
- `Create_Directory`. See A.16(56)."
+ "The interpretation of the ``Form`` parameter in procedure
+ ``Create_Directory``. See A.16(56)."
-The `Form` parameter is not used.
+The ``Form`` parameter is not used.
*
- "The interpretation of the `Form` parameter in procedure
- `Create_Path`. See A.16(60)."
+ "The interpretation of the ``Form`` parameter in procedure
+ ``Create_Path``. See A.16(60)."
-The `Form` parameter is not used.
+The ``Form`` parameter is not used.
*
- "The interpretation of the `Form` parameter in procedure
- `Copy_File`. See A.16(68)."
+ "The interpretation of the ``Form`` parameter in procedure
+ ``Copy_File``. See A.16(68)."
-The `Form` parameter is case-insensitive.
-Two fields are recognized in the `Form` parameter::
+The ``Form`` parameter is case-insensitive.
+Two fields are recognized in the ``Form`` parameter::
*preserve=<value>*
*mode=<value>*
Form => "mode=internal, preserve=timestamps"
*
- "The interpretation of the `Pattern` parameter, when not the null string,
- in the `Start_Search` and `Search` procedures.
+ "The interpretation of the ``Pattern`` parameter, when not the null string,
+ in the ``Start_Search`` and ``Search`` procedures.
See A.16(104) and A.16(112)."
-When the `Pattern` parameter is not the null string, it is interpreted
+When the ``Pattern`` parameter is not the null string, it is interpreted
according to the syntax of regular expressions as defined in the
-`GNAT.Regexp` package.
+``GNAT.Regexp`` package.
See :ref:`GNAT.Regexp_(g-regexp.ads)`.
*Default* Treated the same as C
*External* Treated the same as C
*Fortran* Fortran
-*Intrinsic* For support of pragma `Import` with convention Intrinsic, see
+*Intrinsic* For support of pragma ``Import`` with convention Intrinsic, see
separate section on Intrinsic Subprograms.
*Stdcall* Stdcall (used for Windows implementations only). This convention correspond
to the WINAPI (previously called Pascal convention) C/C++ convention under
*Win32* Synonym for Stdcall
*Stubbed* Stubbed is a special convention used to indicate that the body of the
subprogram will be entirely ignored. Any call to the subprogram
- is converted into a raise of the `Program_Error` exception. If a
- pragma `Import` specifies convention `stubbed` then no body need
+ is converted into a raise of the ``Program_Error`` exception. If a
+ pragma ``Import`` specifies convention ``stubbed`` then no body need
be present at all. This convention is useful during development for the
inclusion of subprograms whose body has not yet been written.
In addition, all otherwise unrecognized convention names are also
letters.
*
- "The effect of pragma `Linker_Options`. See B.1(37)."
+ "The effect of pragma ``Linker_Options``. See B.1(37)."
-The string passed to `Linker_Options` is presented uninterpreted as
+The string passed to ``Linker_Options`` is presented uninterpreted as
an argument to the link command, unless it contains ASCII.NUL characters.
NUL characters if they appear act as argument separators, so for example
pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
-causes two separate arguments `-labc` and `-ldef` to be passed to the
+causes two separate arguments ``-labc`` and ``-ldef`` to be passed to the
linker. The order of linker options is preserved for a given unit. The final
list of options passed to the linker is in reverse order of the elaboration
order. For example, linker options for a body always appear before the options
*
"The contents of the visible part of package
- `Interfaces` and its language-defined descendants. See B.2(1)."
+ ``Interfaces`` and its language-defined descendants. See B.2(1)."
See files with prefix :file:`i-` in the distributed library.
*
"Implementation-defined children of package
- `Interfaces`. The contents of the visible part of package
- `Interfaces`. See B.2(11)."
+ ``Interfaces``. The contents of the visible part of package
+ ``Interfaces``. See B.2(11)."
See files with prefix :file:`i-` in the distributed library.
*
- "The types `Floating`, `Long_Floating`,
- `Binary`, `Long_Binary`, `Decimal_ Element`, and
- `COBOL_Character`; and the initialization of the variables
- `Ada_To_COBOL` and `COBOL_To_Ada`, in
- `Interfaces.COBOL`. See B.4(50)."
+ "The types ``Floating``, ``Long_Floating``,
+ ``Binary``, ``Long_Binary``, ``Decimal_ Element``, and
+ ``COBOL_Character``; and the initialization of the variables
+ ``Ada_To_COBOL`` and ``COBOL_To_Ada``, in
+ ``Interfaces.COBOL``. See B.4(50)."
===================== ====================================
COBOL Ada
Interrupts are mapped to signals or conditions as appropriate. See
definition of unit
-`Ada.Interrupt_Names` in source file :file:`a-intnam.ads` for details
+``Ada.Interrupt_Names`` in source file :file:`a-intnam.ads` for details
on the interrupts supported on a particular target.
*
except under control of the debugger.
*
- "The semantics of pragma `Discard_Names`. See C.5(7)."
+ "The semantics of pragma ``Discard_Names``. See C.5(7)."
-Pragma `Discard_Names` causes names of enumeration literals to
+Pragma ``Discard_Names`` causes names of enumeration literals to
be suppressed. In the presence of this pragma, the Image attribute
provides the image of the Pos of the literal, and Value accepts
Pos values.
*
- "The result of the `Task_Identification.Image`
+ "The result of the ``Task_Identification.Image``
attribute. See C.7.1(7)."
The result of this attribute is a string that identifies
-the object or component that denotes a given task. If a variable `Var`
-has a task type, the image for this task will have the form `Var_`XXXXXXXX``,
-where the suffix
+the object or component that denotes a given task. If a variable ``Var``
+has a task type, the image for this task will have the form :samp:`Var_{XXXXXXXX}`,
+where the suffix *XXXXXXXX*
is the hexadecimal representation of the virtual address of the corresponding
task control block. If the variable is an array of tasks, the image of each
task will have the form of an indexed component indicating the position of a
-given task in the array, e.g., `Group(5)_`XXXXXXX``. If the task is a
+given task in the array, e.g., :samp:`Group(5)_{XXXXXXX}`. If the task is a
component of a record, the image of the task will have the form of a selected
component. These rules are fully recursive, so that the image of a task that
is a subcomponent of a composite object corresponds to the expression that
virtual address of the control block of the task.
*
- "The value of `Current_Task` when in a protected entry
+ "The value of ``Current_Task`` when in a protected entry
or interrupt handler. See C.7.1(17)."
Protected entries or interrupt handlers can be executed by any
-convenient thread, so the value of `Current_Task` is undefined.
+convenient thread, so the value of ``Current_Task`` is undefined.
*
- "The effect of calling `Current_Task` from an entry
+ "The effect of calling ``Current_Task`` from an entry
body or interrupt handler. See C.7.1(19)."
-The effect of calling `Current_Task` from an entry body or
-interrupt handler is to return the identification of the task currently
-executing the code.
+When GNAT can determine statically that ``Current_Task`` is called directly in
+the body of an entry (or barrier) then a warning is emitted and ``Program_Error``
+is raised at run time. Otherwise, the effect of calling ``Current_Task`` from an
+entry body or interrupt handler is to return the identification of the task
+currently executing the code.
*
"Implementation-defined aspects of
- `Task_Attributes`. See C.7.2(19)."
+ ``Task_Attributes``. See C.7.2(19)."
-There are no implementation-defined aspects of `Task_Attributes`.
+There are no implementation-defined aspects of ``Task_Attributes``.
*
- "Values of all `Metrics`. See D(2)."
+ "Values of all ``Metrics``. See D(2)."
The metrics information for GNAT depends on the performance of the
underlying operating system. The sources of the run-time for tasking
the required metrics.
*
- "The declarations of `Any_Priority` and
- `Priority`. See D.1(11)."
+ "The declarations of ``Any_Priority`` and
+ ``Priority``. See D.1(11)."
See declarations in file :file:`system.ads`.
underlying operating system.
*
- "Implementation-defined `policy_identifiers` allowed
- in a pragma `Task_Dispatching_Policy`. See D.2.2(3)."
+ "Implementation-defined *policy_identifiers* allowed
+ in a pragma ``Task_Dispatching_Policy``. See D.2.2(3)."
There are no implementation-defined policy-identifiers allowed in this
pragma.
The policy is the same as that of the underlying threads implementation.
*
- "Implementation-defined `policy_identifiers` allowed
- in a pragma `Locking_Policy`. See D.3(4)."
+ "Implementation-defined *policy_identifiers* allowed
+ in a pragma ``Locking_Policy``. See D.3(4)."
The two implementation defined policies permitted in GNAT are
-`Inheritance_Locking` and `Concurrent_Readers_Locking`. On
-targets that support the `Inheritance_Locking` policy, locking is
+``Inheritance_Locking`` and ``Concurrent_Readers_Locking``. On
+targets that support the ``Inheritance_Locking`` policy, locking is
implemented by inheritance, i.e., the task owning the lock operates
at a priority equal to the highest priority of any task currently
requesting the lock. On targets that support the
-`Concurrent_Readers_Locking` policy, locking is implemented with a
+``Concurrent_Readers_Locking`` policy, locking is implemented with a
read/write lock allowing multiple protected object functions to enter
concurrently.
"Default ceiling priorities. See D.3(10)."
The ceiling priority of protected objects of the type
-`System.Interrupt_Priority'Last` as described in the Ada
+``System.Interrupt_Priority'Last`` as described in the Ada
Reference Manual D.3(10),
*
the implementation. See D.3(16)."
The ceiling priority of internal protected objects is
-`System.Priority'Last`.
+``System.Priority'Last``.
*
"Implementation-defined queuing policies. See D.4(1)."
*
"What happens when a task terminates in the presence of
- pragma `No_Task_Termination`. See D.7(15)."
+ pragma ``No_Task_Termination``. See D.7(15)."
Execution is erroneous in that case.
*
"Implementation-defined aspects of pragma
- `Restrictions`. See D.7(20)."
+ ``Restrictions``. See D.7(20)."
There are no such implementation-defined aspects.
*
"Implementation-defined aspects of package
- `Real_Time`. See D.8(17)."
+ ``Real_Time``. See D.8(17)."
-There are no implementation defined aspects of package `Real_Time`.
+There are no implementation defined aspects of package ``Real_Time``.
*
"Implementation-defined aspects of
- `delay_statements`. See D.9(8)."
+ *delay_statements*. See D.9(8)."
Any difference greater than one microsecond will cause the task to be
delayed (see D.9(7)).
*
"The values of named numbers in the package
- `Decimal`. See F.2(7)."
+ ``Decimal``. See F.2(7)."
==================== ==========
Named Number Value
==================== ==========
*
- "The value of `Max_Picture_Length` in the package
- `Text_IO.Editing`. See F.3.3(16)."
+ "The value of ``Max_Picture_Length`` in the package
+ ``Text_IO.Editing``. See F.3.3(16)."
64
*
- "The value of `Max_Picture_Length` in the package
- `Wide_Text_IO.Editing`. See F.3.4(5)."
+ "The value of ``Max_Picture_Length`` in the package
+ ``Wide_Text_IO.Editing``. See F.3.4(5)."
64
*
"The sign of a zero result (or a component thereof) from
- any operator or function in `Numerics.Generic_Complex_Types`, when
- `Real'Signed_Zeros` is True. See G.1.1(53)."
+ any operator or function in ``Numerics.Generic_Complex_Types``, when
+ ``Real'Signed_Zeros`` is True. See G.1.1(53)."
The signs of zero values are as recommended by the relevant
implementation advice.
*
"The sign of a zero result (or a component thereof) from
any operator or function in
- `Numerics.Generic_Complex_Elementary_Functions`, when
- `Real'Signed_Zeros` is `True`. See G.1.2(45)."
+ ``Numerics.Generic_Complex_Elementary_Functions``, when
+ ``Real'Signed_Zeros`` is ``True``. See G.1.2(45)."
The signs of zero values are as recommended by the relevant
implementation advice.
*
"The result of a floating point arithmetic operation in
- overflow situations, when the `Machine_Overflows` attribute of the
- result type is `False`. See G.2.1(13)."
+ overflow situations, when the ``Machine_Overflows`` attribute of the
+ result type is ``False``. See G.2.1(13)."
Infinite and NaN values are produced as dictated by the IEEE
floating-point standard.
is converted to the target type.
*
- "Conditions on a `universal_real` operand of a fixed
+ "Conditions on a *universal_real* operand of a fixed
point multiplication or division for which the result shall be in the
perfect result set. See G.2.3(22)."
*
"The result of a fixed point arithmetic operation in
- overflow situations, when the `Machine_Overflows` attribute of the
- result type is `False`. See G.2.3(27)."
+ overflow situations, when the ``Machine_Overflows`` attribute of the
+ result type is ``False``. See G.2.3(27)."
-Not relevant, `Machine_Overflows` is `True` for fixed-point
+Not relevant, ``Machine_Overflows`` is ``True`` for fixed-point
types.
*
"The result of an elementary function reference in
- overflow situations, when the `Machine_Overflows` attribute of the
- result type is `False`. See G.2.4(4)."
+ overflow situations, when the ``Machine_Overflows`` attribute of the
+ result type is ``False``. See G.2.4(4)."
IEEE infinite and Nan values are produced as appropriate.
*
"The result of a complex arithmetic operation or complex
elementary function reference in overflow situations, when the
- `Machine_Overflows` attribute of the corresponding real type is
- `False`. See G.2.6(5)."
+ ``Machine_Overflows`` attribute of the corresponding real type is
+ ``False``. See G.2.6(5)."
IEEE infinite and Nan values are produced as appropriate.
*
"Implementation-defined aspects of pragma
- `Inspection_Point`. See H.3.2(8)."
+ ``Inspection_Point``. See H.3.2(8)."
-Pragma `Inspection_Point` ensures that the variable is live and can
+Pragma ``Inspection_Point`` ensures that the variable is live and can
be examined by the debugger at the inspection point.
*
"Implementation-defined aspects of pragma
- `Restrictions`. See H.4(25)."
+ ``Restrictions``. See H.4(25)."
-There are no implementation-defined aspects of pragma `Restrictions`. The
-use of pragma `Restrictions [No_Exceptions]` has no effect on the
-generated code. Checks must suppressed by use of pragma `Suppress`.
+There are no implementation-defined aspects of pragma ``Restrictions``. The
+use of pragma ``Restrictions [No_Exceptions]`` has no effect on the
+generated code. Checks must suppressed by use of pragma ``Suppress``.
*
- "Any restrictions on pragma `Restrictions`. See
+ "Any restrictions on pragma ``Restrictions``. See
H.4(27)."
-There are no restrictions on pragma `Restrictions`.
+There are no restrictions on pragma ``Restrictions``.
+.. role:: switch(samp)
+
.. _Implementation_Defined_Pragmas:
******************************
This pragma must appear at the start of the statement sequence of a
-handled sequence of statements (right after the `begin`). It has
+handled sequence of statements (right after the ``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).
ABSTRACT_STATE ::= name
-For the semantics of this pragma, see the entry for aspect `Abstract_State` in
+For the semantics of this pragma, see the entry for aspect ``Abstract_State`` in
the SPARK 2014 Reference Manual, section 7.1.4.
Pragma Ada_83
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 `(<>)` notation. In addition, some but not all of the additional
+the ``(<>)`` 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
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 `Ada` and `System`
+This mode is set automatically for the ``Ada`` and ``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
A configuration pragma that establishes Ada 2012 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 `Ada` and `System`
+This mode is set automatically for the ``Ada`` and ``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 2012 features, but which is intended to be usable from
pragma Allow_Integer_Address;
-In almost all versions of GNAT, `System.Address` is a private
+In almost all versions of GNAT, ``System.Address`` is a private
type in accordance with the implementation advice in the RM. This
means that integer values,
in particular integer literals, are not allowed as address values.
If the configuration pragma
-`Allow_Integer_Address` is given, then integer expressions may
-be used anywhere a value of type `System.Address` is required.
+``Allow_Integer_Address`` is given, then integer expressions may
+be used anywhere a value of type ``System.Address`` is required.
The effect is to introduce an implicit unchecked conversion from the
-integer value to type `System.Address`. The reverse case of using
+integer value to type ``System.Address``. The reverse case of using
an address where an integer type is required is handled analogously.
The following example compiles without errors:
end AddrAsInt;
-Note that pragma `Allow_Integer_Address` is ignored if `System.Address`
-is not a private type. In implementations of `GNAT` where
+Note that pragma ``Allow_Integer_Address`` is ignored if ``System.Address``
+is not a private type. In implementations of ``GNAT`` where
System.Address is a visible integer type,
this pragma serves no purpose but is ignored
rather than rejected to allow common sets of sources to be used
ARG ::= NAME | EXPRESSION
-This pragma is used to annotate programs. `identifier` identifies
+This pragma is used to annotate programs. IDENTIFIER identifies
the type of annotation. GNAT verifies that it is an identifier, but does
not otherwise analyze it. The second optional identifier is also left
unanalyzed, and by convention is used to control the action of the tool to
-which the annotation is addressed. The remaining `arg` arguments
+which the annotation is addressed. The remaining ARG arguments
can be either string literals or more generally expressions.
String literals are assumed to be either of type
-`Standard.String` or else `Wide_String` or `Wide_Wide_String`
+``Standard.String`` or else ``Wide_String`` or ``Wide_Wide_String``
depending on the character literals they contain.
All other kinds of arguments are analyzed as expressions, and must be
unambiguous. The last argument if present must have the identifier
-`Entity` and GNAT verifies that a local name is given.
+``Entity`` and GNAT verifies that a local name is given.
The analyzed pragma is retained in the tree, but not otherwise processed
by any part of the GNAT compiler, except to generate corresponding note
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 `file`:`nnn`,
-where `file` is the name of the source file containing the assert,
-and `nnn` is the line number of the assert.
+argument is given, the default message is ``file``:``nnn``,
+where ``file`` is the name of the source file containing the assert,
+and ``nnn`` is the line number of the assert.
-Note that, as with the `if` statement to which it is equivalent, the
-type of the expression is either `Standard.Boolean`, or any type derived
+Note that, as with the ``if`` statement to which it is equivalent, the
+type of the expression is either ``Standard.Boolean``, or any type derived
from this standard type.
Assert checks can be either checked or ignored. By default they are ignored.
They will be checked if either the command line switch *-gnata* is
-used, or if an `Assertion_Policy` or `Check_Policy` pragma is used
-to enable `Assert_Checks`.
+used, or if an ``Assertion_Policy`` or ``Check_Policy`` pragma is used
+to enable ``Assert_Checks``.
If assertions are ignored, then there
is no run-time effect (and in particular, any side effects from the
mentioned here for the first time).
If assertions are checked, then the given expression is tested, and if
-it is `False` then `System.Assertions.Raise_Assert_Failure` is called
-which results in the raising of `Assert_Failure` with the given message.
+it is ``False`` then ``System.Assertions.Raise_Assert_Failure`` is called
+which results in the raising of ``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
semantic correctness whether or not assertions are enabled, so turning
assertions on and off cannot affect the legality of a program.
-Note that the implementation defined policy `DISABLE`, given in a
-pragma `Assertion_Policy`, can be used to suppress this semantic analysis.
+Note that the implementation defined policy ``DISABLE``, given in a
+pragma ``Assertion_Policy``, can be used to suppress this semantic analysis.
Note: this is a standard language-defined pragma in versions
of Ada from 2005 on. In GNAT, it is implemented in all versions
[, string_EXPRESSION]);
-The effect of this pragma is identical to that of pragma `Assert`,
-except that in an `Assertion_Policy` pragma, the identifier
-`Assert_And_Cut` is used to control whether it is ignored or checked
+The effect of this pragma is identical to that of pragma ``Assert``,
+except that in an ``Assertion_Policy`` pragma, the identifier
+``Assert_And_Cut`` is used to control whether it is ignored or checked
(or disabled).
The intention is that this be used within a subprogram when the
This is a standard Ada 2012 pragma that is available as an
implementation-defined pragma in earlier versions of Ada.
-The assertion kinds `RM_ASSERTION_KIND` are those defined in
-the Ada standard. The assertion kinds `ID_ASSERTION_KIND`
+The assertion kinds ``RM_ASSERTION_KIND`` are those defined in
+the Ada standard. The assertion kinds ``ID_ASSERTION_KIND``
are implementation defined additions recognized by the GNAT compiler.
The pragma applies in both cases to pragmas and aspects with matching
-names, e.g. `Pre` applies to the Pre aspect, and `Precondition`
-applies to both the `Precondition` pragma
-and the aspect `Precondition`. Note that the identifiers for
+names, e.g. ``Pre`` applies to the Pre aspect, and ``Precondition``
+applies to both the ``Precondition`` pragma
+and the aspect ``Precondition``. Note that the identifiers for
pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not
Pre_Class and Post_Class), since these pragmas are intended to be
identical to the corresponding aspects).
-If the policy is `CHECK`, then assertions are enabled, i.e.
+If the policy is ``CHECK``, then assertions are enabled, i.e.
the corresponding pragma or aspect is activated.
-If the policy is `IGNORE`, then assertions are ignored, i.e.
+If the policy is ``IGNORE``, then assertions are ignored, i.e.
the corresponding pragma or aspect is deactivated.
This pragma overrides the effect of the *-gnata* switch on the
command line.
-If the policy is `SUPPRESSIBLE`, then assertions are enabled by default,
+If the policy is ``SUPPRESSIBLE``, then assertions are enabled by default,
however, if the *-gnatp* switch is specified all assertions are ignored.
-The implementation defined policy `DISABLE` is like
-`IGNORE` except that it completely disables semantic
+The implementation defined policy ``DISABLE`` is like
+``IGNORE`` except that it completely disables semantic
checking of the corresponding pragma or aspect. This is
useful when the pragma or aspect argument references subprograms
in a with'ed package which is replaced by a dummy package
for the final build.
-The implementation defined assertion kind `Assertions` applies to all
+The implementation defined assertion kind ``Assertions`` applies to all
assertion kinds. The form with no assertion kind given implies this
choice, so it applies to all assertion kinds (RM defined, and
implementation defined).
-The implementation defined assertion kind `Statement_Assertions`
-applies to `Assert`, `Assert_And_Cut`,
-`Assume`, `Loop_Invariant`, and `Loop_Variant`.
+The implementation defined assertion kind ``Statement_Assertions``
+applies to ``Assert``, ``Assert_And_Cut``,
+``Assume``, ``Loop_Invariant``, and ``Loop_Variant``.
Pragma Assume
=============
[, string_EXPRESSION]);
-The effect of this pragma is identical to that of pragma `Assert`,
-except that in an `Assertion_Policy` pragma, the identifier
-`Assume` is used to control whether it is ignored or checked
+The effect of this pragma is identical to that of pragma ``Assert``,
+except that in an ``Assertion_Policy`` pragma, the identifier
+``Assume`` is used to control whether it is ignored or checked
(or disabled).
The intention is that this be used for assumptions about the
or informally that the condition is met, this must be
established by examining things outside the program itself.
For example, we may have code that depends on the size of
-`Long_Long_Integer` being at least 64. So we could write:
+``Long_Long_Integer`` being at least 64. So we could write:
.. code-block:: ada
if V1 and V2 have valid values, then the loop is known at compile
time not to execute since the lower bound must be greater than the
upper bound. However in default mode, no such assumption is made,
-and the loop may execute. If `Assume_No_Invalid_Values (On)`
+and the loop may execute. If ``Assume_No_Invalid_Values (On)``
is given, the compiler will assume that any occurrence of a variable
-other than in an explicit `'Valid` test always has a valid
+other than in an explicit ``'Valid`` test always has a valid
value, and the loop above will be optimized away.
-The use of `Assume_No_Invalid_Values (On)` is appropriate if
+The use of ``Assume_No_Invalid_Values (On)`` is appropriate if
you know your code is free of uninitialized variables and other
possible sources of invalid representations, and may result in
more efficient code. A program that accesses an invalid representation
pragma Asynch_Readers [ (boolean_EXPRESSION) ];
-For the semantics of this pragma, see the entry for aspect `Async_Readers` in
+For the semantics of this pragma, see the entry for aspect ``Async_Readers`` in
the SPARK 2014 Reference Manual, section 7.1.2.
.. _Pragma-Async_Writers:
pragma Asynch_Writers [ (boolean_EXPRESSION) ];
-For the semantics of this pragma, see the entry for aspect `Async_Writers` in
+For the semantics of this pragma, see the entry for aspect ``Async_Writers`` in
the SPARK 2014 Reference Manual, section 7.1.2.
Pragma Attribute_Definition
[Expression =>] EXPRESSION | NAME);
-If `Attribute` is a known attribute name, this pragma is equivalent to
+If ``Attribute`` is a known attribute name, this pragma is equivalent to
the attribute definition clause:
for Entity'Attribute use Expression;
-If `Attribute` is not a recognized attribute name, the pragma is
+If ``Attribute`` is not a recognized attribute name, the pragma is
ignored, and a warning is emitted. This allows source
code to be written that takes advantage of some new attribute, while remaining
compilable with earlier compilers.
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 `C_Pass_By_Copy` to change
+B.3(69). Use the configuration pragma ``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:
*
The size of the record type does not exceed the value specified for
- `Max_Size`.
+ ``Max_Size``.
*
- The record type has `Convention C`.
+ The record type has ``Convention C``.
*
The formal parameter has this record type, and the subprogram has a
foreign (non-Ada) convention.
C prototype is a struct (rather than a pointer to a struct).
You can also pass records by copy by specifying the convention
-`C_Pass_By_Copy` for the record type, or by using the extended
-`Import` and `Export` pragmas, which allow specification of
+``C_Pass_By_Copy`` for the record type, or by using the extended
+``Import`` and ``Export`` pragmas, which allow specification of
passing mechanisms on a parameter by parameter basis.
Pragma Check
Invariant'Class
-This pragma is similar to the predefined pragma `Assert` except that an
+This pragma is similar to the predefined pragma ``Assert`` except that an
extra identifier argument is present. In conjunction with pragma
-`Check_Policy`, this can be used to define groups of assertions that can
-be independently controlled. The identifier `Assertion` is special, it
-refers to the normal set of pragma `Assert` statements.
+``Check_Policy``, this can be used to define groups of assertions that can
+be independently controlled. The identifier ``Assertion`` is special, it
+refers to the normal set of pragma ``Assert`` statements.
Checks introduced by this pragma are normally deactivated by default. They can
be activated either by the command line option *-gnata*, which turns on
-all checks, or individually controlled using pragma `Check_Policy`.
+all checks, or individually controlled using pragma ``Check_Policy``.
-The identifiers `Assertions` and `Statement_Assertions` are not
+The identifiers ``Assertions`` and ``Statement_Assertions`` are not
permitted as check kinds, since this would cause confusion with the use
-of these identifiers in `Assertion_Policy` and `Check_Policy`
+of these identifiers in ``Assertion_Policy`` and ``Check_Policy``
pragmas, where they are used to refer to sets of assertions.
Pragma Check_Float_Overflow
pragma Check_Float_Overflow;
-In Ada, the predefined floating-point types (`Short_Float`,
-`Float`, `Long_Float`, `Long_Long_Float`) are
+In Ada, the predefined floating-point types (``Short_Float``,
+``Float``, ``Long_Float``, ``Long_Long_Float``) are
defined to be *unconstrained*. This means that even though each
has a well-defined base range, an operation that delivers a result
outside this base range is not required to raise an exception.
subtype My_Float is Float range Float'Range;
-Here `My_Float` has the same range as
-`Float` but is constrained, so operations on
-`My_Float` values will be checked for overflow
+Here ``My_Float`` has the same range as
+``Float`` but is constrained, so operations on
+``My_Float`` values will be checked for overflow
against this range.
This style will achieve the desired goal, but
it is often more convenient to be able to simply use
the standard predefined floating-point types as long
as overflow checking could be guaranteed.
-The `Check_Float_Overflow`
+The ``Check_Float_Overflow``
configuration pragma achieves this effect. If a unit is compiled
subject to this configuration pragma, then all operations
on predefined floating-point types including operations on
base types of these floating-point types will be treated as
though those types were constrained, and overflow checks
-will be generated. The `Constraint_Error`
+will be generated. The ``Constraint_Error``
exception is raised if the result is out of range.
This mode can also be set by use of the compiler
check name is introduced.
An implementation defined check name introduced with this pragma may
-be used in only three contexts: `pragma Suppress`,
-`pragma Unsuppress`,
-and as the prefix of a `Check_Name'Enabled` attribute reference. For
+be used in only three contexts: ``pragma Suppress``,
+``pragma Unsuppress``,
+and as the prefix of a ``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 `with` clauses).
+are mentioned in ``with`` clauses).
Check names introduced by this pragma are subject to control by compiler
switches (in particular -gnatp) in the usual manner.
This pragma is used to set the checking policy for assertions (specified
-by aspects or pragmas), the `Debug` pragma, or additional checks
-to be checked using the `Check` pragma. It may appear either as
+by aspects or pragmas), the ``Debug`` pragma, or additional checks
+to be checked using the ``Check`` pragma. It may appear either as
a configuration pragma, or within a declarative part of package. In the
latter case, it applies from the point where it appears to the end of
-the declarative region (like pragma `Suppress`).
+the declarative region (like pragma ``Suppress``).
-The `Check_Policy` pragma is similar to the
-predefined `Assertion_Policy` pragma,
+The ``Check_Policy`` pragma is similar to the
+predefined ``Assertion_Policy`` pragma,
and if the check kind corresponds to one of the assertion kinds that
-are allowed by `Assertion_Policy`, then the effect is identical.
+are allowed by ``Assertion_Policy``, then the effect is identical.
If the first argument is Debug, then the policy applies to Debug pragmas,
-disabling their effect if the policy is `OFF`, `DISABLE`, or
-`IGNORE`, and allowing them to execute with normal semantics if
-the policy is `ON` or `CHECK`. In addition if the policy is
-`DISABLE`, then the procedure call in `Debug` pragmas will
+disabling their effect if the policy is ``OFF``, ``DISABLE``, or
+``IGNORE``, and allowing them to execute with normal semantics if
+the policy is ``ON`` or ``CHECK``. In addition if the policy is
+``DISABLE``, then the procedure call in ``Debug`` pragmas will
be totally ignored and not analyzed semantically.
Finally the first argument may be some other identifier than the above
possibilities, in which case it controls a set of named assertions
-that can be checked using pragma `Check`. For example, if the pragma:
+that can be checked using pragma ``Check``. For example, if the pragma:
.. code-block:: ada
pragma Check_Policy (Critical_Error, OFF);
-is given, then subsequent `Check` pragmas whose first argument is also
-`Critical_Error` will be disabled.
+is given, then subsequent ``Check`` pragmas whose first argument is also
+``Critical_Error`` will be disabled.
-The check policy is `OFF` to turn off corresponding checks, and `ON`
+The check policy is ``OFF`` to turn off corresponding checks, and ``ON``
to turn on corresponding checks. The default for a set of checks for which no
-`Check_Policy` is given is `OFF` unless the compiler switch
+``Check_Policy`` is given is ``OFF`` unless the compiler switch
*-gnata* is given, which turns on all checks by default.
-The check policy settings `CHECK` and `IGNORE` are recognized
-as synonyms for `ON` and `OFF`. These synonyms are provided for
-compatibility with the standard `Assertion_Policy` pragma. The check
-policy setting `DISABLE` causes the second argument of a corresponding
-`Check` pragma to be completely ignored and not analyzed.
+The check policy settings ``CHECK`` and ``IGNORE`` are recognized
+as synonyms for ``ON`` and ``OFF``. These synonyms are provided for
+compatibility with the standard ``Assertion_Policy`` pragma. The check
+policy setting ``DISABLE`` causes the second argument of a corresponding
+``Check`` pragma to be completely ignored and not analyzed.
Pragma Comment
==============
pragma Comment (static_string_EXPRESSION);
-This is almost identical in effect to pragma `Ident`. It allows the
+This is almost identical in effect to pragma ``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 `Comment`, unlike `Ident`, has
+difference is that ``Comment``, unlike ``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.
This pragma enables the shared use of variables stored in overlaid
-linker areas corresponding to the use of `COMMON`
+linker areas corresponding to the use of ``COMMON``
in Fortran. The single
-object `LOCAL_NAME` is assigned to the area designated by
-the `External` argument.
+object ``LOCAL_NAME`` is assigned to the area designated by
+the ``External`` argument.
You may define a record to correspond to a series
-of fields. The `Size` argument
+of fields. The ``Size`` argument
is syntax checked in GNAT, but otherwise ignored.
-`Common_Object` is not supported on all platforms. If no
+``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.
([Entity =>] LOCAL_NAME);
-The `Entity` argument must be the name of a record type which has
+The ``Entity`` argument must be the name of a record type which has
two fields of the same floating-point type. The effect of this pragma is
to force gcc to use the special internal complex representation form for
this record, which may be more efficient. Note that this may result in
Specifies the alignment of components in array or record types.
-The meaning of the `Form` argument is as follows:
+The meaning of the ``Form`` argument is as follows:
.. index:: Component_Size (in pragma Component_Alignment)
*Storage_Unit*
Specifies that array or record components are byte aligned, i.e.,
aligned on boundaries determined by the value of the constant
- `System.Storage_Unit`.
+ ``System.Storage_Unit``.
.. index:: Default (in pragma Component_Alignment)
*Default*
Specifies that array or record components are aligned on default
boundaries, appropriate to the underlying hardware or operating system or
- both. The `Default` choice is the same as `Component_Size` (natural
+ both. The ``Default`` choice is the same as ``Component_Size`` (natural
alignment).
-If the `Name` parameter is present, `type_LOCAL_NAME` must
+If the ``Name`` parameter is present, ``type_LOCAL_NAME`` must
refer to a local record or array type, and the specified alignment
choice applies to the specified type. The use of
-`Component_Alignment` together with a pragma `Pack` causes the
-`Component_Alignment` pragma to be ignored. The use of
-`Component_Alignment` together with a record representation clause
+``Component_Alignment`` together with a pragma ``Pack`` causes the
+``Component_Alignment`` pragma to be ignored. The use of
+``Component_Alignment`` together with a record representation clause
is only effective for fields not specified by the representation clause.
-If the `Name` parameter is absent, the pragma can be used as either
+If the ``Name`` parameter is absent, the pragma can be used as either
a configuration pragma, in which case it applies to one or more units in
accordance with the normal rules for configuration pragmas, or it can be
used within a declarative part, in which case it applies to types that
representation.
If the alignment for a record or array type is not specified (using
-pragma `Pack`, pragma `Component_Alignment`, or a record rep
+pragma ``Pack``, pragma ``Component_Alignment``, or a record rep
clause), the GNAT uses the default alignment as described previously.
.. _Pragma-Constant_After_Elaboration:
pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ];
For the semantics of this pragma, see the entry for aspect
-`Constant_After_Elaboration` in the SPARK 2014 Reference Manual, section 3.3.1.
+``Constant_After_Elaboration`` in the SPARK 2014 Reference Manual, section 3.3.1.
.. _Pragma-Contract_Cases:
CONSEQUENCE ::= boolean_EXPRESSION
-The `Contract_Cases` pragma allows defining fine-grain specifications
+The ``Contract_Cases`` pragma allows defining fine-grain specifications
that can complement or replace the contract given by a precondition and a
-postcondition. Additionally, the `Contract_Cases` pragma can be used
+postcondition. Additionally, the ``Contract_Cases`` pragma can be used
by testing and formal verification tools. The compiler checks its validity and,
depending on the assertion policy at the point of declaration of the pragma,
it may insert a check in the executable. For code generation, the contract
the corrresponding consequence is True on exit. Other consequence expressions
are not evaluated.
-A precondition `P` and postcondition `Q` can also be
+A precondition ``P`` and postcondition ``Q`` can also be
expressed as contract cases:
.. code-block:: ada
pragma Contract_Cases (P => Q);
-The placement and visibility rules for `Contract_Cases` pragmas are
+The placement and visibility rules for ``Contract_Cases`` pragmas are
identical to those described for preconditions and postconditions.
The compiler checks that boolean expressions given in conditions and
consequences are valid, where the rules for conditions are the same as
-the rule for an expression in `Precondition` and the rules for
+the rule for an expression in ``Precondition`` and the rules for
consequences are the same as the rule for an expression in
-`Postcondition`. In particular, attributes `'Old` and
-`'Result` can only be used within consequence expressions.
-The condition for the last contract case may be `others`, to denote
+``Postcondition``. In particular, attributes ``'Old`` and
+``'Result`` can only be used within consequence expressions.
+The condition for the last contract case may be ``others``, to denote
any case not captured by the previous cases. The
following is an example of use within a package spec:
This pragma provides a mechanism for supplying synonyms for existing
-convention identifiers. The `Name` identifier can subsequently
+convention identifiers. The ``Name`` identifier can subsequently
be used as a synonym for the given convention in other pragmas (including
-for example pragma `Import` or another `Convention_Identifier`
+for example pragma ``Import`` or another ``Convention_Identifier``
pragma). As an example of the use of this, suppose you had legacy code
which used Fortran77 as the identifier for Fortran. Then the pragma:
pragma Convention_Identifier (Fortran77, Fortran);
-would allow the use of the convention identifier `Fortran77` in
+would allow the use of the convention identifier ``Fortran77`` in
subsequent code, avoiding the need to modify the sources. As another
example, you could use this to parameterize convention requirements
-according to systems. Suppose you needed to use `Stdcall` on
-windows systems, and `C` on some other system, then you could
-define a convention identifier `Library` and use a single
-`Convention_Identifier` pragma to specify which convention
+according to systems. Suppose you needed to use ``Stdcall`` on
+windows systems, and ``C`` on some other system, then you could
+define a convention identifier ``Library`` and use a single
+``Convention_Identifier`` pragma to specify which convention
would be used system-wide.
Pragma CPP_Class
that C++ would lay out the type. If the C++ class has virtual primitives
then the record must be declared as a tagged record type.
-Types for which `CPP_Class` is specified do not have assignment or
+Types for which ``CPP_Class`` is specified do not have assignment or
equality operators defined (such operations can be imported or declared
as subprograms as required). Initialization is allowed only by constructor
-functions (see pragma `CPP_Constructor`). Such types are implicitly
+functions (see pragma ``CPP_Constructor``). Such types are implicitly
limited if not explicitly declared as limited or derived from a limited
type, and an error is issued in that case.
See :ref:`Interfacing_to_C++` for related information.
-Note: Pragma `CPP_Class` is currently obsolete. It is supported
+Note: Pragma ``CPP_Class`` is currently obsolete. It is supported
for backward compatibility but its functionality is available
-using pragma `Import` with `Convention` = `CPP`.
+using pragma ``Import`` with ``Convention`` = ``CPP``.
Pragma CPP_Constructor
======================
This pragma identifies an imported function (imported in the usual way
-with pragma `Import`) as corresponding to a C++ constructor. If
-`External_Name` and `Link_Name` are not specified then the
-`Entity` argument is a name that must have been previously mentioned
-in a pragma `Import` with `Convention` = `CPP`. Such name
+with pragma ``Import``) as corresponding to a C++ constructor. If
+``External_Name`` and ``Link_Name`` are not specified then the
+``Entity`` argument is a name that must have been previously mentioned
+in a pragma ``Import`` with ``Convention`` = ``CPP``. Such name
must be of one of the following forms:
*
- **function** `Fname` **return** T`
+ **function** ``Fname`` **return** T`
*
- **function** `Fname` **return** T'Class
+ **function** ``Fname`` **return** T'Class
*
- **function** `Fname` (...) **return** T`
+ **function** ``Fname`` (...) **return** T`
*
- **function** `Fname` (...) **return** T'Class
+ **function** ``Fname`` (...) **return** T'Class
-where `T` is a limited record type imported from C++ with pragma
-`Import` and `Convention` = `CPP`.
+where ``T`` is a limited record type imported from C++ with pragma
+``Import`` and ``Convention`` = ``CPP``.
The first two forms import the default constructor, used when an object
-of type `T` is created on the Ada side with no explicit constructor.
+of type ``T`` is created on the Ada side with no explicit constructor.
The latter two forms cover all the non-default constructors of the type.
See the GNAT User's Guide for details.
If no constructors are imported, it is impossible to create any objects
on the Ada side and the type is implicitly declared abstract.
-Pragma `CPP_Constructor` is intended primarily for automatic generation
-using an automatic binding generator tool (such as the `-fdump-ada-spec`
+Pragma ``CPP_Constructor`` is intended primarily for automatic generation
+using an automatic binding generator tool (such as the :switch:`-fdump-ada-spec`
GCC switch).
See :ref:`Interfacing_to_C++` for more related information.
pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ];
For the semantics of this pragma, see the entry for aspect
-`Default_Initial_Condition` in the SPARK 2014 Reference Manual, section 7.3.3.
+``Default_Initial_Condition`` in the SPARK 2014 Reference Manual, section 7.3.3.
Pragma Debug
============
to False, this pragma has no effect. If debug pragmas are enabled, the
semantics of the pragma is exactly equivalent to the procedure call statement
corresponding to the argument with a terminating semicolon. Pragmas are
-permitted in sequences of declarations, so you can use pragma `Debug` to
+permitted in sequences of declarations, so you can use pragma ``Debug`` to
intersperse calls to debug procedures in the middle of declarations. Debug
pragmas can be enabled either by use of the command line switch *-gnata*
-or by use of the pragma `Check_Policy` with a first argument of
-`Debug`.
+or by use of the pragma ``Check_Policy`` with a first argument of
+``Debug``.
Pragma Debug_Policy
===================
pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF);
-This pragma is equivalent to a corresponding `Check_Policy` pragma
-with a first argument of `Debug`. It is retained for historical
+This pragma is equivalent to a corresponding ``Check_Policy`` pragma
+with a first argument of ``Debug``. It is retained for historical
compatibility reasons.
Pragma Default_Scalar_Storage_Order
pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First);
-Normally if no explicit `Scalar_Storage_Order` is given for a record
+Normally if no explicit ``Scalar_Storage_Order`` is given for a record
type or array type, then the scalar storage order defaults to the ordinary
default for the target. But this default may be overridden using this pragma.
The pragma may appear as a configuration pragma, or locally within a package
end DSSO1;
-In this example record types L.. have `Low_Order_First` scalar
-storage order, and record types H.. have `High_Order_First`.
-Note that in the case of `H4a`, the order is not inherited
-from the parent type. Only an explicitly set `Scalar_Storage_Order`
+In this example record types with names starting with *L* have `Low_Order_First` scalar
+storage order, and record types with names starting with *H* have ``High_Order_First``.
+Note that in the case of ``H4a``, the order is not inherited
+from the parent type. Only an explicitly set ``Scalar_Storage_Order``
gets inherited on type derivation.
If this pragma is used as a configuration pragma which appears within a
where FUNCTION_RESULT is a function Result attribute_reference
-For the semantics of this pragma, see the entry for aspect `Depends` in the
+For the semantics of this pragma, see the entry for aspect ``Depends`` in the
SPARK 2014 Reference Manual, section 6.1.5.
Pragma Detect_Blocking
required.
The placement and scope rules for this pragma are the same as those
-for `pragma Suppress`. In particular it can be used as a
+for ``pragma Suppress``. In particular it can be used as a
configuration pragma, or in a declaration sequence where it applies
-till the end of the scope. If an `Entity` argument is present,
+till the end of the scope. If an ``Entity`` argument is present,
the action applies only to that entity.
Pragma Dispatching_Domain
pragma Effective_Reads [ (boolean_EXPRESSION) ];
-For the semantics of this pragma, see the entry for aspect `Effective_Reads` in
+For the semantics of this pragma, see the entry for aspect ``Effective_Reads`` in
the SPARK 2014 Reference Manual, section 7.1.2.
.. _Pragma-Effective_Writes:
pragma Effective_Writes [ (boolean_EXPRESSION) ];
-For the semantics of this pragma, see the entry for aspect `Effective_Writes`
+For the semantics of this pragma, see the entry for aspect ``Effective_Writes``
in the SPARK 2014 Reference Manual, section 7.1.2.
Pragma Elaboration_Checks
This is a configuration pragma that provides control over the
elaboration model used by the compilation affected by the
-pragma. If the parameter is `Dynamic`,
+pragma. If the parameter is ``Dynamic``,
then the dynamic elaboration
model described in the Ada Reference Manual is used, as though
the *-gnatE* switch had been specified on the command
-line. If the parameter is `Static`, then the default GNAT static
+line. If the parameter is ``Static``, then the default GNAT static
model is used. This configuration pragma overrides the setting
of the command line. For full details on the elaboration models
used by the GNAT compiler, see the chapter on elaboration order handling
in the *GNAT User's Guide*.
+
Pragma Eliminate
================
.. index:: Elimination of unused subprograms
::
- pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR,
- [Source_Location =>] STRING_LITERAL);
+ pragma Eliminate (
+ [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT ,
+ [ Entity => ] IDENTIFIER |
+ SELECTED_COMPONENT |
+ STRING_LITERAL
+ [, Source_Location => SOURCE_TRACE ] );
+ SOURCE_TRACE ::= STRING_LITERAL
-The string literal given for the source location is a string which
-specifies the line number of the occurrence of the entity, using
-the syntax for SOURCE_TRACE given below:
+This pragma indicates that the given entity is not used in the program to be
+compiled and built, thus allowing the compiler to
+eliminate the code or data associated with the named entity. Any reference to
+an eliminated entity causes a compile-time or link-time error.
-::
+The pragma has the following semantics, where ``U`` is the unit specified by
+the ``Unit_Name`` argument and ``E`` is the entity specified by the ``Entity``
+argument:
- SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET]
+* ``E`` must be a subprogram that is explicitly declared either:
- LBRACKET ::= [
- RBRACKET ::= ]
+ o Within ``U``, or
- SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
+ o Within a generic package that is instantiated in ``U``, or
- LINE_NUMBER ::= DIGIT {DIGIT}
+ o As an instance of generic subprogram instantiated in ``U``.
+ Otherwise the pragma is ignored.
-Spaces around the colon in a `Source_Reference` are optional.
-
-The `DEFINING_DESIGNATOR` matches the defining designator used in an
-explicit subprogram declaration, where the `entity` name in this
-designator appears on the source line specified by the source location.
-
-The source trace that is given as the `Source_Location` shall obey the
-following rules. The `FILE_NAME` is the short name (with no directory
-information) of an Ada source file, given using exactly the required syntax
-for the underlying file system (e.g. case is important if the underlying
-operating system is case sensitive). `LINE_NUMBER` gives the line
-number of the occurrence of the `entity`
-as a decimal literal without an exponent or point. If an `entity` is not
-declared in a generic instantiation (this includes generic subprogram
-instances), the source trace includes only one source reference. If an entity
-is declared inside a generic instantiation, its source trace (when parsing
-from left to right) starts with the source location of the declaration of the
-entity in the generic unit and ends with the source location of the
-instantiation (it is given in square brackets). This approach is recursively
-used in case of nested instantiations: the rightmost (nested most deeply in
-square brackets) element of the source trace is the location of the outermost
-instantiation, the next to left element is the location of the next (first
-nested) instantiation in the code of the corresponding generic unit, and so
-on, and the leftmost element (that is out of any square brackets) is the
-location of the declaration of the entity to eliminate in a generic unit.
-
-Note that the `Source_Location` argument specifies which of a set of
-similarly named entities is being eliminated, dealing both with overloading,
-and also appearance of the same entity name in different scopes.
+* If ``E`` is overloaded within ``U`` then, in the absence of a
+ ``Source_Location`` argument, all overloadings are eliminated.
-This pragma indicates that the given entity is not used in the program to be
-compiled and built. 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 causes a compile-time or link-time error.
+* If ``E`` is overloaded within ``U`` and only some overloadings
+ are to be eliminated, then each overloading to be eliminated
+ must be specified in a corresponding pragma ``Eliminate``
+ with a ``Source_Location`` argument identifying the line where the
+ declaration appears, as described below.
+
+* If ``E`` is declared as the result of a generic instantiation, then
+ a ``Source_Location`` argument is needed, as described below
-The intention of pragma `Eliminate` is to allow a program to be compiled
-in a system-independent manner, with unused entities eliminated, without
+Pragma ``Eliminate`` allows a program to be compiled in a system-independent
+manner, so that unused entities are eliminated but without
needing to modify the source text. Normally the required set of
-`Eliminate` pragmas is constructed automatically using the gnatelim tool.
+``Eliminate`` pragmas is constructed automatically using the ``gnatelim`` tool.
Any source file change that removes, splits, or
-adds lines may make the set of Eliminate pragmas invalid because their
-`Source_Location` argument values may get out of date.
+adds lines may make the set of ``Eliminate`` pragmas invalid because their
+``Source_Location`` argument values may get out of date.
-Pragma `Eliminate` may be used where the referenced entity is a dispatching
+Pragma ``Eliminate`` may be used where the referenced entity is a dispatching
operation. In this case all the subprograms to which the given operation can
dispatch are considered to be unused (are never called as a result of a direct
or a dispatching call).
+The string literal given for the source location specifies the line number
+of the declaration of the entity, using the following syntax for ``SOURCE_TRACE``:
+
+::
+
+ SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ]
+
+ LBRACKET ::= '['
+ RBRACKET ::= ']'
+
+ SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
+
+ LINE_NUMBER ::= DIGIT {DIGIT}
+
+
+Spaces around the colon in a ``SOURCE_REFERENCE`` are optional.
+
+The source trace that is given as the ``Source_Location`` must obey the
+following rules (or else the pragma is ignored), where ``U`` is
+the unit ``U`` specified by the ``Unit_Name`` argument and ``E`` is the
+subprogram specified by the ``Entity`` argument:
+
+* ``FILE_NAME`` is the short name (with no directory
+ information) of the Ada source file for ``U``, using the required syntax
+ for the underlying file system (e.g. case is significant if the underlying
+ operating system is case sensitive).
+ If ``U`` is a package and ``E`` is a subprogram declared in the package
+ specification and its full declaration appears in the package body,
+ then the relevant source file is the one for the package specification;
+ analogously if ``U`` is a generic package.
+
+* If ``E`` is not declared in a generic instantiation (this includes
+ generic subprogram instances), the source trace includes only one source
+ line reference. ``LINE_NUMBER`` gives the line number of the occurrence
+ of the declaration of ``E`` within the source file (as a decimal literal
+ without an exponent or point).
+
+* If ``E`` is declared by a generic instantiation, its source trace
+ (from left to right) starts with the source location of the
+ declaration of ``E`` in the generic unit and ends with the source
+ location of the instantiation, given in square brackets. This approach is
+ applied recursively with nested instantiations: the rightmost (nested
+ most deeply in square brackets) element of the source trace is the location
+ of the outermost instantiation, and the leftmost element (that is, outside
+ of any square brackets) is the location of the declaration of ``E`` in
+ the generic unit.
+
+Examples:
+
+ .. code-block:: ada
+
+ pragma Eliminate (Pkg0, Proc);
+ -- Eliminate (all overloadings of) Proc in Pkg0
+
+ pragma Eliminate (Pkg1, Proc,
+ Source_Location => "pkg1.ads:8");
+ -- Eliminate overloading of Proc at line 8 in pkg1.ads
+
+ -- Assume the following file contents:
+ -- gen_pkg.ads
+ -- 1: generic
+ -- 2: type T is private;
+ -- 3: package Gen_Pkg is
+ -- 4: procedure Proc(N : T);
+ -- ... ...
+ -- ... end Gen_Pkg;
+ --
+ -- q.adb
+ -- 1: with Gen_Pkg;
+ -- 2: procedure Q is
+ -- 3: package Inst_Pkg is new Gen_Pkg(Integer);
+ -- ... -- No calls on Inst_Pkg.Proc
+ -- ... end Q;
+
+ -- The following pragma eliminates Inst_Pkg.Proc from Q
+ pragma Eliminate (Q, Proc,
+ Source_Location => "gen_pkg.ads:4[q.adb:3]");
+
+
+
Pragma Enable_Atomic_Synchronization
====================================
.. index:: Atomic Synchronization
Particularly in the case of multi-processors this may require special
handling, e.g. the generation of memory barriers. This synchronization
is performed by default, but can be turned off using
-`pragma Disable_Atomic_Synchronization`. The
-`Enable_Atomic_Synchronization` pragma can be used to turn
+``pragma Disable_Atomic_Synchronization``. The
+``Enable_Atomic_Synchronization`` pragma can be used to turn
it back on.
The placement and scope rules for this pragma are the same as those
-for `pragma Unsuppress`. In particular it can be used as a
+for ``pragma Unsuppress``. In particular it can be used as a
configuration pragma, or in a declaration sequence where it applies
-till the end of the scope. If an `Entity` argument is present,
+till the end of the scope. If an ``Entity`` argument is present,
the action applies only to that entity.
Pragma Export_Function
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
-`Export`, which must precede the pragma `Export_Function`.
-GNAT does not require a separate pragma `Export`, but if none is
-present, `Convention Ada` is assumed, which is usually
+``Export``, which must precede the pragma ``Export_Function``.
+GNAT does not require a separate pragma ``Export``, but if none is
+present, ``Convention Ada`` is assumed, which is usually
not what is wanted, so it is usually appropriate to use this
-pragma in conjunction with a `Export` or `Convention`
+pragma in conjunction with a ``Export`` or ``Convention``
pragma that specifies the desired foreign convention.
-Pragma `Export_Function`
-(and `Export`, if present) must appear in the same declarative
+Pragma ``Export_Function``
+(and ``Export``, if present) must appear in the same declarative
region as the function to which they apply.
-`internal_name` must uniquely designate the function to which the
+The ``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 `Parameter_Types` and
-`Result_Type` parameters is mandatory to achieve the required
-unique designation. `subtype_mark`s in these parameters must
+the declarative part you must use the ``Parameter_Types`` and
+``Result_Type`` parameters to achieve the required
+unique designation. The `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 `'Access` attribute can be used to match an
+The form with an ``'Access`` attribute can be used to match an
anonymous access parameter.
.. index:: Suppressing external name
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 `Export` pragma applied to an object. You may use a
+the normal ``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. `Size` is syntax checked,
+of portability), but it is not required. ``Size`` is syntax checked,
but otherwise ignored by GNAT.
Pragma Export_Procedure
MECHANISM_NAME ::= Value | Reference
-This pragma is identical to `Export_Function` except that it
+This pragma is identical to ``Export_Function`` except that it
applies to a procedure rather than a function and the parameters
-`Result_Type` and `Result_Mechanism` are not permitted.
-GNAT does not require a separate pragma `Export`, but if none is
-present, `Convention Ada` is assumed, which is usually
+``Result_Type`` and ``Result_Mechanism`` are not permitted.
+GNAT does not require a separate pragma ``Export``, but if none is
+present, ``Convention Ada`` is assumed, which is usually
not what is wanted, so it is usually appropriate to use this
-pragma in conjunction with a `Export` or `Convention`
+pragma in conjunction with a ``Export`` or ``Convention``
pragma that specifies the desired foreign convention.
.. index:: Suppressing external name
MECHANISM_NAME ::= Value | Reference
-This pragma is identical to `Export_Procedure` except that the
-first parameter of `LOCAL_NAME`, which must be present, must be of
-mode `OUT`, and externally the subprogram is treated as a function
+This pragma is identical to ``Export_Procedure`` except that the
+first parameter of ``LOCAL_NAME``, which must be present, must be of
+mode ``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 `OUT` and `IN OUT`
+this capability to allow the use of ``out`` and ``in out``
parameters in interfacing to external functions (which are not permitted
in Ada functions).
-GNAT does not require a separate pragma `Export`, but if none is
-present, `Convention Ada` is assumed, which is almost certainly
+GNAT does not require a separate pragma ``Export``, but if none is
+present, ``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 `Export` or `Convention`
+pragma in conjunction with a ``Export`` or ``Convention``
pragma that specifies the desired foreign convention.
.. index:: Suppressing external name
This pragma is used to provide backwards compatibility with other
-implementations that extend the facilities of package `System`. In
-GNAT, `System` contains only the definitions that are present in
+implementations that extend the facilities of package ``System``. In
+GNAT, ``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 `System`.
+implementation, provide many extensions to package ``System``.
For each such implementation accommodated by this pragma, GNAT provides a
-package `Aux_`xxx``, e.g., `Aux_DEC` for the DEC Ada 83
+package :samp:`Aux_{xxx}`, e.g., ``Aux_DEC`` for the DEC Ada 83
implementation, which provides the required additional definitions. You
-can use this package in two ways. You can `with` it in the normal
-way and access entities either by selection or using a `use`
+can use this package in two ways. You can ``with`` it in the normal
+way and access entities either by selection or using a ``use``
clause. In this case no special processing is required.
However, if existing code contains references such as
-`System.`xxx`` where `xxx` is an entity in the extended
-definitions provided in package `System`, you may use this pragma
-to extend visibility in `System` in a non-standard way that
+:samp:`System.{xxx}` where *xxx* is an entity in the extended
+definitions provided in package ``System``, you may use this pragma
+to extend visibility in ``System`` in a non-standard way that
provides greater compatibility with the existing code. Pragma
-`Extend_System` is a configuration pragma whose single argument is
+``Extend_System`` is a configuration pragma whose single argument is
the name of the package containing the extended definition
-(e.g., `Aux_DEC` for the DEC Ada case). A unit compiled under
+(e.g., ``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 `System.Aux_`xxx`` where
-`Aux_`xxx`` is the pragma argument for any entity referenced in
-package `System`, but not found in package `System`.
+processing that looks in package :samp:`System.Aux_{xxx}` where
+:samp:`Aux_{xxx}` is the pragma argument for any entity referenced in
+package ``System``, but not found in package ``System``.
-You can use this pragma either to access a predefined `System`
-extension supplied with the compiler, for example `Aux_DEC` or
+You can use this pragma either to access a predefined ``System``
+extension supplied with the compiler, for example ``Aux_DEC`` or
you can construct your own extension unit following the above
-definition. Note that such a package is a child of `System`
+definition. Note that such a package is a child of ``System``
and thus is considered part of the implementation.
To compile it you will have to use the *-gnatg* switch
for compiling System units, as explained in the
*Constrained attribute for generic objects*
- The `Constrained` attribute is permitted for objects of
+ The ``Constrained`` attribute is permitted for objects of
generic types. The result indicates if the corresponding actual
is constrained.
pragma Extensions_Visible [ (boolean_EXPRESSION) ];
-For the semantics of this pragma, see the entry for aspect `Extensions_Visible`
+For the semantics of this pragma, see the entry for aspect ``Extensions_Visible``
in the SPARK 2014 Reference Manual, section 6.1.7.
Pragma External
This pragma is identical in syntax and semantics to pragma
-`Export` as defined in the Ada Reference Manual. It is
+``Export`` as defined in the Ada Reference Manual. It is
provided for compatibility with some Ada 83 compilers that
used this pragma for exactly the same purposes as pragma
-`Export` before the latter was standardized.
+``Export`` before the latter was standardized.
Pragma External_Name_Casing
===========================
casing of the external name, and so a convention is needed. In GNAT the
default treatment is that such names are converted to all lower case
letters. This corresponds to the normal C style in many environments.
- The first argument of pragma `External_Name_Casing` can be used to
- control this treatment. If `Uppercase` is specified, then the name
- will be forced to all uppercase letters. If `Lowercase` is specified,
+ The first argument of pragma ``External_Name_Casing`` can be used to
+ control this treatment. If ``Uppercase`` is specified, then the name
+ will be forced to all uppercase letters. If ``Lowercase`` is specified,
then the normal default of all lower case letters will be used.
This same implicit treatment is also used in the case of extended DEC Ada 83
In this case, the string literal normally provides the exact casing required
for the external name. The second argument of pragma
- `External_Name_Casing` may be used to modify this behavior.
- If `Uppercase` is specified, then the name
- will be forced to all uppercase letters. If `Lowercase` is specified,
+ ``External_Name_Casing`` may be used to modify this behavior.
+ If ``Uppercase`` is specified, then the name
+ will be forced to all uppercase letters. If ``Lowercase`` is specified,
then the name will be forced to all lowercase letters. A specification of
- `As_Is` provides the normal default behavior in which the casing is
+ ``As_Is`` provides the normal default behavior in which the casing is
taken from the string provided.
This pragma may appear anywhere that a pragma is valid. In particular, it
overflows for numbers near the end of the range. The Ada standard requires that
this situation be detected and corrected by scaling, but in Fast_Math mode such
cases will simply result in overflow. Note that to take advantage of this you
- must instantiate your own version of `Ada.Numerics.Generic_Complex_Types`
+ must instantiate your own version of ``Ada.Numerics.Generic_Complex_Types``
under control of the pragma, rather than use the preinstantiated versions.
.. _Pragma-Favor_Top_Level:
pragma Favor_Top_Level (type_NAME);
-The argument of pragma `Favor_Top_Level` must be a named access-to-subprogram
+The argument of pragma ``Favor_Top_Level`` must be a named access-to-subprogram
type. This pragma is an efficiency hint to the compiler, regarding the use of
-`'Access` or `'Unrestricted_Access` on nested (non-library-level) subprograms.
+``'Access`` or ``'Unrestricted_Access`` on nested (non-library-level) subprograms.
The pragma means that nested subprograms are not used with this type, or are
rare, so that the generated code should be efficient in the top-level case.
When this pragma is used, dynamically generated trampolines may be used on some
-targets for nested subprograms. See restriction `No_Implicit_Dynamic_Code`.
+targets for nested subprograms. See restriction ``No_Implicit_Dynamic_Code``.
Pragma Finalize_Storage_Only
============================
pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
-The argument of pragma `Finalize_Storage_Only` must denote a local type which
-is derived from `Ada.Finalization.Controlled` or `Limited_Controlled`. The
-pragma suppresses the call to `Finalize` for declared library-level objects
+The argument of pragma ``Finalize_Storage_Only`` must denote a local type which
+is derived from ``Ada.Finalization.Controlled`` or ``Limited_Controlled``. The
+pragma suppresses the call to ``Finalize`` for declared library-level objects
of the argument type. This is mostly useful for types where finalization is
only used to deal with storage reclamation since in most environments it is
not necessary to reclaim memory just before terminating execution, hence the
name. Note that this pragma does not suppress Finalize calls for library-level
-heap-allocated objects (see pragma `No_Heap_Finalization`).
+heap-allocated objects (see pragma ``No_Heap_Finalization``).
Pragma Float_Representation
===========================
In the one argument form, this pragma is a configuration pragma which
allows control over the internal representation chosen for the predefined
-floating point types declared in the packages `Standard` and
-`System`. This pragma is only provided for compatibility and has no effect.
+floating point types declared in the packages ``Standard`` and
+``System``. This pragma is only provided for compatibility and has no effect.
The two argument form specifies the representation to be used for
the specified floating-point type. The argument must
-be `IEEE_Float` to specify the use of IEEE format, as follows:
+be ``IEEE_Float`` to specify the use of IEEE format, as follows:
*
For a digits value of 6, 32-bit IEEE short format will be used.
pragma Ghost [ (boolean_EXPRESSION) ];
-For the semantics of this pragma, see the entry for aspect `Ghost` in the SPARK
+For the semantics of this pragma, see the entry for aspect ``Ghost`` in the SPARK
2014 Reference Manual, section 6.9.
.. _Pragma-Global:
GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM {, GLOBAL_ITEM})
GLOBAL_ITEM ::= NAME
-For the semantics of this pragma, see the entry for aspect `Global` in the
+For the semantics of this pragma, see the entry for aspect ``Global`` in the
SPARK 2014 Reference Manual, section 6.1.4.
Pragma Ident
pragma Ident (static_string_EXPRESSION);
-This pragma is identical in effect to pragma `Comment`. It is provided
+This pragma is identical in effect to pragma ``Comment``. It is provided
for compatibility with other Ada compilers providing this pragma.
Pragma Ignore_Pragma
use of a pragma whose pragma identifier matches this argument will be
silently ignored. This may be useful when legacy code or code intended
for compilation with some other compiler contains pragmas that match the
-name, but not the exact implementation, of a `GNAT` pragma. The use of this
-pragma allows such pragmas to be ignored, which may be useful in `CodePeer`
+name, but not the exact implementation, of a GNAT pragma. The use of this
+pragma allows such pragmas to be ignored, which may be useful in CodePeer
mode, or during porting of legacy code.
Pragma Implementation_Defined
| Reference
-This pragma is used in conjunction with a pragma `Import` to
+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
+``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 ``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
+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
+The form with an ``'Access`` attribute can be used to match an
anonymous access parameter.
-You may optionally use the `Mechanism` and `Result_Mechanism`
+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
This pragma designates an object as imported, and apart from the
extended rules for external symbols, is identical in effect to the use of
-the normal `Import` pragma applied to an object. Unlike the
-subprogram case, you need not use a separate `Import` pragma,
+the normal ``Import`` pragma applied to an object. Unlike the
+subprogram case, you need not use a separate ``Import`` pragma,
although you may do so (and probably should do so from a portability
-point of view). `size` is syntax checked, but otherwise ignored by
+point of view). ``size`` is syntax checked, but otherwise ignored by
GNAT.
Pragma Import_Procedure
MECHANISM_NAME ::= Value | Reference
-This pragma is identical to `Import_Function` except that it
+This pragma is identical to ``Import_Function`` except that it
applies to a procedure rather than a function and the parameters
-`Result_Type` and `Result_Mechanism` are not permitted.
+``Result_Type`` and ``Result_Mechanism`` are not permitted.
Pragma Import_Valued_Procedure
==============================
MECHANISM_NAME ::= Value | Reference
-This pragma is identical to `Import_Procedure` except that the
-first parameter of `LOCAL_NAME`, which must be present, must be of
-mode `OUT`, and externally the subprogram is treated as a function
+This pragma is identical to ``Import_Procedure`` except that the
+first parameter of ``LOCAL_NAME``, which must be present, must be of
+mode ``out``, and externally the subprogram is treated as a function
with this parameter as the result of the function. The purpose of this
-capability is to allow the use of `OUT` and `IN OUT`
+capability is to allow the use of ``out`` and ``in out``
parameters in interfacing to external functions (which are not permitted
-in Ada functions). You may optionally use the `Mechanism`
+in Ada functions). You may optionally use the ``Mechanism``
parameters to specify passing mechanisms for the parameters.
If you specify a single mechanism name, it applies to all parameters.
Otherwise you may specify a mechanism on a parameter by parameter
pragma Initial_Condition (boolean_EXPRESSION);
-For the semantics of this pragma, see the entry for aspect `Initial_Condition`
+For the semantics of this pragma, see the entry for aspect ``Initial_Condition``
in the SPARK 2014 Reference Manual, section 7.1.6.
Pragma Initialize_Scalars
pragma Initialize_Scalars;
-This pragma is similar to `Normalize_Scalars` conceptually but has
+This pragma is similar to ``Normalize_Scalars`` conceptually but has
two important differences. First, there is no requirement for the pragma
to be used uniformly in all units of a partition, in particular, it is fine
to use this just for some or all of the application units of a partition,
the need to rebind with a different switch using an environment variable.
See the GNAT User's Guide for details.
-Note that pragma `Initialize_Scalars` is particularly useful in
+Note that pragma ``Initialize_Scalars`` is particularly useful in
conjunction with the enhanced validity checking that is now provided
in GNAT, which checks for invalid values under more conditions.
Using this feature (see description of the *-gnatV* flag in the
GNAT User's Guide) in conjunction with
-pragma `Initialize_Scalars`
+pragma ``Initialize_Scalars``
provides a powerful new tool to assist in the detection of problems
caused by uninitialized variables.
-Note: the use of `Initialize_Scalars` has a fairly extensive
+Note: the use of ``Initialize_Scalars`` has a fairly extensive
effect on the generated code. This may cause your code to be
substantially larger. It may also cause an increase in the amount
of stack required, so it is probably a good idea to turn on stack
INPUT ::= name
-For the semantics of this pragma, see the entry for aspect `Initializes` in the
+For the semantics of this pragma, see the entry for aspect ``Initializes`` in the
SPARK 2014 Reference Manual, section 7.1.5.
.. _Pragma-Inline_Always:
pragma Inline_Always (NAME [, NAME]);
-Similar to pragma `Inline` except that inlining is unconditional.
+Similar to pragma ``Inline`` except that inlining is unconditional.
Inline_Always instructs the compiler to inline every direct call to the
subprogram or else to emit a compilation error, independently of any
option, in particular *-gnatn* or *-gnatN* or the optimization level.
-It is an error to take the address or access of `NAME`. It is also an error to
+It is an error to take the address or access of ``NAME``. It is also an error to
apply this pragma to a primitive operation of a tagged type. Thanks to such
-restrictions, the compiler is allowed to remove the out-of-line body of `NAME`.
+restrictions, the compiler is allowed to remove the out-of-line body of ``NAME``.
Pragma Inline_Generic
=====================
This pragma is provided for compatibility with Dec Ada 83. It has
-no effect in `GNAT` (which always inlines generics), other
+no effect in GNAT (which always inlines generics), other
than to check that the given names are all names of generic units or
generic instances.
This pragma is identical in syntax and semantics to
-the standard Ada pragma `Import`. It is provided for compatibility
+the standard Ada pragma ``Import``. It is provided for compatibility
with Ada 83. The definition is upwards compatible both with pragma
-`Interface` as defined in the Ada 83 Reference Manual, and also
+``Interface`` as defined in the Ada 83 Reference Manual, and also
with some extended implementations of this pragma in certain Ada 83
-implementations. The only difference between pragma `Interface`
-and pragma `Import` is that there is special circuitry to allow
+implementations. The only difference between pragma ``Interface``
+and pragma ``Import`` is that there is special circuitry to allow
both pragmas to appear for the same subprogram entity (normally it
-is illegal to have multiple `Import` pragmas. This is useful in
+is illegal to have multiple ``Import`` pragmas. This is useful in
maintaining Ada 83/Ada 95 compatibility and is compatible with other
Ada 83 compilers.
This pragma provides an alternative way of specifying the interface name
for an interfaced subprogram, and is provided for compatibility with Ada
83 compilers that use the pragma for this purpose. You must provide at
-least one of `External_Name` or `Link_Name`.
+least one of ``External_Name`` or ``Link_Name``.
Pragma Interrupt_Handler
========================
that are declared at the library level (which includes procedures
declared at the top level of a library package). In the case of AAMP,
when this pragma is applied to a nonprotected procedure, the instruction
-`IERET` is generated for returns from the procedure, enabling
+``IERET`` is generated for returns from the procedure, enabling
maskable interrupts, in place of the normal return instruction.
Pragma Interrupt_State
Normally certain interrupts are reserved to the implementation. Any attempt
to attach an interrupt causes Program_Error to be raised, as described in
-RM C.3.2(22). A typical example is the `SIGINT` interrupt used in
+RM C.3.2(22). A typical example is the ``SIGINT`` interrupt used in
many systems for an :kbd:`Ctrl-C` interrupt. Normally this interrupt is
reserved to the implementation, so that :kbd:`Ctrl-C` can be used to
-interrupt execution. Additionally, signals such as `SIGSEGV`,
-`SIGABRT`, `SIGFPE` and `SIGILL` are often mapped to specific
+interrupt execution. Additionally, signals such as ``SIGSEGV``,
+``SIGABRT``, ``SIGFPE`` and ``SIGILL`` are often mapped to specific
Ada exceptions, or used to implement run-time functions such as the
-`abort` statement and stack overflow checking.
+``abort`` statement and stack overflow checking.
-Pragma `Interrupt_State` provides a general mechanism for overriding
+Pragma ``Interrupt_State`` provides a general mechanism for overriding
such uses of interrupts. It subsumes the functionality of pragma
-`Unreserve_All_Interrupts`. Pragma `Interrupt_State` is not
+``Unreserve_All_Interrupts``. Pragma ``Interrupt_State`` is not
available on Windows or VMS. On all other platforms than VxWorks,
it applies to signals; on VxWorks, it applies to vectored hardware interrupts
and may be used to mark interrupts required by the board support package
Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide
some other action.
-These states are the allowed values of the `State` parameter of the
-pragma. The `Name` parameter is a value of the type
-`Ada.Interrupts.Interrupt_ID`. Typically, it is a name declared in
-`Ada.Interrupts.Names`.
+These states are the allowed values of the ``State`` parameter of the
+pragma. The ``Name`` parameter is a value of the type
+``Ada.Interrupts.Interrupt_ID``. Typically, it is a name declared in
+``Ada.Interrupts.Names``.
This is a configuration pragma, and the binder will check that there
are no inconsistencies between different units in a partition in how a
Note that certain signals on many operating systems cannot be caught and
handled by applications. In such cases, the pragma is ignored. See the
-operating system documentation, or the value of the array `Reserved`
-declared in the spec of package `System.OS_Interface`.
+operating system documentation, or the value of the array ``Reserved``
+declared in the spec of package ``System.OS_Interface``.
Overriding the default state of signals used by the Ada runtime may interfere
with an application's runtime behavior in the cases of the synchronous signals,
-and in the case of the signal used to implement the `abort` statement.
+and in the case of the signal used to implement the ``abort`` statement.
.. _Pragma-Invariant:
pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
-The `LOCAL_NAME` argument
+The ``LOCAL_NAME`` argument
must refer to an enumeration first subtype
in the current declarative part. The effect is to retain the enumeration
-literal names for use by `Image` and `Value` even if a global
-`Discard_Names` pragma applies. This is useful when you want to
+literal names for use by ``Image`` and ``Value`` even if a global
+``Discard_Names`` pragma applies. This is useful when you want to
generally suppress enumeration literal names and for example you therefore
-use a `Discard_Names` pragma in the :file:`gnat.adc` file, but you
+use a ``Discard_Names`` pragma in the :file:`gnat.adc` file, but you
want to retain the names for specific enumeration types.
Pragma License
This pragma is provided to allow automated checking for appropriate license
conditions with respect to the standard and modified GPL. A pragma
-`License`, which is a configuration pragma that typically appears at
+``License``, which is a configuration pragma that typically appears at
the start of a source file or in a separate :file:`gnat.adc` file, specifies
the licensing conditions of a unit as follows:
* GPL
This is used for a unit that is licensed under the unmodified GPL, and which
- therefore cannot be `with`'ed by a restricted unit.
+ therefore cannot be ``with``\ ed by a restricted unit.
* Modified_GPL
This is used for a unit licensed under the GNAT modified GPL that includes
This is used for a unit that is restricted in that it is not permitted to
depend on units that are licensed under the GPL. Typical examples are
proprietary code that is to be released under more restrictive license
- conditions. Note that restricted units are permitted to `with` units
+ conditions. Note that restricted units are permitted to ``with`` units
which are licensed under the modified GPL (this is the whole point of the
modified GPL).
-Normally a unit with no `License` pragma is considered to have an
+Normally a unit with no ``License`` pragma is considered to have an
unknown license, and no checking is done. However, standard GNAT headers
are recognized, and license information is derived from them as follows.
These default actions means that a program with a restricted license pragma
will automatically get warnings if a GPL unit is inappropriately
-`with`'ed. For example, the program:
+``with``\ ed. For example, the program:
.. code-block:: ada
end Secret_Stuff
-if compiled with pragma `License` (`Restricted`) in a
+if compiled with pragma ``License`` (``Restricted``) in a
:file:`gnat.adc` file will generate the warning::
1. with Sem_Ch3;
3. procedure Secret_Stuff is
-Here we get a warning on `Sem_Ch3` since it is part of the GNAT
+Here we get a warning on ``Sem_Ch3`` since it is part of the GNAT
compiler and is licensed under the
-GPL, but no warning for `GNAT.Sockets` which is part of the GNAT
+GPL, but no warning for ``GNAT.Sockets`` which is part of the GNAT
run time, and is therefore licensed under the modified GPL.
Pragma Link_With
This pragma is provided for compatibility with certain Ada 83 compilers.
-It has exactly the same effect as pragma `Linker_Options` except
+It has exactly the same effect as pragma ``Linker_Options`` except
that spaces occurring within one of the string expressions are treated
as separators. For example, in the following case:
pragma Link_With ("-labc -ldef");
-results in passing the strings `-labc` and `-ldef` as two
+results in passing the strings ``-labc`` and ``-ldef`` as two
separate arguments to the linker. In addition pragma Link_With allows
multiple arguments, with the same effect as successive pragmas.
[Target =>] static_string_EXPRESSION);
-`LOCAL_NAME` must refer to an object that is declared at the library
+``LOCAL_NAME`` must refer to an object that is declared at the library
level. This pragma establishes the given entity as a linker alias for the
-given target. It is equivalent to `__attribute__((alias))` in GNU C
-and causes `LOCAL_NAME` to be emitted as an alias for the symbol
-`static_string_EXPRESSION` in the object file, that is to say no space
-is reserved for `LOCAL_NAME` by the assembler and it will be resolved
-to the same address as `static_string_EXPRESSION` by the linker.
+given target. It is equivalent to ``__attribute__((alias))`` in GNU C
+and causes ``LOCAL_NAME`` to be emitted as an alias for the symbol
+``static_string_EXPRESSION`` in the object file, that is to say no space
+is reserved for ``LOCAL_NAME`` by the assembler and it will be resolved
+to the same address as ``static_string_EXPRESSION`` by the linker.
The actual linker name for the target must be used (e.g., the fully
encoded name with qualification in Ada, or the mangled name in C++),
-or it must be declared using the C convention with `pragma Import`
-or `pragma Export`.
+or it must be declared using the C convention with ``pragma Import``
+or ``pragma Export``.
Not all target machines support this pragma. On some of them it is accepted
-only if `pragma Weak_External` has been applied to `LOCAL_NAME`.
+only if ``pragma Weak_External`` has been applied to ``LOCAL_NAME``.
.. code-block:: ada
pragma Linker_Constructor (procedure_LOCAL_NAME);
-`procedure_LOCAL_NAME` must refer to a parameterless procedure that
+``procedure_LOCAL_NAME`` must refer to a parameterless procedure that
is declared at the library level. A procedure to which this pragma is
applied will be treated as an initialization routine by the linker.
-It is equivalent to `__attribute__((constructor))` in GNU C and
-causes `procedure_LOCAL_NAME` to be invoked before the entry point
+It is equivalent to ``__attribute__((constructor))`` in GNU C and
+causes ``procedure_LOCAL_NAME`` to be invoked before the entry point
of the executable is called (or immediately after the shared library is
loaded if the procedure is linked in a shared library), in particular
before the Ada run-time environment is set up.
pragma Linker_Destructor (procedure_LOCAL_NAME);
-`procedure_LOCAL_NAME` must refer to a parameterless procedure that
+``procedure_LOCAL_NAME`` must refer to a parameterless procedure that
is declared at the library level. A procedure to which this pragma is
applied will be treated as a finalization routine by the linker.
-It is equivalent to `__attribute__((destructor))` in GNU C and
-causes `procedure_LOCAL_NAME` to be invoked after the entry point
+It is equivalent to ``__attribute__((destructor))`` in GNU C and
+causes ``procedure_LOCAL_NAME`` to be invoked after the entry point
of the executable has exited (or immediately before the shared library
is unloaded if the procedure is linked in a shared library), in particular
after the Ada run-time environment is shut down.
-See `pragma Linker_Constructor` for the set of restrictions that apply
+See ``pragma Linker_Constructor`` for the set of restrictions that apply
because of these specific contexts.
.. _Pragma-Linker_Section:
[Section =>] static_string_EXPRESSION);
-`LOCAL_NAME` must refer to an object, type, or subprogram that is
+``LOCAL_NAME`` must refer to an object, type, or subprogram that is
declared at the library level. This pragma specifies the name of the
linker section for the given entity. It is equivalent to
-`__attribute__((section))` in GNU C and causes `LOCAL_NAME` to
-be placed in the `static_string_EXPRESSION` section of the
+``__attribute__((section))`` in GNU C and causes ``LOCAL_NAME`` to
+be placed in the ``static_string_EXPRESSION`` section of the
executable (assuming the linker doesn't rename the section).
GNAT also provides an implementation defined aspect of the same name.
In the case of specifying this aspect for a type, the effect is to
-specify the corresponding for all library level objects of the type which
-do not have an explicit linker section set. Note that this only applies to
-whole objects, not to components of composite objects.
+specify the corresponding section for all library-level objects of
+the type that do not have an explicit linker section set. Note that
+this only applies to whole objects, not to components of composite objects.
In the case of a subprogram, the linker section applies to all previously
declared matching overloaded subprograms in the current declarative part
The compiler normally places library-level entities in standard sections
depending on the class: procedures and functions generally go in the
-`.text` section, initialized variables in the `.data` section
-and uninitialized variables in the `.bss` section.
+``.text`` section, initialized variables in the ``.data`` section
+and uninitialized variables in the ``.bss`` section.
Other, special sections may exist on given target machines to map special
hardware, for example I/O ports or flash memory. This pragma is a means to
Some file formats do not support arbitrary sections so not all target
machines support this pragma. The use of this pragma may cause a program
execution to be erroneous if it is used to place an entity into an
-inappropriate section (e.g., a modified variable into the `.text`
-section). See also `pragma Persistent_BSS`.
+inappropriate section (e.g., a modified variable into the ``.text``
+section). See also ``pragma Persistent_BSS``.
.. code-block:: ada
pragma Loop_Invariant ( boolean_EXPRESSION );
-The effect of this pragma is similar to that of pragma `Assert`,
-except that in an `Assertion_Policy` pragma, the identifier
-`Loop_Invariant` is used to control whether it is ignored or checked
+The effect of this pragma is similar to that of pragma ``Assert``,
+except that in an ``Assertion_Policy`` pragma, the identifier
+``Loop_Invariant`` is used to control whether it is ignored or checked
(or disabled).
-`Loop_Invariant` can only appear as one of the items in the sequence
+``Loop_Invariant`` can only appear as one of the items in the sequence
of statements of a loop body, or nested inside block statements that
appear in the sequence of statements of a loop body.
The intention is that it be used to
time through the loop, and which can be used to show that the loop is
achieving its purpose.
-Multiple `Loop_Invariant` and `Loop_Variant` pragmas that
+Multiple ``Loop_Invariant`` and ``Loop_Variant`` pragmas that
apply to the same loop should be grouped in the same sequence of
statements.
-To aid in writing such invariants, the special attribute `Loop_Entry`
+To aid in writing such invariants, the special attribute ``Loop_Entry``
may be used to refer to the value of an expression on entry to the loop. This
-attribute can only be used within the expression of a `Loop_Invariant`
-pragma. For full details, see documentation of attribute `Loop_Entry`.
+attribute can only be used within the expression of a ``Loop_Invariant``
+pragma. For full details, see documentation of attribute ``Loop_Entry``.
Pragma Loop_Optimize
====================
CHANGE_DIRECTION ::= Increases | Decreases
-`Loop_Variant` can only appear as one of the items in the sequence
+``Loop_Variant`` can only appear as one of the items in the sequence
of statements of a loop body, or nested inside block statements that
appear in the sequence of statements of a loop body.
It allows the specification of quantities which must always
specifies that each time through the loop either X increases, or X stays
-the same and Y decreases. A `Loop_Variant` pragma ensures that the
+the same and Y decreases. A ``Loop_Variant`` pragma ensures that the
loop is making progress. It can be useful in helping to show informally
or prove formally that the loop always terminates.
-`Loop_Variant` is an assertion whose effect can be controlled using
-an `Assertion_Policy` with a check name of `Loop_Variant`. The
-policy can be `Check` to enable the loop variant check, `Ignore`
+``Loop_Variant`` is an assertion whose effect can be controlled using
+an ``Assertion_Policy`` with a check name of ``Loop_Variant``. The
+policy can be ``Check`` to enable the loop variant check, ``Ignore``
to ignore the check (in which case the pragma has no effect on the program),
-or `Disable` in which case the pragma is not even checked for correct
+or ``Disable`` in which case the pragma is not even checked for correct
syntax.
-Multiple `Loop_Invariant` and `Loop_Variant` pragmas that
+Multiple ``Loop_Invariant`` and ``Loop_Variant`` pragmas that
apply to the same loop should be grouped in the same sequence of
statements.
-The `Loop_Entry` attribute may be used within the expressions of the
-`Loop_Variant` pragma to refer to values on entry to the loop.
+The ``Loop_Entry`` attribute may be used within the expressions of the
+``Loop_Variant`` pragma to refer to values on entry to the loop.
Pragma Machine_Attribute
========================
Machine-dependent attributes can be specified for types and/or
declarations. This pragma is semantically equivalent to
-`__attribute__((`attribute_name`))` (if `info` is not
-specified) or `__attribute__((`attribute_name`(`info`)))
-in GNU C, where ``attribute_name`` is recognized by the
-compiler middle-end or the `TARGET_ATTRIBUTE_TABLE` machine
-specific macro. A string literal for the optional parameter `info`
+:samp:`__attribute__(({attribute_name}))` (if ``info`` is not
+specified) or :samp:`__attribute__(({attribute_name(info})))`
+in GNU C, where *attribute_name* is recognized by the
+compiler middle-end or the ``TARGET_ATTRIBUTE_TABLE`` machine
+specific macro. A string literal for the optional parameter ``info``
is transformed into an identifier, which may make this pragma unusable
for some attributes.
For further information see :title:`GNU Compiler Collection (GCC) Internals`.
This pragma is provided for compatibility with OpenVMS VAX Systems. It has
no effect in GNAT, other than being syntax checked.
+.. _Pragma-Max_Queue_Length:
+
Pragma Max_Queue_Length
=======================
dummy body with a No_Body pragma ensures that there is no interference from
earlier versions of the package body.
+Pragma No_Component_Reordering
+==============================
+
+Syntax:
+
+
+::
+
+ pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)];
+
+
+``type_LOCAL_NAME`` must refer to a record type declaration in the current
+declarative part. The effect is to preclude any reordering of components
+for the layout of the record, i.e. the record is laid out by the compiler
+in the order in which the components are declared textually. The form with
+no argument is a configuration pragma which applies to all record types
+declared in units to which the pragma applies and there is a requirement
+that this pragma be used consistently within a partition.
+
.. _Pragma-No_Elaboration_Code_All:
Pragma No_Elaboration_Code_All
This is a program unit pragma (there is also an equivalent aspect of the
-same name) that establishes the restriction `No_Elaboration_Code` for
+same name) that establishes the restriction ``No_Elaboration_Code`` for
the current unit and any extended main source units (body and subunits).
It also has the effect of enforcing a transitive application of this
aspect, so that if any unit is implicitly or explicitly with'ed by the
pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ];
-Pragma `No_Heap_Finalization` may be used as a configuration pragma or as a
+Pragma ``No_Heap_Finalization`` may be used as a configuration pragma or as a
type-specific pragma.
In its configuration form, the pragma must appear within a configuration file
such as gnat.adc, without an argument. The pragma suppresses the call to
-`Finalize` for heap-allocated objects created through library-level named
+``Finalize`` for heap-allocated objects created through library-level named
access-to-object types in cases where the designated type requires finalization
actions.
In its type-specific form, the argument of the pragma must denote a
library-level named access-to-object type. The pragma suppresses the call to
-`Finalize` for heap-allocated objects created through the specific access type
+``Finalize`` for heap-allocated objects created through the specific access type
in cases where the designated type requires finalization actions.
It is still possible to finalize such heap-allocated objects by explicitly
deallocating them.
A library-level named access-to-object type declared within a generic unit will
-lose its `No_Heap_Finalization` pragma when the corresponding instance does not
+lose its ``No_Heap_Finalization`` pragma when the corresponding instance does not
appear at the library level.
+.. _Pragma-No_Inline:
+
Pragma No_Inline
================
This pragma suppresses inlining for the callable entity or the instances of
-the generic subprogram designated by `NAME`, including inlining that
-results from the use of pragma `Inline`. This pragma is always active,
+the generic subprogram designated by ``NAME``, including inlining that
+results from the use of pragma ``Inline``. This pragma is always active,
in particular it is not subject to the use of option *-gnatn* or
-*-gnatN*. It is illegal to specify both pragma `No_Inline` and
-pragma `Inline_Always` for the same `NAME`.
+*-gnatN*. It is illegal to specify both pragma ``No_Inline`` and
+pragma ``Inline_Always`` for the same ``NAME``.
Pragma No_Return
================
pragma No_Return (procedure_LOCAL_NAME {, procedure_LOCAL_NAME});
-Each `procedure_LOCAL_NAME` argument must refer to one or more procedure
+Each ``procedure_LOCAL_NAME`` argument must refer to one or more procedure
declarations in the current declarative part. A procedure to which this
-pragma is applied may not contain any explicit `return` statements.
+pragma is applied may not contain any explicit ``return`` statements.
In addition, if the procedure contains any implicit returns from falling
off the end of a statement sequence, then execution of that implicit
return will cause Program_Error to be raised.
This is an obsolete configuration pragma that historically was used to
set up a runtime library with no object code. It is now used only for
internal testing. The pragma has been superseded by the reconfigurable
-runtime capability of `GNAT`.
+runtime capability of GNAT.
Pragma No_Strict_Aliasing
=========================
pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
-`type_LOCAL_NAME` must refer to an access type
+``type_LOCAL_NAME`` must refer to an access type
declaration in the current declarative part. The effect is to inhibit
strict aliasing optimization for the given type. The form with no
arguments is a configuration pragma which applies to all access types
::
- pragma No_Tagged_Streams;
pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)];
of code which is wasted space if stream routines are not needed for the
type in question.
-The `No_Tagged_Streams` pragma causes the generation of these stream
+The ``No_Tagged_Streams`` pragma causes the generation of these stream
routines to be skipped, and any attempt to use stream operations on
types subject to this pragma will be statically rejected as illegal.
*Enumeration types*
Objects of an enumeration type are initialized to all one-bits, i.e., to
- the value `2 ** typ'Size - 1` unless the subtype excludes the literal
+ the value ``2 ** typ'Size - 1`` unless the subtype excludes the literal
whose Pos value is zero, in which case a code of zero is used. This choice
will always generate an invalid value if one exists.
The effect of this pragma is to output a warning message on a reference to
an entity thus marked that the subprogram is obsolescent if the appropriate
-warning option in the compiler is activated. If the Message parameter is
+warning option in the compiler is activated. If the ``Message`` parameter is
present, then a second warning message is given containing this text. In
addition, a reference to the entity is considered to be a violation of pragma
-Restrictions (No_Obsolescent_Features).
+``Restrictions (No_Obsolescent_Features)``.
This pragma can also be used as a program unit pragma for a package,
in which case the entity name is the name of the package, and the
pragma indicates that the entire package is considered
-obsolescent. In this case a client `with`'ing such a package
-violates the restriction, and the `with` statement is
+obsolescent. In this case a client ``with``\ ing such a package
+violates the restriction, and the ``with`` clause is
flagged with warnings if the warning option is set.
-If the Version parameter is present (which must be exactly
-the identifier Ada_05, no other argument is allowed), then the
+If the ``Version`` parameter is present (which must be exactly
+the identifier ``Ada_05``, no other argument is allowed), then the
indication of obsolescence applies only when compiling in Ada 2005
mode. This is primarily intended for dealing with the situations
in the predefined library where subprograms or packages
have become defined as obsolescent in Ada 2005
-(e.g., in Ada.Characters.Handling), but may be used anywhere.
+(e.g., in ``Ada.Characters.Handling``), but may be used anywhere.
The following examples show typical uses of this pragma:
Note that, as for all pragmas, if you use a pragma argument identifier,
then all subsequent parameters must also use a pragma argument identifier.
-So if you specify "Entity =>" for the Entity argument, and a Message
-argument is present, it must be preceded by "Message =>".
+So if you specify ``Entity =>`` for the ``Entity`` argument, and a ``Message``
+argument is present, it must be preceded by ``Message =>``.
Pragma Optimize_Alignment
=========================
with a size of 8 bytes. This is a valid choice, since sizes of objects are
allowed to be bigger than the size of the type, but it can waste space if for
example fields of type R appear in an enclosing record. If the above type is
-compiled in `Optimize_Alignment (Space)` mode, the alignment is set to 1.
+compiled in ``Optimize_Alignment (Space)`` mode, the alignment is set to 1.
However, there is one case in which SPACE is ignored. If a variable length
record (that is a discriminated record with a component which is an array
The default alignment for this record is normally 1, but if this type is
-compiled in `Optimize_Alignment (Time)` mode, then the alignment is set
+compiled in ``Optimize_Alignment (Time)`` mode, then the alignment is set
to 4, which wastes space for objects of the type, since they are now 4 bytes
long, but results in more efficient access when the whole record is referenced.
type Color is (Red, Blue, Green, Yellow);
-By Ada semantics `Blue > Red` and `Green > Blue`,
+By Ada semantics ``Blue > Red`` and ``Green > Blue``,
but really these relations make no sense; the enumeration type merely
specifies a set of possible colors, and the order is unimportant.
the code in the client should list the possibilities, or an
appropriate subtype should be declared in the unit that declares
the original enumeration type. E.g., the following subtype could
-be declared along with the type `Color`:
+be declared along with the type ``Color``:
.. code-block:: ada
rather than one to mark them as unordered, since in our experience,
the great majority of enumeration types are conceptually unordered.
-The types `Boolean`, `Character`, `Wide_Character`,
-and `Wide_Wide_Character`
+The types ``Boolean``, ``Character``, ``Wide_Character``,
+and ``Wide_Wide_Character``
are considered to be ordered types, so each is declared with a
-pragma `Ordered` in package `Standard`.
+pragma ``Ordered`` in package ``Standard``.
-Normally pragma `Ordered` serves only as documentation and a guide for
+Normally pragma ``Ordered`` serves only as documentation and a guide for
coding standards, but GNAT provides a warning switch *-gnatw.u* that
requests warnings for inappropriate uses (comparisons and explicit
subranges) for unordered types. If this switch is used, then any
-enumeration type not marked with pragma `Ordered` will be considered
+enumeration type not marked with pragma ``Ordered`` will be considered
as unordered, and will generate warnings for inappropriate uses.
Note that generic types are not considered ordered or unordered (since the
This pragma sets the current overflow mode to the given setting. For details
of the meaning of these modes, please refer to the
'Overflow Check Handling in GNAT' appendix in the
-GNAT User's Guide. If only the `General` parameter is present,
+GNAT User's Guide. If only the ``General`` parameter is present,
the given mode applies to all expressions. If both parameters are present,
-the `General` mode applies to expressions outside assertions, and
-the `Eliminated` mode applies to expressions within assertions.
+the ``General`` mode applies to expressions outside assertions, and
+the ``Eliminated`` mode applies to expressions within assertions.
-The case of the `MODE` parameter is ignored,
-so `MINIMIZED`, `Minimized` and
-`minimized` all have the same effect.
+The case of the ``MODE`` parameter is ignored,
+so ``MINIMIZED``, ``Minimized`` and
+``minimized`` all have the same effect.
-The `Overflow_Mode` pragma has the same scoping and placement
-rules as pragma `Suppress`, so it can occur either as a
+The ``Overflow_Mode`` pragma has the same scoping and placement
+rules as pragma ``Suppress``, so it can occur either as a
configuration pragma, specifying a default for the whole
program, or in a declarative scope, where it applies to the
remaining declarations and statements in that scope.
-The pragma `Suppress (Overflow_Check)` suppresses
+The pragma ``Suppress (Overflow_Check)`` suppresses
overflow checking, but does not affect the overflow mode.
-The pragma `Unsuppress (Overflow_Check)` unsuppresses (enables)
+The pragma ``Unsuppress (Overflow_Check)`` unsuppresses (enables)
overflow checking, but does not affect the overflow mode.
Pragma Overriding_Renamings
ABSTRACT_STATE ::= NAME
-For the semantics of this pragma, see the entry for aspect `Part_Of` in the
+For the semantics of this pragma, see the entry for aspect ``Part_Of`` in the
SPARK 2014 Reference Manual, section 7.2.6.
Pragma Passive
Syntax checked, but otherwise ignored by GNAT. This is recognized for
compatibility with DEC Ada 83 implementations, where it is used within a
task definition to request that a task be made passive. If the argument
-`Semaphore` is present, or the argument is omitted, then DEC Ada 83
+``Semaphore`` is present, or the argument is omitted, then DEC Ada 83
treats the pragma as an assertion that the containing task is passive
and that optimization of context switch with this task is permitted and
-desired. If the argument `No` is present, the task must not be
+desired. If the argument ``No`` is present, the task must not be
optimized. GNAT does not attempt to optimize any tasks in this manner
(since protected objects are available in place of passive tasks).
pragma Persistent_BSS [(LOCAL_NAME)]
-This pragma allows selected objects to be placed in the `.persistent_bss`
+This pragma allows selected objects to be placed in the ``.persistent_bss``
section. On some targets the linker and loader provide for special
treatment of this section, allowing a program to be reloaded without
affecting the contents of this data (hence the name persistent).
There are two forms of usage. If an argument is given, it must be the
-local name of a library level object, with no explicit initialization
+local name of a library-level object, with no explicit initialization
and whose type is potentially persistent. If no argument is given, then
-the pragma is a configuration pragma, and applies to all library level
+the pragma is a configuration pragma, and applies to all library-level
objects with no explicit initialization of potentially persistent types.
A potentially persistent type is a scalar type, or an untagged,
type is potentially persistent.
If this pragma is used on a target where this feature is not supported,
-then the pragma will be ignored. See also `pragma Linker_Section`.
+then the pragma will be ignored. See also ``pragma Linker_Section``.
Pragma Polling
==============
This pragma controls the generation of polling code. This is normally off.
-If `pragma Polling (ON)` is used then periodic calls are generated to
-the routine `Ada.Exceptions.Poll`. This routine is a separate unit in the
+If ``pragma Polling (ON)`` is used then periodic calls are generated to
+the routine ``Ada.Exceptions.Poll``. This routine is a separate unit in the
runtime library, and can be found in file :file:`a-excpol.adb`.
-Pragma `Polling` can appear as a configuration pragma (for example it
+Pragma ``Polling`` can appear as a configuration pragma (for example it
can be placed in the :file:`gnat.adc` file) to enable polling globally, or it
can be used in the statement or declaration sequence to control polling
more locally.
A call to the polling routine is generated at the start of every loop and
-at the start of every subprogram call. This guarantees that the `Poll`
+at the start of every subprogram call. This guarantees that the ``Poll``
routine is called frequently, and places an upper bound (determined by
-the complexity of the code) on the period between two `Poll` calls.
+the complexity of the code) on the period between two ``Poll`` calls.
The primary purpose of the polling interface is to enable asynchronous
aborts on targets that cannot otherwise support it (for example Windows
NT), but it may be used for any other purpose requiring periodic polling.
The standard version is null, and can be replaced by a user program. This
-will require re-compilation of the `Ada.Exceptions` package that can
+will require re-compilation of the ``Ada.Exceptions`` package that can
be found in files :file:`a-except.ads` and :file:`a-except.adb`.
A standard alternative unit (in file :file:`4wexcpol.adb` in the standard GNAT
distribution) is used to enable the asynchronous abort capability on
targets that do not normally support the capability. The version of
-`Poll` in this file makes a call to the appropriate runtime routine
+``Poll`` in this file makes a call to the appropriate runtime routine
to test for an abort condition.
Note that polling can also be enabled by use of the *-gnatP* switch.
pragma Post (Boolean_Expression);
-The `Post` pragma is intended to be an exact replacement for
+The ``Post`` pragma is intended to be an exact replacement for
the language-defined
-`Post` aspect, and shares its restrictions and semantics.
+``Post`` aspect, and shares its restrictions and semantics.
It must appear either immediately following the corresponding
subprogram declaration (only other pragmas may intervene), or
if there is no separate subprogram declaration, then it can
[,[Message =>] String_Expression]);
-The `Postcondition` pragma allows specification of automatic
+The ``Postcondition`` pragma allows specification of automatic
postcondition checks for subprograms. These checks are similar to
assertions, but are automatically inserted just prior to the return
statements of the subprogram with which they are associated (including
must be true may contain references to function'Result in the case
of a function to refer to the returned value.
-`Postcondition` pragmas may appear either immediately following the
+``Postcondition`` pragmas may appear either immediately following the
(separate) declaration of a subprogram, or at the start of the
declarations of a subprogram body. Only other pragmas may intervene
(that is appear between the subprogram declaration and its
before any return (implicit or explicit) in the subprogram body.
A postcondition is only recognized if postconditions are active
at the time the pragma is encountered. The compiler switch *gnata*
-turns on all postconditions by default, and pragma `Check_Policy`
-with an identifier of `Postcondition` can also be used to
+turns on all postconditions by default, and pragma ``Check_Policy``
+with an identifier of ``Postcondition`` can also be used to
control whether postconditions are active.
The general approach is that postconditions are placed in the spec
end Sqrt
-As this example, shows, the use of the `Old` attribute
+As this example, shows, the use of the ``Old`` attribute
is often useful in postconditions to refer to the state on
entry to the subprogram.
raising an exception, then the postconditions are not checked.
If a postcondition fails, then the exception
-`System.Assertions.Assert_Failure` is raised. If
+``System.Assertions.Assert_Failure`` is raised. If
a message argument was supplied, then the given string
will be used as the exception message. If no message
argument was supplied, then the default message has
There are no restrictions on the complexity or form of
-conditions used within `Postcondition` pragmas.
+conditions used within ``Postcondition`` pragmas.
The following example shows that it is even possible
to verify performance behavior.
by the compiler, but are ignored at run-time even if postcondition
checking is enabled.
-Note that pragma `Postcondition` differs from the language-defined
-`Post` aspect (and corresponding `Post` pragma) in allowing
+Note that pragma ``Postcondition`` differs from the language-defined
+``Post`` aspect (and corresponding ``Post`` pragma) in allowing
multiple occurrences, allowing occurences in the body even if there
is a separate spec, and allowing a second string parameter, and the
-use of the pragma identifier `Check`. Historically, pragma
-`Postcondition` was implemented prior to the development of
+use of the pragma identifier ``Check``. Historically, pragma
+``Postcondition`` was implemented prior to the development of
Ada 2012, and has been retained in its original form for
compatibility purposes.
pragma Post_Class (Boolean_Expression);
-The `Post_Class` pragma is intended to be an exact replacement for
+The ``Post_Class`` pragma is intended to be an exact replacement for
the language-defined
-`Post'Class` aspect, and shares its restrictions and semantics.
+``Post'Class`` aspect, and shares its restrictions and semantics.
It must appear either immediately following the corresponding
subprogram declaration (only other pragmas may intervene), or
if there is no separate subprogram declaration, then it can
appear at the start of the declarations in a subprogram body
(preceded only by other pragmas).
-Note: This pragma is called `Post_Class` rather than
-`Post'Class` because the latter would not be strictly
+Note: This pragma is called ``Post_Class`` rather than
+``Post'Class`` because the latter would not be strictly
conforming to the allowed syntax for pragmas. The motivation
for provinding pragmas equivalent to the aspects is to allow a program
to be written using the pragmas, and then compiled if necessary
using an Ada compiler that does not recognize the pragmas or
aspects, but is prepared to ignore the pragmas. The assertion
-policy that controls this pragma is `Post'Class`, not
-`Post_Class`.
+policy that controls this pragma is ``Post'Class``, not
+``Post_Class``.
Pragma Rename_Pragma
============================
[Renamed =>] pragma_IDENTIFIER);
This pragma provides a mechanism for supplying new names for existing
-pragmas. The `New_Name` identifier can subsequently be used as a synonym for
+pragmas. The ``New_Name`` identifier can subsequently be used as a synonym for
the Renamed pragma. For example, suppose you have code that was originally
developed on a compiler that supports Inline_Only as an implementation defined
pragma. And suppose the semantics of pragma Inline_Only are identical to (or at
pragma Pre (Boolean_Expression);
-The `Pre` pragma is intended to be an exact replacement for
+The ``Pre`` pragma is intended to be an exact replacement for
the language-defined
-`Pre` aspect, and shares its restrictions and semantics.
+``Pre`` aspect, and shares its restrictions and semantics.
It must appear either immediately following the corresponding
subprogram declaration (only other pragmas may intervene), or
if there is no separate subprogram declaration, then it can
[,[Message =>] String_Expression]);
-The `Precondition` pragma is similar to `Postcondition`
+The ``Precondition`` pragma is similar to ``Postcondition``
except that the corresponding checks take place immediately upon
entry to the subprogram, and if a precondition fails, the exception
is raised in the context of the caller, and the attribute 'Result
end Math_Functions;
-`Precondition` pragmas may appear either immediately following the
+``Precondition`` pragmas may appear either immediately following the
(separate) declaration of a subprogram, or at the start of the
declarations of a subprogram body. Only other pragmas may intervene
(that is appear between the subprogram declaration and its
by the compiler, but are ignored at run-time even if precondition
checking is enabled.
-Note that pragma `Precondition` differs from the language-defined
-`Pre` aspect (and corresponding `Pre` pragma) in allowing
+Note that pragma ``Precondition`` differs from the language-defined
+``Pre`` aspect (and corresponding ``Pre`` pragma) in allowing
multiple occurrences, allowing occurences in the body even if there
is a separate spec, and allowing a second string parameter, and the
-use of the pragma identifier `Check`. Historically, pragma
-`Precondition` was implemented prior to the development of
+use of the pragma identifier ``Check``. Historically, pragma
+``Precondition`` was implemented prior to the development of
Ada 2012, and has been retained in its original form for
compatibility purposes.
This pragma (available in all versions of Ada in GNAT) encompasses both
-the `Static_Predicate` and `Dynamic_Predicate` aspects in
+the ``Static_Predicate`` and ``Dynamic_Predicate`` aspects in
Ada 2012. A predicate is regarded as static if it has an allowed form
-for `Static_Predicate` and is otherwise treated as a
-`Dynamic_Predicate`. Otherwise, predicates specified by this
+for ``Static_Predicate`` and is otherwise treated as a
+``Dynamic_Predicate``. Otherwise, predicates specified by this
pragma behave exactly as described in the Ada 2012 reference manual.
For example, if we have
Dynamic_Predicate => F(Q) or G(Q);
-Note that there are no pragmas `Dynamic_Predicate`
-or `Static_Predicate`. That is
+Note that there are no pragmas ``Dynamic_Predicate``
+or ``Static_Predicate``. That is
because these pragmas would affect legality and semantics of
the program and thus do not have a neutral effect if ignored.
The motivation behind providing pragmas equivalent to
static and dynamic predicates, since if the corresponding
pragmas are ignored, then the behavior of the program is
fundamentally changed (for example a membership test
-`A in B` would not take into account a predicate
+``A in B`` would not take into account a predicate
defined for subtype B). When following this approach, the
use of predicates should be avoided.
[Message =>] String_Expression);
-The `Predicate_Failure` pragma is intended to be an exact replacement for
+The ``Predicate_Failure`` pragma is intended to be an exact replacement for
the language-defined
-`Predicate_Failure` aspect, and shares its restrictions and semantics.
+``Predicate_Failure`` aspect, and shares its restrictions and semantics.
Pragma Preelaborable_Initialization
===================================
than a static string constant, since the assumption in this case is that
the program computes exactly the string it wants. If you still want the
prefixing in this case, you can always call
-`GNAT.Source_Info.Enclosing_Entity` and prepend the string manually.
+``GNAT.Source_Info.Enclosing_Entity`` and prepend the string manually.
Pragma Pre_Class
================
pragma Pre_Class (Boolean_Expression);
-The `Pre_Class` pragma is intended to be an exact replacement for
+The ``Pre_Class`` pragma is intended to be an exact replacement for
the language-defined
-`Pre'Class` aspect, and shares its restrictions and semantics.
+``Pre'Class`` aspect, and shares its restrictions and semantics.
It must appear either immediately following the corresponding
subprogram declaration (only other pragmas may intervene), or
if there is no separate subprogram declaration, then it can
appear at the start of the declarations in a subprogram body
(preceded only by other pragmas).
-Note: This pragma is called `Pre_Class` rather than
-`Pre'Class` because the latter would not be strictly
+Note: This pragma is called ``Pre_Class`` rather than
+``Pre'Class`` because the latter would not be strictly
conforming to the allowed syntax for pragmas. The motivation
for providing pragmas equivalent to the aspects is to allow a program
to be written using the pragmas, and then compiled if necessary
using an Ada compiler that does not recognize the pragmas or
aspects, but is prepared to ignore the pragmas. The assertion
-policy that controls this pragma is `Pre'Class`, not
-`Pre_Class`.
+policy that controls this pragma is ``Pre'Class``, not
+``Pre_Class``.
Pragma Priority_Specific_Dispatching
====================================
This pragma is standard in Ada 2005, but is available in all earlier
versions of Ada as an implementation-defined pragma. This is a
configuration pragma that establishes a set of configuration pragmas
-that depend on the argument. `Ravenscar` is standard in Ada 2005.
-The other possibilities (`Restricted`, `Rational`,
-`GNAT_Extended_Ravenscar`, `GNAT_Ravenscar_EDF`)
+that depend on the argument. ``Ravenscar`` is standard in Ada 2005.
+The other possibilities (``Restricted``, ``Rational``,
+``GNAT_Extended_Ravenscar``, ``GNAT_Ravenscar_EDF``)
are implementation-defined. The set of configuration pragmas
is defined in the following sections.
* Pragma Profile (Ravenscar)
- The `Ravenscar` profile is standard in Ada 2005,
+ The ``Ravenscar`` profile is standard in Ada 2005,
but is available in all earlier
versions of Ada as an implementation-defined pragma. This profile
establishes the following set of configuration pragmas:
This is an implementation-defined pragma that is similar in
-effect to `pragma Profile` except that instead of
-generating `Restrictions` pragmas, it generates
-`Restriction_Warnings` pragmas. The result is that
+effect to ``pragma Profile`` except that instead of
+generating ``Restrictions`` pragmas, it generates
+``Restriction_Warnings`` pragmas. The result is that
violations of the profile generate warning messages instead
of error messages.
| static_string_EXPRESSION
-This pragma is identical in effect to pragma `Common_Object`.
+This pragma is identical in effect to pragma ``Common_Object``.
.. _Pragma-Pure_Function:
This pragma appears in the same declarative part as a function
declaration (or a set of function declarations if more than one
overloaded declaration exists, in which case the pragma applies
-to all entities). It specifies that the function `Entity` is
+to all entities). It specifies that the function ``Entity`` is
to be considered pure for the purposes of code generation. This means
that the compiler can assume that there are no side effects, and
in particular that two calls with identical arguments produce the
address clause.
Note that, quite deliberately, there are no static checks to try
-to ensure that this promise is met, so `Pure_Function` can be used
+to ensure that this promise is met, so ``Pure_Function`` can be used
with functions that are conceptually pure, even if they do modify
global variables. For example, a square root function that is
instrumented to count the number of times it is called is still
if that results in unexpected behavior, the proper action is not to
use the pragma for subprograms that are not (conceptually) pure.
-Note: Most functions in a `Pure` package are automatically pure, and
-there is no need to use pragma `Pure_Function` for such functions. One
+Note: Most functions in a ``Pure`` package are automatically pure, and
+there is no need to use pragma ``Pure_Function`` for such functions. One
exception is any function that has at least one formal of type
-`System.Address` or a type derived from it. Such functions are not
+``System.Address`` or a type derived from it. Such functions are not
considered pure by default, since the compiler assumes that the
-`Address` parameter may be functioning as a pointer and that the
+``Address`` parameter may be functioning as a pointer and that the
referenced data may change even if the address value does not.
Similarly, imported functions are not considered to be pure by default,
since there is no way of checking that they are in fact pure. The use
-of pragma `Pure_Function` for such a function will override these default
+of pragma ``Pure_Function`` for such a function will override these default
assumption, and cause the compiler to treat a designated subprogram as pure
in these cases.
-Note: If pragma `Pure_Function` is applied to a renamed function, it
+Note: If pragma ``Pure_Function`` is applied to a renamed function, it
applies to the underlying renamed function. This can be used to
disambiguate cases of overloading where some but not all functions
in a set of overloaded functions are to be designated as pure.
-If pragma `Pure_Function` is applied to a library level function, the
+If pragma ``Pure_Function`` is applied to a library-level function, the
function is also considered pure from an optimization point of view, but the
unit is not a Pure unit in the categorization sense. So for example, a function
-thus marked is free to `with` non-pure units.
+thus marked is free to ``with`` non-pure units.
Pragma Rational
===============
pragma Profile (Ravenscar);
-which is the preferred method of setting the `Ravenscar` profile.
+which is the preferred method of setting the ``Ravenscar`` profile.
.. _Pragma-Refined_Depends:
where FUNCTION_RESULT is a function Result attribute_reference
-For the semantics of this pragma, see the entry for aspect `Refined_Depends` in
+For the semantics of this pragma, see the entry for aspect ``Refined_Depends`` in
the SPARK 2014 Reference Manual, section 6.1.5.
.. _Pragma-Refined_Global:
GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM {, GLOBAL_ITEM})
GLOBAL_ITEM ::= NAME
-For the semantics of this pragma, see the entry for aspect `Refined_Global` in
+For the semantics of this pragma, see the entry for aspect ``Refined_Global`` in
the SPARK 2014 Reference Manual, section 6.1.4.
.. _Pragma-Refined_Post:
pragma Refined_Post (boolean_EXPRESSION);
-For the semantics of this pragma, see the entry for aspect `Refined_Post` in
+For the semantics of this pragma, see the entry for aspect ``Refined_Post`` in
the SPARK 2014 Reference Manual, section 7.2.7.
.. _Pragma-Refined_State:
CONSTITUENT ::= object_NAME | state_NAME
-For the semantics of this pragma, see the entry for aspect `Refined_State` in
+For the semantics of this pragma, see the entry for aspect ``Refined_State`` in
the SPARK 2014 Reference Manual, section 7.2.2.
Pragma Relative_Deadline
the use of a remote access to class-wide type as actual for a formal
access type.
-When this pragma applies to a formal access type `Entity`, that
+When this pragma applies to a formal access type ``Entity``, that
type is treated as a remote access to class-wide type in the generic.
It must be a formal general access type, and its designated type must
be the class-wide type of a formal tagged limited private type from the
This pragma allows a series of restriction identifiers to be
specified (the list of allowed identifiers is the same as for
-pragma `Restrictions`). For each of these identifiers
+pragma ``Restrictions``). For each of these identifiers
the compiler checks for violations of the restriction, but
generates a warning message rather than an error message
if the restriction is violated.
pragma Secondary_Stack_Size (integer_EXPRESSION);
This pragma appears within the task definition of a single task declaration
-or a task type declaration (like pragma `Storage_Size`) and applies to all
+or a task type declaration (like pragma ``Storage_Size``) and applies to all
task objects of that type. The argument specifies the size of the secondary
stack to be used by these task objects, and must be of an integer type. The
secondary stack is used to handle functions that return a variable-sized
VxWorks 653 and bare board targets, where a fixed block for the
secondary stack is allocated from the primary stack of the task. By default,
these targets assign a percentage of the primary stack for the secondary stack,
-as defined by `System.Parameter.Sec_Stack_Percentage`. With this pragma,
-an `integer_EXPRESSION` of bytes is assigned from the primary stack instead.
+as defined by ``System.Parameter.Sec_Stack_Percentage``. With this pragma,
+an ``integer_EXPRESSION`` of bytes is assigned from the primary stack instead.
For most targets, the pragma does not apply as the secondary stack grows on
demand: allocated as a chain of blocks in the heap. The default size of these
-blocks can be modified via the `-D` binder option as described in
+blocks can be modified via the :switch:`-D` binder option as described in
:title:`GNAT User's Guide`.
Note that no check is made to see if the secondary stack can fit inside the
primary stack.
-Note the pragma cannot appear when the restriction `No_Secondary_Stack`
+Note the pragma cannot appear when the restriction ``No_Secondary_Stack``
is in effect.
Pragma Share_Generic
This pragma is provided for compatibility with Dec Ada 83. It has
-no effect in `GNAT` (which does not implement shared generics), other
+no effect in GNAT (which does not implement shared generics), other
than to check that the given names are all names of generic units or
generic instances.
A type can be established as a 'simple storage pool type' by applying
-the representation pragma `Simple_Storage_Pool_Type` to the type.
+the representation pragma ``Simple_Storage_Pool_Type`` to the type.
A type named in the pragma must be a library-level immutably limited record
type or limited tagged type declared immediately within a package declaration.
The type can also be a limited private type whose full type is allowed as
a simple storage pool type.
-For a simple storage pool type `SSP`, nonabstract primitive subprograms
-`Allocate`, `Deallocate`, and `Storage_Size` can be declared that
+For a simple storage pool type ``SSP``, nonabstract primitive subprograms
+``Allocate``, ``Deallocate``, and ``Storage_Size`` can be declared that
are subtype conformant with the following subprogram declarations:
return System.Storage_Elements.Storage_Count;
-Procedure `Allocate` must be declared, whereas `Deallocate` and
-`Storage_Size` are optional. If `Deallocate` is not declared, then
+Procedure ``Allocate`` must be declared, whereas ``Deallocate`` and
+``Storage_Size`` are optional. If ``Deallocate`` is not declared, then
applying an unchecked deallocation has no effect other than to set its actual
-parameter to null. If `Storage_Size` is not declared, then the
-`Storage_Size` attribute applied to an access type associated with
+parameter to null. If ``Storage_Size`` is not declared, then the
+``Storage_Size`` attribute applied to an access type associated with
a pool object of type SSP returns zero. Additional operations can be declared
for a simple storage pool type (such as for supporting a mark/release
storage-management discipline).
pragma, and so has the usual applicability of configuration pragmas
(i.e., it applies to either an entire partition, or to all units in a
compilation, or to a single unit, depending on how it is used.
-`unit_name` is mapped to `file_name_literal`. The identifier for
+``unit_name`` is mapped to ``file_name_literal``. The identifier for
the second argument is required, and indicates whether this is the file
name for the spec or for the body.
The optional Index argument should be used when a file contains multiple
-units, and when you do not want to use `gnatchop` to separate then
+units, and when you do not want to use ``gnatchop`` to separate then
into multiple files (which is the recommended procedure to limit the
number of recompilations that are needed when some sources change).
For instance, if the source file :file:`source.ada` contains
(A, Body_File_Name => "source.ada", Index => 2);
-Note that the `gnatname` utility can also be used to generate those
+Note that the ``gnatname`` utility can also be used to generate those
configuration pragmas.
-Another form of the `Source_File_Name` pragma allows
+Another form of the ``Source_File_Name`` pragma allows
the specification of patterns defining alternative file naming schemes
to apply to all files.
usually supplied automatically by the project manager. A pragma
Source_File_Name cannot appear after a :ref:`Pragma_Source_File_Name_Project`.
-For more details on the use of the `Source_File_Name` pragma, see the
-sections on `Using Other File Names` and `Alternative File Naming Schemes'
+For more details on the use of the ``Source_File_Name`` pragma, see the
+sections on ``Using Other File Names`` and `Alternative File Naming Schemes'
in the :title:`GNAT User's Guide`.
.. _Pragma_Source_File_Name_Project:
This pragma must appear as the first line of a source file.
-`integer_literal` is the logical line number of the line following
+``integer_literal`` is the logical line number of the line following
the pragma line (for use in error messages and debugging
-information). `string_literal` is a static string constant that
+information). ``string_literal`` is a static string constant that
specifies the file name to be used in error messages and debugging
-information. This is most notably used for the output of `gnatchop`
+information. This is most notably used for the output of ``gnatchop``
with the *-r* switch, to make sure that the original unchopped
source file is the one referred to.
Immediately within a library-level package body
*
- Immediately following the `private` keyword of a library-level
+ Immediately following the ``private`` keyword of a library-level
package spec
*
- Immediately following the `begin` keyword of a library-level
+ Immediately following the ``begin`` keyword of a library-level
package body
*
by pragma within the spec or body as above.
The basic consistency rule is that you can't turn SPARK_Mode back
-`On`, once you have explicitly (with a pragma) turned if
-`Off`. So the following rules apply:
+``On``, once you have explicitly (with a pragma) turned if
+``Off``. So the following rules apply:
-If a subprogram spec has SPARK_Mode `Off`, then the body must
-also have SPARK_Mode `Off`.
+If a subprogram spec has SPARK_Mode ``Off``, then the body must
+also have SPARK_Mode ``Off``.
For a package, we have four parts:
*
the body of the package
*
- the elaboration code after `begin`
+ the elaboration code after ``begin``
For a package, the rule is that if you explicitly turn SPARK_Mode
-`Off` for any part, then all the following parts must have
-SPARK_Mode `Off`. Note that this may require repeating a pragma
-SPARK_Mode (`Off`) in the body. For example, if we have a
-configuration pragma SPARK_Mode (`On`) that turns the mode on by
+``Off`` for any part, then all the following parts must have
+SPARK_Mode ``Off``. Note that this may require repeating a pragma
+SPARK_Mode (``Off``) in the body. For example, if we have a
+configuration pragma SPARK_Mode (``On``) that turns the mode on by
default everywhere, and one particular package spec has pragma
-SPARK_Mode (`Off`), then that pragma will need to be repeated in
+SPARK_Mode (``Off``), then that pragma will need to be repeated in
the package body.
Pragma Static_Elaboration_Desired
subtype, and whose returned type must be the type given as the first
argument to the pragma.
-The meaning of the `Read` parameter is that if a stream attribute directly
+The meaning of the ``Read`` parameter is that if a stream attribute directly
or indirectly specifies reading of the type given as the first parameter,
then a value of the type given as the argument to the Read function is
read from the stream, and then the Read function is used to convert this
to the required target type.
-Similarly the `Write` parameter specifies how to treat write attributes
+Similarly the ``Write`` parameter specifies how to treat write attributes
that directly or indirectly apply to the type given as the first parameter.
It must have an input parameter of the type specified by the first parameter,
and the return type must be the same as the input type of the Read function.
The effect is that if the value of an unbounded string is written to a stream,
then the representation of the item in the stream is in the same format that
-would be used for `Standard.String'Output`, and this same representation
+would be used for ``Standard.String'Output``, and this same representation
is expected when a value of this type is read from the stream. Note that the
value written always includes the bounds, even for Unbounded_String'Write,
since Unbounded_String is not an array type.
-Note that the `Stream_Convert` pragma is not effective in the case of
+Note that the ``Stream_Convert`` pragma is not effective in the case of
a derived type of a non-limited tagged type. If such a type is specified then
the pragma is silently ignored, and the default implementation of the stream
attributes is used instead.
gcc -c -gnatyl ...
-The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the `gnaty` switch with no options.
+The form ``ALL_CHECKS`` activates all standard checks (its use is equivalent
+to the use of the :switch:`gnaty` switch with no options.
See the :title:`GNAT User's Guide` for details.)
-Note: the behavior is slightly different in GNAT mode (*-gnatg* used).
-In this case, ALL_CHECKS implies the standard set of GNAT mode style check
-options (i.e. equivalent to *-gnatyg*).
+Note: the behavior is slightly different in GNAT mode (:switch:`-gnatg` used).
+In this case, ``ALL_CHECKS`` implies the standard set of GNAT mode style check
+options (i.e. equivalent to :switch:`-gnatyg`).
-The forms with `Off` and `On`
+The forms with ``Off`` and ``On``
can be used to temporarily disable style checks
as shown in the following example:
Finally the two argument form is allowed only if the first argument is
-`On` or `Off`. The effect is to turn of semantic style checks
+``On`` or ``Off``. The effect is to turn of semantic style checks
for the specified entity, as shown in the following example:
*
- `Alignment_Check` can be used to suppress alignment checks
+ ``Alignment_Check`` can be used to suppress alignment checks
on addresses used in address clauses. Such checks can also be suppressed
- by suppressing range checks, but the specific use of `Alignment_Check`
+ by suppressing range checks, but the specific use of ``Alignment_Check``
allows suppression of alignment checks without suppressing other range checks.
- Note that `Alignment_Check` is suppressed by default on machines (such as
+ Note that ``Alignment_Check`` is suppressed by default on machines (such as
the x86) with non-strict alignment.
*
- `Atomic_Synchronization` can be used to suppress the special memory
+ ``Atomic_Synchronization`` can be used to suppress the special memory
synchronization instructions that are normally generated for access to
- `Atomic` variables to ensure correct synchronization between tasks
+ ``Atomic`` variables to ensure correct synchronization between tasks
that use such variables for synchronization purposes.
*
- `Duplicated_Tag_Check` Can be used to suppress the check that is generated
+ ``Duplicated_Tag_Check`` Can be used to suppress the check that is generated
for a duplicated tag value when a tagged type is declared.
*
- `Container_Checks` Can be used to suppress all checks within Ada.Containers
+ ``Container_Checks`` Can be used to suppress all checks within Ada.Containers
and instances of its children, including Tampering_Check.
*
- `Tampering_Check` Can be used to suppress tampering check in the containers.
+ ``Tampering_Check`` Can be used to suppress tampering check in the containers.
*
- `Predicate_Check` can be used to control whether predicate checks are
+ ``Predicate_Check`` can be used to control whether predicate checks are
active. It is applicable only to predicates for which the policy is
- `Check`. Unlike `Assertion_Policy`, which determines if a given
+ ``Check``. Unlike ``Assertion_Policy``, which determines if a given
predicate is ignored or checked for the whole program, the use of
- `Suppress` and `Unsuppress` with this check name allows a given
+ ``Suppress`` and ``Unsuppress`` with this check name allows a given
predicate to be turned on and off at specific points in the program.
*
- `Validity_Check` can be used specifically to control validity checks.
- If `Suppress` is used to suppress validity checks, then no validity
+ ``Validity_Check`` can be used specifically to control validity checks.
+ If ``Suppress`` is used to suppress validity checks, then no validity
checks are performed, including those specified by the appropriate compiler
- switch or the `Validity_Checks` pragma.
+ switch or the ``Validity_Checks`` pragma.
*
- Additional check names previously introduced by use of the `Check_Name`
+ Additional check names previously introduced by use of the ``Check_Name``
pragma are also allowed.
This pragma can appear anywhere within a unit.
-The effect is to apply `Suppress (All_Checks)` to the unit
+The effect is to apply ``Suppress (All_Checks)`` to the unit
in which it appears. This pragma is implemented for compatibility with DEC
Ada 83 usage where it appears at the end of a unit, and for compatibility
with Rational Ada, where it appears as a program unit pragma.
-The use of the standard Ada pragma `Suppress (All_Checks)`
+The use of the standard Ada pragma ``Suppress (All_Checks)``
as a normal configuration pragma is the preferred usage in GNAT.
.. _Pragma-Suppress_Debug_Info:
an exception message giving the file name and line number for the location
of the raise. This is useful for debugging and logging purposes, but this
entails extra space for the strings for the messages. The configuration
-pragma `Suppress_Exception_Locations` can be used to suppress the
+pragma ``Suppress_Exception_Locations`` can be used to suppress the
generation of these strings, with the result that space is saved, but the
exception message for such raises is null. This configuration pragma may
appear in a global configuration pragma file, or in a specific unit as
This pragma appears within a task definition (like pragma
-`Priority`) and applies to the task in which it appears. The
+``Priority``) and applies to the task in which it appears. The
argument must be of type String, and provides a name to be used for
the task instance when the task is created. Note that this expression
is not required to be static, and in particular, it can contain
The task name is recorded internally in the run-time structures
and is accessible to tools like the debugger. In addition the
-routine `Ada.Task_Identification.Image` will return this
+routine ``Ada.Task_Identification.Image`` will return this
string, with a unique task address appended.
area is an additional storage area allocated to a task. A value of zero
means that either no guard area is created or a minimal guard area is
created, depending on the target. This pragma can appear anywhere a
-`Storage_Size` attribute definition clause is allowed for a task
+``Storage_Size`` attribute definition clause is allowed for a task
type.
.. _Pragma-Test_Case:
[, Ensures => Boolean_Expression]);
-The `Test_Case` pragma allows defining fine-grain specifications
+The ``Test_Case`` pragma allows defining fine-grain specifications
for use by testing tools.
-The compiler checks the validity of the `Test_Case` pragma, but its
+The compiler checks the validity of the ``Test_Case`` pragma, but its
presence does not lead to any modification of the code generated by the
compiler.
-`Test_Case` pragmas may only appear immediately following the
+``Test_Case`` pragmas may only appear immediately following the
(separate) declaration of a subprogram in a package declaration, inside
a package spec unit. Only other pragmas may intervene (that is appear
between the subprogram declaration and a test case).
-The compiler checks that boolean expressions given in `Requires` and
-`Ensures` are valid, where the rules for `Requires` are the
-same as the rule for an expression in `Precondition` and the rules
-for `Ensures` are the same as the rule for an expression in
-`Postcondition`. In particular, attributes `'Old` and
-`'Result` can only be used within the `Ensures`
+The compiler checks that boolean expressions given in ``Requires`` and
+``Ensures`` are valid, where the rules for ``Requires`` are the
+same as the rule for an expression in ``Precondition`` and the rules
+for ``Ensures`` are the same as the rule for an expression in
+``Postcondition``. In particular, attributes ``'Old`` and
+``'Result`` can only be used within the ``Ensures``
expression. The following is an example of use within a package spec:
The meaning of a test case is that there is at least one context where
-`Requires` holds such that, if the associated subprogram is executed in
-that context, then `Ensures` holds when the subprogram returns.
-Mode `Nominal` indicates that the input context should also satisfy the
+``Requires`` holds such that, if the associated subprogram is executed in
+that context, then ``Ensures`` holds when the subprogram returns.
+Mode ``Nominal`` indicates that the input context should also satisfy the
precondition of the subprogram, and the output context should also satisfy its
-postcondition. Mode `Robustness` indicates that the precondition and
+postcondition. Mode ``Robustness`` indicates that the precondition and
postcondition of the subprogram should be ignored for this test case.
.. _Pragma-Thread_Local_Storage:
This pragma specifies that the specified entity, which must be
-a variable declared in a library level package, is to be marked as
-"Thread Local Storage" (`TLS`). On systems supporting this (which
+a variable declared in a library-level package, is to be marked as
+"Thread Local Storage" (``TLS``). On systems supporting this (which
include Windows, Solaris, GNU/Linux and VxWorks 6), this causes each
thread (and hence each Ada task) to see a distinct copy of the variable.
The variable may not have default initialization, and if there is
-an explicit initialization, it must be either `null` for an
+an explicit initialization, it must be either ``null`` for an
access variable, or a static expression for a scalar variable.
This provides a low level mechanism similar to that provided by
-the `Ada.Task_Attributes` package, but much more efficient
+the ``Ada.Task_Attributes`` package, but much more efficient
and is also useful in writing interface code that will interact
with foreign threads.
-If this pragma is used on a system where `TLS` is not supported,
+If this pragma is used on a system where ``TLS`` is not supported,
then an error message will be generated and the program will be rejected.
Pragma Time_Slice
[Check =>] EXPRESSION);
-The `Type_Invariant` pragma is intended to be an exact
-replacement for the language-defined `Type_Invariant`
+The ``Type_Invariant`` pragma is intended to be an exact
+replacement for the language-defined ``Type_Invariant``
aspect, and shares its restrictions and semantics. It differs
-from the language defined `Invariant` pragma in that it
+from the language defined ``Invariant`` pragma in that it
does not permit a string parameter, and it is
-controlled by the assertion identifier `Type_Invariant`
-rather than `Invariant`.
+controlled by the assertion identifier ``Type_Invariant``
+rather than ``Invariant``.
.. _Pragma-Type_Invariant_Class:
[Check =>] EXPRESSION);
-The `Type_Invariant_Class` pragma is intended to be an exact
-replacement for the language-defined `Type_Invariant'Class`
+The ``Type_Invariant_Class`` pragma is intended to be an exact
+replacement for the language-defined ``Type_Invariant'Class``
aspect, and shares its restrictions and semantics.
-Note: This pragma is called `Type_Invariant_Class` rather than
-`Type_Invariant'Class` because the latter would not be strictly
+Note: This pragma is called ``Type_Invariant_Class`` rather than
+``Type_Invariant'Class`` because the latter would not be strictly
conforming to the allowed syntax for pragmas. The motivation
for providing pragmas equivalent to the aspects is to allow a program
to be written using the pragmas, and then compiled if necessary
using an Ada compiler that does not recognize the pragmas or
aspects, but is prepared to ignore the pragmas. The assertion
-policy that controls this pragma is `Type_Invariant'Class`,
-not `Type_Invariant_Class`.
+policy that controls this pragma is ``Type_Invariant'Class``,
+not ``Type_Invariant_Class``.
Pragma Unchecked_Union
======================
Although the rule guarantees against this possibility, it is sometimes
too restrictive. For example if we know that the string has a lower
bound of 1, then we will never raise an exception.
-The pragma `Unevaluated_Use_Of_Old` can be
-used to modify this behavior. If the argument is `Error` then an
+The pragma ``Unevaluated_Use_Of_Old`` can be
+used to modify this behavior. If the argument is ``Error`` then an
error is given (this is the default RM behavior). If the argument is
-`Warn` then the usage is allowed as legal but with a warning
-that an exception might be raised. If the argument is `Allow`
+``Warn`` then the usage is allowed as legal but with a warning
+that an exception might be raised. If the argument is ``Allow``
then the usage is allowed as legal without generating a warning.
This pragma may appear as a configuration pragma, or in a declarative
If this pragma occurs in a unit that is processed by the compiler, GNAT
aborts with the message :samp:`xxx not implemented`, where
-`xxx` is the name of the current compilation unit. This pragma is
+``xxx`` is the name of the current compilation unit. This pragma is
intended to allow the compiler to handle unimplemented library units in
a clean manner.
pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
-`type_LOCAL_NAME` must refer to a type declaration in the current
+``type_LOCAL_NAME`` must refer to a type declaration in the current
declarative part. The effect is to inhibit strict type-based aliasing
optimization for the given type. In other words, the effect is as though
access types designating this type were subject to pragma No_Strict_Aliasing.
For a detailed description of the strict aliasing optimization, and the
situations in which it must be suppressed, see the section on
-`Optimization and Strict Aliasing` in the :title:`GNAT User's Guide`.
+``Optimization and Strict Aliasing`` in the :title:`GNAT User's Guide`.
.. _Pragma-Universal_Data:
This pragma signals that the assignable entities (variables,
-`out` parameters, `in out` parameters) whose names are listed are
+``out`` parameters, ``in out`` parameters) whose names are listed are
deliberately not assigned in the current source unit. This
suppresses warnings about the
entities being referenced but not assigned, and in addition a warning will be
For the variable case, warnings are never given for unreferenced variables
whose name contains one of the substrings
-`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names
+``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names
are typically to be used in cases where such warnings are expected.
-Thus it is never necessary to use `pragma Unmodified` for such
+Thus it is never necessary to use ``pragma Unmodified`` for such
variables, though it is harmless to do so.
.. _Pragma-Unreferenced:
objects declared only for their initialization or finalization side
effects.
-If `LOCAL_NAME` identifies more than one matching homonym in the
+If ``LOCAL_NAME`` identifies more than one matching homonym in the
current scope, then the entity most recently declared is the one to which
the pragma applies. Note that in the case of accept formals, the pragma
-Unreferenced may appear immediately after the keyword `do` which
+Unreferenced may appear immediately after the keyword ``do`` which
allows the indication of whether or not accept formals are referenced
or not to be given individually for each accept statement.
unit would not be flagged); pragma Obsolescent can be used instead
for this purpose, see :ref:`Pragma_Obsolescent`.
-The second form of pragma `Unreferenced` is used within a context
+The second form of pragma ``Unreferenced`` is used within a context
clause. In this case the arguments must be unit names of units previously
-mentioned in `with` clauses (similar to the usage of pragma
-`Elaborate_All`. The effect is to suppress warnings about unreferenced
+mentioned in ``with`` clauses (similar to the usage of pragma
+``Elaborate_All``. The effect is to suppress warnings about unreferenced
units and unreferenced entities within these units.
For the variable case, warnings are never given for unreferenced variables
whose name contains one of the substrings
-`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names
+``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names
are typically to be used in cases where such warnings are expected.
-Thus it is never necessary to use `pragma Unreferenced` for such
+Thus it is never necessary to use ``pragma Unreferenced`` for such
variables, though it is harmless to do so.
.. _Pragma-Unreferenced_Objects:
Normally certain interrupts are reserved to the implementation. Any attempt
to attach an interrupt causes Program_Error to be raised, as described in
-RM C.3.2(22). A typical example is the `SIGINT` interrupt used in
+RM C.3.2(22). A typical example is the ``SIGINT`` interrupt used in
many systems for a :kbd:`Ctrl-C` interrupt. Normally this interrupt is
reserved to the implementation, so that :kbd:`Ctrl-C` can be used to
interrupt execution.
-If the pragma `Unreserve_All_Interrupts` appears anywhere in any unit in
+If the pragma ``Unreserve_All_Interrupts`` appears anywhere in any unit in
a program, then all such interrupts are unreserved. This allows the
program to handle these interrupts, but disables their standard
functions. For example, if this pragma is used, then pressing
:kbd:`Ctrl-C` will not automatically interrupt execution. However,
-a program can then handle the `SIGINT` interrupt as it chooses.
+a program can then handle the ``SIGINT`` interrupt as it chooses.
For a full list of the interrupts handled in a specific implementation,
-see the source code for the spec of `Ada.Interrupts.Names` in
+see the source code for the spec of ``Ada.Interrupts.Names`` in
file :file:`a-intnam.ads`. This is a target dependent file that contains the
list of interrupts recognized for a given target. The documentation in
this file also specifies what interrupts are affected by the use of
-the `Unreserve_All_Interrupts` pragma.
+the ``Unreserve_All_Interrupts`` pragma.
For a more general facility for controlling what interrupts can be
-handled, see pragma `Interrupt_State`, which subsumes the functionality
-of the `Unreserve_All_Interrupts` pragma.
+handled, see pragma ``Interrupt_State``, which subsumes the functionality
+of the ``Unreserve_All_Interrupts`` pragma.
Pragma Unsuppress
=================
pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
-This pragma undoes the effect of a previous pragma `Suppress`. If
-there is no corresponding pragma `Suppress` in effect, it has no
+This pragma undoes the effect of a previous pragma ``Suppress``. If
+there is no corresponding pragma ``Suppress`` in effect, it has no
effect. The range of the effect is the same as for pragma
-`Suppress`. The meaning of the arguments is identical to that used
-in pragma `Suppress`.
+``Suppress``. The meaning of the arguments is identical to that used
+in pragma ``Suppress``.
One important application is to ensure that checks are on in cases where
code depends on the checks for its correct functioning, so that the code
Note that in addition to the checks defined in the Ada RM, GNAT recogizes a
number of implementation-defined check names. See the description of pragma
-`Suppress` for full details.
+``Suppress`` for full details.
Pragma Use_VADS_Size
====================
This pragma signals that the assignable entities (variables,
-`out` parameters, and `in out` parameters) whose names are listed
+``out`` parameters, and ``in out`` parameters) whose names are listed
deliberately do not get assigned or referenced in the current source unit
after the occurrence of the pragma in the current source unit. This
suppresses warnings about the entities that are unreferenced and/or not
For the variable case, warnings are never given for unreferenced
variables whose name contains one of the substrings
-`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names
+``DISCARD, DUMMY, IGNORE, JUNK, UNUSED`` in any casing. Such names
are typically to be used in cases where such warnings are expected.
-Thus it is never necessary to use `pragma Unmodified` for such
+Thus it is never necessary to use ``pragma Unmodified`` for such
variables, though it is harmless to do so.
Pragma Validity_Checks
specifies the exact set of options required. The form of this string
is exactly as described for the *-gnatVx* compiler switch (see the
GNAT User's Guide for details). For example the following two
-methods can be used to enable validity checking for mode `in` and
-`in out` subprogram parameters:
+methods can be used to enable validity checking for mode ``in`` and
+``in out`` subprogram parameters:
*
The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the `gnatva` switch.
+to the use of the :switch:`gnatva` switch.
-The forms with `Off` and `On`
+The forms with ``Off`` and ``On``
can be used to temporarily disable validity checks
as shown in the following example:
The intention is that this be suitable for use with memory-mapped I/O devices
on some machines. Note that there are two important respects in which this is
-different from `pragma Atomic`. First a reference to a `Volatile_Full_Access`
+different from ``pragma Atomic``. First a reference to a ``Volatile_Full_Access``
object is not a sequential action in the RM 9.10 sense and, therefore, does
-not create a synchronization point. Second, in the case of `pragma Atomic`,
+not create a synchronization point. Second, in the case of ``pragma Atomic``,
there is no guarantee that all the bits will be accessed if the reference
is not to the whole object; the compiler is allowed (and generally will)
access only part of the object in this case.
-It is not permissible to specify `Atomic` and `Volatile_Full_Access` for
+It is not permissible to specify ``Atomic`` and ``Volatile_Full_Access`` for
the same object.
-It is not permissible to specify `Volatile_Full_Access` for a composite
-(record or array) type or object that has at least one `Aliased` component.
+It is not permissible to specify ``Volatile_Full_Access`` for a composite
+(record or array) type or object that has at least one ``Aliased`` component.
.. _Pragma-Volatile_Function:
pragma Volatile_Function [ (boolean_EXPRESSION) ];
-For the semantics of this pragma, see the entry for aspect `Volatile_Function`
+For the semantics of this pragma, see the entry for aspect ``Volatile_Function``
in the SPARK 2014 Reference Manual, section 7.1.2.
Pragma Warning_As_Error
The pattern may contain asterisks, which match zero or more characters in
the message. For example, you can use
-`pragma Warning_As_Error ("bits of*unused")` to treat the warning
-message `warning: 960 bits of "a" unused` as an error. No other regular
+``pragma Warning_As_Error ("bits of*unused")`` to treat the warning
+message ``warning: 960 bits of "a" unused`` as an error. No other regular
expression notations are permitted. All characters other than asterisk in
these three specific cases are treated as literal characters in the match.
The match is case insensitive, for example XYZ matches xyz.
Note: in Ada 83 mode, a string literal may be used in place of a static string
expression (which does not exist in Ada 83).
-Note if the second argument of `DETAILS` is a `local_NAME` then the
+Note if the second argument of ``DETAILS`` is a ``local_NAME`` then the
second form is always understood. If the intention is to use
-the fourth form, then you can write `NAME & ""` to force the
-intepretation as a `static_string_EXPRESSION`.
+the fourth form, then you can write ``NAME & ""`` to force the
+intepretation as a *static_string_EXPRESSION*.
-Note: if the first argument is a valid `TOOL_NAME`, it will be interpreted
-that way. The use of the `TOOL_NAME` argument is relevant only to users
+Note: if the first argument is a valid ``TOOL_NAME``, it will be interpreted
+that way. The use of the ``TOOL_NAME`` argument is relevant only to users
of SPARK and GNATprove, see last part of this section for details.
Normally warnings are enabled, with the output being controlled by
-the command line switch. Warnings (`Off`) turns off generation of
-warnings until a Warnings (`On`) is encountered or the end of the
+the command line switch. Warnings (``Off``) turns off generation of
+warnings until a Warnings (``On``) is encountered or the end of the
current unit. If generation of warnings is turned off using this
pragma, then some or all of the warning messages are suppressed,
regardless of the setting of the command line switches.
-The `Reason` parameter may optionally appear as the last argument
+The ``Reason`` parameter may optionally appear as the last argument
in any of the forms of this pragma. It is intended purely for the
-purposes of documenting the reason for the `Warnings` pragma.
+purposes of documenting the reason for the ``Warnings`` pragma.
The compiler will check that the argument is a static string but
otherwise ignore this argument. Other tools may provide specialized
processing for this string.
The form with a single argument (or two arguments if Reason present),
-where the first argument is `ON` or `OFF`
+where the first argument is ``ON`` or ``OFF``
may be used as a configuration pragma.
-If the `LOCAL_NAME` parameter is present, warnings are suppressed for
+If the ``LOCAL_NAME`` parameter is present, warnings are suppressed for
the specified entity. This suppression is effective from the point where
it occurs till the end of the extended scope of the variable (similar to
-the scope of `Suppress`). This form cannot be used as a configuration
+the scope of ``Suppress``). This form cannot be used as a configuration
pragma.
-In the case where the first argument is other than `ON` or
-`OFF`,
+In the case where the first argument is other than ``ON`` or
+``OFF``,
the third form with a single static_string_EXPRESSION argument (and possible
reason) provides more precise
control over which warnings are active. The string is a list of letters
line switch controlling warnings. For a brief summary, use the gnatmake
command with no arguments, which will generate usage information containing
the list of warnings switches supported. For
-full details see the section on `Warning Message Control` in the
+full details see the section on ``Warning Message Control`` in the
:title:`GNAT User's Guide`.
This form can also be used as a configuration pragma.
-The warnings controlled by the *-gnatw* switch are generated by the
+The warnings controlled by the :switch:`-gnatw` switch are generated by the
front end of the compiler. The GCC back end can provide additional warnings
-and they are controlled by the *-W* switch. Such warnings can be
-identified by the appearance of a string of the form `[-Wxxx]` in the
-message which designates the *-Wxxx* switch that controls the message.
-The form with a single static_string_EXPRESSION argument also works for these
-warnings, but the string must be a single full *-Wxxx* switch in this
+and they are controlled by the :switch:`-W` switch. Such warnings can be
+identified by the appearance of a string of the form ``[-W{xxx}]`` in the
+message which designates the :switch:`-W{xxx}` switch that controls the message.
+The form with a single *static_string_EXPRESSION* argument also works for these
+warnings, but the string must be a single full :switch:`-W{xxx}` switch in this
case. The above reference lists a few examples of these additional warnings.
The specified warnings will be in effect until the end of the program
-or another pragma Warnings is encountered. The effect of the pragma is
+or another pragma ``Warnings`` is encountered. The effect of the pragma is
cumulative. Initially the set of warnings is the standard default set
as possibly modified by compiler switches. Then each pragma Warning
modifies this set of warnings as specified. This form of the pragma may
also be used as a configuration pragma.
-The fourth form, with an `On|Off` parameter and a string, is used to
+The fourth form, with an ``On|Off`` parameter and a string, is used to
control individual messages, based on their text. The string argument
is a pattern that is used to match against the text of individual
warning messages (not including the initial "warning: " tag).
The pattern may contain asterisks, which match zero or more characters in
the message. For example, you can use
-`pragma Warnings (Off, "bits of*unused")` to suppress the warning
-message `warning: 960 bits of "a" unused`. No other regular
+``pragma Warnings (Off, "bits of*unused")`` to suppress the warning
+message ``warning: 960 bits of "a" unused``. No other regular
expression notations are permitted. All characters other than asterisk in
these three specific cases are treated as literal characters in the match.
The match is case insensitive, for example XYZ matches xyz.
The above use of patterns to match the message applies only to warning
messages generated by the front end. This form of the pragma with a string
argument can also be used to control warnings provided by the back end and
-mentioned above. By using a single full *-Wxxx* switch in the pragma,
+mentioned above. By using a single full :switch:`-W{xxx}` switch in the pragma,
such warnings can be turned on and off.
There are two ways to use the pragma in this form. The OFF form can be used
warning must be suppressed.
Note: to write a string that will match any warning, use the string
-`"***"`. It will not work to use a single asterisk or two
+``"***"``. It will not work to use a single asterisk or two
asterisks since this looks like an operator name. This form with three
-asterisks is similar in effect to specifying `pragma Warnings (Off)` except (if *-gnatw.w* is given) that a matching
-`pragma Warnings (On, "***")` will be required. This can be
+asterisks is similar in effect to specifying ``pragma Warnings (Off)`` except (if :switch:`-gnatw.w` is given) that a matching
+``pragma Warnings (On, "***")`` will be required. This can be
helpful in avoiding forgetting to turn warnings back on.
-Note: the debug flag -gnatd.i (`/NOWARNINGS_PRAGMAS` in VMS) can be
+Note: the debug flag :switch:`-gnatd.i` (``/NOWARNINGS_PRAGMAS`` in VMS) can be
used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
be useful in checking whether obsolete pragmas in existing programs are hiding
real problems.
separate entry for pragma Style_Checks for control of style messages.
Users of the formal verification tool GNATprove for the SPARK subset of Ada may
-use the version of the pragma with a `TOOL_NAME` parameter.
+use the version of the pragma with a ``TOOL_NAME`` parameter.
-If present, `TOOL_NAME` is the name of a tool, currently either `GNAT` for the
-compiler or `GNATprove` for the formal verification tool. A given tool only
+If present, ``TOOL_NAME`` is the name of a tool, currently either ``GNAT`` for the
+compiler or ``GNATprove`` for the formal verification tool. A given tool only
takes into account pragma Warnings that do not specify a tool name, or that
specify the matching tool name. This makes it possible to disable warnings
selectively for each tool, and as a consequence to detect useless pragma
-Warnings with switch `-gnatw.w`.
+Warnings with switch :switch:`-gnatw.w`.
Pragma Weak_External
====================
pragma Weak_External ([Entity =>] LOCAL_NAME);
-`LOCAL_NAME` must refer to an object that is declared at the library
+``LOCAL_NAME`` must refer to an object that is declared at the library
level. This pragma specifies that the given entity should be marked as a
-weak symbol for the linker. It is equivalent to `__attribute__((weak))`
-in GNU C and causes `LOCAL_NAME` to be emitted as a weak symbol instead
+weak symbol for the linker. It is equivalent to ``__attribute__((weak))``
+in GNU C and causes ``LOCAL_NAME`` to be emitted as a weak symbol instead
of a regular symbol, that is to say a symbol that does not have to be
resolved by the linker if used in conjunction with a pragma Import.
effect, causing "illegal character" errors.
The argument can be an identifier or a character literal. In the identifier
-case, it is one of `HEX`, `UPPER`, `SHIFT_JIS`,
-`EUC`, `UTF8`, or `BRACKETS`. In the character literal
+case, it is one of ``HEX``, ``UPPER``, ``SHIFT_JIS``,
+``EUC``, ``UTF8``, or ``BRACKETS``. In the character literal
case it is correspondingly one of the characters :kbd:`h`, :kbd:`u`,
:kbd:`s`, :kbd:`e`, :kbd:`8`, or :kbd:`b`.
Generally, these features are only
available if the *-gnat12* (Ada 2012 features enabled) option is set,
which is the default behavior,
-or if the configuration pragma `Ada_2012` is used.
+or if the configuration pragma ``Ada_2012`` is used.
However, new pragmas, attributes, and restrictions are
unconditionally available, since the Ada 95 standard allows the addition of
* *AI-0163 Pragmas in place of null (2010-07-01)*
A statement sequence may be composed entirely of pragmas. It is no longer
- necessary to add a dummy `null` statement to make the sequence legal.
+ necessary to add a dummy ``null`` statement to make the sequence legal.
RM References: 2.08 (7) 2.08 (16)
forms of declarations listed in the AI are supported. The following is a
list of the aspects supported (with GNAT implementation aspects marked)
-================================== ===========
-Supported Aspect Source
-================================== ===========
- `Ada_2005` -- GNAT
- `Ada_2012` -- GNAT
- `Address`
- `Alignment`
- `Atomic`
- `Atomic_Components`
- `Bit_Order`
- `Component_Size`
- `Contract_Cases` -- GNAT
- `Discard_Names`
- `External_Tag`
- `Favor_Top_Level` -- GNAT
- `Inline`
- `Inline_Always` -- GNAT
- `Invariant` -- GNAT
- `Machine_Radix`
- `No_Return`
- `Object_Size` -- GNAT
- `Pack`
- `Persistent_BSS` -- GNAT
- `Post`
- `Pre`
- `Predicate`
- `Preelaborable_Initialization`
- `Pure_Function` -- GNAT
- `Remote_Access_Type` -- GNAT
- `Shared` -- GNAT
- `Size`
- `Storage_Pool`
- `Storage_Size`
- `Stream_Size`
- `Suppress`
- `Suppress_Debug_Info` -- GNAT
- `Test_Case` -- GNAT
- `Thread_Local_Storage` -- GNAT
- `Type_Invariant`
- `Unchecked_Union`
- `Universal_Aliasing` -- GNAT
- `Unmodified` -- GNAT
- `Unreferenced` -- GNAT
- `Unreferenced_Objects` -- GNAT
- `Unsuppress`
- `Value_Size` -- GNAT
- `Volatile`
- `Volatile_Components`
- `Warnings` -- GNAT
-================================== ===========
-
- Note that for aspects with an expression, e.g. `Size`, the expression is
+==================================== ===========
+Supported Aspect Source
+==================================== ===========
+ ``Ada_2005`` -- GNAT
+ ``Ada_2012`` -- GNAT
+ ``Address``
+ ``Alignment``
+ ``Atomic``
+ ``Atomic_Components``
+ ``Bit_Order``
+ ``Component_Size``
+ ``Contract_Cases`` -- GNAT
+ ``Discard_Names``
+ ``External_Tag``
+ ``Favor_Top_Level`` -- GNAT
+ ``Inline``
+ ``Inline_Always`` -- GNAT
+ ``Invariant`` -- GNAT
+ ``Machine_Radix``
+ ``No_Return``
+ ``Object_Size`` -- GNAT
+ ``Pack``
+ ``Persistent_BSS`` -- GNAT
+ ``Post``
+ ``Pre``
+ ``Predicate``
+ ``Preelaborable_Initialization``
+ ``Pure_Function`` -- GNAT
+ ``Remote_Access_Type`` -- GNAT
+ ``Shared`` -- GNAT
+ ``Size``
+ ``Storage_Pool``
+ ``Storage_Size``
+ ``Stream_Size``
+ ``Suppress``
+ ``Suppress_Debug_Info`` -- GNAT
+ ``Test_Case`` -- GNAT
+ ``Thread_Local_Storage`` -- GNAT
+ ``Type_Invariant``
+ ``Unchecked_Union``
+ ``Universal_Aliasing`` -- GNAT
+ ``Unmodified`` -- GNAT
+ ``Unreferenced`` -- GNAT
+ ``Unreferenced_Objects`` -- GNAT
+ ``Unsuppress``
+ ``Value_Size`` -- GNAT
+ ``Volatile``
+ ``Volatile_Components``
+ ``Warnings`` -- GNAT
+==================================== ===========
+
+ Note that for aspects with an expression, e.g. ``Size``, the expression is
treated like a default expression (visibility is analyzed at the point of
occurrence of the aspect, but evaluation of the expression occurs at the
freeze point of the entity involved).
* *AI-0003 Qualified expressions as names (2010-07-11)*
In Ada 2012, a qualified expression is considered to be syntactically a name,
- meaning that constructs such as `A'(F(X)).B` are now legal. This is
+ meaning that constructs such as ``A'(F(X)).B`` are now legal. This is
useful in disambiguating some cases of overloading.
RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3)
The wording in the RM implied that if you have a general access to a
constrained object, it could be used to modify the discriminants. This was
- obviously not intended. `Constraint_Error` should be raised, and GNAT
+ obviously not intended. ``Constraint_Error`` should be raised, and GNAT
has always done so in this situation.
RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2)
* *AI-0181 Soft hyphen is a non-graphic character (2010-07-23)*
From Ada 2005 on, soft hyphen is considered a non-graphic character, which
- means that it has a special name (`SOFT_HYPHEN`) in conjunction with the
- `Image` and `Value` attributes for the character types. Strictly
+ means that it has a special name (``SOFT_HYPHEN``) in conjunction with the
+ ``Image`` and ``Value`` attributes for the character types. Strictly
speaking this is an inconsistency with Ada 95, but in practice the use of
these attributes is so obscure that it will not cause problems.
.. index:: AI-0182 (Ada 2012 feature)
-* *AI-0182 Additional forms for `Character'Value* (0000-00-00)`
+* *AI-0182 Additional forms for* ``Character'Value`` *(0000-00-00)*
- This AI allows `Character'Value` to accept the string `'?'` where
- `?` is any character including non-graphic control characters. GNAT has
+ This AI allows ``Character'Value`` to accept the string ``'?'`` where
+ ``?`` is any character including non-graphic control characters. GNAT has
always accepted such strings. It also allows strings such as
- `HEX_00000041` to be accepted, but GNAT does not take advantage of this
- permission and raises `Constraint_Error`, as is certainly still
+ ``HEX_00000041`` to be accepted, but GNAT does not take advantage of this
+ permission and raises ``Constraint_Error``, as is certainly still
permitted.
RM References: 3.05 (56/2)
* *AI-0173 Testing if tags represent abstract types (2010-07-03)*
- The function `Ada.Tags.Type_Is_Abstract` returns `True` if invoked
- with the tag of an abstract type, and `False` otherwise.
+ The function ``Ada.Tags.Type_Is_Abstract`` returns ``True`` if invoked
+ with the tag of an abstract type, and ``False`` otherwise.
RM References: 3.09 (7.4/2) 3.09 (12.4/2)
* *AI-0037 Out-of-range box associations in aggregate (0000-00-00)*
- This AI confirms that an association of the form `Indx => <>` in an
- array aggregate must raise `Constraint_Error` if `Indx`
+ This AI confirms that an association of the form ``Indx => <>`` in an
+ array aggregate must raise ``Constraint_Error`` if ``Indx``
is out of range. The RM specified a range check on other associations, but
not when the value of the association was defaulted. GNAT has always inserted
a constraint check on the index value.
Equality of untagged record composes, so that the predefined equality for a
composite type that includes a component of some untagged record type
- `R` uses the equality operation of `R` (which may be user-defined
+ ``R`` uses the equality operation of ``R`` (which may be user-defined
or predefined). This makes the behavior of untagged records identical to that
of tagged types in this respect.
The new syntax for iterating over arrays and containers is now implemented.
Iteration over containers is for now limited to read-only iterators. Only
- default iterators are supported, with the syntax: `for Elem of C`.
+ default iterators are supported, with the syntax: ``for Elem of C``.
RM References: 5.05
* *AI-0196 Null exclusion tests for out parameters (0000-00-00)*
- Null exclusion checks are not made for `**out**` parameters when
+ Null exclusion checks are not made for ``out`` parameters when
evaluating the actual parameters. GNAT has never generated these checks.
RM References: 6.04.01 (13)
* *AI-0050 Raising Constraint_Error early for function call (0000-00-00)*
- The implementation permissions for raising `Constraint_Error` early on a function call
+ The implementation permissions for raising ``Constraint_Error`` early on a function call
when it was clear an exception would be raised were over-permissive and allowed
mishandling of discriminants in some cases. GNAT did
not take advantage of these incorrect permissions in any case.
Requeue is permitted to a protected, synchronized or task interface primitive
providing it is known that the overriding operation is an entry. Otherwise
the requeue statement has the same effect as a procedure call. Use of pragma
- `Implemented` provides a way to impose a static requirement on the
+ ``Implemented`` provides a way to impose a static requirement on the
overriding operation by adhering to one of the implementation kinds: entry,
protected procedure or any of the above.
* *AI-0201 Independence of atomic object components (2010-07-22)*
- If an Atomic object has a pragma `Pack` or a `Component_Size`
+ If an Atomic object has a pragma ``Pack`` or a ``Component_Size``
attribute, then individual components may not be addressable by independent
tasks. However, if the representation clause has no effect (is confirming),
then independence is not compromised. Furthermore, in GNAT, specification of
* *AI-0009 Pragma Independent[_Components] (2010-07-23)*
- This AI introduces the new pragmas `Independent` and
- `Independent_Components`,
+ This AI introduces the new pragmas ``Independent`` and
+ ``Independent_Components``,
which control guaranteeing independence of access to objects and components.
The AI also requires independence not unaffected by confirming rep clauses.
* *AI-0072 Task signalling using 'Terminated (0000-00-00)*
- This AI clarifies that task signalling for reading `'Terminated` only
+ This AI clarifies that task signalling for reading ``'Terminated`` only
occurs if the result is True. GNAT semantics has always been consistent with
this notion of task signalling.
This AI concerns giving names to various representation aspects, but the
practical effect is simply to make the use of duplicate
- `Atomic[_Components]`,
- `Volatile[_Components]`, and
- `Independent[_Components]` pragmas illegal, and GNAT
+ ``Atomic[_Components]``,
+ ``Volatile[_Components]``, and
+ ``Independent[_Components]`` pragmas illegal, and GNAT
now performs this required check.
RM References: 13.01 (8)
* *AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)*
It is now illegal to give an inappropriate component size or a pragma
- `Pack` that attempts to change the component size in the case of atomic
+ ``Pack`` that attempts to change the component size in the case of atomic
or aliased components. Previously GNAT ignored such an attempt with a
warning.
* *AI-0095 Address of intrinsic subprograms (0000-00-00)*
- The prefix of `'Address` cannot statically denote a subprogram with
- convention `Intrinsic`. The use of the `Address` attribute raises
- `Program_Error` if the prefix denotes a subprogram with convention
- `Intrinsic`.
+ The prefix of ``'Address`` cannot statically denote a subprogram with
+ convention ``Intrinsic``. The use of the ``Address`` attribute raises
+ ``Program_Error`` if the prefix denotes a subprogram with convention
+ ``Intrinsic``.
RM References: 13.03 (11/1)
* *AI-0146 Type invariants (2009-09-21)*
Type invariants may be specified for private types using the aspect notation.
- Aspect `Type_Invariant` may be specified for any private type,
- `Type_Invariant'Class` can
+ Aspect ``Type_Invariant`` may be specified for any private type,
+ ``Type_Invariant'Class`` can
only be specified for tagged types, and is inherited by any descendent of the
tagged types. The invariant is a boolean expression that is tested for being
true in the following situations: conversions to the private type, object
[**in**] **out**
parameters and returned result on return from any primitive operation for
the type that is visible to a client.
- GNAT defines the synonyms `Invariant` for `Type_Invariant` and
- `Invariant'Class` for `Type_Invariant'Class`.
+ GNAT defines the synonyms ``Invariant`` for ``Type_Invariant`` and
+ ``Invariant'Class`` for ``Type_Invariant'Class``.
RM References: 13.03.03 (00)
* *AI-0193 Alignment of allocators (2010-09-16)*
- This AI introduces a new attribute `Max_Alignment_For_Allocation`,
- analogous to `Max_Size_In_Storage_Elements`, but for alignment instead
+ This AI introduces a new attribute ``Max_Alignment_For_Allocation``,
+ analogous to ``Max_Size_In_Storage_Elements``, but for alignment instead
of size.
RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1)
* *AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)*
- A new restriction `No_Default_Stream_Attributes` prevents the use of any
+ A new restriction ``No_Default_Stream_Attributes`` prevents the use of any
of the default stream attributes for elementary types. If this restriction is
in force, then it is necessary to provide explicit subprograms for any
stream attributes used.
* *AI-0194 Value of Stream_Size attribute (0000-00-00)*
- The `Stream_Size` attribute returns the default number of bits in the
+ The ``Stream_Size`` attribute returns the default number of bits in the
stream representation of the given type.
This value is not affected by the presence
of stream subprogram attributes for the type. GNAT has always implemented
* *AI-0114 Classification of letters (0000-00-00)*
- The code points 170 (`FEMININE ORDINAL INDICATOR`),
- 181 (`MICRO SIGN`), and
- 186 (`MASCULINE ORDINAL INDICATOR`) are technically considered
+ The code points 170 (``FEMININE ORDINAL INDICATOR``),
+ 181 (``MICRO SIGN``), and
+ 186 (``MASCULINE ORDINAL INDICATOR``) are technically considered
lower case letters by Unicode.
However, they are not allowed in identifiers, and they
- return `False` to `Ada.Characters.Handling.Is_Letter/Is_Lower`.
+ return ``False`` to ``Ada.Characters.Handling.Is_Letter/Is_Lower``.
This behavior is consistent with that defined in Ada 95.
RM References: A.03.02 (59) A.04.06 (7)
* *AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)*
- Two new packages `Ada.Wide_[Wide_]Characters.Handling` provide
- classification functions for `Wide_Character` and
- `Wide_Wide_Character`, as well as providing
- case folding routines for `Wide_[Wide_]Character` and
- `Wide_[Wide_]String`.
+ Two new packages ``Ada.Wide_[Wide_]Characters.Handling`` provide
+ classification functions for ``Wide_Character`` and
+ ``Wide_Wide_Character``, as well as providing
+ case folding routines for ``Wide_[Wide_]Character`` and
+ ``Wide_[Wide_]String``.
RM References: A.03.05 (0) A.03.06 (0)
* *AI-0031 Add From parameter to Find_Token (2010-07-25)*
- A new version of `Find_Token` is added to all relevant string packages,
- with an extra parameter `From`. Instead of starting at the first
+ A new version of ``Find_Token`` is added to all relevant string packages,
+ with an extra parameter ``From``. Instead of starting at the first
character of the string, the search for a matching Token starts at the
- character indexed by the value of `From`.
+ character indexed by the value of ``From``.
These procedures are available in all versions of Ada
but if used in versions earlier than Ada 2012 they will generate a warning
that an Ada 2012 subprogram is being used.
* *AI-0056 Index on null string returns zero (0000-00-00)*
The wording in the Ada 2005 RM implied an incompatible handling of the
- `Index` functions, resulting in raising an exception instead of
+ ``Index`` functions, resulting in raising an exception instead of
returning zero in some situations.
This was not intended and has been corrected.
GNAT always returned zero, and is thus consistent with this AI.
* *AI-0137 String encoding package (2010-03-25)*
- The packages `Ada.Strings.UTF_Encoding`, together with its child
- packages, `Conversions`, `Strings`, `Wide_Strings`,
- and `Wide_Wide_Strings` have been
+ The packages ``Ada.Strings.UTF_Encoding``, together with its child
+ packages, ``Conversions``, ``Strings``, ``Wide_Strings``,
+ and ``Wide_Wide_Strings`` have been
implemented. These packages (whose documentation can be found in the spec
files :file:`a-stuten.ads`, :file:`a-suenco.ads`, :file:`a-suenst.ads`,
:file:`a-suewst.ads`, :file:`a-suezst.ads`) allow encoding and decoding of
- `String`, `Wide_String`, and `Wide_Wide_String`
+ ``String``, ``Wide_String``, and ``Wide_Wide_String``
values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and
UTF-16), as well as conversions between the different UTF encodings. With
- the exception of `Wide_Wide_Strings`, these packages are available in
+ the exception of ``Wide_Wide_Strings``, these packages are available in
Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
- The `Wide_Wide_Strings package`
+ The ``Wide_Wide_Strings`` package
is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95
- mode since it uses `Wide_Wide_Character`).
+ mode since it uses ``Wide_Wide_Character``).
RM References: A.04.11
The compiler is not required to support exporting an Ada subprogram with
convention C if there are parameters or a return type of an unconstrained
- array type (such as `String`). GNAT allows such declarations but
+ array type (such as ``String``). GNAT allows such declarations but
generates warnings. It is possible, but complicated, to write the
corresponding C code and certainly such code would be specific to GNAT and
non-portable.
* *AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)*
- It is clearly the intention that `No_Task_Hierarchy` is intended to
+ It is clearly the intention that ``No_Task_Hierarchy`` is intended to
forbid tasks declared locally within subprograms, or functions returning task
objects, and that is the implementation that GNAT has always provided.
However the language in the RM was not sufficiently clear on this point.
* *AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)*
- The restriction `No_Relative_Delays` forbids any calls to the subprogram
- `Ada.Real_Time.Timing_Events.Set_Handler`.
+ The restriction ``No_Relative_Delays`` forbids any calls to the subprogram
+ ``Ada.Real_Time.Timing_Events.Set_Handler``.
RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2)
* *AI-0190 pragma Default_Storage_Pool (2010-09-15)*
- This AI introduces a new pragma `Default_Storage_Pool`, which can be
+ This AI introduces a new pragma ``Default_Storage_Pool``, which can be
used to control storage pools globally.
In particular, you can force every access
type that is used for allocation (**new**) to have an explicit storage pool,
* *AI-0189 No_Allocators_After_Elaboration (2010-01-23)*
- This AI introduces a new restriction `No_Allocators_After_Elaboration`,
+ This AI introduces a new restriction ``No_Allocators_After_Elaboration``,
which says that no dynamic allocation will occur once elaboration is
completed.
In general this requires a run-time check, which is not required, and which
* *AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)*
- A new package `System.Multiprocessors` is added, together with the
- definition of pragma `CPU` for controlling task affinity. A new no
- dependence restriction, on `System.Multiprocessors.Dispatching_Domains`,
+ A new package ``System.Multiprocessors`` is added, together with the
+ definition of pragma ``CPU`` for controlling task affinity. A new no
+ dependence restriction, on ``System.Multiprocessors.Dispatching_Domains``,
is added to the Ravenscar profile.
RM References: D.13.01 (4/2) D.16
* *AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)*
- Restriction `No_Anonymous_Allocators` prevents the use of allocators
+ Restriction ``No_Anonymous_Allocators`` prevents the use of allocators
where the type of the returned value is an anonymous access type.
RM References: H.04 (8/1)
.. index:: Machine Code insertions
-Package `Machine_Code` provides machine code support as described
+Package ``Machine_Code`` provides machine code support as described
in the Ada Reference Manual in two separate forms:
*
instruction, see the section on Extended Asm in
:title:`Using_the_GNU_Compiler_Collection_(GCC)`.
-Calls to the function `Asm` and the procedure `Asm` have identical
+Calls to the function ``Asm`` and the procedure ``Asm`` have identical
semantic restrictions and effects as described below. Both are provided so
that the procedure call can be used as a statement, and the function call
can be used to form a code_statement.
-Consider this C `asm` instruction:
+Consider this C ``asm`` instruction:
::
My_Float'Asm_Input ("f", angle));
-The first argument to `Asm` is the assembler template, and is
+The first argument to ``Asm`` is the assembler template, and is
identical to what is used in GNU C. This string must be a static
expression. The second argument is the output operand list. It is
-either a single `Asm_Output` attribute reference, or a list of such
+either a single ``Asm_Output`` attribute reference, or a list of such
references enclosed in parentheses (technically an array aggregate of
such references).
-The `Asm_Output` attribute denotes a function that takes two
+The ``Asm_Output`` attribute denotes a function that takes two
parameters. The first is a string, the second is the name of a variable
of the type designated by the attribute prefix. The first (string)
argument is required to be a static expression and designates the
result. The possible values for constraint are the same as those used in
the RTL, and are dependent on the configuration file used to build the
GCC back end. If there are no output operands, then this argument may
-either be omitted, or explicitly given as `No_Output_Operands`.
+either be omitted, or explicitly given as ``No_Output_Operands``.
No support is provided for GNU C's symbolic names for output parameters.
The second argument of ``my_float'Asm_Output`` functions as
-though it were an `out` parameter, which is a little curious, but
+though it were an ``out`` parameter, which is a little curious, but
all names have the form of expressions, so there is no syntactic
irregularity, even though normally functions would not be permitted
-`out` parameters. The third argument is the list of input
-operands. It is either a single `Asm_Input` attribute reference, or
+``out`` parameters. The third argument is the list of input
+operands. It is either a single ``Asm_Input`` attribute reference, or
a list of such references enclosed in parentheses (technically an array
aggregate of such references).
-The `Asm_Input` attribute denotes a function that takes two
+The ``Asm_Input`` attribute denotes a function that takes two
parameters. The first is a string, the second is an expression of the
type designated by the prefix. The first (string) argument is required
to be a static expression, and is the constraint for the parameter,
No support is provided for GNU C's symbolic names for input parameters.
If there are no input operands, this argument may either be omitted, or
-explicitly given as `No_Input_Operands`. The fourth argument, not
+explicitly given as ``No_Input_Operands``. The fourth argument, not
present in the above example, is a list of register names, called the
*clobber* argument. This argument, if given, must be a static string
expression, and is a space or comma separated list of names of registers
-that must be considered destroyed as a result of the `Asm` call. If
+that must be considered destroyed as a result of the ``Asm`` call. If
this argument is the null string (the default value), then the code
generator assumes that no additional registers are destroyed.
-In addition to registers, the special clobbers `memory` and
-`cc` as described in the GNU C docs are both supported.
+In addition to registers, the special clobbers ``memory`` and
+``cc`` as described in the GNU C docs are both supported.
The fifth argument, not present in the above example, called the
-*volatile* argument, is by default `False`. It can be set to
-the literal value `True` to indicate to the code generator that all
+*volatile* argument, is by default ``False``. It can be set to
+the literal value ``True`` to indicate to the code generator that all
optimizations with respect to the instruction specified should be
suppressed, and in particular an instruction that has outputs
will still be generated, even if none of the outputs are
that is missing either input or output operands or to avoid unwanted
optimizations. A warning is generated if this advice is not followed.
-No support is provided for GNU C's `asm goto` feature.
+No support is provided for GNU C's ``asm goto`` feature.
-The `Asm` subprograms may be used in two ways. First the procedure
+The ``Asm`` subprograms may be used in two ways. First the procedure
forms can be used anywhere a procedure call would be valid, and
correspond to what the RM calls 'intrinsic' routines. Such calls can
be used to intersperse machine instructions with other Ada statements.
Second, the function forms, which return a dummy value of the limited
-private type `Asm_Insn`, can be used in code statements, and indeed
+private type ``Asm_Insn``, can be used in code statements, and indeed
this is the only context where such calls are allowed. Code statements
appear as aggregates of the form:
Typically the form using intrinsic procedure calls is more convenient
and more flexible. The code statement form is provided to meet the RM
suggestion that such a facility should be made available. The following
-is the exact syntax of the call to `Asm`. As usual, if named notation
+is the exact syntax of the call to ``Asm``. As usual, if named notation
is used, the arguments may be given in arbitrary order, following the
normal rules for use of positional and named arguments:
INPUT_OPERAND_ATTRIBUTE ::=
SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
-The identifiers `No_Input_Operands` and `No_Output_Operands`
-are declared in the package `Machine_Code` and must be referenced
+The identifiers ``No_Input_Operands`` and ``No_Output_Operands``
+are declared in the package ``Machine_Code`` and must be referenced
according to normal visibility rules. In particular if there is no
-`use` clause for this package, then appropriate package name
+``use`` clause for this package, then appropriate package name
qualification is required.
.. _GNAT_Implementation_of_Tasking:
complications when it comes to respecting the scheduling semantics
specified in the real-time annex (Annex D).
-For instance the Annex D requirement for the `FIFO_Within_Priorities`
+For instance the Annex D requirement for the ``FIFO_Within_Priorities``
scheduling policy states:
*When the active priority of a ready task that is not running
This section specifies which policies specified by pragma Locking_Policy
are supported on which platforms.
-GNAT supports the standard `Ceiling_Locking` policy, and the
-implementation defined `Inheritance_Locking` and
-`Concurrent_Readers_Locking` policies.
+GNAT supports the standard ``Ceiling_Locking`` policy, and the
+implementation defined ``Inheritance_Locking`` and
+``Concurrent_Readers_Locking`` policies.
-`Ceiling_Locking` is supported on all platforms if the operating system
-supports it. In particular, `Ceiling_Locking` is not supported on
+``Ceiling_Locking`` is supported on all platforms if the operating system
+supports it. In particular, ``Ceiling_Locking`` is not supported on
VxWorks.
-`Inheritance_Locking` is supported on
+``Inheritance_Locking`` is supported on
Linux,
Darwin (Mac OS X),
LynxOS 178,
and VxWorks.
-`Concurrent_Readers_Locking` is supported on Linux.
-
-Note that on Linux, `Ceiling_Locking` requires the program to be running
-with root privileges. Otherwise, the policy is ignored.
+``Concurrent_Readers_Locking`` is supported on Linux.
+
+Notes about ``Ceiling_Locking`` on Linux:
+If the process is running as 'root', ceiling locking is used.
+If the capabilities facility is installed
+("sudo apt-get --assume-yes install libcap-dev" on Ubuntu,
+for example),
+and the program is linked against that library
+("-largs -lcap"),
+and the executable file has the cap_sys_nice capability
+("sudo /sbin/setcap cap_sys_nice=ep executable_file_name"),
+then ceiling locking is used.
+Otherwise, the ``Ceiling_Locking`` policy is ignored.
.. _GNAT_Implementation_of_Shared_Passive_Packages:
.. index:: Shared passive packages
GNAT fully implements the :index:`pragma <pragma Shared_Passive>`
-`Shared_Passive` for
+``Shared_Passive`` for
the purpose of designating shared passive packages.
This allows the use of passive partitions in the
context described in the Ada Reference Manual; i.e., for communication
.. index:: SHARED_MEMORY_DIRECTORY environment variable
-The environment variable `SHARED_MEMORY_DIRECTORY` should be
+The environment variable ``SHARED_MEMORY_DIRECTORY`` should be
set to the directory to be used for these files.
The files in this directory
have names that correspond to their fully qualified names. For
Z : Float;
end X;
-and the environment variable is set to `/stemp/`, then the files created
+and the environment variable is set to ``/stemp/``, then the files created
will have the names:
::
the elaboration process, since elaboration of passive packages elaborates the
initial values, but does not create the files.
-The files are written using normal `Stream_IO` access.
+The files are written using normal ``Stream_IO`` access.
If you want to be able
to communicate between programs or partitions running on different
architectures, then you should use the XDR versions of the stream attribute
----------------------------------------------------
In such cases the aggregate itself establishes the subtype, so that
-associations with `others` cannot be used. GNAT determines the
+associations with ``others`` cannot be used. GNAT determines the
bounds for the actual subtype of the aggregate, and allocates the
aggregate statically as well. No code is generated for the following:
The Size of Discriminated Records with Default Discriminants
============================================================
-If a discriminated type `T` has discriminants with default values, it is
+If a discriminated type ``T`` has discriminants with default values, it is
possible to declare an object of this type without providing an explicit
constraint:
In order to support this behavior efficiently, an unconstrained object is
given the maximum size that any value of the type requires. In the case
-above, `Word` has storage for the discriminant and for
-a `String` of length 100.
+above, ``Word`` has storage for the discriminant and for
+a ``String`` of length 100.
It is important to note that unconstrained objects do not require dynamic
allocation. It would be an improper implementation to place on the heap those
components whose size depends on discriminants. (This improper implementation
-was used by some Ada83 compilers, where the `Name` component above
+was used by some Ada83 compilers, where the ``Name`` component above
would have
been stored as a pointer to a dynamic string). Following the principle that
dynamic storage management should never be introduced implicitly,
Too_Large : Rec;
is flagged by the compiler with a warning:
-an attempt to create `Too_Large` will raise `Storage_Error`,
-because the required size includes `Positive'Last`
+an attempt to create ``Too_Large`` will raise ``Storage_Error``,
+because the required size includes ``Positive'Last``
bytes. As the first example indicates, the proper approach is to declare an
index type of 'reasonable' range so that unconstrained objects are not too
large.
-One final wrinkle: if the object is declared to be `aliased`, or if it is
+One final wrinkle: if the object is declared to be ``aliased``, or if it is
created in the heap by means of an allocator, then it is *not*
unconstrained:
it is constrained by the default values of the discriminants, and those values
(*-fstack-check*).
Note that the result of a floating point arithmetic operation in overflow and
-invalid situations, when the `Machine_Overflows` attribute of the result
-type is `False`, is to generate IEEE NaN and infinite values. This is the
+invalid situations, when the ``Machine_Overflows`` attribute of the result
+type is ``False``, is to generate IEEE NaN and infinite values. This is the
case for machines compliant with the IEEE floating-point standard, but on
machines that are not fully compliant with this standard, such as Alpha, the
*-mieee* compiler flag must be used for achieving IEEE confirming
Interfacing to C with GNAT can use one of two approaches:
*
- The types in the package `Interfaces.C` may be used.
+ The types in the package ``Interfaces.C`` may be used.
*
Standard Ada types may be used directly. This may be less portable to
other compilers, but will work on all GNAT compilers, which guarantee
correspondence between the C and Ada types.
-Pragma `Convention C` may be applied to Ada types, but mostly has no
+Pragma ``Convention C`` may be applied to Ada types, but mostly has no
effect, since this is the default. The following table shows the
correspondence between Ada scalar types and the corresponding C types.
*
Ada enumeration types map to C enumeration types directly if pragma
- `Convention C` is specified, which causes them to have int
- length. Without pragma `Convention C`, Ada enumeration types map to
- 8, 16, or 32 bits (i.e., C types `signed char`, `short`,
- `int`, respectively) depending on the number of values passed.
- This is the only case in which pragma `Convention C` affects the
+ ``Convention C`` is specified, which causes them to have int
+ length. Without pragma ``Convention C``, Ada enumeration types map to
+ 8, 16, or 32 bits (i.e., C types ``signed char``, ``short``,
+ ``int``, respectively) depending on the number of values passed.
+ This is the only case in which pragma ``Convention C`` affects the
representation of an Ada type.
*
inter-operability between Ada tagged types and C++ class definitions.
See :ref:`Implementation_Defined_Pragmas`, for more details.
-*pragma CPP_Class ([Entity =>] `LOCAL_NAME`)*
+:samp:`pragma CPP_Class ([Entity =>] {LOCAL_NAME})`
The argument denotes an entity in the current declarative region that is
declared as a tagged or untagged record type. It indicates that the type
corresponds to an externally declared C++ class type, and is to be laid
out the same way that C++ would lay out the type.
- Note: Pragma `CPP_Class` is currently obsolete. It is supported
+ Note: Pragma ``CPP_Class`` is currently obsolete. It is supported
for backward compatibility but its functionality is available
- using pragma `Import` with `Convention` = `CPP`.
+ using pragma ``Import`` with ``Convention`` = ``CPP``.
-*pragma CPP_Constructor ([Entity =>] `LOCAL_NAME`)*
+:samp:`pragma CPP_Constructor ([Entity =>] {LOCAL_NAME})`
This pragma identifies an imported function (imported in the usual way
- with pragma `Import`) as corresponding to a C++ constructor.
+ with pragma ``Import``) as corresponding to a C++ constructor.
-A few restrictions are placed on the use of the `Access` attribute
-in conjunction with subprograms subject to convention `CPP`: the
+A few restrictions are placed on the use of the ``Access`` attribute
+in conjunction with subprograms subject to convention ``CPP``: the
attribute may be used neither on primitive operations of a tagged
-record type with convention `CPP`, imported or not, nor on
-subprograms imported with pragma `CPP_Constructor`.
+record type with convention ``CPP``, imported or not, nor on
+subprograms imported with pragma ``CPP_Constructor``.
In addition, C++ exceptions are propagated and can be handled in an
-`others` choice of an exception handler. The corresponding Ada
+``others`` choice of an exception handler. The corresponding Ada
occurrence has no message, and the simple name of the exception identity
contains ``Foreign_Exception``. Finalization and awaiting dependent
tasks works properly when such foreign exceptions are propagated.
[External_Name =>] static_string_EXPRESSION);
-The `External_Name` is the name of the C++ RTTI symbol. You can then
+The ``External_Name`` is the name of the C++ RTTI symbol. You can then
cover a specific C++ exception in an exception handler.
.. _Interfacing_to_COBOL:
======================
Interfacing to Fortran is achieved as described in section B.5 of the
-Ada Reference Manual. The pragma `Convention Fortran`, applied to a
+Ada Reference Manual. The pragma ``Convention Fortran``, applied to a
multi-dimensional array causes the array to be stored in column-major
order as required for convenient interface to Fortran.
Interfacing to non-GNAT Ada code
================================
-It is possible to specify the convention `Ada` in a pragma
-`Import` or pragma `Export`. However this refers to
+It is possible to specify the convention ``Ada`` in a pragma
+``Import`` or pragma ``Export``. However this refers to
the calling conventions used by GNAT, which may or may not be
similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
compiler to allow interoperation.
.. index:: Intrinsic operator
All the predefined numeric operators in package Standard
-in `pragma Import (Intrinsic,..)`
+in ``pragma Import (Intrinsic,..)``
declarations. In the binary operator case, the operands must have the same
size. The operand or operands must also be appropriate for
the operator. For example, for addition, the operands must
both be floating-point or both be fixed-point, and the
-right operand for `"**"` must have a root type of
-`Standard.Integer'Base`.
+right operand for ``"**"`` must have a root type of
+``Standard.Integer'Base``.
You can use an intrinsic operator declaration as in the following example:
This declaration would permit 'mixed mode' arithmetic on items
-of the differing types `Int1` and `Int2`.
+of the differing types ``Int1`` and ``Int2``.
It is also possible to specify such operators for private types, if the
full views are appropriate arithmetic types.
.. index:: Compilation_Date
This intrinsic subprogram is used in the implementation of the
-library package `GNAT.Source_Info`. The only useful use of the
+library package ``GNAT.Source_Info``. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-`GNAT.Source_Info.Compilation_Date` to obtain the date of
-the current compilation (in local time format MMM DD YYYY).
+``GNAT.Source_Info.Compilation_ISO_Date`` to obtain the date of
+the current compilation (in local time format YYYY-MM-DD).
.. _Compilation_Time:
.. index:: Compilation_Time
This intrinsic subprogram is used in the implementation of the
-library package `GNAT.Source_Info`. The only useful use of the
+library package ``GNAT.Source_Info``. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-`GNAT.Source_Info.Compilation_Time` to obtain the time of
+``GNAT.Source_Info.Compilation_Time`` to obtain the time of
the current compilation (in local time format HH:MM:SS).
.. _Enclosing_Entity:
.. index:: Enclosing_Entity
This intrinsic subprogram is used in the implementation of the
-library package `GNAT.Source_Info`. The only useful use of the
+library package ``GNAT.Source_Info``. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-`GNAT.Source_Info.Enclosing_Entity` to obtain the name of
+``GNAT.Source_Info.Enclosing_Entity`` to obtain the name of
the current subprogram, package, task, entry, or protected subprogram.
.. _Exception_Information:
.. index:: Exception_Information'
This intrinsic subprogram is used in the implementation of the
-library package `GNAT.Current_Exception`. The only useful
+library package ``GNAT.Current_Exception``. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
-`GNAT.Current_Exception.Exception_Information` to obtain
+``GNAT.Current_Exception.Exception_Information`` to obtain
the exception information associated with the current exception.
.. _Exception_Message:
.. index:: Exception_Message
This intrinsic subprogram is used in the implementation of the
-library package `GNAT.Current_Exception`. The only useful
+library package ``GNAT.Current_Exception``. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
-`GNAT.Current_Exception.Exception_Message` to obtain
+``GNAT.Current_Exception.Exception_Message`` to obtain
the message associated with the current exception.
.. _Exception_Name:
.. index:: Exception_Name
This intrinsic subprogram is used in the implementation of the
-library package `GNAT.Current_Exception`. The only useful
+library package ``GNAT.Current_Exception``. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
-`GNAT.Current_Exception.Exception_Name` to obtain
+``GNAT.Current_Exception.Exception_Name`` to obtain
the name of the current exception.
.. _File:
.. index:: File
This intrinsic subprogram is used in the implementation of the
-library package `GNAT.Source_Info`. The only useful use of the
+library package ``GNAT.Source_Info``. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-`GNAT.Source_Info.File` to obtain the name of the current
+``GNAT.Source_Info.File`` to obtain the name of the current
file.
.. _Line:
.. index:: Line
This intrinsic subprogram is used in the implementation of the
-library package `GNAT.Source_Info`. The only useful use of the
+library package ``GNAT.Source_Info``. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-`GNAT.Source_Info.Line` to obtain the number of the current
+``GNAT.Source_Info.Line`` to obtain the number of the current
source line.
.. _Shifts_and_Rotates:
.. index:: Rotate_Right
In standard Ada, the shift and rotate functions are available only
-for the predefined modular types in package `Interfaces`. However, in
+for the predefined modular types in package ``Interfaces``. However, in
GNAT it is possible to define these functions for any integer
type (signed or modular), as in this example:
Rotate_Right. T must be an integer type. T'Size must be
8, 16, 32 or 64 bits; if T is modular, the modulus
must be 2**8, 2**16, 2**32 or 2**64.
-The result type must be the same as the type of `Value`.
+The result type must be the same as the type of ``Value``.
The shift amount must be Natural.
The formal parameter names can be anything.
.. index:: Source_Location
This intrinsic subprogram is used in the implementation of the
-library routine `GNAT.Source_Info`. The only useful use of the
+library routine ``GNAT.Source_Info``. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-`GNAT.Source_Info.Source_Location` to obtain the current
+``GNAT.Source_Info.Source_Location`` to obtain the current
source file location.
pragma No_Run_Time
==================
-The pragma `No_Run_Time` is used to achieve an affect similar
+The pragma ``No_Run_Time`` is used to achieve an affect similar
to the use of the "Zero Foot Print" configurable run time, but without
requiring a specially configured run time. The result of using this
pragma, which must be used for all units in a partition, is to restrict
pragma Ravenscar
================
-The pragma `Ravenscar` has exactly the same effect as pragma
-`Profile (Ravenscar)`. The latter usage is preferred since it
+The pragma ``Ravenscar`` has exactly the same effect as pragma
+``Profile (Ravenscar)``. The latter usage is preferred since it
is part of the new Ada 2005 standard.
.. _pragma_Restricted_Run_Time:
pragma Restricted_Run_Time
==========================
-The pragma `Restricted_Run_Time` has exactly the same effect as
-pragma `Profile (Restricted)`. The latter usage is
-preferred since the Ada 2005 pragma `Profile` is intended for
+The pragma ``Restricted_Run_Time`` has exactly the same effect as
+pragma ``Profile (Restricted)``. The latter usage is
+preferred since the Ada 2005 pragma ``Profile`` is intended for
this kind of implementation dependent addition.
.. _pragma_Task_Info:
pragma Task_Info
================
-The functionality provided by pragma `Task_Info` is now part of the
-Ada language. The `CPU` aspect and the package
-`System.Multiprocessors` offer a less system-dependent way to specify
+The functionality provided by pragma ``Task_Info`` is now part of the
+Ada language. The ``CPU`` aspect and the package
+``System.Multiprocessors`` offer a less system-dependent way to specify
task affinity or to query the number of processsors.
Syntax
pragma Task_Info (EXPRESSION);
This pragma appears within a task definition (like pragma
-`Priority`) and applies to the task in which it appears. The
-argument must be of type `System.Task_Info.Task_Info_Type`.
-The `Task_Info` pragma provides system dependent control over
+``Priority``) and applies to the task in which it appears. The
+argument must be of type ``System.Task_Info.Task_Info_Type``.
+The ``Task_Info`` pragma provides system dependent control over
aspects of tasking implementation, for example, the ability to map
tasks to specific processors. For details on the facilities available
for the version of GNAT that you are using, see the documentation
===============================================
This package provides target dependent functionality that is used
-to support the `Task_Info` pragma. The predefined Ada package
-`System.Multiprocessors` and the `CPU` aspect now provide a
-standard replacement for GNAT's `Task_Info` functionality.
+to support the ``Task_Info`` pragma. The predefined Ada package
+``System.Multiprocessors`` and the ``CPU`` aspect now provide a
+standard replacement for GNAT's ``Task_Info`` functionality.
.. raw:: latex
+.. role:: switch(samp)
+
.. _Representation_Clauses_and_Pragmas:
**********************************
* *Elementary Types*.
For elementary types, the alignment is the minimum of the actual size of
- objects of the type divided by `Storage_Unit`,
+ objects of the type divided by ``Storage_Unit``,
and the maximum alignment supported by the target.
(This maximum alignment is given by the GNAT-specific attribute
- `Standard'Maximum_Alignment`; see :ref:`Attribute_Maximum_Alignment`.)
+ ``Standard'Maximum_Alignment``; see :ref:`Attribute_Maximum_Alignment`.)
.. index:: Maximum_Alignment attribute
- For example, for type `Long_Float`, the object size is 8 bytes, and the
+ For example, for type ``Long_Float``, the object size is 8 bytes, and the
default alignment will be 8 on any target that supports alignments
this large, but on some targets, the maximum alignment may be smaller
- than 8, in which case objects of type `Long_Float` will be maximally
+ than 8, in which case objects of type ``Long_Float`` will be maximally
aligned.
* *Arrays*.
For the normal non-packed case, the alignment of a record is equal to
the maximum alignment of any of its components. For tagged records, this
- includes the implicit access type used for the tag. If a pragma `Pack`
+ includes the implicit access type used for the tag. If a pragma ``Pack``
is used and all components are packable (see separate section on pragma
- `Pack`), then the resulting alignment is 1, unless the layout of the
+ ``Pack``), then the resulting alignment is 1, unless the layout of the
record makes it profitable to increase it.
A special case is when:
end record;
for Small'Size use 16;
- then the default alignment of the record type `Small` is 2, not 1. This
+ then the default alignment of the record type ``Small`` is 2, not 1. This
leads to more efficient code when the record is treated as a unit, and also
- allows the type to specified as `Atomic` on architectures requiring
+ allows the type to specified as ``Atomic`` on architectures requiring
strict alignment.
An alignment clause may specify a larger alignment than the default value
up to some maximum value dependent on the target (obtainable by using the
-attribute reference `Standard'Maximum_Alignment`). It may also specify
+attribute reference ``Standard'Maximum_Alignment``). It may also specify
a smaller alignment than the default value for enumeration, integer and
fixed point types, as well as for record types, for example
.. index:: Alignment, default
-The default alignment for the type `V` is 4, as a result of the
+The default alignment for the type ``V`` is 4, as a result of the
Integer field in the record, but it is permissible, as shown, to
override the default alignment of the record with a smaller value.
subtype RS is R range 1 .. 1000;
The alignment clause specifies an alignment of 1 for the first named subtype
-`R` but this does not necessarily apply to `RS`. When writing
+``R`` but this does not necessarily apply to ``RS``. When writing
portable Ada code, you should avoid writing code that explicitly or
implicitly relies on the alignment of such subtypes.
For the GNAT compiler, if an explicit alignment clause is given, this
value is also used for any subsequent subtypes. So for GNAT, in the
-above example, you can count on the alignment of `RS` being 1. But this
+above example, you can count on the alignment of ``RS`` being 1. But this
assumption is non-portable, and other compilers may choose different
-alignments for the subtype `RS`.
+alignments for the subtype ``RS``.
.. _Size_Clauses:
.. index:: Size Clause
-The default size for a type `T` is obtainable through the
-language-defined attribute `T'Size` and also through the
-equivalent GNAT-defined attribute `T'Value_Size`.
-For objects of type `T`, GNAT will generally increase the type size
+The default size for a type ``T`` is obtainable through the
+language-defined attribute ``T'Size`` and also through the
+equivalent GNAT-defined attribute ``T'Value_Size``.
+For objects of type ``T``, GNAT will generally increase the type size
so that the object size (obtainable through the GNAT-defined attribute
-`T'Object_Size`)
-is a multiple of `T'Alignment * Storage_Unit`.
+``T'Object_Size``)
+is a multiple of ``T'Alignment * Storage_Unit``.
For example:
Y2 : boolean;
end record;
-In this example, `Smallint'Size` = `Smallint'Value_Size` = 3,
+In this example, ``Smallint'Size`` = ``Smallint'Value_Size`` = 3,
as specified by the RM rules,
but objects of this type will have a size of 8
-(`Smallint'Object_Size` = 8),
+(``Smallint'Object_Size`` = 8),
since objects by default occupy an integral number
of storage units. On some targets, notably older
versions of the Digital Alpha, the size of stand
alone objects of this type may be 32, reflecting
the inability of the hardware to do byte load/stores.
-Similarly, the size of type `Rec` is 40 bits
-(`Rec'Size` = `Rec'Value_Size` = 40), but
+Similarly, the size of type ``Rec`` is 40 bits
+(``Rec'Size`` = ``Rec'Value_Size`` = 40), but
the alignment is 4, so objects of this type will have
their size increased to 64 bits so that it is a multiple
of the alignment (in bits). This decision is
in accordance with the specific Implementation Advice in RM 13.3(43):
- "A `Size` clause should be supported for an object if the specified
- `Size` is at least as large as its subtype's `Size`, and corresponds
+ "A ``Size`` clause should be supported for an object if the specified
+ ``Size`` is at least as large as its subtype's ``Size``, and corresponds
to a size in storage elements that is a multiple of the object's
- `Alignment` (if the `Alignment` is nonzero)."
+ ``Alignment`` (if the ``Alignment`` is nonzero)."
An explicit size clause may be used to override the default size by
increasing it. For example, if we have:
.. index:: Storage_Size Clause
-For tasks, the `Storage_Size` clause specifies the amount of space
+For tasks, the ``Storage_Size`` clause specifies the amount of space
to be allocated for the task stack. This cannot be extended, and if the
-stack is exhausted, then `Storage_Error` will be raised (if stack
-checking is enabled). Use a `Storage_Size` attribute definition clause,
-or a `Storage_Size` pragma in the task definition to set the
+stack is exhausted, then ``Storage_Error`` will be raised (if stack
+checking is enabled). Use a ``Storage_Size`` attribute definition clause,
+or a ``Storage_Size`` pragma in the task definition to set the
appropriate required size. A useful technique is to include in every
task definition a pragma of the form:
pragma Storage_Size (Default_Stack_Size);
-Then `Default_Stack_Size` can be defined in a global package, and
+Then ``Default_Stack_Size`` can be defined in a global package, and
modified as required. Any tasks requiring stack sizes different from the
default can have an appropriate alternative reference in the pragma.
You can also use the *-d* binder switch to modify the default stack
size.
-For access types, the `Storage_Size` clause specifies the maximum
+For access types, the ``Storage_Size`` clause specifies the maximum
space available for allocation of objects of the type. If this space is
-exceeded then `Storage_Error` will be raised by an allocation attempt.
+exceeded then ``Storage_Error`` will be raised by an allocation attempt.
In the case where the access type is declared local to a subprogram, the
-use of a `Storage_Size` clause triggers automatic use of a special
-predefined storage pool (`System.Pool_Size`) that ensures that all
+use of a ``Storage_Size`` clause triggers automatic use of a special
+predefined storage pool (``System.Pool_Size``) that ensures that all
space for the pool is automatically reclaimed on exit from the scope in
which the type is declared.
A special case recognized by the compiler is the specification of a
-`Storage_Size` of zero for an access type. This means that no
+``Storage_Size`` of zero for an access type. This means that no
items can be allocated from the pool, and this is recognized at compile
time, and all the overhead normally associated with maintaining a fixed
size storage pool is eliminated. Consider the following example:
in the general case, even fewer bits may be needed at any particular
point during the program execution.
-As can be seen from the output of this program, the `'Size`
+As can be seen from the output of this program, the ``'Size``
attribute applied to such an object in GNAT gives the actual allocated
size of the variable, which is the largest size of any of the variants.
The Ada Reference Manual is not completely clear on what choice should
16
16
-Here we see that while the `'Size` attribute always returns
+Here we see that while the ``'Size`` attribute always returns
the maximum size, regardless of the current variant value, the
-`Size` function does indeed return the size of the current
+``Size`` function does indeed return the size of the current
variant value.
type Small is range -7 .. -4;
for Small'Size use 2;
-Although the default size of type `Small` is 4, the `Size`
+Although the default size of type ``Small`` is 4, the ``Size``
clause is accepted by GNAT and results in the following representation
scheme:
-5 is represented as 2#10#
-4 is represented as 2#11#
-Biased representation is only used if the specified `Size` clause
+Biased representation is only used if the specified ``Size`` clause
cannot be accepted in any other manner. These reduced sizes that force
biased representation can be used for all discrete types except for
enumeration types for which a representation clause is given.
.. index:: Object_Size
.. index:: Size, of objects
-In Ada 95 and Ada 2005, `T'Size` for a type `T` is the minimum
-number of bits required to hold values of type `T`.
+In Ada 95 and Ada 2005, ``T'Size`` for a type ``T`` is the minimum
+number of bits required to hold values of type ``T``.
Although this interpretation was allowed in Ada 83, it was not required,
and this requirement in practice can cause some significant difficulties.
-For example, in most Ada 83 compilers, `Natural'Size` was 32.
+For example, in most Ada 83 compilers, ``Natural'Size`` was 32.
However, in Ada 95 and Ada 2005,
-`Natural'Size` is
+``Natural'Size`` is
typically 31. This means that code may change in behavior when moving
from Ada 83 to Ada 95 or Ada 2005. For example, consider:
at 0 range Natural'Size .. 2 * Natural'Size - 1;
end record;
-In the above code, since the typical size of `Natural` objects
-is 32 bits and `Natural'Size` is 31, the above code can cause
+In the above code, since the typical size of ``Natural`` objects
+is 32 bits and ``Natural'Size`` is 31, the above code can cause
unexpected inefficient packing in Ada 95 and Ada 2005, and in general
there are cases where the fact that the object size can exceed the
size of the type causes surprises.
To help get around this problem GNAT provides two implementation
-defined attributes, `Value_Size` and `Object_Size`. When
+defined attributes, ``Value_Size`` and ``Object_Size``. When
applied to a type, these attributes yield the size of the type
(corresponding to the RM defined size attribute), and the size of
objects of the type respectively.
-The `Object_Size` is used for determining the default size of
+The ``Object_Size`` is used for determining the default size of
objects and components. This size value can be referred to using the
-`Object_Size` attribute. The phrase 'is used' here means that it is
+``Object_Size`` attribute. The phrase 'is used' here means that it is
the basis of the determination of the size. The backend is free to
pad this up if necessary for efficiency, e.g., an 8-bit stand-alone
character might be stored in 32 bits on a machine with no efficient
byte access instructions such as the Alpha.
-The default rules for the value of `Object_Size` for
+The default rules for the value of ``Object_Size`` for
discrete types are as follows:
*
- The `Object_Size` for base subtypes reflect the natural hardware
+ The ``Object_Size`` for base subtypes reflect the natural hardware
size in bits (run the compiler with *-gnatS* to find those values
for numeric types). Enumeration types and fixed-point base subtypes have
8, 16, 32, or 64 bits for this size, depending on the range of values
to be stored.
*
- The `Object_Size` of a subtype is the same as the
- `Object_Size` of
+ The ``Object_Size`` of a subtype is the same as the
+ ``Object_Size`` of
the type from which it is obtained.
*
- The `Object_Size` of a derived base type is copied from the parent
- base type, and the `Object_Size` of a derived first subtype is copied
+ The ``Object_Size`` of a derived base type is copied from the parent
+ base type, and the ``Object_Size`` of a derived first subtype is copied
from the parent first subtype.
-The `Value_Size` attribute
+The ``Value_Size`` attribute
is the (minimum) number of bits required to store a value
of the type.
This value is used to determine how tightly to pack
records or arrays with components of this type, and also affects
the semantics of unchecked conversion (unchecked conversions where
-the `Value_Size` values differ generate a warning, and are potentially
+the ``Value_Size`` values differ generate a warning, and are potentially
target dependent).
-The default rules for the value of `Value_Size` are as follows:
+The default rules for the value of ``Value_Size`` are as follows:
*
- The `Value_Size` for a base subtype is the minimum number of bits
+ The ``Value_Size`` for a base subtype is the minimum number of bits
required to store all values of the type (including the sign bit
only if negative values are possible).
*
If a subtype statically matches the first subtype of a given type, then it has
- by default the same `Value_Size` as the first subtype. This is a
+ by default the same ``Value_Size`` as the first subtype. This is a
consequence of RM 13.1(14): "if two subtypes statically match,
then their subtype-specific aspects are the same".)
*
- All other subtypes have a `Value_Size` corresponding to the minimum
+ All other subtypes have a ``Value_Size`` corresponding to the minimum
number of bits required to store all values of the subtype. For
dynamic bounds, it is assumed that the value can range down or up
to the corresponding bound of the ancestor
-The RM defined attribute `Size` corresponds to the
-`Value_Size` attribute.
+The RM defined attribute ``Size`` corresponds to the
+``Value_Size`` attribute.
-The `Size` attribute may be defined for a first-named subtype. This sets
-the `Value_Size` of
+The ``Size`` attribute may be defined for a first-named subtype. This sets
+the ``Value_Size`` of
the first-named subtype to the given value, and the
-`Object_Size` of this first-named subtype to the given value padded up
+``Object_Size`` of this first-named subtype to the given value padded up
to an appropriate boundary. It is a consequence of the default rules
-above that this `Object_Size` will apply to all further subtypes. On the
-other hand, `Value_Size` is affected only for the first subtype, any
+above that this ``Object_Size`` will apply to all further subtypes. On the
+other hand, ``Value_Size`` is affected only for the first subtype, any
dynamic subtypes obtained from it directly, and any statically matching
-subtypes. The `Value_Size` of any other static subtypes is not affected.
+subtypes. The ``Value_Size`` of any other static subtypes is not affected.
-`Value_Size` and
-`Object_Size` may be explicitly set for any subtype using
+``Value_Size`` and
+``Object_Size`` may be explicitly set for any subtype using
an attribute definition clause. Note that the use of these attributes
can cause the RM 13.1(14) rule to be violated. If two access types
-reference aliased objects whose subtypes have differing `Object_Size`
+reference aliased objects whose subtypes have differing ``Object_Size``
values as a result of explicit attribute definition clauses, then it
is illegal to convert from one access subtype to the other. For a more
complete description of this additional legality rule, see the
-description of the `Object_Size` attribute.
+description of the ``Object_Size`` attribute.
To get a feel for the difference, consider the following examples (note
-that in each case the base is `Short_Short_Integer` with a size of 8):
+that in each case the base is ``Short_Short_Integer`` with a size of 8):
+---------------------------------------------+-------------+-------------+
|Type or subtype declaration | Object_Size | Value_Size|
possible dynamic values for the bounds at run-time.
So far, so good, but GNAT has to obey the RM rules, so the question is
-under what conditions must the RM `Size` be used.
+under what conditions must the RM ``Size`` be used.
The following is a list
-of the occasions on which the RM `Size` must be used:
+of the occasions on which the RM ``Size`` must be used:
*
Component size for packed arrays or records
*
- Value of the attribute `Size` for a type
+ Value of the attribute ``Size`` for a type
*
Warning about sizes not matching for unchecked conversion
-For record types, the `Object_Size` is always a multiple of the
+For record types, the ``Object_Size`` is always a multiple of the
alignment of the type (this is true for all types). In some cases the
-`Value_Size` can be smaller. Consider:
+``Value_Size`` can be smaller. Consider:
.. code-block:: ada
On a typical 32-bit architecture, the X component will be four bytes, and
require four-byte alignment, and the Y component will be one byte. In this
-case `R'Value_Size` will be 40 (bits) since this is the minimum size
+case ``R'Value_Size`` will be 40 (bits) since this is the minimum size
required to store a value of this type, and for example, it is permissible
to have a component of type R in an outer array whose component size is
-specified to be 48 bits. However, `R'Object_Size` will be 64 (bits),
+specified to be 48 bits. However, ``R'Object_Size`` will be 64 (bits),
since it must be rounded up so that this value is a multiple of the
alignment (4 bytes = 32 bits).
-For all other types, the `Object_Size`
-and `Value_Size` are the same (and equivalent to the RM attribute `Size`).
-Only `Size` may be specified for such types.
+For all other types, the ``Object_Size``
+and ``Value_Size`` are the same (and equivalent to the RM attribute ``Size``).
+Only ``Size`` may be specified for such types.
-Note that `Value_Size` can be used to force biased representation
+Note that ``Value_Size`` can be used to force biased representation
for a particular subtype. Consider this example:
subtype REF is R range E .. F;
-By default, `RAB`
+By default, ``RAB``
has a size of 1 (sufficient to accommodate the representation
-of `A` and `B`, 0 and 1), and `REF`
+of ``A`` and ``B``, 0 and 1), and ``REF``
has a size of 3 (sufficient to accommodate the representation
-of `E` and `F`, 4 and 5). But if we add the
-following `Value_Size` attribute definition clause:
+of ``E`` and ``F``, 4 and 5). But if we add the
+following ``Value_Size`` attribute definition clause:
.. code-block:: ada
for REF'Value_Size use 1;
-then biased representation is forced for `REF`,
-and 0 will represent `E` and 1 will represent `F`.
-A warning is issued when a `Value_Size` attribute
+then biased representation is forced for ``REF``,
+and 0 will represent ``E`` and 1 will represent ``F``.
+A warning is issued when a ``Value_Size`` attribute
definition clause forces biased representation. This
-warning can be turned off using `-gnatw.B`.
+warning can be turned off using :switch:`-gnatw.B`.
.. _Component_Size_Clauses:
.. index:: ordering, of bits
-For record subtypes, GNAT permits the specification of the `Bit_Order`
+For record subtypes, GNAT permits the specification of the ``Bit_Order``
attribute. The specification may either correspond to the default bit
order for the target, in which case the specification has no effect and
places no additional restrictions, or it may be for the non-standard
* Components fitting within a single storage unit.
These are unrestricted, and the effect is merely to renumber bits. For
- example if we are on a little-endian machine with `Low_Order_First`
+ example if we are on a little-endian machine with ``Low_Order_First``
being the default, then the following two declarations have exactly
the same effect:
The useful application here is to write the second declaration with the
- `Bit_Order` attribute definition clause, and know that it will be treated
+ ``Bit_Order`` attribute definition clause, and know that it will be treated
the same, regardless of whether the target is little-endian or big-endian.
* Components occupying an integral number of bytes.
These are components that exactly fit in two or more bytes. Such component
declarations are allowed, but have no effect, since it is important to realize
- that the `Bit_Order` specification does not affect the ordering of bytes.
+ that the ``Bit_Order`` specification does not affect the ordering of bytes.
In particular, the following attempt at getting an endian-independent integer
does not work:
little-endian machine, and a big-endian integer on a big-endian machine.
If byte flipping is required for interoperability between big- and
little-endian machines, this must be explicitly programmed. This capability
- is not provided by `Bit_Order`.
+ is not provided by ``Bit_Order``.
* Components that are positioned across byte boundaries.
Since the misconception that Bit_Order automatically deals with all
endian-related incompatibilities is a common one, the specification of
a component field that is an integral number of bytes will always
-generate a warning. This warning may be suppressed using `pragma Warnings (Off)`
+generate a warning. This warning may be suppressed using ``pragma Warnings (Off)``
if desired. The following section contains additional
details regarding the issue of byte ordering.
.. index:: ordering, of bytes
-In this section we will review the effect of the `Bit_Order` attribute
+In this section we will review the effect of the ``Bit_Order`` attribute
definition clause on byte ordering. Briefly, it has no effect at all, but
a detailed example will be helpful. Before giving this
example, let us review the precise
-definition of the effect of defining `Bit_Order`. The effect of a
+definition of the effect of defining ``Bit_Order``. The effect of a
non-standard bit order is described in section 13.5.3 of the Ada
Reference Manual:
less than Storage_Unit."
The critical point here is that storage places are taken from
-the values after normalization, not before. So the `Bit_Order`
+the values after normalization, not before. So the ``Bit_Order``
interpretation applies to normalized values. The interpretation
is described in the later part of the 13.5.3 paragraph:
It is a nuisance to have to rewrite the clause, especially if
the code has to be maintained on both machines. However,
this is a case that we can handle with the
-`Bit_Order` attribute if it is implemented.
+``Bit_Order`` attribute if it is implemented.
Note that the implementation is not required on byte addressed
machines, but it is indeed implemented in GNAT.
This means that we can simply use the
machine.
The important point to understand is that byte ordering is not affected.
-A `Bit_Order` attribute definition never affects which byte a field
+A ``Bit_Order`` attribute definition never affects which byte a field
ends up in, only where it ends up in that byte.
To make this clear, let us rewrite the record rep clause of the previous
example as:
end record;
-Why are they equivalent? Well take a specific field, the `Slave_V2`
+Why are they equivalent? Well take a specific field, the ``Slave_V2``
field. The storage place attributes are obtained by normalizing the
-values given so that the `First_Bit` value is less than 8. After
+values given so that the ``First_Bit`` value is less than 8. After
normalizing the values (0,10,10) we get (1,2,2) which is exactly what
we specified in the other case.
-Now one might expect that the `Bit_Order` attribute might affect
+Now one might expect that the ``Bit_Order`` attribute might affect
bit numbering within the entire record component (two bytes in this
case, thus affecting which byte fields end up in), but that is not
the way this feature is defined, it only affects numbering of bits,
Consequently it never makes sense to specify a starting bit number
greater than 7 (for a byte addressable field) if an attribute
-definition for `Bit_Order` has been given, and indeed it
+definition for ``Bit_Order`` has been given, and indeed it
may be actively confusing to specify such a value, so the compiler
generates a warning for such usage.
end record;
Now to switch between machines, all that is necessary is
-to set the boolean constant `Master_Byte_First` in
+to set the boolean constant ``Master_Byte_First`` in
an appropriate manner.
.. _Pragma_Pack_for_Arrays:
.. index:: Pragma Pack (for arrays)
-Pragma `Pack` applied to an array has an effect that depends upon whether the
+Pragma ``Pack`` applied to an array has an effect that depends upon whether the
component type is *packable*. For a component type to be *packable*, it must
be one of the following cases:
* Any small simple record type with a static size.
For all these cases, if the component subtype size is in the range
-1 through 64, then the effect of the pragma `Pack` is exactly as though a
+1 through 64, then the effect of the pragma ``Pack`` is exactly as though a
component size were specified giving the component subtype size.
All other types are non-packable, they occupy an integral number of storage
type ar is array (1 .. 8) of r;
pragma Pack (ar);
-Then the component size of `ar` will be set to 5 (i.e., to `r'size`,
-and the size of the array `ar` will be exactly 40 bits).
+Then the component size of ``ar`` will be set to 5 (i.e., to ``r'size``,
+and the size of the array ``ar`` will be exactly 40 bits).
Note that in some cases this rather fierce approach to packing can produce
unexpected effects. For example, in Ada 95 and Ada 2005,
-subtype `Natural` typically has a size of 31, meaning that if you
-pack an array of `Natural`, you get 31-bit
+subtype ``Natural`` typically has a size of 31, meaning that if you
+pack an array of ``Natural``, you get 31-bit
close packing, which saves a few bits, but results in far less efficient
access. Since many other Ada compilers will ignore such a packing request,
-GNAT will generate a warning on some uses of pragma `Pack` that it guesses
+GNAT will generate a warning on some uses of pragma ``Pack`` that it guesses
might not be what is intended. You can easily remove this warning by
-using an explicit `Component_Size` setting instead, which never generates
+using an explicit ``Component_Size`` setting instead, which never generates
a warning, since the intention of the programmer is clear in this case.
GNAT treats packed arrays in one of two ways. If the size of the array is
One special case that is worth noting occurs when the base type of the
component size is 8/16/32 and the subtype is one bit less. Notably this
-occurs with subtype `Natural`. Consider:
+occurs with subtype ``Natural``. Consider:
.. code-block:: ada
pragma Pack (Arr);
In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
-since typically `Natural'Size` is 32 in Ada 83, and in any case most
+since typically ``Natural'Size`` is 32 in Ada 83, and in any case most
Ada 83 compilers did not attempt 31 bit packing.
-In Ada 95 and Ada 2005, `Natural'Size` is required to be 31. Furthermore,
+In Ada 95 and Ada 2005, ``Natural'Size`` is required to be 31. Furthermore,
GNAT really does pack 31-bit subtype to 31 bits. This may result in a
substantial unintended performance penalty when porting legacy Ada 83 code.
To help prevent this, GNAT generates a warning in such cases. If you really
.. index:: Pragma Pack (for records)
-Pragma `Pack` applied to a record will pack the components to reduce
+Pragma ``Pack`` applied to a record will pack the components to reduce
wasted space from alignment gaps and by reducing the amount of space
taken by components. We distinguish between *packable* components and
*non-packable* components.
* Small simple records, where the size is statically known, are also packable.
-For all these cases, if the 'Size value is in the range 1 through 64, the
+For all these cases, if the ``'Size`` value is in the range 1 through 64, the
components occupy the exact number of bits corresponding to this value
and are packed with no padding bits, i.e. they can start on an arbitrary
bit boundary.
All other types are non-packable, they occupy an integral number of storage
-units and the only effect of pragma Pack is to remove alignment gaps.
+units and the only effect of pragma ``Pack`` is to remove alignment gaps.
For example, consider the record
end record;
pragma Pack (X2);
-The representation for the record X2 is as follows:
+The representation for the record ``X2`` is as follows:
.. code-block:: ada
L6 at 18 range 0 .. 71;
end record;
-Studying this example, we see that the packable fields `L1`
-and `L2` are
+Studying this example, we see that the packable fields ``L1``
+and ``L2`` are
of length equal to their sizes, and placed at specific bit boundaries (and
not byte boundaries) to
-eliminate padding. But `L3` is of a non-packable float type (because
+eliminate padding. But ``L3`` is of a non-packable float type (because
it is aliased), so it is on the next appropriate alignment boundary.
-The next two fields are fully packable, so `L4` and `L5` are
-minimally packed with no gaps. However, type `Rb2` is a packed
+The next two fields are fully packable, so ``L4`` and ``L5`` are
+minimally packed with no gaps. However, type ``Rb2`` is a packed
array that is longer than 64 bits, so it is itself non-packable. Thus
-the `L6` field is aligned to the next byte boundary, and takes an
+the ``L6`` field is aligned to the next byte boundary, and takes an
integral number of bytes, i.e., 72 bits.
.. _Record_Representation_Clauses:
.. index:: Component Clause
For all components of an elementary type, the only restriction on component
-clauses is that the size must be at least the 'Size value of the type
+clauses is that the size must be at least the ``'Size`` value of the type
(actually the Value_Size). There are no restrictions due to alignment,
and such components may freely cross storage boundaries.
pragma Pack (R);
for R'Size use 49;
-then a component clause for a component of type R may start on any
+then a component clause for a component of type ``R`` may start on any
specified bit boundary, and may specify a value of 49 bits or greater.
For packed bit arrays that are longer than 64 bits, there are two
tag. When a tagged type appears as a component, the tag field must have
proper alignment
-In the case of a record extension T1, of a type T, no component clause applied
-to the type T1 can specify a storage location that would overlap the first
-T'Size bytes of the record.
+In the case of a record extension ``T1``, of a type ``T``, no component clause applied
+to the type ``T1`` can specify a storage location that would overlap the first
+``T'Size`` bytes of the record.
For all other component types, including non-bit-packed arrays,
the component can be placed at an arbitrary bit boundary,
R at 0 range 82 .. 161;
end record;
-Note: the above rules apply to recent releases of GNAT 5.
-In GNAT 3, there are more severe restrictions on larger components.
-For composite types, including packed arrays with a size greater than
-64 bits, component clauses must respect the alignment requirement of the
-type, in particular, always starting on a byte boundary, and the length
-must be a multiple of the storage unit.
-
.. _Handling_of_Records_with_Holes:
Handling of Records with Holes
type t is array (r) of Character;
The array type t corresponds to a vector with exactly three elements and
-has a default size equal to `3*Character'Size`. This ensures efficient
+has a default size equal to ``3*Character'Size``. This ensures efficient
use of space, but means that accesses to elements of the array will incur
the overhead of converting representation values to the corresponding
-positional values, (i.e., the value delivered by the `Pos` attribute).
+positional values, (i.e., the value delivered by the ``Pos`` attribute).
.. _Address_Clauses:
Additionally, GNAT treats as static an address clause that is an
unchecked_conversion of a static integer value. This simplifies the porting
of legacy code, and provides a portable equivalent to the GNAT attribute
-`To_Address`.
+``To_Address``.
Another issue with address clauses is the interaction with alignment
requirements. When an address clause is given for an object, the address
machines with strict alignment requirements, GNAT
checks (at compile time if possible, generating a warning, or at execution
time with a run-time check) that the alignment is appropriate. If the
-run-time check fails, then `Program_Error` is raised. This run-time
+run-time check fails, then ``Program_Error`` is raised. This run-time
check is suppressed if range checks are suppressed, or if the special GNAT
check Alignment_Check is suppressed, or if
-`pragma Restrictions (No_Elaboration_Code)` is in effect. It is also
+``pragma Restrictions (No_Elaboration_Code)`` is in effect. It is also
suppressed by default on non-strict alignment machines (such as the x86).
Finally, GNAT does not permit overlaying of objects of class-wide types. In
for B'Address use Addr;
-In both of these cases, `A` and `B` become aliased to one another
+In both of these cases, ``A`` and ``B`` become aliased to one another
via the address clause. This use of address clauses to overlay
variables, achieving an effect similar to unchecked conversion
was erroneous in Ada 83, but in Ada 95 and Ada 2005
the effect is implementation defined. Furthermore, the
Ada RM specifically recommends that in a situation
-like this, `B` should be subject to the following
+like this, ``B`` should be subject to the following
implementation advice (RM 13.3(19)):
"19 If the Address of an object is specified, or it is imported
optimizations based on assumptions of no aliases."
GNAT follows this recommendation, and goes further by also applying
-this recommendation to the overlaid variable (`A` in the above example)
+this recommendation to the overlaid variable (``A`` in the above example)
in this case. This means that the overlay works "as expected", in that
a modification to one of the variables will affect the value of the other.
More generally, GNAT interprets this recommendation conservatively for
address clauses: in the cases other than overlays, it considers that the
-object is effectively subject to pragma `Volatile` and implements the
+object is effectively subject to pragma ``Volatile`` and implements the
associated semantics.
Note that when address clause overlays are used in this way, there is an
end Overwrite_Record;
-Here the default initialization of `Y` will clobber the value
-of `X`, which justifies the warning. The warning notes that
-this effect can be eliminated by adding a `pragma Import`
+Here the default initialization of ``Y`` will clobber the value
+of ``X``, which justifies the warning. The warning notes that
+this effect can be eliminated by adding a ``pragma Import``
which suppresses the initialization:
.. code-block:: ada
end Overwrite_Record;
-Note that the use of `pragma Initialize_Scalars` may cause variables to
+Note that the use of ``pragma Initialize_Scalars`` may cause variables to
be initialized when they would not otherwise have been in the absence
of the use of this pragma. This may cause an overlay to have this
unintended clobbering effect. The compiler avoids this for scalar
types, but not for composite objects (where in general the effect
-of `Initialize_Scalars` is part of the initialization routine
+of ``Initialize_Scalars`` is part of the initialization routine
for the composite object:
::
end Overwrite_Array;
The above program generates the warning as shown, and at execution
-time, prints `X was clobbered`. If the `pragma Import` is
+time, prints ``X was clobbered``. If the ``pragma Import`` is
added as suggested:
.. code-block:: ada
end Overwrite_Array;
then the program compiles without the warning and when run will generate
-the output `X was not clobbered`.
+the output ``X was not clobbered``.
.. _Use_of_Address_Clauses_for_Memory-Mapped_I/O:
components to be atomic if you want the byte store, or explicitly writing
the full word access sequence if that is what the hardware requires.
Alternatively, if the full word access sequence is required, GNAT also
-provides the pragma `Volatile_Full_Access` which can be used in lieu of
-pragma `Atomic` and will give the additional guarantee.
+provides the pragma ``Volatile_Full_Access`` which can be used in lieu of
+pragma ``Atomic`` and will give the additional guarantee.
.. _Effect_of_Convention_on_Representation:
type Color is (Red, Green, Blue);
8 bits is sufficient to store all values of the type, so by default, objects
- of type `Color` will be represented using 8 bits. However, normal C
+ of type ``Color`` will be represented using 8 bits. However, normal C
convention is to use 32 bits for all enum values in C, since enum values
- are essentially of type int. If pragma `Convention C` is specified for an
+ are essentially of type int. If pragma ``Convention C`` is specified for an
Ada enumeration type, then the size is modified as necessary (usually to
32 bits) to be consistent with the C convention for enum values.
true. In Ada, the normal convention is that two specific values, typically
0/1, are used to represent false/true respectively.
- Fortran has a similar convention for `LOGICAL` values (any nonzero
+ Fortran has a similar convention for ``LOGICAL`` values (any nonzero
value represents true).
To accommodate the Fortran and C conventions, if a pragma Convention specifies
of what the compiler actually does. For example, if a partial record
representation clause specifies the location of some components and not
others, then where are the non-specified components placed? Or if pragma
-`Pack` is used on a record, then exactly where are the resulting
-fields placed? The section on pragma `Pack` in this chapter can be
+``Pack`` is used on a record, then exactly where are the resulting
+fields placed? The section on pragma ``Pack`` in this chapter can be
used to answer the second question, but it is often easier to just see
what the compiler does.
of the parent type of r2, i.e., r1.
The component size and size clauses for types rb1 and rb2 show
-the exact effect of pragma `Pack` on these arrays, and the record
+the exact effect of pragma ``Pack`` on these arrays, and the record
representation clause for type x2 shows how pragma `Pack` affects
this record type.
.. index:: Max_Entry_Queue_Depth
-The restriction `Max_Entry_Queue_Depth` is recognized as a
-synonym for `Max_Entry_Queue_Length`. This is retained for historical
+The restriction ``Max_Entry_Queue_Depth`` is recognized as a
+synonym for ``Max_Entry_Queue_Length``. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on obsolescent features are activated).
.. index:: No_Dispatch
[RM H.4] This restriction ensures at compile time that there are no
-occurrences of `T'Class`, for any (tagged) subtype `T`.
+occurrences of ``T'Class``, for any (tagged) subtype ``T``.
No_Dispatching_Calls
--------------------
membership test is allowed in the presence of this restriction, because its
implementation requires no dispatching.
This restriction is comparable to the official Ada restriction
-`No_Dispatch` except that it is a bit less restrictive in that it allows
+``No_Dispatch`` except that it is a bit less restrictive in that it allows
all classwide constructs that do not imply dispatching.
The following example indicates constructs that violate this restriction.
.. index:: No_Dynamic_Interrupts
-The restriction `No_Dynamic_Interrupts` is recognized as a
-synonym for `No_Dynamic_Attachment`. This is retained for historical
+The restriction ``No_Dynamic_Interrupts`` is recognized as a
+synonym for ``No_Dynamic_Attachment``. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on obsolescent features are activated).
are no longer considered controlled when this restriction is in effect:
*
- `Ada.Finalization.Controlled`
+ ``Ada.Finalization.Controlled``
*
- `Ada.Finalization.Limited_Controlled`
+ ``Ada.Finalization.Limited_Controlled``
*
- Derivations from `Controlled` or `Limited_Controlled`
+ Derivations from ``Controlled`` or ``Limited_Controlled``
*
Class-wide types
*
[GNAT] This restriction prevents the compiler from building 'trampolines'.
This is a structure that is built on the stack and contains dynamic
code to be executed at run time. On some targets, a trampoline is
-built for the following features: `Access`,
-`Unrestricted_Access`, or `Address` of a nested subprogram;
+built for the following features: ``Access``,
+``Unrestricted_Access``, or ``Address`` of a nested subprogram;
nested task bodies; primitive operations of nested tagged types.
Trampolines do not work on machines that prevent execution of stack
data. For example, on windows systems, enabling DEP (data execution
version of system.ads for your target --- if it has
Always_Compatible_Rep equal to False, then trampolines are largely
eliminated. In particular, a trampoline is built for the following
-features: `Address` of a nested subprogram;
-`Access` or `Unrestricted_Access` of a nested subprogram,
+features: ``Address`` of a nested subprogram;
+``Access`` or ``Unrestricted_Access`` of a nested subprogram,
but only if pragma Favor_Top_Level applies, or the access type has a
foreign-language convention; primitive operations of nested tagged
types.
.. index:: No_Relative_Delay
[RM D.7] This restriction ensures at compile time that there are no delay
-relative statements and prevents expressions such as `delay 1.23;` from
+relative statements and prevents expressions such as ``delay 1.23;`` from
appearing in source code.
No_Requeue_Statements
.. index:: No_Requeue_Statements
[RM D.7] This restriction ensures at compile time that no requeue statements
-are permitted and prevents keyword `requeue` from being used in source
+are permitted and prevents keyword ``requeue`` from being used in source
code.
.. index:: No_Requeue
-The restriction `No_Requeue` is recognized as a
-synonym for `No_Requeue_Statements`. This is retained for historical
+The restriction ``No_Requeue`` is recognized as a
+synonym for ``No_Requeue_Statements``. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on oNobsolescent features are activated).
[GNAT] This restriction ensures at compile time that the generated code
does not contain any reference to the secondary stack. The secondary
stack is used to implement functions returning unconstrained objects
-(arrays or records) on some targets. Suppresses the allocation of
+(arrays or records) on some targets. Suppresses the allocation of
secondary stacks for tasks (excluding the environment task) at run time.
No_Select_Statements
.. index:: No_Select_Statements
[RM D.7] This restriction ensures at compile time no select statements of any
-kind are permitted, that is the keyword `select` may not appear.
+kind are permitted, that is the keyword ``select`` may not appear.
No_Specific_Termination_Handlers
--------------------------------
.. index:: No_Stream_Optimizations
[GNAT] This restriction affects the performance of stream operations on types
-`String`, `Wide_String` and `Wide_Wide_String`. By default, the
-compiler uses block reads and writes when manipulating `String` objects
+``String``, ``Wide_String`` and ``Wide_Wide_String``. By default, the
+compiler uses block reads and writes when manipulating ``String`` objects
due to their supperior performance. When this restriction is in effect, the
compiler performs all IO operations on a per-character basis.
[GNAT] This restriction ensures at compile/bind time that there are no
stream objects created and no use of stream attributes.
This restriction does not forbid dependences on the package
-`Ada.Streams`. So it is permissible to with
-`Ada.Streams` (or another package that does so itself)
+``Ada.Streams``. So it is permissible to with
+``Ada.Streams`` (or another package that does so itself)
as long as no actual stream objects are created and no
stream attributes are used.
.. index:: No_Task_Attributes_Package
[GNAT] This restriction ensures at compile time that there are no implicit or
-explicit dependencies on the package `Ada.Task_Attributes`.
+explicit dependencies on the package ``Ada.Task_Attributes``.
.. index:: No_Task_Attributes
-The restriction `No_Task_Attributes` is recognized as a synonym
-for `No_Task_Attributes_Package`. This is retained for historical
+The restriction ``No_Task_Attributes`` is recognized as a synonym
+for ``No_Task_Attributes_Package``. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on obsolescent features are activated).
[GNAT] This restriction prevents the declaration of tasks or task types
throughout the partition. It is similar in effect to the use of
-`Max_Tasks => 0` except that violations are caught at compile time
+``Max_Tasks => 0`` except that violations are caught at compile time
and cause an error message to be output either by the compiler or
binder.
[GNAT] This restriction ensures at compile time that protected entry
barriers are restricted to:
-* simple variables defined in the private part of the
- protected type/object,
+* components of the protected object (excluding selection from dereferences),
* constant declarations,
* named numbers,
* enumeration literals,
* character literals,
* implicitly defined comparison operators,
* uses of the Standard."not" operator,
-* short-circuit operator
+* short-circuit operator,
+* the Count attribute
This restriction is a relaxation of the Simple_Barriers restriction,
but still ensures absence of side effects, exceptions, and recursion
.. index:: Boolean_Entry_Barriers
-The restriction `Boolean_Entry_Barriers` is recognized as a
-synonym for `Simple_Barriers`. This is retained for historical
+The restriction ``Boolean_Entry_Barriers`` is recognized as a
+synonym for ``Simple_Barriers``. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on obsolescent features are activated).
[GNAT] This restriction ensures at compile time that all priority expressions
are static, and that there are no dependences on the package
-`Ada.Dynamic_Priorities`.
+``Ada.Dynamic_Priorities``.
Static_Storage_Size
-------------------
[GNAT] This restriction ensures at compile time that no elaboration code is
generated. Note that this is not the same condition as is enforced
-by pragma `Preelaborate`. There are cases in which pragma
-`Preelaborate` still permits code to be generated (e.g., code
+by pragma ``Preelaborate``. There are cases in which pragma
+``Preelaborate`` still permits code to be generated (e.g., code
to initialize a large array to all zeroes), and there are cases of units
-which do not meet the requirements for pragma `Preelaborate`,
+which do not meet the requirements for pragma ``Preelaborate``,
but for which no elaboration code is generated. Generally, it is
the case that preelaborable units will meet the restrictions, with
the exception of large aggregates initialized with an others_clause,
In the case of aggregates with others, if the aggregate has a dynamic
size, there is no way to eliminate the elaboration code (such dynamic
-bounds would be incompatible with `Preelaborate` in any case). If
+bounds would be incompatible with ``Preelaborate`` in any case). If
the bounds are static, then use of this restriction actually modifies
the code choice of the compiler to avoid generating a loop, and instead
generate the aggregate statically if possible, no matter how many times
.. index:: No_Implementation_Restrictions
[GNAT] This restriction checks at compile time that no GNAT-defined restriction
-identifiers (other than `No_Implementation_Restrictions` itself)
+identifiers (other than ``No_Implementation_Restrictions`` itself)
are present. With this restriction, the only other restriction identifiers
that can be used are those defined in the Ada Reference Manual.
.. index:: No_Implicit_Loops
[GNAT] This restriction ensures that the generated code of the unit marked
-with this restriction does not contain any implicit `for` loops, either by
+with this restriction does not contain any implicit ``for`` loops, either by
modifying the generated code where possible, or by rejecting any construct
-that would otherwise generate an implicit `for` loop. If this restriction is
+that would otherwise generate an implicit ``for`` loop. If this restriction is
active, it is possible to build large array aggregates with all static
components without generating an intermediate temporary, and without generating
a loop to initialize individual components. Otherwise, a loop is created for
.. index:: No_Wide_Characters
[GNAT] This restriction ensures at compile time that no uses of the types
-`Wide_Character` or `Wide_String` or corresponding wide
+``Wide_Character`` or ``Wide_String`` or corresponding wide
wide types
appear, and that no wide or wide wide string or character literals
appear in the program (that is literals representing characters not in
-type `Character`).
+type ``Character``).
SPARK_05
--------
.. index:: SPARK
-The restriction `SPARK` is recognized as a
-synonym for `SPARK_05`. This is retained for historical
+The restriction ``SPARK`` is recognized as a
+synonym for ``SPARK_05``. This is retained for historical
compatibility purposes (and an unconditional warning will be generated
-for its use, advising replacement by `SPARK`).
+for its use, advising replacement by ``SPARK``).
This is not a replacement for the semantic checks performed by the
SPARK Examiner tool, as the compiler currently only deals with code,
Thus it may well be the case that code which passes the compiler with
the SPARK restriction is rejected by the SPARK Examiner, e.g. due to
the different visibility rules of the Examiner based on SPARK 2005
-`inherit` annotations.
+``inherit`` annotations.
This restriction can be useful in providing an initial filter for code
developed using SPARK 2005, or in examining legacy code to see how far
``Ada.Assertions`` *(11.4.2)*
- `Assertions` provides the `Assert` subprograms, and also
- the declaration of the `Assertion_Error` exception.
+ ``Assertions`` provides the ``Assert`` subprograms, and also
+ the declaration of the ``Assertion_Error`` exception.
``Ada.Asynchronous_Task_Control`` *(D.11)*
- `Asynchronous_Task_Control` provides low level facilities for task
+ ``Asynchronous_Task_Control`` provides low level facilities for task
synchronization. It is typically not implemented. See package spec for details.
``Ada.Calendar`` *(9.6)*
- `Calendar` provides time of day access, and routines for
+ ``Calendar`` provides time of day access, and routines for
manipulating times and durations.
``Ada.Calendar.Arithmetic`` *(9.6.1)*
This package provides additional arithmetic
- operations for `Calendar`.
+ operations for ``Calendar``.
``Ada.Calendar.Formatting`` *(9.6.1)*
- This package provides formatting operations for `Calendar`.
+ This package provides formatting operations for ``Calendar``.
``Ada.Calendar.Time_Zones`` *(9.6.1)*
- This package provides additional `Calendar` facilities
+ This package provides additional ``Calendar`` facilities
for handling time zones.
that appear in type CHARACTER. It is useful for writing programs that
will run in international environments. For example, if you want an
upper case E with an acute accent in a string, it is often better to use
- the definition of `UC_E_Acute` in this package. Then your program
+ the definition of ``UC_E_Acute`` in this package. Then your program
will print in an understandable manner even if your environment does not
support these extended characters.
``Ada.Command_Line`` *(A.15)*
This package provides access to the command line parameters and the name
- of the current program (analogous to the use of `argc` and `argv`
+ of the current program (analogous to the use of ``argc`` and ``argv``
in C), and also allows the exit status for the program to be set in a
system-independent manner.
``Ada.Locales`` *(A.19)*
This package provides declarations providing information (Language
- and Country) about the current locale.
+ and Country) about the current locale. This package is currently not
+ implemented other than by providing stubs which will always return
+ Language_Unknown/Country_Unknown.
``Ada.Numerics``
``Ada.Numerics.Complex_Elementary_Functions``
Provides the implementation of standard elementary functions (such as
log and trigonometric functions) operating on complex numbers using the
- standard `Float` and the `Complex` and `Imaginary` types
- created by the package `Numerics.Complex_Types`.
+ standard ``Float`` and the ``Complex`` and ``Imaginary`` types
+ created by the package ``Numerics.Complex_Types``.
``Ada.Numerics.Complex_Types``
This is a predefined instantiation of
- `Numerics.Generic_Complex_Types` using `Standard.Float` to
- build the type `Complex` and `Imaginary`.
+ ``Numerics.Generic_Complex_Types`` using ``Standard.Float`` to
+ build the type ``Complex`` and ``Imaginary``.
``Ada.Numerics.Discrete_Random``
* ``Short_Float``
- `Ada.Numerics.Short_Complex_Elementary_Functions`
+ ``Ada.Numerics.Short_Complex_Elementary_Functions``
* ``Float``
- `Ada.Numerics.Complex_Elementary_Functions`
+ ``Ada.Numerics.Complex_Elementary_Functions``
* ``Long_Float``
- `Ada.Numerics.Long_Complex_Elementary_Functions`
+ ``Ada.Numerics.Long_Complex_Elementary_Functions``
``Ada.Numerics.Generic_Complex_Types``
This is a generic package that allows the creation of complex types,
* ``Short_Float``
- `Ada.Numerics.Short_Complex_Complex_Types`
+ ``Ada.Numerics.Short_Complex_Complex_Types``
* ``Float``
- `Ada.Numerics.Complex_Complex_Types`
+ ``Ada.Numerics.Complex_Complex_Types``
* ``Long_Float``
- `Ada.Numerics.Long_Complex_Complex_Types`
+ ``Ada.Numerics.Long_Complex_Complex_Types``
``Ada.Numerics.Generic_Elementary_Functions``
This is a generic package that provides the implementation of standard
* ``Short_Float``
- `Ada.Numerics.Short_Elementary_Functions`
+ ``Ada.Numerics.Short_Elementary_Functions``
* ``Float``
- `Ada.Numerics.Elementary_Functions`
+ ``Ada.Numerics.Elementary_Functions``
* ``Long_Float``
- `Ada.Numerics.Long_Elementary_Functions`
+ ``Ada.Numerics.Long_Elementary_Functions``
``Ada.Numerics.Generic_Real_Arrays`` *(G.3.1)*
Generic operations on arrays of reals
Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float).
``Ada.Real_Time`` *(D.8)*
- This package provides facilities similar to those of `Calendar`, but
+ This package provides facilities similar to those of ``Calendar``, but
operating with a finer clock suitable for real time control. Note that
annex D requires that there be no backward clock jumps, and GNAT generally
guarantees this behavior, but of course if the external clock on which
``Ada.Streams`` *(13.13.1)*
This is a generic package that provides the basic support for the
- concept of streams as used by the stream attributes (`Input`,
- `Output`, `Read` and `Write`).
+ concept of streams as used by the stream attributes (``Input``,
+ ``Output``, ``Read`` and ``Write``).
``Ada.Streams.Stream_IO`` *(A.12.1)*
- This package is a specialization of the type `Streams` defined in
- package `Streams` together with a set of operations providing
+ This package is a specialization of the type ``Streams`` defined in
+ package ``Streams`` together with a set of operations providing
Stream_IO capability. The Stream_IO model permits both random and
sequential access to a file which can contain an arbitrary set of values
of one or more Ada types.
``Ada.Strings.Wide_Unbounded`` *(A.4.7)*
These packages provide analogous capabilities to the corresponding
packages without ``Wide_`` in the name, but operate with the types
- `Wide_String` and `Wide_Character` instead of `String`
- and `Character`. Versions of all the child packages are available.
+ ``Wide_String`` and ``Wide_Character`` instead of ``String``
+ and ``Character``. Versions of all the child packages are available.
``Ada.Strings.Wide_Wide_Bounded`` *(A.4.7)*
``Ada.Strings.Wide_Wide_Unbounded`` *(A.4.7)*
These packages provide analogous capabilities to the corresponding
packages without ``Wide_`` in the name, but operate with the types
- `Wide_Wide_String` and `Wide_Wide_Character` instead
- of `String` and `Character`.
+ ``Wide_Wide_String`` and ``Wide_Wide_Character`` instead
+ of ``String`` and ``Character``.
``Ada.Synchronous_Barriers`` *(D.10.1)*
This package provides facilities for synchronizing tasks at a low level
* ``Short_Float``
- `Short_Float_Text_IO`
+ ``Short_Float_Text_IO``
* ``Float``
- `Float_Text_IO`
+ ``Float_Text_IO``
* ``Long_Float``
- `Long_Float_Text_IO`
+ ``Long_Float_Text_IO``
``Ada.Text_IO.Integer_IO``
Provides input-output facilities for integer types. The following
* ``Short_Short_Integer``
- `Ada.Short_Short_Integer_Text_IO`
+ ``Ada.Short_Short_Integer_Text_IO``
* ``Short_Integer``
- `Ada.Short_Integer_Text_IO`
+ ``Ada.Short_Integer_Text_IO``
* ``Integer``
- `Ada.Integer_Text_IO`
+ ``Ada.Integer_Text_IO``
* ``Long_Integer``
- `Ada.Long_Integer_Text_IO`
+ ``Ada.Long_Integer_Text_IO``
* ``Long_Long_Integer``
- `Ada.Long_Long_Integer_Text_IO`
+ ``Ada.Long_Long_Integer_Text_IO``
``Ada.Text_IO.Modular_IO``
Provides input-output facilities for modular (unsigned) types.
allocated by use of an allocator.
``Ada.Wide_Text_IO`` *(A.11)*
- This package is similar to `Ada.Text_IO`, except that the external
+ This package is similar to ``Ada.Text_IO``, except that the external
file supports wide character representations, and the internal types are
- `Wide_Character` and `Wide_String` instead of `Character`
- and `String`. The corresponding set of nested packages and child
+ ``Wide_Character`` and ``Wide_String`` instead of ``Character``
+ and ``String``. The corresponding set of nested packages and child
packages are defined.
``Ada.Wide_Wide_Text_IO`` *(A.11)*
- This package is similar to `Ada.Text_IO`, except that the external
+ This package is similar to ``Ada.Text_IO``, except that the external
file supports wide character representations, and the internal types are
- `Wide_Character` and `Wide_String` instead of `Character`
- and `String`. The corresponding set of nested packages and child
+ ``Wide_Character`` and ``Wide_String`` instead of ``Character``
+ and ``String``. The corresponding set of nested packages and child
packages are defined.
For packages in Interfaces and System, all the RM defined packages are
+.. role:: switch(samp)
+
.. _The_GNAT_Library:
****************
the SPITBOL pattern matching capability, including a full tutorial and
extensive examples, look in the :file:`g-spipat.ads` file in the library.
-For each entry here, the package name (as it would appear in a `with`
+For each entry here, the package name (as it would appear in a ``with``
clause) is given, followed by the name of the corresponding spec file in
-parentheses. The packages are children in four hierarchies, `Ada`,
-`Interfaces`, `System`, and `GNAT`, the latter being a
+parentheses. The packages are children in four hierarchies, ``Ada``,
+``Interfaces``, ``System``, and ``GNAT``, the latter being a
GNAT-specific hierarchy.
Note that an application program should only use packages in one of these
four hierarchies if the package is defined in the Ada Reference Manual,
or is listed in this section of the GNAT Programmers Reference Manual.
All other units should be considered internal implementation units and
-should not be directly `with`'ed by application code. The use of
-a `with` statement that references one of these internal implementation
+should not be directly ``with``\ ed by application code. The use of
+a ``with`` clause that references one of these internal implementation
units makes an application potentially dependent on changes in versions
of GNAT, and will generate a warning message.
.. _`Ada.Characters.Latin_9_(a-chlat9.ads)`:
-`Ada.Characters.Latin_9` (:file:`a-chlat9.ads`)
-===============================================
+``Ada.Characters.Latin_9`` (:file:`a-chlat9.ads`)
+=================================================
.. index:: Ada.Characters.Latin_9 (a-chlat9.ads)
.. index:: Latin_9 constants for Character
-This child of `Ada.Characters`
+This child of ``Ada.Characters``
provides a set of definitions corresponding to those in the
-RM-defined package `Ada.Characters.Latin_1` but with the
-few modifications required for `Latin-9`
+RM-defined package ``Ada.Characters.Latin_1`` but with the
+few modifications required for ``Latin-9``
The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
.. _`Ada.Characters.Wide_Latin_1_(a-cwila1.ads)`:
-`Ada.Characters.Wide_Latin_1` (:file:`a-cwila1.ads`)
-====================================================
+``Ada.Characters.Wide_Latin_1`` (:file:`a-cwila1.ads`)
+======================================================
.. index:: Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
.. index:: Latin_1 constants for Wide_Character
-This child of `Ada.Characters`
+This child of ``Ada.Characters``
provides a set of definitions corresponding to those in the
-RM-defined package `Ada.Characters.Latin_1` but with the
-types of the constants being `Wide_Character`
-instead of `Character`. The provision of such a package
+RM-defined package ``Ada.Characters.Latin_1`` but with the
+types of the constants being ``Wide_Character``
+instead of ``Character``. The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
.. _`Ada.Characters.Wide_Latin_9_(a-cwila1.ads)`:
-`Ada.Characters.Wide_Latin_9` (:file:`a-cwila1.ads`)
-====================================================
+``Ada.Characters.Wide_Latin_9`` (:file:`a-cwila1.ads`)
+======================================================
.. index:: Ada.Characters.Wide_Latin_9 (a-cwila1.ads)
.. index:: Latin_9 constants for Wide_Character
-This child of `Ada.Characters`
+This child of ``Ada.Characters``
provides a set of definitions corresponding to those in the
-GNAT defined package `Ada.Characters.Latin_9` but with the
-types of the constants being `Wide_Character`
-instead of `Character`. The provision of such a package
+GNAT defined package ``Ada.Characters.Latin_9`` but with the
+types of the constants being ``Wide_Character``
+instead of ``Character``. The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
.. _`Ada.Characters.Wide_Wide_Latin_1_(a-chzla1.ads)`:
-`Ada.Characters.Wide_Wide_Latin_1` (:file:`a-chzla1.ads`)
-=========================================================
+``Ada.Characters.Wide_Wide_Latin_1`` (:file:`a-chzla1.ads`)
+===========================================================
.. index:: Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
.. index:: Latin_1 constants for Wide_Wide_Character
-This child of `Ada.Characters`
+This child of ``Ada.Characters``
provides a set of definitions corresponding to those in the
-RM-defined package `Ada.Characters.Latin_1` but with the
-types of the constants being `Wide_Wide_Character`
-instead of `Character`. The provision of such a package
+RM-defined package ``Ada.Characters.Latin_1`` but with the
+types of the constants being ``Wide_Wide_Character``
+instead of ``Character``. The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
.. _`Ada.Characters.Wide_Wide_Latin_9_(a-chzla9.ads)`:
-`Ada.Characters.Wide_Wide_Latin_9` (:file:`a-chzla9.ads`)
-=========================================================
+``Ada.Characters.Wide_Wide_Latin_9`` (:file:`a-chzla9.ads`)
+===========================================================
.. index:: Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
.. index:: Latin_9 constants for Wide_Wide_Character
-This child of `Ada.Characters`
+This child of ``Ada.Characters``
provides a set of definitions corresponding to those in the
-GNAT defined package `Ada.Characters.Latin_9` but with the
-types of the constants being `Wide_Wide_Character`
-instead of `Character`. The provision of such a package
+GNAT defined package ``Ada.Characters.Latin_9`` but with the
+types of the constants being ``Wide_Wide_Character``
+instead of ``Character``. The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
.. _`Ada.Containers.Formal_Doubly_Linked_Lists_(a-cfdlli.ads)`:
-`Ada.Containers.Formal_Doubly_Linked_Lists` (:file:`a-cfdlli.ads`)
-==================================================================
+``Ada.Containers.Formal_Doubly_Linked_Lists`` (:file:`a-cfdlli.ads`)
+====================================================================
.. index:: Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)
.. index:: Formal container for doubly linked lists
-This child of `Ada.Containers` defines a modified version of the
+This child of ``Ada.Containers`` defines a modified version of the
Ada 2005 container for doubly linked lists, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
.. _`Ada.Containers.Formal_Hashed_Maps_(a-cfhama.ads)`:
-`Ada.Containers.Formal_Hashed_Maps` (:file:`a-cfhama.ads`)
-==========================================================
+``Ada.Containers.Formal_Hashed_Maps`` (:file:`a-cfhama.ads`)
+============================================================
.. index:: Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)
.. index:: Formal container for hashed maps
-This child of `Ada.Containers` defines a modified version of the
+This child of ``Ada.Containers`` defines a modified version of the
Ada 2005 container for hashed maps, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
.. _`Ada.Containers.Formal_Hashed_Sets_(a-cfhase.ads)`:
-`Ada.Containers.Formal_Hashed_Sets` (:file:`a-cfhase.ads`)
-==========================================================
+``Ada.Containers.Formal_Hashed_Sets`` (:file:`a-cfhase.ads`)
+============================================================
.. index:: Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)
.. index:: Formal container for hashed sets
-This child of `Ada.Containers` defines a modified version of the
+This child of ``Ada.Containers`` defines a modified version of the
Ada 2005 container for hashed sets, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
.. _`Ada.Containers.Formal_Ordered_Maps_(a-cforma.ads)`:
-`Ada.Containers.Formal_Ordered_Maps` (:file:`a-cforma.ads`)
-===========================================================
+``Ada.Containers.Formal_Ordered_Maps`` (:file:`a-cforma.ads`)
+=============================================================
.. index:: Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)
.. index:: Formal container for ordered maps
-This child of `Ada.Containers` defines a modified version of the
+This child of ``Ada.Containers`` defines a modified version of the
Ada 2005 container for ordered maps, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
.. _`Ada.Containers.Formal_Ordered_Sets_(a-cforse.ads)`:
-`Ada.Containers.Formal_Ordered_Sets` (:file:`a-cforse.ads`)
-===========================================================
+``Ada.Containers.Formal_Ordered_Sets`` (:file:`a-cforse.ads`)
+=============================================================
.. index:: Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)
.. index:: Formal container for ordered sets
-This child of `Ada.Containers` defines a modified version of the
+This child of ``Ada.Containers`` defines a modified version of the
Ada 2005 container for ordered sets, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
.. _`Ada.Containers.Formal_Vectors_(a-cofove.ads)`:
-`Ada.Containers.Formal_Vectors` (:file:`a-cofove.ads`)
-======================================================
+``Ada.Containers.Formal_Vectors`` (:file:`a-cofove.ads`)
+========================================================
.. index:: Ada.Containers.Formal_Vectors (a-cofove.ads)
.. index:: Formal container for vectors
-This child of `Ada.Containers` defines a modified version of the
+This child of ``Ada.Containers`` defines a modified version of the
Ada 2005 container for vectors, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
.. _`Ada.Containers.Formal_Indefinite_Vectors_(a-cfinve.ads)`:
-`Ada.Containers.Formal_Indefinite_Vectors` (:file:`a-cfinve.ads`)
-=================================================================
+``Ada.Containers.Formal_Indefinite_Vectors`` (:file:`a-cfinve.ads`)
+===================================================================
.. index:: Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads)
.. index:: Formal container for vectors
-This child of `Ada.Containers` defines a modified version of the
+This child of ``Ada.Containers`` defines a modified version of the
Ada 2005 container for vectors of indefinite elements, meant to
facilitate formal verification of code using such containers. The
specification of this unit is compatible with SPARK 2014.
efficient version than the one defined in the standard. In particular it
does not have the complex overhead required to detect cursor tampering.
+.. _`Ada.Containers.Functional_Vectors_(a-cofuve.ads)`:
+
+``Ada.Containers.Functional_Vectors`` (:file:`a-cofuve.ads`)
+=================================================================
+
+.. index:: Ada.Containers.Functional_Vectors (a-cofuve.ads)
+
+.. index:: Functional vectors
+
+This child of ``Ada.Containers`` defines immutable vectors. These
+containers are unbounded and may contain indefinite elements. Furthermore, to
+be usable in every context, they are neither controlled nor limited. As they
+are functional, that is, no primitives are provided which would allow modifying
+an existing container, these containers can still be used safely.
+
+Their API features functions creating new containers from existing ones.
+As a consequence, these containers are highly inefficient. They are also
+memory consuming, as the allocated memory is not reclaimed when the container
+is no longer referenced. Thus, they should in general be used in ghost code
+and annotations, so that they can be removed from the final executable. The
+specification of this unit is compatible with SPARK 2014.
+
+.. _`Ada.Containers.Functional_Sets_(a-cofuse.ads)`:
+
+``Ada.Containers.Functional_Sets`` (:file:`a-cofuse.ads`)
+=================================================================
+
+.. index:: Ada.Containers.Functional_Sets (a-cofuse.ads)
+
+.. index:: Functional sets
+
+This child of ``Ada.Containers`` defines immutable sets. These containers are
+unbounded and may contain indefinite elements. Furthermore, to be usable in
+every context, they are neither controlled nor limited. As they are functional,
+that is, no primitives are provided which would allow modifying an existing
+container, these containers can still be used safely.
+
+Their API features functions creating new containers from existing ones.
+As a consequence, these containers are highly inefficient. They are also
+memory consuming, as the allocated memory is not reclaimed when the container
+is no longer referenced. Thus, they should in general be used in ghost code
+and annotations, so that they can be removed from the final executable. The
+specification of this unit is compatible with SPARK 2014.
+
+.. _`Ada.Containers.Functional_Maps_(a-cofuma.ads)`:
+
+``Ada.Containers.Functional_Maps`` (:file:`a-cofuma.ads`)
+=================================================================
+
+.. index:: Ada.Containers.Functional_Maps (a-cofuma.ads)
+
+.. index:: Functional maps
+
+This child of ``Ada.Containers`` defines immutable maps. These containers are
+unbounded and may contain indefinite elements. Furthermore, to be usable in
+every context, they are neither controlled nor limited. As they are functional,
+that is, no primitives are provided which would allow modifying an existing
+container, these containers can still be used safely.
+
+Their API features functions creating new containers from existing ones.
+As a consequence, these containers are highly inefficient. They are also
+memory consuming, as the allocated memory is not reclaimed when the container
+is no longer referenced. Thus, they should in general be used in ghost code
+and annotations, so that they can be removed from the final executable. The
+specification of this unit is compatible with SPARK 2014.
+
.. _`Ada.Containers.Bounded_Holders_(a-coboho.ads)`:
-`Ada.Containers.Bounded_Holders` (:file:`a-coboho.ads`)
-=======================================================
+``Ada.Containers.Bounded_Holders`` (:file:`a-coboho.ads`)
+=========================================================
.. index:: Ada.Containers.Bounded_Holders (a-coboho.ads)
.. index:: Formal container for vectors
-This child of `Ada.Containers` defines a modified version of
+This child of ``Ada.Containers`` defines a modified version of
Indefinite_Holders that avoids heap allocation.
.. _`Ada.Command_Line.Environment_(a-colien.ads)`:
-`Ada.Command_Line.Environment` (:file:`a-colien.ads`)
-=====================================================
+``Ada.Command_Line.Environment`` (:file:`a-colien.ads`)
+=======================================================
.. index:: Ada.Command_Line.Environment (a-colien.ads)
.. index:: Environment entries
-This child of `Ada.Command_Line`
+This child of ``Ada.Command_Line``
provides a mechanism for obtaining environment values on systems
where this concept makes sense.
.. _`Ada.Command_Line.Remove_(a-colire.ads)`:
-`Ada.Command_Line.Remove` (:file:`a-colire.ads`)
-================================================
+``Ada.Command_Line.Remove`` (:file:`a-colire.ads`)
+==================================================
.. index:: Ada.Command_Line.Remove (a-colire.ads)
.. index:: Command line, argument removal
-This child of `Ada.Command_Line`
+This child of ``Ada.Command_Line``
provides a mechanism for logically removing
arguments from the argument list. Once removed, an argument is not visible
-to further calls on the subprograms in `Ada.Command_Line` will not
+to further calls on the subprograms in ``Ada.Command_Line`` will not
see the removed argument.
.. _`Ada.Command_Line.Response_File_(a-clrefi.ads)`:
-`Ada.Command_Line.Response_File` (:file:`a-clrefi.ads`)
-=======================================================
+``Ada.Command_Line.Response_File`` (:file:`a-clrefi.ads`)
+=========================================================
.. index:: Ada.Command_Line.Response_File (a-clrefi.ads)
.. index:: Command line, handling long command lines
-This child of `Ada.Command_Line` provides a mechanism facilities for
+This child of ``Ada.Command_Line`` provides a mechanism facilities for
getting command line arguments from a text file, called a "response file".
Using a response file allow passing a set of arguments to an executable longer
than the maximum allowed by the system on the command line.
.. _`Ada.Direct_IO.C_Streams_(a-diocst.ads)`:
-`Ada.Direct_IO.C_Streams` (:file:`a-diocst.ads`)
-================================================
+``Ada.Direct_IO.C_Streams`` (:file:`a-diocst.ads`)
+==================================================
.. index:: Ada.Direct_IO.C_Streams (a-diocst.ads)
.. index:: C Streams, Interfacing with Direct_IO
This package provides subprograms that allow interfacing between
-C streams and `Direct_IO`. The stream identifier can be
+C streams and ``Direct_IO``. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
.. _`Ada.Exceptions.Is_Null_Occurrence_(a-einuoc.ads)`:
-`Ada.Exceptions.Is_Null_Occurrence` (:file:`a-einuoc.ads`)
-==========================================================
+``Ada.Exceptions.Is_Null_Occurrence`` (:file:`a-einuoc.ads`)
+============================================================
.. index:: Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
.. index:: Null_Occurrence, testing for
This child subprogram provides a way of testing for the null
-exception occurrence (`Null_Occurrence`) without raising
+exception occurrence (``Null_Occurrence``) without raising
an exception.
.. _`Ada.Exceptions.Last_Chance_Handler_(a-elchha.ads)`:
-`Ada.Exceptions.Last_Chance_Handler` (:file:`a-elchha.ads`)
-===========================================================
+``Ada.Exceptions.Last_Chance_Handler`` (:file:`a-elchha.ads`)
+=============================================================
.. index:: Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
.. _`Ada.Exceptions.Traceback_(a-exctra.ads)`:
-`Ada.Exceptions.Traceback` (:file:`a-exctra.ads`)
-=================================================
+``Ada.Exceptions.Traceback`` (:file:`a-exctra.ads`)
+===================================================
.. index:: Ada.Exceptions.Traceback (a-exctra.ads)
.. index:: Traceback for Exception Occurrence
-This child package provides the subprogram (`Tracebacks`) to
+This child package provides the subprogram (``Tracebacks``) to
give a traceback array of addresses based on an exception
occurrence.
.. _`Ada.Sequential_IO.C_Streams_(a-siocst.ads)`:
-`Ada.Sequential_IO.C_Streams` (:file:`a-siocst.ads`)
-====================================================
+``Ada.Sequential_IO.C_Streams`` (:file:`a-siocst.ads`)
+======================================================
.. index:: Ada.Sequential_IO.C_Streams (a-siocst.ads)
.. index:: C Streams, Interfacing with Sequential_IO
This package provides subprograms that allow interfacing between
-C streams and `Sequential_IO`. The stream identifier can be
+C streams and ``Sequential_IO``. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
.. _`Ada.Streams.Stream_IO.C_Streams_(a-ssicst.ads)`:
-`Ada.Streams.Stream_IO.C_Streams` (:file:`a-ssicst.ads`)
-========================================================
+``Ada.Streams.Stream_IO.C_Streams`` (:file:`a-ssicst.ads`)
+==========================================================
.. index:: Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
.. index:: C Streams, Interfacing with Stream_IO
This package provides subprograms that allow interfacing between
-C streams and `Stream_IO`. The stream identifier can be
+C streams and ``Stream_IO``. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
.. _`Ada.Strings.Unbounded.Text_IO_(a-suteio.ads)`:
-`Ada.Strings.Unbounded.Text_IO` (:file:`a-suteio.ads`)
-======================================================
+``Ada.Strings.Unbounded.Text_IO`` (:file:`a-suteio.ads`)
+========================================================
.. index:: Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
.. _`Ada.Strings.Wide_Unbounded.Wide_Text_IO_(a-swuwti.ads)`:
-`Ada.Strings.Wide_Unbounded.Wide_Text_IO` (:file:`a-swuwti.ads`)
-================================================================
+``Ada.Strings.Wide_Unbounded.Wide_Text_IO`` (:file:`a-swuwti.ads`)
+==================================================================
.. index:: Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
.. _`Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO_(a-szuzti.ads)`:
-`Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO` (:file:`a-szuzti.ads`)
-==========================================================================
+``Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO`` (:file:`a-szuzti.ads`)
+============================================================================
.. index:: Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
.. _`Ada.Text_IO.C_Streams_(a-tiocst.ads)`:
-`Ada.Text_IO.C_Streams` (:file:`a-tiocst.ads`)
-==============================================
+``Ada.Text_IO.C_Streams`` (:file:`a-tiocst.ads`)
+================================================
.. index:: Ada.Text_IO.C_Streams (a-tiocst.ads)
-.. index:: C Streams, Interfacing with `Text_IO`
+.. index:: C Streams, Interfacing with ``Text_IO``
This package provides subprograms that allow interfacing between
-C streams and `Text_IO`. The stream identifier can be
+C streams and ``Text_IO``. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
.. _`Ada.Text_IO.Reset_Standard_Files_(a-tirsfi.ads)`:
-`Ada.Text_IO.Reset_Standard_Files` (:file:`a-tirsfi.ads`)
-=========================================================
+``Ada.Text_IO.Reset_Standard_Files`` (:file:`a-tirsfi.ads`)
+===========================================================
.. index:: Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
.. _`Ada.Wide_Characters.Unicode_(a-wichun.ads)`:
-`Ada.Wide_Characters.Unicode` (:file:`a-wichun.ads`)
-====================================================
+``Ada.Wide_Characters.Unicode`` (:file:`a-wichun.ads`)
+======================================================
.. index:: Ada.Wide_Characters.Unicode (a-wichun.ads)
.. _`Ada.Wide_Text_IO.C_Streams_(a-wtcstr.ads)`:
-`Ada.Wide_Text_IO.C_Streams` (:file:`a-wtcstr.ads`)
-===================================================
+``Ada.Wide_Text_IO.C_Streams`` (:file:`a-wtcstr.ads`)
+=====================================================
.. index:: Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
-.. index:: C Streams, Interfacing with `Wide_Text_IO`
+.. index:: C Streams, Interfacing with ``Wide_Text_IO``
This package provides subprograms that allow interfacing between
-C streams and `Wide_Text_IO`. The stream identifier can be
+C streams and ``Wide_Text_IO``. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
.. _`Ada.Wide_Text_IO.Reset_Standard_Files_(a-wrstfi.ads)`:
-`Ada.Wide_Text_IO.Reset_Standard_Files` (:file:`a-wrstfi.ads`)
-==============================================================
+``Ada.Wide_Text_IO.Reset_Standard_Files`` (:file:`a-wrstfi.ads`)
+================================================================
.. index:: Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
.. _`Ada.Wide_Wide_Characters.Unicode_(a-zchuni.ads)`:
-`Ada.Wide_Wide_Characters.Unicode` (:file:`a-zchuni.ads`)
-=========================================================
+``Ada.Wide_Wide_Characters.Unicode`` (:file:`a-zchuni.ads`)
+===========================================================
.. index:: Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
.. _`Ada.Wide_Wide_Text_IO.C_Streams_(a-ztcstr.ads)`:
-`Ada.Wide_Wide_Text_IO.C_Streams` (:file:`a-ztcstr.ads`)
-========================================================
+``Ada.Wide_Wide_Text_IO.C_Streams`` (:file:`a-ztcstr.ads`)
+==========================================================
.. index:: Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
-.. index:: C Streams, Interfacing with `Wide_Wide_Text_IO`
+.. index:: C Streams, Interfacing with ``Wide_Wide_Text_IO``
This package provides subprograms that allow interfacing between
-C streams and `Wide_Wide_Text_IO`. The stream identifier can be
+C streams and ``Wide_Wide_Text_IO``. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
.. _`Ada.Wide_Wide_Text_IO.Reset_Standard_Files_(a-zrstfi.ads)`:
-`Ada.Wide_Wide_Text_IO.Reset_Standard_Files` (:file:`a-zrstfi.ads`)
-===================================================================
+``Ada.Wide_Wide_Text_IO.Reset_Standard_Files`` (:file:`a-zrstfi.ads`)
+=====================================================================
.. index:: Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
.. _`GNAT.Altivec_(g-altive.ads)`:
-`GNAT.Altivec` (:file:`g-altive.ads`)
-=====================================
+``GNAT.Altivec`` (:file:`g-altive.ads`)
+=======================================
.. index:: GNAT.Altivec (g-altive.ads)
.. _`GNAT.Altivec.Conversions_(g-altcon.ads)`:
-`GNAT.Altivec.Conversions` (:file:`g-altcon.ads`)
-=================================================
+``GNAT.Altivec.Conversions`` (:file:`g-altcon.ads`)
+===================================================
.. index:: GNAT.Altivec.Conversions (g-altcon.ads)
.. _`GNAT.Altivec.Vector_Operations_(g-alveop.ads)`:
-`GNAT.Altivec.Vector_Operations` (:file:`g-alveop.ads`)
-=======================================================
+``GNAT.Altivec.Vector_Operations`` (:file:`g-alveop.ads`)
+=========================================================
.. index:: GNAT.Altivec.Vector_Operations (g-alveop.ads)
.. _`GNAT.Altivec.Vector_Types_(g-alvety.ads)`:
-`GNAT.Altivec.Vector_Types` (:file:`g-alvety.ads`)
-==================================================
+``GNAT.Altivec.Vector_Types`` (:file:`g-alvety.ads`)
+====================================================
.. index:: GNAT.Altivec.Vector_Types (g-alvety.ads)
.. _`GNAT.Altivec.Vector_Views_(g-alvevi.ads)`:
-`GNAT.Altivec.Vector_Views` (:file:`g-alvevi.ads`)
-==================================================
+``GNAT.Altivec.Vector_Views`` (:file:`g-alvevi.ads`)
+====================================================
.. index:: GNAT.Altivec.Vector_Views (g-alvevi.ads)
.. _`GNAT.Array_Split_(g-arrspl.ads)`:
-`GNAT.Array_Split` (:file:`g-arrspl.ads`)
-=========================================
+``GNAT.Array_Split`` (:file:`g-arrspl.ads`)
+===========================================
.. index:: GNAT.Array_Split (g-arrspl.ads)
.. _`GNAT.AWK_(g-awk.ads)`:
-`GNAT.AWK` (:file:`g-awk.ads`)
-==============================
+``GNAT.AWK`` (:file:`g-awk.ads`)
+================================
.. index:: GNAT.AWK (g-awk.ads)
.. _`GNAT.Bind_Environment_(g-binenv.ads)`:
-`GNAT.Bind_Environment` (:file:`g-binenv.ads`)
-==============================================
+``GNAT.Bind_Environment`` (:file:`g-binenv.ads`)
+================================================
.. index:: GNAT.Bind_Environment (g-binenv.ads)
.. index:: Bind environment
Provides access to key=value associations captured at bind time.
-These associations can be specified using the `-V` binder command
+These associations can be specified using the :switch:`-V` binder command
line switch.
.. _`GNAT.Bounded_Buffers_(g-boubuf.ads)`:
-`GNAT.Bounded_Buffers` (:file:`g-boubuf.ads`)
-=============================================
+``GNAT.Bounded_Buffers`` (:file:`g-boubuf.ads`)
+===============================================
.. index:: GNAT.Bounded_Buffers (g-boubuf.ads)
.. _`GNAT.Bounded_Mailboxes_(g-boumai.ads)`:
-`GNAT.Bounded_Mailboxes` (:file:`g-boumai.ads`)
-===============================================
+``GNAT.Bounded_Mailboxes`` (:file:`g-boumai.ads`)
+=================================================
.. index:: GNAT.Bounded_Mailboxes (g-boumai.ads)
.. _`GNAT.Bubble_Sort_(g-bubsor.ads)`:
-`GNAT.Bubble_Sort` (:file:`g-bubsor.ads`)
-=========================================
+``GNAT.Bubble_Sort`` (:file:`g-bubsor.ads`)
+===========================================
.. index:: GNAT.Bubble_Sort (g-bubsor.ads)
.. _`GNAT.Bubble_Sort_A_(g-busora.ads)`:
-`GNAT.Bubble_Sort_A` (:file:`g-busora.ads`)
-===========================================
+``GNAT.Bubble_Sort_A`` (:file:`g-busora.ads`)
+=============================================
.. index:: GNAT.Bubble_Sort_A (g-busora.ads)
Provides a general implementation of bubble sort usable for sorting arbitrary
data items. Move and comparison procedures are provided by passing
access-to-procedure values. This is an older version, retained for
-compatibility. Usually `GNAT.Bubble_Sort` will be preferable.
+compatibility. Usually ``GNAT.Bubble_Sort`` will be preferable.
.. _`GNAT.Bubble_Sort_G_(g-busorg.ads)`:
-`GNAT.Bubble_Sort_G` (:file:`g-busorg.ads`)
-===========================================
+``GNAT.Bubble_Sort_G`` (:file:`g-busorg.ads`)
+=============================================
.. index:: GNAT.Bubble_Sort_G (g-busorg.ads)
.. index:: Bubble sort
-Similar to `Bubble_Sort_A` except that the move and sorting procedures
+Similar to ``Bubble_Sort_A`` except that the move and sorting procedures
are provided as generic parameters, this improves efficiency, especially
if the procedures can be inlined, at the expense of duplicating code for
multiple instantiations.
.. _`GNAT.Byte_Order_Mark_(g-byorma.ads)`:
-`GNAT.Byte_Order_Mark` (:file:`g-byorma.ads`)
-=============================================
+``GNAT.Byte_Order_Mark`` (:file:`g-byorma.ads`)
+===============================================
.. index:: GNAT.Byte_Order_Mark (g-byorma.ads)
.. _`GNAT.Byte_Swapping_(g-bytswa.ads)`:
-`GNAT.Byte_Swapping` (:file:`g-bytswa.ads`)
-===========================================
+``GNAT.Byte_Swapping`` (:file:`g-bytswa.ads`)
+=============================================
.. index:: GNAT.Byte_Swapping (g-bytswa.ads)
.. _`GNAT.Calendar_(g-calend.ads)`:
-`GNAT.Calendar` (:file:`g-calend.ads`)
-======================================
+``GNAT.Calendar`` (:file:`g-calend.ads`)
+========================================
.. index:: GNAT.Calendar (g-calend.ads)
.. index:: Calendar
-Extends the facilities provided by `Ada.Calendar` to include handling
-of days of the week, an extended `Split` and `Time_Of` capability.
-Also provides conversion of `Ada.Calendar.Time` values to and from the
-C `timeval` format.
+Extends the facilities provided by ``Ada.Calendar`` to include handling
+of days of the week, an extended ``Split`` and ``Time_Of`` capability.
+Also provides conversion of ``Ada.Calendar.Time`` values to and from the
+C ``timeval`` format.
.. _`GNAT.Calendar.Time_IO_(g-catiio.ads)`:
-`GNAT.Calendar.Time_IO` (:file:`g-catiio.ads`)
-==============================================
+``GNAT.Calendar.Time_IO`` (:file:`g-catiio.ads`)
+================================================
.. index:: Calendar
.. _`GNAT.CRC32_(g-crc32.ads)`:
-`GNAT.CRC32` (:file:`g-crc32.ads`)
-==================================
+``GNAT.CRC32`` (:file:`g-crc32.ads`)
+====================================
.. index:: GNAT.CRC32 (g-crc32.ads)
.. _`GNAT.Case_Util_(g-casuti.ads)`:
-`GNAT.Case_Util` (:file:`g-casuti.ads`)
-=======================================
+``GNAT.Case_Util`` (:file:`g-casuti.ads`)
+=========================================
.. index:: GNAT.Case_Util (g-casuti.ads)
.. index:: Casing utilities
-.. index:: Character handling (`GNAT.Case_Util`)
+.. index:: Character handling (``GNAT.Case_Util``)
A set of simple routines for handling upper and lower casing of strings
without the overhead of the full casing tables
-in `Ada.Characters.Handling`.
+in ``Ada.Characters.Handling``.
.. _`GNAT.CGI_(g-cgi.ads)`:
-`GNAT.CGI` (:file:`g-cgi.ads`)
-==============================
+``GNAT.CGI`` (:file:`g-cgi.ads`)
+================================
.. index:: GNAT.CGI (g-cgi.ads)
.. _`GNAT.CGI.Cookie_(g-cgicoo.ads)`:
-`GNAT.CGI.Cookie` (:file:`g-cgicoo.ads`)
-========================================
+``GNAT.CGI.Cookie`` (:file:`g-cgicoo.ads`)
+==========================================
.. index:: GNAT.CGI.Cookie (g-cgicoo.ads)
.. _`GNAT.CGI.Debug_(g-cgideb.ads)`:
-`GNAT.CGI.Debug` (:file:`g-cgideb.ads`)
-=======================================
+``GNAT.CGI.Debug`` (:file:`g-cgideb.ads`)
+=========================================
.. index:: GNAT.CGI.Debug (g-cgideb.ads)
.. _`GNAT.Command_Line_(g-comlin.ads)`:
-`GNAT.Command_Line` (:file:`g-comlin.ads`)
-==========================================
+``GNAT.Command_Line`` (:file:`g-comlin.ads`)
+============================================
.. index:: GNAT.Command_Line (g-comlin.ads)
.. index:: Command line
-Provides a high level interface to `Ada.Command_Line` facilities,
+Provides a high level interface to ``Ada.Command_Line`` facilities,
including the ability to scan for named switches with optional parameters
and expand file names using wild card notations.
.. _`GNAT.Compiler_Version_(g-comver.ads)`:
-`GNAT.Compiler_Version` (:file:`g-comver.ads`)
-==============================================
+``GNAT.Compiler_Version`` (:file:`g-comver.ads`)
+================================================
.. index:: GNAT.Compiler_Version (g-comver.ads)
.. _`GNAT.Ctrl_C_(g-ctrl_c.ads)`:
-`GNAT.Ctrl_C` (:file:`g-ctrl_c.ads`)
-====================================
+``GNAT.Ctrl_C`` (:file:`g-ctrl_c.ads`)
+======================================
.. index:: GNAT.Ctrl_C (g-ctrl_c.ads)
.. _`GNAT.Current_Exception_(g-curexc.ads)`:
-`GNAT.Current_Exception` (:file:`g-curexc.ads`)
-===============================================
+``GNAT.Current_Exception`` (:file:`g-curexc.ads`)
+=================================================
.. index:: GNAT.Current_Exception (g-curexc.ads)
.. _`GNAT.Debug_Pools_(g-debpoo.ads)`:
-`GNAT.Debug_Pools` (:file:`g-debpoo.ads`)
-=========================================
+``GNAT.Debug_Pools`` (:file:`g-debpoo.ads`)
+===========================================
.. index:: GNAT.Debug_Pools (g-debpoo.ads)
Provide a debugging storage pools that helps tracking memory corruption
problems.
-See `The GNAT Debug_Pool Facility` section in the :title:`GNAT User's Guide`.
+See ``The GNAT Debug_Pool Facility`` section in the :title:`GNAT User's Guide`.
.. _`GNAT.Debug_Utilities_(g-debuti.ads)`:
-`GNAT.Debug_Utilities` (:file:`g-debuti.ads`)
-=============================================
+``GNAT.Debug_Utilities`` (:file:`g-debuti.ads`)
+===============================================
.. index:: GNAT.Debug_Utilities (g-debuti.ads)
.. _`GNAT.Decode_String_(g-decstr.ads)`:
-`GNAT.Decode_String` (:file:`g-decstr.ads`)
-===========================================
+``GNAT.Decode_String`` (:file:`g-decstr.ads`)
+=============================================
.. index:: GNAT.Decode_String (g-decstr.ads)
.. _`GNAT.Decode_UTF8_String_(g-deutst.ads)`:
-`GNAT.Decode_UTF8_String` (:file:`g-deutst.ads`)
-================================================
+``GNAT.Decode_UTF8_String`` (:file:`g-deutst.ads`)
+==================================================
.. index:: GNAT.Decode_UTF8_String (g-deutst.ads)
.. _`GNAT.Directory_Operations_(g-dirope.ads)`:
-`GNAT.Directory_Operations` (:file:`g-dirope.ads`)
-==================================================
+``GNAT.Directory_Operations`` (:file:`g-dirope.ads`)
+====================================================
.. index:: GNAT.Directory_Operations (g-dirope.ads)
.. _`GNAT.Directory_Operations.Iteration_(g-diopit.ads)`:
-`GNAT.Directory_Operations.Iteration` (:file:`g-diopit.ads`)
-============================================================
+``GNAT.Directory_Operations.Iteration`` (:file:`g-diopit.ads`)
+==============================================================
.. index:: GNAT.Directory_Operations.Iteration (g-diopit.ads)
.. _`GNAT.Dynamic_HTables_(g-dynhta.ads)`:
-`GNAT.Dynamic_HTables` (:file:`g-dynhta.ads`)
-=============================================
+``GNAT.Dynamic_HTables`` (:file:`g-dynhta.ads`)
+===============================================
.. index:: GNAT.Dynamic_HTables (g-dynhta.ads)
data. Provided in two forms, a simple form with built in hash functions,
and a more complex form in which the hash function is supplied.
-This package provides a facility similar to that of `GNAT.HTable`,
+This package provides a facility similar to that of ``GNAT.HTable``,
except that this package declares a type that can be used to define
dynamic instances of the hash table, while an instantiation of
-`GNAT.HTable` creates a single instance of the hash table.
+``GNAT.HTable`` creates a single instance of the hash table.
.. _`GNAT.Dynamic_Tables_(g-dyntab.ads)`:
-`GNAT.Dynamic_Tables` (:file:`g-dyntab.ads`)
-============================================
+``GNAT.Dynamic_Tables`` (:file:`g-dyntab.ads`)
+==============================================
.. index:: GNAT.Dynamic_Tables (g-dyntab.ads)
A generic package providing a single dimension array abstraction where the
length of the array can be dynamically modified.
-This package provides a facility similar to that of `GNAT.Table`,
+This package provides a facility similar to that of ``GNAT.Table``,
except that this package declares a type that can be used to define
dynamic instances of the table, while an instantiation of
-`GNAT.Table` creates a single instance of the table type.
+``GNAT.Table`` creates a single instance of the table type.
.. _`GNAT.Encode_String_(g-encstr.ads)`:
-`GNAT.Encode_String` (:file:`g-encstr.ads`)
-===========================================
+``GNAT.Encode_String`` (:file:`g-encstr.ads`)
+=============================================
.. index:: GNAT.Encode_String (g-encstr.ads)
.. _`GNAT.Encode_UTF8_String_(g-enutst.ads)`:
-`GNAT.Encode_UTF8_String` (:file:`g-enutst.ads`)
-================================================
+``GNAT.Encode_UTF8_String`` (:file:`g-enutst.ads`)
+==================================================
.. index:: GNAT.Encode_UTF8_String (g-enutst.ads)
.. _`GNAT.Exception_Actions_(g-excact.ads)`:
-`GNAT.Exception_Actions` (:file:`g-excact.ads`)
-===============================================
+``GNAT.Exception_Actions`` (:file:`g-excact.ads`)
+=================================================
.. index:: GNAT.Exception_Actions (g-excact.ads)
.. _`GNAT.Exception_Traces_(g-exctra.ads)`:
-`GNAT.Exception_Traces` (:file:`g-exctra.ads`)
-==============================================
+``GNAT.Exception_Traces`` (:file:`g-exctra.ads`)
+================================================
.. index:: GNAT.Exception_Traces (g-exctra.ads)
.. _`GNAT.Exceptions_(g-expect.ads)`:
-`GNAT.Exceptions` (:file:`g-expect.ads`)
-========================================
+``GNAT.Exceptions`` (:file:`g-expect.ads`)
+==========================================
.. index:: GNAT.Exceptions (g-expect.ads)
Normally it is not possible to raise an exception with
a message from a subprogram in a pure package, since the
-necessary types and subprograms are in `Ada.Exceptions`
-which is not a pure unit. `GNAT.Exceptions` provides a
+necessary types and subprograms are in ``Ada.Exceptions``
+which is not a pure unit. ``GNAT.Exceptions`` provides a
facility for getting around this limitation for a few
predefined exceptions, and for example allow raising
-`Constraint_Error` with a message from a pure subprogram.
+``Constraint_Error`` with a message from a pure subprogram.
.. _`GNAT.Expect_(g-expect.ads)`:
-`GNAT.Expect` (:file:`g-expect.ads`)
-====================================
+``GNAT.Expect`` (:file:`g-expect.ads`)
+======================================
.. index:: GNAT.Expect (g-expect.ads)
with the standard Tcl Expect tool.
It allows you to easily spawn and communicate with an external process.
You can send commands or inputs to the process, and compare the output
-with some expected regular expression. Currently `GNAT.Expect`
+with some expected regular expression. Currently ``GNAT.Expect``
is implemented on all native GNAT ports.
It is not implemented for cross ports, and in particular is not
implemented for VxWorks or LynxOS.
.. _`GNAT.Expect.TTY_(g-exptty.ads)`:
-`GNAT.Expect.TTY` (:file:`g-exptty.ads`)
-========================================
+``GNAT.Expect.TTY`` (:file:`g-exptty.ads`)
+==========================================
.. index:: GNAT.Expect.TTY (g-exptty.ads)
As GNAT.Expect but using pseudo-terminal.
-Currently `GNAT.Expect.TTY` is implemented on all native GNAT
+Currently ``GNAT.Expect.TTY`` is implemented on all native GNAT
ports. It is not implemented for cross ports, and
in particular is not implemented for VxWorks or LynxOS.
.. _`GNAT.Float_Control_(g-flocon.ads)`:
-`GNAT.Float_Control` (:file:`g-flocon.ads`)
-===========================================
+``GNAT.Float_Control`` (:file:`g-flocon.ads`)
+=============================================
.. index:: GNAT.Float_Control (g-flocon.ads)
.. _`GNAT.Formatted_String_(g-forstr.ads)`:
-`GNAT.Formatted_String` (:file:`g-forstr.ads`)
-==============================================
+``GNAT.Formatted_String`` (:file:`g-forstr.ads`)
+================================================
.. index:: GNAT.Formatted_String (g-forstr.ads)
.. _`GNAT.Heap_Sort_(g-heasor.ads)`:
-`GNAT.Heap_Sort` (:file:`g-heasor.ads`)
-=======================================
+``GNAT.Heap_Sort`` (:file:`g-heasor.ads`)
+=========================================
.. index:: GNAT.Heap_Sort (g-heasor.ads)
.. _`GNAT.Heap_Sort_A_(g-hesora.ads)`:
-`GNAT.Heap_Sort_A` (:file:`g-hesora.ads`)
-=========================================
+``GNAT.Heap_Sort_A`` (:file:`g-hesora.ads`)
+===========================================
.. index:: GNAT.Heap_Sort_A (g-hesora.ads)
data items. Move and comparison procedures are provided by passing
access-to-procedure values. The algorithm used is a modified heap sort
that performs approximately N*log(N) comparisons in the worst case.
-This differs from `GNAT.Heap_Sort` in having a less convenient
+This differs from ``GNAT.Heap_Sort`` in having a less convenient
interface, but may be slightly more efficient.
.. _`GNAT.Heap_Sort_G_(g-hesorg.ads)`:
-`GNAT.Heap_Sort_G` (:file:`g-hesorg.ads`)
-=========================================
+``GNAT.Heap_Sort_G`` (:file:`g-hesorg.ads`)
+===========================================
.. index:: GNAT.Heap_Sort_G (g-hesorg.ads)
.. index:: Sorting
-Similar to `Heap_Sort_A` except that the move and sorting procedures
+Similar to ``Heap_Sort_A`` except that the move and sorting procedures
are provided as generic parameters, this improves efficiency, especially
if the procedures can be inlined, at the expense of duplicating code for
multiple instantiations.
.. _`GNAT.HTable_(g-htable.ads)`:
-`GNAT.HTable` (:file:`g-htable.ads`)
-====================================
+``GNAT.HTable`` (:file:`g-htable.ads`)
+======================================
.. index:: GNAT.HTable (g-htable.ads)
.. _`GNAT.IO_(g-io.ads)`:
-`GNAT.IO` (:file:`g-io.ads`)
-============================
+``GNAT.IO`` (:file:`g-io.ads`)
+==============================
.. index:: GNAT.IO (g-io.ads)
.. _`GNAT.IO_Aux_(g-io_aux.ads)`:
-`GNAT.IO_Aux` (:file:`g-io_aux.ads`)
-====================================
+``GNAT.IO_Aux`` (:file:`g-io_aux.ads`)
+======================================
.. index:: GNAT.IO_Aux (g-io_aux.ads)
.. _`GNAT.Lock_Files_(g-locfil.ads)`:
-`GNAT.Lock_Files` (:file:`g-locfil.ads`)
-========================================
+``GNAT.Lock_Files`` (:file:`g-locfil.ads`)
+==========================================
.. index:: GNAT.Lock_Files (g-locfil.ads)
.. _`GNAT.MBBS_Discrete_Random_(g-mbdira.ads)`:
-`GNAT.MBBS_Discrete_Random` (:file:`g-mbdira.ads`)
-==================================================
+``GNAT.MBBS_Discrete_Random`` (:file:`g-mbdira.ads`)
+====================================================
.. index:: GNAT.MBBS_Discrete_Random (g-mbdira.ads)
.. index:: Random number generation
-The original implementation of `Ada.Numerics.Discrete_Random`. Uses
+The original implementation of ``Ada.Numerics.Discrete_Random``. Uses
a modified version of the Blum-Blum-Shub generator.
.. _`GNAT.MBBS_Float_Random_(g-mbflra.ads)`:
-`GNAT.MBBS_Float_Random` (:file:`g-mbflra.ads`)
-===============================================
+``GNAT.MBBS_Float_Random`` (:file:`g-mbflra.ads`)
+=================================================
.. index:: GNAT.MBBS_Float_Random (g-mbflra.ads)
.. index:: Random number generation
-The original implementation of `Ada.Numerics.Float_Random`. Uses
+The original implementation of ``Ada.Numerics.Float_Random``. Uses
a modified version of the Blum-Blum-Shub generator.
.. _`GNAT.MD5_(g-md5.ads)`:
-`GNAT.MD5` (:file:`g-md5.ads`)
-==============================
+``GNAT.MD5`` (:file:`g-md5.ads`)
+================================
.. index:: GNAT.MD5 (g-md5.ads)
.. _`GNAT.Memory_Dump_(g-memdum.ads)`:
-`GNAT.Memory_Dump` (:file:`g-memdum.ads`)
-=========================================
+``GNAT.Memory_Dump`` (:file:`g-memdum.ads`)
+===========================================
.. index:: GNAT.Memory_Dump (g-memdum.ads)
.. _`GNAT.Most_Recent_Exception_(g-moreex.ads)`:
-`GNAT.Most_Recent_Exception` (:file:`g-moreex.ads`)
-===================================================
+``GNAT.Most_Recent_Exception`` (:file:`g-moreex.ads`)
+=====================================================
.. index:: GNAT.Most_Recent_Exception (g-moreex.ads)
.. _`GNAT.OS_Lib_(g-os_lib.ads)`:
-`GNAT.OS_Lib` (:file:`g-os_lib.ads`)
-====================================
+``GNAT.OS_Lib`` (:file:`g-os_lib.ads`)
+======================================
.. index:: GNAT.OS_Lib (g-os_lib.ads)
.. _`GNAT.Perfect_Hash_Generators_(g-pehage.ads)`:
-`GNAT.Perfect_Hash_Generators` (:file:`g-pehage.ads`)
-=====================================================
+``GNAT.Perfect_Hash_Generators`` (:file:`g-pehage.ads`)
+=======================================================
.. index:: GNAT.Perfect_Hash_Generators (g-pehage.ads)
.. _`GNAT.Random_Numbers_(g-rannum.ads)`:
-`GNAT.Random_Numbers` (:file:`g-rannum.ads`)
-============================================
+``GNAT.Random_Numbers`` (:file:`g-rannum.ads`)
+==============================================
.. index:: GNAT.Random_Numbers (g-rannum.ads)
.. _`GNAT.Regexp_(g-regexp.ads)`:
-`GNAT.Regexp` (:file:`g-regexp.ads`)
-====================================
+``GNAT.Regexp`` (:file:`g-regexp.ads`)
+======================================
.. index:: GNAT.Regexp (g-regexp.ads)
.. _`GNAT.Registry_(g-regist.ads)`:
-`GNAT.Registry` (:file:`g-regist.ads`)
-======================================
+``GNAT.Registry`` (:file:`g-regist.ads`)
+========================================
.. index:: GNAT.Registry (g-regist.ads)
.. _`GNAT.Regpat_(g-regpat.ads)`:
-`GNAT.Regpat` (:file:`g-regpat.ads`)
-====================================
+``GNAT.Regpat`` (:file:`g-regpat.ads`)
+======================================
.. index:: GNAT.Regpat (g-regpat.ads)
.. _`GNAT.Rewrite_Data_(g-rewdat.ads)`:
-`GNAT.Rewrite_Data` (:file:`g-rewdat.ads`)
-==========================================
+``GNAT.Rewrite_Data`` (:file:`g-rewdat.ads`)
+============================================
.. index:: GNAT.Rewrite_Data (g-rewdat.ads)
.. _`GNAT.Secondary_Stack_Info_(g-sestin.ads)`:
-`GNAT.Secondary_Stack_Info` (:file:`g-sestin.ads`)
-==================================================
+``GNAT.Secondary_Stack_Info`` (:file:`g-sestin.ads`)
+====================================================
.. index:: GNAT.Secondary_Stack_Info (g-sestin.ads)
.. _`GNAT.Semaphores_(g-semaph.ads)`:
-`GNAT.Semaphores` (:file:`g-semaph.ads`)
-========================================
+``GNAT.Semaphores`` (:file:`g-semaph.ads`)
+==========================================
.. index:: GNAT.Semaphores (g-semaph.ads)
.. _`GNAT.Serial_Communications_(g-sercom.ads)`:
-`GNAT.Serial_Communications` (:file:`g-sercom.ads`)
-===================================================
+``GNAT.Serial_Communications`` (:file:`g-sercom.ads`)
+=====================================================
.. index:: GNAT.Serial_Communications (g-sercom.ads)
.. _`GNAT.SHA1_(g-sha1.ads)`:
-`GNAT.SHA1` (:file:`g-sha1.ads`)
-================================
+``GNAT.SHA1`` (:file:`g-sha1.ads`)
+==================================
.. index:: GNAT.SHA1 (g-sha1.ads)
.. _`GNAT.SHA224_(g-sha224.ads)`:
-`GNAT.SHA224` (:file:`g-sha224.ads`)
-====================================
+``GNAT.SHA224`` (:file:`g-sha224.ads`)
+======================================
.. index:: GNAT.SHA224 (g-sha224.ads)
.. _`GNAT.SHA256_(g-sha256.ads)`:
-`GNAT.SHA256` (:file:`g-sha256.ads`)
-====================================
+``GNAT.SHA256`` (:file:`g-sha256.ads`)
+======================================
.. index:: GNAT.SHA256 (g-sha256.ads)
.. _`GNAT.SHA384_(g-sha384.ads)`:
-`GNAT.SHA384` (:file:`g-sha384.ads`)
-====================================
+``GNAT.SHA384`` (:file:`g-sha384.ads`)
+======================================
.. index:: GNAT.SHA384 (g-sha384.ads)
.. _`GNAT.SHA512_(g-sha512.ads)`:
-`GNAT.SHA512` (:file:`g-sha512.ads`)
-====================================
+``GNAT.SHA512`` (:file:`g-sha512.ads`)
+======================================
.. index:: GNAT.SHA512 (g-sha512.ads)
.. _`GNAT.Signals_(g-signal.ads)`:
-`GNAT.Signals` (:file:`g-signal.ads`)
-=====================================
+``GNAT.Signals`` (:file:`g-signal.ads`)
+=======================================
.. index:: GNAT.Signals (g-signal.ads)
.. _`GNAT.Sockets_(g-socket.ads)`:
-`GNAT.Sockets` (:file:`g-socket.ads`)
-=====================================
+``GNAT.Sockets`` (:file:`g-socket.ads`)
+=======================================
.. index:: GNAT.Sockets (g-socket.ads)
A high level and portable interface to develop sockets based applications.
This package is based on the sockets thin binding found in
-`GNAT.Sockets.Thin`. Currently `GNAT.Sockets` is implemented
+``GNAT.Sockets.Thin``. Currently ``GNAT.Sockets`` is implemented
on all native GNAT ports and on VxWorks cross prots. It is not implemented for
the LynxOS cross port.
.. _`GNAT.Source_Info_(g-souinf.ads)`:
-`GNAT.Source_Info` (:file:`g-souinf.ads`)
-=========================================
+``GNAT.Source_Info`` (:file:`g-souinf.ads`)
+===========================================
.. index:: GNAT.Source_Info (g-souinf.ads)
Provides subprograms that give access to source code information known at
compile time, such as the current file name and line number. Also provides
subprograms yielding the date and time of the current compilation (like the
-C macros `__DATE__` and `__TIME__`)
+C macros ``__DATE__`` and ``__TIME__``)
.. _`GNAT.Spelling_Checker_(g-speche.ads)`:
-`GNAT.Spelling_Checker` (:file:`g-speche.ads`)
-==============================================
+``GNAT.Spelling_Checker`` (:file:`g-speche.ads`)
+================================================
.. index:: GNAT.Spelling_Checker (g-speche.ads)
.. _`GNAT.Spelling_Checker_Generic_(g-spchge.ads)`:
-`GNAT.Spelling_Checker_Generic` (:file:`g-spchge.ads`)
-======================================================
+``GNAT.Spelling_Checker_Generic`` (:file:`g-spchge.ads`)
+========================================================
.. index:: GNAT.Spelling_Checker_Generic (g-spchge.ads)
.. _`GNAT.Spitbol.Patterns_(g-spipat.ads)`:
-`GNAT.Spitbol.Patterns` (:file:`g-spipat.ads`)
-==============================================
+``GNAT.Spitbol.Patterns`` (:file:`g-spipat.ads`)
+================================================
.. index:: GNAT.Spitbol.Patterns (g-spipat.ads)
.. _`GNAT.Spitbol_(g-spitbo.ads)`:
-`GNAT.Spitbol` (:file:`g-spitbo.ads`)
-=====================================
+``GNAT.Spitbol`` (:file:`g-spitbo.ads`)
+=======================================
.. index:: GNAT.Spitbol (g-spitbo.ads)
.. _`GNAT.Spitbol.Table_Boolean_(g-sptabo.ads)`:
-`GNAT.Spitbol.Table_Boolean` (:file:`g-sptabo.ads`)
-===================================================
+``GNAT.Spitbol.Table_Boolean`` (:file:`g-sptabo.ads`)
+=====================================================
.. index:: GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
.. index:: SPITBOL Tables
-A library level of instantiation of `GNAT.Spitbol.Patterns.Table`
-for type `Standard.Boolean`, giving an implementation of sets of
+A library level of instantiation of ``GNAT.Spitbol.Patterns.Table``
+for type ``Standard.Boolean``, giving an implementation of sets of
string values.
.. _`GNAT.Spitbol.Table_Integer_(g-sptain.ads)`:
-`GNAT.Spitbol.Table_Integer` (:file:`g-sptain.ads`)
-===================================================
+``GNAT.Spitbol.Table_Integer`` (:file:`g-sptain.ads`)
+=====================================================
.. index:: GNAT.Spitbol.Table_Integer (g-sptain.ads)
.. index:: SPITBOL Tables
-A library level of instantiation of `GNAT.Spitbol.Patterns.Table`
-for type `Standard.Integer`, giving an implementation of maps
+A library level of instantiation of ``GNAT.Spitbol.Patterns.Table``
+for type ``Standard.Integer``, giving an implementation of maps
from string to integer values.
.. _`GNAT.Spitbol.Table_VString_(g-sptavs.ads)`:
-`GNAT.Spitbol.Table_VString` (:file:`g-sptavs.ads`)
-===================================================
+``GNAT.Spitbol.Table_VString`` (:file:`g-sptavs.ads`)
+=====================================================
.. index:: GNAT.Spitbol.Table_VString (g-sptavs.ads)
.. index:: SPITBOL Tables
-A library level of instantiation of `GNAT.Spitbol.Patterns.Table` for
+A library level of instantiation of ``GNAT.Spitbol.Patterns.Table`` for
a variable length string type, giving an implementation of general
maps from strings to strings.
.. _`GNAT.SSE_(g-sse.ads)`:
-`GNAT.SSE` (:file:`g-sse.ads`)
-==============================
+``GNAT.SSE`` (:file:`g-sse.ads`)
+================================
.. index:: GNAT.SSE (g-sse.ads)
.. _`GNAT.SSE.Vector_Types_(g-ssvety.ads)`:
-`GNAT.SSE.Vector_Types` (:file:`g-ssvety.ads`)
-==============================================
+``GNAT.SSE.Vector_Types`` (:file:`g-ssvety.ads`)
+================================================
.. index:: GNAT.SSE.Vector_Types (g-ssvety.ads)
.. _`GNAT.String_Hash(g-strhas.ads)`:
-`GNAT.String_Hash` (:file:`g-strhas.ads`)
-=========================================
+``GNAT.String_Hash`` (:file:`g-strhas.ads`)
+===========================================
.. index:: GNAT.String_Hash (g-strhas.ads)
.. _`GNAT.Strings_(g-string.ads)`:
-`GNAT.Strings` (:file:`g-string.ads`)
-=====================================
+``GNAT.Strings`` (:file:`g-string.ads`)
+=======================================
.. index:: GNAT.Strings (g-string.ads)
.. _`GNAT.String_Split_(g-strspl.ads)`:
-`GNAT.String_Split` (:file:`g-strspl.ads`)
-==========================================
+``GNAT.String_Split`` (:file:`g-strspl.ads`)
+============================================
.. index:: GNAT.String_Split (g-strspl.ads)
Useful string manipulation routines: given a set of separators, split
a string wherever the separators appear, and provide direct access
to the resulting slices. This package is instantiated from
-`GNAT.Array_Split`.
+``GNAT.Array_Split``.
.. _`GNAT.Table_(g-table.ads)`:
-`GNAT.Table` (:file:`g-table.ads`)
-==================================
+``GNAT.Table`` (:file:`g-table.ads`)
+====================================
.. index:: GNAT.Table (g-table.ads)
A generic package providing a single dimension array abstraction where the
length of the array can be dynamically modified.
-This package provides a facility similar to that of `GNAT.Dynamic_Tables`,
+This package provides a facility similar to that of ``GNAT.Dynamic_Tables``,
except that this package declares a single instance of the table type,
-while an instantiation of `GNAT.Dynamic_Tables` creates a type that can be
+while an instantiation of ``GNAT.Dynamic_Tables`` creates a type that can be
used to define dynamic instances of the table.
.. _`GNAT.Task_Lock_(g-tasloc.ads)`:
-`GNAT.Task_Lock` (:file:`g-tasloc.ads`)
-=======================================
+``GNAT.Task_Lock`` (:file:`g-tasloc.ads`)
+=========================================
.. index:: GNAT.Task_Lock (g-tasloc.ads)
.. _`GNAT.Time_Stamp_(g-timsta.ads)`:
-`GNAT.Time_Stamp` (:file:`g-timsta.ads`)
-========================================
+``GNAT.Time_Stamp`` (:file:`g-timsta.ads`)
+==========================================
.. index:: GNAT.Time_Stamp (g-timsta.ads)
.. _`GNAT.Threads_(g-thread.ads)`:
-`GNAT.Threads` (:file:`g-thread.ads`)
-=====================================
+``GNAT.Threads`` (:file:`g-thread.ads`)
+=======================================
.. index:: GNAT.Threads (g-thread.ads)
.. _`GNAT.Traceback_(g-traceb.ads)`:
-`GNAT.Traceback` (:file:`g-traceb.ads`)
-=======================================
+``GNAT.Traceback`` (:file:`g-traceb.ads`)
+=========================================
.. index:: GNAT.Traceback (g-traceb.ads)
.. _`GNAT.Traceback.Symbolic_(g-trasym.ads)`:
-`GNAT.Traceback.Symbolic` (:file:`g-trasym.ads`)
-================================================
+``GNAT.Traceback.Symbolic`` (:file:`g-trasym.ads`)
+==================================================
.. index:: GNAT.Traceback.Symbolic (g-trasym.ads)
.. _`GNAT.UTF_32_(g-table.ads)`:
-`GNAT.UTF_32` (:file:`g-table.ads`)
-===================================
+``GNAT.UTF_32`` (:file:`g-table.ads`)
+=====================================
.. index:: GNAT.UTF_32 (g-table.ads)
.. index:: Wide character codes
This is a package intended to be used in conjunction with the
-`Wide_Character` type in Ada 95 and the
-`Wide_Wide_Character` type in Ada 2005 (available
-in `GNAT` in Ada 2005 mode). This package contains
+``Wide_Character`` type in Ada 95 and the
+``Wide_Wide_Character`` type in Ada 2005 (available
+in ``GNAT`` in Ada 2005 mode). This package contains
Unicode categorization routines, as well as lexical
categorization routines corresponding to the Ada 2005
lexical rules for identifiers and strings, and also a
.. _`GNAT.Wide_Spelling_Checker_(g-u3spch.ads)`:
-`GNAT.Wide_Spelling_Checker` (:file:`g-u3spch.ads`)
-===================================================
+``GNAT.Wide_Spelling_Checker`` (:file:`g-u3spch.ads`)
+=====================================================
.. index:: GNAT.Wide_Spelling_Checker (g-u3spch.ads)
.. _`GNAT.Wide_Spelling_Checker_(g-wispch.ads)`:
-`GNAT.Wide_Spelling_Checker` (:file:`g-wispch.ads`)
-===================================================
+``GNAT.Wide_Spelling_Checker`` (:file:`g-wispch.ads`)
+=====================================================
.. index:: GNAT.Wide_Spelling_Checker (g-wispch.ads)
.. _`GNAT.Wide_String_Split_(g-wistsp.ads)`:
-`GNAT.Wide_String_Split` (:file:`g-wistsp.ads`)
-===============================================
+``GNAT.Wide_String_Split`` (:file:`g-wistsp.ads`)
+=================================================
.. index:: GNAT.Wide_String_Split (g-wistsp.ads)
Useful wide string manipulation routines: given a set of separators, split
a wide string wherever the separators appear, and provide direct access
to the resulting slices. This package is instantiated from
-`GNAT.Array_Split`.
+``GNAT.Array_Split``.
.. _`GNAT.Wide_Wide_Spelling_Checker_(g-zspche.ads)`:
-`GNAT.Wide_Wide_Spelling_Checker` (:file:`g-zspche.ads`)
-========================================================
+``GNAT.Wide_Wide_Spelling_Checker`` (:file:`g-zspche.ads`)
+==========================================================
.. index:: GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
.. _`GNAT.Wide_Wide_String_Split_(g-zistsp.ads)`:
-`GNAT.Wide_Wide_String_Split` (:file:`g-zistsp.ads`)
-====================================================
+``GNAT.Wide_Wide_String_Split`` (:file:`g-zistsp.ads`)
+======================================================
.. index:: GNAT.Wide_Wide_String_Split (g-zistsp.ads)
Useful wide wide string manipulation routines: given a set of separators, split
a wide wide string wherever the separators appear, and provide direct access
to the resulting slices. This package is instantiated from
-`GNAT.Array_Split`.
+``GNAT.Array_Split``.
.. _`Interfaces.C.Extensions_(i-cexten.ads)`:
-`Interfaces.C.Extensions` (:file:`i-cexten.ads`)
-================================================
+``Interfaces.C.Extensions`` (:file:`i-cexten.ads`)
+==================================================
.. index:: Interfaces.C.Extensions (i-cexten.ads)
.. _`Interfaces.C.Streams_(i-cstrea.ads)`:
-`Interfaces.C.Streams` (:file:`i-cstrea.ads`)
-=============================================
+``Interfaces.C.Streams`` (:file:`i-cstrea.ads`)
+===============================================
.. index:: Interfaces.C.Streams (i-cstrea.ads)
.. _`Interfaces.Packed_Decimal_(i-pacdec.ads)`:
-`Interfaces.Packed_Decimal` (:file:`i-pacdec.ads`)
-==================================================
+``Interfaces.Packed_Decimal`` (:file:`i-pacdec.ads`)
+====================================================
.. index:: Interfaces.Packed_Decimal (i-pacdec.ads)
.. _`Interfaces.VxWorks_(i-vxwork.ads)`:
-`Interfaces.VxWorks` (:file:`i-vxwork.ads`)
-===========================================
+``Interfaces.VxWorks`` (:file:`i-vxwork.ads`)
+=============================================
.. index:: Interfaces.VxWorks (i-vxwork.ads)
.. _`Interfaces.VxWorks.Int_Connection_(i-vxinco.ads)`:
-`Interfaces.VxWorks.Int_Connection` (:file:`i-vxinco.ads`)
-==========================================================
+``Interfaces.VxWorks.Int_Connection`` (:file:`i-vxinco.ads`)
+============================================================
.. index:: Interfaces.VxWorks.Int_Connection (i-vxinco.ads)
.. _`Interfaces.VxWorks.IO_(i-vxwoio.ads)`:
-`Interfaces.VxWorks.IO` (:file:`i-vxwoio.ads`)
-==============================================
+``Interfaces.VxWorks.IO`` (:file:`i-vxwoio.ads`)
+================================================
.. index:: Interfaces.VxWorks.IO (i-vxwoio.ads)
.. _`System.Address_Image_(s-addima.ads)`:
-`System.Address_Image` (:file:`s-addima.ads`)
-=============================================
+``System.Address_Image`` (:file:`s-addima.ads`)
+===============================================
.. index:: System.Address_Image (s-addima.ads)
.. _`System.Assertions_(s-assert.ads)`:
-`System.Assertions` (:file:`s-assert.ads`)
-==========================================
+``System.Assertions`` (:file:`s-assert.ads`)
+============================================
.. index:: System.Assertions (s-assert.ads)
.. _`System.Atomic_Counters_(s-atocou.ads)`:
-`System.Atomic_Counters` (:file:`s-atocou.ads`)
-===============================================
+``System.Atomic_Counters`` (:file:`s-atocou.ads`)
+=================================================
.. index:: System.Atomic_Counters (s-atocou.ads)
.. _`System.Memory_(s-memory.ads)`:
-`System.Memory` (:file:`s-memory.ads`)
-======================================
+``System.Memory`` (:file:`s-memory.ads`)
+========================================
.. index:: System.Memory (s-memory.ads)
realloc. The body of this unit may be modified to provide alternative
allocation mechanisms for the default pool, and in addition, direct
calls to this unit may be made for low level allocation uses (for
-example see the body of `GNAT.Tables`).
+example see the body of ``GNAT.Tables``).
.. _`System.Multiprocessors_(s-multip.ads)`:
-`System.Multiprocessors` (:file:`s-multip.ads`)
-===============================================
+``System.Multiprocessors`` (:file:`s-multip.ads`)
+=================================================
.. index:: System.Multiprocessors (s-multip.ads)
.. _`System.Multiprocessors.Dispatching_Domains_(s-mudido.ads)`:
-`System.Multiprocessors.Dispatching_Domains` (:file:`s-mudido.ads`)
-===================================================================
+``System.Multiprocessors.Dispatching_Domains`` (:file:`s-mudido.ads`)
+=====================================================================
.. index:: System.Multiprocessors.Dispatching_Domains (s-mudido.ads)
.. _`System.Partition_Interface_(s-parint.ads)`:
-`System.Partition_Interface` (:file:`s-parint.ads`)
-===================================================
+``System.Partition_Interface`` (:file:`s-parint.ads`)
+=====================================================
.. index:: System.Partition_Interface (s-parint.ads)
This package provides facilities for partition interfacing. It
is used primarily in a distribution context when using Annex E
-with `GLADE`.
+with ``GLADE``.
.. _`System.Pool_Global_(s-pooglo.ads)`:
-`System.Pool_Global` (:file:`s-pooglo.ads`)
-===========================================
+``System.Pool_Global`` (:file:`s-pooglo.ads`)
+=============================================
.. index:: System.Pool_Global (s-pooglo.ads)
.. _`System.Pool_Local_(s-pooloc.ads)`:
-`System.Pool_Local` (:file:`s-pooloc.ads`)
-==========================================
+``System.Pool_Local`` (:file:`s-pooloc.ads`)
+============================================
.. index:: System.Pool_Local (s-pooloc.ads)
.. _`System.Restrictions_(s-restri.ads)`:
-`System.Restrictions` (:file:`s-restri.ads`)
-============================================
+``System.Restrictions`` (:file:`s-restri.ads`)
+==============================================
.. index:: System.Restrictions (s-restri.ads)
.. _`System.Rident_(s-rident.ads)`:
-`System.Rident` (:file:`s-rident.ads`)
-======================================
+``System.Rident`` (:file:`s-rident.ads`)
+========================================
.. index:: System.Rident (s-rident.ads)
This package provides definitions of the restrictions
identifiers supported by GNAT, and also the format of
the restrictions provided in package System.Restrictions.
-It is not normally necessary to `with` this generic package
+It is not normally necessary to ``with`` this generic package
since the necessary instantiation is included in
package System.Restrictions.
.. _`System.Strings.Stream_Ops_(s-ststop.ads)`:
-`System.Strings.Stream_Ops` (:file:`s-ststop.ads`)
-==================================================
+``System.Strings.Stream_Ops`` (:file:`s-ststop.ads`)
+====================================================
.. index:: System.Strings.Stream_Ops (s-ststop.ads)
.. _`System.Unsigned_Types_(s-unstyp.ads)`:
-`System.Unsigned_Types` (:file:`s-unstyp.ads`)
-==============================================
+``System.Unsigned_Types`` (:file:`s-unstyp.ads`)
+================================================
.. index:: System.Unsigned_Types (s-unstyp.ads)
.. _`System.Wch_Cnv_(s-wchcnv.ads)`:
-`System.Wch_Cnv` (:file:`s-wchcnv.ads`)
-=======================================
+``System.Wch_Cnv`` (:file:`s-wchcnv.ads`)
+=========================================
.. index:: System.Wch_Cnv (s-wchcnv.ads)
This package provides routines for converting between
wide and wide wide characters and a representation as a value of type
-`Standard.String`, using a specified wide character
+``Standard.String``, using a specified wide character
encoding method. It uses definitions in
-package `System.Wch_Con`.
+package ``System.Wch_Con``.
.. _`System.Wch_Con_(s-wchcon.ads)`:
-`System.Wch_Con` (:file:`s-wchcon.ads`)
-=======================================
+``System.Wch_Con`` (:file:`s-wchcon.ads`)
+=========================================
.. index:: System.Wch_Con (s-wchcon.ads)
This package provides definitions and descriptions of
the various methods used for encoding wide characters
in ordinary strings. These definitions are used by
-the package `System.Wch_Cnv`.
+the package ``System.Wch_Cnv``.
library streams facility; where
*
- All files are opened using `fopen`.
+ All files are opened using ``fopen``.
*
- All input/output operations use `fread`/`fwrite`.
+ All input/output operations use ``fread``/`fwrite`.
There is no internal buffering of any kind at the Ada library level. The only
buffering is that provided at the system level in the implementation of the
sequence, with the first record starting at offset zero, and subsequent
records following. There is no control information of any kind. For
example, if 32-bit integers are being written, each record takes
-4-bytes, so the record at index `K` starts at offset
-(`K`-1)*4.
+4-bytes, so the record at index ``K`` starts at offset
+(``K``-1)*4.
There is no limit on the size of Direct_IO files, they are expanded as
necessary to accommodate whatever records are written to the file.
For the indefinite type case, the elements written consist of two
parts. First is the size of the data item, written as the memory image
-of a `Interfaces.C.size_t` value, followed by the memory image of
+of a ``Interfaces.C.size_t`` value, followed by the memory image of
the data value. The resulting file can only be read using the same
(unconstrained) type. Normal assignment checks are performed on these
-read operations, and if these checks fail, `Data_Error` is
+read operations, and if these checks fail, ``Data_Error`` is
raised. In particular, in the array case, the lengths must match, and in
the variant record case, if the variable for a particular read operation
is constrained, the discriminants must match.
Note that it is not possible to use Sequential_IO to write variable
length array items, and then read the data back into different length
-arrays. For example, the following will raise `Data_Error`:
+arrays. For example, the following will raise ``Data_Error``:
.. code-block:: ada
-On some Ada implementations, this will print `hell`, but the program is
+On some Ada implementations, this will print ``hell``, but the program is
clearly incorrect, since there is only one element in the file, and that
-element is the string `hello!`.
+element is the string ``hello!``.
In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
using Stream_IO, and this is the preferred mechanism. In particular, the
conditions are met:
*
- The character `LF` is used only as a line mark, i.e., to mark the end
+ The character ``LF`` is used only as a line mark, i.e., to mark the end
of the line.
*
- The character `FF` is used only as a page mark, i.e., to mark the
+ The character ``FF`` is used only as a page mark, i.e., to mark the
end of a page and consequently can appear only immediately following a
- `LF` (line mark) character.
+ ``LF`` (line mark) character.
*
- The file ends with either `LF` (line mark) or `LF`-`FF`
+ The file ends with either ``LF`` (line mark) or ``LF``-`FF`
(line mark, page mark). In the former case, the page mark is implicitly
assumed to be present.
A file written using Text_IO will be in canonical form provided that no
-explicit `LF` or `FF` characters are written using `Put`
-or `Put_Line`. There will be no `FF` character at the end of
-the file unless an explicit `New_Page` operation was performed
+explicit ``LF`` or ``FF`` characters are written using ``Put``
+or ``Put_Line``. There will be no ``FF`` character at the end of
+the file unless an explicit ``New_Page`` operation was performed
before closing the file.
A canonical Text_IO file that is a regular file (i.e., not a device or a
file has one of the following:
*
- The file contains `FF` characters not immediately following a
- `LF` character.
+ The file contains ``FF`` characters not immediately following a
+ ``LF`` character.
*
- The file contains `LF` or `FF` characters written by
- `Put` or `Put_Line`, which are not logically considered to be
+ The file contains ``LF`` or ``FF`` characters written by
+ ``Put`` or ``Put_Line``, which are not logically considered to be
line marks or page marks.
*
- The file ends in a character other than `LF` or `FF`,
+ The file ends in a character other than ``LF`` or ``FF``,
i.e., there is no explicit line mark or page mark at the end of the file.
Text_IO can be used to read such non-standard text files but subprograms
to do with line or page numbers do not have defined meanings. In
-particular, a `FF` character that does not follow a `LF`
+particular, a ``FF`` character that does not follow a ``LF``
character may or may not be treated as a page mark from the point of
-view of page and line numbering. Every `LF` character is considered
-to end a line, and there is an implied `LF` character at the end of
+view of page and line numbering. Every ``LF`` character is considered
+to end a line, and there is an implied ``LF`` character at the end of
the file.
.. _Stream_Pointer_Positioning:
Stream Pointer Positioning
--------------------------
-`Ada.Text_IO` has a definition of current position for a file that
+``Ada.Text_IO`` has a definition of current position for a file that
is being read. No internal buffering occurs in Text_IO, and usually the
physical position in the stream used to implement the file corresponds
to this logical position defined by Text_IO. There are two exceptions:
*
- After a call to `End_Of_Page` that returns `True`, the stream
- is positioned past the `LF` (line mark) that precedes the page
+ After a call to ``End_Of_Page`` that returns ``True``, the stream
+ is positioned past the ``LF`` (line mark) that precedes the page
mark. Text_IO maintains an internal flag so that subsequent read
operations properly handle the logical position which is unchanged by
- the `End_Of_Page` call.
+ the ``End_Of_Page`` call.
*
- After a call to `End_Of_File` that returns `True`, if the
+ After a call to ``End_Of_File`` that returns ``True``, if the
Text_IO file was positioned before the line mark at the end of file
before the call, then the logical position is unchanged, but the stream
is physically positioned right at the end of file (past the line mark,
look-ahead as follows:
An input file that is not a regular file is considered to have no page
-marks. Any `Ascii.FF` characters (the character normally used for a
+marks. Any ``Ascii.FF`` characters (the character normally used for a
page mark) appearing in the file are considered to be data
characters. In particular:
*
- `Get_Line` and `Skip_Line` do not test for a page mark
+ ``Get_Line`` and ``Skip_Line`` do not test for a page mark
following a line mark. If a page mark appears, it will be treated as a
data character.
entered from the pipe to complete one of these operations.
*
- `End_Of_Page` always returns `False`
+ ``End_Of_Page`` always returns ``False``
*
- `End_Of_File` will return `False` if there is a page mark at
+ ``End_Of_File`` will return ``False`` if there is a page mark at
the end of the file.
Output to non-regular files is the same as for regular files. Page marks
-may be written to non-regular files using `New_Page`, but as noted
+may be written to non-regular files using ``New_Page``, but as noted
above they will not be treated as page marks on input if the output is
piped to another Ada program.
of file indication is not 'sticky'. If an end of file is entered, e.g., by
pressing the :kbd:`EOT` key,
then end of file
-is signaled once (i.e., the test `End_Of_File`
-will yield `True`, or a read will
-raise `End_Error`), but then reading can resume
+is signaled once (i.e., the test ``End_Of_File``
+will yield ``True``, or a read will
+raise ``End_Error``), but then reading can resume
to read data past that end of
file indication, until another end of file indication is entered.
.. index:: Stream files
-The package `Text_IO.Streams` allows a Text_IO file to be treated
-as a stream. Data written to a Text_IO file in this stream mode is
-binary data. If this binary data contains bytes 16#0A# (`LF`) or
-16#0C# (`FF`), the resulting file may have non-standard
+The package ``Text_IO.Streams`` allows a ``Text_IO`` file to be treated
+as a stream. Data written to a ``Text_IO`` file in this stream mode is
+binary data. If this binary data contains bytes 16#0A# (``LF``) or
+16#0C# (``FF``), the resulting file may have non-standard
format. Similarly if read operations are used to read from a Text_IO
-file treated as a stream, then `LF` and `FF` characters may be
+file treated as a stream, then ``LF`` and ``FF`` characters may be
skipped and the effect is similar to that described above for
-`Get_Immediate`.
+``Get_Immediate``.
.. _Text_IO_Extensions:
.. index:: Text_IO extensions
A package GNAT.IO_Aux in the GNAT library provides some useful extensions
-to the standard `Text_IO` package:
+to the standard ``Text_IO`` package:
* function File_Exists (Name : String) return Boolean;
Determines if a file of the given name exists.
.. index:: Unbounded_String, Text_IO operations
-The package `Ada.Strings.Unbounded.Text_IO`
-in library files `a-suteio.ads/adb` contains some GNAT-specific
+The package ``Ada.Strings.Unbounded.Text_IO``
+in library files :file:`a-suteio.ads/adb` contains some GNAT-specific
subprograms useful for Text_IO operations on unbounded strings:
* procedure Put (File : File_Type; U : Unbounded_String);
Writes the value of the given unbounded string to the specified file
Similar to the effect of
- `Put (To_String (U))` except that an extra copy is avoided.
+ ``Put (To_String (U))`` except that an extra copy is avoided.
* procedure Put_Line (File : File_Type; U : Unbounded_String);
Writes the value of the given unbounded string to the specified file,
- followed by a `New_Line`.
- Similar to the effect of `Put_Line (To_String (U))` except
+ followed by a ``New_Line``.
+ Similar to the effect of ``Put_Line (To_String (U))`` except
that an extra copy is avoided.
-In the above procedures, `File` is of type `Ada.Text_IO.File_Type`
+In the above procedures, ``File`` is of type ``Ada.Text_IO.File_Type``
and is optional. If the parameter is omitted, then the standard input or
output file is referenced as appropriate.
-The package `Ada.Strings.Wide_Unbounded.Wide_Text_IO` in library
+The package ``Ada.Strings.Wide_Unbounded.Wide_Text_IO`` in library
files :file:`a-swuwti.ads` and :file:`a-swuwti.adb` provides similar extended
-`Wide_Text_IO` functionality for unbounded wide strings.
+``Wide_Text_IO`` functionality for unbounded wide strings.
-The package `Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO` in library
+The package ``Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO`` in library
files :file:`a-szuzti.ads` and :file:`a-szuzti.adb` provides similar extended
-`Wide_Wide_Text_IO` functionality for unbounded wide wide strings.
+``Wide_Wide_Text_IO`` functionality for unbounded wide wide strings.
.. _Wide_Text_IO:
Wide_Text_IO
============
-`Wide_Text_IO` is similar in most respects to Text_IO, except that
+``Wide_Text_IO`` is similar in most respects to Text_IO, except that
both input and output files may contain special sequences that represent
wide character values. The encoding scheme for a given file may be
specified using a FORM parameter:
as part of the FORM string (WCEM = wide character encoding method),
-where `x` is one of the following characters
+where ``x`` is one of the following characters
========== ====================
Character Encoding
..
- where `a`, `b`, `c`, `d` are the four hexadecimal
+ where ``a``, ``b``, ``c``, ``d`` are the four hexadecimal
characters (using upper case letters) of the wide character code. For
example, ESC A345 is used to represent the wide character with code
16#A345#. This scheme is compatible with use of the full
- `Wide_Character` set.
+ ``Wide_Character`` set.
*Upper Half Coding*
..
- where the `xxx` bits correspond to the left-padded bits of the
+ where the ``xxx`` bits correspond to the left-padded bits of the
16-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
..
- where `a`, `b`, `c`, `d` are the four hexadecimal
+ where ``a``, ``b``, ``c``, ``d`` are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
- example, `["A345"]` is used to represent the wide character with code
- `16#A345#`.
+ example, ``["A345"]`` is used to represent the wide character with code
+ ``16#A345#``.
This scheme is compatible with use of the full Wide_Character set.
On input, brackets coding can also be used for upper half characters,
- e.g., `["C1"]` for lower case a. However, on output, brackets notation
- is only used for wide characters with a code greater than `16#FF#`.
+ e.g., ``["C1"]`` for lower case a. However, on output, brackets notation
+ is only used for wide characters with a code greater than ``16#FF#``.
Note that brackets coding is not normally used in the context of
Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
Stream Pointer Positioning
--------------------------
-`Ada.Wide_Text_IO` is similar to `Ada.Text_IO` in its handling
+``Ada.Wide_Text_IO`` is similar to ``Ada.Text_IO`` in its handling
of stream pointer positioning (:ref:`Text_IO`). There is one additional
case:
-If `Ada.Wide_Text_IO.Look_Ahead` reads a character outside the
+If ``Ada.Wide_Text_IO.Look_Ahead`` reads a character outside the
normal lower ASCII set (i.e., a character in the range:
then although the logical position of the file pointer is unchanged by
-the `Look_Ahead` call, the stream is physically positioned past the
+the ``Look_Ahead`` call, the stream is physically positioned past the
wide character sequence. Again this is to avoid the need for buffering
-or backup, and all `Wide_Text_IO` routines check the internal
+or backup, and all ``Wide_Text_IO`` routines check the internal
indication that this situation has occurred so that this is not visible
-to a normal program using `Wide_Text_IO`. However, this discrepancy
+to a normal program using ``Wide_Text_IO``. However, this discrepancy
can be observed if the wide text file shares a stream with another file.
.. _Reading_and_Writing_Non-Regular_Files_1:
As in the case of Text_IO, when a non-regular file is read, it is
assumed that the file contains no page marks (any form characters are
-treated as data characters), and `End_Of_Page` always returns
-`False`. Similarly, the end of file indication is not sticky, so
+treated as data characters), and ``End_Of_Page`` always returns
+``False``. Similarly, the end of file indication is not sticky, so
it is possible to read beyond an end of file.
.. _Wide_Wide_Text_IO:
Wide_Wide_Text_IO
=================
-`Wide_Wide_Text_IO` is similar in most respects to Text_IO, except that
+``Wide_Wide_Text_IO`` is similar in most respects to Text_IO, except that
both input and output files may contain special sequences that represent
wide wide character values. The encoding scheme for a given file may be
specified using a FORM parameter:
as part of the FORM string (WCEM = wide character encoding method),
-where `x` is one of the following characters
+where ``x`` is one of the following characters
========== ====================
Character Encoding
..
- where the `xxx` bits correspond to the left-padded bits of the
+ where the ``xxx`` bits correspond to the left-padded bits of the
21-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
..
- where `a`, `b`, `c`, `d`, `e`, and `f`
+ where ``a``, ``b``, ``c``, ``d``, ``e``, and ``f``
are the four or six hexadecimal
characters (using uppercase letters) of the wide wide character code. For
- example, `["01A345"]` is used to represent the wide wide character
- with code `16#01A345#`.
+ example, ``["01A345"]`` is used to represent the wide wide character
+ with code ``16#01A345#``.
This scheme is compatible with use of the full Wide_Wide_Character set.
On input, brackets coding can also be used for upper half characters,
- e.g., `["C1"]` for lower case a. However, on output, brackets notation
- is only used for wide characters with a code greater than `16#FF#`.
+ e.g., ``["C1"]`` for lower case a. However, on output, brackets notation
+ is only used for wide characters with a code greater than ``16#FF#``.
If is also possible to use the other Wide_Character encoding methods,
Stream Pointer Positioning
--------------------------
-`Ada.Wide_Wide_Text_IO` is similar to `Ada.Text_IO` in its handling
+``Ada.Wide_Wide_Text_IO`` is similar to ``Ada.Text_IO`` in its handling
of stream pointer positioning (:ref:`Text_IO`). There is one additional
case:
-If `Ada.Wide_Wide_Text_IO.Look_Ahead` reads a character outside the
+If ``Ada.Wide_Wide_Text_IO.Look_Ahead`` reads a character outside the
normal lower ASCII set (i.e., a character in the range:
then although the logical position of the file pointer is unchanged by
-the `Look_Ahead` call, the stream is physically positioned past the
+the ``Look_Ahead`` call, the stream is physically positioned past the
wide character sequence. Again this is to avoid the need for buffering
-or backup, and all `Wide_Wide_Text_IO` routines check the internal
+or backup, and all ``Wide_Wide_Text_IO`` routines check the internal
indication that this situation has occurred so that this is not visible
-to a normal program using `Wide_Wide_Text_IO`. However, this discrepancy
+to a normal program using ``Wide_Wide_Text_IO``. However, this discrepancy
can be observed if the wide text file shares a stream with another file.
.. _Reading_and_Writing_Non-Regular_Files_2:
As in the case of Text_IO, when a non-regular file is read, it is
assumed that the file contains no page marks (any form characters are
-treated as data characters), and `End_Of_Page` always returns
-`False`. Similarly, the end of file indication is not sticky, so
+treated as data characters), and ``End_Of_Page`` always returns
+``False``. Similarly, the end of file indication is not sticky, so
it is possible to read beyond an end of file.
.. _Stream_IO:
A stream file is a sequence of bytes, where individual elements are
written to the file as described in the Ada Reference Manual. The type
-`Stream_Element` is simply a byte. There are two ways to read or
+``Stream_Element`` is simply a byte. There are two ways to read or
write a stream file.
*
- The operations `Read` and `Write` directly read or write a
+ The operations ``Read`` and ``Write`` directly read or write a
sequence of stream elements with no control information.
*
*
In the absence of a ``shared=xxx`` form parameter, an attempt
to open two or more files with the same full name is considered an error
- and is not supported. The exception `Use_Error` will be
+ and is not supported. The exception ``Use_Error`` will be
raised. Note that a file that is not explicitly closed by the program
remains open until the program terminates.
When a program that opens multiple files with the same name is ported
from another Ada compiler to GNAT, the effect will be that
-`Use_Error` is raised.
+``Use_Error`` is raised.
The documentation of the original compiler and the documentation of the
program should then be examined to determine if file sharing was
-expected, and ``shared=xxx`` parameters added to `Open`
-and `Create` calls as required.
+expected, and ``shared=xxx`` parameters added to ``Open``
+and ``Create`` calls as required.
When a program is ported from GNAT to some other Ada compiler, no
special attention is required unless the ``shared=xxx`` form
Open Modes
==========
-`Open` and `Create` calls result in a call to `fopen`
+``Open`` and ``Create`` calls result in a call to ``fopen``
using the mode shown in the following table:
+----------------------------+---------------+------------------+
-| `Open` and `Create` Call Modes |
+| ``Open`` and ``Create`` Call Modes |
+----------------------------+---------------+------------------+
| | **OPEN** | **CREATE** |
+============================+===============+==================+
A special case occurs with Stream_IO. As shown in the above table, the
file is initially opened in ``r`` or ``w`` mode for the
-`In_File` and `Out_File` cases. If a `Set_Mode` operation
+``In_File`` and ``Out_File`` cases. If a ``Set_Mode`` operation
subsequently requires switching from reading to writing or vice-versa,
then the file is reopened in ``r+`` mode to permit the required operation.
Operations on C Streams
=======================
-The package `Interfaces.C_Streams` provides an Ada program with direct
+The package ``Interfaces.C_Streams`` provides an Ada program with direct
access to the C library functions for operations on C streams:
end Ada.Stream_IO.C_Streams;
-In each of these six packages, the `C_Stream` function obtains the
-`FILE` pointer from a currently opened Ada file. It is then
-possible to use the `Interfaces.C_Streams` package to operate on
+In each of these six packages, the ``C_Stream`` function obtains the
+``FILE`` pointer from a currently opened Ada file. It is then
+possible to use the ``Interfaces.C_Streams`` package to operate on
this stream, or the stream can be passed to a C program which can
operate on it directly. Of course the program is responsible for
ensuring that only appropriate sequences of operations are executed.
One particular use of relevance to an Ada program is that the
-`setvbuf` function can be used to control the buffering of the
+``setvbuf`` function can be used to control the buffering of the
stream used by an Ada file. In the absence of such a call the standard
default buffering is used.
-The `Open` procedures in these packages open a file giving an
+The ``Open`` procedures in these packages open a file giving an
existing C Stream instead of a file name. Typically this stream is
imported from a C program, allowing an Ada file to operate on an
existing C file.
GNAT User's Guide for Native Platforms
======================================
-*GNAT, The GNU Ada Development Environment*
+.. only:: not latex
-.. only:: PRO
+ *GNAT, The GNU Ada Development Environment*
- *GNAT Pro Edition*
+ .. only:: PRO
- | Version |version|
- | Date: |today|
+ *GNAT Pro Edition*
-.. only:: GPL
+ | Version |version|
+ | Date: |today|
- *GNAT GPL Edition*
+ .. only:: GPL
- | Version |version|
- | Date: |today|
+ *GNAT GPL Edition*
-.. only:: FSF
+ | Version |version|
+ | Date: |today|
- .. raw:: texinfo
+ .. only:: FSF
- @include gcc-common.texi
- GCC version @value{version-GCC}@*
+ .. raw:: texinfo
-AdaCore
+ @include gcc-common.texi
+ GCC version @value{version-GCC}@*
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover Texts being
-"GNAT User's Guide for Native Platforms",
-and with no Back-Cover Texts. A copy of the license is
-included in the section entitled :ref:`gnu_fdl`.
+ AdaCore
+
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3 or
+ any later version published by the Free Software Foundation; with no
+ Invariant Sections, with the Front-Cover Texts being
+ "GNAT User's Guide for Native Platforms",
+ and with no Back-Cover Texts. A copy of the license is
+ included in the section entitled :ref:`gnu_fdl`.
.. toctree::
:maxdepth: 3
* :ref:`The_GNAT_Compilation_Model` has been extended so that it now covers
the following material:
- - The `gnatname`, `gnatkr`, and `gnatchop` tools
+ - The ``gnatname``, ``gnatkr``, and ``gnatchop`` tools
- :ref:`Configuration_Pragmas`
- :ref:`GNAT_and_Libraries`
- :ref:`Conditional_Compilation` including :ref:`Preprocessing_with_gnatprep`
- :ref:`Microsoft_Windows_Topics`
- :ref:`Mac_OS_Topics`
-* The `Compatibility and Porting Guide` appendix has been moved to the
+* The *Compatibility and Porting Guide* appendix has been moved to the
:title:`GNAT Reference Manual`. It now includes a section
- `Writing Portable Fixed-Point Declarations` which was previously
+ *Writing Portable Fixed-Point Declarations* which was previously
a separate chapter in the :title:`GNAT User's Guide`.
Following are examples of the typographical and graphic conventions used
in this guide:
-* `Functions`, `utility program names`, `standard names`,
- and `classes`.
+* ``Functions``, ``utility program names``, ``standard names``,
+ and ``classes``.
-* `Option flags`
+* ``Option flags``
* :file:`File names`
-* `Variables`
+* ``Variables``
* *Emphasis*
.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-
+.. role:: switch(samp)
.. _Building_Executable_Programs_With_GNAT:
.. _The_GNAT_Make_Program_gnatmake:
-Building with *gnatmake*
-========================
+Building with ``gnatmake``
+==========================
.. index:: gnatmake
The third step in particular can be tricky, because not only do the modified
files have to be compiled, but any files depending on these files must also be
recompiled. The dependency rules in Ada can be quite complex, especially
-in the presence of overloading, `use` clauses, generics and inlined
+in the presence of overloading, ``use`` clauses, generics and inlined
subprograms.
-*gnatmake* automatically takes care of the third and fourth steps
+``gnatmake`` automatically takes care of the third and fourth steps
of this process. It determines which sources need to be compiled,
compiles them, and binds and links the resulting object files.
the GNAT compilation model makes this possible. This means that if
changes to the source program cause corresponding changes in
dependencies, they will always be tracked exactly correctly by
-*gnatmake*.
+``gnatmake``.
Note that for advanced forms of project structure, we recommend creating
a project file as explained in the *GNAT_Project_Manager* chapter in the
*GPRbuild User's Guide*, and using the
-*gprbuild* tool which supports building with project files and works similarly
-to *gnatmake*.
+``gprbuild`` tool which supports building with project files and works similarly
+to ``gnatmake``.
.. _Running_gnatmake:
-Running *gnatmake*
-------------------
+Running ``gnatmake``
+--------------------
-The usual form of the *gnatmake* command is
+The usual form of the ``gnatmake`` command is
.. code-block:: sh
$ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>]
-The only required argument is one `file_name`, which specifies
-a compilation unit that is a main program. Several `file_names` can be
+The only required argument is one ``file_name``, which specifies
+a compilation unit that is a main program. Several ``file_names`` can be
specified: this will result in several executables being built.
-If `switches` are present, they can be placed before the first
-`file_name`, between `file_names` or after the last `file_name`.
-If `mode_switches` are present, they must always be placed after
-the last `file_name` and all `switches`.
+If ``switches`` are present, they can be placed before the first
+``file_name``, between ``file_names`` or after the last ``file_name``.
+If ``mode_switches`` are present, they must always be placed after
+the last ``file_name`` and all ``switches``.
If you are using standard file extensions (:file:`.adb` and
:file:`.ads`), then the
-extension may be omitted from the `file_name` arguments. However, if
+extension may be omitted from the ``file_name`` arguments. However, if
you are using non-standard extensions, then it is required that the
extension be given. A relative or absolute directory path can be
-specified in a `file_name`, in which case, the input source file will
+specified in a ``file_name``, in which case, the input source file will
be searched for in the specified directory only. Otherwise, the input
source file will first be searched in the directory where
-*gnatmake* was invoked and if it is not found, it will be search on
+``gnatmake`` was invoked and if it is not found, it will be search on
the source path of the compiler as described in
:ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
-All *gnatmake* output (except when you specify *-M*) is sent to
+All ``gnatmake`` output (except when you specify :switch:`-M`) is sent to
:file:`stderr`. The output produced by the
-*-M* switch is sent to :file:`stdout`.
+:switch:`-M` switch is sent to :file:`stdout`.
.. _Switches_for_gnatmake:
-Switches for *gnatmake*
------------------------
+Switches for ``gnatmake``
+-------------------------
-You may specify any of the following switches to *gnatmake*:
+You may specify any of the following switches to ``gnatmake``:
.. index:: --version (gnatmake)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatmake)
-:samp:`--help`
+:switch:`--help`
If ``--version`` was not used, display usage, then exit disregarding
all other options.
.. index:: --GCC=compiler_name (gnatmake)
-:samp:`--GCC={compiler_name}`
+:switch:`--GCC={compiler_name}`
Program used for compiling. The default is ``gcc``. You need to use
- quotes around `compiler_name` if `compiler_name` contains
+ quotes around ``compiler_name`` if ``compiler_name`` contains
spaces or other separator characters.
As an example ``--GCC="foo -x -y"``
- will instruct *gnatmake* to use ``foo -x -y`` as your
+ will instruct ``gnatmake`` to use ``foo -x -y`` as your
compiler. A limitation of this syntax is that the name and path name of
the executable itself must not include any embedded spaces. Note that
- switch ``-c`` is always inserted after your command name. Thus in the
- above example the compiler command that will be used by *gnatmake*
+ switch :switch:`-c` is always inserted after your command name. Thus in the
+ above example the compiler command that will be used by ``gnatmake``
will be ``foo -c -x -y``. If several ``--GCC=compiler_name`` are
- used, only the last `compiler_name` is taken into account. However,
+ used, only the last ``compiler_name`` is taken into account. However,
all the additional switches are also taken into account. Thus,
``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
``--GCC="bar -x -y -z -t"``.
.. index:: --GNATBIND=binder_name (gnatmake)
-:samp:`--GNATBIND={binder_name}`
+:switch:`--GNATBIND={binder_name}`
Program used for binding. The default is ``gnatbind``. You need to
- use quotes around `binder_name` if `binder_name` contains spaces
+ use quotes around ``binder_name`` if ``binder_name`` contains spaces
or other separator characters.
As an example ``--GNATBIND="bar -x -y"``
- will instruct *gnatmake* to use `bar -x -y` as your
- binder. Binder switches that are normally appended by *gnatmake*
- to ``gnatbind`` are now appended to the end of `bar -x -y`.
+ will instruct ``gnatmake`` to use ``bar -x -y`` as your
+ binder. Binder switches that are normally appended by ``gnatmake``
+ to ``gnatbind`` are now appended to the end of ``bar -x -y``.
A limitation of this syntax is that the name and path name of the executable
itself must not include any embedded spaces.
.. index:: --GNATLINK=linker_name (gnatmake)
-:samp:`--GNATLINK={linker_name}`
+:switch:`--GNATLINK={linker_name}`
Program used for linking. The default is ``gnatlink``. You need to
- use quotes around `linker_name` if `linker_name` contains spaces
+ use quotes around ``linker_name`` if ``linker_name`` contains spaces
or other separator characters.
As an example ``--GNATLINK="lan -x -y"``
- will instruct *gnatmake* to use ``lan -x -y`` as your
+ will instruct ``gnatmake`` to use ``lan -x -y`` as your
linker. Linker switches that are normally appended by ``gnatmake`` to
``gnatlink`` are now appended to the end of ``lan -x -y``.
A limitation of this syntax is that the name and path name of the executable
itself must not include any embedded spaces.
-:samp:`--create-map-file`
+:switch:`--create-map-file`
When linking an executable, create a map file. The name of the map file
has the same name as the executable with extension ".map".
-:samp:`--create-map-file={mapfile}`
+:switch:`--create-map-file={mapfile}`
When linking an executable, create a map file with the specified name.
.. index:: --create-missing-dirs (gnatmake)
-:samp:`--create-missing-dirs`
- When using project files (:samp:`-P{project}`), automatically create
+:switch:`--create-missing-dirs`
+ When using project files (:switch:`-P{project}`), automatically create
missing object directories, library directories and exec
directories.
-:samp:`--single-compile-per-obj-dir`
+:switch:`--single-compile-per-obj-dir`
Disallow simultaneous compilations in the same object directory when
project files are used.
-:samp:`--subdirs={subdir}`
+:switch:`--subdirs={subdir}`
Actual object directory of each project file is the subdirectory subdir of the
object directory specified or defaulted in the project file.
-:samp:`--unchecked-shared-lib-imports`
+:switch:`--unchecked-shared-lib-imports`
By default, shared library projects are not allowed to import static library
projects. When this switch is used on the command line, this restriction is
relaxed.
-:samp:`--source-info={source info file}`
+:switch:`--source-info={source info file}`
Specify a source info file. This switch is active only when project files
are used. If the source info file is specified as a relative path, then it is
relative to the object directory of the main project. If the source info file
long time. If the source info file exists but cannot be parsed successfully,
the Project Manager will attempt to recreate it. If the Project Manager fails
to create the source info file, a message is issued, but gnatmake does not
- fail. *gnatmake* "trusts" the source info file. This means that
+ fail. ``gnatmake`` "trusts" the source info file. This means that
if the source files have changed (addition, deletion, moving to a different
source directory), then the source info file need to be deleted and recreated.
.. index:: -a (gnatmake)
-:samp:`-a`
+:switch:`-a`
Consider all files in the make process, even the GNAT internal system
files (for example, the predefined Ada library files), as well as any
locked files. Locked files are files whose ALI file is write-protected.
By default,
- *gnatmake* does not check these files,
+ ``gnatmake`` does not check these files,
because the assumption is that the GNAT internal files are properly up
to date, and also that any write protected ALI files have been properly
installed. Note that if there is an installation problem, such that one
in conjunction with ``-f``
if you need to recompile an entire application,
including run-time files, using special configuration pragmas,
- such as a `Normalize_Scalars` pragma.
+ such as a ``Normalize_Scalars`` pragma.
By default
``gnatmake -a`` compiles all GNAT
.. index:: -b (gnatmake)
-:samp:`-b`
- Bind only. Can be combined with *-c* to do
+:switch:`-b`
+ Bind only. Can be combined with :switch:`-c` to do
compilation and binding, but no link.
- Can be combined with *-l*
+ Can be combined with :switch:`-l`
to do binding and linking. When not combined with
- *-c*
+ :switch:`-c`
all the units in the closure of the main program must have been previously
- compiled and must be up to date. The root unit specified by `file_name`
+ compiled and must be up to date. The root unit specified by ``file_name``
may be given without extension, with the source extension or, if no GNAT
Project File is specified, with the ALI file extension.
.. index:: -c (gnatmake)
-:samp:`-c`
- Compile only. Do not perform binding, except when *-b*
+:switch:`-c`
+ Compile only. Do not perform binding, except when :switch:`-b`
is also specified. Do not perform linking, except if both
- *-b* and
- *-l* are also specified.
- If the root unit specified by `file_name` is not a main unit, this is the
- default. Otherwise *gnatmake* will attempt binding and linking
+ :switch:`-b` and
+ :switch:`-l` are also specified.
+ If the root unit specified by ``file_name`` is not a main unit, this is the
+ default. Otherwise ``gnatmake`` will attempt binding and linking
unless all objects are up to date and the executable is more recent than
the objects.
.. index:: -C (gnatmake)
-:samp:`-C`
+:switch:`-C`
Use a temporary mapping file. A mapping file is a way to communicate
to the compiler two mappings: from unit names to file names (without
any directory information) and from file names to path names (with
full directory information). A mapping file can make the compiler's
file searches faster, especially if there are many source directories,
or the sources are read over a slow network connection. If
- *-P* is used, a mapping file is always used, so
- *-C* is unnecessary; in this case the mapping file
+ :switch:`-P` is used, a mapping file is always used, so
+ :switch:`-C` is unnecessary; in this case the mapping file
is initially populated based on the project file. If
- *-C* is used without
- *-P*,
+ :switch:`-C` is used without
+ :switch:`-P`,
the mapping file is initially empty. Each invocation of the compiler
will add any newly accessed sources to the mapping file.
.. index:: -C= (gnatmake)
-:samp:`-C={file}`
+:switch:`-C={file}`
Use a specific mapping file. The file, specified as a path name (absolute or
relative) by this switch, should already exist, otherwise the switch is
ineffective. The specified mapping file will be communicated to the compiler.
.. index:: -d (gnatmake)
-:samp:`-d`
+:switch:`-d`
Display progress for each source, up to date or not, as a single line:
::
.. index:: -D (gnatmake)
-:samp:`-D {dir}`
- Put all object files and ALI file in directory `dir`.
- If the *-D* switch is not used, all object files
+:switch:`-D {dir}`
+ Put all object files and ALI file in directory ``dir``.
+ If the :switch:`-D` switch is not used, all object files
and ALI files go in the current working directory.
This switch cannot be used when using a project file.
.. index:: -eI (gnatmake)
-:samp:`-eI{nnn}`
+:switch:`-eI{nnn}`
Indicates that the main source is a multi-unit source and the rank of the unit
in the source file is nnn. nnn needs to be a positive number and a valid
- index in the source. This switch cannot be used when *gnatmake* is
+ index in the source. This switch cannot be used when ``gnatmake`` is
invoked for several mains.
.. index:: -eL (gnatmake)
.. index:: symbolic links
-:samp:`-eL`
+:switch:`-eL`
Follow all symbolic links when processing project files.
This should be used if your project uses symbolic links for files or
directories, but is not needed in other cases.
.. index:: -eS (gnatmake)
-:samp:`-eS`
+:switch:`-eS`
Output the commands for the compiler, the binder and the linker
on standard output,
instead of standard error.
.. index:: -f (gnatmake)
-:samp:`-f`
+:switch:`-f`
Force recompilations. Recompile all sources, even though some object
files may be up to date, but don't recompile predefined or GNAT internal
files or locked files (files with a write-protected ALI file),
- unless the *-a* switch is also specified.
+ unless the :switch:`-a` switch is also specified.
.. index:: -F (gnatmake)
-:samp:`-F`
+:switch:`-F`
When using project files, if some errors or warnings are detected during
parsing and verbose mode is not in effect (no use of switch
-v), then error lines start with the full path name of the project
.. index:: -g (gnatmake)
-:samp:`-g`
+:switch:`-g`
Enable debugging. This switch is simply passed to the compiler and to the
linker.
.. index:: -i (gnatmake)
-:samp:`-i`
- In normal mode, *gnatmake* compiles all object files and ALI files
- into the current directory. If the *-i* switch is used,
+:switch:`-i`
+ In normal mode, ``gnatmake`` compiles all object files and ALI files
+ into the current directory. If the :switch:`-i` switch is used,
then instead object files and ALI files that already exist are overwritten
in place. This means that once a large project is organized into separate
- directories in the desired manner, then *gnatmake* will automatically
+ directories in the desired manner, then ``gnatmake`` will automatically
maintain and update this organization. If no ALI files are found on the
Ada object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`),
the new object and ALI files are created in the
directory containing the source being compiled. If another organization
is desired, where objects and sources are kept in different directories,
a useful technique is to create dummy ALI files in the desired directories.
- When detecting such a dummy file, *gnatmake* will be forced to
+ When detecting such a dummy file, ``gnatmake`` will be forced to
recompile the corresponding source file, and it will be put the resulting
object and ALI files in the directory where it found the dummy file.
.. index:: -j (gnatmake)
.. index:: Parallel make
-:samp:`-j{n}`
- Use `n` processes to carry out the (re)compilations. On a multiprocessor
- machine compilations will occur in parallel. If `n` is 0, then the
+:switch:`-j{n}`
+ Use ``n`` processes to carry out the (re)compilations. On a multiprocessor
+ machine compilations will occur in parallel. If ``n`` is 0, then the
maximum number of parallel compilations is the number of core processors
on the platform. In the event of compilation errors, messages from various
- compilations might get interspersed (but *gnatmake* will give you the
+ compilations might get interspersed (but ``gnatmake`` will give you the
full ordered list of failing compiles at the end). If this is problematic,
rerun the make process with n set to 1 to get a clean list of messages.
.. index:: -k (gnatmake)
-:samp:`-k`
+:switch:`-k`
Keep going. Continue as much as possible after a compilation error. To
ease the programmer's task in case of compilation errors, the list of
- sources for which the compile fails is given when *gnatmake*
+ sources for which the compile fails is given when ``gnatmake``
terminates.
- If *gnatmake* is invoked with several :file:`file_names` and with this
+ If ``gnatmake`` is invoked with several :file:`file_names` and with this
switch, if there are compilation errors when building an executable,
- *gnatmake* will not attempt to build the following executables.
+ ``gnatmake`` will not attempt to build the following executables.
.. index:: -l (gnatmake)
-:samp:`-l`
- Link only. Can be combined with *-b* to binding
+:switch:`-l`
+ Link only. Can be combined with :switch:`-b` to binding
and linking. Linking will not be performed if combined with
- *-c*
- but not with *-b*.
- When not combined with *-b*
+ :switch:`-c`
+ but not with :switch:`-b`.
+ When not combined with :switch:`-b`
all the units in the closure of the main program must have been previously
compiled and must be up to date, and the main program needs to have been bound.
- The root unit specified by `file_name`
+ The root unit specified by ``file_name``
may be given without extension, with the source extension or, if no GNAT
Project File is specified, with the ALI file extension.
.. index:: -m (gnatmake)
-:samp:`-m`
+:switch:`-m`
Specify that the minimum necessary amount of recompilations
- be performed. In this mode *gnatmake* ignores time
+ be performed. In this mode ``gnatmake`` ignores time
stamp differences when the only
modifications to a source file consist in adding/removing comments,
empty lines, spaces or tabs. This means that if you have changed the
comments in a source file or have simply reformatted it, using this
- switch will tell *gnatmake* not to recompile files that depend on it
+ switch will tell ``gnatmake`` not to recompile files that depend on it
(provided other sources on which these files depend have undergone no
semantic modifications). Note that the debugging information may be
- out of date with respect to the sources if the *-m* switch causes
+ out of date with respect to the sources if the :switch:`-m` switch causes
a compilation to be switched, so the use of this switch represents a
trade-off between compilation time and accurate debugging information.
.. index:: Dependencies, producing list
.. index:: -M (gnatmake)
-:samp:`-M`
+:switch:`-M`
Check if all objects are up to date. If they are, output the object
dependences to :file:`stdout` in a form that can be directly exploited in
a :file:`Makefile`. By default, each source file is prefixed with its
(relative or absolute) directory name. This name is whatever you
- specified in the various *-aI*
- and *-I* switches. If you use
- `gnatmake -M` *-q*
+ specified in the various :switch:`-aI`
+ and :switch:`-I` switches. If you use
+ ``gnatmake -M`` :switch:`-q`
(see below), only the source file names,
- without relative paths, are output. If you just specify the *-M*
+ without relative paths, are output. If you just specify the :switch:`-M`
switch, dependencies of the GNAT internal system files are omitted. This
is typically what you want. If you also specify
- the *-a* switch,
+ the :switch:`-a` switch,
dependencies of the GNAT internal files are also listed. Note that
dependencies of the objects in external Ada libraries (see
- switch :samp:`-aL{dir}` in the following list)
+ switch :switch:`-aL{dir}` in the following list)
are never reported.
.. index:: -n (gnatmake)
-:samp:`-n`
+:switch:`-n`
Don't compile, bind, or link. Checks if all objects are up to date.
If they are not, the full name of the first file that needs to be
recompiled is printed.
.. index:: -o (gnatmake)
-:samp:`-o {exec_name}`
+:switch:`-o {exec_name}`
Output executable name. The name of the final executable program will be
- `exec_name`. If the *-o* switch is omitted the default
+ ``exec_name``. If the :switch:`-o` switch is omitted the default
name for the executable will be the name of the input file in appropriate form
for an executable file on the host system.
- This switch cannot be used when invoking *gnatmake* with several
+ This switch cannot be used when invoking ``gnatmake`` with several
:file:`file_names`.
.. index:: -p (gnatmake)
-:samp:`-p`
- Same as :samp:`--create-missing-dirs`
+:switch:`-p`
+ Same as :switch:`--create-missing-dirs`
.. index:: -P (gnatmake)
-:samp:`-P{project}`
- Use project file `project`. Only one such switch can be used.
+:switch:`-P{project}`
+ Use project file ``project``. Only one such switch can be used.
.. -- Comment:
:ref:`gnatmake_and_Project_Files`.
.. index:: -q (gnatmake)
-:samp:`-q`
+:switch:`-q`
Quiet. When this flag is not set, the commands carried out by
- *gnatmake* are displayed.
+ ``gnatmake`` are displayed.
.. index:: -s (gnatmake)
-:samp:`-s`
+:switch:`-s`
Recompile if compiler switches have changed since last compilation.
All compiler switches but -I and -o are taken into account in the
following way:
orders between different 'first letter' switches are ignored, but
orders between same switches are taken into account. For example,
- *-O -O2* is different than *-O2 -O*, but *-g -O*
- is equivalent to *-O -g*.
+ :switch:`-O -O2` is different than :switch:`-O2 -O`, but :switch:`-g -O`
+ is equivalent to :switch:`-O -g`.
This switch is recommended when Integrated Preprocessing is used.
.. index:: -u (gnatmake)
-:samp:`-u`
+:switch:`-u`
Unique. Recompile at most the main files. It implies -c. Combined with
-f, it is equivalent to calling the compiler directly. Note that using
-u with a project file and no main has a special meaning.
.. index:: -U (gnatmake)
-:samp:`-U`
+:switch:`-U`
When used without a project file or with one or several mains on the command
line, is equivalent to -u. When used with a project file and no main
on the command line, all sources of all project files are checked and compiled
.. index:: -v (gnatmake)
-:samp:`-v`
- Verbose. Display the reason for all recompilations *gnatmake*
+:switch:`-v`
+ Verbose. Display the reason for all recompilations ``gnatmake``
decides are necessary, with the highest verbosity level.
.. index:: -vl (gnatmake)
-:samp:`-vl`
+:switch:`-vl`
Verbosity level Low. Display fewer lines than in verbosity Medium.
.. index:: -vm (gnatmake)
-:samp:`-vm`
+:switch:`-vm`
Verbosity level Medium. Potentially display fewer lines than in verbosity High.
.. index:: -vm (gnatmake)
-:samp:`-vh`
+:switch:`-vh`
Verbosity level High. Equivalent to -v.
-:samp:`-vP{x}`
+:switch:`-vP{x}`
Indicate the verbosity of the parsing of GNAT project files.
See :ref:`Switches_Related_to_Project_Files`.
.. index:: -x (gnatmake)
-:samp:`-x`
+:switch:`-x`
Indicate that sources that are not part of any Project File may be compiled.
Normally, when using Project Files, only sources that are part of a Project
File may be compile. When this switch is used, a source outside of all Project
Files may be compiled. The ALI file and the object file will be put in the
object directory of the main Project. The compilation switches used will only
be those specified on the command line. Even when
- *-x* is used, mains specified on the
+ :switch:`-x` is used, mains specified on the
command line need to be sources of a project file.
-:samp:`-X{name}={value}`
- Indicate that external variable `name` has the value `value`.
+:switch:`-X{name}={value}`
+ Indicate that external variable ``name`` has the value ``value``.
The Project Manager will use this value for occurrences of
- `external(name)` when parsing the project file.
+ ``external(name)`` when parsing the project file.
:ref:`Switches_Related_to_Project_Files`.
.. index:: -z (gnatmake)
-:samp:`-z`
+:switch:`-z`
No main subprogram. Bind and link the program even if the unit name
given on the command line is a package name. The resulting executable
will execute the elaboration routines of the package and its closure,
.. rubric:: GCC switches
-Any uppercase or multi-character switch that is not a *gnatmake* switch
-is passed to *gcc* (e.g., *-O*, *-gnato,* etc.)
+Any uppercase or multi-character switch that is not a ``gnatmake`` switch
+is passed to ``gcc`` (e.g., :switch:`-O`, :switch:`-gnato,` etc.)
.. rubric:: Source and library search path switches
.. index:: -aI (gnatmake)
-:samp:`-aI{dir}`
- When looking for source files also look in directory `dir`.
+:switch:`-aI{dir}`
+ When looking for source files also look in directory ``dir``.
The order in which source files search is undertaken is
described in :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
.. index:: -aL (gnatmake)
-:samp:`-aL{dir}`
- Consider `dir` as being an externally provided Ada library.
- Instructs *gnatmake* to skip compilation units whose :file:`.ALI`
- files have been located in directory `dir`. This allows you to have
- missing bodies for the units in `dir` and to ignore out of date bodies
+:switch:`-aL{dir}`
+ Consider ``dir`` as being an externally provided Ada library.
+ Instructs ``gnatmake`` to skip compilation units whose :file:`.ALI`
+ files have been located in directory ``dir``. This allows you to have
+ missing bodies for the units in ``dir`` and to ignore out of date bodies
for the same units. You still need to specify
the location of the specs for these units by using the switches
- :samp:`-aI{dir}` or :samp:`-I{dir}`.
+ :switch:`-aI{dir}` or :switch:`-I{dir}`.
Note: this switch is provided for compatibility with previous versions
- of *gnatmake*. The easier method of causing standard libraries
+ of ``gnatmake``. The easier method of causing standard libraries
to be excluded from consideration is to write-protect the corresponding
ALI files.
.. index:: -aO (gnatmake)
-:samp:`-aO{dir}`
+:switch:`-aO{dir}`
When searching for library and object files, look in directory
- `dir`. The order in which library files are searched is described in
+ ``dir``. The order in which library files are searched is described in
:ref:`Search_Paths_for_gnatbind`.
.. index:: Search paths, for gnatmake
.. index:: -A (gnatmake)
-:samp:`-A{dir}`
- Equivalent to :samp:`-aL{dir}` :samp:`-aI{dir}`.
+:switch:`-A{dir}`
+ Equivalent to :switch:`-aL{dir}` :switch:`-aI{dir}`.
.. index:: -I (gnatmake)
-:samp:`-I{dir}`
- Equivalent to :samp:`-aO{dir} -aI{dir}`.
+:switch:`-I{dir}`
+ Equivalent to :switch:`-aO{dir} -aI{dir}`.
.. index:: -I- (gnatmake)
.. index:: Source files, suppressing search
-:samp:`-I-`
+:switch:`-I-`
Do not look for source files in the directory containing the source
file named in the command line.
Do not look for ALI or object files in the directory
- where *gnatmake* was invoked.
+ where ``gnatmake`` was invoked.
.. index:: -L (gnatmake)
.. index:: Linker libraries
-:samp:`-L{dir}`
- Add directory `dir` to the list of directories in which the linker
+:switch:`-L{dir}`
+ Add directory ``dir`` to the list of directories in which the linker
will search for libraries. This is equivalent to
- :samp:`-largs` :samp:`-L{dir}`.
+ :switch:`-largs` :switch:`-L{dir}`.
Furthermore, under Windows, the sources pointed to by the libraries path
set in the registry are not searched for.
.. index:: -nostdinc (gnatmake)
-:samp:`-nostdinc`
+:switch:`-nostdinc`
Do not look for source files in the system default directory.
.. index:: -nostdlib (gnatmake)
-:samp:`-nostdlib`
+:switch:`-nostdlib`
Do not look for library files in the system default directory.
.. index:: --RTS (gnatmake)
-:samp:`--RTS={rts-path}`
+:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. GNAT looks for the
runtime
in the following directories, and stops as soon as a valid runtime is found
.. _Mode_Switches_for_gnatmake:
-Mode Switches for *gnatmake*
-----------------------------
+Mode Switches for ``gnatmake``
+------------------------------
-The mode switches (referred to as `mode_switches`) allow the
+The mode switches (referred to as ``mode_switches``) allow the
inclusion of switches that are to be passed to the compiler itself, the
binder or the linker. The effect of a mode switch is to cause all
subsequent switches up to the end of the switch list, or up to the next
.. index:: -cargs (gnatmake)
-:samp:`-cargs {switches}`
- Compiler switches. Here `switches` is a list of switches
- that are valid switches for *gcc*. They will be passed on to
- all compile steps performed by *gnatmake*.
+:switch:`-cargs {switches}`
+ Compiler switches. Here ``switches`` is a list of switches
+ that are valid switches for ``gcc``. They will be passed on to
+ all compile steps performed by ``gnatmake``.
.. index:: -bargs (gnatmake)
-:samp:`-bargs {switches}`
- Binder switches. Here `switches` is a list of switches
- that are valid switches for `gnatbind`. They will be passed on to
- all bind steps performed by *gnatmake*.
+:switch:`-bargs {switches}`
+ Binder switches. Here ``switches`` is a list of switches
+ that are valid switches for ``gnatbind``. They will be passed on to
+ all bind steps performed by ``gnatmake``.
.. index:: -largs (gnatmake)
-:samp:`-largs {switches}`
- Linker switches. Here `switches` is a list of switches
- that are valid switches for *gnatlink*. They will be passed on to
- all link steps performed by *gnatmake*.
+:switch:`-largs {switches}`
+ Linker switches. Here ``switches`` is a list of switches
+ that are valid switches for ``gnatlink``. They will be passed on to
+ all link steps performed by ``gnatmake``.
.. index:: -margs (gnatmake)
-:samp:`-margs {switches}`
- Make switches. The switches are directly interpreted by *gnatmake*,
- regardless of any previous occurrence of *-cargs*, *-bargs*
- or *-largs*.
+:switch:`-margs {switches}`
+ Make switches. The switches are directly interpreted by ``gnatmake``,
+ regardless of any previous occurrence of :switch:`-cargs`, :switch:`-bargs`
+ or :switch:`-largs`.
.. _Notes_on_the_Command_Line:
-------------------------
This section contains some additional useful notes on the operation
-of the *gnatmake* command.
+of the ``gnatmake`` command.
.. index:: Recompilation (by gnatmake)
-* If *gnatmake* finds no ALI files, it recompiles the main program
+* If ``gnatmake`` finds no ALI files, it recompiles the main program
and all other units required by the main program.
- This means that *gnatmake*
+ This means that ``gnatmake``
can be used for the initial compile, as well as during subsequent steps of
the development cycle.
* If you enter ``gnatmake foo.adb``, where ``foo``
- is a subunit or body of a generic unit, *gnatmake* recompiles
+ is a subunit or body of a generic unit, ``gnatmake`` recompiles
:file:`foo.adb` (because it finds no ALI) and stops, issuing a
warning.
-* In *gnatmake* the switch *-I*
+* In ``gnatmake`` the switch :switch:`-I`
is used to specify both source and
- library file paths. Use *-aI*
+ library file paths. Use :switch:`-aI`
instead if you just want to specify
- source paths only and *-aO*
+ source paths only and :switch:`-aO`
if you want to specify library paths
only.
-* *gnatmake* will ignore any files whose ALI file is write-protected.
+* ``gnatmake`` will ignore any files whose ALI file is write-protected.
This may conveniently be used to exclude standard libraries from
consideration and in particular it means that the use of the
- *-f* switch will not recompile these files
- unless *-a* is also specified.
+ :switch:`-f` switch will not recompile these files
+ unless :switch:`-a` is also specified.
-* *gnatmake* has been designed to make the use of Ada libraries
+* ``gnatmake`` has been designed to make the use of Ada libraries
particularly convenient. Assume you have an Ada library organized
as follows: *obj-dir* contains the objects and ALI files for
of your Ada compilation units,
whereas *include-dir* contains the
specs of these units, but no bodies. Then to compile a unit
- stored in `main.adb`, which uses this Ada library you would just type:
+ stored in ``main.adb``, which uses this Ada library you would just type:
.. code-block:: sh
$ gnatmake -aI`include-dir` -aL`obj-dir` main
-* Using *gnatmake* along with the *-m (minimal recompilation)*
+* Using ``gnatmake`` along with the :switch:`-m (minimal recompilation)`
switch provides a mechanism for avoiding unnecessary recompilations. Using
this switch,
you can update the comments/format of your
.. _How_gnatmake_Works:
-How *gnatmake* Works
---------------------
+How ``gnatmake`` Works
+----------------------
-Generally *gnatmake* automatically performs all necessary
+Generally ``gnatmake`` automatically performs all necessary
recompilations and you don't need to worry about how it works. However,
-it may be useful to have some basic understanding of the *gnatmake*
+it may be useful to have some basic understanding of the ``gnatmake``
approach and in particular to understand how it uses the results of
previous compilations without incorrectly depending on them.
files that it depends on have been modified, and hence there is no need
to recompile this file.
-*gnatmake* works by first checking if the specified main unit is up
+``gnatmake`` works by first checking if the specified main unit is up
to date. If so, no compilations are required for the main unit. If not,
-*gnatmake* compiles the main program to build a new ALI file that
+``gnatmake`` compiles the main program to build a new ALI file that
reflects the latest sources. Then the ALI file of the main unit is
examined to find all the source files on which the main program depends,
-and *gnatmake* recursively applies the above procedure on all these
+and ``gnatmake`` recursively applies the above procedure on all these
files.
-This process ensures that *gnatmake* only trusts the dependencies
+This process ensures that ``gnatmake`` only trusts the dependencies
in an existing ALI file if they are known to be correct. Otherwise it
always recompiles to determine a new, guaranteed accurate set of
dependencies. As a result the program is compiled 'upside down' from what may
systems. In particular, clients are compiled before the units on which
they depend. The ability of GNAT to compile in any order is critical in
allowing an order of compilation to be chosen that guarantees that
-*gnatmake* will recompute a correct set of new dependencies if
+``gnatmake`` will recompute a correct set of new dependencies if
necessary.
-When invoking *gnatmake* with several `file_names`, if a unit is
+When invoking ``gnatmake`` with several ``file_names``, if a unit is
imported by several of the executables, it will be recompiled at most once.
Note: when using non-standard naming conventions
(:ref:`Using_Other_File_Names`), changing through a configuration pragmas
-file the version of a source and invoking *gnatmake* to recompile may
+file the version of a source and invoking ``gnatmake`` to recompile may
have no effect, if the previous version of the source is still accessible
-by *gnatmake*. It may be necessary to use the switch
+by ``gnatmake``. It may be necessary to use the switch
-f.
.. _Examples_of_gnatmake_Usage:
-Examples of *gnatmake* Usage
-----------------------------
+Examples of ``gnatmake`` Usage
+------------------------------
*gnatmake hello.adb*
Compile all files necessary to bind and link the main program
- :file:`hello.adb` (containing unit `Hello`) and bind and link the
+ :file:`hello.adb` (containing unit ``Hello``) and bind and link the
resulting object files to generate an executable file :file:`hello`.
*gnatmake main1 main2 main3*
Compile all files necessary to bind and link the main programs
- :file:`main1.adb` (containing unit `Main1`), :file:`main2.adb`
- (containing unit `Main2`) and :file:`main3.adb`
- (containing unit `Main3`) and bind and link the resulting object files
+ :file:`main1.adb` (containing unit ``Main1``), :file:`main2.adb`
+ (containing unit ``Main2``) and :file:`main3.adb`
+ (containing unit ``Main3``) and bind and link the resulting object files
to generate three executable files :file:`main1`,
:file:`main2` and :file:`main3`.
*gnatmake -q Main_Unit -cargs -O2 -bargs -l*
Compile all files necessary to bind and link the main program unit
- `Main_Unit` (from file :file:`main_unit.adb`). All compilations will
+ ``Main_Unit`` (from file :file:`main_unit.adb`). All compilations will
be done with optimization level 2 and the order of elaboration will be
- listed by the binder. *gnatmake* will operate in quiet mode, not
+ listed by the binder. ``gnatmake`` will operate in quiet mode, not
displaying commands it is executing.
.. _Compiling_with_gcc:
-Compiling with *gcc*
-====================
+Compiling with ``gcc``
+======================
-This section discusses how to compile Ada programs using the *gcc*
+This section discusses how to compile Ada programs using the ``gcc``
command. It also describes the set of switches
that can be used to control the behavior of the compiler.
------------------
The first step in creating an executable program is to compile the units
-of the program using the *gcc* command. You must compile the
+of the program using the ``gcc`` command. You must compile the
following files:
* the body file (:file:`.adb`) for a library level subprogram or generic
.. index:: cannot generate code
If you attempt to compile any of these files, you will get one of the
-following error messages (where `fff` is the name of the file you
+following error messages (where ``fff`` is the name of the file you
compiled):
::
- cannot generate code for file `fff` (package spec)
+ cannot generate code for file ``fff`` (package spec)
to check package spec, use -gnatc
- cannot generate code for file `fff` (missing subunits)
+ cannot generate code for file ``fff`` (missing subunits)
to check parent unit, use -gnatc
- cannot generate code for file `fff` (subprogram spec)
+ cannot generate code for file ``fff`` (subprogram spec)
to check subprogram spec, use -gnatc
- cannot generate code for file `fff` (subunit)
+ cannot generate code for file ``fff`` (subunit)
to check subunit, use -gnatc
As indicated by the above error messages, if you want to submit
one of these files to the compiler to check for correct semantics
-without generating code, then use the *-gnatc* switch.
+without generating code, then use the :switch:`-gnatc` switch.
The basic command for compiling a file containing an Ada unit is:
$ gcc -c [switches] <file name>
-where `file name` is the name of the Ada file (usually
+where ``file name`` is the name of the Ada file (usually
having an extension :file:`.ads` for a spec or :file:`.adb` for a body).
You specify the
-:option:`-c` switch to tell *gcc* to compile, but not link, the file.
+:switch:`-c` switch to tell ``gcc`` to compile, but not link, the file.
The result of a successful compilation is an object file, which has the
same name as the source file but an extension of :file:`.o` and an Ada
Library Information (ALI) file, which also has the same name as the
file in any directory using an absolute or relative path specification
containing the directory information.
+TESTING: the :switch:`--foobar{NN}` switch
+
.. index:: gnat1
-*gcc* is actually a driver program that looks at the extensions of
+``gcc`` is actually a driver program that looks at the extensions of
the file arguments and loads the appropriate compiler. For example, the
GNU C compiler is :file:`cc1`, and the Ada compiler is :file:`gnat1`.
These programs are in directories known to the driver program (in some
configurations via environment variables you set), but need not be in
-your path. The *gcc* driver also calls the assembler and any other
+your path. The ``gcc`` driver also calls the assembler and any other
utilities needed to complete the generation of the required object
files.
-It is possible to supply several file names on the same *gcc*
-command. This causes *gcc* to call the appropriate compiler for
+It is possible to supply several file names on the same ``gcc``
+command. This causes ``gcc`` to call the appropriate compiler for
each file. For example, the following command lists two separate
files to be compiled:
$ gcc -c x.adb y.adb
-calls `gnat1` (the Ada compiler) twice to compile :file:`x.adb` and
+calls ``gnat1`` (the Ada compiler) twice to compile :file:`x.adb` and
:file:`y.adb`.
The compiler generates two object files :file:`x.o` and :file:`y.o`
and the two ALI files :file:`x.ali` and :file:`y.ali`.
Any switches apply to all the files listed, see :ref:`Switches_for_gcc` for a
-list of available *gcc* switches.
+list of available ``gcc`` switches.
.. _Search_Paths_and_the_Run-Time_Library_RTL:
* The directory containing the source file of the main unit being compiled
(the file name on the command line).
-* Each directory named by an *-I* switch given on the *gcc*
+* Each directory named by an :switch:`-I` switch given on the ``gcc``
command line, in the order given.
.. index:: ADA_PRJ_INCLUDE_FILE
GNAT Run Time Library (RTL) source files.
:ref:`Installing_a_library`
-Specifying the switch *-I-*
+Specifying the switch :switch:`-I-`
inhibits the use of the directory
containing the source file named in the command line. You can still
have this directory on your search path, but in this case it must be
-explicitly requested with a *-I* switch.
+explicitly requested with a :switch:`-I` switch.
-Specifying the switch *-nostdinc*
+Specifying the switch :switch:`-nostdinc`
inhibits the search of the default location for the GNAT Run Time
Library (RTL) source files.
The compiler outputs its object files and ALI files in the current
working directory.
-Caution: The object file can be redirected with the *-o* switch;
-however, *gcc* and `gnat1` have not been coordinated on this
+Caution: The object file can be redirected with the :switch:`-o` switch;
+however, ``gcc`` and ``gnat1`` have not been coordinated on this
so the :file:`ALI` file will not go to the right place. Therefore, you should
-avoid using the *-o* switch.
+avoid using the :switch:`-o` switch.
.. index:: System.IO
-The packages `Ada`, `System`, and `Interfaces` and their
-children make up the GNAT RTL, together with the simple `System.IO`
-package used in the `"Hello World"` example. The sources for these units
+The packages ``Ada``, ``System``, and ``Interfaces`` and their
+children make up the GNAT RTL, together with the simple ``System.IO``
+package used in the ``"Hello World"`` example. The sources for these units
are needed by the compiler and are kept together in one directory. Not
all of the bodies are needed, but all of the sources are kept together
anyway. In a normal installation, you need not specify these directory
names when compiling or binding. Either the environment variables or
the built-in defaults cause these files to be found.
-In addition to the language-defined hierarchies (`System`, `Ada` and
-`Interfaces`), the GNAT distribution provides a fourth hierarchy,
-consisting of child units of `GNAT`. This is a collection of generally
+In addition to the language-defined hierarchies (``System``, ``Ada`` and
+``Interfaces``), the GNAT distribution provides a fourth hierarchy,
+consisting of child units of ``GNAT``. This is a collection of generally
useful types, subprograms, etc. See the :title:`GNAT_Reference_Manual`
for further details.
Order of Compilation Issues
---------------------------
-If, in our earlier example, there was a spec for the `hello`
+If, in our earlier example, there was a spec for the ``hello``
procedure, it would be contained in the file :file:`hello.ads`; yet this
file would not have to be explicitly compiled. This is the result of the
model we chose to implement library management. Some of the consequences
$ gcc -c -O2 -gnata xyz-def.adb
Compile the child unit package in file :file:`xyz-def.adb` with extensive
-optimizations, and pragma `Assert`/`Debug` statements
+optimizations, and pragma ``Assert``/`Debug` statements
enabled.
.. code-block:: sh
Compiler Switches
=================
-The *gcc* command accepts switches that control the
+The ``gcc`` command accepts switches that control the
compilation process. These switches are fully described in this section:
first an alphabetical listing of all switches with a brief description,
and then functionally grouped sets of switches with more detailed
.. index:: -b (gcc)
-:samp:`-b {target}`
- Compile your program to run on `target`, which is the name of a
+:switch:`-b {target}`
+ Compile your program to run on ``target``, which is the name of a
system configuration. You must have a GNAT cross-compiler built if
- `target` is not the same as your host system.
+ ``target`` is not the same as your host system.
.. index:: -B (gcc)
-:samp:`-B{dir}`
- Load compiler executables (for example, `gnat1`, the Ada compiler)
- from `dir` instead of the default location. Only use this switch
+:switch:`-B{dir}`
+ Load compiler executables (for example, ``gnat1``, the Ada compiler)
+ from ``dir`` instead of the default location. Only use this switch
when multiple versions of the GNAT compiler are available.
See the "Options for Directory Search" section in the
:title:`Using the GNU Compiler Collection (GCC)` manual for further details.
- You would normally use the *-b* or *-V* switch instead.
+ You would normally use the :switch:`-b` or :switch:`-V` switch instead.
.. index:: -c (gcc)
-:samp:`-c`
+:switch:`-c`
Compile. Always use this switch when compiling Ada programs.
- Note: for some other languages when using *gcc*, notably in
+ Note: for some other languages when using ``gcc``, notably in
the case of C and C++, it is possible to use
- use *gcc* without a *-c* switch to
+ use ``gcc`` without a :switch:`-c` switch to
compile and link in one step. In the case of GNAT, you
cannot use this approach, because the binder must be run
- and *gcc* cannot be used to run the GNAT binder.
+ and ``gcc`` cannot be used to run the GNAT binder.
.. index:: -fcallgraph-info (gcc)
-:samp:`-fcallgraph-info[=su,da]`
+:switch:`-fcallgraph-info[=su,da]`
Makes the compiler output callgraph information for the program, on a
per-file basis. The information is generated in the VCG format. It can
be decorated with additional, per-node and/or per-edge information, if a
list of comma-separated markers is additionally specified. When the
- `su` marker is specified, the callgraph is decorated with stack usage
- information; it is equivalent to *-fstack-usage*. When the `da`
+ ``su`` marker is specified, the callgraph is decorated with stack usage
+ information; it is equivalent to :switch:`-fstack-usage`. When the ``da``
marker is specified, the callgraph is decorated with information about
dynamically allocated objects.
.. index:: -fdump-scos (gcc)
-:samp:`-fdump-scos`
+:switch:`-fdump-scos`
Generates SCO (Source Coverage Obligation) information in the ALI file.
This information is used by advanced coverage tools. See unit :file:`SCOs`
in the compiler sources for details in files :file:`scos.ads` and
.. index:: -fdump-xref (gcc)
-:samp:`-fdump-xref`
+:switch:`-fdump-xref`
Generates cross reference information in GLI files for C and C++ sources.
The GLI files have the same syntax as the ALI files for Ada, and can be used
for source navigation in IDEs and on the command line using e.g. gnatxref
- and the *--ext=gli* switch.
+ and the :switch:`--ext=gli` switch.
.. index:: -flto (gcc)
-:samp:`-flto[={n}]`
+:switch:`-flto[={n}]`
Enables Link Time Optimization. This switch must be used in conjunction
- with the traditional *-Ox* switches and instructs the compiler to
+ with the traditional :switch:`-Ox` switches and instructs the compiler to
defer most optimizations until the link stage. The advantage of this
approach is that the compiler can do a whole-program analysis and choose
the best interprocedural optimization strategy based on a complete view
of the program, instead of a fragmentary view with the usual approach.
This can also speed up the compilation of big programs and reduce the
size of the executable, compared with a traditional per-unit compilation
- with inlining across modules enabled by the *-gnatn* switch.
+ with inlining across modules enabled by the :switch:`-gnatn` switch.
The drawback of this approach is that it may require more memory and that
the debugging information generated by -g with it might be hardly usable.
- The switch, as well as the accompanying *-Ox* switches, must be
+ The switch, as well as the accompanying :switch:`-Ox` switches, must be
specified both for the compilation and the link phases.
- If the `n` parameter is specified, the optimization and final code
- generation at link time are executed using `n` parallel jobs by
- means of an installed *make* program.
+ If the ``n`` parameter is specified, the optimization and final code
+ generation at link time are executed using ``n`` parallel jobs by
+ means of an installed ``make`` program.
.. index:: -fno-inline (gcc)
-:samp:`-fno-inline`
- Suppresses all inlining, unless requested with pragma `Inline_Always`. The
+:switch:`-fno-inline`
+ Suppresses all inlining, unless requested with pragma ``Inline_Always``. The
effect is enforced regardless of other optimization or inlining switches.
Note that inlining can also be suppressed on a finer-grained basis with
- pragma `No_Inline`.
+ pragma ``No_Inline``.
.. index:: -fno-inline-functions (gcc)
-:samp:`-fno-inline-functions`
+:switch:`-fno-inline-functions`
Suppresses automatic inlining of subprograms, which is enabled
- if *-O3* is used.
+ if :switch:`-O3` is used.
.. index:: -fno-inline-small-functions (gcc)
-:samp:`-fno-inline-small-functions`
+:switch:`-fno-inline-small-functions`
Suppresses automatic inlining of small subprograms, which is enabled
- if *-O2* is used.
+ if :switch:`-O2` is used.
.. index:: -fno-inline-functions-called-once (gcc)
-:samp:`-fno-inline-functions-called-once`
+:switch:`-fno-inline-functions-called-once`
Suppresses inlining of subprograms local to the unit and called once
- from within it, which is enabled if *-O1* is used.
+ from within it, which is enabled if :switch:`-O1` is used.
.. index:: -fno-ivopts (gcc)
-:samp:`-fno-ivopts`
+:switch:`-fno-ivopts`
Suppresses high-level loop induction variable optimizations, which are
- enabled if *-O1* is used. These optimizations are generally
+ enabled if :switch:`-O1` is used. These optimizations are generally
profitable but, for some specific cases of loops with numerous uses
of the iteration variable that follow a common pattern, they may end
up destroying the regularity that could be exploited at a lower level
.. index:: -fno-strict-aliasing (gcc)
-:samp:`-fno-strict-aliasing`
+:switch:`-fno-strict-aliasing`
Causes the compiler to avoid assumptions regarding non-aliasing
of objects of different types. See
:ref:`Optimization_and_Strict_Aliasing` for details.
.. index:: -fno-strict-overflow (gcc)
-:samp:`-fno-strict-overflow`
+:switch:`-fno-strict-overflow`
Causes the compiler to avoid assumptions regarding the rules of signed
integer overflow. These rules specify that signed integer overflow will
result in a Constraint_Error exception at run time and are enforced in
default mode by the compiler, so this switch should not be necessary in
- normal operating mode. It might be useful in conjunction with *-gnato0*
+ normal operating mode. It might be useful in conjunction with :switch:`-gnato0`
for very peculiar cases of low-level programming.
.. index:: -fstack-check (gcc)
-:samp:`-fstack-check`
+:switch:`-fstack-check`
Activates stack checking.
See :ref:`Stack_Overflow_Checking` for details.
.. index:: -fstack-usage (gcc)
-:samp:`-fstack-usage`
+:switch:`-fstack-usage`
Makes the compiler output stack usage information for the program, on a
per-subprogram basis. See :ref:`Static_Stack_Usage_Analysis` for details.
.. index:: -g (gcc)
-:samp:`-g`
+:switch:`-g`
Generate debugging information. This information is stored in the object
file and copied from there to the final executable file by the linker,
where it can be read by the debugger. You must use the
- *-g* switch if you plan on using the debugger.
+ :switch:`-g` switch if you plan on using the debugger.
.. index:: -gnat05 (gcc)
-:samp:`-gnat05`
+:switch:`-gnat05`
Allow full Ada 2005 features.
.. index:: -gnat12 (gcc)
-:samp:`-gnat12`
+:switch:`-gnat12`
Allow full Ada 2012 features.
.. index:: -gnat83 (gcc)
.. index:: -gnat2005 (gcc)
-:samp:`-gnat2005`
- Allow full Ada 2005 features (same as *-gnat05*)
+:switch:`-gnat2005`
+ Allow full Ada 2005 features (same as :switch:`-gnat05`)
.. index:: -gnat2012 (gcc)
-:samp:`-gnat2012`
- Allow full Ada 2012 features (same as *-gnat12*)
+:switch:`-gnat2012`
+ Allow full Ada 2012 features (same as :switch:`-gnat12`)
-:samp:`-gnat83`
+:switch:`-gnat83`
Enforce Ada 83 restrictions.
.. index:: -gnat95 (gcc)
-:samp:`-gnat95`
+:switch:`-gnat95`
Enforce Ada 95 restrictions.
Note: for compatibility with some Ada 95 compilers which support only
- the `overriding` keyword of Ada 2005, the *-gnatd.D* switch can
- be used along with *-gnat95* to achieve a similar effect with GNAT.
+ the ``overriding`` keyword of Ada 2005, the :switch:`-gnatd.D` switch can
+ be used along with :switch:`-gnat95` to achieve a similar effect with GNAT.
- *-gnatd.D* instructs GNAT to consider `overriding` as a keyword
+ :switch:`-gnatd.D` instructs GNAT to consider ``overriding`` as a keyword
and handle its associated semantic checks, even in Ada 95 mode.
.. index:: -gnata (gcc)
-:samp:`-gnata`
- Assertions enabled. `Pragma Assert` and `pragma Debug` to be
+:switch:`-gnata`
+ Assertions enabled. ``Pragma Assert`` and ``pragma Debug`` to be
activated. Note that these pragmas can also be controlled using the
- configuration pragmas `Assertion_Policy` and `Debug_Policy`.
- It also activates pragmas `Check`, `Precondition`, and
- `Postcondition`. Note that these pragmas can also be controlled
- using the configuration pragma `Check_Policy`. In Ada 2012, it
+ configuration pragmas ``Assertion_Policy`` and ``Debug_Policy``.
+ It also activates pragmas ``Check``, ``Precondition``, and
+ ``Postcondition``. Note that these pragmas can also be controlled
+ using the configuration pragma ``Check_Policy``. In Ada 2012, it
also activates all assertions defined in the RM as aspects: preconditions,
postconditions, type invariants and (sub)type predicates. In all Ada modes,
corresponding pragmas for type invariants and (sub)type predicates are
.. index:: -gnatA (gcc)
-:samp:`-gnatA`
+:switch:`-gnatA`
Avoid processing :file:`gnat.adc`. If a :file:`gnat.adc` file is present,
it will be ignored.
.. index:: -gnatb (gcc)
-:samp:`-gnatb`
+:switch:`-gnatb`
Generate brief messages to :file:`stderr` even if verbose mode set.
.. index:: -gnatB (gcc)
-:samp:`-gnatB`
+:switch:`-gnatB`
Assume no invalid (bad) values except for 'Valid attribute use
(:ref:`Validity_Checking`).
.. index:: -gnatc (gcc)
-:samp:`-gnatc`
+:switch:`-gnatc`
Check syntax and semantics only (no code generation attempted). When the
- compiler is invoked by *gnatmake*, if the switch *-gnatc* is
- only given to the compiler (after *-cargs* or in package Compiler of
- the project file, *gnatmake* will fail because it will not find the
- object file after compilation. If *gnatmake* is called with
- *-gnatc* as a builder switch (before *-cargs* or in package
- Builder of the project file) then *gnatmake* will not fail because
+ compiler is invoked by ``gnatmake``, if the switch :switch:`-gnatc` is
+ only given to the compiler (after :switch:`-cargs` or in package Compiler of
+ the project file, ``gnatmake`` will fail because it will not find the
+ object file after compilation. If ``gnatmake`` is called with
+ :switch:`-gnatc` as a builder switch (before :switch:`-cargs` or in package
+ Builder of the project file) then ``gnatmake`` will not fail because
it will not look for the object files after compilation, and it will not try
to build and link.
.. index:: -gnatC (gcc)
-:samp:`-gnatC`
+:switch:`-gnatC`
Generate CodePeer intermediate format (no code generation attempted).
This switch will generate an intermediate representation suitable for
use by CodePeer (:file:`.scil` files). This switch is not compatible with
.. index:: -gnatd (gcc)
-:samp:`-gnatd`
+:switch:`-gnatd`
Specify debug options for the compiler. The string of characters after
- the *-gnatd* specify the specific debug options. The possible
+ the :switch:`-gnatd` specify the specific debug options. The possible
characters are 0-9, a-z, A-Z, optionally preceded by a dot. See
compiler source file :file:`debug.adb` for details of the implemented
debug options. Certain debug options are relevant to applications
.. index:: -gnatD[nn] (gcc)
-:samp:`-gnatD`
+:switch:`-gnatD`
Create expanded source files for source level debugging. This switch
also suppresses generation of cross-reference information
- (see *-gnatx*). Note that this switch is not allowed if a previous
+ (see :switch:`-gnatx`). Note that this switch is not allowed if a previous
-gnatR switch has been given, since these two switches are not compatible.
.. index:: -gnateA (gcc)
-:samp:`-gnateA`
+:switch:`-gnateA`
Check that the actual parameters of a subprogram call are not aliases of one
another. To qualify as aliasing, the actuals must denote objects of a composite
type, their memory locations must be identical or overlapping, and at least one
Detect_Aliasing (Obj, Self (Obj));
- In the example above, the first call to `Detect_Aliasing` fails with a
- `Program_Error` at runtime because the actuals for `Val_1` and
- `Val_2` denote the same object. The second call executes without raising
- an exception because `Self(Obj)` produces an anonymous object which does
- not share the memory location of `Obj`.
+ In the example above, the first call to ``Detect_Aliasing`` fails with a
+ ``Program_Error`` at runtime because the actuals for ``Val_1`` and
+ ``Val_2`` denote the same object. The second call executes without raising
+ an exception because ``Self(Obj)`` produces an anonymous object which does
+ not share the memory location of ``Obj``.
.. index:: -gnatec (gcc)
-:samp:`-gnatec={path}`
+:switch:`-gnatec={path}`
Specify a configuration pragma file
(the equal sign is optional)
(:ref:`The_Configuration_Pragmas_Files`).
.. index:: -gnateC (gcc)
-:samp:`-gnateC`
+:switch:`-gnateC`
Generate CodePeer messages in a compiler-like format. This switch is only
- effective if *-gnatcC* is also specified and requires an installation
+ effective if :switch:`-gnatcC` is also specified and requires an installation
of CodePeer.
.. index:: -gnated (gcc)
-:samp:`-gnated`
+:switch:`-gnated`
Disable atomic synchronization
.. index:: -gnateD (gcc)
-:samp:`-gnateDsymbol[={value}]`
- Defines a symbol, associated with `value`, for preprocessing.
+:switch:`-gnateDsymbol[={value}]`
+ Defines a symbol, associated with ``value``, for preprocessing.
(:ref:`Integrated_Preprocessing`).
.. index:: -gnateE (gcc)
-:samp:`-gnateE`
+:switch:`-gnateE`
Generate extra information in exception messages. In particular, display
extra column information and the value and range associated with index and
range check failures, and extra column information for access checks.
.. index:: -gnatef (gcc)
-:samp:`-gnatef`
+:switch:`-gnatef`
Display full source path name in brief error messages.
.. index:: -gnateF (gcc)
-:samp:`-gnateF`
+:switch:`-gnateF`
Check for overflow on all floating-point operations, including those
for unconstrained predefined types. See description of pragma
- `Check_Float_Overflow` in GNAT RM.
+ ``Check_Float_Overflow`` in GNAT RM.
.. index:: -gnateg (gcc)
-:samp:`-gnateg`
-:samp:`-gnatceg`
+:switch:`-gnateg`
+:switch:`-gnatceg`
- The `-gnatc` switch must always be specified before this switch, e.g.
- `-gnatceg`. Generate a C header from the Ada input file. See
+ The :switch:`-gnatc` switch must always be specified before this switch, e.g.
+ :switch:`-gnatceg`. Generate a C header from the Ada input file. See
:ref:`Generating_C_Headers_for_Ada_Specifications` for more
information.
.. index:: -gnateG (gcc)
-:samp:`-gnateG`
+:switch:`-gnateG`
Save result of preprocessing in a text file.
.. index:: -gnatei (gcc)
-:samp:`-gnatei{nnn}`
+:switch:`-gnatei{nnn}`
Set maximum number of instantiations during compilation of a single unit to
- `nnn`. This may be useful in increasing the default maximum of 8000 for
+ ``nnn``. This may be useful in increasing the default maximum of 8000 for
the rare case when a single unit legitimately exceeds this limit.
.. index:: -gnateI (gcc)
-:samp:`-gnateI{nnn}`
+:switch:`-gnateI{nnn}`
Indicates that the source is a multi-unit source and that the index of the
- unit to compile is `nnn`. `nnn` needs to be a positive number and need
+ unit to compile is ``nnn``. ``nnn`` needs to be a positive number and need
to be a valid index in the multi-unit source.
.. index:: -gnatel (gcc)
-:samp:`-gnatel`
+:switch:`-gnatel`
This switch can be used with the static elaboration model to issue info
messages showing
- where implicit `pragma Elaborate` and `pragma Elaborate_All`
+ where implicit ``pragma Elaborate`` and ``pragma Elaborate_All``
are generated. This is useful in diagnosing elaboration circularities
caused by these implicit pragmas when using the static elaboration
model. See See the section in this guide on elaboration checking for
.. index:: -gnatel (gcc)
-:samp:`-gnateL`
+:switch:`-gnateL`
This switch turns off the info messages about implicit elaboration pragmas.
.. index:: -gnatem (gcc)
-:samp:`-gnatem={path}`
+:switch:`-gnatem={path}`
Specify a mapping file
(the equal sign is optional)
(:ref:`Units_to_Sources_Mapping_Files`).
.. index:: -gnatep (gcc)
-:samp:`-gnatep={file}`
+:switch:`-gnatep={file}`
Specify a preprocessing data file
(the equal sign is optional)
(:ref:`Integrated_Preprocessing`).
.. index:: -gnateP (gcc)
-:samp:`-gnateP`
+:switch:`-gnateP`
Turn categorization dependency errors into warnings.
Ada requires that units that WITH one another have compatible categories, for
example a Pure unit cannot WITH a Preelaborate unit. If this switch is used,
.. index:: -gnateS (gcc)
-:samp:`-gnateS`
- Synonym of *-fdump-scos*, kept for backwards compatibility.
+:switch:`-gnateS`
+ Synonym of :switch:`-fdump-scos`, kept for backwards compatibility.
.. index:: -gnatet=file (gcc)
-:samp:`-gnatet={path}`
+:switch:`-gnatet={path}`
Generate target dependent information. The format of the output file is
- described in the section about switch *-gnateT*.
+ described in the section about switch :switch:`-gnateT`.
.. index:: -gnateT (gcc)
-:samp:`-gnateT={path}`
+:switch:`-gnateT={path}`
Read target dependent information, such as endianness or sizes and alignments
of base type. If this switch is passed, the default target dependent
information of the compiler is replaced by the one read from the input file.
the machine on which the tool is run.
The following target dependent values should be defined,
- where `Nat` denotes a natural integer value, `Pos` denotes a
+ where ``Nat`` denotes a natural integer value, ``Pos`` denotes a
positive integer value, and fields marked with a question mark are
boolean fields, where a value of 0 is False, and a value of 1 is True:
name value
- where `name` is the name of the parameter, spelled out in full,
- and cased as in the above list, and `value` is an unsigned decimal
+ where ``name`` is the name of the parameter, spelled out in full,
+ and cased as in the above list, and ``value`` is an unsigned decimal
integer. Two or more blanks separates the name from the value.
All the variables must be present, in alphabetical order (i.e. the
name digs float_rep size alignment
- where `name` is the string name of the type (which can have
- single spaces embedded in the name (e.g. long double), `digs` is
- the number of digits for the floating-point type, `float_rep` is
+ where ``name`` is the string name of the type (which can have
+ single spaces embedded in the name (e.g. long double), ``digs`` is
+ the number of digits for the floating-point type, ``float_rep`` is
the float representation (I/V/A for IEEE-754-Binary, Vax_Native,
- AAMP), `size` is the size in bits, `alignment` is the
+ AAMP), ``size`` is the size in bits, ``alignment`` is the
alignment in bits. The name is followed by at least two blanks, fields
are separated by at least one blank, and a LF character immediately
follows the alignment field.
.. index:: -gnateu (gcc)
-:samp:`-gnateu`
+:switch:`-gnateu`
Ignore unrecognized validity, warning, and style switches that
appear after this switch is given. This may be useful when
compiling sources developed on a later version of the compiler
.. index:: -gnateV (gcc)
-:samp:`-gnateV`
+:switch:`-gnateV`
Check that all actual parameters of a subprogram call are valid according to
the rules of validity checking (:ref:`Validity_Checking`).
.. index:: -gnateY (gcc)
-:samp:`-gnateY`
+:switch:`-gnateY`
Ignore all STYLE_CHECKS pragmas. Full legality checks
are still carried out, but the pragmas have no effect
on what style checks are active. This allows all style
.. index:: -gnatE (gcc)
-:samp:`-gnatE`
+:switch:`-gnatE`
Full dynamic elaboration checks.
.. index:: -gnatf (gcc)
-:samp:`-gnatf`
+:switch:`-gnatf`
Full errors. Multiple errors per line, all undefined references, do not
attempt to suppress cascaded errors.
.. index:: -gnatF (gcc)
-:samp:`-gnatF`
+:switch:`-gnatF`
Externals names are folded to all uppercase.
.. index:: -gnatg (gcc)
-:samp:`-gnatg`
+:switch:`-gnatg`
Internal GNAT implementation mode. This should not be used for
applications programs, it is intended only for use by the compiler
and its run-time library. For documentation, see the GNAT sources.
- Note that *-gnatg* implies
- *-gnatw.ge* and
- *-gnatyg*
+ Note that :switch:`-gnatg` implies
+ :switch:`-gnatw.ge` and
+ :switch:`-gnatyg`
so that all standard warnings and all standard style options are turned on.
All warnings and style messages are treated as errors.
.. index:: -gnatG[nn] (gcc)
-:samp:`-gnatG=nn`
+:switch:`-gnatG=nn`
List generated expanded code in source form.
.. index:: -gnath (gcc)
-:samp:`-gnath`
+:switch:`-gnath`
Output usage information. The output is written to :file:`stdout`.
.. index:: -gnati (gcc)
-:samp:`-gnati{c}`
- Identifier character set (`c` = 1/2/3/4/8/9/p/f/n/w).
- For details of the possible selections for `c`,
+:switch:`-gnati{c}`
+ Identifier character set (``c`` = 1/2/3/4/8/9/p/f/n/w).
+ For details of the possible selections for ``c``,
see :ref:`Character_Set_Control`.
.. index:: -gnatI (gcc)
-:samp:`-gnatI`
+:switch:`-gnatI`
Ignore representation clauses. When this switch is used,
representation clauses are treated as comments. This is useful
when initially porting code where you want to ignore rep clause
are: enumeration_representation_clause, record_representation_clause,
and attribute_definition_clause for the following attributes:
Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
- Object_Size, Size, Small, Stream_Size, and Value_Size.
+ Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
+ and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
Note that this option should be used only for compiling -- the
code is likely to malfunction at run time.
- Note that when `-gnatct` is used to generate trees for input
- into `ASIS` tools, these representation clauses are removed
+ Note that when :switch:`-gnatct` is used to generate trees for input
+ into ASIS tools, these representation clauses are removed
from the tree and ignored. This means that the tool will not see them.
.. index:: -gnatjnn (gcc)
-:samp:`-gnatj{nn}`
- Reformat error messages to fit on `nn` character lines
+:switch:`-gnatj{nn}`
+ Reformat error messages to fit on ``nn`` character lines
.. index:: -gnatk (gcc)
-:samp:`-gnatk={n}`
- Limit file names to `n` (1-999) characters (`k` = krunch).
+:switch:`-gnatk={n}`
+ Limit file names to ``n`` (1-999) characters (``k`` = krunch).
.. index:: -gnatl (gcc)
-:samp:`-gnatl`
+:switch:`-gnatl`
Output full source listing with embedded error messages.
.. index:: -gnatL (gcc)
-:samp:`-gnatL`
+:switch:`-gnatL`
Used in conjunction with -gnatG or -gnatD to intersperse original
source lines (as comment lines with line numbers) in the expanded
source output.
.. index:: -gnatm (gcc)
-:samp:`-gnatm={n}`
- Limit number of detected error or warning messages to `n`
- where `n` is in the range 1..999999. The default setting if
+:switch:`-gnatm={n}`
+ Limit number of detected error or warning messages to ``n``
+ where ``n`` is in the range 1..999999. The default setting if
no switch is given is 9999. If the number of warnings reaches this
limit, then a message is output and further warnings are suppressed,
but the compilation is continued. If the number of error messages
.. index:: -gnatn (gcc)
-:samp:`-gnatn[12]`
- Activate inlining across modules for subprograms for which pragma `Inline`
+:switch:`-gnatn[12]`
+ Activate inlining across modules for subprograms for which pragma ``Inline``
is specified. This inlining is performed by the GCC back-end. An optional
digit sets the inlining level: 1 for moderate inlining across modules
or 2 for full inlining across modules. If no inlining level is specified,
.. index:: -gnatN (gcc)
-:samp:`-gnatN`
+:switch:`-gnatN`
Activate front end inlining for subprograms for which
- pragma `Inline` is specified. This inlining is performed
+ pragma ``Inline`` is specified. This inlining is performed
by the front end and will be visible in the
- *-gnatG* output.
+ :switch:`-gnatG` output.
When using a gcc-based back end (in practice this means using any version
of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
- *-gnatN* is deprecated, and the use of *-gnatn* is preferred.
+ :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
.. index:: -gnato0 (gcc)
-:samp:`-gnato0`
+:switch:`-gnato0`
Suppresses overflow checking. This causes the behavior of the compiler to
match the default for older versions where overflow checking was suppressed
by default. This is equivalent to having
- `pragma Suppress (Overflow_Mode)` in a configuration pragma file.
+ ``pragma Suppress (Overflow_Check)`` in a configuration pragma file.
.. index:: -gnato?? (gcc)
-:samp:`-gnato??`
+:switch:`-gnato??`
Set default mode for handling generation of code to avoid intermediate
- arithmetic overflow. Here `??` is two digits, a
- single digit, or nothing. Each digit is one of the digits `1`
- through `3`:
+ arithmetic overflow. Here ``??`` is two digits, a
+ single digit, or nothing. Each digit is one of the digits ``1``
+ through ``3``:
===== ===============================================================
Digit Interpretation
----- ---------------------------------------------------------------
- *1* All intermediate overflows checked against base type (`STRICT`)
- *2* Minimize intermediate overflows (`MINIMIZED`)
- *3* Eliminate intermediate overflows (`ELIMINATED`)
+ *1* All intermediate overflows checked against base type (``STRICT``)
+ *2* Minimize intermediate overflows (``MINIMIZED``)
+ *3* Eliminate intermediate overflows (``ELIMINATED``)
===== ===============================================================
If only one digit appears, then it applies to all
assertions, pre/postconditions, and type invariants, and the second
applies within assertions, pre/postconditions, and type invariants.
- If no digits follow the *-gnato*, then it is equivalent to
- *-gnato11*,
+ If no digits follow the :switch:`-gnato`, then it is equivalent to
+ :switch:`-gnato11`,
causing all intermediate overflows to be handled in strict
mode.
This switch also causes arithmetic overflow checking to be performed
- (as though `pragma Unsuppress (Overflow_Mode)` had been specified).
+ (as though ``pragma Unsuppress (Overflow_Check)`` had been specified).
- The default if no option *-gnato* is given is that overflow handling
- is in `STRICT` mode (computations done using the base type), and that
+ The default if no option :switch:`-gnato` is given is that overflow handling
+ is in ``STRICT`` mode (computations done using the base type), and that
overflow checking is enabled.
Note that division by zero is a separate check that is not
.. index:: -gnatp (gcc)
-:samp:`-gnatp`
+:switch:`-gnatp`
Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch
- has no effect if cancelled by a subsequent *-gnat-p* switch.
+ has no effect if cancelled by a subsequent :switch:`-gnat-p` switch.
.. index:: -gnat-p (gcc)
-:samp:`-gnat-p`
- Cancel effect of previous *-gnatp* switch.
+:switch:`-gnat-p`
+ Cancel effect of previous :switch:`-gnatp` switch.
.. index:: -gnatP (gcc)
-:samp:`-gnatP`
+:switch:`-gnatP`
Enable polling. This is required on some systems (notably Windows NT) to
obtain asynchronous abort and asynchronous transfer of control capability.
- See `Pragma_Polling` in the :title:`GNAT_Reference_Manual` for full
+ See ``Pragma_Polling`` in the :title:`GNAT_Reference_Manual` for full
details.
.. index:: -gnatq (gcc)
-:samp:`-gnatq`
+:switch:`-gnatq`
Don't quit. Try semantics, even if parse errors.
.. index:: -gnatQ (gcc)
-:samp:`-gnatQ`
+:switch:`-gnatQ`
Don't quit. Generate :file:`ALI` and tree files even if illegalities.
Note that code generation is still suppressed in the presence of any
- errors, so even with *-gnatQ* no object file is generated.
+ errors, so even with :switch:`-gnatQ` no object file is generated.
.. index:: -gnatr (gcc)
-:samp:`-gnatr`
+:switch:`-gnatr`
Treat pragma Restrictions as Restriction_Warnings.
.. index:: -gnatR (gcc)
-:samp:`-gnatR[0/1/2/3[s]]`
- Output representation information for declared types and objects.
- Note that this switch is not allowed if a previous `-gnatD` switch has
- been given, since these two switches are not compatible.
-
-
-:samp:`-gnatRm[s]`
- Output convention and parameter passing mechanisms for all subprograms.
+:switch:`-gnatR[0/1/2/3][e][m][s]`
+ Output representation information for declared types, objects and
+ subprograms. Note that this switch is not allowed if a previous
+ :switch:`-gnatD` switch has been given, since these two switches
+ are not compatible.
.. index:: -gnats (gcc)
-:samp:`-gnats`
+:switch:`-gnats`
Syntax check only.
.. index:: -gnatS (gcc)
-:samp:`-gnatS`
+:switch:`-gnatS`
Print package Standard.
.. index:: -gnatt (gcc)
-:samp:`-gnatt`
+:switch:`-gnatt`
Generate tree output file.
.. index:: -gnatT (gcc)
-:samp:`-gnatT{nnn}`
- All compiler tables start at `nnn` times usual starting size.
+:switch:`-gnatT{nnn}`
+ All compiler tables start at ``nnn`` times usual starting size.
.. index:: -gnatu (gcc)
-:samp:`-gnatu`
+:switch:`-gnatu`
List units for this compilation.
.. index:: -gnatU (gcc)
-:samp:`-gnatU`
+:switch:`-gnatU`
Tag all error messages with the unique string 'error:'
.. index:: -gnatv (gcc)
-:samp:`-gnatv`
+:switch:`-gnatv`
Verbose mode. Full error output with source lines to :file:`stdout`.
.. index:: -gnatV (gcc)
-:samp:`-gnatV`
+:switch:`-gnatV`
Control level of validity checking (:ref:`Validity_Checking`).
.. index:: -gnatw (gcc)
-:samp:`-gnatw{xxx}`
+:switch:`-gnatw{xxx}`
Warning mode where
- `xxx` is a string of option letters that denotes
+ ``xxx`` is a string of option letters that denotes
the exact warnings that
are enabled or disabled (:ref:`Warning_Message_Control`).
.. index:: -gnatW (gcc)
-:samp:`-gnatW{e}`
+:switch:`-gnatW{e}`
Wide character encoding method
- (`e`\ =n/h/u/s/e/8).
+ (``e``\ =n/h/u/s/e/8).
.. index:: -gnatx (gcc)
-:samp:`-gnatx`
+:switch:`-gnatx`
Suppress generation of cross-reference information.
.. index:: -gnatX (gcc)
-:samp:`-gnatX`
+:switch:`-gnatX`
Enable GNAT implementation extensions and latest Ada version.
.. index:: -gnaty (gcc)
-:samp:`-gnaty`
+:switch:`-gnaty`
Enable built-in style checks (:ref:`Style_Checking`).
.. index:: -gnatz (gcc)
-:samp:`-gnatz{m}`
+:switch:`-gnatz{m}`
Distribution stub generation and compilation
- (`m`\ =r/c for receiver/caller stubs).
+ (``m``\ =r/c for receiver/caller stubs).
.. index:: -I (gcc)
-:samp:`-I{dir}`
+:switch:`-I{dir}`
.. index:: RTL
- Direct GNAT to search the `dir` directory for source files needed by
+ Direct GNAT to search the ``dir`` directory for source files needed by
the current compilation
(see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
.. index:: -I- (gcc)
-:samp:`-I-`
+:switch:`-I-`
.. index:: RTL
Except for the source file named in the command line, do not look for source
.. index:: -o (gcc)
-:samp:`-o {file}`
- This switch is used in *gcc* to redirect the generated object file
+:switch:`-o {file}`
+ This switch is used in ``gcc`` to redirect the generated object file
and its associated ALI file. Beware of this switch with GNAT, because it may
cause the object file and ALI file to have different names which in turn
may confuse the binder and the linker.
.. index:: -nostdinc (gcc)
-:samp:`-nostdinc`
+:switch:`-nostdinc`
Inhibit the search of the default location for the GNAT Run Time
Library (RTL) source files.
.. index:: -nostdlib (gcc)
-:samp:`-nostdlib`
+:switch:`-nostdlib`
Inhibit the search of the default location for the GNAT Run Time
Library (RTL) ALI files.
.. index:: -O (gcc)
-:samp:`-O[{n}]`
- `n` controls the optimization level:
+:switch:`-O[{n}]`
+ ``n`` controls the optimization level:
======= ==================================================================
*n* Effect
------- ------------------------------------------------------------------
- *0* No optimization, the default setting if no *-O* appears
- *1* Normal optimization, the default if you specify *-O* without an
+ *0* No optimization, the default setting if no :switch:`-O` appears
+ *1* Normal optimization, the default if you specify :switch:`-O` without an
operand. A good compromise between code quality and compilation
time.
*2* Extensive optimization, may improve execution time, possibly at
the cost of substantially increased compilation time.
- *3* Same as *-O2*, and also includes inline expansion for small
+ *3* Same as :switch:`-O2`, and also includes inline expansion for small
subprograms in the same unit.
*s* Optimize space usage
======= ==================================================================
.. index:: -pass-exit-codes (gcc)
-:samp:`-pass-exit-codes`
+:switch:`-pass-exit-codes`
Catch exit codes from the compiler and use the most meaningful as
exit status.
.. index:: --RTS (gcc)
-:samp:`--RTS={rts-path}`
+:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -S (gcc)
-:samp:`-S`
- Used in place of *-c* to
+:switch:`-S`
+ Used in place of :switch:`-c` to
cause the assembler source file to be
generated, using :file:`.s` as the extension,
instead of the object file.
.. index:: -fverbose-asm (gcc)
-:samp:`-fverbose-asm`
- Used in conjunction with *-S*
+:switch:`-fverbose-asm`
+ Used in conjunction with :switch:`-S`
to cause the generated assembly code file to be annotated with variable
names, making it significantly easier to follow.
.. index:: -v (gcc)
-:samp:`-v`
- Show commands generated by the *gcc* driver. Normally used only for
+:switch:`-v`
+ Show commands generated by the ``gcc`` driver. Normally used only for
debugging purposes or if you need to be sure what version of the
compiler you are executing.
.. index:: -V (gcc)
-:samp:`-V {ver}`
- Execute `ver` version of the compiler. This is the *gcc*
+:switch:`-V {ver}`
+ Execute ``ver`` version of the compiler. This is the ``gcc``
version, not the GNAT version.
.. index:: -w (gcc)
-:samp:`-w`
+:switch:`-w`
Turn off warnings generated by the back end of the compiler. Use of
this switch also causes the default for front end warnings to be set
- to suppress (as though *-gnatws* had appeared at the start of
+ to suppress (as though :switch:`-gnatws` had appeared at the start of
the options).
The following restrictions apply to the combination of switches
in this manner:
-* The switch *-gnatc* if combined with other switches must come
+* The switch :switch:`-gnatc` if combined with other switches must come
first in the string.
-* The switch *-gnats* if combined with other switches must come
+* The switch :switch:`-gnats` if combined with other switches must come
first in the string.
* The switches
- *-gnatzc* and *-gnatzr* may not be combined with any other
+ :switch:`-gnatzc` and :switch:`-gnatzr` may not be combined with any other
switches, and only one of them may appear in the command line.
-* The switch *-gnat-p* may not be combined with any other switch.
+* The switch :switch:`-gnat-p` may not be combined with any other switch.
-* Once a 'y' appears in the string (that is a use of the *-gnaty*
+* Once a 'y' appears in the string (that is a use of the :switch:`-gnaty`
switch), then all further characters in the switch are interpreted
- as style modifiers (see description of *-gnaty*).
+ as style modifiers (see description of :switch:`-gnaty`).
-* Once a 'd' appears in the string (that is a use of the *-gnatd*
+* Once a 'd' appears in the string (that is a use of the :switch:`-gnatd`
switch), then all further characters in the switch are interpreted
- as debug flags (see description of *-gnatd*).
+ as debug flags (see description of :switch:`-gnatd`).
-* Once a 'w' appears in the string (that is a use of the *-gnatw*
+* Once a 'w' appears in the string (that is a use of the :switch:`-gnatw`
switch), then all further characters in the switch are interpreted
- as warning mode modifiers (see description of *-gnatw*).
+ as warning mode modifiers (see description of :switch:`-gnatw`).
-* Once a 'V' appears in the string (that is a use of the *-gnatV*
+* Once a 'V' appears in the string (that is a use of the :switch:`-gnatV`
switch), then all further characters in the switch are interpreted
as validity checking options (:ref:`Validity_Checking`).
The first integer after the file name is the line number in the file,
and the second integer is the column number within the line.
-`GPS` can parse the error messages
+``GPS`` can parse the error messages
and point to the referenced character.
The following switches provide control over the error message
format:
.. index:: -gnatv (gcc)
-:samp:`-gnatv`
- The `v` stands for verbose.
+:switch:`-gnatv`
+ The ``v`` stands for verbose.
The effect of this setting is to write long-format error
messages to :file:`stdout` (the standard output file.
The same program compiled with the
- *-gnatv* switch would generate:
+ :switch:`-gnatv` switch would generate:
::
>>> ";" should be "is"
- The vertical bar indicates the location of the error, and the :samp:`>>>`
+ The vertical bar indicates the location of the error, and the ``>>>``
prefix can be used to search for error messages. When this switch is
used the only source lines output are those with errors.
.. index:: -gnatl (gcc)
-:samp:`-gnatl`
- The `l` stands for list.
+:switch:`-gnatl`
+ The ``l`` stands for list.
This switch causes a full listing of
the file to be generated. In the case where a body is
compiled, the corresponding spec is also listed, along
5. end;
- When you specify the *-gnatv* or *-gnatl* switches and
+ When you specify the :switch:`-gnatv` or :switch:`-gnatl` switches and
standard output is redirected, a brief summary is written to
:file:`stderr` (standard error) giving the number of error messages and
warning messages generated.
.. index:: -gnatl=fname (gcc)
-:samp:`-gnatl={fname}`
- This has the same effect as *-gnatl* except that the output is
+:switch:`-gnatl={fname}`
+ This has the same effect as :switch:`-gnatl` except that the output is
written to a file instead of to standard output. If the given name
:file:`fname` does not start with a period, then it is the full name
of the file to be written. If :file:`fname` is an extension, it is
appended to the name of the file being compiled. For example, if
- file :file:`xyz.adb` is compiled with *-gnatl=.lst*,
+ file :file:`xyz.adb` is compiled with :switch:`-gnatl=.lst`,
then the output is written to file xyz.adb.lst.
.. index:: -gnatU (gcc)
-:samp:`-gnatU`
+:switch:`-gnatU`
This switch forces all error messages to be preceded by the unique
string 'error:'. This means that error messages take a few more
characters in space, but allows easy searching for and identification
.. index:: -gnatb (gcc)
-:samp:`-gnatb`
- The `b` stands for brief.
+:switch:`-gnatb`
+ The ``b`` stands for brief.
This switch causes GNAT to generate the
brief format error messages to :file:`stderr` (the standard error
file) as well as the verbose
.. index:: -gnatm (gcc)
-:samp:`-gnatm={n}`
- The `m` stands for maximum.
- `n` is a decimal integer in the
+:switch:`-gnatm={n}`
+ The ``m`` stands for maximum.
+ ``n`` is a decimal integer in the
range of 1 to 999999 and limits the number of error or warning
messages to be generated. For example, using
- *-gnatm2* might yield
+ :switch:`-gnatm2` might yield
::
is abandoned. A value of zero means that no limit applies.
Note that the equal sign is optional, so the switches
- *-gnatm2* and *-gnatm=2* are equivalent.
+ :switch:`-gnatm2` and :switch:`-gnatm=2` are equivalent.
.. index:: -gnatf (gcc)
-:samp:`-gnatf`
+:switch:`-gnatf`
.. index:: Error messages, suppressing
- The `f` stands for full.
+ The ``f`` stands for full.
Normally, the compiler suppresses error messages that are likely to be
redundant. This switch causes all error
messages to be generated. In particular, in the case of
e.adb:7:07: "V" is undefined (more references follow)
where the parenthetical comment warns that there are additional
- references to the variable `V`. Compiling the same program with the
- *-gnatf* switch yields
+ references to the variable ``V``. Compiling the same program with the
+ :switch:`-gnatf` switch yields
::
e.adb:9:07: "V" is undefined
e.adb:9:12: "V" is undefined
- The *-gnatf* switch also generates additional information for
+ The :switch:`-gnatf` switch also generates additional information for
some error messages. Some examples are:
* Details on possibly non-portable unchecked conversion
.. index:: -gnatjnn (gcc)
-:samp:`-gnatjnn`
- In normal operation mode (or if *-gnatj0* is used), then error messages
+:switch:`-gnatjnn`
+ In normal operation mode (or if :switch:`-gnatj0` is used), then error messages
with continuation lines are treated as though the continuation lines were
separate messages (and so a warning with two continuation lines counts as
three warnings, and is listed as three separate messages).
- If the *-gnatjnn* switch is used with a positive value for nn, then
+ If the :switch:`-gnatjnn` switch is used with a positive value for nn, then
messages are output in a different manner. A message and all its continuation
lines are treated as a unit, and count as only one warning or message in the
statistics totals. Furthermore, the message is reformatted so that no line
.. index:: -gnatq (gcc)
-:samp:`-gnatq`
- The `q` stands for quit (really 'don't quit').
+:switch:`-gnatq`
+ The ``q`` stands for quit (really 'don't quit').
In normal operation mode, the compiler first parses the program and
determines if there are any syntax errors. If there are, appropriate
error messages are generated and compilation is immediately terminated.
.. index:: -gnatQ (gcc)
-:samp:`-gnatQ`
+:switch:`-gnatQ`
In normal operation mode, the :file:`ALI` file is not generated if any
- illegalities are detected in the program. The use of *-gnatQ* forces
+ illegalities are detected in the program. The use of :switch:`-gnatQ` forces
generation of the :file:`ALI` file. This file is marked as being in
error, so it cannot be used for binding purposes, but it does contain
reasonably complete cross-reference information, and thus may be useful
for use by tools (e.g., semantic browsing tools or integrated development
environments) that are driven from the :file:`ALI` file. This switch
- implies *-gnatq*, since the semantic phase must be run to get a
+ implies :switch:`-gnatq`, since the semantic phase must be run to get a
meaningful ALI file.
- In addition, if *-gnatt* is also specified, then the tree file is
+ In addition, if :switch:`-gnatt` is also specified, then the tree file is
generated even if there are illegalities. It may be useful in this case
- to also specify *-gnatq* to ensure that full semantic processing
+ to also specify :switch:`-gnatq` to ensure that full semantic processing
occurs. The resulting tree file can be processed by ASIS, for the purpose
of providing partial information about illegal units, but if the error
causes the tree to be badly malformed, then ASIS may crash during the
analysis.
- When *-gnatQ* is used and the generated :file:`ALI` file is marked as
- being in error, *gnatmake* will attempt to recompile the source when it
- finds such an :file:`ALI` file, including with switch *-gnatc*.
+ When :switch:`-gnatQ` is used and the generated :file:`ALI` file is marked as
+ being in error, ``gnatmake`` will attempt to recompile the source when it
+ finds such an :file:`ALI` file, including with switch :switch:`-gnatc`.
- Note that *-gnatQ* has no effect if *-gnats* is specified,
- since ALI files are never generated if *-gnats* is set.
+ Note that :switch:`-gnatQ` has no effect if :switch:`-gnats` is specified,
+ since ALI files are never generated if :switch:`-gnats` is set.
.. _Warning_Message_Control:
for the generation of warning messages. As always, warnings are not
definite indications of errors. For example, if you do an out-of-range
assignment with the deliberate intention of raising a
-`Constraint_Error` exception, then the warning that may be
+``Constraint_Error`` exception, then the warning that may be
issued does not indicate an error. Some of the situations for which GNAT
issues warnings (at least some of the time) are given in the following
list. This list is not complete, and new warnings are often added to
* Variables that are referenced before being initialized
-* Task entries with no corresponding `accept` statement
+* Task entries with no corresponding ``accept`` statement
-* Duplicate accepts for the same task entry in a `select`
+* Duplicate accepts for the same task entry in a ``select``
* Objects that take too much storage
* Unchecked conversion between types of differing sizes
-* Missing `return` statement along some execution path in a function
+* Missing ``return`` statement along some execution path in a function
* Incorrect (unrecognized) pragmas
* Unused |with| clauses
-* `Bit_Order` usage that does not have any effect
+* ``Bit_Order`` usage that does not have any effect
-* `Standard.Duration` used to resolve universal fixed expression
+* ``Standard.Duration`` used to resolve universal fixed expression
* Dereference of possibly null value
* Unreferenced or unmodified variables. Note that a special
exemption applies to variables which contain any of the substrings
- `DISCARD, DUMMY, IGNORE, JUNK, UNUSED`, in any casing. Such variables
+ ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED``, in any casing. Such variables
are considered likely to be intentionally used in a situation where
otherwise a warning would be given, so warnings of this kind are
always suppressed for such variables.
* Access before elaboration detected at compile time
-* A range in a `for` loop that is known to be null or might be null
+* A range in a ``for`` loop that is known to be null or might be null
The following section lists compiler switches that are available
.. index:: -gnatwa (gcc)
-:samp:`-gnatwa`
+:switch:`-gnatwa`
*Activate most optional warnings.*
This switch activates most optional warning messages. See the remaining list
switch are:
- * :samp:`-gnatwd` (implicit dereferencing)
+ * :switch:`-gnatwd` (implicit dereferencing)
+
+ * :switch:`-gnatw.d` (tag warnings with -gnatw switch)
- * :samp:`-gnatw.d` (tag warnings with -gnatw switch)
+ * :switch:`-gnatwh` (hiding)
- * :samp:`-gnatwh` (hiding)
+ * :switch:`-gnatw.h` (holes in record layouts)
- * :samp:`-gnatw.h` (holes in record layouts)
+ * :switch:`-gnatw.j` (late primitives of tagged types)
- * :samp:`-gnatw.j` (late primitives of tagged types)
+ * :switch:`-gnatw.k` (redefinition of names in standard)
- * :samp:`-gnatw.k` (redefinition of names in standard)
+ * :switch:`-gnatwl` (elaboration warnings)
- * :samp:`-gnatwl` (elaboration warnings)
+ * :switch:`-gnatw.l` (inherited aspects)
- * :samp:`-gnatw.l` (inherited aspects)
+ * :switch:`-gnatw.n` (atomic synchronization)
- * :samp:`-gnatw.n` (atomic synchronization)
+ * :switch:`-gnatwo` (address clause overlay)
- * :samp:`-gnatwo` (address clause overlay)
+ * :switch:`-gnatw.o` (values set by out parameters ignored)
- * :samp:`-gnatw.o` (values set by out parameters ignored)
+ * :switch:`-gnatw.q` (questionable layout of record types)
- * :samp:`-gnatw.s` (overridden size clause)
+ * :switch:`-gnatw.s` (overridden size clause)
- * :samp:`-gnatwt` (tracking of deleted conditional code)
+ * :switch:`-gnatwt` (tracking of deleted conditional code)
- * :samp:`-gnatw.u` (unordered enumeration)
+ * :switch:`-gnatw.u` (unordered enumeration)
- * :samp:`-gnatw.w` (use of Warnings Off)
+ * :switch:`-gnatw.w` (use of Warnings Off)
- * :samp:`-gnatw.y` (reasons for package needing body)
+ * :switch:`-gnatw.y` (reasons for package needing body)
All other optional warnings are turned on.
.. index:: -gnatwA (gcc)
-:samp:`-gnatwA`
+:switch:`-gnatwA`
*Suppress all optional errors.*
This switch suppresses all optional warning messages, see remaining list
in this section for details on optional warning messages that can be
- individually controlled. Note that unlike switch *-gnatws*, the
- use of switch *-gnatwA* does not suppress warnings that are
+ individually controlled. Note that unlike switch :switch:`-gnatws`, the
+ use of switch :switch:`-gnatwA` does not suppress warnings that are
normally given unconditionally and cannot be individually controlled
(for example, the warning about a missing exit path in a function).
- Also, again unlike switch *-gnatws*, warnings suppressed by
- the use of switch *-gnatwA* can be individually turned back
- on. For example the use of switch *-gnatwA* followed by
- switch *-gnatwd* will suppress all optional warnings except
+ Also, again unlike switch :switch:`-gnatws`, warnings suppressed by
+ the use of switch :switch:`-gnatwA` can be individually turned back
+ on. For example the use of switch :switch:`-gnatwA` followed by
+ switch :switch:`-gnatwd` will suppress all optional warnings except
the warnings for implicit dereferencing.
.. index:: -gnatw.a (gcc)
-:samp:`-gnatw.a`
+:switch:`-gnatw.a`
*Activate warnings on failing assertions.*
.. index:: Assert failures
.. index:: -gnatw.A (gcc)
-:samp:`-gnatw.A`
+:switch:`-gnatw.A`
*Suppress warnings on failing assertions.*
.. index:: Assert failures
.. index:: -gnatwb (gcc)
-:samp:`-gnatwb`
+:switch:`-gnatwb`
*Activate warnings on bad fixed values.*
.. index:: Bad fixed values
.. index:: -gnatwB (gcc)
-:samp:`-gnatwB`
+:switch:`-gnatwB`
*Suppress warnings on bad fixed values.*
This switch suppresses warnings for static fixed-point expressions whose
.. index:: -gnatw.b (gcc)
-:samp:`-gnatw.b`
+:switch:`-gnatw.b`
*Activate warnings on biased representation.*
.. index:: Biased representation
.. index:: -gnatwB (gcc)
-:samp:`-gnatw.B`
+:switch:`-gnatw.B`
*Suppress warnings on biased representation.*
This switch suppresses warnings for representation clauses that force the use
.. index:: -gnatwc (gcc)
-:samp:`-gnatwc`
+:switch:`-gnatwc`
*Activate warnings on conditionals.*
.. index:: Conditionals, constant
If the compiler can tell that only the equality condition is possible,
then it will warn that the '>' or '<' part of the test
is useless and that the operator could be replaced by '='.
- An example would be comparing a `Natural` variable <= 0.
+ An example would be comparing a ``Natural`` variable <= 0.
This warning option also generates warnings if
one or both tests is optimized away in a membership test for integer
enumeration types are not included, since it is common for such tests
to include an end point.
- This warning can also be turned on using *-gnatwa*.
+ This warning can also be turned on using :switch:`-gnatwa`.
.. index:: -gnatwC (gcc)
-:samp:`-gnatwC`
+:switch:`-gnatwC`
*Suppress warnings on conditionals.*
This switch suppresses warnings for conditional expressions used in
.. index:: -gnatw.c (gcc)
-:samp:`-gnatw.c`
+:switch:`-gnatw.c`
*Activate warnings on missing component clauses.*
.. index:: Component clause, missing
.. index:: -gnatwC (gcc)
-:samp:`-gnatw.C`
+:switch:`-gnatw.C`
*Suppress warnings on missing component clauses.*
This switch suppresses warnings for record components that are
.. index:: -gnatwd (gcc)
-:samp:`-gnatwd`
+:switch:`-gnatwd`
*Activate warnings on implicit dereferencing.*
If this switch is set, then the use of a prefix of an access type
in an indexed component, slice, or selected component without an
- explicit `.all` will generate a warning. With this warning
+ explicit ``.all`` will generate a warning. With this warning
enabled, access checks occur only at points where an explicit
- `.all` appears in the source code (assuming no warnings are
+ ``.all`` appears in the source code (assuming no warnings are
generated as a result of this switch). The default is that such
warnings are not generated.
.. index:: -gnatwD (gcc)
-:samp:`-gnatwD`
+:switch:`-gnatwD`
*Suppress warnings on implicit dereferencing.*
.. index:: Implicit dereferencing
.. index:: -gnatw.d (gcc)
-:samp:`-gnatw.d`
+:switch:`-gnatw.d`
*Activate tagging of warning and info messages.*
If this switch is set, then warning messages are tagged, with one of the
following strings:
- *[-gnatw?]*
- Used to tag warnings controlled by the switch *-gnatwx* where x
+ Used to tag warnings controlled by the switch :switch:`-gnatwx` where x
is a letter a-z.
- *[-gnatw.?]*
- Used to tag warnings controlled by the switch *-gnatw.x* where x
+ Used to tag warnings controlled by the switch :switch:`-gnatw.x` where x
is a letter a-z.
- *[-gnatel]*
Used to tag elaboration information (info) messages generated when the
- static model of elaboration is used and the *-gnatel* switch is set.
+ static model of elaboration is used and the :switch:`-gnatel` switch is set.
- *[restriction warning]*
Used to tag warning messages for restriction violations, activated by use
- of the pragma *Restriction_Warnings*.
+ of the pragma ``Restriction_Warnings``.
- *[warning-as-error]*
- *[enabled by default]*
Used to tag all other warnings that are always given by default, unless
warnings are completely suppressed using pragma *Warnings(Off)* or
- the switch *-gnatws*.
+ the switch :switch:`-gnatws`.
.. index:: -gnatw.d (gcc)
-:samp:`-gnatw.D`
+:switch:`-gnatw.D`
*Deactivate tagging of warning and info messages messages.*
If this switch is set, then warning messages return to the default
mode in which warnings and info messages are not tagged as described above for
- `-gnatw.d`.
+ :switch:`-gnatw.d`.
.. index:: -gnatwe (gcc)
.. index:: Warnings, treat as error
-:samp:`-gnatwe`
+:switch:`-gnatwe`
*Treat warnings and style checks as errors.*
This switch causes warning messages and style check messages to be
.. index:: -gnatw.e (gcc)
-:samp:`-gnatw.e`
+:switch:`-gnatw.e`
*Activate every optional warning.*
.. index:: Warnings, activate every optional warning
This switch activates all optional warnings, including those which
- are not activated by `-gnatwa`. The use of this switch is not
+ are not activated by :switch:`-gnatwa`. The use of this switch is not
recommended for normal use. If you turn this switch on, it is almost
certain that you will get large numbers of useless warnings. The
- warnings that are excluded from `-gnatwa` are typically highly
+ warnings that are excluded from :switch:`-gnatwa` are typically highly
specialized warnings that are suitable for use only in code that has
been specifically designed according to specialized coding rules.
+.. index:: -gnatwE (gcc)
+.. index:: Warnings, treat as error
+
+:switch:`-gnatwE`
+ *Treat all run-time exception warnings as errors.*
+
+ This switch causes warning messages regarding errors that will be raised
+ during run-time execution to be treated as errors.
+
+
.. index:: -gnatwf (gcc)
-:samp:`-gnatwf`
+:switch:`-gnatwf`
*Activate warnings on unreferenced formals.*
.. index:: Formals, unreferenced
This switch causes a warning to be generated if a formal parameter
is not referenced in the body of the subprogram. This warning can
- also be turned on using *-gnatwu*. The
+ also be turned on using :switch:`-gnatwu`. The
default is that these warnings are not generated.
.. index:: -gnatwF (gcc)
-:samp:`-gnatwF`
+:switch:`-gnatwF`
*Suppress warnings on unreferenced formals.*
This switch suppresses warnings for unreferenced formal
parameters. Note that the
- combination *-gnatwu* followed by *-gnatwF* has the
+ combination :switch:`-gnatwu` followed by :switch:`-gnatwF` has the
effect of warning on unreferenced entities other than subprogram
formals.
.. index:: -gnatwg (gcc)
-:samp:`-gnatwg`
+:switch:`-gnatwg`
*Activate warnings on unrecognized pragmas.*
.. index:: Pragmas, unrecognized
.. index:: -gnatwG (gcc)
-:samp:`-gnatwG`
+:switch:`-gnatwG`
*Suppress warnings on unrecognized pragmas.*
This switch suppresses warnings for unrecognized pragmas.
.. index:: -gnatw.g (gcc)
-:samp:`-gnatw.g`
+:switch:`-gnatw.g`
*Warnings used for GNAT sources.*
This switch sets the warning categories that are used by the standard
GNAT style. Currently this is equivalent to
- *-gnatwAao.sI.C.V.X*
+ :switch:`-gnatwAao.q.s.CI.V.X.Z`
but more warnings may be added in the future without advanced notice.
.. index:: -gnatwh (gcc)
-:samp:`-gnatwh`
+:switch:`-gnatwh`
*Activate warnings on hiding.*
.. index:: Hiding of Declarations
.. index:: -gnatwH (gcc)
-:samp:`-gnatwH`
+:switch:`-gnatwH`
*Suppress warnings on hiding.*
This switch suppresses warnings on hiding declarations.
.. index:: -gnatw.h (gcc)
-:samp:`-gnatw.h`
+:switch:`-gnatw.h`
*Activate warnings on holes/gaps in records.*
.. index:: Record Representation (gaps)
.. index:: -gnatw.H (gcc)
-:samp:`-gnatw.H`
+:switch:`-gnatw.H`
*Suppress warnings on holes/gaps in records.*
This switch suppresses warnings on component clauses in record
.. index:: -gnatwi (gcc)
-:samp:`-gnatwi`
+:switch:`-gnatwi`
*Activate warnings on implementation units.*
This switch activates warnings for a |with| of an internal GNAT
- implementation unit, defined as any unit from the `Ada`,
- `Interfaces`, `GNAT`,
- or `System`
+ implementation unit, defined as any unit from the ``Ada``,
+ ``Interfaces``, ``GNAT``,
+ or ``System``
hierarchies that is not
documented in either the Ada Reference Manual or the GNAT
Programmer's Reference Manual. Such units are intended only
.. index:: -gnatwI (gcc)
-:samp:`-gnatwI`
+:switch:`-gnatwI`
*Disable warnings on implementation units.*
This switch disables warnings for a |with| of an internal GNAT
.. index:: -gnatw.i (gcc)
-:samp:`-gnatw.i`
+:switch:`-gnatw.i`
*Activate warnings on overlapping actuals.*
This switch enables a warning on statically detectable overlapping actuals in
.. index:: -gnatw.I (gcc)
-:samp:`-gnatw.I`
+:switch:`-gnatw.I`
*Disable warnings on overlapping actuals.*
This switch disables warnings on overlapping actuals in a call..
.. index:: -gnatwj (gcc)
-:samp:`-gnatwj`
+:switch:`-gnatwj`
*Activate warnings on obsolescent features (Annex J).*
.. index:: Features, obsolescent
.. index:: Obsolescent features
If this warning option is activated, then warnings are generated for
- calls to subprograms marked with `pragma Obsolescent` and
+ calls to subprograms marked with ``pragma Obsolescent`` and
for use of features in Annex J of the Ada Reference Manual. In the
case of Annex J, not all features are flagged. In particular use
- of the renamed packages (like `Text_IO`) and use of package
- `ASCII` are not flagged, since these are very common and
+ of the renamed packages (like ``Text_IO``) and use of package
+ ``ASCII`` are not flagged, since these are very common and
would generate many annoying positive warnings. The default is that
such warnings are not generated.
In addition to the above cases, warnings are also generated for
GNAT features that have been provided in past versions but which
have been superseded (typically by features in the new Ada standard).
- For example, `pragma Ravenscar` will be flagged since its
- function is replaced by `pragma Profile(Ravenscar)`, and
- `pragma Interface_Name` will be flagged since its function
- is replaced by `pragma Import`.
+ For example, ``pragma Ravenscar`` will be flagged since its
+ function is replaced by ``pragma Profile(Ravenscar)``, and
+ ``pragma Interface_Name`` will be flagged since its function
+ is replaced by ``pragma Import``.
Note that this warning option functions differently from the
- restriction `No_Obsolescent_Features` in two respects.
+ restriction ``No_Obsolescent_Features`` in two respects.
First, the restriction applies only to annex J features.
- Second, the restriction does flag uses of package `ASCII`.
+ Second, the restriction does flag uses of package ``ASCII``.
.. index:: -gnatwJ (gcc)
-:samp:`-gnatwJ`
+:switch:`-gnatwJ`
*Suppress warnings on obsolescent features (Annex J).*
This switch disables warnings on use of obsolescent features.
.. index:: -gnatw.j (gcc)
-:samp:`-gnatw.j`
+:switch:`-gnatw.j`
*Activate warnings on late declarations of tagged type primitives.*
This switch activates warnings on visible primitives added to a
.. index:: -gnatw.J (gcc)
-:samp:`-gnatw.J`
+:switch:`-gnatw.J`
*Suppress warnings on late declarations of tagged type primitives.*
This switch suppresses warnings on visible primitives added to a
.. index:: -gnatwk (gcc)
-:samp:`-gnatwk`
+:switch:`-gnatwk`
*Activate warnings on variables that could be constants.*
This switch activates warnings for variables that are initialized but
.. index:: -gnatwK (gcc)
-:samp:`-gnatwK`
+:switch:`-gnatwK`
*Suppress warnings on variables that could be constants.*
This switch disables warnings on variables that could be declared constants.
.. index:: -gnatw.k (gcc)
-:samp:`-gnatw.k`
+:switch:`-gnatw.k`
*Activate warnings on redefinition of names in standard.*
This switch activates warnings for declarations that declare a name that
.. index:: -gnatwK (gcc)
-:samp:`-gnatw.K`
+:switch:`-gnatw.K`
*Suppress warnings on redefinition of names in standard.*
This switch activates warnings for declarations that declare a name that
.. index:: -gnatwl (gcc)
-:samp:`-gnatwl`
+:switch:`-gnatwl`
*Activate warnings for elaboration pragmas.*
.. index:: Elaboration, warnings
This switch activates warnings for possible elaboration problems,
including suspicious use
- of `Elaborate` pragmas, when using the static elaboration model, and
- possible situations that may raise `Program_Error` when using the
+ of ``Elaborate`` pragmas, when using the static elaboration model, and
+ possible situations that may raise ``Program_Error`` when using the
dynamic elaboration model.
See the section in this guide on elaboration checking for further details.
The default is that such warnings
.. index:: -gnatwL (gcc)
-:samp:`-gnatwL`
+:switch:`-gnatwL`
*Suppress warnings for elaboration pragmas.*
This switch suppresses warnings for possible elaboration problems.
.. index:: -gnatw.l (gcc)
-:samp:`-gnatw.l`
+:switch:`-gnatw.l`
*List inherited aspects.*
This switch causes the compiler to list inherited invariants,
.. index:: -gnatw.L (gcc)
-:samp:`-gnatw.L`
+:switch:`-gnatw.L`
*Suppress listing of inherited aspects.*
This switch suppresses listing of inherited aspects.
.. index:: -gnatwm (gcc)
-:samp:`-gnatwm`
+:switch:`-gnatwm`
*Activate warnings on modified but unreferenced variables.*
This switch activates warnings for variables that are assigned (using
.. index:: -gnatwM (gcc)
-:samp:`-gnatwM`
+:switch:`-gnatwM`
*Disable warnings on modified but unreferenced variables.*
This switch disables warnings for variables that are assigned or
.. index:: -gnatw.m (gcc)
-:samp:`-gnatw.m`
+:switch:`-gnatw.m`
*Activate warnings on suspicious modulus values.*
This switch activates warnings for modulus values that seem suspicious.
.. index:: -gnatw.M (gcc)
-:samp:`-gnatw.M`
+:switch:`-gnatw.M`
*Disable warnings on suspicious modulus values.*
This switch disables warnings for suspicious modulus values.
.. index:: -gnatwn (gcc)
-:samp:`-gnatwn`
+:switch:`-gnatwn`
*Set normal warnings mode.*
This switch sets normal warning mode, in which enabled warnings are
issued and treated as warnings rather than errors. This is the default
- mode. the switch *-gnatwn* can be used to cancel the effect of
- an explicit *-gnatws* or
- *-gnatwe*. It also cancels the effect of the
- implicit *-gnatwe* that is activated by the
- use of *-gnatg*.
+ mode. the switch :switch:`-gnatwn` can be used to cancel the effect of
+ an explicit :switch:`-gnatws` or
+ :switch:`-gnatwe`. It also cancels the effect of the
+ implicit :switch:`-gnatwe` that is activated by the
+ use of :switch:`-gnatg`.
.. index:: -gnatw.n (gcc)
.. index:: Atomic Synchronization, warnings
-:samp:`-gnatw.n`
+:switch:`-gnatw.n`
*Activate warnings on atomic synchronization.*
This switch actives warnings when an access to an atomic variable
.. index:: -gnatw.N (gcc)
-:samp:`-gnatw.N`
+:switch:`-gnatw.N`
*Suppress warnings on atomic synchronization.*
.. index:: Atomic Synchronization, warnings
.. index:: -gnatwo (gcc)
.. index:: Address Clauses, warnings
-:samp:`-gnatwo`
+:switch:`-gnatwo`
*Activate warnings on address clause overlays.*
This switch activates warnings for possibly unintended initialization
.. index:: -gnatwO (gcc)
-:samp:`-gnatwO`
+:switch:`-gnatwO`
*Suppress warnings on address clause overlays.*
This switch suppresses warnings on possibly unintended initialization
.. index:: -gnatw.o (gcc)
-:samp:`-gnatw.o`
+:switch:`-gnatw.o`
*Activate warnings on modified but unreferenced out parameters.*
This switch activates warnings for variables that are modified by using
.. index:: -gnatw.O (gcc)
-:samp:`-gnatw.O`
+:switch:`-gnatw.O`
*Disable warnings on modified but unreferenced out parameters.*
This switch suppresses warnings for variables that are modified by using
.. index:: -gnatwp (gcc)
.. index:: Inlining, warnings
-:samp:`-gnatwp`
+:switch:`-gnatwp`
*Activate warnings on ineffective pragma Inlines.*
This switch activates warnings for failure of front end inlining
- (activated by *-gnatN*) to inline a particular call. There are
+ (activated by :switch:`-gnatN`) to inline a particular call. There are
many reasons for not being able to inline a call, including most
commonly that the call is too complex to inline. The default is
that such warnings are not given.
.. index:: -gnatwP (gcc)
-:samp:`-gnatwP`
+:switch:`-gnatwP`
*Suppress warnings on ineffective pragma Inlines.*
This switch suppresses warnings on ineffective pragma Inlines. If the
.. index:: -gnatw.p (gcc)
.. index:: Parameter order, warnings
-:samp:`-gnatw.p`
+:switch:`-gnatw.p`
*Activate warnings on parameter ordering.*
This switch activates warnings for cases of suspicious parameter
.. index:: -gnatw.P (gcc)
-:samp:`-gnatw.P`
+:switch:`-gnatw.P`
*Suppress warnings on parameter ordering.*
This switch suppresses warnings on cases of suspicious parameter
.. index:: -gnatwq (gcc)
.. index:: Parentheses, warnings
-:samp:`-gnatwq`
+:switch:`-gnatwq`
*Activate warnings on questionable missing parentheses.*
This switch activates warnings for cases where parentheses are not used and
.. index:: -gnatwQ (gcc)
-:samp:`-gnatwQ`
+:switch:`-gnatwQ`
*Suppress warnings on questionable missing parentheses.*
This switch suppresses warnings for cases where the association is not
clear and the use of parentheses is preferred.
+.. index:: -gnatw.q (gcc)
+.. index:: Layout, warnings
+
+:switch:`-gnatw.q`
+ *Activate warnings on questionable layout of record types.*
+
+ This switch activates warnings for cases where the default layout of
+ a record type, that is to say the layout of its components in textual
+ order of the source code, would very likely cause inefficiencies in
+ the code generated by the compiler, both in terms of space and speed
+ during execution. One warning is issued for each problematic component
+ without representation clause in the nonvariant part and then in each
+ variant recursively, if any.
+
+ The purpose of these warnings is neither to prescribe an optimal layout
+ nor to force the use of representation clauses, but rather to get rid of
+ the most blatant inefficiencies in the layout. Therefore, the default
+ layout is matched against the following synthetic ordered layout and
+ the deviations are flagged on a component-by-component basis:
+
+ * first all components or groups of components whose length is fixed
+ and a multiple of the storage unit,
+
+ * then the remaining components whose length is fixed and not a multiple
+ of the storage unit,
+
+ * then the remaining components whose length doesn't depend on discriminants
+ (that is to say, with variable but uniform length for all objects),
+
+ * then all components whose length depends on discriminants,
+
+ * finally the variant part (if any),
+
+ for the nonvariant part and for each variant recursively, if any.
+
+ The exact wording of the warning depends on whether the compiler is allowed
+ to reorder the components in the record type or precluded from doing it by
+ means of pragma ``No_Component_Reordering``.
+
+ The default is that these warnings are not given.
+
+.. index:: -gnatw.Q (gcc)
+
+:switch:`-gnatw.Q`
+ *Suppress warnings on questionable layout of record types.*
+
+ This switch suppresses warnings for cases where the default layout of
+ a record type would very likely cause inefficiencies.
+
+
.. index:: -gnatwr (gcc)
-:samp:`-gnatwr`
+:switch:`-gnatwr`
*Activate warnings on redundant constructs.*
This switch activates warnings for redundant constructs. The following
* Type conversion that converts an expression to its own type.
- * Use of the attribute `Base` where `typ'Base` is the same
- as `typ`.
+ * Use of the attribute ``Base`` where ``typ'Base`` is the same
+ as ``typ``.
- * Use of pragma `Pack` when all components are placed by a record
+ * Use of pragma ``Pack`` when all components are placed by a record
representation clause.
* Exception handler containing only a reraise statement (raise with no
* Use of the operator abs on an operand that is known at compile time
to be non-negative
- * Comparison of boolean expressions to an explicit True value.
+ * Comparison of an object or (unary or binary) operation of boolean type to
+ an explicit True value.
The default is that warnings for redundant constructs are not given.
.. index:: -gnatwR (gcc)
-:samp:`-gnatwR`
+:switch:`-gnatwR`
*Suppress warnings on redundant constructs.*
This switch suppresses warnings for redundant constructs.
.. index:: -gnatw.r (gcc)
-:samp:`-gnatw.r`
+:switch:`-gnatw.r`
*Activate warnings for object renaming function.*
This switch activates warnings for an object renaming that renames a
.. index:: -gnatwT (gcc)
-:samp:`-gnatw.R`
+:switch:`-gnatw.R`
*Suppress warnings for object renaming function.*
This switch suppresses warnings for object renaming function.
.. index:: -gnatws (gcc)
-:samp:`-gnatws`
+:switch:`-gnatws`
*Suppress all warnings.*
This switch completely suppresses the
both warnings that can be controlled by switches described in this
section, and those that are normally given unconditionally. The
effect of this suppress action can only be cancelled by a subsequent
- use of the switch *-gnatwn*.
+ use of the switch :switch:`-gnatwn`.
- Note that switch *-gnatws* does not suppress
- warnings from the *gcc* back end.
- To suppress these back end warnings as well, use the switch *-w*
- in addition to *-gnatws*. Also this switch has no effect on the
+ Note that switch :switch:`-gnatws` does not suppress
+ warnings from the ``gcc`` back end.
+ To suppress these back end warnings as well, use the switch :switch:`-w`
+ in addition to :switch:`-gnatws`. Also this switch has no effect on the
handling of style check messages.
.. index:: -gnatw.s (gcc)
.. index:: Record Representation (component sizes)
-:samp:`-gnatw.s`
+:switch:`-gnatw.s`
*Activate warnings on overridden size clauses.*
This switch activates warnings on component clauses in record
.. index:: -gnatw.S (gcc)
-:samp:`-gnatw.S`
+:switch:`-gnatw.S`
*Suppress warnings on overridden size clauses.*
This switch suppresses warnings on component clauses in record
.. index:: Deactivated code, warnings
.. index:: Deleted code, warnings
-:samp:`-gnatwt`
+:switch:`-gnatwt`
*Activate warnings for tracking of deleted conditional code.*
This switch activates warnings for tracking of code in conditionals (IF and
.. index:: -gnatwT (gcc)
-:samp:`-gnatwT`
+:switch:`-gnatwT`
*Suppress warnings for tracking of deleted conditional code.*
This switch suppresses warnings for tracking of deleted conditional code.
.. index:: -gnatw.t (gcc)
-:samp:`-gnatw.t`
+:switch:`-gnatw.t`
*Activate warnings on suspicious contracts.*
This switch activates warnings on suspicious contracts. This includes
- warnings on suspicious postconditions (whether a pragma `Postcondition` or a
- `Post` aspect in Ada 2012) and suspicious contract cases (pragma or aspect
- `Contract_Cases`). A function postcondition or contract case is suspicious
+ warnings on suspicious postconditions (whether a pragma ``Postcondition`` or a
+ ``Post`` aspect in Ada 2012) and suspicious contract cases (pragma or aspect
+ ``Contract_Cases``). A function postcondition or contract case is suspicious
when no postcondition or contract case for this function mentions the result
of the function. A procedure postcondition or contract case is suspicious
when it only refers to the pre-state of the procedure, because in that case
.. index:: -gnatw.T (gcc)
-:samp:`-gnatw.T`
+:switch:`-gnatw.T`
*Suppress warnings on suspicious contracts.*
This switch suppresses warnings on suspicious contracts.
.. index:: -gnatwu (gcc)
-:samp:`-gnatwu`
+:switch:`-gnatwu`
*Activate warnings on unused entities.*
This switch activates warnings to be generated for entities that
and not
referenced. In the case of packages, a warning is also generated if
no entities in the package are referenced. This means that if a with'ed
- package is referenced but the only references are in `use`
- clauses or `renames`
+ package is referenced but the only references are in ``use``
+ clauses or ``renames``
declarations, a warning is still generated. A warning is also generated
for a generic package that is |withed| but never instantiated.
In the case where a package or subprogram body is compiled, and there
|with| can be moved to the body. The default is that
such warnings are not generated.
This switch also activates warnings on unreferenced formals
- (it includes the effect of *-gnatwf*).
+ (it includes the effect of :switch:`-gnatwf`).
.. index:: -gnatwU (gcc)
-:samp:`-gnatwU`
+:switch:`-gnatwU`
*Suppress warnings on unused entities.*
This switch suppresses warnings for unused entities and packages.
It also turns off warnings on unreferenced formals (and thus includes
- the effect of *-gnatwF*).
+ the effect of :switch:`-gnatwF`).
.. index:: -gnatw.u (gcc)
-:samp:`-gnatw.u`
+:switch:`-gnatw.u`
*Activate warnings on unordered enumeration types.*
This switch causes enumeration types to be considered as conceptually
- unordered, unless an explicit pragma `Ordered` is given for the type.
+ unordered, unless an explicit pragma ``Ordered`` is given for the type.
The effect is to generate warnings in clients that use explicit comparisons
or subranges, since these constructs both treat objects of the type as
ordered. (A *client* is defined as a unit that is other than the unit in
which the type is declared, or its body or subunits.) Please refer to
- the description of pragma `Ordered` in the
+ the description of pragma ``Ordered`` in the
:title:`GNAT Reference Manual` for further details.
The default is that such warnings are not generated.
.. index:: -gnatw.U (gcc)
-:samp:`-gnatw.U`
+:switch:`-gnatw.U`
*Deactivate warnings on unordered enumeration types.*
This switch causes all enumeration types to be considered as ordered, so
.. index:: -gnatwv (gcc)
.. index:: Unassigned variable warnings
-:samp:`-gnatwv`
+:switch:`-gnatwv`
*Activate warnings on unassigned variables.*
This switch activates warnings for access to variables which
.. index:: -gnatwV (gcc)
-:samp:`-gnatwV`
+:switch:`-gnatwV`
*Suppress warnings on unassigned variables.*
This switch suppresses warnings for access to variables which
.. index:: -gnatw.v (gcc)
.. index:: bit order warnings
-:samp:`-gnatw.v`
+:switch:`-gnatw.v`
*Activate info messages for non-default bit order.*
This switch activates messages (labeled "info", they are not warnings,
.. index:: -gnatw.V (gcc)
-:samp:`-gnatw.V`
+:switch:`-gnatw.V`
*Suppress info messages for non-default bit order.*
This switch suppresses information messages for the effects of specifying
.. index:: -gnatww (gcc)
.. index:: String indexing warnings
-:samp:`-gnatww`
+:switch:`-gnatww`
*Activate warnings on wrong low bound assumption.*
This switch activates warnings for indexing an unconstrained string parameter
.. index:: -gnatwW (gcc)
-:samp:`-gnatwW`
+:switch:`-gnatwW`
*Suppress warnings on wrong low bound assumption.*
This switch suppresses warnings for indexing an unconstrained string parameter
.. index:: -gnatw.w (gcc)
.. index:: Warnings Off control
-:samp:`-gnatw.w`
+:switch:`-gnatw.w`
*Activate warnings on Warnings Off pragmas.*
- This switch activates warnings for use of `pragma Warnings (Off, entity)`
+ This switch activates warnings for use of ``pragma Warnings (Off, entity)``
where either the pragma is entirely useless (because it suppresses no
- warnings), or it could be replaced by `pragma Unreferenced` or
- `pragma Unmodified`.
+ warnings), or it could be replaced by ``pragma Unreferenced`` or
+ ``pragma Unmodified``.
Also activates warnings for the case of
Warnings (Off, String), where either there is no matching
Warnings (On, String), or the Warnings (Off) did not suppress any warning.
.. index:: -gnatw.W (gcc)
-:samp:`-gnatw.W`
+:switch:`-gnatw.W`
*Suppress warnings on unnecessary Warnings Off pragmas.*
- This switch suppresses warnings for use of `pragma Warnings (Off, ...)`.
+ This switch suppresses warnings for use of ``pragma Warnings (Off, ...)``.
.. index:: -gnatwx (gcc)
.. index:: Export/Import pragma warnings
-:samp:`-gnatwx`
+:switch:`-gnatwx`
*Activate warnings on Export/Import pragmas.*
This switch activates warnings on Export/Import pragmas when
.. index:: -gnatwX (gcc)
-:samp:`-gnatwX`
+:switch:`-gnatwX`
*Suppress warnings on Export/Import pragmas.*
This switch suppresses warnings on Export/Import pragmas.
.. index:: -gnatwm (gcc)
-:samp:`-gnatw.x`
+:switch:`-gnatw.x`
*Activate warnings for No_Exception_Propagation mode.*
This switch activates warnings for exception usage when pragma Restrictions
warnings are not given.
-:samp:`-gnatw.X`
+:switch:`-gnatw.X`
*Disable warnings for No_Exception_Propagation mode.*
This switch disables warnings for exception usage when pragma Restrictions
.. index:: -gnatwy (gcc)
.. index:: Ada compatibility issues warnings
-:samp:`-gnatwy`
+:switch:`-gnatwy`
*Activate warnings for Ada compatibility issues.*
For the most part, newer versions of Ada are upwards compatible
with older versions. For example, Ada 2005 programs will almost
always work when compiled as Ada 2012.
However there are some exceptions (for example the fact that
- `some` is now a reserved word in Ada 2012). This
+ ``some`` is now a reserved word in Ada 2012). This
switch activates several warnings to help in identifying
and correcting such incompatibilities. The default is that
these warnings are generated. Note that at one point Ada 2005
.. index:: -gnatwY (gcc)
.. index:: Ada compatibility issues warnings
-:samp:`-gnatwY`
+:switch:`-gnatwY`
*Disable warnings for Ada compatibility issues.*
This switch suppresses the warnings intended to help in identifying
.. index:: -gnatw.y (gcc)
.. index:: Package spec needing body
-:samp:`-gnatw.y`
+:switch:`-gnatw.y`
*Activate information messages for why package spec needs body.*
There are a number of cases in which a package spec needs a body.
.. index:: -gnatw.Y (gcc)
.. index:: No information messages for why package spec needs body
-:samp:`-gnatw.Y`
+:switch:`-gnatw.Y`
*Disable information messages for why package spec needs body.*
This switch suppresses the output of information messages showing why
.. index:: -gnatwz (gcc)
.. index:: Unchecked_Conversion warnings
-:samp:`-gnatwz`
+:switch:`-gnatwz`
*Activate warnings on unchecked conversions.*
This switch activates warnings for unchecked conversions
.. index:: -gnatwZ (gcc)
-:samp:`-gnatwZ`
+:switch:`-gnatwZ`
*Suppress warnings on unchecked conversions.*
This switch suppresses warnings for unchecked conversions
.. index:: -gnatw.z (gcc)
.. index:: Size/Alignment warnings
-:samp:`-gnatw.z`
+:switch:`-gnatw.z`
*Activate warnings for size not a multiple of alignment.*
This switch activates warnings for cases of record types with
- specified `Size` and `Alignment` attributes where the
+ specified ``Size`` and ``Alignment`` attributes where the
size is not a multiple of the alignment, resulting in an object
size that is greater than the specified size. The default
is that such warnings are generated.
.. index:: -gnatw.Z (gcc)
.. index:: Size/Alignment warnings
-:samp:`-gnatw.Z`
+:switch:`-gnatw.Z`
*Suppress warnings for size not a multiple of alignment.*
This switch suppresses warnings for cases of record types with
- specified `Size` and `Alignment` attributes where the
+ specified ``Size`` and ``Alignment`` attributes where the
size is not a multiple of the alignment, resulting in an object
size that is greater than the specified size.
The warning can also be
- suppressed by giving an explicit `Object_Size` value.
+ suppressed by giving an explicit ``Object_Size`` value.
.. index:: -Wunused (gcc)
-:samp:`-Wunused`
- The warnings controlled by the *-gnatw* switch are generated by
- the front end of the compiler. The *GCC* back end can provide
- additional warnings and they are controlled by the *-W* switch.
- For example, *-Wunused* activates back end
+:switch:`-Wunused`
+ The warnings controlled by the :switch:`-gnatw` switch are generated by
+ the front end of the compiler. The GCC back end can provide
+ additional warnings and they are controlled by the :switch:`-W` switch.
+ For example, :switch:`-Wunused` activates back end
warnings for entities that are declared but not referenced.
.. index:: -Wuninitialized (gcc)
-:samp:`-Wuninitialized`
- Similarly, *-Wuninitialized* activates
+:switch:`-Wuninitialized`
+ Similarly, :switch:`-Wuninitialized` activates
the back end warning for uninitialized variables. This switch must be
used in conjunction with an optimization level greater than zero.
.. index:: -Wstack-usage (gcc)
-:samp:`-Wstack-usage={len}`
- Warn if the stack usage of a subprogram might be larger than `len` bytes.
+:switch:`-Wstack-usage={len}`
+ Warn if the stack usage of a subprogram might be larger than ``len`` bytes.
See :ref:`Static_Stack_Usage_Analysis` for details.
.. index:: -Wall (gcc)
-:samp:`-Wall`
- This switch enables most warnings from the *GCC* back end.
+:switch:`-Wall`
+ This switch enables most warnings from the GCC back end.
The code generator detects a number of warning situations that are missed
- by the *GNAT* front end, and this switch can be used to activate them.
+ by the GNAT front end, and this switch can be used to activate them.
The use of this switch also sets the default front end warning mode to
- *-gnatwa*, that is, most front end warnings activated as well.
+ :switch:`-gnatwa`, that is, most front end warnings activated as well.
.. index:: -w (gcc)
-:samp:`-w`
- Conversely, this switch suppresses warnings from the *GCC* back end.
+:switch:`-w`
+ Conversely, this switch suppresses warnings from the GCC back end.
The use of this switch also sets the default front end warning mode to
- *-gnatws*, that is, front end warnings suppressed as well.
+ :switch:`-gnatws`, that is, front end warnings suppressed as well.
.. index:: -Werror (gcc)
-:samp:`-Werror`
- This switch causes warnings from the *GCC* back end to be treated as
+:switch:`-Werror`
+ This switch causes warnings from the GCC back end to be treated as
errors. The warning string still appears, but the warning messages are
counted as errors, and prevent the generation of an object file.
will turn on all optional warnings except for unrecognized pragma warnings,
and also specify that warnings should be treated as errors.
-When no switch *-gnatw* is used, this is equivalent to:
+When no switch :switch:`-gnatw` is used, this is equivalent to:
+
+ * :switch:`-gnatw.a`
- * :samp:`-gnatw.a`
+ * :switch:`-gnatwB`
- * :samp:`-gnatwB`
+ * :switch:`-gnatw.b`
- * :samp:`-gnatw.b`
+ * :switch:`-gnatwC`
- * :samp:`-gnatwC`
+ * :switch:`-gnatw.C`
- * :samp:`-gnatw.C`
+ * :switch:`-gnatwD`
- * :samp:`-gnatwD`
+ * :switch:`-gnatwF`
- * :samp:`-gnatwF`
+ * :switch:`-gnatwg`
- * :samp:`-gnatwg`
+ * :switch:`-gnatwH`
- * :samp:`-gnatwH`
+ * :switch:`-gnatwi`
- * :samp:`-gnatwi`
+ * :switch:`-gnatw.I`
- * :samp:`-gnatw.I`
+ * :switch:`-gnatwJ`
- * :samp:`-gnatwJ`
+ * :switch:`-gnatwK`
- * :samp:`-gnatwK`
+ * :switch:`-gnatwL`
- * :samp:`-gnatwL`
+ * :switch:`-gnatw.L`
- * :samp:`-gnatw.L`
+ * :switch:`-gnatwM`
- * :samp:`-gnatwM`
+ * :switch:`-gnatw.m`
- * :samp:`-gnatw.m`
+ * :switch:`-gnatwn`
- * :samp:`-gnatwn`
+ * :switch:`-gnatwo`
- * :samp:`-gnatwo`
+ * :switch:`-gnatw.O`
- * :samp:`-gnatw.O`
+ * :switch:`-gnatwP`
- * :samp:`-gnatwP`
+ * :switch:`-gnatw.P`
- * :samp:`-gnatw.P`
+ * :switch:`-gnatwq`
- * :samp:`-gnatwq`
+ * :switch:`-gnatw.Q`
- * :samp:`-gnatwR`
+ * :switch:`-gnatwR`
- * :samp:`-gnatw.R`
+ * :switch:`-gnatw.R`
- * :samp:`-gnatw.S`
+ * :switch:`-gnatw.S`
- * :samp:`-gnatwT`
+ * :switch:`-gnatwT`
- * :samp:`-gnatw.T`
+ * :switch:`-gnatw.T`
- * :samp:`-gnatwU`
+ * :switch:`-gnatwU`
- * :samp:`-gnatwv`
+ * :switch:`-gnatwv`
- * :samp:`-gnatww`
+ * :switch:`-gnatww`
- * :samp:`-gnatw.W`
+ * :switch:`-gnatw.W`
- * :samp:`-gnatwx`
+ * :switch:`-gnatwx`
- * :samp:`-gnatw.X`
+ * :switch:`-gnatw.X`
- * :samp:`-gnatwy`
+ * :switch:`-gnatwy`
- * :samp:`-gnatwz`
+ * :switch:`-gnatwz`
.. _Debugging_and_Assertion_Control:
.. index:: -gnata (gcc)
-:samp:`-gnata`
+:switch:`-gnata`
.. index:: Assert
.. index:: Debug
.. index:: Assertions
.. index:: Type invariants
.. index:: Subtype predicates
- The `-gnata` option is equivalent to the following Assertion_Policy pragma::
+ The :switch:`-gnata` option is equivalent to the following ``Assertion_Policy`` pragma::
pragma Assertion_Policy (Check);
Type_Invariant => Check,
Type_Invariant'Class => Check);
- The pragmas `Assert` and `Debug` normally have no effect and
- are ignored. This switch, where :samp:`a` stands for assert, causes
- pragmas `Assert` and `Debug` to be activated. This switch also
+ The pragmas ``Assert`` and ``Debug`` normally have no effect and
+ are ignored. This switch, where ``a`` stands for 'assert', causes
+ pragmas ``Assert`` and ``Debug`` to be activated. This switch also
causes preconditions, postconditions, subtype predicates, and
type invariants to be activated.
with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
=> <Boolean-expression>;
- The `Assert` pragma causes `Boolean-expression` to be tested.
- If the result is `True`, the pragma has no effect (other than
+ The ``Assert`` pragma causes ``Boolean-expression`` to be tested.
+ If the result is ``True``, the pragma has no effect (other than
possible side effects from evaluating the expression). If the result is
- `False`, the exception `Assert_Failure` declared in the package
- `System.Assertions` is raised (passing `static-string-expression`, if
+ ``False``, the exception ``Assert_Failure`` declared in the package
+ ``System.Assertions`` is raised (passing ``static-string-expression``, if
present, as the message associated with the exception). If no string
expression is given, the default is a string containing the file name and
line number of the pragma.
- The `Debug` pragma causes `procedure` to be called. Note that
- `pragma Debug` may appear within a declaration sequence, allowing
+ The ``Debug`` pragma causes ``procedure`` to be called. Note that
+ ``pragma Debug`` may appear within a declaration sequence, allowing
debugging procedures to be called between declarations.
- For the aspect specification, the `<Boolean-expression>` is evaluated.
- If the result is `True`, the aspect has no effect. If the result
- is `False`, the exception `Assert_Failure` is raised.
+ For the aspect specification, the ``Boolean-expression`` is evaluated.
+ If the result is ``True``, the aspect has no effect. If the result
+ is ``False``, the exception ``Assert_Failure`` is raised.
.. _Validity_Checking:
It is an error to read an invalid value, but the RM does not require
run-time checks to detect such errors, except for some minimal
checking to prevent erroneous execution (i.e. unpredictable
-behavior). This corresponds to the *-gnatVd* switch below,
+behavior). This corresponds to the :switch:`-gnatVd` switch below,
which is the default. For example, by default, if the expression of a
case statement is invalid, it will raise Constraint_Error rather than
causing a wild jump, and if an array index on the left-hand side of an
assignment is invalid, it will raise Constraint_Error rather than
overwriting an arbitrary memory location.
-The *-gnatVa* may be used to enable additional validity checks,
+The :switch:`-gnatVa` may be used to enable additional validity checks,
which are not required by the RM. These checks are often very
expensive (which is why the RM does not require them). These checks
are useful in tracking down uninitialized variables, but they are
If performance is a consideration, leading to the need to optimize,
then the validity checking options should not be used.
-The other *-gnatV*\ ``x`` switches below allow finer-grained
+The other :switch:`-gnatV{x}` switches below allow finer-grained
control; you can enable whichever validity checks you desire. However,
-for most debugging purposes, *-gnatVa* is sufficient, and the
-default *-gnatVd* (i.e. standard Ada behavior) is usually
+for most debugging purposes, :switch:`-gnatVa` is sufficient, and the
+default :switch:`-gnatVd` (i.e. standard Ada behavior) is usually
sufficient for non-debugging use.
-The *-gnatB* switch tells the compiler to assume that all
+The :switch:`-gnatB` switch tells the compiler to assume that all
values are valid (that is, within their declared subtype range)
except in the context of a use of the Valid attribute. This means
the compiler can generate more efficient code, since the range
of values is better known at compile time. However, an uninitialized
variable can cause wild jumps and memory corruption in this mode.
-The *-gnatV*\ ``x`` switch allows control over the validity
+The :switch:`-gnatV{x}` switch allows control over the validity
checking mode as described below.
The ``x`` argument is a string of letters that
indicate validity checks that are performed or not performed in addition
.. index:: -gnatVa (gcc)
-:samp:`-gnatVa`
+:switch:`-gnatVa`
*All validity checks.*
All validity checks are turned on.
- That is, *-gnatVa* is
- equivalent to *gnatVcdfimorst*.
+ That is, :switch:`-gnatVa` is
+ equivalent to ``gnatVcdfimorst``.
.. index:: -gnatVc (gcc)
-:samp:`-gnatVc`
+:switch:`-gnatVc`
*Validity checks for copies.*
The right hand side of assignments, and the initializing values of
.. index:: -gnatVd (gcc)
-:samp:`-gnatVd`
+:switch:`-gnatVd`
*Default (RM) validity checks.*
Some validity checks are done by default following normal Ada semantics
of the subtype. If it is not, Constraint_Error is raised.
For assignments to array components, a check is done that the expression used
as index is within the range. If it is not, Constraint_Error is raised.
- Both these validity checks may be turned off using switch *-gnatVD*.
- They are turned on by default. If *-gnatVD* is specified, a subsequent
- switch *-gnatVd* will leave the checks turned on.
- Switch *-gnatVD* should be used only if you are sure that all such
+ Both these validity checks may be turned off using switch :switch:`-gnatVD`.
+ They are turned on by default. If :switch:`-gnatVD` is specified, a subsequent
+ switch :switch:`-gnatVd` will leave the checks turned on.
+ Switch :switch:`-gnatVD` should be used only if you are sure that all such
expressions have valid values. If you use this switch and invalid values
are present, then the program is erroneous, and wild jumps or memory
overwriting may occur.
.. index:: -gnatVe (gcc)
-:samp:`-gnatVe`
+:switch:`-gnatVe`
*Validity checks for elementary components.*
In the absence of this switch, assignments to record or array components are
not validity checked, even if validity checks for assignments generally
- (*-gnatVc*) are turned on. In Ada, assignment of composite values do not
+ (:switch:`-gnatVc`) are turned on. In Ada, assignment of composite values do not
require valid data, but assignment of individual components does. So for
example, there is a difference between copying the elements of an array with a
slice assignment, compared to assigning element by element in a loop. This
.. index:: -gnatVf (gcc)
-:samp:`-gnatVf`
+:switch:`-gnatVf`
*Validity checks for floating-point values.*
In the absence of this switch, validity checking occurs only for discrete
- values. If *-gnatVf* is specified, then validity checking also applies
+ values. If :switch:`-gnatVf` is specified, then validity checking also applies
for floating-point values, and NaNs and infinities are considered invalid,
as well as out of range values for constrained types. Note that this means
that standard IEEE infinity mode is not allowed. The exact contexts
in which floating-point values are checked depends on the setting of other
- options. For example, *-gnatVif* or *-gnatVfi*
+ options. For example, :switch:`-gnatVif` or :switch:`-gnatVfi`
(the order does not matter) specifies that floating-point parameters of mode
- `in` should be validity checked.
+ ``in`` should be validity checked.
.. index:: -gnatVi (gcc)
-:samp:`-gnatVi`
- *Validity checks for `in` mode parameters.*
+:switch:`-gnatVi`
+ *Validity checks for ``in`` mode parameters.*
- Arguments for parameters of mode `in` are validity checked in function
+ Arguments for parameters of mode ``in`` are validity checked in function
and procedure calls at the point of call.
.. index:: -gnatVm (gcc)
-:samp:`-gnatVm`
- *Validity checks for `in out` mode parameters.*
+:switch:`-gnatVm`
+ *Validity checks for ``in out`` mode parameters.*
- Arguments for parameters of mode `in out` are validity checked in
- procedure calls at the point of call. The `'m'` here stands for
+ Arguments for parameters of mode ``in out`` are validity checked in
+ procedure calls at the point of call. The ``'m'`` here stands for
modify, since this concerns parameters that can be modified by the call.
- Note that there is no specific option to test `out` parameters,
+ Note that there is no specific option to test ``out`` parameters,
but any reference within the subprogram will be tested in the usual
manner, and if an invalid value is copied back, any reference to it
will be subject to validity checking.
.. index:: -gnatVn (gcc)
-:samp:`-gnatVn`
+:switch:`-gnatVn`
*No validity checks.*
This switch turns off all validity checking, including the default checking
for case statements and left hand side subscripts. Note that the use of
- the switch *-gnatp* suppresses all run-time checks, including
- validity checks, and thus implies *-gnatVn*. When this switch
- is used, it cancels any other *-gnatV* previously issued.
+ the switch :switch:`-gnatp` suppresses all run-time checks, including
+ validity checks, and thus implies :switch:`-gnatVn`. When this switch
+ is used, it cancels any other :switch:`-gnatV` previously issued.
.. index:: -gnatVo (gcc)
-:samp:`-gnatVo`
+:switch:`-gnatVo`
*Validity checks for operator and attribute operands.*
Arguments for predefined operators and attributes are validity checked.
- This includes all operators in package `Standard`,
- the shift operators defined as intrinsic in package `Interfaces`
- and operands for attributes such as `Pos`. Checks are also made
+ This includes all operators in package ``Standard``,
+ the shift operators defined as intrinsic in package ``Interfaces``
+ and operands for attributes such as ``Pos``. Checks are also made
on individual component values for composite comparisons, and on the
expressions in type conversions and qualified expressions. Checks are
also made on explicit ranges using :samp:`..` (e.g., slices, loops etc).
.. index:: -gnatVp (gcc)
-:samp:`-gnatVp`
+:switch:`-gnatVp`
*Validity checks for parameters.*
This controls the treatment of parameters within a subprogram (as opposed
- to *-gnatVi* and *-gnatVm* which control validity testing
+ to :switch:`-gnatVi` and :switch:`-gnatVm` which control validity testing
of parameters on a call. If either of these call options is used, then
normally an assumption is made within a subprogram that the input arguments
have been validity checking at the point of call, and do not need checking
- again within a subprogram). If *-gnatVp* is set, then this assumption
+ again within a subprogram). If :switch:`-gnatVp` is set, then this assumption
is not made, and parameters are not assumed to be valid, so their validity
will be checked (or rechecked) within the subprogram.
.. index:: -gnatVr (gcc)
-:samp:`-gnatVr`
+:switch:`-gnatVr`
*Validity checks for function returns.*
- The expression in `return` statements in functions is validity
+ The expression in ``return`` statements in functions is validity
checked.
.. index:: -gnatVs (gcc)
-:samp:`-gnatVs`
+:switch:`-gnatVs`
*Validity checks for subscripts.*
All subscripts expressions are checked for validity, whether they appear
.. index:: -gnatVt (gcc)
-:samp:`-gnatVt`
+:switch:`-gnatVt`
*Validity checks for tests.*
- Expressions used as conditions in `if`, `while` or `exit`
+ Expressions used as conditions in ``if``, ``while`` or ``exit``
statements are checked, as well as guard expressions in entry calls.
-The *-gnatV* switch may be followed by a string of letters
+The :switch:`-gnatV` switch may be followed by a string of letters
to turn on a series of validity checking options.
-For example, :samp:`-gnatVcr`
+For example, :switch:`-gnatVcr`
specifies that in addition to the default validity checking, copies and
function return expressions are to be validity checked.
In order to make it easier to specify the desired combination of effects,
-the upper case letters `CDFIMORST` may
+the upper case letters ``CDFIMORST`` may
be used to turn off the corresponding lower case option.
-Thus :samp:`-gnatVaM` turns on all validity checking options except for
-checking of `**in out**` procedure arguments.
+Thus :switch:`-gnatVaM` turns on all validity checking options except for
+checking of ``in out`` parameters.
The specification of additional validity checking generates extra code (and
-in the case of *-gnatVa* the code expansion can be substantial).
+in the case of :switch:`-gnatVa` the code expansion can be substantial).
However, these additional checks can be very useful in detecting
uninitialized variables, incorrect use of unchecked conversion, and other
-errors leading to invalid values. The use of pragma `Initialize_Scalars`
+errors leading to invalid values. The use of pragma ``Initialize_Scalars``
is useful in conjunction with the extra validity checking, since this
ensures that wherever possible uninitialized variables have invalid values.
-See also the pragma `Validity_Checks` which allows modification of
+See also the pragma ``Validity_Checks`` which allows modification of
the validity checking mode at the program source level, and also allows for
temporary disabling of validity checks.
.. index:: -gnaty (gcc)
-The *-gnatyx* switch causes the compiler to
+The :switch:`-gnatyx` switch causes the compiler to
enforce specified style rules. A limited set of style rules has been used
in writing the GNAT sources themselves. This switch allows user programs
to activate all or some of these checks. If the source program fails a
specified style check, an appropriate message is given, preceded by
the character sequence '(style)'. This message does not prevent
-successful compilation (unless the *-gnatwe* switch is used).
+successful compilation (unless the :switch:`-gnatwe` switch is used).
Note that this is by no means intended to be a general facility for
checking arbitrary coding standards. It is simply an embedding of the
of an existing set of coding rules, you should look to the gnatcheck
tool, which is designed for that purpose.
-The string `x` is a sequence of letters or digits
+The string ``x`` is a sequence of letters or digits
indicating the particular style
checks to be performed. The following checks are defined:
.. index:: -gnaty[0-9] (gcc)
-:samp:`-gnaty0`
+:switch:`-gnaty0`
*Specify indentation level.*
If a digit from 1-9 appears
- in the string after *-gnaty*
+ in the string after :switch:`-gnaty`
then proper indentation is checked, with the digit indicating the
indentation level required. A value of zero turns off this style check.
The general style of required indentation is as specified by
the examples in the Ada Reference Manual. Full line comments must be
- aligned with the `--` starting on a column that is a multiple of
+ aligned with the ``--`` starting on a column that is a multiple of
the alignment level, or they may be aligned the same way as the following
non-blank line (this is useful when full line comments appear in the middle
of a statement, or they may be aligned with the source line on the previous
.. index:: -gnatya (gcc)
-:samp:`-gnatya`
+:switch:`-gnatya`
*Check attribute casing.*
- Attribute names, including the case of keywords such as `digits`
+ Attribute names, including the case of keywords such as ``digits``
used as attributes names, must be written in mixed case, that is, the
initial letter and any letter following an underscore must be uppercase.
All other letters must be lowercase.
.. index:: -gnatyA (gcc)
-:samp:`-gnatyA`
+:switch:`-gnatyA`
*Use of array index numbers in array attributes.*
When using the array attributes First, Last, Range,
.. index:: -gnatyb (gcc)
-:samp:`-gnatyb`
+:switch:`-gnatyb`
*Blanks not allowed at statement end.*
Trailing blanks are not allowed at the end of statements. The purpose of this
.. index:: -gnatyB (gcc)
-:samp:`-gnatyB`
+:switch:`-gnatyB`
*Check Boolean operators.*
The use of AND/OR operators is not permitted except in the cases of modular
operands, array operands, and simple stand-alone boolean variables or
- boolean constants. In all other cases `and then`/`or else` are
+ boolean constants. In all other cases ``and then``/`or else` are
required.
.. index:: -gnatyc (gcc)
-:samp:`-gnatyc`
+:switch:`-gnatyc`
*Check comments, double space.*
Comments must meet the following set of rules:
- * The '`--`' that starts the column must either start in column one,
+ * The ``--`` that starts the column must either start in column one,
or else at least one blank must precede this sequence.
* Comments that follow other tokens on a line must have at least one blank
- following the '`--`' at the start of the comment.
+ following the ``--`` at the start of the comment.
* Full line comments must have at least two blanks following the
- '`--`' that starts the comment, with the following exceptions.
+ ``--`` that starts the comment, with the following exceptions.
- * A line consisting only of the '`--`' characters, possibly preceded
+ * A line consisting only of the ``--`` characters, possibly preceded
by blanks is permitted.
- * A comment starting with '`--x`' where `x` is a special character
+ * A comment starting with ``--x`` where ``x`` is a special character
is permitted.
- This allows proper processing of the output generated by specialized tools
- including *gnatprep* (where '`--!`' is used) and the SPARK
+ This allows proper processing of the output from specialized tools
+ such as ``gnatprep`` (where ``--!`` is used) and in earlier versions of the SPARK
annotation
- language (where '`--#`' is used). For the purposes of this rule, a
+ language (where ``--#`` is used). For the purposes of this rule, a
special character is defined as being in one of the ASCII ranges
- `16#21#...16#2F#` or `16#3A#...16#3F#`.
+ ``16#21#...16#2F#`` or ``16#3A#...16#3F#``.
Note that this usage is not permitted
- in GNAT implementation units (i.e., when *-gnatg* is used).
+ in GNAT implementation units (i.e., when :switch:`-gnatg` is used).
* A line consisting entirely of minus signs, possibly preceded by blanks, is
permitted. This allows the construction of box comments where lines of minus
signs are used to form the top and bottom of the box.
- * A comment that starts and ends with '`--`' is permitted as long as at
- least one blank follows the initial '`--`'. Together with the preceding
+ * A comment that starts and ends with ``--`` is permitted as long as at
+ least one blank follows the initial ``--``. Together with the preceding
rule, this allows the construction of box comments, as shown in the following
example:
.. index:: -gnatyC (gcc)
-:samp:`-gnatyC`
+:switch:`-gnatyC`
*Check comments, single space.*
- This is identical to `c` except that only one space
- is required following the `--` of a comment instead of two.
+ This is identical to ``c`` except that only one space
+ is required following the ``--`` of a comment instead of two.
.. index:: -gnatyd (gcc)
-:samp:`-gnatyd`
+:switch:`-gnatyd`
*Check no DOS line terminators present.*
All lines must be terminated by a single ASCII.LF
.. index:: -gnatye (gcc)
-:samp:`-gnatye`
+:switch:`-gnatye`
*Check end/exit labels.*
- Optional labels on `end` statements ending subprograms and on
- `exit` statements exiting named loops, are required to be present.
+ Optional labels on ``end`` statements ending subprograms and on
+ ``exit`` statements exiting named loops, are required to be present.
.. index:: -gnatyf (gcc)
-:samp:`-gnatyf`
+:switch:`-gnatyf`
*No form feeds or vertical tabs.*
Neither form feeds nor vertical tab characters are permitted
.. index:: -gnatyg (gcc)
-:samp:`-gnatyg`
+:switch:`-gnatyg`
*GNAT style mode.*
The set of style check switches is set to match that used by the GNAT sources.
This may be useful when developing code that is eventually intended to be
- incorporated into GNAT. Currently this is equivalent to *-gnatwydISux*)
+ incorporated into GNAT. Currently this is equivalent to :switch:`-gnatwydISux`)
but additional style switches may be added to this set in the future without
advance notice.
.. index:: -gnatyh (gcc)
-:samp:`-gnatyh`
+:switch:`-gnatyh`
*No horizontal tabs.*
Horizontal tab characters are not permitted in the source text.
.. index:: -gnatyi (gcc)
-:samp:`-gnatyi`
+:switch:`-gnatyi`
*Check if-then layout.*
- The keyword `then` must appear either on the same
- line as corresponding `if`, or on a line on its own, lined
- up under the `if`.
+ The keyword ``then`` must appear either on the same
+ line as corresponding ``if``, or on a line on its own, lined
+ up under the ``if``.
.. index:: -gnatyI (gcc)
-:samp:`-gnatyI`
+:switch:`-gnatyI`
*check mode IN keywords.*
- Mode `in` (the default mode) is not
- allowed to be given explicitly. `in out` is fine,
- but not `in` on its own.
+ Mode ``in`` (the default mode) is not
+ allowed to be given explicitly. ``in out`` is fine,
+ but not ``in`` on its own.
.. index:: -gnatyk (gcc)
-:samp:`-gnatyk`
+:switch:`-gnatyk`
*Check keyword casing.*
All keywords must be in lower case (with the exception of keywords
- such as `digits` used as attribute names to which this check
+ such as ``digits`` used as attribute names to which this check
does not apply).
.. index:: -gnatyl (gcc)
-:samp:`-gnatyl`
+:switch:`-gnatyl`
*Check layout.*
Layout of statement and declaration constructs must follow the
recommendations in the Ada Reference Manual, as indicated by the
- form of the syntax rules. For example an `else` keyword must
- be lined up with the corresponding `if` keyword.
+ form of the syntax rules. For example an ``else`` keyword must
+ be lined up with the corresponding ``if`` keyword.
There are two respects in which the style rule enforced by this check
option are more liberal than those in the Ada Reference Manual. First
in the case of record declarations, it is permissible to put the
- `record` keyword on the same line as the `type` keyword, and
- then the `end` in `end record` must line up under `type`.
+ ``record`` keyword on the same line as the ``type`` keyword, and
+ then the ``end`` in ``end record`` must line up under ``type``.
This is also permitted when the type declaration is split on two lines.
For example, any of the following three layouts is acceptable:
end record;
Second, in the case of a block statement, a permitted alternative
- is to put the block label on the same line as the `declare` or
- `begin` keyword, and then line the `end` keyword up under
+ is to put the block label on the same line as the ``declare`` or
+ ``begin`` keyword, and then line the ``end`` keyword up under
the block label. For example both the following are permitted:
.. code-block:: ada
.. index:: -gnatyLnnn (gcc)
-:samp:`-gnatyL`
+:switch:`-gnatyL`
*Set maximum nesting level.*
The maximum level of nesting of constructs (including subprograms, loops,
.. index:: -gnatym (gcc)
-:samp:`-gnatym`
+:switch:`-gnatym`
*Check maximum line length.*
The length of source lines must not exceed 79 characters, including
.. index:: -gnatyMnnn (gcc)
-:samp:`-gnatyM`
+:switch:`-gnatyM`
*Set maximum line length.*
The length of lines must not exceed the
.. index:: -gnatyn (gcc)
-:samp:`-gnatyn`
+:switch:`-gnatyn`
*Check casing of entities in Standard.*
Any identifier from Standard must be cased
to match the presentation in the Ada Reference Manual (for example,
- `Integer` and `ASCII.NUL`).
+ ``Integer`` and ``ASCII.NUL``).
.. index:: -gnatyN (gcc)
-:samp:`-gnatyN`
+:switch:`-gnatyN`
*Turn off all style checks.*
All style check options are turned off.
.. index:: -gnatyo (gcc)
-:samp:`-gnatyo`
+:switch:`-gnatyo`
*Check order of subprogram bodies.*
All subprogram bodies in a given scope
.. index:: -gnatyO (gcc)
-:samp:`-gnatyO`
+:switch:`-gnatyO`
*Check that overriding subprograms are explicitly marked as such.*
This applies to all subprograms of a derived type that override a primitive
.. index:: -gnatyp (gcc)
-:samp:`-gnatyp`
+:switch:`-gnatyp`
*Check pragma casing.*
Pragma names must be written in mixed case, that is, the
.. index:: -gnatyr (gcc)
-:samp:`-gnatyr`
+:switch:`-gnatyr`
*Check references.*
All identifier references must be cased in the same way as the
.. index:: -gnatys (gcc)
-:samp:`-gnatys`
+:switch:`-gnatys`
*Check separate specs.*
Separate declarations ('specs') are required for subprograms (a
.. index:: -gnatyS (gcc)
-:samp:`-gnatyS`
+:switch:`-gnatyS`
*Check no statements after then/else.*
No statements are allowed
- on the same line as a `then` or `else` keyword following the
- keyword in an `if` statement. `or else` and `and then` are not
- affected, and a special exception allows a pragma to appear after `else`.
+ on the same line as a ``then`` or ``else`` keyword following the
+ keyword in an ``if`` statement. ``or else`` and ``and then`` are not
+ affected, and a special exception allows a pragma to appear after ``else``.
.. index:: -gnatyt (gcc)
-:samp:`-gnatyt`
+:switch:`-gnatyt`
*Check token spacing.*
The following token spacing rules are enforced:
- * The keywords `abs` and `not` must be followed by a space.
+ * The keywords ``abs`` and ``not`` must be followed by a space.
- * The token `=>` must be surrounded by spaces.
+ * The token ``=>`` must be surrounded by spaces.
- * The token `<>` must be preceded by a space or a left parenthesis.
+ * The token ``<>`` must be preceded by a space or a left parenthesis.
- * Binary operators other than `**` must be surrounded by spaces.
- There is no restriction on the layout of the `**` binary operator.
+ * Binary operators other than ``**`` must be surrounded by spaces.
+ There is no restriction on the layout of the ``**`` binary operator.
* Colon must be surrounded by spaces.
* A vertical bar must be surrounded by spaces.
Exactly one blank (and no other white space) must appear between
- a `not` token and a following `in` token.
+ a ``not`` token and a following ``in`` token.
.. index:: -gnatyu (gcc)
-:samp:`-gnatyu`
+:switch:`-gnatyu`
*Check unnecessary blank lines.*
Unnecessary blank lines are not allowed. A blank line is considered
.. index:: -gnatyx (gcc)
-:samp:`-gnatyx`
+:switch:`-gnatyx`
*Check extra parentheses.*
Unnecessary extra level of parentheses (C-style) are not allowed
- around conditions in `if` statements, `while` statements and
- `exit` statements.
+ around conditions in ``if`` statements, ``while`` statements and
+ ``exit`` statements.
.. index:: -gnatyy (gcc)
-:samp:`-gnatyy`
+:switch:`-gnatyy`
*Set all standard style check options.*
- This is equivalent to `gnaty3aAbcefhiklmnprst`, that is all checking
- options enabled with the exception of *-gnatyB*, *-gnatyd*,
- *-gnatyI*, *-gnatyLnnn*, *-gnatyo*, *-gnatyO*,
- *-gnatyS*, *-gnatyu*, and *-gnatyx*.
+ This is equivalent to ``gnaty3aAbcefhiklmnprst``, that is all checking
+ options enabled with the exception of :switch:`-gnatyB`, :switch:`-gnatyd`,
+ :switch:`-gnatyI`, :switch:`-gnatyLnnn`, :switch:`-gnatyo`, :switch:`-gnatyO`,
+ :switch:`-gnatyS`, :switch:`-gnatyu`, and :switch:`-gnatyx`.
.. index:: -gnaty- (gcc)
-:samp:`-gnaty-`
+:switch:`-gnaty-`
*Remove style check options.*
This causes any subsequent options in the string to act as canceling the
corresponding style check option. To cancel maximum nesting level control,
- use *L* parameter witout any integer value after that, because any
- digit following *-* in the parameter string of the *-gnaty*
- option will be threated as canceling indentation check. The same is true
- for *M* parameter. *y* and *N* parameters are not
+ use the ``L`` parameter without any integer value after that, because any
+ digit following *-* in the parameter string of the :switch:`-gnaty`
+ option will be treated as canceling the indentation check. The same is true
+ for the ``M`` parameter. ``y`` and ``N`` parameters are not
allowed after *-*.
.. index:: -gnaty+ (gcc)
-:samp:`-gnaty+`
+:switch:`-gnaty+`
*Enable style check options.*
This causes any subsequent options in the string to enable the corresponding
details on the violation. The initial characters of such messages are
always '`(style)`'. Note that these messages are treated as warning
messages, so they normally do not prevent the generation of an object
-file. The *-gnatwe* switch can be used to treat warning messages,
+file. The :switch:`-gnatwe` switch can be used to treat warning messages,
including style messages, as fatal errors.
-The switch :samp:`-gnaty` on its own (that is not
+The switch :switch:`-gnaty` on its own (that is not
followed by any letters or digits) is equivalent
-to the use of *-gnatyy* as described above, that is all
+to the use of :switch:`-gnatyy` as described above, that is all
built-in standard style check options are enabled.
-The switch :samp:`-gnatyN` clears any previously set style checks.
+The switch :switch:`-gnatyN` clears any previously set style checks.
.. _Run-Time_Checks:
By default, the following checks are suppressed: stack overflow
checks, and checks for access before elaboration on subprogram
calls. All other checks, including overflow checks, range checks and
-array bounds checks, are turned on by default. The following *gcc*
+array bounds checks, are turned on by default. The following ``gcc``
switches refine this default behavior.
.. index:: -gnatp (gcc)
-:samp:`-gnatp`
+:switch:`-gnatp`
.. index:: Suppressing checks
.. index:: Checks, suppressing
This switch causes the unit to be compiled
- as though `pragma Suppress (All_checks)`
+ as though ``pragma Suppress (All_checks)``
had been present in the source. Validity checks are also eliminated (in
- other words *-gnatp* also implies *-gnatVn*.
+ other words :switch:`-gnatp` also implies :switch:`-gnatVn`.
Use this switch to improve the performance
of the code at the expense of safety in the presence of invalid data or
program bugs.
execution if that assumption is wrong.
The checks subject to suppression include all the checks defined by the Ada
- standard, the additional implementation defined checks `Alignment_Check`,
- `Duplicated_Tag_Check`, `Predicate_Check`, Container_Checks, Tampering_Check,
- and `Validity_Check`, as well as any checks introduced using `pragma
- Check_Name`. Note that `Atomic_Synchronization` is not automatically
- suppressed by use of this option.
+ standard, the additional implementation defined checks ``Alignment_Check``,
+ ``Duplicated_Tag_Check``, ``Predicate_Check``, ``Container_Checks``, ``Tampering_Check``,
+ and ``Validity_Check``, as well as any checks introduced using ``pragma Check_Name``.
+ Note that ``Atomic_Synchronization`` is not automatically suppressed by use of this option.
If the code depends on certain checks being active, you can use
- pragma `Unsuppress` either as a configuration pragma or as
+ pragma ``Unsuppress`` either as a configuration pragma or as
a local pragma to make sure that a specified check is performed
- even if *gnatp* is specified.
+ even if ``gnatp`` is specified.
- The *-gnatp* switch has no effect if a subsequent
- *-gnat-p* switch appears.
+ The :switch:`-gnatp` switch has no effect if a subsequent
+ :switch:`-gnat-p` switch appears.
.. index:: -gnat-p (gcc)
.. index:: Checks, suppressing
.. index:: Suppress
-:samp:`-gnat-p`
- This switch cancels the effect of a previous *gnatp* switch.
+:switch:`-gnat-p`
+ This switch cancels the effect of a previous ``gnatp`` switch.
.. index:: -gnato?? (gcc)
.. index:: Overflow mode
.. index:: Check, overflow
-:samp:`-gnato??`
+:switch:`-gnato??`
This switch controls the mode used for computing intermediate
arithmetic integer operations, and also enables overflow checking.
For a full description of overflow mode and checking control, see
*2 = MINIMIZED*
In MINIMIZED mode, overflows in intermediate operations are avoided
where possible by using a larger integer type for the computation
- (typically `Long_Long_Integer`). Overflow checking ensures that
+ (typically ``Long_Long_Integer``). Overflow checking ensures that
the result fits in this larger integer type.
by using multi-precision arithmetic. In this case, overflow checking
has no effect on intermediate operations (since overflow is impossible).
- If two digits are present after *-gnato* then the first digit
+ If two digits are present after :switch:`-gnato` then the first digit
sets the mode for expressions outside assertions, and the second digit
sets the mode for expressions within assertions. Here assertions is used
in the technical sense (which includes for example precondition and
If no digits are present, the default is to enable overflow checks
and set STRICT mode for both kinds of expressions. This is compatible
- with the use of *-gnato* in previous versions of GNAT.
+ with the use of :switch:`-gnato` in previous versions of GNAT.
.. index:: Machine_Overflows
- Note that the *-gnato??* switch does not affect the code generated
+ Note that the :switch:`-gnato??` switch does not affect the code generated
for any floating-point operations; it applies only to integer semantics.
- For floating-point, GNAT has the `Machine_Overflows`
- attribute set to `False` and the normal mode of operation is to
+ For floating-point, GNAT has the ``Machine_Overflows``
+ attribute set to ``False`` and the normal mode of operation is to
generate IEEE NaN and infinite values on overflow or invalid operations
(such as dividing 0.0 by 0.0).
checking is also quite expensive in time and space, since in general it
requires the use of double length arithmetic.
- Note again that the default is *-gnato11* (equivalent to *-gnato1*),
+ Note again that the default is :switch:`-gnato11` (equivalent to :switch:`-gnato1`),
so overflow checking is performed in STRICT mode by default.
.. index:: Elaboration checks
.. index:: Check, elaboration
-:samp:`-gnatE`
+:switch:`-gnatE`
Enables dynamic checks for access-before-elaboration
on subprogram calls and generic instantiations.
- Note that *-gnatE* is not necessary for safety, because in the
+ Note that :switch:`-gnatE` is not necessary for safety, because in the
default mode, GNAT ensures statically that the checks would not fail.
For full details of the effect and use of this switch,
:ref:`Compiling_with_gcc`.
.. index:: Stack Overflow Checking
.. index:: Checks, stack overflow checking
-:samp:`-fstack-check`
+:switch:`-fstack-check`
Activates stack overflow checking. For full details of the effect and use of
this switch see :ref:`Stack_Overflow_Checking`.
.. index:: Unsuppress
The setting of these switches only controls the default setting of the
-checks. You may modify them using either `Suppress` (to remove
-checks) or `Unsuppress` (to add back suppressed checks) pragmas in
+checks. You may modify them using either ``Suppress`` (to remove
+checks) or ``Unsuppress`` (to add back suppressed checks) pragmas in
the program source.
.. _Using_gcc_for_Syntax_Checking:
-Using *gcc* for Syntax Checking
--------------------------------
+Using ``gcc`` for Syntax Checking
+---------------------------------
.. index:: -gnats (gcc)
-:samp:`-gnats`
- The `s` stands for 'syntax'.
+:switch:`-gnats`
+ The ``s`` stands for 'syntax'.
Run GNAT in syntax checking only mode. For
example, the command
compiles file :file:`x.adb` in syntax-check-only mode. You can check a
series of files in a single command
, and can use wild cards to specify such a group of files.
- Note that you must specify the *-c* (compile
- only) flag in addition to the *-gnats* flag.
+ Note that you must specify the :switch:`-c` (compile
+ only) flag in addition to the :switch:`-gnats` flag.
- You may use other switches in conjunction with *-gnats*. In
- particular, *-gnatl* and *-gnatv* are useful to control the
+ You may use other switches in conjunction with :switch:`-gnats`. In
+ particular, :switch:`-gnatl` and :switch:`-gnatv` are useful to control the
format of any generated error messages.
When the source file is empty or contains only empty lines and/or comments,
Otherwise, the output is simply the error messages, if any. No object file or
ALI file is generated by a syntax-only compilation. Also, no units other
- than the one specified are accessed. For example, if a unit `X`
- |withs| a unit `Y`, compiling unit `X` in syntax
+ than the one specified are accessed. For example, if a unit ``X``
+ |withs| a unit ``Y``, compiling unit ``X`` in syntax
check only mode does not access the source file containing unit
- `Y`.
+ ``Y``.
.. index:: Multiple units, syntax checking
Normally, GNAT allows only a single unit in a source file. However, this
restriction does not apply in syntax-check-only mode, and it is possible
to check a file containing multiple compilation units concatenated
- together. This is primarily used by the `gnatchop` utility
+ together. This is primarily used by the ``gnatchop`` utility
(:ref:`Renaming_Files_with_gnatchop`).
.. _Using_gcc_for_Semantic_Checking:
-Using *gcc* for Semantic Checking
----------------------------------
+Using ``gcc`` for Semantic Checking
+-----------------------------------
.. index:: -gnatc (gcc)
-:samp:`-gnatc`
- The `c` stands for 'check'.
+:switch:`-gnatc`
+ The ``c`` stands for 'check'.
Causes the compiler to operate in semantic check mode,
with full checking for all illegalities specified in the
Ada Reference Manual, but without generation of any object code
.. index:: ACVC, Ada 83 tests
.. index:: Ada 83 mode
-:samp:`-gnat83` (Ada 83 Compatibility Mode)
+:switch:`-gnat83` (Ada 83 Compatibility Mode)
Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
specifies that the program is to be compiled in Ada 83 mode. With
- *-gnat83*, GNAT rejects most post-Ada 83 extensions and applies Ada 83
+ :switch:`-gnat83`, GNAT rejects most post-Ada 83 extensions and applies Ada 83
semantics where this can be done easily.
It is not possible to guarantee this switch does a perfect
job; some subtle tests, such as are
where, due to contractual reasons, existing code needs to be maintained
using only Ada 83 features.
- With few exceptions (most notably the need to use `<>` on
+ With few exceptions (most notably the need to use ``<>`` on
unconstrained :index:`generic formal parameters <Generic formal parameters>`,
the use of the new Ada 95 / Ada 2005
reserved words, and the use of packages
with optional bodies), it is not necessary to specify the
- *-gnat83* switch when compiling Ada 83 programs, because, with rare
+ :switch:`-gnat83` switch when compiling Ada 83 programs, because, with rare
exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
a correct Ada 83 program is usually also a correct program
in these later versions of the language standard. For further information
- please refer to the `Compatibility_and_Porting_Guide` chapter in the
+ please refer to the *Compatibility and Porting Guide* chapter in the
:title:`GNAT Reference Manual`.
.. index:: -gnat95 (gcc)
.. index:: Ada 95 mode
-:samp:`-gnat95` (Ada 95 mode)
+:switch:`-gnat95` (Ada 95 mode)
This switch directs the compiler to implement the Ada 95 version of the
language.
Since Ada 95 is almost completely upwards
compatible with Ada 83, Ada 83 programs may generally be compiled using
- this switch (see the description of the *-gnat83* switch for further
+ this switch (see the description of the :switch:`-gnat83` switch for further
information about Ada 83 mode).
If an Ada 2005 program is compiled in Ada 95 mode,
uses of the new Ada 2005 features will cause error
messages or warnings.
This switch also can be used to cancel the effect of a previous
- *-gnat83*, *-gnat05/2005*, or *-gnat12/2012*
+ :switch:`-gnat83`, :switch:`-gnat05/2005`, or :switch:`-gnat12/2012`
switch earlier in the command line.
.. index:: -gnat2005 (gcc)
.. index:: Ada 2005 mode
-:samp:`-gnat05` or :samp:`-gnat2005` (Ada 2005 mode)
+:switch:`-gnat05` or :switch:`-gnat2005` (Ada 2005 mode)
This switch directs the compiler to implement the Ada 2005 version of the
language, as documented in the official Ada standards document.
Since Ada 2005 is almost completely upwards
compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
may generally be compiled using this switch (see the description of the
- *-gnat83* and *-gnat95* switches for further
+ :switch:`-gnat83` and :switch:`-gnat95` switches for further
information).
.. index:: -gnat2012 (gcc)
.. index:: Ada 2012 mode
-:samp:`-gnat12` or :samp:`-gnat2012` (Ada 2012 mode)
+:switch:`-gnat12` or :switch:`-gnat2012` (Ada 2012 mode)
This switch directs the compiler to implement the Ada 2012 version of the
language (also the default).
Since Ada 2012 is almost completely upwards
compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
Ada 83 and Ada 95 programs
may generally be compiled using this switch (see the description of the
- *-gnat83*, *-gnat95*, and *-gnat05/2005* switches
+ :switch:`-gnat83`, :switch:`-gnat95`, and :switch:`-gnat05/2005` switches
for further information).
.. index:: Ada language extensions
.. index:: GNAT extensions
-:samp:`-gnatX` (Enable GNAT Extensions)
+:switch:`-gnatX` (Enable GNAT Extensions)
This switch directs the compiler to implement the latest version of the
language (currently Ada 2012) and also to enable certain GNAT implementation
extensions that are not part of any Ada standard. For a full list of these
.. index:: -gnati (gcc)
-:samp:`-gnati{c}`
+:switch:`-gnati{c}`
Normally GNAT recognizes the Latin-1 character set in source program
identifiers, as described in the Ada Reference Manual.
This switch causes
- GNAT to recognize alternate character sets in identifiers. `c` is a
+ GNAT to recognize alternate character sets in identifiers. ``c`` is a
single character indicating the character set, as follows:
========== ======================================================
.. index:: -gnatW (gcc)
-:samp:`-gnatW{e}`
+:switch:`-gnatW{e}`
Specify the method of encoding for wide characters.
- `e` is one of the following:
+ ``e`` is one of the following:
========== ======================================================
*h* Hex encoding (brackets coding also recognized)
For full details on these encoding
methods see :ref:`Wide_Character_Encodings`.
Note that brackets coding is always accepted, even if one of the other
- options is specified, so for example *-gnatW8* specifies that both
+ options is specified, so for example :switch:`-gnatW8` specifies that both
brackets and UTF-8 encodings will be recognized. The units that are
with'ed directly or indirectly will be scanned using the specified
representation scheme, and so if one of the non-brackets scheme is
brackets are considered to be normal graphic characters, and bracket sequences
are never recognized as wide characters.
- If no *-gnatW?* parameter is present, then the default
+ If no :switch:`-gnatW?` parameter is present, then the default
representation is normally Brackets encoding only. However, if the
first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
byte order mark or BOM for UTF-8), then these three characters are
parameter.
-When no *-gnatW?* is specified, then characters (other than wide
+When no :switch:`-gnatW?` is specified, then characters (other than wide
characters represented using brackets notation) are treated as 8-bit
Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
and ASCII format effectors (CR, LF, HT, VT). Other lower half control
.. index:: -gnatk (gcc)
-:samp:`-gnatk{n}`
- Activates file name 'krunching'. `n`, a decimal integer in the range
+:switch:`-gnatk{n}`
+ Activates file name 'krunching'. ``n``, a decimal integer in the range
1-999, indicates the maximum allowable length of a file name (not
including the :file:`.ads` or :file:`.adb` extension). The default is not
to enable file name krunching.
.. index:: -gnatn (gcc)
-:samp:`-gnatn[12]`
- The `n` here is intended to suggest the first syllable of the word 'inline'.
- GNAT recognizes and processes `Inline` pragmas. However, for inlining to
+:switch:`-gnatn[12]`
+ The ``n`` here is intended to suggest the first syllable of the word 'inline'.
+ GNAT recognizes and processes ``Inline`` pragmas. However, for inlining to
actually occur, optimization must be enabled and, by default, inlining of
subprograms across modules is not performed. If you want to additionally
- enable inlining of subprograms specified by pragma `Inline` across modules,
+ enable inlining of subprograms specified by pragma ``Inline`` across modules,
you must also specify this switch.
In the absence of this switch, GNAT does not attempt inlining across modules
- and does not access the bodies of subprograms for which `pragma Inline` is
+ and does not access the bodies of subprograms for which ``pragma Inline`` is
specified if they are not in the current unit.
You can optionally specify the inlining level: 1 for moderate inlining across
modules, which is a good compromise between compilation times and performances
at run time, or 2 for full inlining across modules, which may bring about
longer compilation times. If no inlining level is specified, the compiler will
- pick it based on the optimization level: 1 for *-O1*, *-O2* or
- *-Os* and 2 for *-O3*.
+ pick it based on the optimization level: 1 for :switch:`-O1`, :switch:`-O2` or
+ :switch:`-Os` and 2 for :switch:`-O3`.
If you specify this switch the compiler will access these bodies,
creating an extra source dependency for the resulting object file, and
.. index:: -gnatN (gcc)
-:samp:`-gnatN`
+:switch:`-gnatN`
This switch activates front-end inlining which also
generates additional dependencies.
When using a gcc-based back end (in practice this means using any version
of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
- *-gnatN* is deprecated, and the use of *-gnatn* is preferred.
+ :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
.. index:: Writing internal trees
.. index:: Internal trees, writing to file
-:samp:`-gnatt`
+:switch:`-gnatt`
Causes GNAT to write the internal tree for a unit to a file (with the
extension :file:`.adt`.
This not normally required, but is used by separate analysis tools.
Typically
these tools do the necessary compilations automatically, so you should
not have to specify this switch in normal operation.
- Note that the combination of switches *-gnatct*
+ Note that the combination of switches :switch:`-gnatct`
generates a tree in the form required by ASIS applications.
.. index:: -gnatu (gcc)
-:samp:`-gnatu`
+:switch:`-gnatu`
Print a list of units required by this compilation on :file:`stdout`.
The listing includes all units on which the unit being compiled depends
either directly or indirectly.
.. index:: -pass-exit-codes (gcc)
-:samp:`-pass-exit-codes`
- If this switch is not used, the exit code returned by *gcc* when
+:switch:`-pass-exit-codes`
+ If this switch is not used, the exit code returned by ``gcc`` when
compiling multiple files indicates whether all source files have
been successfully used to generate object files or not.
- When *-pass-exit-codes* is used, *gcc* exits with an extended
+ When :switch:`-pass-exit-codes` is used, ``gcc`` exits with an extended
exit status and allows an integrated development environment to better
react to a compilation failure. Those exit status are:
.. index:: -gnatd (gcc)
-:samp:`-gnatd{x}`
- Activate internal debugging switches. `x` is a letter or digit, or
+:switch:`-gnatd{x}`
+ Activate internal debugging switches. ``x`` is a letter or digit, or
string of letters or digits, which specifies the type of debugging
outputs desired. Normally these are used only for internal development
or system debugging purposes. You can find full documentation for these
- switches in the body of the `Debug` unit in the compiler source
+ switches in the body of the ``Debug`` unit in the compiler source
file :file:`debug.adb`.
.. index:: -gnatG (gcc)
-:samp:`-gnatG[={nn}]`
+:switch:`-gnatG[={nn}]`
This switch causes the compiler to generate auxiliary output containing
a pseudo-source listing of the generated expanded code. Like most Ada
compilers, GNAT works by first transforming the high level Ada code into
This is very useful in understanding the implications of various Ada
usage on the efficiency of the generated code. There are many cases in
Ada (e.g., the use of controlled types), where simple Ada statements can
- generate a lot of run-time code. By using *-gnatG* you can identify
+ generate a lot of run-time code. By using :switch:`-gnatG` you can identify
these cases, and consider whether it may be desirable to modify the coding
approach to improve efficiency.
- The optional parameter `nn` if present after -gnatG specifies an
+ The optional parameter ``nn`` if present after -gnatG specifies an
alternative maximum line length that overrides the normal default of 72.
This value is in the range 40-999999, values less than 40 being silently
reset to 40. The equal sign is optional.
additions correspond to low level features used in the generated code that
do not have any exact analogies in pure Ada source form. The following
is a partial list of these special constructions. See the spec
- of package `Sprint` in file :file:`sprint.ads` for a full list.
+ of package ``Sprint`` in file :file:`sprint.ads` for a full list.
.. index:: -gnatL (gcc)
- If the switch *-gnatL* is used in conjunction with
- *-gnatG*, then the original source lines are interspersed
+ If the switch :switch:`-gnatL` is used in conjunction with
+ :switch:`-gnatG`, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
:samp:`new {xxx} [storage_pool = {yyy}]`
:samp:`(if {expr} then {expr} else {expr})`
- Conditional expression equivalent to the `x?y:z` construction in C.
+ Conditional expression equivalent to the ``x?y:z`` construction in C.
:samp:`{target}^({source})`
:samp:`free {expr} [storage_pool = {xxx}]`
- Shows the storage pool associated with a `free` statement.
+ Shows the storage pool associated with a ``free`` statement.
:samp:`[subtype or type declaration]`
:samp:`freeze {type-name} [{actions}]`
- Shows the point at which `type-name` is frozen, with possible
+ Shows the point at which ``type-name`` is frozen, with possible
associated actions to be performed at the freeze point.
:samp:`reference {itype}`
- Reference (and hence definition) to internal type `itype`.
+ Reference (and hence definition) to internal type ``itype``.
:samp:`{function-name}! ({arg}, {arg}, {arg})`
:samp:`{label-name} : label`
- Declaration of label `labelname`.
+ Declaration of label ``labelname``.
:samp:`#$ {subprogram-name}`
:samp:`{expr} && {expr} && {expr} ... && {expr}`
- A multiple concatenation (same effect as `expr` & `expr` &
- `expr`, but handled more efficiently).
+ A multiple concatenation (same effect as ``expr`` & ``expr`` &
+ ``expr``, but handled more efficiently).
:samp:`[constraint_error]`
- Raise the `Constraint_Error` exception.
+ Raise the ``Constraint_Error`` exception.
:samp:`{expression}'reference`
:samp:`{target-type}!({source-expression})`
- An unchecked conversion of `source-expression` to `target-type`.
+ An unchecked conversion of ``source-expression`` to ``target-type``.
:samp:`[{numerator}/{denominator}]`
.. index:: -gnatD (gcc)
-:samp:`-gnatD[=nn]`
- When used in conjunction with *-gnatG*, this switch causes
+:switch:`-gnatD[=nn]`
+ When used in conjunction with :switch:`-gnatG`, this switch causes
the expanded source, as described above for
- *-gnatG* to be written to files with names
+ :switch:`-gnatG` to be written to files with names
:file:`xxx.dg`, where :file:`xxx` is the normal file name,
instead of to the standard output file. For
example, if the source file name is :file:`hello.adb`, then a file
:file:`hello.adb.dg` will be written. The debugging
- information generated by the *gcc* *-g* switch
+ information generated by the ``gcc`` :switch:`-g` switch
will refer to the generated :file:`xxx.dg` file. This allows
you to do source level debugging using the generated code which is
sometimes useful for complex code, for example to find out exactly
which part of a complex construction raised an exception. This switch
also suppresses generation of cross-reference information (see
- *-gnatx*) since otherwise the cross-reference information
+ :switch:`-gnatx`) since otherwise the cross-reference information
would refer to the :file:`.dg` file, which would cause
confusion since this is not the original source file.
- Note that *-gnatD* actually implies *-gnatG*
+ Note that :switch:`-gnatD` actually implies :switch:`-gnatG`
automatically, so it is not necessary to give both options.
- In other words *-gnatD* is equivalent to *-gnatDG*).
+ In other words :switch:`-gnatD` is equivalent to :switch:`-gnatDG`).
.. index:: -gnatL (gcc)
- If the switch *-gnatL* is used in conjunction with
- *-gnatDG*, then the original source lines are interspersed
+ If the switch :switch:`-gnatL` is used in conjunction with
+ :switch:`-gnatDG`, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
- The optional parameter `nn` if present after -gnatD specifies an
+ The optional parameter ``nn`` if present after -gnatD specifies an
alternative maximum line length that overrides the normal default of 72.
This value is in the range 40-999999, values less than 40 being silently
reset to 40. The equal sign is optional.
.. index:: -gnatr (gcc)
.. index:: pragma Restrictions
-:samp:`-gnatr`
+:switch:`-gnatr`
This switch causes pragma Restrictions to be treated as Restriction_Warnings
so that violation of restrictions causes warnings rather than illegalities.
This is useful during the development process when new restrictions are added
.. index:: -gnatR (gcc)
-:samp:`-gnatR[0|1|2|3[s]]`
+:switch:`-gnatR[0|1|2|3][e][m][s]`
This switch controls output from the compiler of a listing showing
- representation information for declared types and objects. For
- *-gnatR0*, no information is output (equivalent to omitting
- the *-gnatR* switch). For *-gnatR1* (which is the default,
- so *-gnatR* with no parameter has the same effect), size and alignment
- information is listed for declared array and record types. For
- *-gnatR2*, size and alignment information is listed for all
- declared types and objects. The `Linker_Section` is also listed for any
- entity for which the `Linker_Section` is set explicitly or implicitly (the
- latter case occurs for objects of a type for which a `Linker_Section`
+ representation information for declared types, objects and subprograms.
+ For :switch:`-gnatR0`, no information is output (equivalent to omitting
+ the :switch:`-gnatR` switch). For :switch:`-gnatR1` (which is the default,
+ so :switch:`-gnatR` with no parameter has the same effect), size and
+ alignment information is listed for declared array and record types.
+ For :switch:`-gnatR2`, size and alignment information is listed for all
+ declared types and objects. The ``Linker_Section`` is also listed for any
+ entity for which the ``Linker_Section`` is set explicitly or implicitly (the
+ latter case occurs for objects of a type for which a ``Linker_Section``
is set).
- Finally *-gnatR3* includes symbolic
- expressions for values that are computed at run time for
- variant records. These symbolic expressions have a mostly obvious
- format with #n being used to represent the value of the n'th
- discriminant. See source files :file:`repinfo.ads/adb` in the
- `GNAT` sources for full details on the format of *-gnatR3*
- output. If the switch is followed by an s (e.g., *-gnatR2s*), then
- the output is to a file with the name :file:`file.rep` where
- file is the name of the corresponding source file.
+ For :switch:`-gnatR3`, symbolic expressions for values that are computed
+ at run time for records are included. These symbolic expressions have
+ a mostly obvious format with #n being used to represent the value of the
+ n'th discriminant. See source files :file:`repinfo.ads/adb` in the
+ GNAT sources for full details on the format of :switch:`-gnatR3` output.
+
+ If the switch is followed by an ``e`` (e.g. :switch:`-gnatR2e`), then
+ extended representation information for record sub-components of records
+ are included.
+ If the switch is followed by an ``m`` (e.g. :switch:`-gnatRm`), then
+ subprogram conventions and parameter passing mechanisms for all the
+ subprograms are included.
-:samp:`-gnatRm[s]`
- This form of the switch controls output of subprogram conventions
- and parameter passing mechanisms for all subprograms. A following
- `s` means output to a file as described above.
+ If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then
+ the output is to a file with the name :file:`file.rep` where file is
+ the name of the corresponding source file.
Note that it is possible for record components to have zero size. In
this case, the component clause uses an obvious extension of permitted
- Ada syntax, for example `at 0 range 0 .. -1`.
+ Ada syntax, for example ``at 0 range 0 .. -1``.
.. index:: -gnatS (gcc)
-:samp:`-gnatS`
- The use of the switch *-gnatS* for an
+:switch:`-gnatS`
+ The use of the switch :switch:`-gnatS` for an
Ada compilation will cause the compiler to output a
representation of package Standard in a form very
close to standard Ada. It is not quite possible to
.. index:: -gnatx (gcc)
-:samp:`-gnatx`
+:switch:`-gnatx`
Normally the compiler generates full cross-referencing information in
the :file:`ALI` file. This information is used by a number of tools,
- including `gnatfind` and `gnatxref`. The *-gnatx* switch
+ including ``gnatfind`` and ``gnatxref``. The :switch:`-gnatx` switch
suppresses this information. This saves some space and may slightly
speed up compilation, but means that these tools cannot be used.
--------------------------
GNAT uses two methods for handling exceptions at run-time. The
-`setjmp/longjmp` method saves the context when entering
+``setjmp/longjmp`` method saves the context when entering
a frame with an exception handler. Then when an exception is
raised, the context can be restored immediately, without the
need for tracing stack frames. This method provides very fast
exception handlers if no exception is raised. Note that in this
mode and in the context of mixed Ada and C/C++ programming,
to propagate an exception through a C/C++ code, the C/C++ code
-must be compiled with the *-funwind-tables* GCC's
+must be compiled with the :switch:`-funwind-tables` GCC's
option.
The following switches may be used to control which of the
.. index:: --RTS=sjlj (gnatmake)
-:samp:`--RTS=sjlj`
+:switch:`--RTS=sjlj`
This switch causes the setjmp/longjmp run-time (when available) to be used
for exception handling. If the default
mechanism for the target is zero cost exceptions, then
.. index:: --RTS=zcx (gnatmake)
.. index:: Zero Cost Exceptions
-:samp:`--RTS=zcx`
+:switch:`--RTS=zcx`
This switch causes the zero cost approach to be used
for exception handling. If this is the default mechanism for the
target (see below), then this switch is unneeded. If the default
This option can only be used if the zero cost approach
is available for the target in use, otherwise it will generate an error.
-The same option *--RTS* must be used both for *gcc*
-and *gnatbind*. Passing this option to *gnatmake*
+The same option :switch:`--RTS` must be used both for ``gcc``
+and ``gnatbind``. Passing this option to ``gnatmake``
(:ref:`Switches_for_gnatmake`) will ensure the required consistency
through the compilation and binding steps.
.. index:: -gnatem (gcc)
-:samp:`-gnatem={path}`
+:switch:`-gnatem={path}`
A mapping file is a way to communicate to the compiler two mappings:
from unit names to file names (without any directory information) and from
file names to path names (with full directory information). These mappings
compiler, but mapping files can improve efficiency, particularly when
sources are read over a slow network connection. In normal operation,
you need not be concerned with the format or use of mapping files,
- and the *-gnatem* switch is not a switch that you would use
+ and the :switch:`-gnatem` switch is not a switch that you would use
explicitly. It is intended primarily for use by automatic tools such as
- *gnatmake* running under the project file facility. The
+ ``gnatmake`` running under the project file facility. The
description here of the format of mapping files is provided
for completeness and for possible use by other tools.
A mapping file is a sequence of sets of three lines. In each set, the
- first line is the unit name, in lower case, with `%s` appended
- for specs and `%b` appended for bodies; the second line is the
+ first line is the unit name, in lower case, with ``%s`` appended
+ for specs and ``%b`` appended for bodies; the second line is the
file name; and the third line is the path name.
Example::
/gnat/project1/sources/main.2.ada
- When the switch *-gnatem* is specified, the compiler will
+ When the switch :switch:`-gnatem` is specified, the compiler will
create in memory the two mappings from the specified file. If there is
any problem (nonexistent file, truncated file or duplicate entries),
no mapping will be created.
- Several *-gnatem* switches may be specified; however, only the
+ Several :switch:`-gnatem` switches may be specified; however, only the
last one on the command line will be taken into account.
- When using a project file, *gnatmake* creates a temporary
+ When using a project file, ``gnatmake`` creates a temporary
mapping file and communicates it to the compiler using this switch.
-----------------------
The GCC technology provides a wide range of target dependent
-:samp:`-m` switches for controlling
+:switch:`-m` switches for controlling
details of code generation with respect to different versions of
architectures. This includes variations in instruction sets (e.g.,
different members of the power pc family), and different requirements
for optimal arrangement of instructions (e.g., different members of
-the x86 family). The list of available *-m* switches may be
+the x86 family). The list of available :switch:`-m` switches may be
found in the GCC documentation.
-Use of these *-m* switches may in some cases result in improved
+Use of these :switch:`-m` switches may in some cases result in improved
code performance.
The GNAT technology is tested and qualified without any
-:samp:`-m` switches,
+:switch:`-m` switches,
so generally the most reliable approach is to avoid the use of these
switches. However, we generally expect most of these switches to work
successfully with GNAT, and many customers have reported successful
use of these options.
-Our general advice is to avoid the use of *-m* switches unless
+Our general advice is to avoid the use of :switch:`-m` switches unless
special needs lead to requirements in this area. In particular,
-there is no point in using *-m* switches to improve performance
+there is no point in using :switch:`-m` switches to improve performance
unless you actually see a performance improvement.
Linker Switches
===============
-Linker switches can be specified after :samp:`-largs` builder switch.
+Linker switches can be specified after :switch:`-largs` builder switch.
.. index:: -fuse-ld=name
-:samp:`-fuse-ld={name}`
+:switch:`-fuse-ld={name}`
Linker to be used. The default is ``bfd`` for :file:`ld.bfd`,
the alternative being ``gold`` for :file:`ld.gold`. The later is
a more recent and faster linker, but only available on GNU/Linux
.. _Binding_with_gnatbind:
-Binding with `gnatbind`
-=======================
+Binding with ``gnatbind``
+=========================
.. index:: ! gnatbind
-This chapter describes the GNAT binder, `gnatbind`, which is used
+This chapter describes the GNAT binder, ``gnatbind``, which is used
to bind compiled GNAT objects.
-Note: to invoke `gnatbind` with a project file, use the `gnat`
-driver (see :ref:`The_GNAT_Driver_and_Project_Files`).
-
-The `gnatbind` program performs four separate functions:
+The ``gnatbind`` program performs four separate functions:
* Checks that a program is consistent, in accordance with the rules in
Chapter 10 of the Ada Reference Manual. In particular, error
This program is a small Ada package (body and spec) that
must be subsequently compiled
using the GNAT compiler. The necessary compilation step is usually
- performed automatically by *gnatlink*. The two most important
+ performed automatically by ``gnatlink``. The two most important
functions of this program
are to call the elaboration routines of units in an appropriate order
and to call the main program.
* Determines the set of object files required by the given main program.
This information is output in the forms of comments in the generated program,
- to be read by the *gnatlink* utility used to link the Ada application.
+ to be read by the ``gnatlink`` utility used to link the Ada application.
.. _Running_gnatbind:
-Running `gnatbind`
-------------------
+Running ``gnatbind``
+--------------------
-The form of the `gnatbind` command is
+The form of the ``gnatbind`` command is
.. code-block:: sh
- $ gnatbind [`switches`] `mainprog`[.ali] [`switches`]
+ $ gnatbind [ switches ] mainprog[.ali] [ switches ]
where :file:`mainprog.adb` is the Ada file containing the main program
-unit body. `gnatbind` constructs an Ada
+unit body. ``gnatbind`` constructs an Ada
package in two files whose names are
:file:`b~mainprog.ads`, and :file:`b~mainprog.adb`.
For example, if given the
When doing consistency checking, the binder takes into consideration
any source files it can locate. For example, if the binder determines
-that the given main program requires the package `Pack`, whose
+that the given main program requires the package ``Pack``, whose
:file:`.ALI`
file is :file:`pack.ali` and whose corresponding source spec file is
:file:`pack.ads`, it attempts to locate the source file :file:`pack.ads`
(using the same search path conventions as previously described for the
-*gcc* command). If it can locate this source file, it checks that
+``gcc`` command). If it can locate this source file, it checks that
the time stamps
or source checksums of the source and its references to in :file:`ALI` files
match. In other words, any :file:`ALI` files that mentions this spec must have
error messages to be generated by the binder.
For example, suppose you have a main program :file:`hello.adb` and a
-package `P`, from file :file:`p.ads` and you perform the following
+package ``P``, from file :file:`p.ads` and you perform the following
steps:
-* Enter `gcc -c hello.adb` to compile the main program.
+* Enter ``gcc -c hello.adb`` to compile the main program.
-* Enter `gcc -c p.ads` to compile package `P`.
+* Enter ``gcc -c p.ads`` to compile package ``P``.
* Edit file :file:`p.ads`.
-* Enter `gnatbind hello`.
+* Enter ``gnatbind hello``.
At this point, the file :file:`p.ali` contains an out-of-date time stamp
because the file :file:`p.ads` has been edited. The attempt at binding
with the contents of this file, but for reference purposes a sample
binder output file is given in :ref:`Example_of_Binder_Output_File`.
-In most normal usage, the default mode of *gnatbind* which is to
+In most normal usage, the default mode of ``gnatbind`` which is to
generate the main package in Ada, as described in the previous section.
In particular, this means that any Ada programmer can read and understand
the generated main program. It can also be debugged just like any other
-Ada code provided the *-g* switch is used for
-*gnatbind* and *gnatlink*.
+Ada code provided the :switch:`-g` switch is used for
+``gnatbind`` and ``gnatlink``.
.. _Switches_for_gnatbind:
-Switches for *gnatbind*
------------------------
+Switches for ``gnatbind``
+-------------------------
-The following switches are available with `gnatbind`; details will
+The following switches are available with ``gnatbind``; details will
be presented in subsequent sections.
.. index:: --version (gnatbind)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatbind)
-:samp:`--help`
- If *--version* was not used, display usage, then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatbind)
-:samp:`-a`
+:switch:`-a`
Indicates that, if supported by the platform, the adainit procedure should
be treated as an initialisation routine by the linker (a constructor). This
is intended to be used by the Project Manager to automatically initialize
.. index:: -aO (gnatbind)
-:samp:`-aO`
+:switch:`-aO`
Specify directory to be searched for ALI files.
.. index:: -aI (gnatbind)
-:samp:`-aI`
+:switch:`-aI`
Specify directory to be searched for source file.
.. index:: -A (gnatbind)
-:samp:`-A[={filename}]`
+:switch:`-A[={filename}]`
Output ALI list (to standard output or to the named file).
.. index:: -b (gnatbind)
-:samp:`-b`
+:switch:`-b`
Generate brief messages to :file:`stderr` even if verbose mode set.
.. index:: -c (gnatbind)
-:samp:`-c`
+:switch:`-c`
Check only, no generation of binder output file.
.. index:: -dnn[k|m] (gnatbind)
-:samp:`-d{nn}[k|m]`
+:switch:`-d{nn}[k|m]`
This switch can be used to change the default task stack size value
- to a specified size `nn`, which is expressed in bytes by default, or
- in kilobytes when suffixed with `k` or in megabytes when suffixed
- with `m`.
+ to a specified size ``nn``, which is expressed in bytes by default, or
+ in kilobytes when suffixed with ``k`` or in megabytes when suffixed
+ with ``m``.
In the absence of a :samp:`[k|m]` suffix, this switch is equivalent,
in effect, to completing all task specs with
.. index:: -D (gnatbind)
-:samp:`-D{nn}[k|m]`
+:switch:`-D{nn}[k|m]`
This switch can be used to change the default secondary stack size value
- to a specified size `nn`, which is expressed in bytes by default, or
- in kilobytes when suffixed with `k` or in megabytes when suffixed
- with `m`.
+ to a specified size ``nn``, which is expressed in bytes by default, or
+ in kilobytes when suffixed with ``k`` or in megabytes when suffixed
+ with ``m``.
The secondary stack is used to deal with functions that return a variable
sized result, for example a function returning an unconstrained
and the actual size needed for the current allocation request).
For certain targets, notably VxWorks 653 and bare board targets,
- the secondary stack is allocated by carving off a chunk of the primary task
+ the secondary stack is allocated by carving off a chunk of the primary task
stack. By default this is a fixed percentage of the primary task stack as
- defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per
+ defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per
task using the Secondary_Stack_Size pragma/aspect. The -D option is used to
define the size of the environment task's secondary stack.
.. index:: -e (gnatbind)
-:samp:`-e`
+:switch:`-e`
Output complete list of elaboration-order dependencies.
.. index:: -Ea (gnatbind)
-:samp:`-Ea`
+:switch:`-Ea`
Store tracebacks in exception occurrences when the target supports it.
The "a" is for "address"; tracebacks will contain hexadecimal addresses,
unless symbolic tracebacks are enabled.
- See also the packages `GNAT.Traceback` and
- `GNAT.Traceback.Symbolic` for more information.
- Note that on x86 ports, you must not use *-fomit-frame-pointer*
- *gcc* option.
+ See also the packages ``GNAT.Traceback`` and
+ ``GNAT.Traceback.Symbolic`` for more information.
+ Note that on x86 ports, you must not use :switch:`-fomit-frame-pointer`
+ ``gcc`` option.
.. index:: -Es (gnatbind)
-:samp:`-Es`
+:switch:`-Es`
Store tracebacks in exception occurrences when the target supports it.
The "s" is for "symbolic"; symbolic tracebacks are enabled.
.. index:: -E (gnatbind)
-:samp:`-E`
- Currently the same as `-Ea`.
+:switch:`-E`
+ Currently the same as ``-Ea``.
.. index:: -f (gnatbind)
-:samp:`-f{elab-order}`
+:switch:`-f{elab-order}`
Force elaboration order.
.. index:: -F (gnatbind)
-:samp:`-F`
- Force the checks of elaboration flags. *gnatbind* does not normally
+:switch:`-F`
+ Force the checks of elaboration flags. ``gnatbind`` does not normally
generate checks of elaboration flags for the main executable, except when
a Stand-Alone Library is used. However, there are cases when this cannot be
detected by gnatbind. An example is importing an interface of a Stand-Alone
.. index:: -h (gnatbind)
-:samp:`-h`
+:switch:`-h`
Output usage (help) information.
.. index:: -H32 (gnatbind)
-:samp:`-H32`
- Use 32-bit allocations for `__gnat_malloc` (and thus for access types).
+:switch:`-H32`
+ Use 32-bit allocations for ``__gnat_malloc`` (and thus for access types).
For further details see :ref:`Dynamic_Allocation_Control`.
.. index:: -H64 (gnatbind)
.. index:: __gnat_malloc
-:samp:`-H64`
- Use 64-bit allocations for `__gnat_malloc` (and thus for access types).
+:switch:`-H64`
+ Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types).
For further details see :ref:`Dynamic_Allocation_Control`.
.. index:: -I (gnatbind)
-:samp:`-I`
+:switch:`-I`
Specify directory to be searched for source and ALI files.
.. index:: -I- (gnatbind)
-:samp:`-I-`
- Do not look for sources in the current directory where `gnatbind` was
+:switch:`-I-`
+ Do not look for sources in the current directory where ``gnatbind`` was
invoked, and do not look for ALI files in the directory containing the
- ALI file named in the `gnatbind` command line.
+ ALI file named in the ``gnatbind`` command line.
.. index:: -l (gnatbind)
-:samp:`-l`
+:switch:`-l`
Output chosen elaboration order.
.. index:: -L (gnatbind)
-:samp:`-L{xxx}`
- Bind the units for library building. In this case the adainit and
- adafinal procedures (:ref:`Binding_with_Non-Ada_Main_Programs`)
- are renamed to `xxx`init and
- `xxx`final.
+:switch:`-L{xxx}`
+ Bind the units for library building. In this case the ``adainit`` and
+ ``adafinal`` procedures (:ref:`Binding_with_Non-Ada_Main_Programs`)
+ are renamed to :samp:`{xxx}init` and
+ :samp:`{xxx}final`.
Implies -n.
(:ref:`GNAT_and_Libraries`, for more details.)
.. index:: -M (gnatbind)
-:samp:`-M{xyz}`
+:switch:`-M{xyz}`
Rename generated main program from main to xyz. This option is
supported on cross environments only.
.. index:: -m (gnatbind)
-:samp:`-m{n}`
- Limit number of detected errors or warnings to `n`, where `n` is
+:switch:`-m{n}`
+ Limit number of detected errors or warnings to ``n``, where ``n`` is
in the range 1..999999. The default value if no switch is
given is 9999. If the number of warnings reaches this limit, then a
message is output and further warnings are suppressed, the bind
.. index:: -n (gnatbind)
-:samp:`-n`
+:switch:`-n`
No main program.
.. index:: -nostdinc (gnatbind)
-:samp:`-nostdinc`
+:switch:`-nostdinc`
Do not look for sources in the system default directory.
.. index:: -nostdlib (gnatbind)
-:samp:`-nostdlib`
+:switch:`-nostdlib`
Do not look for library files in the system default directory.
.. index:: --RTS (gnatbind)
-:samp:`--RTS={rts-path}`
+:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -o (gnatbind)
-:samp:`-o {file}`
- Name the output file `file` (default is :file:`b~`xxx`.adb`).
+:switch:`-o {file}`
+ Name the output file ``file`` (default is :file:`b~`xxx`.adb`).
Note that if this option is used, then linking must be done manually,
gnatlink cannot be used.
.. index:: -O (gnatbind)
-:samp:`-O[={filename}]`
+:switch:`-O[={filename}]`
Output object list (to standard output or to the named file).
.. index:: -p (gnatbind)
-:samp:`-p`
+:switch:`-p`
Pessimistic (worst-case) elaboration order.
.. index:: -P (gnatbind)
-:samp:`-P`
+:switch:`-P`
Generate binder file suitable for CodePeer.
.. index:: -R (gnatbind)
-:samp:`-R`
+:switch:`-R`
Output closure source list, which includes all non-run-time units that are
included in the bind.
.. index:: -Ra (gnatbind)
-:samp:`-Ra`
- Like *-R* but the list includes run-time units.
+:switch:`-Ra`
+ Like :switch:`-R` but the list includes run-time units.
.. index:: -s (gnatbind)
-:samp:`-s`
+:switch:`-s`
Require all source files to be present.
.. index:: -S (gnatbind)
-:samp:`-S{xxx}`
+:switch:`-S{xxx}`
Specifies the value to be used when detecting uninitialized scalar
objects with pragma Initialize_Scalars.
- The `xxx` string specified with the switch is one of:
+ The ``xxx`` string specified with the switch is one of:
* ``in`` for an invalid value.
one bits. For floating-point, a large value is set
(see body of package System.Scalar_Values for exact values).
- * `xx` for hex value (two hex digits).
+ * ``xx`` for hex value (two hex digits).
The underlying scalar is set to a value consisting of repeated bytes, whose
value corresponds to the given value. For example if ``BF`` is given,
.. index:: GNAT_INIT_SCALARS
- In addition, you can specify *-Sev* to indicate that the value is
+ In addition, you can specify :switch:`-Sev` to indicate that the value is
to be set at run time. In this case, the program will look for an environment
- variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where `yy` is one
- of *in/lo/hi/`xx*` with the same meanings as above.
+ variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where ``yy`` is one
+ of :samp:`in/lo/hi/{xx}` with the same meanings as above.
If no environment variable is found, or if it does not have a valid value,
- then the default is *in* (invalid values).
+ then the default is ``in`` (invalid values).
.. index:: -static (gnatbind)
-:samp:`-static`
+:switch:`-static`
Link against a static GNAT run time.
.. index:: -shared (gnatbind)
-:samp:`-shared`
+:switch:`-shared`
Link against a shared GNAT run time when available.
.. index:: -t (gnatbind)
-:samp:`-t`
+:switch:`-t`
Tolerate time stamp and other consistency errors.
.. index:: -T (gnatbind)
-:samp:`-T{n}`
- Set the time slice value to `n` milliseconds. If the system supports
+:switch:`-T{n}`
+ Set the time slice value to ``n`` milliseconds. If the system supports
the specification of a specific time slice value, then the indicated value
is used. If the system does not support specific time slice values, but
does support some general notion of round-robin scheduling, then any
slicing, and in addition, indicates to the tasking run time that the
semantics should match as closely as possible the Annex D
requirements of the Ada RM, and in particular sets the default
- scheduling policy to `FIFO_Within_Priorities`.
+ scheduling policy to ``FIFO_Within_Priorities``.
.. index:: -u (gnatbind)
-:samp:`-u{n}`
- Enable dynamic stack usage, with `n` results stored and displayed
+:switch:`-u{n}`
+ Enable dynamic stack usage, with ``n`` results stored and displayed
at program termination. A result is generated when a task
terminates. Results that can't be stored are displayed on the fly, at
task termination. This option is currently not supported on Itanium
.. index:: -v (gnatbind)
-:samp:`-v`
+:switch:`-v`
Verbose mode. Write error messages, header, summary output to
:file:`stdout`.
.. index:: -V (gnatbind)
-:samp:`-V{key}={value}`
- Store the given association of `key` to `value` in the bind environment.
+:switch:`-V{key}={value}`
+ Store the given association of ``key`` to ``value`` in the bind environment.
Values stored this way can be retrieved at run time using
- `GNAT.Bind_Environment`.
+ ``GNAT.Bind_Environment``.
.. index:: -w (gnatbind)
-:samp:`-w{x}`
- Warning mode; `x` = s/e for suppress/treat as error.
+:switch:`-w{x}`
+ Warning mode; ``x`` = s/e for suppress/treat as error.
.. index:: -Wx (gnatbind)
-:samp:`-Wx{e}`
+:switch:`-Wx{e}`
Override default wide character encoding for standard Text_IO files.
.. index:: -x (gnatbind)
-:samp:`-x`
+:switch:`-x`
Exclude source files (check object consistency only).
.. index:: -Xnnn (gnatbind)
-:samp:`-X{nnn}`
+:switch:`-X{nnn}`
Set default exit status value, normally 0 for POSIX compliance.
.. index:: -y (gnatbind)
-:samp:`-y`
- Enable leap seconds support in `Ada.Calendar` and its children.
+:switch:`-y`
+ Enable leap seconds support in ``Ada.Calendar`` and its children.
.. index:: -z (gnatbind)
-:samp:`-z`
+:switch:`-z`
No main subprogram.
-You may obtain this listing of switches by running `gnatbind` with
+You may obtain this listing of switches by running ``gnatbind`` with
no arguments.
Consistency-Checking Modes
^^^^^^^^^^^^^^^^^^^^^^^^^^
-As described earlier, by default `gnatbind` checks
+As described earlier, by default ``gnatbind`` checks
that object files are consistent with one another and are consistent
with any source files it can locate. The following switches control binder
access to sources.
.. index:: -s (gnatbind)
-:samp:`-s`
+:switch:`-s`
Require source files to be present. In this mode, the binder must be
able to locate all source files that are referenced, in order to check
their consistency. In normal mode, if a source file cannot be located it
.. index:: -Wx (gnatbind)
-:samp:`-Wx{e}`
+:switch:`-Wx{e}`
Override default wide character encoding for standard Text_IO files.
Normally the default wide character encoding method used for standard
[Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for
the main source input (see description of switch
- *-gnatWx* for the compiler). The
+ :switch:`-gnatWx` for the compiler). The
use of this switch for the binder (which has the same set of
possible arguments) overrides this default as specified.
.. index:: -x (gnatbind)
-:samp:`-x`
+:switch:`-x`
Exclude source files. In this mode, the binder only checks that ALI
files are consistent with one another. Source files are not accessed.
The binder runs faster in this mode, and there is still a guarantee that
If a source file has been edited since it was last compiled, and you
specify this switch, the binder will not detect that the object
file is out of date with respect to the source file. Note that this is the
- mode that is automatically used by *gnatmake* because in this
+ mode that is automatically used by ``gnatmake`` because in this
case the checking against sources has already been performed by
- *gnatmake* in the course of compilation (i.e., before binding).
+ ``gnatmake`` in the course of compilation (i.e., before binding).
.. _Binder_Error_Message_Control:
.. index:: -v (gnatbind)
-:samp:`-v`
+:switch:`-v`
Verbose mode. In the normal mode, brief error messages are generated to
:file:`stderr`. If this switch is present, a header is written
to :file:`stdout` and any error messages are directed to :file:`stdout`.
.. index:: -b (gnatbind)
-:samp:`-b`
+:switch:`-b`
Generate brief error messages to :file:`stderr` even if verbose mode is
specified. This is relevant only when used with the
- *-v* switch.
+ :switch:`-v` switch.
.. index:: -m (gnatbind)
-:samp:`-m{n}`
- Limits the number of error messages to `n`, a decimal integer in the
+:switch:`-m{n}`
+ Limits the number of error messages to ``n``, a decimal integer in the
range 1-999. The binder terminates immediately if this limit is reached.
.. index:: -M (gnatbind)
-:samp:`-M{xxx}`
- Renames the generated main program from `main` to `xxx`.
+:switch:`-M{xxx}`
+ Renames the generated main program from ``main`` to ``xxx``.
This is useful in the case of some cross-building environments, where
the actual main program is separate from the one generated
- by `gnatbind`.
+ by ``gnatbind``.
.. index:: -ws (gnatbind)
.. index:: Warnings
-:samp:`-ws`
+:switch:`-ws`
Suppress all warning messages.
.. index:: -we (gnatbind)
-:samp:`-we`
+:switch:`-we`
Treat any warning messages as fatal errors.
.. index:: Binder consistency checks
.. index:: Consistency checks, in binder
-:samp:`-t`
+:switch:`-t`
The binder performs a number of consistency checks including:
* Check that checksums of a given source unit are consistent
- * Check that consistent versions of `GNAT` were used for compilation
+ * Check that consistent versions of ``GNAT`` were used for compilation
* Check consistency of configuration pragmas as required
generated which abort the binder and prevent the output of a binder
file and subsequent link to obtain an executable.
- The *-t* switch converts these error messages
+ The :switch:`-t` switch converts these error messages
into warnings, so that
binding and linking can continue to completion even in the presence of such
errors. The result may be a failed link (due to missing symbols), or a
.. note::
- This means that *-t* should be used only in unusual situations,
+ This means that :switch:`-t` should be used only in unusual situations,
with extreme care.
.. _Elaboration_Control:
.. index:: -f (gnatbind)
-:samp:`-f{elab-order}`
+:switch:`-f{elab-order}`
Force elaboration order.
- `elab-order` should be the name of a "forced elaboration order file", that
+ ``elab-order`` should be the name of a "forced elaboration order file", that
is, a text file containing library item names, one per line. A name of the
form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
name of the form "some.unit%b" or "some.unit (body)" denotes the body of
dependences are already required by Ada rules, so this file is really just
forcing the body of This to be elaborated before the spec of That.
- The given order must be consistent with Ada rules, or else `gnatbind` will
+ The given order must be consistent with Ada rules, or else ``gnatbind`` will
give elaboration cycle errors. For example, if you say x (body) should be
elaborated before x (spec), there will be a cycle, because Ada rules require
x (spec) to be elaborated before x (body); you can't have the spec and body
.. index:: -p (gnatbind)
-:samp:`-p`
+:switch:`-p`
Normally the binder attempts to choose an elaboration order that is
likely to minimize the likelihood of an elaboration order error resulting
- in raising a `Program_Error` exception. This switch reverses the
+ in raising a ``Program_Error`` exception. This switch reverses the
action of the binder, and requests that it deliberately choose an order
that is likely to maximize the likelihood of an elaboration error.
This is useful in ensuring portability and avoiding dependence on
accidental fortuitous elaboration ordering.
- Normally it only makes sense to use the *-p*
+ Normally it only makes sense to use the :switch:`-p`
switch if dynamic
- elaboration checking is used (*-gnatE* switch used for compilation).
+ elaboration checking is used (:switch:`-gnatE` switch used for compilation).
This is because in the default static elaboration mode, all necessary
- `Elaborate` and `Elaborate_All` pragmas are implicitly inserted.
+ ``Elaborate`` and ``Elaborate_All`` pragmas are implicitly inserted.
These implicit pragmas are still respected by the binder in
- *-p* mode, so a
+ :switch:`-p` mode, so a
safe elaboration order is assured.
- Note that *-p* is not intended for
+ Note that :switch:`-p` is not intended for
production use; it is more for debugging/experimental use.
.. _Output_Control:
.. index:: -c (gnatbind)
-:samp:`-c`
+:switch:`-c`
Check only. Do not generate the binder output file. In this mode the
binder performs all error checks but does not generate an output file.
.. index:: -e (gnatbind)
-:samp:`-e`
+:switch:`-e`
Output complete list of elaboration-order dependencies, showing the
reason for each dependency. This output can be rather extensive but may
be useful in diagnosing problems with elaboration order. The output is
.. index:: -h (gnatbind)
-:samp:`-h`
+:switch:`-h`
Output usage information. The output is written to :file:`stdout`.
.. index:: -K (gnatbind)
-:samp:`-K`
+:switch:`-K`
Output linker options to :file:`stdout`. Includes library search paths,
contents of pragmas Ident and Linker_Options, and libraries added
- by `gnatbind`.
+ by ``gnatbind``.
.. index:: -l (gnatbind)
-:samp:`-l`
+:switch:`-l`
Output chosen elaboration order. The output is written to :file:`stdout`.
.. index:: -O (gnatbind)
-:samp:`-O`
+:switch:`-O`
Output full names of all the object files that must be linked to provide
the Ada component of the program. The output is written to :file:`stdout`.
This list includes the files explicitly supplied and referenced by the user
.. index:: -o (gnatbind)
-:samp:`-o {file}`
- Set name of output file to `file` instead of the normal
- :file:`b~`mainprog`.adb` default. Note that `file` denote the Ada
+:switch:`-o {file}`
+ Set name of output file to ``file`` instead of the normal
+ :file:`b~`mainprog`.adb` default. Note that ``file`` denote the Ada
binder generated body filename.
Note that if this option is used, then linking must be done manually.
It is not possible to use gnatlink in this case, since it cannot locate
.. index:: -r (gnatbind)
-:samp:`-r`
- Generate list of `pragma Restrictions` that could be applied to
+:switch:`-r`
+ Generate list of ``pragma Restrictions`` that could be applied to
the current unit. This is useful for code audit purposes, and also may
be used to improve code generation in some cases.
Dynamic Allocation Control
^^^^^^^^^^^^^^^^^^^^^^^^^^
-The heap control switches -- *-H32* and *-H64* --
+The heap control switches -- :switch:`-H32` and :switch:`-H64` --
determine whether dynamic allocation uses 32-bit or 64-bit memory.
-They only affect compiler-generated allocations via `__gnat_malloc`;
-explicit calls to `malloc` and related functions from the C
+They only affect compiler-generated allocations via ``__gnat_malloc``;
+explicit calls to ``malloc`` and related functions from the C
run-time library are unaffected.
-:samp:`-H32`
+:switch:`-H32`
Allocate memory on 32-bit heap
-:samp:`-H64`
+:switch:`-H64`
Allocate memory on 64-bit heap. This is the default
- unless explicitly overridden by a `'Size` clause on the access type.
+ unless explicitly overridden by a ``'Size`` clause on the access type.
These switches are only effective on VMS platforms.
The description so far has assumed that the main
program is in Ada, and that the task of the binder is to generate a
-corresponding function `main` that invokes this Ada main
+corresponding function ``main`` that invokes this Ada main
program. GNAT also supports the building of executable programs where
the main program is not in Ada, but some of the called routines are
written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`).
.. index:: -n (gnatbind)
-:samp:`-n`
+:switch:`-n`
No main program. The main program is not in Ada.
In this case, most of the functions of the binder are still required,
.. index:: adainit
- *adainit*
+ ``adainit``
You must call this routine to initialize the Ada part of the program by
- calling the necessary elaboration routines. A call to `adainit` is
+ calling the necessary elaboration routines. A call to ``adainit`` is
required before the first call to an Ada subprogram.
Note that it is assumed that the basic execution environment must be setup
.. index:: adafinal
- *adafinal*
+ ``adafinal``
You must call this routine to perform any library-level finalization
- required by the Ada subprograms. A call to `adafinal` is required
+ required by the Ada subprograms. A call to ``adafinal`` is required
after the last call to an Ada subprogram, and before the program
terminates.
.. index:: -n (gnatbind)
.. index:: Binder, multiple input files
-If the *-n* switch
+If the :switch:`-n` switch
is given, more than one ALI file may appear on
-the command line for `gnatbind`. The normal *closure*
+the command line for ``gnatbind``. The normal ``closure``
calculation is performed for each of the specified units. Calculating
the closure means finding out the set of units involved by tracing
|with| references. The reason it is necessary to be able to
more quite separate groups of Ada units.
The binder takes the name of its output file from the last specified ALI
-file, unless overridden by the use of the *-o file*.
+file, unless overridden by the use of the :switch:`-o file`.
.. index:: -o (gnatbind)
The output is an Ada unit in source form that can be compiled with GNAT.
-This compilation occurs automatically as part of the *gnatlink*
+This compilation occurs automatically as part of the ``gnatlink``
processing.
Currently the GNAT run time requires a FPU using 80 bits mode
.. index:: -z (gnatbind)
-:samp:`-z`
+:switch:`-z`
Normally the binder checks that the unit name given on the command line
corresponds to a suitable main subprogram. When this switch is used,
a list of ALI files can be given, and the execution of the program
that the default wide character encoding method for standard Text_IO
files is always set to Brackets if this switch is set (you can use
the binder switch
- *-Wx* to override this default).
+ :switch:`-Wx` to override this default).
.. _Command-Line_Access:
Command-Line Access
-------------------
-The package `Ada.Command_Line` provides access to the command-line
+The package ``Ada.Command_Line`` provides access to the command-line
arguments and program name. In order for this interface to operate
correctly, the two variables
.. index:: gnat_argc
are declared in one of the GNAT library routines. These variables must
-be set from the actual `argc` and `argv` values passed to the
-main program. With no *n* present, `gnatbind`
+be set from the actual ``argc`` and ``argv`` values passed to the
+main program. With no *n* present, ``gnatbind``
generates the C main program to automatically set these variables.
If the *n* switch is used, there is no automatic way to
set these variables. If they are not set, the procedures in
-`Ada.Command_Line` will not be available, and any attempt to use
-them will raise `Constraint_Error`. If command line access is
-required, your main program must set `gnat_argc` and
-`gnat_argv` from the `argc` and `argv` values passed to
+``Ada.Command_Line`` will not be available, and any attempt to use
+them will raise ``Constraint_Error``. If command line access is
+required, your main program must set ``gnat_argc`` and
+``gnat_argv`` from the ``argc`` and ``argv`` values passed to
it.
.. _Search_Paths_for_gnatbind:
-Search Paths for `gnatbind`
----------------------------
+Search Paths for ``gnatbind``
+-----------------------------
The binder takes the name of an ALI file as its argument and needs to
locate source files as well as other ALI files to verify object consistency.
-For source files, it follows exactly the same search rules as *gcc*
+For source files, it follows exactly the same search rules as ``gcc``
(see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the
directories searched are:
* The directory containing the ALI file named in the command line, unless
- the switch *-I-* is specified.
+ the switch :switch:`-I-` is specified.
-* All directories specified by *-I*
- switches on the `gnatbind`
+* All directories specified by :switch:`-I`
+ switches on the ``gnatbind``
command line, in the order given.
.. index:: ADA_PRJ_OBJECTS_FILE
* The content of the :file:`ada_object_path` file which is part of the GNAT
installation tree and is used to store standard libraries such as the
- GNAT Run Time Library (RTL) unless the switch *-nostdlib* is
+ GNAT Run Time Library (RTL) unless the switch :switch:`-nostdlib` is
specified. See :ref:`Installing_a_library`
.. index:: -I (gnatbind)
.. index:: -aI (gnatbind)
.. index:: -aO (gnatbind)
-In the binder the switch *-I*
+In the binder the switch :switch:`-I`
is used to specify both source and
-library file paths. Use *-aI*
+library file paths. Use :switch:`-aI`
instead if you want to specify
-source paths only, and *-aO*
+source paths only, and :switch:`-aO`
if you want to specify library paths
only. This means that for the binder
-:samp:`-I{dir}` is equivalent to
-:samp:`-aI{dir}`
-:samp:`-aO`{dir}`.
+:switch:`-I{dir}` is equivalent to
+:switch:`-aI{dir}`
+:switch:`-aO`{dir}`.
The binder generates the bind file (a C language source file) in the
current working directory.
.. index:: Interfaces
.. index:: GNAT
-The packages `Ada`, `System`, and `Interfaces` and their
+The packages ``Ada``, ``System``, and ``Interfaces`` and their
children make up the GNAT Run-Time Library, together with the package
GNAT and its children, which contain a set of useful additional
library functions provided by GNAT. The sources for these units are
.. _Examples_of_gnatbind_Usage:
-Examples of `gnatbind` Usage
-----------------------------
+Examples of ``gnatbind`` Usage
+------------------------------
-Here are some examples of `gnatbind` invovations:
+Here are some examples of ``gnatbind`` invovations:
::
gnatbind hello
- The main program `Hello` (source program in :file:`hello.adb`) is
+ The main program ``Hello`` (source program in :file:`hello.adb`) is
bound using the standard switch settings. The generated main program is
:file:`b~hello.adb`. This is the normal, default use of the binder.
gnatbind hello -o mainprog.adb
- The main program `Hello` (source program in :file:`hello.adb`) is
+ The main program ``Hello`` (source program in :file:`hello.adb`) is
bound using the standard switch settings. The generated main program is
:file:`mainprog.adb` with the associated spec in
:file:`mainprog.ads`. Note that you must specify the body here not the
.. _Linking_with_gnatlink:
-Linking with *gnatlink*
-=======================
+Linking with ``gnatlink``
+=========================
.. index:: ! gnatlink
-This chapter discusses *gnatlink*, a tool that links
+This chapter discusses ``gnatlink``, a tool that links
an Ada program and builds an executable file. This utility
-invokes the system linker (via the *gcc* command)
+invokes the system linker (via the ``gcc`` command)
with a correct list of object files and library references.
-*gnatlink* automatically determines the list of files and
+``gnatlink`` automatically determines the list of files and
references for the Ada part of a program. It uses the binder file
-generated by the *gnatbind* to determine this list.
+generated by the ``gnatbind`` to determine this list.
Note: to invoke `gnatlink` with a project file, use the `gnat`
driver (see :ref:`The_GNAT_Driver_and_Project_Files`).
.. _Running_gnatlink:
-Running *gnatlink*
-------------------
+Running ``gnatlink``
+--------------------
-The form of the *gnatlink* command is
+The form of the ``gnatlink`` command is
.. code-block:: sh
- $ gnatlink [`switches`] `mainprog`[.ali]
- [`non-Ada objects`] [`linker options`]
+ $ gnatlink [ switches ] mainprog [.ali]
+ [ non-Ada objects ] [ linker options ]
-The arguments of *gnatlink* (switches, main :file:`ALI` file,
+The arguments of ``gnatlink`` (switches, main ``ALI`` file,
non-Ada objects
or linker options) may be in any order, provided that no non-Ada object may
be mistaken for a main :file:`ALI` file.
:file:`mainprog.ali` references the ALI file of the main program.
The :file:`.ali` extension of this file can be omitted. From this
-reference, *gnatlink* locates the corresponding binder file
+reference, ``gnatlink`` locates the corresponding binder file
:file:`b~mainprog.adb` and, using the information in this file along
with the list of non-Ada objects and linker options, constructs a
linker command file to create the executable.
-The arguments other than the *gnatlink* switches and the main
+The arguments other than the ``gnatlink`` switches and the main
:file:`ALI` file are passed to the linker uninterpreted.
They typically include the names of
object files for units written in other languages than Ada and any library
references required to resolve references in any of these foreign language
-units, or in `Import` pragmas in any Ada units.
+units, or in ``Import`` pragmas in any Ada units.
-`linker options` is an optional list of linker specific
+``linker options`` is an optional list of linker specific
switches.
-The default linker called by gnatlink is *gcc* which in
+The default linker called by gnatlink is ``gcc`` which in
turn calls the appropriate system linker.
-One useful option for the linker is *-s*: it reduces the size of the
+One useful option for the linker is :switch:`-s`: it reduces the size of the
executable by removing all symbol table and relocation information from the
executable.
-Standard options for the linker such as *-lmy_lib* or
-*-Ldir* can be added as is.
+Standard options for the linker such as :switch:`-lmy_lib` or
+:switch:`-Ldir` can be added as is.
For options that are not recognized by
-*gcc* as linker options, use the *gcc* switches
-*-Xlinker* or *-Wl,*.
+``gcc`` as linker options, use the ``gcc`` switches
+:switch:`-Xlinker` or :switch:`-Wl,`.
Refer to the GCC documentation for
details.
$ gnatlink my_prog -Wl,-Map,MAPFILE
-Using `linker options` it is possible to set the program stack and
+Using ``linker options`` it is possible to set the program stack and
heap size.
See :ref:`Setting_Stack_Size_from_gnatlink` and
:ref:`Setting_Heap_Size_from_gnatlink`.
-*gnatlink* determines the list of objects required by the Ada
+``gnatlink`` determines the list of objects required by the Ada
program and prepends them to the list of objects passed to the linker.
-*gnatlink* also gathers any arguments set by the use of
-`pragma Linker_Options` and adds them to the list of arguments
+``gnatlink`` also gathers any arguments set by the use of
+``pragma Linker_Options`` and adds them to the list of arguments
presented to the linker.
.. _Switches_for_gnatlink:
-Switches for *gnatlink*
------------------------
+Switches for ``gnatlink``
+-------------------------
-The following switches are available with the *gnatlink* utility:
+The following switches are available with the ``gnatlink`` utility:
.. index:: --version (gnatlink)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatlink)
-:samp:`--help`
- If *--version* was not used, display usage, then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: Command line length
.. index:: -f (gnatlink)
-:samp:`-f`
- On some targets, the command line length is limited, and *gnatlink*
+:switch:`-f`
+ On some targets, the command line length is limited, and ``gnatlink``
will generate a separate file for the linker if the list of object files
is too long.
- The *-f* switch forces this file
+ The :switch:`-f` switch forces this file
to be generated even if
the limit is not exceeded. This is useful in some cases to deal with
special situations where the command line length is exceeded.
.. index:: Debugging information, including
.. index:: -g (gnatlink)
-:samp:`-g`
+:switch:`-g`
The option to include debugging information causes the Ada bind file (in
- other words, :file:`b~mainprog.adb`) to be compiled with *-g*.
+ other words, :file:`b~mainprog.adb`) to be compiled with :switch:`-g`.
In addition, the binder does not delete the :file:`b~mainprog.adb`,
:file:`b~mainprog.o` and :file:`b~mainprog.ali` files.
- Without *-g*, the binder removes these files by default.
+ Without :switch:`-g`, the binder removes these files by default.
.. index:: -n (gnatlink)
-:samp:`-n`
+:switch:`-n`
Do not compile the file generated by the binder. This may be used when
a link is rerun with different options, but there is no need to recompile
the binder file.
.. index:: -v (gnatlink)
-:samp:`-v`
+:switch:`-v`
Verbose mode. Causes additional information to be output, including a full
list of the included object files.
This switch option is most useful when you want
.. index:: -v -v (gnatlink)
-:samp:`-v -v`
+:switch:`-v -v`
Very verbose mode. Requests that the compiler operate in verbose mode when
it compiles the binder file, and that the system linker run in verbose mode.
.. index:: -o (gnatlink)
-:samp:`-o {exec-name}`
- `exec-name` specifies an alternate name for the generated
+:switch:`-o {exec-name}`
+ ``exec-name`` specifies an alternate name for the generated
executable program. If this switch is omitted, the executable has the same
- name as the main unit. For example, `gnatlink try.ali` creates
+ name as the main unit. For example, ``gnatlink try.ali`` creates
an executable called :file:`try`.
.. index:: -b (gnatlink)
-:samp:`-b {target}`
- Compile your program to run on `target`, which is the name of a
+:switch:`-b {target}`
+ Compile your program to run on ``target``, which is the name of a
system configuration. You must have a GNAT cross-compiler built if
- `target` is not the same as your host system.
+ ``target`` is not the same as your host system.
.. index:: -B (gnatlink)
-:samp:`-B{dir}`
- Load compiler executables (for example, `gnat1`, the Ada compiler)
- from `dir` instead of the default location. Only use this switch
+:switch:`-B{dir}`
+ Load compiler executables (for example, ``gnat1``, the Ada compiler)
+ from ``dir`` instead of the default location. Only use this switch
when multiple versions of the GNAT compiler are available.
- See the `Directory Options` section in :title:`The_GNU_Compiler_Collection`
- for further details. You would normally use the *-b* or
- *-V* switch instead.
+ See the ``Directory Options`` section in :title:`The_GNU_Compiler_Collection`
+ for further details. You would normally use the :switch:`-b` or
+ :switch:`-V` switch instead.
.. index:: -M (gnatlink)
-:samp:`-M`
+:switch:`-M`
When linking an executable, create a map file. The name of the map file
has the same name as the executable with extension ".map".
.. index:: -M= (gnatlink)
-:samp:`-M={mapfile}`
+:switch:`-M={mapfile}`
When linking an executable, create a map file. The name of the map file is
- `mapfile`.
+ ``mapfile``.
.. index:: --GCC=compiler_name (gnatlink)
-:samp:`--GCC={compiler_name}`
+:switch:`--GCC={compiler_name}`
Program used for compiling the binder file. The default is
- ``gcc``. You need to use quotes around `compiler_name` if
- `compiler_name` contains spaces or other separator characters.
- As an example ``--GCC="foo -x -y"`` will instruct *gnatlink* to
+ ``gcc``. You need to use quotes around ``compiler_name`` if
+ ``compiler_name`` contains spaces or other separator characters.
+ As an example ``--GCC="foo -x -y"`` will instruct ``gnatlink`` to
use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always
inserted after your command name. Thus in the above example the compiler
- command that will be used by *gnatlink* will be ``foo -c -x -y``.
+ command that will be used by ``gnatlink`` will be ``foo -c -x -y``.
A limitation of this syntax is that the name and path name of the executable
itself must not include any embedded spaces. If the compiler executable is
different from the default one (gcc or <prefix>-gcc), then the back-end
switches in the ALI file are not used to compile the binder generated source.
For example, this is the case with ``--GCC="foo -x -y"``. But the back end
switches will be used for ``--GCC="gcc -gnatv"``. If several
- ``--GCC=compiler_name`` are used, only the last `compiler_name`
+ ``--GCC=compiler_name`` are used, only the last ``compiler_name``
is taken into account. However, all the additional switches are also taken
into account. Thus,
``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
.. index:: --LINK= (gnatlink)
-:samp:`--LINK={name}`
- `name` is the name of the linker to be invoked. This is especially
+:switch:`--LINK={name}`
+ ``name`` is the name of the linker to be invoked. This is especially
useful in mixed language programs since languages such as C++ require
their own linker to be used. When this switch is omitted, the default
- name for the linker is *gcc*. When this switch is used, the
- specified linker is called instead of *gcc* with exactly the same
- parameters that would have been passed to *gcc* so if the desired
+ name for the linker is ``gcc``. When this switch is used, the
+ specified linker is called instead of ``gcc`` with exactly the same
+ parameters that would have been passed to ``gcc`` so if the desired
linker requires different parameters it is necessary to use a wrapper
script that massages the parameters before invoking the real linker. It
may be useful to control the exact invocation by using the verbose
.. _Using_the_GNU_make_Utility:
-Using the GNU `make` Utility
-============================
+Using the GNU ``make`` Utility
+==============================
.. index:: make (GNU), GNU make
This chapter offers some examples of makefiles that solve specific
problems. It does not explain how to write a makefile, nor does it try to replace the
-*gnatmake* utility (:ref:`The_GNAT_Make_Program_gnatmake`).
+``gnatmake`` utility (:ref:`The_GNAT_Make_Program_gnatmake`).
All the examples in this section are specific to the GNU version of
-make. Although *make* is a standard utility, and the basic language
+make. Although ``make`` is a standard utility, and the basic language
is the same, these examples use some advanced features found only in
-`GNU make`.
+``GNU make``.
.. _Using_gnatmake_in_a_Makefile:
each step of the build process.
The list of dependencies are handled automatically by
-*gnatmake*. The Makefile is simply used to call gnatmake in each of
+``gnatmake``. The Makefile is simply used to call gnatmake in each of
the appropriate directories.
Note that you should also read the example on how to automatically
The example below presents two methods. The first one, although less
general, gives you more control over the list. It involves wildcard
-characters, that are automatically expanded by *make*. Its
+characters, that are automatically expanded by ``make``. Its
shortcoming is that you need to explicitly specify some of the
organization of your project, such as for instance the directory tree
depth, whether some directories are found in a separate tree, etc.
The second method is the most general one. It requires an external
-program, called *find*, which is standard on all Unix systems. All
+program, called ``find``, which is standard on all Unix systems. All
the directories found under a given root directory will be added to the
list.
# Note that the argument(s) to wildcard below should end with a '/'.
# Since wildcards also return file names, we have to filter them out
# to avoid duplicate directory names.
- # We thus use make's `dir` and `sort` functions.
+ # We thus use make's ``dir`` and ``sort`` functions.
# It sets DIRs to the following value (note that the directories aaa and baa
# are not given, unless you change the arguments to wildcard).
# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
gnatmake the list of source and object directories.
This example shows how you can set up environment variables, which will
-make *gnatmake* behave exactly as if the directories had been
+make ``gnatmake`` behave exactly as if the directories had been
specified on the command line, but have a much higher length limit (or
even none on most systems).
Note a small trick in the Makefile below: for efficiency reasons, we
create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
-expanded immediately by `make`. This way we overcome the standard
+expanded immediately by ``make``. This way we overcome the standard
make behavior which is to expand the variables only when they are
actually used.
+.. role:: switch(samp)
+
.. |with| replace:: *with*
.. |withs| replace:: *with*\ s
.. |withed| replace:: *with*\ ed
* *Package initialization code*
- Code in a `BEGIN-END` section at the outer level of a package body is
+ Code in a ``begin`` ... `` end`` section at the outer level of a package body is
executed as part of the package body elaboration code.
* *Library level task allocators*
have is a series of elaboration code sections, potentially one section
for each unit in the program. It is important that these execute
in the correct order. Correctness here means that, taking the above
-example of the declaration of `Sqrt_Half`,
+example of the declaration of ``Sqrt_Half``,
if some other piece of
-elaboration code references `Sqrt_Half`,
+elaboration code references ``Sqrt_Half``,
then it must run after the
section of elaboration code that contains the declaration of
-`Sqrt_Half`.
+``Sqrt_Half``.
There would never be any order of elaboration problem if we made a rule
that whenever you |with| a unit, you must elaborate both the spec and body
with Unit_1;
package Unit_2 is ...
-would require that both the body and spec of `Unit_1` be elaborated
-before the spec of `Unit_2`. However, a rule like that would be far too
+would require that both the body and spec of ``Unit_1`` be elaborated
+before the spec of ``Unit_2``. However, a rule like that would be far too
restrictive. In particular, it would make it impossible to have routines
in separate packages that were mutually recursive.
but in the general case, this is not possible. Consider the following
example.
-In the body of `Unit_1`, we have a procedure `Func_1`
+In the body of ``Unit_1``, we have a procedure ``Func_1``
that references
-the variable `Sqrt_1`, which is declared in the elaboration code
-of the body of `Unit_1`:
+the variable ``Sqrt_1``, which is declared in the elaboration code
+of the body of ``Unit_1``:
.. code-block:: ada
Sqrt_1 : Float := Sqrt (0.1);
-The elaboration code of the body of `Unit_1` also contains:
+The elaboration code of the body of ``Unit_1`` also contains:
.. code-block:: ada
Q := Unit_2.Func_2;
end if;
-`Unit_2` is exactly parallel,
-it has a procedure `Func_2` that references
-the variable `Sqrt_2`, which is declared in the elaboration code of
-the body `Unit_2`:
+``Unit_2`` is exactly parallel,
+it has a procedure ``Func_2`` that references
+the variable ``Sqrt_2``, which is declared in the elaboration code of
+the body ``Unit_2``:
.. code-block:: ada
Sqrt_2 : Float := Sqrt (0.1);
-The elaboration code of the body of `Unit_2` also contains:
+The elaboration code of the body of ``Unit_2`` also contains:
.. code-block:: ada
If you carefully analyze the flow here, you will see that you cannot tell
at compile time the answer to this question.
-If `expression_1` is not equal to 1,
-and `expression_2` is not equal to 2,
+If ``expression_1`` is not equal to 1,
+and ``expression_2`` is not equal to 2,
then either order is acceptable, because neither of the function calls is
executed. If both tests evaluate to true, then neither order is acceptable
and in fact there is no correct order.
If one of the two expressions is true, and the other is false, then one
of the above orders is correct, and the other is incorrect. For example,
-if `expression_1` /= 1 and `expression_2` = 2,
-then the call to `Func_1`
-will occur, but not the call to `Func_2.`
+if ``expression_1`` /= 1 and ``expression_2`` = 2,
+then the call to ``Func_1``
+will occur, but not the call to ``Func_2.``
This means that it is essential
-to elaborate the body of `Unit_1` before
-the body of `Unit_2`, so the first
+to elaborate the body of ``Unit_1`` before
+the body of ``Unit_2``, so the first
order of elaboration is correct and the second is wrong.
-By making `expression_1` and `expression_2`
+By making ``expression_1`` and ``expression_2``
depend on input data, or perhaps
the time of day, we can make it impossible for the compiler or binder
to figure out which of these expressions will be true, and hence it
Dynamic checks are made at run time, so that if some entity is accessed
before it is elaborated (typically by means of a subprogram call)
- then the exception (`Program_Error`) is raised.
+ then the exception (``Program_Error``) is raised.
* *Elaboration control*
has been elaborated. The rules for elaboration given above guarantee
that the spec of the subprogram has been elaborated before the
call, but not the body. If this rule is violated, then the
- exception `Program_Error` is raised.
+ exception ``Program_Error`` is raised.
* *Restrictions on instantiations*
unit has been elaborated. Again, the rules for elaboration given above
guarantee that the spec of the generic unit has been elaborated
before the instantiation, but not the body. If this rule is
- violated, then the exception `Program_Error` is raised.
+ violated, then the exception ``Program_Error`` is raised.
The idea is that if the body has been elaborated, then any variables
it references must have been elaborated; by checking for the body being
A Boolean variable is associated with each subprogram
and each generic unit. This variable is initialized to False, and is set to
True at the point body is elaborated. Every call or instantiation checks the
-variable, and raises `Program_Error` if the variable is False.
+variable, and raises ``Program_Error`` if the variable is False.
Note that one might think that it would be good enough to have one Boolean
variable for each package, but that would not deal with cases of trying
to call a body in the same package as the call
that has not been elaborated yet.
Of course a compiler may be able to do enough analysis to optimize away
-some of the Boolean variables as unnecessary, and `GNAT` indeed
+some of the Boolean variables as unnecessary, and GNAT indeed
does such optimizations, but still the easiest conceptual model is to
think of there being one variable per subprogram.
=================================
In the previous section we discussed the rules in Ada which ensure
-that `Program_Error` is raised if an incorrect elaboration order is
+that ``Program_Error`` is raised if an incorrect elaboration order is
chosen. This prevents erroneous executions, but we need mechanisms to
specify a correct execution and avoid the exception altogether.
To achieve this, Ada provides a number of features for controlling
end Subp;
end Definitions;
- A package that |withs| `Definitions` may safely instantiate
- `Definitions.Subp` because the compiler can determine that there
+ A package that |withs| ``Definitions`` may safely instantiate
+ ``Definitions.Subp`` because the compiler can determine that there
definitely is no package body to worry about in this case
.. index:: pragma Pure
* *pragma Elaborate_Body*
This pragma requires that the body of a unit be elaborated immediately
- after its spec. Suppose a unit `A` has such a pragma,
- and unit `B` does
- a |with| of unit `A`. Recall that the standard rules require
- the spec of unit `A`
+ after its spec. Suppose a unit ``A`` has such a pragma,
+ and unit ``B`` does
+ a |with| of unit ``A``. Recall that the standard rules require
+ the spec of unit ``A``
to be elaborated before the |withing| unit; given the pragma in
- `A`, we also know that the body of `A`
- will be elaborated before `B`, so
- that calls to `A` are safe and do not need a check.
+ ``A``, we also know that the body of ``A``
+ will be elaborated before ``B``, so
+ that calls to ``A`` are safe and do not need a check.
- Note that, unlike pragma `Pure` and pragma `Preelaborate`,
- the use of `Elaborate_Body` does not guarantee that the program is
+ Note that, unlike pragma ``Pure`` and pragma ``Preelaborate``,
+ the use of ``Elaborate_Body`` does not guarantee that the program is
free of elaboration problems, because it may not be possible
to satisfy the requested elaboration order.
- Let's go back to the example with `Unit_1` and `Unit_2`.
- If a programmer marks `Unit_1` as `Elaborate_Body`,
- and not `Unit_2,` then the order of
+ Let's go back to the example with ``Unit_1`` and ``Unit_2``.
+ If a programmer marks ``Unit_1`` as ``Elaborate_Body``,
+ and not ``Unit_2,`` then the order of
elaboration will be::
Spec of Unit_2
Body of Unit_1
Body of Unit_2
- Now that means that the call to `Func_1` in `Unit_2`
+ Now that means that the call to ``Func_1`` in ``Unit_2``
need not be checked,
- it must be safe. But the call to `Func_2` in
- `Unit_1` may still fail if
- `Expression_1` is equal to 1,
+ it must be safe. But the call to ``Func_2`` in
+ ``Unit_1`` may still fail if
+ ``Expression_1`` is equal to 1,
and the programmer must still take
responsibility for this not being the case.
- If all units carry a pragma `Elaborate_Body`, then all problems are
+ If all units carry a pragma ``Elaborate_Body``, then all problems are
eliminated, except for calls entirely within a body, which are
in any case fully under programmer control. However, using the pragma
everywhere is not always possible.
- In particular, for our `Unit_1`/`Unit_2` example, if
- we marked both of them as having pragma `Elaborate_Body`, then
+ In particular, for our ``Unit_1``/`Unit_2` example, if
+ we marked both of them as having pragma ``Elaborate_Body``, then
clearly there would be no possible elaboration order.
The above pragmas allow a server to guarantee safe use by clients, and
clearly this is the preferable approach. Consequently a good rule
-is to mark units as `Pure` or `Preelaborate` if possible,
+is to mark units as ``Pure`` or ``Preelaborate`` if possible,
and if this is not possible,
-mark them as `Elaborate_Body` if possible.
+mark them as ``Elaborate_Body`` if possible.
As we have seen, there are situations where neither of these
three pragmas can be used.
So we also provide methods for clients to control the
Unit B |withs| unit C, and B.Func calls C.Func
- Now if we put a pragma `Elaborate (B)`
- in unit `A`, this ensures that the
- body of `B` is elaborated before the call, but not the
- body of `C`, so
- the call to `C.Func` could still cause `Program_Error` to
+ Now if we put a pragma ``Elaborate (B)``
+ in unit ``A``, this ensures that the
+ body of ``B`` is elaborated before the call, but not the
+ body of ``C``, so
+ the call to ``C.Func`` could still cause ``Program_Error`` to
be raised.
- The effect of a pragma `Elaborate_All` is stronger, it requires
+ The effect of a pragma ``Elaborate_All`` is stronger, it requires
not only that the body of the named unit be elaborated before the
unit doing the |with|, but also the bodies of all units that the
named unit uses, following |with| links transitively. For example,
- if we put a pragma `Elaborate_All (B)` in unit `A`,
- then it requires not only that the body of `B` be elaborated before `A`,
- but also the body of `C`, because `B` |withs| `C`.
+ if we put a pragma ``Elaborate_All (B)`` in unit ``A``,
+ then it requires not only that the body of ``B`` be elaborated before ``A``,
+ but also the body of ``C``, because ``B`` |withs| ``C``.
We are now in a position to give a usage rule in Ada for avoiding
elaboration problems, at least if dynamic dispatching and access to
indirectly make a call to a subprogram in a |withed| unit, or instantiate
a generic package in a |withed| unit,
then if the |withed| unit does not have
-pragma `Pure` or `Preelaborate`, then the client should have
-a pragma `Elaborate_All`for the |withed| unit.**
+pragma ``Pure`` or ``Preelaborate``, then the client should have
+a pragma ``Elaborate_All``for the |withed| unit.**
By following this rule a client is
assured that calls can be made without risk of an exception.
For generic subprogram instantiations, the rule can be relaxed to
-require only a pragma `Elaborate` since elaborating the body
+require only a pragma ``Elaborate`` since elaborating the body
of a subprogram cannot cause any transitive elaboration (we are
not calling the subprogram in this case, just elaborating its
declaration).
* *No order exists*
No order of elaboration exists which follows the rules, taking into
- account any `Elaborate`, `Elaborate_All`,
- or `Elaborate_Body` pragmas. In
+ account any ``Elaborate``, ``Elaborate_All``,
+ or ``Elaborate_Body`` pragmas. In
this case, an Ada compiler must diagnose the situation at bind
time, and refuse to build an executable program.
One or more acceptable elaboration orders exist, and all of them
generate an elaboration order problem. In this case, the binder
- can build an executable program, but `Program_Error` will be raised
+ can build an executable program, but ``Program_Error`` will be raised
when the program is run.
* *Several orders exist, some right, some incorrect*
may be true even if the rule is not followed.
Note that one additional advantage of following our rules on the use
-of `Elaborate` and `Elaborate_All`
+of ``Elaborate`` and ``Elaborate_All``
is that the program continues to stay in the ideal (all orders OK) state
even if maintenance
changes some bodies of some units. Conversely, if a program that does
may deteriorate silently as a result of maintenance changes.
You may have noticed that the above discussion did not mention
-the use of `Elaborate_Body`. This was a deliberate omission. If you
-|with| an `Elaborate_Body` unit, it still may be the case that
+the use of ``Elaborate_Body``. This was a deliberate omission. If you
+|with| an ``Elaborate_Body`` unit, it still may be the case that
code in the body makes calls to some other unit, so it is still necessary
-to use `Elaborate_All` on such units.
+to use ``Elaborate_All`` on such units.
.. _Controlling_Elaboration_in_GNAT_-_Internal_Calls:
return 1.0;
end One;
-will obviously raise `Program_Error` at run time, because function
+will obviously raise ``Program_Error`` at run time, because function
One will be called before its body is elaborated. In this case GNAT will
-generate a warning that the call will raise `Program_Error`::
+generate a warning that the call will raise ``Program_Error``::
1. procedure y is
2. function One return Float;
Note that in this particular case, it is likely that the call is safe, because
-the function `One` does not access any global variables.
+the function ``One`` does not access any global variables.
Nevertheless in Ada, we do not want the validity of the check to depend on
the contents of the body (think about the separate compilation case), so this
is still wrong, as we discussed in the previous sections.
The error is easily corrected by rearranging the declarations so that the
-body of `One` appears before the declaration containing the call
+body of ``One`` appears before the declaration containing the call
(note that in Ada 95 as well as later versions of the Ada standard,
declarations can appear in any order, so there is no restriction that
would prevent this reordering, and if we write:
Q : Float := One;
then all is well, no warning is generated, and no
-`Program_Error` exception
+``Program_Error`` exception
will be raised.
Things are more complicated when a chain of subprograms is executed:
function A return Integer is begin return 1; end;
-Now the call to `C`
-at elaboration time in the declaration of `X` is correct, because
-the body of `C` is already elaborated,
-and the call to `B` within the body of
-`C` is correct, but the call
-to `A` within the body of `B` is incorrect, because the body
-of `A` has not been elaborated, so `Program_Error`
-will be raised on the call to `A`.
+Now the call to ``C``
+at elaboration time in the declaration of ``X`` is correct, because
+the body of ``C`` is already elaborated,
+and the call to ``B`` within the body of
+``C`` is correct, but the call
+to ``A`` within the body of ``B`` is incorrect, because the body
+of ``A`` has not been elaborated, so ``Program_Error``
+will be raised on the call to ``A``.
In this case GNAT will generate a
-warning that `Program_Error` may be
+warning that ``Program_Error`` may be
raised at the point of the call. Let's look at the warning::
1. procedure x is
Note that the message here says 'may raise', instead of the direct case,
where the message says 'will be raised'. That's because whether
-`A` is
+``A`` is
actually called depends in general on run-time flow of control.
-For example, if the body of `B` said
+For example, if the body of ``B`` said
.. code-block:: ada
end B;
then we could not know until run time whether the incorrect call to A would
-actually occur, so `Program_Error` might
+actually occur, so ``Program_Error`` might
or might not be raised. It is possible for a compiler to
do a better job of analyzing bodies, to
-determine whether or not `Program_Error`
+determine whether or not ``Program_Error``
might be raised, but it certainly
couldn't do a perfect job (that would require solving the halting problem
and is provably impossible), and because this is a warning anyway, it does
In the rare case where a warning is bogus, it can be suppressed by any of
the following methods:
-* Compile with the *-gnatws* switch set
+* Compile with the :switch:`-gnatws` switch set
-* Suppress `Elaboration_Check` for the called subprogram
+* Suppress ``Elaboration_Check`` for the called subprogram
-* Use pragma `Warnings_Off` to turn warnings off for the call
+* Use pragma ``Warnings_Off`` to turn warnings off for the call
For the internal elaboration check case,
GNAT by default generates the
necessary run-time checks to ensure
-that `Program_Error` is raised if any
+that ``Program_Error`` is raised if any
call fails an elaboration check. Of course this can only happen if a
warning has been issued as described above. The use of pragma
-`Suppress (Elaboration_Check)` may (but is not guaranteed to) suppress
+``Suppress (Elaboration_Check)`` may (but is not guaranteed to) suppress
some of these checks, meaning that it may be possible (but is not
guaranteed) for a program to be able to call a subprogram whose body
-is not yet elaborated, without raising a `Program_Error` exception.
+is not yet elaborated, without raising a ``Program_Error`` exception.
.. _Controlling_Elaboration_in_GNAT_-_External_Calls:
...
end Main;
-where `Main` is the main program. When this program is executed, the
+where ``Main`` is the main program. When this program is executed, the
elaboration code must first be executed, and one of the jobs of the
binder is to determine the order in which the units of a program are
to be elaborated. In this case we have four units: the spec and body
-of `Math`,
-the spec of `Stuff` and the body of `Main`).
+of ``Math``,
+the spec of ``Stuff`` and the body of ``Main``).
In what order should the four separate sections of elaboration code
be executed?
There are some restrictions in the order of elaboration that the binder
can choose. In particular, if unit U has a |with|
-for a package `X`, then you
-are assured that the spec of `X`
+for a package ``X``, then you
+are assured that the spec of ``X``
is elaborated before U , but you are
-not assured that the body of `X`
+not assured that the body of ``X``
is elaborated before U.
This means that in the above case, the binder is allowed to choose the
order::
body of Math
body of Main
-but that's not good, because now the call to `Math.Sqrt`
+but that's not good, because now the call to ``Math.Sqrt``
that happens during
-the elaboration of the `Stuff`
-spec happens before the body of `Math.Sqrt` is
-elaborated, and hence causes `Program_Error` exception to be raised.
+the elaboration of the ``Stuff``
+spec happens before the body of ``Math.Sqrt`` is
+elaborated, and hence causes ``Program_Error`` exception to be raised.
At first glance, one might say that the binder is misbehaving, because
obviously you want to elaborate the body of something you |with| first, but
that is not a general rule that can be followed in all cases. Consider
problems that might arise in connection with elaboration code, this works fine.
A rule that says that you must first elaborate the body of anything you
|with| cannot work in this case:
-the body of `X` |withs| `Y`,
+the body of ``X`` |withs| ``Y``,
which means you would have to
-elaborate the body of `Y` first, but that |withs| `X`,
+elaborate the body of ``Y`` first, but that |withs| ``X``,
which means
-you have to elaborate the body of `X` first, but ... and we have a
+you have to elaborate the body of ``X`` first, but ... and we have a
loop that cannot be broken.
It is true that the binder can in many cases guess an order of elaboration
-that is unlikely to cause a `Program_Error`
+that is unlikely to cause a ``Program_Error``
exception to be raised, and it tries to do so (in the
-above example of `Math/Stuff/Spec`, the GNAT binder will
+above example of ``Math/Stuff/Spec``, the GNAT binder will
by default
-elaborate the body of `Math` right after its spec, so all will be well).
+elaborate the body of ``Math`` right after its spec, so all will be well).
However, a program that blindly relies on the binder to be helpful can
get into trouble, as we discussed in the previous sections, so GNAT
*If a unit has elaboration code that can directly or indirectly make a
call to a subprogram in a |withed| unit, or instantiate a generic
package in a |withed| unit, then if the |withed| unit
-does not have pragma `Pure` or `Preelaborate`, then the client should have an
-`Elaborate_All` pragma for the |withed| unit.*
+does not have pragma ``Pure`` or ``Preelaborate``, then the client should have an
+``Elaborate_All`` pragma for the |withed| unit.*
*In the case of instantiating a generic subprogram, it is always
-sufficient to have only an `Elaborate` pragma for the
+sufficient to have only an ``Elaborate`` pragma for the
|withed| unit.*
By following this rule a client is assured that calls and instantiations
can be made without risk of an exception.
In this mode GNAT traces all calls that are potentially made from
-elaboration code, and puts in any missing implicit `Elaborate`
-and `Elaborate_All` pragmas.
+elaboration code, and puts in any missing implicit ``Elaborate``
+and ``Elaborate_All`` pragmas.
The advantage of this approach is that no elaboration problems
are possible if the binder can find an elaboration order that is
-consistent with these implicit `Elaborate` and
-`Elaborate_All` pragmas. The
+consistent with these implicit ``Elaborate`` and
+``Elaborate_All`` pragmas. The
disadvantage of this approach is that no such order may exist.
If the binder does not generate any diagnostics, then it means that it has
found an elaboration order that is guaranteed to be safe. However, the binder
-may still be relying on implicitly generated `Elaborate` and
-`Elaborate_All` pragmas so portability to other compilers than GNAT is not
+may still be relying on implicitly generated ``Elaborate`` and
+``Elaborate_All`` pragmas so portability to other compilers than GNAT is not
guaranteed.
If it is important to guarantee portability, then the compilations should
-use the *-gnatel*
+use the :switch:`-gnatel`
(info messages for elaboration pragmas) switch. This will cause info messages
-to be generated indicating the missing `Elaborate` and
-`Elaborate_All` pragmas.
+to be generated indicating the missing ``Elaborate`` and
+``Elaborate_All`` pragmas.
Consider the following source program:
.. code-block:: ada
end;
where it is clear that there
-should be a pragma `Elaborate_All`
-for unit `k`. An implicit pragma will be generated, and it is
+should be a pragma ``Elaborate_All``
+for unit ``k``. An implicit pragma will be generated, and it is
likely that the binder will be able to honor it. However, if you want
to port this program to some other Ada compiler than GNAT.
it is safer to include the pragma explicitly in the source. If this
-unit is compiled with the *-gnatel*
+unit is compiled with the :switch:`-gnatel`
switch, then the compiler outputs an information message::
1. with k;
the missing pragmas. It is usually a bad idea to use this
option during development. That's because it will tell you when
you need to put in a pragma, but cannot tell you when it is time
-to take it out. So the use of pragma `Elaborate_All` may lead to
+to take it out. So the use of pragma ``Elaborate_All`` may lead to
unnecessary dependencies and even false circularities.
This default mode is more restrictive than the Ada Reference
standard dynamic model of elaboration with run-time checks.
In GNAT, this standard mode can be achieved either by the use of
-the *-gnatE* switch on the compiler (*gcc* or
-*gnatmake*) command, or by the use of the configuration pragma:
+the :switch:`-gnatE` switch on the compiler (``gcc`` or
+``gnatmake``) command, or by the use of the configuration pragma:
.. code-block:: ada
.. index:: Pragma Elaborate
-The use of `pragma Elaborate`
+The use of ``pragma Elaborate``
should generally be avoided in Ada 95 and Ada 2005 programs,
since there is no guarantee that transitive calls
will be properly handled. Indeed at one point, this pragma was placed
in Annex J (Obsolescent Features), on the grounds that it is never useful.
Now that's a bit restrictive. In practice, the case in which
-`pragma Elaborate` is useful is when the caller knows that there
+``pragma Elaborate`` is useful is when the caller knows that there
are no transitive calls, or that the called unit contains all necessary
-transitive `pragma Elaborate` statements, and legacy code often
+transitive ``pragma Elaborate`` statements, and legacy code often
contains such uses.
Strictly speaking the static mode in GNAT should ignore such pragmas,
since there is no assurance at compile time that the necessary safety
conditions are met. In practice, this would cause GNAT to be incompatible
with correctly written Ada 83 code that had all necessary
-`pragma Elaborate` statements in place. Consequently, we made the
+``pragma Elaborate`` statements in place. Consequently, we made the
decision that GNAT in its default mode will believe that if it encounters
-a `pragma Elaborate` then the programmer knows what they are doing,
+a ``pragma Elaborate`` then the programmer knows what they are doing,
and it will trust that no elaboration errors can occur.
The result of this decision is two-fold. First to be safe using the
-static mode, you should remove all `pragma Elaborate` statements.
+static mode, you should remove all ``pragma Elaborate`` statements.
Second, when fixing circularities in existing code, you can selectively
-use `pragma Elaborate` statements to convince the static mode of
-GNAT that it need not generate an implicit `pragma Elaborate_All`
+use ``pragma Elaborate`` statements to convince the static mode of
+GNAT that it need not generate an implicit ``pragma Elaborate_All``
statement.
-When using the static mode with *-gnatwl*, any use of
-`pragma Elaborate` will generate a warning about possible
+When using the static mode with :switch:`-gnatwl`, any use of
+``pragma Elaborate`` will generate a warning about possible
problems.
If the above example is compiled in the default static elaboration
mode, then a circularity occurs. The circularity comes from the call
-`Utils.Put_Val` in the task body of `Decls.Lib_Task`. Since
+``Utils.Put_Val`` in the task body of ``Decls.Lib_Task``. Since
this call occurs in elaboration code, we need an implicit pragma
-`Elaborate_All` for `Utils`. This means that not only must
-the spec and body of `Utils` be elaborated before the body
-of `Decls`, but also the spec and body of any unit that is
-|withed| by the body of `Utils` must also be elaborated before
-the body of `Decls`. This is the transitive implication of
-pragma `Elaborate_All` and it makes sense, because in general
-the body of `Put_Val` might have a call to something in a
+``Elaborate_All`` for ``Utils``. This means that not only must
+the spec and body of ``Utils`` be elaborated before the body
+of ``Decls``, but also the spec and body of any unit that is
+|withed| by the body of ``Utils`` must also be elaborated before
+the body of ``Decls``. This is the transitive implication of
+pragma ``Elaborate_All`` and it makes sense, because in general
+the body of ``Put_Val`` might have a call to something in a
|withed| unit.
In this case, the body of Utils (actually its spec) |withs|
-`Decls`. Unfortunately this means that the body of `Decls`
+``Decls``. Unfortunately this means that the body of ``Decls``
must be elaborated before itself, in case there is a call from the
-body of `Utils`.
+body of ``Utils``.
Here is the exact chain of events we are worrying about:
-* In the body of `Decls` a call is made from within the body of a library
- task to a subprogram in the package `Utils`. Since this call may
+* In the body of ``Decls`` a call is made from within the body of a library
+ task to a subprogram in the package ``Utils``. Since this call may
occur at elaboration time (given that the task is activated at elaboration
time), we have to assume the worst, i.e., that the
call does happen at elaboration time.
-* This means that the body and spec of `Util` must be elaborated before
- the body of `Decls` so that this call does not cause an access before
+* This means that the body and spec of ``Util`` must be elaborated before
+ the body of ``Decls`` so that this call does not cause an access before
elaboration.
-* Within the body of `Util`, specifically within the body of
- `Util.Put_Val` there may be calls to any unit |withed|
+* Within the body of ``Util``, specifically within the body of
+ ``Util.Put_Val`` there may be calls to any unit |withed|
by this package.
-* One such |withed| package is package `Decls`, so there
- might be a call to a subprogram in `Decls` in `Put_Val`.
+* One such |withed| package is package ``Decls``, so there
+ might be a call to a subprogram in ``Decls`` in ``Put_Val``.
In fact there is such a call in this example, but we would have to
assume that there was such a call even if it were not there, since
- we are not supposed to write the body of `Decls` knowing what
- is in the body of `Utils`; certainly in the case of the
+ we are not supposed to write the body of ``Decls`` knowing what
+ is in the body of ``Utils``; certainly in the case of the
static elaboration model, the compiler does not know what is in
other bodies and must assume the worst.
-* This means that the spec and body of `Decls` must also be
+* This means that the spec and body of ``Decls`` must also be
elaborated before we elaborate the unit containing the call, but
- that unit is `Decls`! This means that the body of `Decls`
+ that unit is ``Decls``! This means that the body of ``Decls``
must be elaborated before itself, and that's a circularity.
-Indeed, if you add an explicit pragma `Elaborate_All` for `Utils` in
-the body of `Decls` you will get a true Ada Reference Manual
+Indeed, if you add an explicit pragma ``Elaborate_All`` for ``Utils`` in
+the body of ``Decls`` you will get a true Ada Reference Manual
circularity that makes the program illegal.
In practice, we have found that problems with the static model of
we must address this particular situation.
Note that if we compile and run the program above, using the dynamic model of
-elaboration (that is to say use the *-gnatE* switch),
+elaboration (that is to say use the :switch:`-gnatE` switch),
then it compiles, binds,
links, and runs, printing the expected result of 2. Therefore in some sense
the circularity here is only apparent, and we need to capture
* Use the dynamic model of elaboration.
- If we use the *-gnatE* switch, then as noted above, the program works.
+ If we use the :switch:`-gnatE` switch, then as noted above, the program works.
Why is this? If we examine the task body, it is apparent that the task cannot
proceed past the
- `accept` statement until after elaboration has been completed, because
+ ``accept`` statement until after elaboration has been completed, because
the corresponding entry call comes from the main program, not earlier.
This is why the dynamic model works here. But that's really giving
up on a precise analysis, and we prefer to take this approach only if we cannot
end;
- All we have done is to split `Decls` into two packages, one
+ All we have done is to split ``Decls`` into two packages, one
containing the library task, and one containing everything else. Now
there is no cycle, and the program compiles, binds, links and executes
using the default static model of elaboration.
end;
- What we have done here is to replace the `task` declaration in
- package `Decls` with a `task type` declaration. Then we
- introduce a separate package `Declst` to contain the actual
+ What we have done here is to replace the ``task`` declaration in
+ package ``Decls`` with a ``task type`` declaration. Then we
+ introduce a separate package ``Declst`` to contain the actual
task object. This separates the elaboration issues for
- the `task type`
+ the ``task type``
declaration, which causes no trouble, from the elaboration issues
of the task object, which is also unproblematic, since it is now independent
- of the elaboration of `Utils`.
+ of the elaboration of ``Utils``.
This separation of concerns also corresponds to
a generally sound engineering principle of separating declarations
from instances. This version of the program also compiles, binds, links,
Let us consider more carefully why our original sample program works
under the dynamic model of elaboration. The reason is that the code
- in the task body blocks immediately on the `accept`
+ in the task body blocks immediately on the ``accept``
statement. Now of course there is nothing to prohibit elaboration
code from making entry calls (for example from another library level task),
so we cannot tell in isolation that
However, in practice it is very unusual to see elaboration code
make any entry calls, and the pattern of tasks starting
- at elaboration time and then immediately blocking on `accept` or
- `select` statements is very common. What this means is that
+ at elaboration time and then immediately blocking on ``accept`` or
+ ``select`` statements is very common. What this means is that
the compiler is being too pessimistic when it analyzes the
whole package body as though it might be executed at elaboration
time.
in the presence of a :file:`gnat.adc` containing the above pragma,
then once again, we can compile, bind, link, and execute, obtaining
the expected result. In the presence of this pragma, the compiler does
- not trace calls in a task body, that appear after the first `accept`
- or `select` statement, and therefore does not report a potential
+ not trace calls in a task body, that appear after the first ``accept``
+ or ``select`` statement, and therefore does not report a potential
circularity in the original program.
The compiler will check to the extent it can that the above
be |withed| by a unit compiled with the dynamic model**.
The reason for this is that in the static model, a unit assumes that
its clients guarantee to use (the equivalent of) pragma
-`Elaborate_All` so that no elaboration checks are required
+``Elaborate_All`` so that no elaboration checks are required
in inner subprograms, and this assumption is violated if the
client is compiled with dynamic checks.
* The |withed| unit is itself compiled with dynamic elaboration
- checks (that is with the *-gnatE* switch.
+ checks (that is with the :switch:`-gnatE` switch.
* The |withed| unit is an internal GNAT implementation unit from
the System, Interfaces, Ada, or GNAT hierarchies.
* The |withed| unit has pragma Preelaborate or pragma Pure.
* The |withing| unit (that is the client) has an explicit pragma
- `Elaborate_All` for the |withed| unit.
+ ``Elaborate_All`` for the |withed| unit.
If this rule is violated, that is if a unit with dynamic elaboration
checks |withs| a unit that does not meet one of the above four
-criteria, then the binder (`gnatbind`) will issue a warning
+criteria, then the binder (``gnatbind``) will issue a warning
similar to that in the following example::
warning: "x.ads" has dynamic elaboration checks and with's
These warnings indicate that the rule has been violated, and that as a result
elaboration checks may be missed in the resulting executable file.
-This warning may be suppressed using the *-ws* binder switch
+This warning may be suppressed using the :switch:`-ws` binder switch
in the usual manner.
One useful application of this mixing rule is in the case of a subsystem
info: reason: pragma Elaborate in unit "proc (body)"
In this case we have a cycle that the binder cannot break. On the one
-hand, there is an explicit pragma Elaborate in `proc` for
-`pack`. This means that the body of `pack` must be elaborated
-before the body of `proc`. On the other hand, there is elaboration
-code in `pack` that calls a subprogram in `proc`. This means
+hand, there is an explicit pragma Elaborate in ``proc`` for
+``pack``. This means that the body of ``pack`` must be elaborated
+before the body of ``proc``. On the other hand, there is elaboration
+code in ``pack`` that calls a subprogram in ``proc``. This means
that for maximum safety, there should really be a pragma
-Elaborate_All in `pack` for `proc` which would require that
-the body of `proc` be elaborated before the body of
-`pack`. Clearly both requirements cannot be satisfied.
+Elaborate_All in ``pack`` for ``proc`` which would require that
+the body of ``proc`` be elaborated before the body of
+``pack``. Clearly both requirements cannot be satisfied.
Faced with a circularity of this kind, you have three different options.
* *Perform dynamic checks*
- If the compilations are done using the *-gnatE*
+ If the compilations are done using the :switch:`-gnatE`
(dynamic elaboration check) switch, then GNAT behaves in a quite different
manner. Dynamic checks are generated for all calls that could possibly result
in raising an exception. With this switch, the compiler does not generate
- implicit `Elaborate` or `Elaborate_All` pragmas. The behavior then is
+ implicit ``Elaborate`` or ``Elaborate_All`` pragmas. The behavior then is
exactly as specified in the :title:`Ada Reference Manual`.
The binder will generate
- an executable program that may or may not raise `Program_Error`, and then
+ an executable program that may or may not raise ``Program_Error``, and then
it is the programmer's job to ensure that it does not raise an exception. Note
that it is important to compile all units with the switch, it cannot be used
selectively.
are absolutely sure that your program cannot raise any elaboration
exceptions, and you still want to use the dynamic elaboration model,
then you can use the configuration pragma
- `Suppress (Elaboration_Check)` to suppress all such checks. For
+ ``Suppress (Elaboration_Check)`` to suppress all such checks. For
example this pragma could be placed in the :file:`gnat.adc` file.
* *Suppress checks selectively*
When you know that certain calls or instantiations in elaboration code cannot
possibly lead to an elaboration error, and the binder nevertheless complains
- about implicit `Elaborate` and `Elaborate_All` pragmas that lead to
+ about implicit ``Elaborate`` and ``Elaborate_All`` pragmas that lead to
elaboration circularities, it is possible to remove those warnings locally and
obtain a program that will bind. Clearly this can be unsafe, and it is the
responsibility of the programmer to make sure that the resulting program has no
- elaboration anomalies. The pragma `Suppress (Elaboration_Check)` can be
+ elaboration anomalies. The pragma ``Suppress (Elaboration_Check)`` can be
used with different granularity to suppress warnings and break elaboration
circularities:
* Use Pragma Elaborate.
As previously described in section :ref:`Treatment_of_Pragma_Elaborate`,
- GNAT in static mode assumes that a `pragma` Elaborate indicates correctly
+ GNAT in static mode assumes that a ``pragma`` Elaborate indicates correctly
that no elaboration checks are required on calls to the designated unit.
There may be cases in which the caller knows that no transitive calls
- can occur, so that a `pragma Elaborate` will be sufficient in a
- case where `pragma Elaborate_All` would cause a circularity.
+ can occur, so that a ``pragma Elaborate`` will be sufficient in a
+ case where ``pragma Elaborate_All`` would cause a circularity.
These five cases are listed in order of decreasing safety, and therefore
require increasing programmer care in their application. Consider the
info: which is withed by:
info: "pack1 (body)"
- The sources of the circularity are the two calls to `Pack2.Pure` and
- `Pack2.F2` in the body of `Pack1`. We can see that the call to
+ The sources of the circularity are the two calls to ``Pack2.Pure`` and
+ ``Pack2.F2`` in the body of ``Pack1``. We can see that the call to
F2 is safe, even though F2 calls F1, because the call appears after the
elaboration of the body of F1. Therefore the pragma (1) is safe, and will
remove the warning on the call. It is also possible to use pragma (2)
because there are no other potentially unsafe calls in the block.
- The call to `Pure` is safe because this function does not depend on the
- state of `Pack2`. Therefore any call to this function is safe, and it
+ The call to ``Pure`` is safe because this function does not depend on the
+ state of ``Pack2``. Therefore any call to this function is safe, and it
is correct to place pragma (3) in the corresponding package spec.
- Finally, we could place pragma (4) in the spec of `Pack2` to disable
+ Finally, we could place pragma (4) in the spec of ``Pack2`` to disable
warnings on all calls to functions declared therein. Note that this is not
necessarily safe, and requires more detailed examination of the subprogram
- bodies involved. In particular, a call to `F2` requires that `F1`
+ bodies involved. In particular, a call to ``F2`` requires that ``F1``
be already elaborated.
It is hard to generalize on which of these four approaches should be
taken. Obviously if it is possible to fix the program so that the default
treatment works, this is preferable, but this may not always be practical.
-It is certainly simple enough to use *-gnatE*
+It is certainly simple enough to use :switch:`-gnatE`
but the danger in this case is that, even if the GNAT binder
finds a correct elaboration order, it may not always do so,
and certainly a binder from another Ada compiler might not. A
combination of testing and analysis (for which the
-information messages generated with the *-gnatel*
+information messages generated with the :switch:`-gnatel`
switch can be useful) must be used to ensure that the program is free
of errors. One switch that is useful in this testing is the
-*-p (pessimistic elaboration order)* switch for `gnatbind`.
+:switch:`-p` (pessimistic elaboration order) switch for ``gnatbind``.
Normally the binder tries to find an order that has the best chance
of avoiding elaboration problems. However, if this switch is used, the binder
plays a devil's advocate role, and tries to choose the order that
a correct order statically, and it checks that an exception is indeed
raised at run time.
-This one test must be compiled and run using the *-gnatE*
+This one test must be compiled and run using the :switch:`-gnatE`
switch, and then it passes. Alternatively, the entire suite can
be run using this switch. It is never wrong to run with the dynamic
elaboration switch if your code is correct, and we assume that the
dispatching calls to not-yet-elaborated subprograms. In such cases, we
fall back to run-time checks; premature calls to any primitive
operation of a tagged type before the body of the operation has been
-elaborated will raise `Program_Error`.
+elaborated will raise ``Program_Error``.
Access-to-subprogram types, however, are handled conservatively in many
cases. This was not true in earlier versions of the compiler; you can use
-the *-gnatd.U* debug switch to revert to the old behavior if the new
+the :switch:`-gnatd.U` debug switch to revert to the old behavior if the new
conservative behavior causes elaboration cycles. Here, 'conservative' means
-that if you do `P'Access` during elaboration, the compiler will normally
-assume that you might call `P` indirectly during elaboration, so it adds an
-implicit `pragma Elaborate_All` on the library unit containing `P`. The
-*-gnatd.U* switch is safe if you know there are no such calls. If the
-program worked before, it will continue to work with *-gnatd.U*. But beware
+that if you do ``P'Access`` during elaboration, the compiler will normally
+assume that you might call ``P`` indirectly during elaboration, so it adds an
+implicit ``pragma Elaborate_All`` on the library unit containing ``P``. The
+:switch:`-gnatd.U` switch is safe if you know there are no such calls. If the
+program worked before, it will continue to work with :switch:`-gnatd.U`. But beware
that code modifications such as adding an indirect call can cause erroneous
-behavior in the presence of *-gnatd.U*.
+behavior in the presence of :switch:`-gnatd.U`.
These implicit Elaborate_All pragmas are not added in all cases, because
they cause elaboration cycles in certain common code patterns. If you want
-even more conservative handling of P'Access, you can use the *-gnatd.o*
+even more conservative handling of P'Access, you can use the :switch:`-gnatd.o`
switch.
-See `debug.adb` for documentation on the *-gnatd...* debug switches.
+See :file:`debug.adb` for documentation on the :switch:`-gnatd...` debug switches.
.. _Summary_of_Procedures_for_Elaboration_Control:
raised by the use of access-to-subprogram types and dynamic dispatching,
the program is free of elaboration errors. If it is important that the
program be portable to other compilers than GNAT, then use the
-*-gnatel*
-switch to generate messages about missing `Elaborate` or
-`Elaborate_All` pragmas, and supply the missing pragmas.
+:switch:`-gnatel`
+switch to generate messages about missing ``Elaborate`` or
+``Elaborate_All`` pragmas, and supply the missing pragmas.
If the program fails to bind using the default static elaboration
handling, then you can fix the program to eliminate the binder
message, or recompile the entire program with the
-*-gnatE* switch to generate dynamic elaboration checks,
+:switch:`-gnatE` switch to generate dynamic elaboration checks,
and, if you are sure there really are no elaboration problems,
-use a global pragma `Suppress (Elaboration_Check)`.
+use a global pragma ``Suppress (Elaboration_Check)``.
.. _Other_Elaboration_Order_Considerations:
There is no language rule to prefer one or the other, both are correct
from an order of elaboration point of view. But the programmatic effects
of the two orders are very different. In the first, the elaboration routine
-of `Calc` initializes `Z` to zero, and then the main program
+of ``Calc`` initializes ``Z`` to zero, and then the main program
runs with this value of zero. But in the second order, the elaboration
-routine of `Calc` runs after the body of Init_Constants has set
-`X` and `Y` and thus `Z` is set to 7 before `Main` runs.
+routine of ``Calc`` runs after the body of Init_Constants has set
+``X`` and ``Y`` and thus ``Z`` is set to 7 before ``Main`` runs.
One could perhaps by applying pretty clever non-artificial intelligence
to the situation guess that it is more likely that the second order of
pragma Elaborate_All (Constants);
-which requires that the body (if any) and spec of `Constants`,
+which requires that the body (if any) and spec of ``Constants``,
as well as the body and spec of any unit |withed| by
-`Constants` be elaborated before `Calc` is elaborated.
+``Constants`` be elaborated before ``Calc`` is elaborated.
Clearly no automatic method can always guess which alternative you require,
and if you are working with legacy code that had constraints of this kind
-which were not properly specified by adding `Elaborate` or
-`Elaborate_All` pragmas, then indeed it is possible that two different
+which were not properly specified by adding ``Elaborate`` or
+``Elaborate_All`` pragmas, then indeed it is possible that two different
compilers can choose different orders.
However, GNAT does attempt to diagnose the common situation where there
in which a pragma Elaborate_Body is usually desirable, and GNAT will generate
a warning that suggests this addition if it detects this situation.
-The `gnatbind` *-p* switch may be useful in smoking
+The ``gnatbind` :switch:`-p` switch may be useful in smoking
out problems. This switch causes bodies to be elaborated as late as possible
instead of as early as possible. In the example above, it would have forced
the choice of the first elaboration order. If you get different results
when using this switch, and particularly if one set of results is right,
and one is wrong as far as you are concerned, it shows that you have some
-missing `Elaborate` pragmas. For the example above, we have the
+missing ``Elaborate`` pragmas. For the example above, we have the
following output:
.. code-block:: sh
it is up to you in a case like this to investigate the source of the
difference, by looking at the two elaboration orders that are chosen,
and figuring out which is correct, and then adding the necessary
-`Elaborate` or `Elaborate_All` pragmas to ensure the desired order.
+``Elaborate`` or ``Elaborate_All`` pragmas to ensure the desired order.
.. _Determining_the_Chosen_Elaboration_Order:
You can also ask the binder to generate a more
readable list of the elaboration order using the
-`-l` switch when invoking the binder. Here is
+:switch:`-l` switch when invoking the binder. Here is
an example of the output generated by this switch::
ada (spec)
The Ada code in the above example is exactly what is generated by the
binder. We have added comments to more clearly indicate the function
-of each part of the generated `Ada_Main` package.
+of each part of the generated ``Ada_Main`` package.
The code is standard Ada in all respects, and can be processed by any
tools that handle Ada. In particular, it is possible to use the debugger
-in Ada mode to debug the generated `Ada_Main` package. For example,
+in Ada mode to debug the generated ``Ada_Main`` package. For example,
suppose that for reasons that you do not understand, your program is crashing
-during elaboration of the body of `Ada.Text_IO`. To locate this bug,
+during elaboration of the body of ``Ada.Text_IO``. To locate this bug,
you can place a breakpoint on the call:
.. code-block:: ada
+.. role:: switch(samp)
+
.. _Getting_Started_with_GNAT:
*************************
* The file(s) must be bound using the GNAT binder.
* All appropriate object files must be linked to produce an executable.
-All three steps are most commonly handled by using the *gnatmake*
+All three steps are most commonly handled by using the ``gnatmake``
utility program that, given the name of the main program, automatically
performs the necessary compilation, binding and linking steps.
extension is :file:`ads` for a
spec and :file:`adb` for a body.
You can override this default file naming convention by use of the
-special pragma `Source_File_Name` (for further information please
+special pragma ``Source_File_Name`` (for further information please
see :ref:`Using_Other_File_Names`).
Alternatively, if you want to rename your files according to this default
convention, which is probably more convenient if you will be using GNAT
-for all your compilations, then the `gnatchop` utility
+for all your compilations, then the ``gnatchop`` utility
can be used to generate correctly-named source files
(see :ref:`Renaming_Files_with_gnatchop`).
-You can compile the program using the following command (`$` is used
+You can compile the program using the following command (``$`` is used
as the command prompt in the examples in this document):
.. code-block:: sh
$ gcc -c hello.adb
-*gcc* is the command used to run the compiler. This compiler is
+``gcc`` is the command used to run the compiler. This compiler is
capable of compiling programs in several languages, including Ada and
C. It assumes that you have given it an Ada program if the file extension is
either :file:`.ads` or :file:`.adb`, and it will then call
the GNAT compiler to compile the specified file.
-The :option:`-c` switch is required. It tells *gcc* to only do a
-compilation. (For C programs, *gcc* can also do linking, but this
-capability is not used directly for Ada programs, so the :option:`-c`
+The :switch:`-c` switch is required. It tells ``gcc`` to only do a
+compilation. (For C programs, ``gcc`` can also do linking, but this
+capability is not used directly for Ada programs, so the :switch:`-c`
switch must always be present.)
This compile command generates a file
which contains additional information used to check
that an Ada program is consistent.
To build an executable file,
-use `gnatbind` to bind the program
-and *gnatlink* to link it. The
-argument to both `gnatbind` and *gnatlink* is the name of the
+use ``gnatbind`` to bind the program
+and ``gnatlink`` to link it. The
+argument to both ``gnatbind`` and ``gnatlink`` is the name of the
:file:`ALI` file, but the default extension of :file:`.ali` can
be omitted. This means that in the most common case, the argument
is simply the name of the main program:
$ gnatbind hello
$ gnatlink hello
-A simpler method of carrying out these steps is to use *gnatmake*,
+A simpler method of carrying out these steps is to use ``gnatmake``,
a master program that invokes all the required
compilation, binding and linking tools in the correct order. In particular,
-*gnatmake* automatically recompiles any sources that have been
+``gnatmake`` automatically recompiles any sources that have been
modified since they were last compiled, or sources that depend
on such modified sources, so that 'version skew' is avoided.
-.. index:: Version skew (avoided by *gnatmake*)
+.. index:: Version skew (avoided by ``gnatmake``)
.. code-block:: sh
*greetings.ads*
- spec of package `Greetings`
+ spec of package ``Greetings``
*greetings.adb*
- body of package `Greetings`
+ body of package ``Greetings``
*gmain.adb*
Also, it is not necessary to compile package specs in the case where
there is an accompanying body; you only need to compile the body. If you want
to submit these files to the compiler for semantic checking and not code
-generation, then use the :option:`-gnatc` switch:
+generation, then use the :switch:`-gnatc` switch:
.. code-block:: sh
Although the compilation can be done in separate steps as in the
above example, in practice it is almost always more convenient
-to use the *gnatmake* tool. All you need to know in this case
+to use the ``gnatmake`` tool. All you need to know in this case
is the name of the main program's source file. The effect of the above four
commands can be achieved with a single one:
$ gnatmake gmain.adb
-In the next section we discuss the advantages of using *gnatmake* in
+In the next section we discuss the advantages of using ``gnatmake`` in
more detail.
.. _Using_the_gnatmake_Utility:
-Using the *gnatmake* Utility
-============================
+Using the ``gnatmake`` Utility
+==============================
If you work on a program by compiling single components at a time using
-*gcc*, you typically keep track of the units you modify. In order to
+``gcc``, you typically keep track of the units you modify. In order to
build a consistent system, you compile not only these units, but also any
units that depend on the units you have modified.
For example, in the preceding case,
:file:`greetings.adb` and :file:`gmain.adb`, because both files contain
units that depend on :file:`greetings.ads`.
-*gnatbind* will warn you if you forget one of these compilation
+``gnatbind`` will warn you if you forget one of these compilation
steps, so that it is impossible to generate an inconsistent program as a
result of forgetting to do a compilation. Nevertheless it is tedious and
error-prone to keep track of dependencies among units.
sure that the makefile is kept up-to-date manually, which is also an
error-prone process.
-The *gnatmake* utility takes care of these details automatically.
+The ``gnatmake`` utility takes care of these details automatically.
Invoke it using either one of the following forms:
.. code-block:: sh
$ gnatmake gmain
The argument is the name of the file containing the main program;
-you may omit the extension. *gnatmake*
+you may omit the extension. ``gnatmake``
examines the environment, automatically recompiles any files that need
recompiling, and binds and links the resulting set of object files,
generating the executable file, :file:`gmain`.
In a large program, it
-can be extremely helpful to use *gnatmake*, because working out by hand
+can be extremely helpful to use ``gnatmake``, because working out by hand
what needs to be recompiled can be difficult.
-Note that *gnatmake* takes into account all the Ada rules that
+Note that ``gnatmake`` takes into account all the Ada rules that
establish dependencies among units. These include dependencies that result
from inlining subprogram bodies, and from
generic instantiation. Unlike some other
-Ada make tools, *gnatmake* does not rely on the dependencies that were
+Ada make tools, ``gnatmake`` does not rely on the dependencies that were
found by the compiler on a previous compilation, which may possibly
-be wrong when sources change. *gnatmake* determines the exact set of
+be wrong when sources change. ``gnatmake`` determines the exact set of
dependencies from scratch each time it is run.
+.. role:: switch(samp)
+
.. |with| replace:: *with*
.. |withs| replace:: *with*\ s
.. |withed| replace:: *with*\ ed
The GNAT Debugger GDB
---------------------
-`GDB` is a general purpose, platform-independent debugger that
-can be used to debug mixed-language programs compiled with *gcc*,
+``GDB`` is a general purpose, platform-independent debugger that
+can be used to debug mixed-language programs compiled with ``gcc``,
and in particular is capable of debugging Ada programs compiled with
-GNAT. The latest versions of `GDB` are Ada-aware and can handle
+GNAT. The latest versions of ``GDB`` are Ada-aware and can handle
complex Ada data structures.
See :title:`Debugging with GDB`,
-for full details on the usage of `GDB`, including a section on
+for full details on the usage of ``GDB``, including a section on
its usage on programs. This manual should be consulted for full
details. The section that follows is a brief introduction to the
-philosophy and use of `GDB`.
+philosophy and use of ``GDB``.
When GNAT programs are compiled, the compiler optionally writes debugging
information into the generated object file, including information on
larger, but it does not add to the size of the actual executable that
will be loaded into memory, and has no impact on run-time performance. The
generation of debug information is triggered by the use of the
--g switch in the *gcc* or *gnatmake* command
+:switch:`-g` switch in the ``gcc`` or ``gnatmake`` command
used to carry out the compilations. It is important to emphasize that
the use of these options does not change the generated code.
standard C formats. Details of this encoding scheme may be found in
the file exp_dbug.ads in the GNAT source distribution. However, the
details of this encoding are, in general, of no interest to a user,
-since `GDB` automatically performs the necessary decoding.
+since ``GDB`` automatically performs the necessary decoding.
When a program is bound and linked, the debugging information is
collected from the object files, and stored in the executable image of
the normal manner, it runs exactly as if the debug information were
not present, and takes no more actual memory.
-However, if the program is run under control of `GDB`, the
+However, if the program is run under control of ``GDB``, the
debugger is activated. The image of the program is loaded, at which
point it is ready to run. If a run command is given, then the program
-will run exactly as it would have if `GDB` were not present. This
-is a crucial part of the `GDB` design philosophy. `GDB` is
+will run exactly as it would have if ``GDB`` were not present. This
+is a crucial part of the ``GDB`` design philosophy. ``GDB`` is
entirely non-intrusive until a breakpoint is encountered. If no
breakpoint is ever hit, the program will run exactly as it would if no
-debugger were present. When a breakpoint is hit, `GDB` accesses
+debugger were present. When a breakpoint is hit, ``GDB`` accesses
the debugging information and can respond to user commands to inspect
variables, and more generally to report on the state of execution.
This section describes how to initiate the debugger.
-The debugger can be launched from a `GPS` menu or
+The debugger can be launched from a ``GPS`` menu or
directly from the command line. The description below covers the latter use.
-All the commands shown can be used in the `GPS` debug console window,
+All the commands shown can be used in the ``GPS`` debug console window,
but there are usually more GUI-based ways to achieve the same effect.
-The command to run `GDB` is
+The command to run ``GDB`` is
::
$ gdb program
-where `program` is the name of the executable file. This
+where ``program`` is the name of the executable file. This
activates the debugger and results in a prompt for debugger commands.
-The simplest command is simply `run`, which causes the program to run
+The simplest command is simply ``run``, which causes the program to run
exactly as if the debugger were not present. The following section
-describes some of the additional commands that can be given to `GDB`.
+describes some of the additional commands that can be given to ``GDB``.
.. _Introduction_to_GDB_Commands:
Introduction to GDB Commands
----------------------------
-`GDB` contains a large repertoire of commands.
+``GDB`` contains a large repertoire of commands.
See :title:`Debugging with GDB` for extensive documentation on the use
of these commands, together with examples of their use. Furthermore,
the command *help* invoked from within GDB activates a simple help
facility which summarizes the available commands and their options.
In this section we summarize a few of the most commonly
-used commands to give an idea of what `GDB` is about. You should create
+used commands to give an idea of what ``GDB`` is about. You should create
a simple program with debugging information and experiment with the use of
-these `GDB` commands on the program as you read through the
+these ``GDB`` commands on the program as you read through the
following section.
-* *set args `arguments`*
- The `arguments` list above is a list of arguments to be passed to
+* :samp:`set args {arguments}`
+ The *arguments* list above is a list of arguments to be passed to
the program on a subsequent run command, just as though the arguments
- had been entered on a normal invocation of the program. The `set args`
+ had been entered on a normal invocation of the program. The ``set args``
command is not needed if the program does not require arguments.
-* *run*
- The `run` command causes execution of the program to start from
+* :samp:`run`
+ The ``run`` command causes execution of the program to start from
the beginning. If the program is already running, that is to say if
you are currently positioned at a breakpoint, then a prompt will ask
for confirmation that you want to abandon the current execution and
restart.
-* *breakpoint `location`*
+* :samp:`breakpoint {location}`
The breakpoint command sets a breakpoint, that is to say a point at which
- execution will halt and `GDB` will await further
- commands. `location` is
- either a line number within a file, given in the format `file:linenumber`,
+ execution will halt and ``GDB`` will await further
+ commands. *location* is
+ either a line number within a file, given in the format ``file:linenumber``,
or it is the name of a subprogram. If you request that a breakpoint be set on
a subprogram that is overloaded, a prompt will ask you to specify on which of
those subprograms you want to breakpoint. You can also
specify that all of them should be breakpointed. If the program is run
and execution encounters the breakpoint, then the program
- stops and `GDB` signals that the breakpoint was encountered by
+ stops and ``GDB`` signals that the breakpoint was encountered by
printing the line of code before which the program is halted.
-* *catch exception `name`*
+* :samp:`catch exception {name}`
This command causes the program execution to stop whenever exception
- `name` is raised. If `name` is omitted, then the execution is
+ ``name`` is raised. If ``name`` is omitted, then the execution is
suspended when any exception is raised.
-* *print `expression`*
+* :samp:`print {expression}`
This will print the value of the given expression. Most simple
- Ada expression formats are properly handled by `GDB`, so the expression
+ Ada expression formats are properly handled by ``GDB``, so the expression
can contain function calls, variables, operators, and attribute references.
-* *continue*
+* :samp:`continue`
Continues execution following a breakpoint, until the next breakpoint or the
termination of the program.
-* *step*
+* :samp:`step`
Executes a single line after a breakpoint. If the next statement
is a subprogram call, execution continues into (the first statement of)
the called subprogram.
-* *next*
+* :samp:`next`
Executes a single line. If this line is a subprogram call, executes and
returns from the call.
-* *list*
+* :samp:`list`
Lists a few lines around the current source location. In practice, it
is usually more convenient to have a separate edit window open with the
relevant source file displayed. Successive applications of this command
line number, in which case it displays a few lines around the specified one.
-* *backtrace*
+* :samp:`backtrace`
Displays a backtrace of the call chain. This command is typically
used after a breakpoint has occurred, to examine the sequence of calls that
leads to the current breakpoint. The display includes one line for each
activation record (frame) corresponding to an active subprogram.
-* *up*
- At a breakpoint, `GDB` can display the values of variables local
- to the current frame. The command `up` can be used to
+* :samp:`up`
+ At a breakpoint, ``GDB`` can display the values of variables local
+ to the current frame. The command ``up`` can be used to
examine the contents of other active frames, by moving the focus up
the stack, that is to say from callee to caller, one frame at a time.
-* *down*
- Moves the focus of `GDB` down from the frame currently being
+* :samp:`down`
+ Moves the focus of ``GDB`` down from the frame currently being
examined to the frame of its callee (the reverse of the previous command),
-* *frame `n`*
+* :samp:`frame {n}`
Inspect the frame with the given number. The value 0 denotes the frame
of the current breakpoint, that is to say the top of the call stack.
-* *kill*
+* :samp:`kill`
Kills the child process in which the program is running under GDB.
This may be useful for several purposes:
* It allows you to debug a core dump rather than a running process.
The above list is a very short introduction to the commands that
-`GDB` provides. Important additional capabilities, including conditional
+``GDB`` provides. Important additional capabilities, including conditional
breakpoints, the ability to execute command sequences on a breakpoint,
the ability to debug at the machine instruction level and many other
features are described in detail in :title:`Debugging with GDB`.
.. index:: Ada expressions (in gdb)
-`GDB` supports a fairly large subset of Ada expression syntax, with some
+``GDB`` supports a fairly large subset of Ada expression syntax, with some
extensions. The philosophy behind the design of this subset is
- * That `GDB` should provide basic literals and access to operations for
+ * That ``GDB`` should provide basic literals and access to operations for
arithmetic, dereferencing, field selection, indexing, and subprogram calls,
leaving more sophisticated computations to subprograms written into the
- program (which therefore may be called from `GDB`).
+ program (which therefore may be called from ``GDB``).
* That type safety and strict adherence to Ada language restrictions
are not particularly relevant in a debugging context.
- * That brevity is important to the `GDB` user.
+ * That brevity is important to the ``GDB`` user.
Thus, for brevity, the debugger acts as if there were
-implicit `with` and `use` clauses in effect for all user-written
+implicit ``with`` and ``use`` clauses in effect for all user-written
packages, thus making it unnecessary to fully qualify most names with
their packages, regardless of context. Where this causes ambiguity,
-`GDB` asks the user's intent.
+``GDB`` asks the user's intent.
For details on the supported Ada syntax, see :title:`Debugging with GDB`.
Calling User-Defined Subprograms
--------------------------------
-An important capability of `GDB` is the ability to call user-defined
+An important capability of ``GDB`` is the ability to call user-defined
subprograms while debugging. This is achieved simply by entering
a subprogram call statement in the form:
call subprogram-name (parameters)
-The keyword `call` can be omitted in the normal case where the
-`subprogram-name` does not coincide with any of the predefined
-`GDB` commands.
+The keyword ``call`` can be omitted in the normal case where the
+``subprogram-name`` does not coincide with any of the predefined
+``GDB`` commands.
The effect is to invoke the given subprogram, passing it the
list of parameters that is supplied. The parameters can be expressions and
can include variables from the program being debugged. The
subprogram must be defined
-at the library level within your program, and `GDB` will call the
+at the library level within your program, and ``GDB`` will call the
subprogram within the environment of your program execution (which
means that the subprogram is free to access or even modify variables
within your program).
in your program. Such debugging routines can be written to provide a suitably
high-level description of an abstract type, rather than a low-level dump
of its physical layout. After all, the standard
-`GDB print` command only knows the physical layout of your
+``GDB print`` command only knows the physical layout of your
types, not their abstract meaning. Debugging routines can provide information
at the desired semantic level and are thus enormously useful.
the contents of the tree nodes used to represent the program internally.
But tree nodes are represented simply by an integer value (which in turn
is an index into a table of nodes).
-Using the `print` command on a tree node would simply print this integer
+Using the ``print`` command on a tree node would simply print this integer
value, which is not very useful. But the PN routine (defined in file
treepr.adb in the GNAT sources) takes a tree node as input, and displays
a useful high level representation of the tree node, which includes the
Using the *next* Command in a Function
--------------------------------------
-When you use the `next` command in a function, the current source
+When you use the ``next`` command in a function, the current source
location will advance to the next statement as usual. A special case
-arises in the case of a `return` statement.
+arises in the case of a ``return`` statement.
Part of the code for a return statement is the 'epilogue' of the function.
This is the code that returns to the caller. There is only one copy of
implementations, this epilogue is associated with the first statement
of the function.
-The result is that if you use the `next` command from a return
+The result is that if you use the ``next`` command from a return
statement that is not the last return statement of the function you
may see a strange apparent jump to the last return statement or to
the start of the function. You should simply ignore this odd jump.
raises selected exceptions.
-* *catch exception*
+* :samp:`catch exception`
Set a catchpoint that stops execution whenever (any task in the) program
raises any exception.
-* *catch exception `name`*
+* :samp:`catch exception {name}`
Set a catchpoint that stops execution whenever (any task in the) program
- raises the exception `name`.
+ raises the exception *name*.
-* *catch exception unhandled*
+* :samp:`catch exception unhandled`
Set a catchpoint that stops executing whenever (any task in the) program
raises an exception for which there is no handler.
-* *info exceptions*, *info exceptions `regexp`*
- The `info exceptions` command permits the user to examine all defined
- exceptions within Ada programs. With a regular expression, `regexp`, as
- argument, prints out only those exceptions whose name matches `regexp`.
+* :samp:`info exceptions`, :samp:`info exceptions {regexp}`
+ The ``info exceptions`` command permits the user to examine all defined
+ exceptions within Ada programs. With a regular expression, *regexp*, as
+ argument, prints out only those exceptions whose name matches *regexp*.
.. index:: Tasks (in gdb)
Ada Tasks
---------
-`GDB` allows the following task-related commands:
+``GDB`` allows the following task-related commands:
-* *info tasks*
+* :samp:`info tasks`
This command shows a list of current Ada tasks, as in the following example:
::
.. index:: Breakpoints and tasks
-* *break `linespec` task `taskid`*, *break `linespec` task `taskid` if ...*
+* ``break``*linespec* ``task`` *taskid*, ``break`` *linespec* ``task`` *taskid* ``if`` ...
- These commands are like the `break ... thread ...`.
- `linespec` specifies source lines.
+ These commands are like the ``break ... thread ...``.
+ *linespec* specifies source lines.
Use the qualifier :samp:`task {taskid}` with a breakpoint command
- to specify that you only want `GDB` to stop the program when a
- particular Ada task reaches this breakpoint. `taskid` is one of the
- numeric task identifiers assigned by `GDB`, shown in the first
+ to specify that you only want ``GDB`` to stop the program when a
+ particular Ada task reaches this breakpoint. *taskid* is one of the
+ numeric task identifiers assigned by ``GDB``, shown in the first
column of the ``info tasks`` display.
If you do not specify :samp:`task {taskid}` when you set a
breakpoint, the breakpoint applies to *all* tasks of your
program.
- You can use the `task` qualifier on conditional breakpoints as
+ You can use the ``task`` qualifier on conditional breakpoints as
well; in this case, place :samp:`task {taskid}` before the
- breakpoint condition (before the `if`).
+ breakpoint condition (before the ``if``).
.. index:: Task switching (in gdb)
-* *task `taskno`*
+* :samp:`task {taskno}`
- This command allows switching to the task referred by `taskno`. In
+ This command allows switching to the task referred by *taskno*. In
particular, this allows browsing of the backtrace of the specified
task. It is advisable to switch back to the original task before
continuing execution otherwise the scheduling of the program may be
made, with appropriate substitutions of formals by actuals.
It is not possible to refer to the original generic entities in
-`GDB`, but it is always possible to debug a particular instance of
+``GDB``, but it is always possible to debug a particular instance of
a generic, by using the appropriate expanded names. For example, if we have
.. code-block:: ada
difficulty, corresponding to your experience in using GNAT and your
familiarity with compiler internals.
-* Run *gcc* with the *-gnatf*. This first
+* Run ``gcc`` with the :switch:`-gnatf`. This first
switch causes all errors on a given line to be reported. In its absence,
only the first error on a line is displayed.
- The *-gnatdO* switch causes errors to be displayed as soon as they
+ The :switch:`-gnatdO` switch causes errors to be displayed as soon as they
are encountered, rather than after compilation is terminated. If GNAT
terminates prematurely or goes into an infinite loop, the last error
message displayed may help to pinpoint the culprit.
-* Run *gcc* with the *-v (verbose)* switch. In this
- mode, *gcc* produces ongoing information about the progress of the
+* Run ``gcc`` with the :switch:`-v` (verbose) switch. In this
+ mode, ``gcc`` produces ongoing information about the progress of the
compilation and provides the name of each procedure as code is
generated. This switch allows you to find which Ada procedure was being
compiled when it encountered a code generation problem.
.. index:: -gnatdc switch
-* Run *gcc* with the *-gnatdc* switch. This is a GNAT specific
- switch that does for the front-end what *-v* does
+* Run ``gcc`` with the :switch:`-gnatdc` switch. This is a GNAT specific
+ switch that does for the front-end what :switch:`-v` does
for the back end. The system prints the name of each unit,
either a compilation unit or nested unit, as it is being analyzed.
* Finally, you can start
- `gdb` directly on the `gnat1` executable. `gnat1` is the
+ ``gdb`` directly on the ``gnat1`` executable. ``gnat1`` is the
front-end of GNAT, and can be run independently (normally it is just
- called from *gcc*). You can use `gdb` on `gnat1` as you
+ called from ``gcc``). You can use ``gdb`` on ``gnat1`` as you
would on a C program (but :ref:`The_GNAT_Debugger_GDB` for caveats). The
- `where` command is the first line of attack; the variable
- `lineno` (seen by `print lineno`), used by the second phase of
- `gnat1` and by the *gcc* backend, indicates the source line at
- which the execution stopped, and `input_file name` indicates the name of
+ ``where`` command is the first line of attack; the variable
+ ``lineno`` (seen by ``print lineno``), used by the second phase of
+ ``gnat1`` and by the ``gcc`` backend, indicates the source line at
+ which the execution stopped, and ``input_file name`` indicates the name of
the source file.
.. index:: Annex A (in Ada Reference Manual)
-* Ada files with the prefix :file:`a-` are children of `Ada`, as
+* Ada files with the prefix :file:`a-` are children of ``Ada``, as
defined in Annex A.
.. index:: Annex B (in Ada reference Manual)
-* Files with prefix :file:`i-` are children of `Interfaces`, as
+* Files with prefix :file:`i-` are children of ``Interfaces``, as
defined in Annex B.
.. index:: System (package in Ada Reference Manual)
-* Files with prefix :file:`s-` are children of `System`. This includes
+* Files with prefix :file:`s-` are children of ``System``. This includes
both language-defined children and GNAT run-time routines.
.. index:: GNAT (package)
-* Files with prefix :file:`g-` are children of `GNAT`. These are useful
+* Files with prefix :file:`g-` are children of ``GNAT``. These are useful
general-purpose packages, fully documented in their specs. All
- the other :file:`.c` files are modifications of common *gcc* files.
+ the other :file:`.c` files are modifications of common ``gcc`` files.
.. _Getting_Internal_Debugging_Information:
.. rubric:: Tracebacks From an Unhandled Exception
A runtime non-symbolic traceback is a list of addresses of call instructions.
-To enable this feature you must use the *-E*
-`gnatbind`'s option. With this option a stack traceback is stored as part
+To enable this feature you must use the :switch:`-E`
+``gnatbind`` option. With this option a stack traceback is stored as part
of exception information. You can retrieve this information using the
-`addr2line` tool.
+``addr2line`` tool.
Here is a simple example:
0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
As we see the traceback lists a sequence of addresses for the unhandled
-exception `CONSTRAINT_ERROR` raised in procedure P1. It is easy to
+exception ``CONSTRAINT_ERROR`` raised in procedure P1. It is easy to
guess that this exception come from procedure P1. To translate these
addresses into the source lines where the calls appear, the
-`addr2line` tool, described below, is invaluable. The use of this tool
+``addr2line`` tool, described below, is invaluable. The use of this tool
requires the program to be compiled with debug information.
::
004011F1 at /build/.../crt1.c:222
77E892A4 in ?? at ??:0
-The `addr2line` tool has several other useful options:
+The ``addr2line`` tool has several other useful options:
======================== ========================================================
:samp:`--functions` to get the function name corresponding to any location
:ref:`Running_gnatbind`. The remaining entries are assorted runtime routines,
and the output will vary from platform to platform.
-It is also possible to use `GDB` with these traceback addresses to debug
+It is also possible to use ``GDB`` with these traceback addresses to debug
the program. For example, we can break at a given code location, as reported
in the stack traceback:
.. rubric:: Tracebacks From Exception Occurrences
-Non-symbolic tracebacks are obtained by using the *-E* binder argument.
+Non-symbolic tracebacks are obtained by using the :switch:`-E` binder argument.
The stack traceback is attached to the exception information string, and can
be retrieved in an exception handler within the Ada program, by means of the
-Ada facilities defined in `Ada.Exceptions`. Here is a simple example:
+Ada facilities defined in ``Ada.Exceptions``. Here is a simple example:
.. code-block:: ada
It is also possible to retrieve a stack traceback from anywhere in a
program. For this you need to
-use the `GNAT.Traceback` API. This package includes a procedure called
-`Call_Chain` that computes a complete stack traceback, as well as useful
+use the ``GNAT.Traceback`` API. This package includes a procedure called
+``Call_Chain`` that computes a complete stack traceback, as well as useful
display procedures described below. It is not necessary to use the
-*-E gnatbind* option in this case, because the stack traceback mechanism
+:switch:`-E` ``gnatbind`` option in this case, because the stack traceback mechanism
is invoked explicitly.
In the following example we compute a traceback at a specific location in
-the program, and we display it using `GNAT.Debug_Utilities.Image` to
+the program, and we display it using ``GNAT.Debug_Utilities.Image`` to
convert addresses to strings:
16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4#
-You can then get further information by invoking the `addr2line`
+You can then get further information by invoking the ``addr2line``
tool as described earlier (note that the hexadecimal addresses
need to be specified in C format, with a leading '0x').
004011F1 in mainCRTStartup at crt1.c:222
77E892A4 in ?? at ??:0
-In the above example the ``.\`` syntax in the *gnatmake* command
-is currently required by *addr2line* for files that are in
+In the above example the ``.\`` syntax in the ``gnatmake`` command
+is currently required by ``addr2line`` for files that are in
the current working directory.
Moreover, the exact sequence of linker options may vary from platform
to platform.
-The above *-largs* section is for Windows platforms. By contrast,
-under Unix there is no need for the *-largs* section.
+The above :switch:`-largs` section is for Windows platforms. By contrast,
+under Unix there is no need for the :switch:`-largs` section.
Differences across platforms are due to details of linker implementation.
It is possible to get a symbolic stack traceback
from anywhere in a program, just as for non-symbolic tracebacks.
The first step is to obtain a non-symbolic
-traceback, and then call `Symbolic_Traceback` to compute the symbolic
+traceback, and then call ``Symbolic_Traceback`` to compute the symbolic
information. Here is an example:
.. code-block:: ada
.. rubric:: Automatic Symbolic Tracebacks
Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as
-in `gprbuild -g ... -bargs -Es`).
+in ``gprbuild -g ... -bargs -Es``).
This will cause the Exception_Information to contain a symbolic traceback,
which will also be printed if an unhandled exception terminates the
program.
+.. _Pretty-Printers_For_The_GNAT_Runtime:
+
+Pretty-Printers for the GNAT runtime
+------------------------------------
+
+As discussed in :title:`Calling User-Defined Subprograms`, GDB's
+``print`` command only knows about the physical layout of program data
+structures and therefore normally displays only low-level dumps, which
+are often hard to understand.
+
+An example of this is when trying to display the contents of an Ada
+standard container, such as ``Ada.Containers.Ordered_Maps.Map``:
+
+ .. code-block:: ada
+
+ with Ada.Containers.Ordered_Maps;
+
+ procedure PP is
+ package Int_To_Nat is
+ new Ada.Containers.Ordered_Maps (Integer, Natural);
+
+ Map : Int_To_Nat.Map;
+ begin
+ Map.Insert (1, 10);
+ Map.Insert (2, 20);
+ Map.Insert (3, 30);
+
+ Map.Clear; -- BREAK HERE
+ end PP;
+
+When this program is built with debugging information and run under
+GDB up to the ``Map.Clear`` statement, trying to print ``Map`` will
+yield information that is only relevant to the developers of our standard
+containers:
+
+ ::
+
+ (gdb) print map
+ $1 = (
+ tree => (
+ first => 0x64e010,
+ last => 0x64e070,
+ root => 0x64e040,
+ length => 3,
+ tc => (
+ busy => 0,
+ lock => 0
+ )
+ )
+ )
+
+Fortunately, GDB has a feature called `pretty-printers
+<http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Introduction>`_,
+which allows customizing how GDB displays data structures. The GDB
+shipped with GNAT embeds such pretty-printers for the most common
+containers in the standard library. To enable them, either run the
+following command manually under GDB or add it to your ``.gdbinit`` file:
+
+ ::
+
+ python import gnatdbg; gnatdbg.setup()
+
+Once this is done, GDB's ``print`` command will automatically use
+these pretty-printers when appropriate. Using the previous example:
+
+ ::
+
+ (gdb) print map
+ $1 = pp.int_to_nat.map of length 3 = {
+ [1] = 10,
+ [2] = 20,
+ [3] = 30
+ }
+
+Pretty-printers are invoked each time GDB tries to display a value,
+including when displaying the arguments of a called subprogram (in
+GDB's ``backtrace`` command) or when printing the value returned by a
+function (in GDB's ``finish`` command).
+
+To display a value without involving pretty-printers, ``print`` can be
+invoked with its ``/r`` option:
+
+ ::
+
+ (gdb) print/r map
+ $1 = (
+ tree => (...
+
+Finer control of pretty-printers is also possible: see `GDB's online
+documentation
+<http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Commands>`_
+for more information.
+
+
.. index:: Code Coverage
.. index:: Profiling
Code Coverage and Profiling
===========================
-This section describes how to use the `gcov` coverage testing tool and
-the `gprof` profiler tool on Ada programs.
+This section describes how to use the ``gcov`` coverage testing tool and
+the ``gprof`` profiler tool on Ada programs.
.. index:: ! gcov
Code Coverage of Ada Programs with gcov
---------------------------------------
-`gcov` is a test coverage program: it analyzes the execution of a given
+``gcov`` is a test coverage program: it analyzes the execution of a given
program on selected tests, to help you determine the portions of the program
that are still untested.
-`gcov` is part of the GCC suite, and is described in detail in the GCC
+``gcov`` is part of the GCC suite, and is described in detail in the GCC
User's Guide. You can refer to this documentation for a more complete
description.
Quick startup guide
^^^^^^^^^^^^^^^^^^^
-In order to perform coverage analysis of a program using `gcov`, several
+In order to perform coverage analysis of a program using ``gcov``, several
steps are needed:
#. Instrument the code during the compilation process,
#. Execute the instrumented program, and
-#. Invoke the `gcov` tool to generate the coverage results.
+#. Invoke the ``gcov`` tool to generate the coverage results.
.. index:: -fprofile-arcs (gcc)
.. index:: -ftest-coverage (gcc
inserted by gcc during the compilation process. To compile your code with code
coverage activated, you need to recompile your whole project using the
switches
-`-fprofile-arcs` and `-ftest-coverage`, and link it using
-`-fprofile-arcs`.
+:switch:`-fprofile-arcs` and :switch:`-ftest-coverage`, and link it using
+:switch:`-fprofile-arcs`.
::
will update those files, so that a cumulative result of the covered
portions of the program is generated.
-Finally, you need to call the `gcov` tool. The different options of
-`gcov` are described in the GCC User's Guide, section 'Invoking gcov'.
+Finally, you need to call the ``gcov`` tool. The different options of
+``gcov`` are described in the GCC User's Guide, section *Invoking gcov*.
This will create annotated source files with a :file:`.gcov` extension:
:file:`my_main.adb` file will be analyzed in :file:`my_main.adb.gcov`.
several object files. This is the case for example when generics are
involved, when inlining is active or when declarations generate initialisation
calls. In order to take
-into account this shared code, you need to call `gcov` on all
+into account this shared code, you need to call ``gcov`` on all
source files of the tested program at once.
The list of source files might exceed the system's maximum command line
length. In order to bypass this limitation, a new mechanism has been
-implemented in `gcov`: you can now list all your project's files into a
+implemented in ``gcov``: you can now list all your project's files into a
text file, and provide this file to gcov as a parameter, preceded by a ``@``
(e.g. :samp:`gcov @mysrclist.txt`).
-Note that on AIX compiling a static library with `-fprofile-arcs` is
+Note that on AIX compiling a static library with :switch:`-fprofile-arcs` is
not supported as there can be unresolved symbols during the final link.
Profiling an Ada Program with gprof
-----------------------------------
-This section is not meant to be an exhaustive documentation of `gprof`.
+This section is not meant to be an exhaustive documentation of ``gprof``.
Full documentation for it can be found in the :title:`GNU Profiler User's Guide`
documentation that is part of this GNAT distribution.
Profiling a program helps determine the parts of a program that are executed
most often, and are therefore the most time-consuming.
-`gprof` is the standard GNU profiling tool; it has been enhanced to
+``gprof`` is the standard GNU profiling tool; it has been enhanced to
better handle Ada programs and multitasking.
It is currently supported on the following platforms
* solaris sparc/sparc64/x86
* windows x86
-In order to profile a program using `gprof`, several steps are needed:
+In order to profile a program using ``gprof``, several steps are needed:
#. Instrument the code, which requires a full recompilation of the project with the
proper switches.
#. Execute the program under the analysis conditions, i.e. with the desired
input.
-#. Analyze the results using the `gprof` tool.
+#. Analyze the results using the ``gprof`` tool.
The following sections detail the different steps, and indicate how
to interpret the results.
Running gprof
^^^^^^^^^^^^^
-The `gprof` tool is called as follow:
+The ``gprof`` tool is called as follow:
::
$ gprof [switches] [executable [data-file]]
-`gprof` supports numerous switches. The order of these
+``gprof`` supports numerous switches. The order of these
switch does not matter. The full list of options can be found in
the GNU Profiler User's Guide documentation that comes with this documentation.
.. index:: -e (gprof)
:samp:`-e {function_name}`
- The :samp:`-e {function}` option tells `gprof` not to print
- information about the function `function_name` (and its
+ The :samp:`-e {function}` option tells ``gprof`` not to print
+ information about the function ``function_name`` (and its
children...) in the call graph. The function will still be listed
as a child of any functions that call it, but its index number will be
shown as ``[not printed]``. More than one ``-e`` option may be
- given; only one `function_name` may be indicated with each ``-e``
+ given; only one ``function_name`` may be indicated with each ``-e``
option.
The :samp:`-E {function}` option works like the ``-e`` option, but
execution time spent in the function (and children who were not called from
anywhere else), will not be used to compute the percentages-of-time for
- the call graph. More than one ``-E`` option may be given; only one
- `function_name` may be indicated with each ``-E`` option.
+ the call graph. More than one :switch:`-E` option may be given; only one
+ ``function_name`` may be indicated with each :switch:`-E`` option.
.. index:: -f (gprof)
:samp:`-f {function_name}`
- The :samp:`-f {function}` option causes `gprof` to limit the
- call graph to the function `function_name` and its children (and
+ The :samp:`-f {function}` option causes ``gprof`` to limit the
+ call graph to the function ``function_name`` and its children (and
their children...). More than one ``-f`` option may be given;
- only one `function_name` may be indicated with each ``-f``
+ only one ``function_name`` may be indicated with each ``-f``
option.
only time spent in the function and its children (and their
children...) will be used to determine total-time and
percentages-of-time for the call graph. More than one ``-F`` option
- may be given; only one `function_name` may be indicated with each
+ may be given; only one ``function_name`` may be indicated with each
``-F`` option. The ``-F`` option overrides the ``-E`` option.
.. only:: PRO or GPL
It then documents the unused subprogram/data elimination feature
- and the *gnatelim* tool,
+ and the ``gnatelim`` tool,
which can reduce the size of program executables.
.. index:: -gnatp (gcc)
.. index:: -gnato (gcc)
-The gnat switch, *-gnatp* allows this default to be modified. See
+The gnat switch, :switch:`-gnatp` allows this default to be modified. See
:ref:`Run-Time_Checks`.
Our experience is that the default is suitable for most development
For validity checks, the minimal checks required by the Ada Reference
Manual (for case statements and assignments to array elements) are on
-by default. These can be suppressed by use of the *-gnatVn* switch.
+by default. These can be suppressed by use of the :switch:`-gnatVn` switch.
Note that in Ada 83, there were no validity checks, so if the Ada 83 mode
is acceptable (or when comparing GNAT performance with an Ada 83 compiler),
-it may be reasonable to routinely use *-gnatVn*. Validity checks
-are also suppressed entirely if *-gnatp* is used.
+it may be reasonable to routinely use :switch:`-gnatVn`. Validity checks
+are also suppressed entirely if :switch:`-gnatp` is used.
.. index:: Overflow checks
.. index:: Checks, overflow
.. index:: pragma Unsuppress
Note that the setting of the switches controls the default setting of
-the checks. They may be modified using either `pragma Suppress` (to
-remove checks) or `pragma Unsuppress` (to add back suppressed
+the checks. They may be modified using either ``pragma Suppress`` (to
+remove checks) or ``pragma Unsuppress`` (to add back suppressed
checks) in the program source.
exception handlers are used. The reason is that certain sections of code
have to be marked as non-abortable.
-If you use neither the `abort` statement, nor asynchronous transfer
-of control (`select ... then abort`), then this distributed overhead
+If you use neither the ``abort`` statement, nor asynchronous transfer
+of control (``select ... then abort``), then this distributed overhead
is removed, which may have a general positive effect in improving
overall performance. Especially code involving frequent use of tasking
constructs and controlled types will show much improved performance.
times, but GNAT makes absolutely no attempt to optimize, and the
generated programs are considerably larger and slower than when
optimization is enabled. You can use the
-*-O* switch (the permitted forms are *-O0*, *-O1*
-*-O2*, *-O3*, and *-Os*)
-to *gcc* to control the optimization level:
+:switch:`-O` switch (the permitted forms are :switch:`-O0`, :switch:`-O1`
+:switch:`-O2`, :switch:`-O3`, and :switch:`-Os`)
+to ``gcc`` to control the optimization level:
-* *-O0*
+* :switch:`-O0`
No optimization (the default);
generates unoptimized code but has
the fastest compilation time.
- Note that many other compilers do fairly extensive optimization
- even if 'no optimization' is specified. With gcc, it is
- very unusual to use -O0 for production if
- execution time is of any concern, since -O0
- really does mean no optimization at all. This difference between
- gcc and other compilers should be kept in mind when doing
- performance comparisons.
+ Note that many other compilers do substantial optimization even
+ if 'no optimization' is specified. With gcc, it is very unusual
+ to use :switch:`-O0` for production if execution time is of any concern,
+ since :switch:`-O0` means (almost) no optimization. This difference
+ between gcc and other compilers should be kept in mind when
+ doing performance comparisons.
-* *-O1*
+* :switch:`-O1`
Moderate optimization;
optimizes reasonably well but does not
degrade compilation time significantly.
-* *-O2*
+* :switch:`-O2`
Full optimization;
generates highly optimized code and has
the slowest compilation time.
-* *-O3*
- Full optimization as in *-O2*;
+* :switch:`-O3`
+ Full optimization as in :switch:`-O2`;
also uses more aggressive automatic inlining of subprograms within a unit
(:ref:`Inlining_of_Subprograms`) and attempts to vectorize loops.
-* *-Os*
+* :switch:`-Os`
Optimize space usage (code and data) of resulting program.
Higher optimization levels perform more global transformations on the
See the *Options That Control Optimization* section in
:title:`Using the GNU Compiler Collection (GCC)`
for details about
-the *-O* settings and a number of *-f* options that
+the :switch:`-O` settings and a number of :switch:`-f` options that
individually enable or disable specific optimizations.
-Unlike some other compilation systems, *gcc* has
+Unlike some other compilation systems, ``gcc`` has
been tested extensively at all optimization levels. There are some bugs
which appear only with optimization turned on, but there have also been
bugs which show up only in *unoptimized* code. Selecting a lower
generator, which in practice is highly reliable at all optimization
levels.
-Note regarding the use of *-O3*: The use of this optimization level
-is generally discouraged with GNAT, since it often results in larger
-executables which may run more slowly. See further discussion of this point
-in :ref:`Inlining_of_Subprograms`.
+Note regarding the use of :switch:`-O3`: The use of this optimization level
+ought not to be automatically preferred over that of level :switch:`-O2`,
+since it often results in larger executables which may run more slowly.
+See further discussion of this point in :ref:`Inlining_of_Subprograms`.
.. _Debugging_Optimized_Code:
For example, if a loop is strength-reduced, the loop
control variable may be completely eliminated and thus cannot be
displayed in the debugger.
-This can only happen at *-O2* or *-O3*.
+This can only happen at :switch:`-O2` or :switch:`-O3`.
Explicit temporary variables that you code might be eliminated at
-level *-O1* or higher.
+level :switch:`-O1` or higher.
.. index:: -g (gcc)
-The use of the *-g* switch,
+The use of the :switch:`-g` switch,
which is needed for source-level debugging,
affects the size of the program executable on disk,
and indeed the debugging information can be quite large.
anomalous situations that may arise while debugging optimized code.
These are the most common cases:
-* *The 'hopping Program Counter':* Repeated `step` or `next`
+* *The 'hopping Program Counter':* Repeated ``step`` or ``next``
commands show
the PC bouncing back and forth in the code. This may result from any of
the following optimizations:
jumps to a statement that is not supposed to be executed, simply because
it (and the code following) translates to the same thing as the code
that *was* supposed to be executed. This effect is typically seen in
- sequences that end in a jump, such as a `goto`, a `return`, or
- a `break` in a C `switch` statement.
+ sequences that end in a jump, such as a ``goto``, a ``return``, or
+ a ``break`` in a C ``switch`` statement.
* *The 'roving variable':* The symptom is an unexpected value in a variable.
There are various reasons for this effect:
strange value to see if code motion had simply moved the variable's
assignments later.
-In light of such anomalies, a recommended technique is to use *-O0*
+In light of such anomalies, a recommended technique is to use :switch:`-O0`
early in the software development cycle, when extensive debugging capabilities
-are most needed, and then move to *-O1* and later *-O2* as
+are most needed, and then move to :switch:`-O1` and later :switch:`-O2` as
the debugger becomes less critical.
-Whether to use the *-g* switch in the release version is
+Whether to use the :switch:`-g` switch in the release version is
a release management issue.
-Note that if you use *-g* you can then use the *strip* program
+Note that if you use :switch:`-g` you can then use the ``strip`` program
on the resulting executable,
which removes both debugging information and global symbols.
A call to a subprogram in the current unit is inlined if all the
following conditions are met:
-* The optimization level is at least *-O1*.
+* The optimization level is at least :switch:`-O1`.
* The called subprogram is suitable for inlining: It must be small enough
- and not contain something that *gcc* cannot support in inlined
+ and not contain something that ``gcc`` cannot support in inlined
subprograms.
.. index:: pragma Inline
.. index:: Inline
-* Any one of the following applies: `pragma Inline` is applied to the
+* Any one of the following applies: ``pragma Inline`` is applied to the
subprogram; the subprogram is local to the unit and called once from
- within it; the subprogram is small and optimization level *-O2* is
- specified; optimization level *-O3* is specified.
+ within it; the subprogram is small and optimization level :switch:`-O2` is
+ specified; optimization level :switch:`-O3` is specified.
Calls to subprograms in |withed| units are normally not inlined.
To achieve actual inlining (that is, replacement of the call by the code
in the body of the subprogram), the following conditions must all be true:
-* The optimization level is at least *-O1*.
+* The optimization level is at least :switch:`-O1`.
* The called subprogram is suitable for inlining: It must be small enough
- and not contain something that *gcc* cannot support in inlined
+ and not contain something that ``gcc`` cannot support in inlined
subprograms.
-* There is a `pragma Inline` for the subprogram.
+* There is a ``pragma Inline`` for the subprogram.
-* The *-gnatn* switch is used on the command line.
+* The :switch:`-gnatn` switch is used on the command line.
Even if all these conditions are met, it may not be possible for
the compiler to inline the call, due to the length of the body,
or features in the body that make it impossible for the compiler
to do the inlining.
-Note that specifying the *-gnatn* switch causes additional
+Note that specifying the :switch:`-gnatn` switch causes additional
compilation dependencies. Consider the following:
.. code-block:: ada
R.Q;
end Main;
-With the default behavior (no *-gnatn* switch specified), the
-compilation of the `Main` procedure depends only on its own source,
+With the default behavior (no :switch:`-gnatn` switch specified), the
+compilation of the ``Main`` procedure depends only on its own source,
:file:`main.adb`, and the spec of the package in file :file:`r.ads`. This
-means that editing the body of `R` does not require recompiling
-`Main`.
+means that editing the body of ``R`` does not require recompiling
+``Main``.
-On the other hand, the call `R.Q` is not inlined under these
-circumstances. If the *-gnatn* switch is present when `Main`
-is compiled, the call will be inlined if the body of `Q` is small
-enough, but now `Main` depends on the body of `R` in
+On the other hand, the call ``R.Q`` is not inlined under these
+circumstances. If the :switch:`-gnatn` switch is present when ``Main``
+is compiled, the call will be inlined if the body of ``Q`` is small
+enough, but now ``Main`` depends on the body of ``R`` in
:file:`r.adb` as well as on the spec. This means that if this body is edited,
the main program must be recompiled. Note that this extra dependency
-occurs whether or not the call is in fact inlined by *gcc*.
+occurs whether or not the call is in fact inlined by ``gcc``.
-The use of front end inlining with *-gnatN* generates similar
+The use of front end inlining with :switch:`-gnatN` generates similar
additional dependencies.
.. index:: -fno-inline (gcc)
-Note: The *-fno-inline* switch overrides all other conditions and ensures that
-no inlining occurs, unless requested with pragma Inline_Always for *gcc*
-back-ends. The extra dependences resulting from *-gnatn* will still be active,
+Note: The :switch:`-fno-inline` switch overrides all other conditions and ensures that
+no inlining occurs, unless requested with pragma Inline_Always for ``gcc``
+back-ends. The extra dependences resulting from :switch:`-gnatn` will still be active,
even if this switch is used to suppress the resulting inlining actions.
.. index:: -fno-inline-functions (gcc)
-Note: The *-fno-inline-functions* switch can be used to prevent
-automatic inlining of subprograms if *-O3* is used.
+Note: The :switch:`-fno-inline-functions` switch can be used to prevent
+automatic inlining of subprograms if :switch:`-O3` is used.
.. index:: -fno-inline-small-functions (gcc)
-Note: The *-fno-inline-small-functions* switch can be used to prevent
-automatic inlining of small subprograms if *-O2* is used.
+Note: The :switch:`-fno-inline-small-functions` switch can be used to prevent
+automatic inlining of small subprograms if :switch:`-O2` is used.
.. index:: -fno-inline-functions-called-once (gcc)
-Note: The *-fno-inline-functions-called-once* switch
+Note: The :switch:`-fno-inline-functions-called-once` switch
can be used to prevent inlining of subprograms local to the unit
-and called once from within it if *-O1* is used.
-
-Note regarding the use of *-O3*: *-gnatn* is made up of two
-sub-switches *-gnatn1* and *-gnatn2* that can be directly
-specified in lieu of it, *-gnatn* being translated into one of them
-based on the optimization level. With *-O2* or below, *-gnatn*
-is equivalent to *-gnatn1* which activates pragma `Inline` with
-moderate inlining across modules. With *-O3*, *-gnatn* is
-equivalent to *-gnatn2* which activates pragma `Inline` with
-full inlining across modules. If you have used pragma `Inline` in
-appropriate cases, then it is usually much better to use *-O2*
-and *-gnatn* and avoid the use of *-O3* which has the additional
+and called once from within it if :switch:`-O1` is used.
+
+Note regarding the use of :switch:`-O3`: :switch:`-gnatn` is made up of two
+sub-switches :switch:`-gnatn1` and :switch:`-gnatn2` that can be directly
+specified in lieu of it, :switch:`-gnatn` being translated into one of them
+based on the optimization level. With :switch:`-O2` or below, :switch:`-gnatn`
+is equivalent to :switch:`-gnatn1` which activates pragma ``Inline`` with
+moderate inlining across modules. With :switch:`-O3`, :switch:`-gnatn` is
+equivalent to :switch:`-gnatn2` which activates pragma ``Inline`` with
+full inlining across modules. If you have used pragma ``Inline`` in
+appropriate cases, then it is usually much better to use :switch:`-O2`
+and :switch:`-gnatn` and avoid the use of :switch:`-O3` which has the additional
effect of inlining subprograms you did not think should be inlined. We have
-found that the use of *-O3* may slow down the compilation and increase
+found that the use of :switch:`-O3` may slow down the compilation and increase
the code size by performing excessive inlining, leading to increased
instruction cache pressure from the increased code size and thus minor
performance improvements. So the bottom line here is that you should not
-automatically assume that *-O3* is better than *-O2*, and
-indeed you should use *-O3* only if tests show that it actually
+automatically assume that :switch:`-O3` is better than :switch:`-O2`, and
+indeed you should use :switch:`-O3` only if tests show that it actually
improves performance for your program.
.. _Floating_Point_Operations:
.. index:: Optimization Switches
-You can take advantage of the auto-vectorizer present in the *gcc*
+You can take advantage of the auto-vectorizer present in the ``gcc``
back end to vectorize loops with GNAT. The corresponding command line switch
-is *-ftree-vectorize* but, as it is enabled by default at *-O3*
+is :switch:`-ftree-vectorize` but, as it is enabled by default at :switch:`-O3`
and other aggressive optimizations helpful for vectorization also are enabled
-by default at this level, using *-O3* directly is recommended.
+by default at this level, using :switch:`-O3` directly is recommended.
You also need to make sure that the target architecture features a supported
SIMD instruction set. For example, for the x86 architecture, you should at
-least specify *-msse2* to get significant vectorization (but you don't
+least specify :switch:`-msse2` to get significant vectorization (but you don't
need to specify it for x86-64 as it is part of the base 64-bit architecture).
-Similarly, for the PowerPC architecture, you should specify *-maltivec*.
+Similarly, for the PowerPC architecture, you should specify :switch:`-maltivec`.
-The preferred loop form for vectorization is the `for` iteration scheme.
-Loops with a `while` iteration scheme can also be vectorized if they are
+The preferred loop form for vectorization is the ``for`` iteration scheme.
+Loops with a ``while`` iteration scheme can also be vectorized if they are
very simple, but the vectorizer will quickly give up otherwise. With either
iteration scheme, the flow of control must be straight, in particular no
-`exit` statement may appear in the loop body. The loop may however
+``exit`` statement may appear in the loop body. The loop may however
contain a single nested loop, if it can be vectorized when considered alone:
.. code-block:: ada
The vectorizable operations depend on the targeted SIMD instruction set, but
the adding and some of the multiplying operators are generally supported, as
well as the logical operators for modular types. Note that compiling
-with *-gnatp* might well reveal cases where some checks do thwart
+with :switch:`-gnatp` might well reveal cases where some checks do thwart
vectorization.
Type conversions may also prevent vectorization if they involve semantics that
Integer (S'Truncation (F))
-if `S` is the subtype of floating-point object `F`.
+if ``S`` is the subtype of floating-point object ``F``.
In most cases, the vectorizable loops are loops that iterate over arrays.
All kinds of array types are supported, i.e. constrained array types with
fix things up at run time.
It is possible to specify that a given loop should be subject to vectorization
-preferably to other optimizations by means of pragma `Loop_Optimize`:
+preferably to other optimizations by means of pragma ``Loop_Optimize``:
.. code-block:: ada
.. index:: Optimization Switches
-Since `GNAT` uses the *gcc* back end, all the specialized
-*gcc* optimization switches are potentially usable. These switches
+Since GNAT uses the ``gcc`` back end, all the specialized
+``gcc`` optimization switches are potentially usable. These switches
have not been extensively tested with GNAT but can generally be expected
-to work. Examples of switches in this category are *-funroll-loops*
-and the various target-specific *-m* options (in particular, it has
-been observed that *-march=xxx* can significantly improve performance
+to work. Examples of switches in this category are :switch:`-funroll-loops`
+and the various target-specific :switch:`-m` options (in particular, it has
+been observed that :switch:`-march=xxx` can significantly improve performance
on appropriate machines). For full details of these switches, see
-the `Submodel Options` section in the `Hardware Models and Configurations`
+the *Submodel Options* section in the *Hardware Models and Configurations*
chapter of :title:`Using the GNU Compiler Collection (GCC)`.
...
end R;
-In this example, since the variable `Int1V` can only access objects
-of type `Int1`, and `Int2V` can only access objects of type
-`Int2`, there is no possibility that the assignment to
-`Int2V.all` affects the value of `Int1V.all`. This means that
-the compiler optimizer can "know" that the value `Int1V.all` is constant
+In this example, since the variable ``Int1V`` can only access objects
+of type ``Int1``, and ``Int2V`` can only access objects of type
+``Int2``, there is no possibility that the assignment to
+``Int2V.all`` affects the value of ``Int1V.all``. This means that
+the compiler optimizer can "know" that the value ``Int1V.all`` is constant
for all iterations of the loop and avoid the extra memory reference
required to dereference it each time through the loop.
This kind of optimization, called strict aliasing analysis, is
-triggered by specifying an optimization level of *-O2* or
-higher or *-Os* and allows `GNAT` to generate more efficient code
+triggered by specifying an optimization level of :switch:`-O2` or
+higher or :switch:`-Os` and allows GNAT to generate more efficient code
when access values are involved.
However, although this optimization is always correct in terms of
the formal semantics of the Ada Reference Manual, difficulties can
-arise if features like `Unchecked_Conversion` are used to break
+arise if features like ``Unchecked_Conversion`` are used to break
the typing system. Consider the following complete program example:
.. code-block:: ada
put_line (int1'image (v1.all));
end;
-This program prints out 0 in *-O0* or *-O1*
-mode, but it prints out 1 in *-O2* mode. That's
+This program prints out 0 in :switch:`-O0` or :switch:`-O1`
+mode, but it prints out 1 in :switch:`-O2` mode. That's
because in strict aliasing mode, the compiler can and
-does assume that the assignment to `v2.all` could not
-affect the value of `v1.all`, since different types
+does assume that the assignment to ``v2.all`` could not
+affect the value of ``v1.all``, since different types
are involved.
This behavior is not a case of non-conformance with the standard, since
bit pattern is not a correct value of the target type can result in an
abnormal value and attempting to reference an abnormal value makes the
execution of a program erroneous. That's the case here since the result
-does not point to an object of type `int2`. This means that the
+does not point to an object of type ``int2``. This means that the
effect is entirely unpredictable.
However, although that explanation may satisfy a language
p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);"
Unfortunately the problem is recognized when compiling the body of
-package `p2`, but the actual "bad" code is generated while
-compiling the body of `m` and this latter compilation does not see
-the suspicious `Unchecked_Conversion`.
+package ``p2``, but the actual "bad" code is generated while
+compiling the body of ``m`` and this latter compilation does not see
+the suspicious ``Unchecked_Conversion``.
As implied by the warning message, there are approaches you can use to
avoid the unwanted strict aliasing optimization in a case like this.
-One possibility is to simply avoid the use of *-O2*, but
+One possibility is to simply avoid the use of :switch:`-O2`, but
that is a bit drastic, since it throws away a number of useful
optimizations that do not involve strict aliasing assumptions.
A less drastic approach is to compile the program using the
-option *-fno-strict-aliasing*. Actually it is only the
+option :switch:`-fno-strict-aliasing`. Actually it is only the
unit containing the dereferencing of the suspicious pointer
that needs to be compiled. So in this case, if we compile
-unit `m` with this switch, then we get the expected
+unit ``m`` with this switch, then we get the expected
value of zero printed. Analyzing which units might need
the switch can be painful, so a more reasonable approach
-is to compile the entire program with options *-O2*
-and *-fno-strict-aliasing*. If the performance is
+is to compile the entire program with options :switch:`-O2`
+and :switch:`-fno-strict-aliasing`. If the performance is
satisfactory with this combination of options, then the
advantage is that the entire issue of possible "wrong"
optimization due to strict aliasing is avoided.
To avoid the use of compiler switches, the configuration
-pragma `No_Strict_Aliasing` with no parameters may be
+pragma ``No_Strict_Aliasing`` with no parameters may be
used to specify that for all access types, the strict
aliasing optimization should be suppressed.
First, if a careful analysis of uses of the pointer shows
that there are no possible problematic references, then
the warning can be suppressed by bracketing the
-instantiation of `Unchecked_Conversion` to turn
+instantiation of ``Unchecked_Conversion`` to turn
the warning off:
.. code-block:: ada
The first possibility is to move the instantiation of unchecked
conversion to the unit in which the type is declared. In
this example, we would move the instantiation of
-`Unchecked_Conversion` from the body of package
-`p2` to the spec of package `p1`. Now the
+``Unchecked_Conversion`` from the body of package
+``p2`` to the spec of package ``p1``. Now the
warning disappears. That's because any use of the
access type knows there is a suspicious unchecked
conversion, and the strict aliasing optimization
If it is not practical to move the unchecked conversion to the same unit
in which the destination access type is declared (perhaps because the
source type is not visible in that unit), you may use pragma
-`No_Strict_Aliasing` for the type. This pragma must occur in the
+``No_Strict_Aliasing`` for the type. This pragma must occur in the
same declarative sequence as the declaration of the access type:
.. code-block:: ada
pragma No_Strict_Aliasing (a2);
Here again, the compiler now knows that the strict aliasing optimization
-should be suppressed for any reference to type `a2` and the
+should be suppressed for any reference to type ``a2`` and the
expected behavior is obtained.
Finally, note that although the compiler can generate warnings for
application code where the time is increased by up to 5% by turning
this optimization off. If you have code that includes significant
usage of unchecked conversion, you might want to just stick with
-*-O1* and avoid the entire issue. If you get adequate
+:switch:`-O1` and avoid the entire issue. If you get adequate
performance at this level of optimization level, that's probably
the safest approach. If tests show that you really need higher
-levels of optimization, then you can experiment with *-O2*
-and *-O2 -fno-strict-aliasing* to see how much effect this
+levels of optimization, then you can experiment with :switch:`-O2`
+and :switch:`-O2 -fno-strict-aliasing` to see how much effect this
has on size and speed of the code. If you really need to use
-*-O2* with strict aliasing in effect, then you should
+:switch:`-O2` with strict aliasing in effect, then you should
review any uses of unchecked conversion of access types,
particularly if you are getting the warnings described above.
end;
where Get_String is a C function that uses the address in Temp to
-modify the variable `Name`. This code is dubious, and arguably
+modify the variable ``Name``. This code is dubious, and arguably
erroneous, and the compiler would be entitled to assume that
-`Name` is never modified, and generate code accordingly.
+``Name`` is never modified, and generate code accordingly.
However, in practice, this would cause some existing code that
seems to work with no optimization to start failing at high
...
X := RV.B;
-You cannot assume that the reference to `RV.B`
+You cannot assume that the reference to ``RV.B``
will read the entire 32-bit
variable with a single load instruction. It is perfectly legitimate if
the hardware allows it to do a byte read of just the B field. This read
examine the assembly language and see a full 32-bit load, this might
change in a future version of the compiler.
-If your application requires that all accesses to `RV` in this
+If your application requires that all accesses to ``RV`` in this
example be full 32-bit loads, you need to make a copy for the access
as in:
.. _Text_IO_Suggestions:
-`Text_IO` Suggestions
----------------------
+``Text_IO`` Suggestions
+-----------------------
.. index:: Text_IO and performance
-The `Ada.Text_IO` package has fairly high overheads due in part to
+The ``Ada.Text_IO`` package has fairly high overheads due in part to
the requirement of maintaining page and line counts. If performance
-is critical, a recommendation is to use `Stream_IO` instead of
-`Text_IO` for volume output, since this package has less overhead.
+is critical, a recommendation is to use ``Stream_IO`` instead of
+``Text_IO`` for volume output, since this package has less overhead.
-If `Text_IO` must be used, note that by default output to the standard
+If ``Text_IO`` must be used, note that by default output to the standard
output and standard error files is unbuffered (this provides better
behavior when output statements are used for debugging, or if the
progress of a program is observed by tracking the output, e.g. by
using the Unix *tail -f* command to watch redirected output.
-If you are generating large volumes of output with `Text_IO` and
+If you are generating large volumes of output with ``Text_IO`` and
performance is an important factor, use a designated file instead
of the standard output file, or change the standard output file to
-be buffered using `Interfaces.C_Streams.setvbuf`.
+be buffered using ``Interfaces.C_Streams.setvbuf``.
.. _Reducing_Size_of_Executables_with_Unused_Subprogram/Data_Elimination:
In order to do this, it has to work with objects compiled with the
following options:
-*-ffunction-sections* *-fdata-sections*.
+:switch:`-ffunction-sections` :switch:`-fdata-sections`.
These options are usable with C and Ada files.
They will place respectively each
Once the objects and static libraries are created with these options, the
linker can perform the dead code elimination. You can do this by setting
-the *-Wl,--gc-sections* option to gcc command or in the
-*-largs* section of *gnatmake*. This will perform a
+the :switch:`-Wl,--gc-sections` option to gcc command or in the
+:switch:`-largs` section of ``gnatmake``. This will perform a
garbage collection of code and data never referenced.
-If the linker performs a partial link (*-r* linker option), then you
-will need to provide the entry point using the *-e* / *--entry*
+If the linker performs a partial link (:switch:`-r` linker option), then you
+will need to provide the entry point using the :switch:`-e` / :switch:`--entry`
linker option.
-Note that objects compiled without the *-ffunction-sections* and
-*-fdata-sections* options can still be linked with the executable.
+Note that objects compiled without the :switch:`-ffunction-sections` and
+:switch:`-fdata-sections` options can still be linked with the executable.
However, no dead code elimination will be performed on those objects (they will
be linked as is).
end Unused;
end Aux;
-`Unused` and `Unused_Data` are never referenced in this code
+``Unused`` and ``Unused_Data`` are never referenced in this code
excerpt, and hence they may be safely removed from the final executable.
::
02005350 T aux__used
0201ffe0 B aux__used_data
-It can be observed that the procedure `Unused` and the object
-`Unused_Data` are removed by the linker when using the
+It can be observed that the procedure ``Unused`` and the object
+``Unused_Data`` are removed by the linker when using the
appropriate options.
.. only:: PRO or GPL
.. _Reducing_Size_of_Ada_Executables_with_gnatelim:
- Reducing Size of Ada Executables with `gnatelim`
- ------------------------------------------------
+ Reducing Size of Ada Executables with ``gnatelim``
+ --------------------------------------------------
.. index:: gnatelim
- This section describes *gnatelim*, a tool which detects unused
+ This section describes ``gnatelim``, a tool which detects unused
subprograms and helps the compiler to create a smaller executable for your
program.
- *gnatelim* is a project-aware tool.
+ ``gnatelim`` is a project-aware tool.
(See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches but note that *gnatelim* does not support
+ the project-related switches but note that ``gnatelim`` does not support
the :samp:`-U`, :samp:`-U {main_unit}`, :samp:`--subdirs={dir}`, or
:samp:`--no_objects_dir` switches.)
The project file package that can specify
- *gnatelim* switches is named ``Eliminate``.
+ ``gnatelim`` switches is named ``Eliminate``.
.. _About_gnatelim:
- About `gnatelim`
- ^^^^^^^^^^^^^^^^
+ About ``gnatelim``
+ ^^^^^^^^^^^^^^^^^^
When a program shares a set of Ada
packages with other programs, it may happen that this program uses
only a fraction of the subprograms defined in these packages. The code
created for these unused subprograms increases the size of the executable.
- `gnatelim` tracks unused subprograms in an Ada program and
- outputs a list of GNAT-specific pragmas `Eliminate` marking all the
+ ``gnatelim`` tracks unused subprograms in an Ada program and
+ outputs a list of GNAT-specific pragmas ``Eliminate`` marking all the
subprograms that are declared but never called. By placing the list of
- `Eliminate` pragmas in the GNAT configuration file :file:`gnat.adc` and
+ ``Eliminate`` pragmas in the GNAT configuration file :file:`gnat.adc` and
recompiling your program, you may decrease the size of its executable,
because the compiler will not generate the code for 'eliminated' subprograms.
- See `Pragma_Eliminate` in the :title:`GNAT_Reference_Manual` for more
+ See ``Pragma_Eliminate`` in the :title:`GNAT_Reference_Manual` for more
information about this pragma.
- `gnatelim` needs as its input data the name of the main subprogram.
+ ``gnatelim`` needs as its input data the name of the main subprogram.
- If a set of source files is specified as `gnatelim` arguments, it
+ If a set of source files is specified as ``gnatelim`` arguments, it
treats these files as a complete set of sources making up a program to
analyse, and analyses only these sources.
- After a full successful build of the main subprogram `gnatelim` can be
+ After a full successful build of the main subprogram ``gnatelim`` can be
called without specifying sources to analyse, in this case it computes
the source closure of the main unit from the :file:`ALI` files.
- If the set of sources to be processed by `gnatelim` contains sources with
+ If the set of sources to be processed by ``gnatelim`` contains sources with
preprocessing directives
then the needed options should be provided to run preprocessor as a part of
- the *gnatelim* call, and the generated set of pragmas `Eliminate`
+ the ``gnatelim`` call, and the generated set of pragmas ``Eliminate``
will correspond to preprocessed sources.
The following command will create the set of :file:`ALI` files needed for
- `gnatelim`:
+ ``gnatelim``:
::
$ gnatmake -c Main_Prog
- Note that `gnatelim` does not need object files.
+ Note that ``gnatelim`` does not need object files.
.. _Running_gnatelim:
- Running `gnatelim`
- ^^^^^^^^^^^^^^^^^^
+ Running ``gnatelim``
+ ^^^^^^^^^^^^^^^^^^^^
- `gnatelim` has the following command-line interface:
+ ``gnatelim`` has the following command-line interface:
::
- $ gnatelim [`switches`] -main=`main_unit_name` {`filename`} [-cargs `gcc_switches`]
+ $ gnatelim [switches] -main=`main_unit_name {filename} [-cargs gcc_switches]
- `main_unit_name` should be a name of a source file that contains the main
+ ``main_unit_name`` should be a name of a source file that contains the main
subprogram of a program (partition).
- Each `filename` is the name (including the extension) of a source
+ Each ``filename`` is the name (including the extension) of a source
file to process. 'Wildcards' are allowed, and
the file name may contain path information.
- `gcc_switches` is a list of switches for
- *gcc*. They will be passed on to all compiler invocations made by
- *gnatelim* to generate the ASIS trees. Here you can provide
- *-I* switches to form the source search path,
- use the *-gnatec* switch to set the configuration file,
- use the *-gnat05* switch if sources should be compiled in
+ ``gcc_switches`` is a list of switches for
+ ``gcc``. They will be passed on to all compiler invocations made by
+ ``gnatelim`` to generate the ASIS trees. Here you can provide
+ :switch:`-I` switches to form the source search path,
+ use the :switch:`-gnatec` switch to set the configuration file,
+ use the :switch:`-gnat05` switch if sources should be compiled in
Ada 2005 mode etc.
- `gnatelim` has the following switches:
+ ``gnatelim`` has the following switches:
.. index:: --version (gnatelim)
.. index:: -X (gnatelim)
:samp:`-X{name}={value}`
- Indicates that external variable `name` in the argument project
- has the value `value`. Has no effect if no project is specified as
+ Indicates that external variable ``name`` in the argument project
+ has the value ``value``. Has no effect if no project is specified as
tool argument.
:samp:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -files (gnatelim)
Take the argument source files from the specified file. This file should be an
ordinary text file containing file names separated by spaces or
line breaks. You can use this switch more than once in the same call to
- *gnatelim*. You also can combine this switch with
+ ``gnatelim``. You also can combine this switch with
an explicit list of files.
:samp:`-o={report_file}`
- Put *gnatelim* output into a specified file. If this file already exists,
- it is overridden. If this switch is not used, *gnatelim* outputs its results
+ Put ``gnatelim`` output into a specified file. If this file already exists,
+ it is overridden. If this switch is not used, ``gnatelim`` outputs its results
into :file:`stderr`
.. index:: -j (gnatelim)
:samp:`-j{n}`
- Use `n` processes to carry out the tree creations (internal representations
+ Use ``n`` processes to carry out the tree creations (internal representations
of the argument sources). On a multiprocessor machine this speeds up processing
- of big sets of argument sources. If `n` is 0, then the maximum number of
+ of big sets of argument sources. If ``n`` is 0, then the maximum number of
parallel tree creations is the number of core processors on the platform.
.. index:: -q (gnatelim)
:samp:`-q`
- Quiet mode: by default `gnatelim` outputs to the standard error
+ Quiet mode: by default ``gnatelim`` outputs to the standard error
stream the number of program units left to be processed. This option turns
this trace off.
.. index:: -v (gnatelim)
:samp:`-v`
- Verbose mode: `gnatelim` version information is printed as Ada
+ Verbose mode: ``gnatelim`` version information is printed as Ada
comments to the standard output stream. Also, in addition to the number of
- program units left `gnatelim` will output the name of the current unit
+ program units left ``gnatelim`` will output the name of the current unit
being processed.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If some program uses a precompiled Ada library, it can be processed by
- `gnatelim` in a usual way. `gnatelim` will newer generate an
+ ``gnatelim`` in a usual way. ``gnatelim`` will newer generate an
Eliminate pragma for a subprogram if the body of this subprogram has not
been analysed, this is a typical case for subprograms from precompiled
- libraries. Switch *-wq* may be used to suppress
+ libraries. Switch :switch:`-wq` may be used to suppress
warnings about missing source files and non-analyzed subprogram bodies
that can be generated when processing precompiled Ada libraries.
Correcting the List of Eliminate Pragmas
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- In some rare cases `gnatelim` may try to eliminate
+ In some rare cases ``gnatelim`` may try to eliminate
subprograms that are actually called in the program. In this case, the
compiler will generate an error message of the form:
main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5
- You will need to manually remove the wrong `Eliminate` pragmas from
+ You will need to manually remove the wrong ``Eliminate`` pragmas from
the configuration file indicated in the error message. You should recompile
your program from scratch after that, because you need a consistent
configuration file(s) during the entire compilation.
$ gnatmake -f main_prog
- (Use the *-f* option for *gnatmake* to
+ (Use the :switch:`-f` option for ``gnatmake`` to
recompile everything
- with the set of pragmas `Eliminate` that you have obtained with
- *gnatelim*).
+ with the set of pragmas ``Eliminate`` that you have obtained with
+ ``gnatelim``).
- Be aware that the set of `Eliminate` pragmas is specific to each
- program. It is not recommended to merge sets of `Eliminate`
+ Be aware that the set of ``Eliminate`` pragmas is specific to each
+ program. It is not recommended to merge sets of ``Eliminate``
pragmas created for different programs in one configuration file.
.. _Summary_of_the_gnatelim_Usage_Cycle:
- Summary of the `gnatelim` Usage Cycle
- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ Summary of the ``gnatelim`` Usage Cycle
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Here is a quick summary of the steps to be taken in order to reduce
- the size of your executables with `gnatelim`. You may use
+ the size of your executables with ``gnatelim``. You may use
other GNAT options to control the optimization level,
to produce the debugging information, to set search path, etc.
$ gnatmake -c main_prog
- * Generate a list of `Eliminate` pragmas in default configuration file
+ * Generate a list of ``Eliminate`` pragmas in default configuration file
:file:`gnat.adc` in the current directory
::
...
A := A + 1;
-If `A` has the value `Integer'Last`, then the addition may cause
-overflow since the result is out of range of the type `Integer`.
-In this case `Constraint_Error` will be raised if checks are
+If ``A`` has the value ``Integer'Last``, then the addition may cause
+overflow since the result is out of range of the type ``Integer``.
+In this case ``Constraint_Error`` will be raised if checks are
enabled.
A trickier situation arises in examples like the following:
...
A := (A + 1) + C;
-where `A` is `Integer'Last` and `C` is `-1`.
+where ``A`` is ``Integer'Last`` and ``C`` is ``-1``.
Now the final result of the expression on the right hand side is
-`Integer'Last` which is in range, but the question arises whether the
-intermediate addition of `(A + 1)` raises an overflow error.
+``Integer'Last`` which is in range, but the question arises whether the
+intermediate addition of ``(A + 1)`` raises an overflow error.
The (perhaps surprising) answer is that the Ada language
definition does not answer this question. Instead it leaves
it up to the implementation to do one of two things if overflow
checks are enabled.
-* raise an exception (`Constraint_Error`), or
+* raise an exception (``Constraint_Error``), or
* yield the correct mathematical result which is then used in
subsequent operations.
If the compiler chooses the first approach, then the assignment of this
-example will indeed raise `Constraint_Error` if overflow checking is
+example will indeed raise ``Constraint_Error`` if overflow checking is
enabled, or result in erroneous execution if overflow checks are suppressed.
But if the compiler
One often wants to regard arithmetic in a context like this from
a mathematical point of view. So for example, if the two actual parameters
-for a call to `P` are both `Integer'Last`, then
+for a call to ``P`` are both ``Integer'Last``, then
the precondition should be regarded as False. If we are executing
in a mode with run-time checks enabled for preconditions, then we would
like this precondition to fail, rather than raising an exception
because of the intermediate overflow.
However, the language definition leaves the specification of
-whether the above condition fails (raising `Assert_Error`) or
-causes an intermediate overflow (raising `Constraint_Error`)
+whether the above condition fails (raising ``Assert_Error``) or
+causes an intermediate overflow (raising ``Constraint_Error``)
up to the implementation.
The situation is worse in a case such as the following:
The three modes are:
-* *Use base type for intermediate operations* (`STRICT`)
+* *Use base type for intermediate operations* (``STRICT``)
In this mode, all intermediate results for predefined arithmetic
operators are computed using the base type, and the result must
enabled) or the execution is erroneous (if overflow checks are suppressed).
This is the normal default mode.
-* *Most intermediate overflows avoided* (`MINIMIZED`)
+* *Most intermediate overflows avoided* (``MINIMIZED``)
In this mode, the compiler attempts to avoid intermediate overflows by
- using a larger integer type, typically `Long_Long_Integer`,
+ using a larger integer type, typically ``Long_Long_Integer``,
as the type in which arithmetic is
performed for predefined arithmetic operators. This may be slightly more
expensive at
the cost is negligible on modern 64-bit machines. For the examples given
earlier, no intermediate overflows would have resulted in exceptions,
since the intermediate results are all in the range of
- `Long_Long_Integer` (typically 64-bits on nearly all implementations
+ ``Long_Long_Integer`` (typically 64-bits on nearly all implementations
of GNAT). In addition, if checks are enabled, this reduces the number of
checks that must be made, so this choice may actually result in an
improvement in space and time behavior.
- However, there are cases where `Long_Long_Integer` is not large
+ However, there are cases where ``Long_Long_Integer`` is not large
enough, consider the following example:
.. code-block:: ada
procedure R (A, B, C, D : Integer) with
Pre => (A**2 * B**2) / (C**2 * D**2) <= 10;
- where `A` = `B` = `C` = `D` = `Integer'Last`.
+ where ``A`` = ``B`` = ``C`` = ``D`` = ``Integer'Last``.
Now the intermediate results are
- out of the range of `Long_Long_Integer` even though the final result
+ out of the range of ``Long_Long_Integer`` even though the final result
is in range and the precondition is True (from a mathematical point
of view). In such a case, operating in this mode, an overflow occurs
for the intermediate computation (which is why this mode
an exception is raised if overflow checks are enabled, and the
execution is erroneous if overflow checks are suppressed.
-* *All intermediate overflows avoided* (`ELIMINATED`)
+* *All intermediate overflows avoided* (``ELIMINATED``)
In this mode, the compiler avoids all intermediate overflows
by using arbitrary precision arithmetic as required. In this
- mode, the above example with `A**2 * B**2` would
+ mode, the above example with ``A**2 * B**2`` would
not cause intermediate overflow, because the intermediate result
would be evaluated using sufficient precision, and the result
of evaluating the precondition would be True.
Note that in this mode, the behavior is unaffected by whether or
not overflow checks are suppressed, since overflow does not occur.
It is possible for gigantic intermediate expressions to raise
- `Storage_Error` as a result of attempting to compute the
- results of such expressions (e.g. `Integer'Last ** Integer'Last`)
+ ``Storage_Error`` as a result of attempting to compute the
+ results of such expressions (e.g. ``Integer'Last ** Integer'Last``)
but overflow is impossible.
are enabled
then fixed-point values are always checked for overflow against the
base type for intermediate expressions (that is such checks always
-operate in the equivalent of `STRICT` mode).
+operate in the equivalent of ``STRICT`` mode).
-For floating-point, on nearly all architectures, `Machine_Overflows`
+For floating-point, on nearly all architectures, ``Machine_Overflows``
is False, and IEEE infinities are generated, so overflow exceptions
are never raised. If you want to avoid infinities, and check that
final results of expressions are in range, then you can declare a
.. index:: pragma Overflow_Mode
The desired mode of for handling intermediate overflow can be specified using
-either the `Overflow_Mode` pragma or an equivalent compiler switch.
+either the ``Overflow_Mode`` pragma or an equivalent compiler switch.
The pragma has the form
.. code-block:: ada
pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]);
-where `MODE` is one of
+where ``MODE`` is one of
-* `STRICT`: intermediate overflows checked (using base type)
-* `MINIMIZED`: minimize intermediate overflows
-* `ELIMINATED`: eliminate intermediate overflows
+* ``STRICT``: intermediate overflows checked (using base type)
+* ``MINIMIZED``: minimize intermediate overflows
+* ``ELIMINATED``: eliminate intermediate overflows
-The case is ignored, so `MINIMIZED`, `Minimized` and
-`minimized` all have the same effect.
+The case is ignored, so ``MINIMIZED``, ``Minimized`` and
+``minimized`` all have the same effect.
-If only the `General` parameter is present, then the given `MODE`
-applies
+If only the ``General`` parameter is present, then the given ``MODE`` applies
to expressions both within and outside assertions. If both arguments
-are present, then `General` applies to expressions outside assertions,
-and `Assertions` applies to expressions within assertions. For example:
+are present, then ``General`` applies to expressions outside assertions,
+and ``Assertions`` applies to expressions within assertions. For example:
.. code-block:: ada
the behavior at run time matches the expected mathematical
behavior.
-The `Overflow_Mode` pragma has the same scoping and placement
-rules as pragma `Suppress`, so it can occur either as a
+The ``Overflow_Mode`` pragma has the same scoping and placement
+rules as pragma ``Suppress``, so it can occur either as a
configuration pragma, specifying a default for the whole
program, or in a declarative scope, where it applies to the
remaining declarations and statements in that scope.
-Note that pragma `Overflow_Mode` does not affect whether
+Note that pragma ``Overflow_Mode`` does not affect whether
overflow checks are enabled or suppressed. It only controls the
method used to compute intermediate values. To control whether
-overflow checking is enabled or suppressed, use pragma `Suppress`
-or `Unsuppress` in the usual manner
+overflow checking is enabled or suppressed, use pragma ``Suppress``
+or ``Unsuppress`` in the usual manner.
.. index:: -gnato? (gcc)
.. index:: -gnato?? (gcc)
-Additionally, a compiler switch *-gnato?* or *-gnato??*
+Additionally, a compiler switch :switch:`-gnato?` or :switch:`-gnato??`
can be used to control the checking mode default (which can be subsequently
overridden using pragmas).
Here ``?`` is one of the digits ``1`` through ``3``:
- ====== =====================================================
- ``1`` use base type for intermediate operations (`STRICT`)
- ``2`` minimize intermediate overflows (`MINIMIZED`)
- ``3`` eliminate intermediate overflows (`ELIMINATED`)
- ====== =====================================================
+ ====== ======================================================
+ ``1`` use base type for intermediate operations (``STRICT``)
+ ``2`` minimize intermediate overflows (``MINIMIZED``)
+ ``3`` eliminate intermediate overflows (``ELIMINATED``)
+ ====== ======================================================
As with the pragma, if only one digit appears then it applies to all
cases; if two digits are given, then the first applies outside
assertions, and the second within assertions. Thus the equivalent
of the example pragma above would be
-*-gnato23*.
+:switch:`-gnato23`.
-If no digits follow the *-gnato*, then it is equivalent to
-*-gnato11*,
+If no digits follow the :switch:`-gnato`, then it is equivalent to
+:switch:`-gnato11`,
causing all intermediate operations to be computed using the base
-type (`STRICT` mode).
+type (``STRICT`` mode).
.. _Default_Settings:
.. Sphinx allows no emphasis within :index: role. As a workaround we
point the index to "switch" and use emphasis for "-gnato".
-The :index:`switch <-gnato (gcc)>` *-gnato* (with no digits following)
+The :index:`switch <-gnato (gcc)>` :switch:`-gnato` (with no digits following)
is equivalent to
::
which causes overflow checking of all intermediate overflows
both inside and outside assertions against the base type.
-The pragma `Suppress (Overflow_Check)` disables overflow
+The pragma ``Suppress (Overflow_Check)`` disables overflow
checking, but it has no effect on the method used for computing
intermediate results.
-The pragma `Unsuppress (Overflow_Check)` enables overflow
+The pragma ``Unsuppress (Overflow_Check)`` enables overflow
checking, but it has no effect on the method used for computing
intermediate results.
Implementation Notes
--------------------
-In practice on typical 64-bit machines, the `MINIMIZED` mode is
+In practice on typical 64-bit machines, the ``MINIMIZED`` mode is
reasonably efficient, and can be generally used. It also helps
to ensure compatibility with code imported from some other
compiler to GNAT.
-Setting all intermediate overflows checking (`CHECKED` mode)
+Setting all intermediate overflows checking (``CHECKED`` mode)
makes sense if you want to
make sure that your code is compatible with any other possible
Ada implementation. This may be useful in ensuring portability
The Ada standard allows the reassociation of expressions at
the same precedence level if no parentheses are present. For
-example, `A+B+C` parses as though it were `(A+B)+C`, but
-the compiler can reintepret this as `A+(B+C)`, possibly
+example, ``A+B+C`` parses as though it were ``(A+B)+C``, but
+the compiler can reintepret this as ``A+(B+C)``, possibly
introducing or eliminating an overflow exception. The GNAT
compiler never takes advantage of this freedom, and the
-expression `A+B+C` will be evaluated as `(A+B)+C`.
+expression ``A+B+C`` will be evaluated as ``(A+B)+C``.
If you need the other order, you can write the parentheses
-explicitly `A+(B+C)` and GNAT will respect this order.
+explicitly ``A+(B+C)`` and GNAT will respect this order.
-The use of `ELIMINATED` mode will cause the compiler to
+The use of ``ELIMINATED`` mode will cause the compiler to
automatically include an appropriate arbitrary precision
integer arithmetic package. The compiler will make calls
to this package, though only in cases where it cannot be
-sure that `Long_Long_Integer` is sufficient to guard against
+sure that ``Long_Long_Integer`` is sufficient to guard against
intermediate overflows. This package does not use dynamic
alllocation, but it does use the secondary stack, so an
appropriate secondary stack package must be present (this
is always true for standard full Ada, but may require
specific steps for restricted run times such as ZFP).
-Although `ELIMINATED` mode causes expressions to use arbitrary
+Although ``ELIMINATED`` mode causes expressions to use arbitrary
precision arithmetic, avoiding overflow, the final result
must be in an appropriate range. This is true even if the
-final result is of type `[Long_[Long_]]Integer'Base`, which
+final result is of type ``[Long_[Long_]]Integer'Base``, which
still has the same bounds as its associated constrained
type at run-time.
-Currently, the `ELIMINATED` mode is only available on target
-platforms for which `Long_Long_Integer` is 64-bits (nearly all GNAT
+Currently, the ``ELIMINATED`` mode is only available on target
+platforms for which ``Long_Long_Integer`` is 64-bits (nearly all GNAT
platforms).
This feature depends on Ada 2012 aspect specifications, and is available from
version 7.0.1 of GNAT onwards.
-The GNAT-specific aspect `Dimension_System`
-allows you to define a system of units; the aspect `Dimension`
+The GNAT-specific aspect ``Dimension_System``
+allows you to define a system of units; the aspect ``Dimension``
then allows the user to declare dimensioned quantities within a given system.
(These aspects are described in the *Implementation Defined Aspects*
chapter of the *GNAT Reference Manual*).
.. index:: MKS_Type type
The simplest way to impose dimensionality checking on a computation is to make
-use of the package `System.Dim.Mks`,
+use of the package ``System.Dim.Mks``,
which is part of the GNAT library. This
-package defines a floating-point type `MKS_Type`,
+package defines a floating-point type ``MKS_Type``,
for which a sequence of
dimension names are specified, together with their conventional abbreviations.
The following should be read together with the full specification of the
with
Dimension => (Symbol => 'm', Meter => 1, others => 0);
-and similarly for `Mass`, `Time`, `Electric_Current`,
-`Thermodynamic_Temperature`, `Amount_Of_Substance`, and
-`Luminous_Intensity` (the standard set of units of the SI system).
+and similarly for ``Mass``, ``Time``, ``Electric_Current``,
+``Thermodynamic_Temperature``, ``Amount_Of_Substance``, and
+``Luminous_Intensity`` (the standard set of units of the SI system).
The package also defines conventional names for values of each unit, for
example:
.. index:: -fstack-check (gcc)
-For most operating systems, *gcc* does not perform stack overflow
+For most operating systems, ``gcc`` does not perform stack overflow
checking by default. This means that if the main environment task or
some other task exceeds the available stack space, then unpredictable
behavior will occur. Most native systems offer some level of protection by
the exception propagation code. Enabling stack checking avoids
such situations.
-To activate stack checking, compile all units with the gcc option
-`-fstack-check`. For example:
+To activate stack checking, compile all units with the ``gcc`` option
+:switch:`-fstack-check`. For example:
::
Units compiled with this option will generate extra instructions to check
that any use of the stack (for procedure calls or for declaring local
variables in declare blocks) does not exceed the available stack space.
-If the space is exceeded, then a `Storage_Error` exception is raised.
+If the space is exceeded, then a ``Storage_Error`` exception is raised.
For declared tasks, the stack size is controlled by the size
-given in an applicable `Storage_Size` pragma or by the value specified
+given in an applicable ``Storage_Size`` pragma or by the value specified
at bind time with ``-d`` (:ref:`Switches_for_gnatbind`) or is set to
the default size as defined in the GNAT runtime otherwise.
* The name of the function.
* A number of bytes.
-* One or more qualifiers: `static`, `dynamic`, `bounded`.
+* One or more qualifiers: ``static``, ``dynamic``, ``bounded``.
The second field corresponds to the size of the known part of the function
frame.
-The qualifier `static` means that the function frame size
+The qualifier ``static`` means that the function frame size
is purely static.
It usually means that all local variables have a static size.
In this case, the second field is a reliable measure of the function stack
utilization.
-The qualifier `dynamic` means that the function frame size is not static.
+The qualifier ``dynamic`` means that the function frame size is not static.
It happens mainly when some local variables have a dynamic size. When this
qualifier appears alone, the second field is not a reliable measure
-of the function stack analysis. When it is qualified with `bounded`, it
+of the function stack analysis. When it is qualified with ``bounded``, it
means that the second field is a reliable maximum of the function stack
utilization.
----------------------------
It is possible to measure the maximum amount of stack used by a task, by
-adding a switch to *gnatbind*, as:
+adding a switch to ``gnatbind``, as:
::
The environment task stack, e.g., the stack that contains the main unit, is
only processed when the environment variable GNAT_STACK_LIMIT is set.
-The package `GNAT.Task_Stack_Usage` provides facilities to get
+The package ``GNAT.Task_Stack_Usage`` provides facilities to get
stack usage reports at run-time. See its body for the details.
.. only:: PRO or GPL
- It also describes the *gnatmem* tool, which can be used to track down
+ It also describes the ``gnatmem`` tool, which can be used to track down
"memory leaks".
.. _Some_Useful_Memory_Pools:
.. index:: Memory Pool
.. index:: storage, pool
-The `System.Pool_Global` package offers the Unbounded_No_Reclaim_Pool
-storage pool. Allocations use the standard system call `malloc` while
-deallocations use the standard system call `free`. No reclamation is
+The ``System.Pool_Global`` package offers the Unbounded_No_Reclaim_Pool
+storage pool. Allocations use the standard system call ``malloc`` while
+deallocations use the standard system call ``free``. No reclamation is
performed when the pool goes out of scope. For performance reasons, the
standard default Ada allocators/deallocators do not use any explicit storage
pools but if they did, they could use this storage pool without any change in
-- the above is equivalent to
for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object;
-The `System.Pool_Local` package offers the Unbounded_Reclaim_Pool storage
-pool. The allocation strategy is similar to `Pool_Local`'s
+The ``System.Pool_Local`` package offers the ``Unbounded_Reclaim_Pool`` storage
+pool. The allocation strategy is similar to ``Pool_Local``
except that the all
storage allocated with this pool is reclaimed when the pool object goes out of
scope. This pool provides a explicit mechanism similar to the implicit one
end loop;
end Pooloc1;
-The `System.Pool_Size` package implements the Stack_Bounded_Pool used when
-`Storage_Size` is specified for an access type.
+The ``System.Pool_Size`` package implements the ``Stack_Bounded_Pool`` used when
+``Storage_Size`` is specified for an access type.
The whole storage for the pool is
allocated at once, usually on the stack at the point where the access type is
elaborated. It is automatically reclaimed when exiting the scope where the
references are usually difficult to tackle because the symptoms can be
very remote from the origin of the problem. In such cases, it is
very helpful to detect the problem as early as possible. This is the
-purpose of the Storage Pool provided by `GNAT.Debug_Pools`.
+purpose of the Storage Pool provided by ``GNAT.Debug_Pools``.
In order to use the GNAT specific debugging pool, the user must
associate a debug pool object with each of the access types that may be
Pool : GNAT.Debug_Pools.Debug_Pool;
for Ptr'Storage_Pool use Pool;
-`GNAT.Debug_Pools` is derived from a GNAT-specific kind of
-pool: the `Checked_Pool`. Such pools, like standard Ada storage pools,
+``GNAT.Debug_Pools`` is derived from a GNAT-specific kind of
+pool: the ``Checked_Pool``. Such pools, like standard Ada storage pools,
allow the user to redefine allocation and deallocation strategies. They
also provide a checkpoint for each dereference, through the use of
-the primitive operation `Dereference` which is implicitly called at
+the primitive operation ``Dereference`` which is implicitly called at
each dereference of an access value.
Once an access type has been associated with a debug pool, operations on
values of the type may raise four distinct exceptions,
which correspond to four potential kinds of memory corruption:
-* `GNAT.Debug_Pools.Accessing_Not_Allocated_Storage`
-* `GNAT.Debug_Pools.Accessing_Deallocated_Storage`
-* `GNAT.Debug_Pools.Freeing_Not_Allocated_Storage`
-* `GNAT.Debug_Pools.Freeing_Deallocated_Storage`
+* ``GNAT.Debug_Pools.Accessing_Not_Allocated_Storage``
+* ``GNAT.Debug_Pools.Accessing_Deallocated_Storage``
+* ``GNAT.Debug_Pools.Freeing_Not_Allocated_Storage``
+* ``GNAT.Debug_Pools.Freeing_Deallocated_Storage``
For types associated with a Debug_Pool, dynamic allocation is performed using
the standard GNAT allocation routine. References to all allocated chunks of
provided, whereupon the user can choose to release the memory to the system,
keep it allocated for further invalid access checks, or fill it with an easily
recognizable pattern for debug sessions. The memory pattern is the old IBM
-hexadecimal convention: `16#DEADBEEF#`.
+hexadecimal convention: ``16#DEADBEEF#``.
See the documentation in the file g-debpoo.ads for more information on the
various strategies.
Upon each dereference, a check is made that the access value denotes a
properly allocated memory location. Here is a complete example of use of
-`Debug_Pools`, that includes typical instances of memory corruption:
+``Debug_Pools``, that includes typical instances of memory corruption:
.. code-block:: ada
.. _The_gnatmem_Tool:
- The *gnatmem* Tool
- ------------------
+ The ``gnatmem`` Tool
+ --------------------
.. index:: ! gnatmem
- The `gnatmem` utility monitors dynamic allocation and
+ The ``gnatmem`` utility monitors dynamic allocation and
deallocation activity in a program, and displays information about
incorrect deallocations and possible sources of memory leaks.
It is designed to work in association with a static runtime library
.. _Running_gnatmem:
- Running `gnatmem`
- ^^^^^^^^^^^^^^^^^
+ Running ``gnatmem``
+ ^^^^^^^^^^^^^^^^^^^
- `gnatmem` makes use of the output created by the special version of
+ ``gnatmem`` makes use of the output created by the special version of
allocation and deallocation routines that record call information. This allows
it to obtain accurate dynamic memory usage history at a minimal cost to the
- execution speed. Note however, that `gnatmem` is not supported on all
+ execution speed. Note however, that ``gnatmem`` is not supported on all
platforms (currently, it is supported on AIX, HP-UX, GNU/Linux, Solaris and
Windows).
- The `gnatmem` command has the form
+ The ``gnatmem`` command has the form
::
- $ gnatmem [`switches`] `user_program`
+ $ gnatmem [ switches ] user_program
The program must have been linked with the instrumented version of the
allocation and deallocation routines. This is done by linking with the
$ gnatmake -g my_program -largs -lgmem
As library :file:`libgmem.a` contains an alternate body for package
- `System.Memory`, :file:`s-memory.adb` should not be compiled and linked
+ ``System.Memory``, :file:`s-memory.adb` should not be compiled and linked
when an executable is linked with library :file:`libgmem.a`. It is then not
- recommended to use *gnatmake* with switch *-a*.
+ recommended to use ``gnatmake`` with switch :switch:`-a`.
When :file:`my_program` is executed, the file :file:`gmem.out` is produced.
This file contains information about all allocations and deallocations
performed by the program. It is produced by the instrumented allocations and
- deallocations routines and will be used by `gnatmem`.
+ deallocations routines and will be used by ``gnatmem``.
In order to produce symbolic backtrace information for allocations and
deallocations performed by the GNAT run-time library, you need to use a
- version of that library that has been compiled with the *-g* switch
+ version of that library that has been compiled with the :switch:`-g` switch
(see :ref:`Rebuilding_the_GNAT_Run-Time_Library`).
- *gnatmem* must be supplied with the :file:`gmem.out` file and the executable to
+ ``gnatmem`` must be supplied with the :file:`gmem.out` file and the executable to
examine. If the location of :file:`gmem.out` file was not explicitly supplied by
- *-i* switch, gnatmem will assume that this file can be found in the
+ :switch:`-i` switch, gnatmem will assume that this file can be found in the
current directory. For example, after you have executed :file:`my_program`,
- :file:`gmem.out` can be analyzed by `gnatmem` using the command:
+ :file:`gmem.out` can be analyzed by ``gnatmem`` using the command:
::
.
The first block of output gives general information. In this case, the
- Ada construct **new** was executed 45 times, and only 6 calls to an
+ Ada construct ``new`` was executed 45 times, and only 6 calls to an
Unchecked_Deallocation routine occurred.
Subsequent paragraphs display information on all allocation roots.
An allocation root is a specific point in the execution of the program
- that generates some dynamic allocation, such as a **new**
+ that generates some dynamic allocation, such as a ``new``
construct. This root is represented by an execution backtrace (or subprogram
call stack). By default the backtrace depth for allocations roots is 1, so
that a root corresponds exactly to a source location. The backtrace can
.. _Switches_for_gnatmem:
- Switches for `gnatmem`
- ^^^^^^^^^^^^^^^^^^^^^^
+ Switches for ``gnatmem``
+ ^^^^^^^^^^^^^^^^^^^^^^^^
- `gnatmem` recognizes the following switches:
+ ``gnatmem`` recognizes the following switches:
.. index:: -q (gnatmem)
.. index:: N switch (gnatmem)
:samp:`{N}`
- `N` is an integer literal (usually between 1 and 10) which controls the
+ ``N`` is an integer literal (usually between 1 and 10) which controls the
depth of the backtraces defining allocation root. The default value for
N is 1. The deeper the backtrace, the more precise the localization of
the root. Note that the total number of roots can depend on this
.. index:: -b (gnatmem)
:samp:`-b {N}`
- This switch has the same effect as just a depth parameter `N`.
+ This switch has the same effect as just a depth parameter ``N``.
.. index:: -i (gnatmem)
:samp:`-i {file}`
- Do the `gnatmem` processing starting from :file:`file`, rather than
+ Do the ``gnatmem`` processing starting from :file:`file`, rather than
:file:`gmem.out` in the current directory.
.. index:: -m (gnatmem)
:samp:`-m {n}`
- This switch causes `gnatmem` to mask the allocation roots that have less
+ This switch causes ``gnatmem`` to mask the allocation roots that have less
than n leaks. The default value is 1. Specifying the value of 0 will allow
examination of even the roots that did not result in leaks.
.. index:: -s (gnatmem)
:samp:`-s {order}`
- This switch causes `gnatmem` to sort the allocation roots according to the
+ This switch causes ``gnatmem`` to sort the allocation roots according to the
specified order of sort criteria, each identified by a single letter. The
- currently supported criteria are `n`, `h`, and `w` standing respectively for
+ currently supported criteria are ``n``, ``h``, and ``w`` standing respectively for
number of unfreed allocations, high watermark, and final watermark
- corresponding to a specific root. The default order is `nwh`.
+ corresponding to a specific root. The default order is ``nwh``.
.. index:: -t (gnatmem)
:samp:`-t`
This switch causes memory allocated size to be always output in bytes.
- Default `gnatmem` behavior is to show memory sizes less then 1 kilobyte
+ Default ``gnatmem`` behavior is to show memory sizes less then 1 kilobyte
in bytes, from 1 kilobyte till 1 megabyte in kilobytes and the rest in
megabytes.
.. _Example_of_gnatmem_Usage:
- Example of `gnatmem` Usage
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
+ Example of ``gnatmem`` Usage
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- The following example shows the use of `gnatmem`
+ The following example shows the use of ``gnatmem``
on a simple memory-leaking program.
Suppose that we have the following Ada program:
end;
The program needs to be compiled with the debugging option and linked with
- the `gmem` library:
+ the ``gmem`` library:
::
$ test_gm
- Then `gnatmem` is invoked simply with
+ Then ``gnatmem`` is invoked simply with
::
+.. role:: switch(samp)
+
+.. |rightarrow| unicode:: 0x2192
+
.. _GNAT_Utility_Programs:
*********************
.. _The_File_Cleanup_Utility_gnatclean:
-The File Cleanup Utility *gnatclean*
-====================================
+The File Cleanup Utility ``gnatclean``
+======================================
.. index:: File cleanup tool
.. index:: gnatclean
-`gnatclean` is a tool that allows the deletion of files produced by the
+``gnatclean`` is a tool that allows the deletion of files produced by the
compiler, binder and linker, including ALI files, object files, tree files,
expanded source files, library files, interface copy source files, binder
generated files and executable files.
.. _Running_gnatclean:
-Running `gnatclean`
--------------------
+Running ``gnatclean``
+---------------------
-The `gnatclean` command has the form:
+The ``gnatclean`` command has the form:
::
- $ gnatclean switches `names`
+ $ gnatclean switches names
-where `names` is a list of source file names. Suffixes :file:`.ads` and
+where ``names`` is a list of source file names. Suffixes :file:`.ads` and
:file:`adb` may be omitted. If a project file is specified using switch
-:samp:`-P`, then `names` may be completely omitted.
+:switch:`-P`, then ``names`` may be completely omitted.
-In normal mode, `gnatclean` delete the files produced by the compiler and,
-if switch `-c` is not specified, by the binder and
+In normal mode, ``gnatclean`` delete the files produced by the compiler and,
+if switch :switch:`-c` is not specified, by the binder and
the linker. In informative-only mode, specified by switch
-`-n`, the list of files that would have been deleted in
+:switch:`-n`, the list of files that would have been deleted in
normal mode is listed, but no file is actually deleted.
.. _Switches_for_gnatclean:
-Switches for `gnatclean`
-------------------------
+Switches for ``gnatclean``
+--------------------------
-`gnatclean` recognizes the following switches:
+``gnatclean`` recognizes the following switches:
.. index:: --version (gnatclean)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatclean)
-:samp:`--help`
- If *--version* was not used, display usage, then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
-:samp:`--subdirs={subdir}`
+:switch:`--subdirs={subdir}`
Actual object directory of each project file is the subdirectory subdir of the
object directory specified or defaulted in the project file.
-:samp:`--unchecked-shared-lib-imports`
+:switch:`--unchecked-shared-lib-imports`
By default, shared library projects are not allowed to import static library
projects. When this switch is used on the command line, this restriction is
relaxed.
.. index:: -c (gnatclean)
-:samp:`-c`
+:switch:`-c`
Only attempt to delete the files produced by the compiler, not those produced
by the binder or the linker. The files that are not to be deleted are library
files, interface copy files, binder generated files and executable files.
.. index:: -D (gnatclean)
-:samp:`-D {dir}`
- Indicate that ALI and object files should normally be found in directory `dir`.
+:switch:`-D {dir}`
+ Indicate that ALI and object files should normally be found in directory ``dir``.
.. index:: -F (gnatclean)
-:samp:`-F`
+:switch:`-F`
When using project files, if some errors or warnings are detected during
parsing and verbose mode is not in effect (no use of switch
-v), then error lines start with the full path name of the project
.. index:: -h (gnatclean)
-:samp:`-h`
- Output a message explaining the usage of `gnatclean`.
+:switch:`-h`
+ Output a message explaining the usage of ``gnatclean``.
.. index:: -n (gnatclean)
-:samp:`-n`
+:switch:`-n`
Informative-only mode. Do not delete any files. Output the list of the files
that would have been deleted if this switch was not specified.
.. index:: -P (gnatclean)
-:samp:`-P{project}`
- Use project file `project`. Only one such switch can be used.
+:switch:`-P{project}`
+ Use project file ``project``. Only one such switch can be used.
When cleaning a project file, the files produced by the compilation of the
immediate sources or inherited sources of the project files are to be
deleted. This is not depending on the presence or not of executable names
.. index:: -q (gnatclean)
-:samp:`-q`
+:switch:`-q`
Quiet output. If there are no errors, do not output anything, except in
verbose mode (switch -v) or in informative-only mode
(switch -n).
.. index:: -r (gnatclean)
-:samp:`-r`
+:switch:`-r`
When a project file is specified (using switch -P),
clean all imported and extended project files, recursively. If this switch
is not specified, only the files related to the main project file are to be
.. index:: -v (gnatclean)
-:samp:`-v`
+:switch:`-v`
Verbose mode.
.. index:: -vP (gnatclean)
-:samp:`-vP{x}`
+:switch:`-vP{x}`
Indicates the verbosity of the parsing of GNAT project files.
:ref:`Switches_Related_to_Project_Files`.
.. index:: -X (gnatclean)
-:samp:`-X{name}={value}`
- Indicates that external variable `name` has the value `value`.
+:switch:`-X{name}={value}`
+ Indicates that external variable ``name`` has the value ``value``.
The Project Manager will use this value for occurrences of
- `external(name)` when parsing the project file.
- :ref:`Switches_Related_to_Project_Files`.
+ ``external(name)`` when parsing the project file.
+ See :ref:`Switches_Related_to_Project_Files`.
.. index:: -aO (gnatclean)
-:samp:`-aO{dir}`
- When searching for ALI and object files, look in directory `dir`.
+:switch:`-aO{dir}`
+ When searching for ALI and object files, look in directory ``dir``.
.. index:: -I (gnatclean)
-:samp:`-I{dir}`
- Equivalent to :samp:`-aO{dir}`.
+:switch:`-I{dir}`
+ Equivalent to :switch:`-aO{dir}`.
.. index:: -I- (gnatclean)
.. index:: Source files, suppressing search
-:samp:`-I-`
+:switch:`-I-`
Do not look for ALI or object files in the directory
- where `gnatclean` was invoked.
+ where ``gnatclean`` was invoked.
.. _The_GNAT_Library_Browser_gnatls:
-The GNAT Library Browser `gnatls`
-=================================
+The GNAT Library Browser ``gnatls``
+===================================
.. index:: Library browser
.. index:: ! gnatls
-`gnatls` is a tool that outputs information about compiled
+``gnatls`` is a tool that outputs information about compiled
units. It gives the relationship between objects, unit names and source
files. It can also be used to check the source dependencies of a unit
as well as various characteristics.
.. _Running_gnatls:
-Running `gnatls`
-----------------
+Running ``gnatls``
+------------------
-The `gnatls` command has the form
+The ``gnatls`` command has the form
::
- $ gnatls switches `object_or_ali_file`
+ $ gnatls switches object_or_ali_file
The main argument is the list of object or :file:`ali` files
(see :ref:`The_Ada_Library_Information_Files`)
for which information is requested.
-In normal mode, without additional option, `gnatls` produces a
+In normal mode, without additional option, ``gnatls`` produces a
four-column listing. Each line represents information for a specific
object. The first column gives the full path of the object, the second
column gives the name of the principal unit in this object, the third
*MOK (slightly modified)*
The version of the source file used for the compilation of the
specified unit differs from the actual source file but not enough to
- require recompilation. If you use gnatmake with the qualifier
- *-m (minimal recompilation)*, a file marked
+ require recompilation. If you use gnatmake with the option
+ :switch:`-m` (minimal recompilation), a file marked
MOK will not be recompiled.
*DIF (modified)*
.. _Switches_for_gnatls:
-Switches for `gnatls`
----------------------
+Switches for ``gnatls``
+-----------------------
-`gnatls` recognizes the following switches:
+``gnatls`` recognizes the following switches:
.. index:: --version (gnatls)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatls)
-:samp:`*--help`
- If *--version* was not used, display usage, then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatls)
-:samp:`-a`
+:switch:`-a`
Consider all units, including those of the predefined Ada library.
- Especially useful with *-d*.
+ Especially useful with :switch:`-d`.
.. index:: -d (gnatls)
-:samp:`-d`
+:switch:`-d`
List sources from which specified units depend on.
.. index:: -h (gnatls)
-:samp:`-h`
+:switch:`-h`
Output the list of options.
.. index:: -o (gnatls)
-:samp:`-o`
+:switch:`-o`
Only output information about object files.
.. index:: -s (gnatls)
-:samp:`-s`
+:switch:`-s`
Only output information about source files.
.. index:: -u (gnatls)
-:samp:`-u`
+:switch:`-u`
Only output information about compilation units.
.. index:: -files (gnatls)
-:samp:`-files={file}`
- Take as arguments the files listed in text file `file`.
- Text file `file` may contain empty lines that are ignored.
+:switch:`-files={file}`
+ Take as arguments the files listed in text file ``file``.
+ Text file ``file`` may contain empty lines that are ignored.
Each nonempty line should contain the name of an existing file.
Several such switches may be specified simultaneously.
.. index:: -I- (gnatls)
-:samp:`-aO{dir}`, :samp:`-aI{dir}`, :samp:`-I{dir}`, :samp:`-I-`, :samp:`-nostdinc`
- Source path manipulation. Same meaning as the equivalent *gnatmake*
+:switch:`-aO{dir}`, :switch:`-aI{dir}`, :switch:`-I{dir}`, :switch:`-I-`, :switch:`-nostdinc`
+ Source path manipulation. Same meaning as the equivalent ``gnatmake``
flags (:ref:`Switches_for_gnatmake`).
.. index:: -aP (gnatls)
-:samp:`-aP{dir}`
- Add `dir` at the beginning of the project search dir.
+:switch:`-aP{dir}`
+ Add ``dir`` at the beginning of the project search dir.
.. index:: --RTS (gnatls)
-:samp:`--RTS={rts-path}``
+:switch:`--RTS={rts-path}``
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -v (gnatls)
-:samp:`-v`
+:switch:`-v`
Verbose mode. Output the complete source, object and project paths. Do not use
the default column layout but instead use long format giving as much as
information possible on each requested units, including special
.. _Example_of_gnatls_Usage:
-Example of `gnatls` Usage
--------------------------
+Example of ``gnatls`` Usage
+---------------------------
Example of using the verbose switch. Note how the source and
object paths are affected by the -I switch.
.. _The_Cross-Referencing_Tools_gnatxref_and_gnatfind:
-The Cross-Referencing Tools `gnatxref` and `gnatfind`
-=====================================================
+The Cross-Referencing Tools ``gnatxref`` and ``gnatfind``
+=========================================================
.. index:: ! gnatxref
.. index:: ! gnatfind
The compiler generates cross-referencing information (unless
-you set the :samp:`-gnatx` switch), which are saved in the :file:`.ali` files.
+you set the :switch:`-gnatx` switch), which are saved in the :file:`.ali` files.
This information indicates where in the source each entity is declared and
referenced. Note that entities in package Standard are not included, but
entities in all other predefined units are included in the output.
application, so that GNAT gets a chance to generate the cross-referencing
information.
-The two tools `gnatxref` and `gnatfind` take advantage of this
+The two tools ``gnatxref`` and ``gnatfind`` take advantage of this
information to provide the user with the capability to easily locate the
declaration and references to an entity. These tools are quite similar,
-the difference being that `gnatfind` is intended for locating
+the difference being that ``gnatfind`` is intended for locating
definitions and/or references to a specified entity or entities, whereas
-`gnatxref` is oriented to generating a full report of all
+``gnatxref`` is oriented to generating a full report of all
cross-references.
To use these tools, you must not compile your application using the
-*-gnatx* switch on the *gnatmake* command line
+:switch:`-gnatx` switch on the ``gnatmake`` command line
(see :ref:`The_GNAT_Make_Program_gnatmake`). Otherwise, cross-referencing
information will not be generated.
.. _gnatxref_Switches:
-`gnatxref` Switches
--------------------
+``gnatxref`` Switches
+---------------------
-The command invocation for `gnatxref` is:
+The command invocation for ``gnatxref`` is:
::
- $ gnatxref [`switches`] `sourcefile1` [`sourcefile2` ...]
+ $ gnatxref [ switches ] sourcefile1 [ sourcefile2 ... ]
where
-*sourcefile1* [, *sourcefile2* ...]
+``sourcefile1`` [, ``sourcefile2`` ...]
identify the source files for which a report is to be generated. The
- 'with'ed units will be processed too. You must provide at least one file.
+ ``with``\ ed units will be processed too. You must provide at least one file.
These file names are considered to be regular expressions, so for instance
specifying :file:`source\*.adb` is the same as giving every file in the current
directory whose name starts with :file:`source` and whose extension is
:file:`adb`.
- You shouldn't specify any directory name, just base names. *gnatxref*
- and *gnatfind* will be able to locate these files by themselves using
+ You shouldn't specify any directory name, just base names. ``gnatxref``
+ and ``gnatfind`` will be able to locate these files by themselves using
the source path. If you specify directories, no result is produced.
-The following switches are available for *gnatxref*:
+The following switches are available for ``gnatxref``:
.. index:: --version (gnatxref)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatxref)
-:samp:`--help`
- If *--version* was not used, display usage, then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatxref)
-:samp:`-a`
- If this switch is present, `gnatfind` and `gnatxref` will parse
+:switch:`-a`
+ If this switch is present, ``gnatfind`` and ``gnatxref`` will parse
the read-only files found in the library search path. Otherwise, these files
will be ignored. This option can be used to protect Gnat sources or your own
- libraries from being parsed, thus making `gnatfind` and `gnatxref`
+ libraries from being parsed, thus making ``gnatfind`` and ``gnatxref``
much faster, and their output much smaller. Read-only here refers to access
or permissions status in the file system for the current user.
.. index:: -aIDIR (gnatxref)
-:samp:`-aI{DIR}`
+:switch:`-aI{DIR}`
When looking for source files also look in directory DIR. The order in which
- source file search is undertaken is the same as for *gnatmake*.
+ source file search is undertaken is the same as for ``gnatmake``.
.. index:: -aODIR (gnatxref)
-:samp:`aO{DIR}`
+:switch:`aO{DIR}`
When -searching for library and object files, look in directory
DIR. The order in which library files are searched is the same as for
- *gnatmake*.
+ ``gnatmake``.
.. index:: -nostdinc (gnatxref)
-:samp:`-nostdinc`
+:switch:`-nostdinc`
Do not look for sources in the system default directory.
.. index:: -nostdlib (gnatxref)
-:samp:`-nostdlib`
+:switch:`-nostdlib`
Do not look for library files in the system default directory.
.. index:: --ext (gnatxref)
-:samp:`--ext={extension}`
- Specify an alternate ali file extension. The default is `ali` and other
- extensions (e.g. `gli` for C/C++ sources when using *-fdump-xref*)
+:switch:`--ext={extension}`
+ Specify an alternate ali file extension. The default is ``ali`` and other
+ extensions (e.g. ``gli`` for C/C++ sources when using :switch:`-fdump-xref`)
may be specified via this switch. Note that if this switch overrides the
default, which means that only the new extension will be considered.
.. index:: --RTS (gnatxref)
-:samp:`--RTS={rts-path}`
+:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -d (gnatxref)
-:samp:`-d`
- If this switch is set `gnatxref` will output the parent type
+:switch:`-d`
+ If this switch is set ``gnatxref`` will output the parent type
reference for each matching derived types.
.. index:: -f (gnatxref)
-:samp:`-f`
+:switch:`-f`
If this switch is set, the output file names will be preceded by their
directory (if the file was found in the search path). If this switch is
not set, the directory will not be printed.
.. index:: -g (gnatxref)
-:samp:`-g`
+:switch:`-g`
If this switch is set, information is output only for library-level
entities, ignoring local entities. The use of this switch may accelerate
- `gnatfind` and `gnatxref`.
+ ``gnatfind`` and ``gnatxref``.
.. index:: -IDIR (gnatxref)
-:samp:`-I{DIR}`
- Equivalent to :samp:`-aODIR -aIDIR`.
+:switch:`-I{DIR}`
+ Equivalent to :switch:`-aODIR -aIDIR`.
.. index:: -pFILE (gnatxref)
-:samp:`-p{FILE}`
+:switch:`-p{FILE}`
Specify a configuration file to use to list the source and object directories.
If a file is specified, then the content of the source directory and object
directory lines are added as if they had been specified respectively
- by :samp:`-aI` and :samp:`-aO`.
+ by :switch:`-aI` and :switch:`-aO`.
See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
of this configuration file.
-:samp:`-u`
+:switch:`-u`
Output only unused symbols. This may be really useful if you give your
- main compilation unit on the command line, as `gnatxref` will then
+ main compilation unit on the command line, as ``gnatxref`` will then
display every unused entity and 'with'ed package.
-:samp:`-v`
- Instead of producing the default output, `gnatxref` will generate a
+:switch:`-v`
+ Instead of producing the default output, ``gnatxref`` will generate a
:file:`tags` file that can be used by vi. For examples how to use this
feature, see :ref:`Examples_of_gnatxref_Usage`. The tags file is output
to the standard output, thus you will have to redirect it to a file.
All these switches may be in any order on the command line, and may even
appear after the file names. They need not be separated by spaces, thus
-you can say :samp:`gnatxref -ag` instead of :samp:`gnatxref -a -g`.
+you can say ``gnatxref -ag`` instead of ``gnatxref -a -g``.
.. _gnatfind_Switches:
-`gnatfind` Switches
--------------------
+``gnatfind`` Switches
+---------------------
-The command invocation for `gnatfind` is:
+The command invocation for ``gnatfind`` is:
::
- $ gnatfind [`switches`] `pattern`[:`sourcefile`[:`line`[:`column`]]]
- [`file1` `file2` ...]
+ $ gnatfind [ switches ] pattern[:sourcefile[:line[:column]]]
+ [file1 file2 ...]
with the following iterpretation of the command arguments:
*pattern*
An entity will be output only if it matches the regular expression found
- in `pattern`, see :ref:`Regular_Expressions_in_gnatfind_and_gnatxref`.
+ in *pattern*, see :ref:`Regular_Expressions_in_gnatfind_and_gnatxref`.
Omitting the pattern is equivalent to specifying ``*``, which
will match any entity. Note that if you do not provide a pattern, you
8-bit codes other than Latin-1, or for wide characters in identifiers.
*sourcefile*
- `gnatfind` will look for references, bodies or declarations
- of symbols referenced in :file:`sourcefile`, at line `line`
- and column `column`. See :ref:`Examples_of_gnatfind_Usage`
+ ``gnatfind`` will look for references, bodies or declarations
+ of symbols referenced in :file:`sourcefile`, at line ``line``
+ and column ``column``. See :ref:`Examples_of_gnatfind_Usage`
for syntax examples.
*line*
occurrences of the entity in the separate units of the ones given on the
command line will also be displayed.
- Note that if you specify at least one file in this part, `gnatfind` may
+ Note that if you specify at least one file in this part, ``gnatfind`` may
sometimes not be able to find the body of the subprograms.
At least one of 'sourcefile' or 'pattern' has to be present on
.. index:: --version (gnatfind)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatfind)
-:samp:`--help`
- If *--version* was not used, display usage, then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatfind)
-:samp:`-a`
- If this switch is present, `gnatfind` and `gnatxref` will parse
+:switch:`-a`
+ If this switch is present, ``gnatfind`` and ``gnatxref`` will parse
the read-only files found in the library search path. Otherwise, these files
will be ignored. This option can be used to protect Gnat sources or your own
- libraries from being parsed, thus making `gnatfind` and `gnatxref`
+ libraries from being parsed, thus making ``gnatfind`` and ``gnatxref``
much faster, and their output much smaller. Read-only here refers to access
or permission status in the file system for the current user.
.. index:: -aIDIR (gnatfind)
-:samp:`-aI{DIR}`
+:switch:`-aI{DIR}`
When looking for source files also look in directory DIR. The order in which
- source file search is undertaken is the same as for *gnatmake*.
+ source file search is undertaken is the same as for ``gnatmake``.
.. index:: -aODIR (gnatfind)
-:samp:`-aO{DIR}`
+:switch:`-aO{DIR}`
When searching for library and object files, look in directory
DIR. The order in which library files are searched is the same as for
- *gnatmake*.
+ ``gnatmake``.
.. index:: -nostdinc (gnatfind)
-:samp:`-nostdinc`
+:switch:`-nostdinc`
Do not look for sources in the system default directory.
.. index:: -nostdlib (gnatfind)
-:samp:`-nostdlib`
+:switch:`-nostdlib`
Do not look for library files in the system default directory.
.. index:: --ext (gnatfind)
-:samp:`--ext={extension}`
- Specify an alternate ali file extension. The default is `ali` and other
- extensions (e.g. `gli` for C/C++ sources when using *-fdump-xref*)
+:switch:`--ext={extension}`
+ Specify an alternate ali file extension. The default is ``ali`` and other
+ extensions (e.g. ``gli`` for C/C++ sources when using :switch:`-fdump-xref`)
may be specified via this switch. Note that if this switch overrides the
default, which means that only the new extension will be considered.
.. index:: --RTS (gnatfind)
-:samp:`--RTS={rts-path}`
+:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -d (gnatfind)
-:samp:`-d`
- If this switch is set, then `gnatfind` will output the parent type
+:switch:`-d`
+ If this switch is set, then ``gnatfind`` will output the parent type
reference for each matching derived types.
.. index:: -e (gnatfind)
-:samp:`-e`
- By default, `gnatfind` accept the simple regular expression set for
- `pattern`. If this switch is set, then the pattern will be
+:switch:`-e`
+ By default, ``gnatfind`` accept the simple regular expression set for
+ ``pattern``. If this switch is set, then the pattern will be
considered as full Unix-style regular expression.
.. index:: -f (gnatfind)
-:samp:`-f`
+:switch:`-f`
If this switch is set, the output file names will be preceded by their
directory (if the file was found in the search path). If this switch is
not set, the directory will not be printed.
.. index:: -g (gnatfind)
-:samp:`-g`
+:switch:`-g`
If this switch is set, information is output only for library-level
entities, ignoring local entities. The use of this switch may accelerate
- `gnatfind` and `gnatxref`.
+ ``gnatfind`` and ``gnatxref``.
.. index:: -IDIR (gnatfind)
-:samp:`-I{DIR}`
- Equivalent to :samp:`-aODIR -aIDIR`.
+:switch:`-I{DIR}`
+ Equivalent to :switch:`-aODIR -aIDIR`.
.. index:: -pFILE (gnatfind)
-:samp:`-p{FILE}`
+:switch:`-p{FILE}`
Specify a configuration file to use to list the source and object directories.
If a file is specified, then the content of the source directory and object
directory lines are added as if they had been specified respectively
- by :samp:`-aI` and :samp:`-aO`.
+ by :switch:`-aI` and :switch:`-aO`.
See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
of this configuration file.
.. index:: -r (gnatfind)
-:samp:`-r`
- By default, `gnatfind` will output only the information about the
+:switch:`-r`
+ By default, ``gnatfind`` will output only the information about the
declaration, body or type completion of the entities. If this switch is
- set, the `gnatfind` will locate every reference to the entities in
+ set, the ``gnatfind`` will locate every reference to the entities in
the files specified on the command line (or in every file in the search
path if no file is given on the command line).
.. index:: -s (gnatfind)
-:samp:`-s`
- If this switch is set, then `gnatfind` will output the content
+:switch:`-s`
+ If this switch is set, then ``gnatfind`` will output the content
of the Ada source file lines were the entity was found.
.. index:: -t (gnatfind)
-:samp:`-t`
- If this switch is set, then `gnatfind` will output the type hierarchy for
+:switch:`-t`
+ If this switch is set, then ``gnatfind`` will output the type hierarchy for
the specified type. It act like -d option but recursively from parent
type to parent type. When this switch is set it is not possible to
specify more than one file.
All these switches may be in any order on the command line, and may even
appear after the file names. They need not be separated by spaces, thus
-you can say :samp:`gnatxref -ag` instead of
-:samp:`gnatxref -a -g`.
+you can say ``gnatxref -ag`` instead of
+``gnatxref -a -g``.
-As stated previously, gnatfind will search in every directory in the
+As stated previously, ``gnatfind`` will search in every directory in the
search path. You can force it to look only in the current directory if
-you specify `*` at the end of the command line.
+you specify ``*`` at the end of the command line.
.. _Configuration_Files_for_gnatxref_and_gnatfind:
-Configuration Files for *gnatxref* and *gnatfind*
--------------------------------------------------
+Configuration Files for ``gnatxref`` and ``gnatfind``
+-----------------------------------------------------
-Configuration files are used by `gnatxref` and `gnatfind` to specify
+Configuration files are used by ``gnatxref`` and ``gnatfind`` to specify
the list of source and object directories to consider. They can be
-specified via the :samp:`-p` switch.
+specified via the :switch:`-p` switch.
The following lines can be included, in any order in the file:
* *src_dir=DIR*
- [default: `"./"`].
- Specifies a directory where to look for source files. Multiple `src_dir`
+ [default: ``"./"``].
+ Specifies a directory where to look for source files. Multiple ``src_dir``
lines can be specified and they will be searched in the order they
are specified.
* *obj_dir=DIR*
- [default: `"./"`].
+ [default: ``"./"``].
Specifies a directory where to look for object and library files. Multiple
- `obj_dir` lines can be specified, and they will be searched in the order
+ ``obj_dir`` lines can be specified, and they will be searched in the order
they are specified
Any other line will be silently ignored.
.. _Regular_Expressions_in_gnatfind_and_gnatxref:
-Regular Expressions in `gnatfind` and `gnatxref`
-------------------------------------------------
+Regular Expressions in ``gnatfind`` and ``gnatxref``
+----------------------------------------------------
-As specified in the section about *gnatfind*, the pattern can be a
+As specified in the section about ``gnatfind``, the pattern can be a
regular expression. Two kinds of regular expressions
are recognized:
* *Full regular expression*
The second set of regular expressions is much more powerful. This is the
- type of regular expressions recognized by utilities such as :samp:`grep`.
+ type of regular expressions recognized by utilities such as ``grep``.
The following is the form of a regular expression, expressed in same BNF
style as is found in the Ada Reference Manual:
Here are a few examples:
``abcde|fghi``
- will match any of the two strings :samp:`abcde` and :samp:`fghi`,
+ will match any of the two strings ``abcde`` and ``fghi``,
``abc*d``
will match any string like ``abd``, ``abcd``, ``abccd``,
.. _Examples_of_gnatxref_Usage:
-Examples of `gnatxref` Usage
-----------------------------
+Examples of ``gnatxref`` Usage
+------------------------------
General Usage
^^^^^^^^^^^^^
You can then issue any of the following commands:
* ``gnatxref main.adb``
- `gnatxref` generates cross-reference information for main.adb
+ ``gnatxref`` generates cross-reference information for main.adb
and every unit 'with'ed by main.adb.
The output would be:
Ref: main.adb 6:12 7:12
- This shows that the entity `Main` is declared in main.ads, line 2, column 9,
+ This shows that the entity ``Main`` is declared in main.ads, line 2, column 9,
its body is in main.adb, line 1, column 14 and is not referenced any where.
- The entity `Print` is declared in bar.ads, line 2, column 15 and it
- is referenced in main.adb, line 6 column 12 and line 7 column 12.
+ The entity ``Print`` is declared in :file:`bar.ads`, line 2, column 15 and it
+ is referenced in :file:`main.adb`, line 6 column 12 and line 7 column 12.
* ``gnatxref package1.adb package2.ads``
- `gnatxref` will generates cross-reference information for
- package1.adb, package2.ads and any other package 'with'ed by any
+ ``gnatxref`` will generates cross-reference information for
+ :file:`package1.adb`, :file:`package2.ads` and any other package ``with``\ ed by any
of these.
-Using gnatxref with vi
-^^^^^^^^^^^^^^^^^^^^^^
+Using ``gnatxref`` with ``vi``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-`gnatxref` can generate a tags file output, which can be used
-directly from *vi*. Note that the standard version of *vi*
+``gnatxref`` can generate a tags file output, which can be used
+directly from ``vi``. Note that the standard version of ``vi``
will not work properly with overloaded symbols. Consider using another
-free implementation of *vi*, such as *vim*.
+free implementation of ``vi``, such as ``vim``.
::
$ gnatxref -v gnatfind.adb > tags
-The following command will generate the tags file for `gnatfind` itself
+The following command will generate the tags file for ``gnatfind`` itself
(if the sources are in the search path!):
::
$ gnatxref -v gnatfind.adb > tags
-From *vi*, you can then use the command :samp:`:tag {entity}`
-(replacing `entity` by whatever you are looking for), and vi will
+From ``vi``, you can then use the command :samp:`:tag {entity}`
+(replacing ``entity`` by whatever you are looking for), and vi will
display a new file with the corresponding declaration of entity.
.. _Examples_of_gnatfind_Usage:
-Examples of `gnatfind` Usage
-----------------------------
+Examples of ``gnatfind`` Usage
+------------------------------
* ``gnatfind -f xyz:main.adb``
Find declarations for all entities xyz referenced at least once in
declared at line 45 of foo.ads
* ``gnatfind -fs xyz:main.adb``
- This is the same command as the previous one, but `gnatfind` will
+ This is the same command as the previous one, but ``gnatfind`` will
display the content of the Ada source file lines.
The output will look like:
.. _The_Ada_to_HTML_Converter_gnathtml:
-The Ada to HTML Converter `gnathtml`
-====================================
+The Ada to HTML Converter ``gnathtml``
+======================================
.. index:: ! gnathtml
-*gnathtml* is a Perl script that allows Ada source files to be browsed using
+``gnathtml`` is a Perl script that allows Ada source files to be browsed using
standard Web browsers. For installation information, see :ref:`Installing_gnathtml`.
Ada reserved keywords are highlighted in a bold font and Ada comments in
-a blue font. Unless your program was compiled with the gcc *-gnatx*
+a blue font. Unless your program was compiled with the gcc :switch:`-gnatx`
switch to suppress the generation of cross-referencing information, user
defined variables and types will appear in a different color; you will
be able to click on any identifier and go to its declaration.
.. _Invoking_gnathtml:
-Invoking *gnathtml*
--------------------
+Invoking ``gnathtml``
+---------------------
The command line is as follows:
::
- $ perl gnathtml.pl [`switches`] `ada-files`
+ $ perl gnathtml.pl [ switches ] ada-files
-You can specify as many Ada files as you want. `gnathtml` will generate
+You can specify as many Ada files as you want. ``gnathtml`` will generate
an html file for every ada file, and a global file called :file:`index.htm`.
This file is an index of every identifier defined in the files.
:samp:`d`
If the Ada files depend on some other files (for instance through
- `with` clauses, the latter files will also be converted to html.
+ ``with`` clauses, the latter files will also be converted to html.
Only the files in the user project will be converted to html, not the files
in the run-time library itself.
.. index:: -D (gnathtml)
:samp:`D`
- This command is the same as *-d* above, but *gnathtml* will
+ This command is the same as :switch:`-d` above, but ``gnathtml`` will
also look for files in the run-time library, and generate html files for them.
.. index:: -ext (gnathtml)
:samp:`f`
By default, gnathtml will generate html links only for global entities
('with'ed units, global variables and types,...). If you specify
- *-f* on the command line, then links will be generated for local
+ :switch:`-f` on the command line, then links will be generated for local
entities too.
.. index:: -l (gnathtml)
:samp:`l {number}`
- If this switch is provided and `number` is not 0, then
- `gnathtml` will number the html files every `number` line.
+ If this switch is provided and ``number`` is not 0, then
+ ``gnathtml`` will number the html files every ``number`` line.
.. index:: -I (gnathtml)
.. _Installing_gnathtml:
-Installing `gnathtml`
----------------------
+Installing ``gnathtml``
+-----------------------
-`Perl` needs to be installed on your machine to run this script.
-`Perl` is freely available for almost every architecture and
+``Perl`` needs to be installed on your machine to run this script.
+``Perl`` is freely available for almost every architecture and
operating system via the Internet.
On Unix systems, you may want to modify the first line of the script
-`gnathtml`, to explicitly specify where Perl
+``gnathtml``, to explicitly specify where Perl
is located. The syntax of this line is:
::
::
- $ perl gnathtml.pl [`switches`] `files`
+ $ perl gnathtml.pl [ switches ] files
.. _The_Ada-to-XML_converter_gnat2xml:
- The Ada-to-XML converter *gnat2xml*
- ===================================
+ The Ada-to-XML converter ``gnat2xml``
+ =====================================
.. index:: ! gnat2xml
.. index:: XML generation
- The *gnat2xml* tool is an ASIS-based utility that converts
+ The ``gnat2xml`` tool is an ASIS-based utility that converts
Ada source code into XML.
- *gnat2xml* is a project-aware tool
+ ``gnat2xml`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches). The project file package that can specify
- *gnat2xml* switches is named ``gnat2xml``.
+ ``gnat2xml`` switches is named ``gnat2xml``.
- .. _Switches_for_*gnat2xml*:
+ .. _Switches_for_``gnat2xml``:
- Switches for *gnat2xml*
- -----------------------
+ Switches for ``gnat2xml``
+ -------------------------
- *gnat2xml* takes Ada source code as input, and produces XML
+ ``gnat2xml`` takes Ada source code as input, and produces XML
that conforms to the schema.
Usage:
Options:
- :samp:`--help`
+ :switch:`--help`
Generate usage information and quit, ignoring all other options
- :samp:`-h`
+ :switch:`-h`
Same as ``--help``
- :samp:`--version`
+ :switch:`--version`
Print version and quit, ignoring all other options
- :samp:`-P{file}`
+ :switch:`-P{file}`
indicates the name of the project file that describes
the set of sources to be processed. The exact set of argument
sources depends on other options specified, see below.
- :samp:`-U`
+ :switch:`-U`
If a project file is specified and no argument source is explicitly
specified, process all the units of the closure of the argument project.
Otherwise this option has no effect.
- :samp:`-U {main_unit}`
+ :switch:`-U {main_unit}`
If a project file is specified and no argument source
- is explicitly specified (either directly or by means of *-files*
- option), process the closure of units rooted at `main_unit`.
+ is explicitly specified (either directly or by means of :switch:`-files`
+ option), process the closure of units rooted at ``main_unit``.
Otherwise this option has no effect.
- :samp:`-X{name}={value}`
- Indicates that external variable `name` in
- the argument project has the value `value`. Has no effect if no
+ :switch:`-X{name}={value}`
+ Indicates that external variable ``name`` in
+ the argument project has the value ``value``. Has no effect if no
project is specified as tool argument.
- :samp:`--RTS={rts-path}`
+ :switch:`--RTS={rts-path}`
Specifies the default location of the runtime
- library. Same meaning as the equivalent *gnatmake* flag
+ library. Same meaning as the equivalent ``gnatmake`` flag
(:ref:`Switches_for_gnatmake`).
- :samp:`--incremental`
+ :switch:`--incremental`
Incremental processing on a per-file basis. Source files are
only processed if they have been modified, or if files they depend
on have been modified. This is similar to the way gnatmake/gprbuild
only compiles files that need to be recompiled. A project file
is required in this mode.
- :samp:`-j{n}`
- In *--incremental* mode, use `n` *gnat2xml*
- processes to perform XML generation in parallel. If `n` is 0, then
+ :switch:`-j{n}`
+ In :switch:`--incremental` mode, use ``n`` ``gnat2xml``
+ processes to perform XML generation in parallel. If ``n`` is 0, then
the maximum number of parallel tree creations is the number of core
processors on the platform.
- :samp:`--output-dir={dir}`
+ :switch:`--output-dir={dir}`
Generate one .xml file for each Ada source file, in
directory :file:`dir`. (Default is to generate the XML to standard
output.)
- :samp:`-I{include-dir}`
+ :switch:`-I{include-dir}`
Directories to search for dependencies.
You can also set the ADA_INCLUDE_PATH environment variable for this.
- :samp:`--compact`
+ :switch:`--compact`
Debugging version, with interspersed source, and a more
compact representation of "sloc". This version does not conform
to any schema.
- :samp:`--rep-clauses`
+ :switch:`--rep-clauses`
generate representation clauses (see :ref:`Generating_Representation_Clauses`).
- :samp:`-files={filename}`
- The name of a text file containing a list of Ada source files to process
+ :switch:`-files={filename}`
+ Take as arguments the files listed in text file ``file``.
+ Text file ``file`` may contain empty lines that are ignored.
+ Each nonempty line should contain the name of an existing file.
+ Several such switches may be specified simultaneously.
- :samp:`-q`
+ :switch:`-q`
Quiet
- :samp:`-v`
+ :switch:`-v`
Verbose
- :samp:`-cargs` ...
+ :switch:`-cargs` ...
Options to pass to gcc
If a project file is specified and no argument source is explicitly
- specified, and no *-U* is specified, then the set of processed
+ specified, and no :switch:`-U` is specified, then the set of processed
sources is all the immediate units of the argument project.
Example:
--------------
The distribution includes two other programs that are related to
- *gnat2xml*:
+ ``gnat2xml``:
- *gnat2xsd* is the schema generator, which generates the schema
+ ``gnat2xsd`` is the schema generator, which generates the schema
to standard output, based on the structure of Ada as encoded by
- ASIS. You don't need to run *gnat2xsd* in order to use
- *gnat2xml*. To generate the schema, type:
+ ASIS. You don't need to run ``gnat2xsd`` in order to use
+ ``gnat2xml``. To generate the schema, type:
::
$ gnat2xsd > ada-schema.xsd
- *gnat2xml* generates XML files that will validate against
+ ``gnat2xml`` generates XML files that will validate against
:file:`ada-schema.xsd`.
- *xml2gnat* is a back-translator that translates the XML back
- into Ada source code. The Ada generated by *xml2gnat* has
+ ``xml2gnat`` is a back-translator that translates the XML back
+ into Ada source code. The Ada generated by ``xml2gnat`` has
identical semantics to the original Ada code passed to
- *gnat2xml*. It is not textually identical, however --- for
+ ``gnat2xml``. It is not textually identical, however --- for
example, no attempt is made to preserve the original indentation.
.. _Structure_of_the_XML:
--------------------
The primary documentation for the structure of the XML generated by
- *gnat2xml* is the schema (see *gnat2xsd* above). The
+ ``gnat2xml`` is the schema (see ``gnat2xsd`` above). The
following documentation gives additional details needed to understand
the schema and therefore the XML.
Some subelements are 'Boolean'. For example, Private_Type_Definition
has has_abstract_q and has_limited_q, to indicate whether those
- keywords are present, as in `type T is abstract limited private;`.
+ keywords are present, as in ``type T is abstract limited private;``.
False is represented by a Nil_Element. True is represented
by an element type specific to that query (for example, Abstract and
Limited).
in package Asis.
* unit_full_name is the full expanded name of the unit, starting from a
- root library unit. So for `package P.Q.R is ...`,
- `unit_full_name="P.Q.R"`. Same for `separate (P.Q) package R is ...`.
+ root library unit. So for ``package P.Q.R is ...``,
+ ``unit_full_name="P.Q.R"``. Same for ``separate (P.Q) package R is ...``.
* def_name is the same as unit_full_name for library units; for subunits,
it is just the simple name.
* source_file is the name of the Ada source file. For example, for
- the spec of `P.Q.R`, `source_file="p-q-r.ads"`. This allows one to
+ the spec of ``P.Q.R``, ``source_file="p-q-r.ads"``. This allows one to
interpret the source locations --- the 'sloc' of all elements
within this Compilation_Unit refers to line and column numbers
within the named file.
algorithm, which is subject to change; we just guarantee that the
names are unique in the face of overloading.
- * type is the type of the declared object, or `null` for
+ * type is the type of the declared object, or ``null`` for
declarations of things other than objects.
Usage occurrences have these attributes:
* ref is the same as the def of the corresponding defining
occurrence.
- In summary, `def_name` and `ref_name` are as in the source
- code of the declaration, possibly overloaded, whereas `def` and
- `ref` are unique-ified.
+ In summary, ``def_name`` and ``ref_name`` are as in the source
+ code of the declaration, possibly overloaded, whereas ``def`` and
+ ``ref`` are unique-ified.
Literal elements have this attribute:
* lit_val is the value of the literal as written in the source text,
- appropriately escaped (e.g. `"` ---> `"`). This applies
+ appropriately escaped (e.g. ``"`` |rightarrow| ``"``). This applies
only to numeric and string literals. Enumeration literals in Ada are
not really "literals" in the usual sense; they are usage occurrences,
and have ref_name and ref as described above. Note also that string
Generating Representation Clauses
---------------------------------
- If the *--rep-clauses* switch is given, *gnat2xml* will
+ If the :switch:`--rep-clauses` switch is given, ``gnat2xml`` will
generate representation clauses for certain types showing the
representation chosen by the compiler. The information is produced by
the ASIS 'Data Decomposition' facility --- see the
- `Asis.Data_Decomposition` package for details.
+ ``Asis.Data_Decomposition`` package for details.
- Not all types are supported. For example, `Type_Model_Kind` must
- be `A_Simple_Static_Model`. Types declared within generic units
+ Not all types are supported. For example, ``Type_Model_Kind`` must
+ be ``A_Simple_Static_Model``. Types declared within generic units
have no representation. The clauses that are generated include
- `attribute_definition_clauses` for `Size` and
- `Component_Size`, as well as
- `record_representation_clauses`.
+ ``attribute_definition_clauses`` for ``Size`` and
+ ``Component_Size``, as well as
+ ``record_representation_clauses``.
There is no guarantee that the generated representation clauses could
have actually come from legal Ada code; Ada has some restrictions that
.. _The_Program_Property_Verifier_gnatcheck:
- The Program Property Verifier *gnatcheck*
- =========================================
+ The Coding Standard Verifier ``gnatcheck``
+ ==========================================
.. index:: ! gnatcheck
.. index:: ASIS
- The *gnatcheck* tool is an ASIS-based utility that checks properties
- of Ada source files according to a given set of semantic rules.
+ The ``gnatcheck`` tool is an ASIS-based utility that checks coding standard
+ compliance of Ada source files according to a given set of semantic rules.
- *gnatcheck* is a project-aware tool
+ ``gnatcheck`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches). The project file package that can specify
- *gnatcheck* switches is named ``Check``.
+ ``gnatcheck`` switches is named ``Check``.
For full details, plese refer to :title:`GNATcheck Reference Manual`.
.. _The_GNAT_Metrics_Tool_gnatmetric:
- The GNAT Metrics Tool *gnatmetric*
- ==================================
+ The GNAT Metrics Tool ``gnatmetric``
+ ====================================
.. index:: ! gnatmetric
.. index:: Metric tool
- The *gnatmetric* tool is an ASIS-based utility
+ The ``gnatmetric`` tool is an ASIS-based utility
for computing various program metrics.
It takes an Ada source file as input and generates a file containing the
metrics data as output. Various switches control which
metrics are computed and output.
- *gnatmetric* is a project-aware tool
+ ``gnatmetric`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches). The project file package that can specify
- *gnatmetric* switches is named ``Metrics``.
+ ``gnatmetric`` switches is named ``Metrics``.
- To compute program metrics, *gnatmetric* invokes the Ada
+ To compute program metrics, ``gnatmetric`` invokes the Ada
compiler and generates and uses the ASIS tree for the input source;
thus the input must be legal Ada code, and the tool should have all the
information needed to compile the input source. To provide this information,
(or you may call *gnatmetric*
through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`).
Another possibility is to specify the source search
- path and needed configuration files in *-cargs* section of *gnatmetric*
- call, see the description of the *gnatmetric* switches below.
+ path and needed configuration files in :switch:`-cargs` section of ``gnatmetric``
+ call, see the description of the ``gnatmetric`` switches below.
- If the set of sources to be processed by `gnatmetric` contains sources with
+ If the set of sources to be processed by ``gnatmetric`` contains sources with
preprocessing directives
then the needed options should be provided to run preprocessor as a part of
- the *gnatmetric* call, and the computed metrics
+ the ``gnatmetric`` call, and the computed metrics
will correspond to preprocessed sources.
- The *gnatmetric* command has the form
+ The ``gnatmetric`` command has the form
::
- $ gnatmetric [`switches`] {`filename`} [-cargs `gcc_switches`]
+ $ gnatmetric [ switches ] { filename } [ -cargs gcc_switches ]
where:
- * `switches` specify the metrics to compute and define the destination for
+ * ``switches`` specify the metrics to compute and define the destination for
the output
- * Each `filename` is the name (including the extension) of a source
+ * Each ``filename`` is the name (including the extension) of a source
file to process. 'Wildcards' are allowed, and
the file name may contain path information.
- If no `filename` is supplied, then the `switches` list must contain
+ If no ``filename`` is supplied, then the ``switches`` list must contain
at least one
- *-files* switch (see :ref:`Other_gnatmetric_Switches`).
- Including both a *-files* switch and one or more
- `filename` arguments is permitted.
-
- * `gcc_switches` is a list of switches for
- *gcc*. They will be passed on to all compiler invocations made by
- *gnatmetric* to generate the ASIS trees. Here you can provide
- *-I* switches to form the source search path,
- and use the *-gnatec* switch to set the configuration file,
- use the *-gnat05* switch if sources should be compiled in
+ :switch:`-files` switch (see :ref:`Other_gnatmetric_Switches`).
+ Including both a :switch:`-files` switch and one or more
+ ``filename`` arguments is permitted.
+
+ * ``gcc_switches`` is a list of switches for
+ ``gcc``. They will be passed on to all compiler invocations made by
+ ``gnatmetric`` to generate the ASIS trees. Here you can provide
+ :switch:`-I` switches to form the source search path,
+ and use the :switch:`-gnatec` switch to set the configuration file,
+ use the :switch:`-gnat05` switch if sources should be compiled in
Ada 2005 mode etc.
The following subsections describe the various switches accepted by
- *gnatmetric*, organized by category.
+ ``gnatmetric``, organized by category.
.. _Output_File_Control-gnatmetric:
.. index:: Output file control in gnatmetric
- *gnatmetric* has two output formats. It can generate a
+ ``gnatmetric`` has two output formats. It can generate a
textual (human-readable) form, and also XML. By default only textual
output is generated.
- When generating the output in textual form, *gnatmetric* creates
+ When generating the output in textual form, ``gnatmetric`` creates
for each Ada source file a corresponding text file
containing the computed metrics, except for the case when the set of metrics
specified by gnatmetric parameters consists only of metrics that are computed
By default, the name of the file containing metric information for a source
is obtained by appending the :file:`.metrix` suffix to the
name of the input source file. If not otherwise specified and no project file
- is specified as *gnatmetric* option this file is placed in the same
- directory as where the source file is located. If *gnatmetric* has a
+ is specified as ``gnatmetric`` option this file is placed in the same
+ directory as where the source file is located. If ``gnatmetric`` has a
project file as its parameter, it places all the generated files in the
object directory of the project (or in the project source directory if the
- project does not define an objects directory), if *--subdirs* option
+ project does not define an objects directory), if :switch:`--subdirs` option
is specified, the files are placed in the subrirectory of this directory
specified by this option.
All the output information generated in XML format is placed in a single
file. By default the name of this file is :file:`metrix.xml`.
If not otherwise specified and if no project file is specified
- as *gnatmetric* option this file is placed in the
+ as ``gnatmetric`` option this file is placed in the
current directory.
Some of the computed metrics are summed over the units passed to
- *gnatmetric*; for example, the total number of lines of code.
+ ``gnatmetric``; for example, the total number of lines of code.
By default this information is sent to :file:`stdout`, but a file
- can be specified with the *-og* switch.
+ can be specified with the :switch:`-og` switch.
- The following switches control the *gnatmetric* output:
+ The following switches control the ``gnatmetric`` output:
.. index:: -x (gnatmetric)
- :samp:`-x`
+ :switch:`-x`
Generate the XML output
.. index:: -xs (gnatmetric)
- :samp:`-xs`
+ :switch:`-xs`
Generate the XML output and the XML schema file that describes the structure
of the XML metric report, this schema is assigned to the XML file. The schema
file has the same name as the XML output file with :file:`.xml` suffix replaced
.. index:: -nt (gnatmetric)
- :samp:`-nt`
- Do not generate the output in text form (implies *-x*)
+ :switch:`-nt`
+ Do not generate the output in text form (implies :switch:`-x`)
.. index:: -d (gnatmetric)
- :samp:`-d {output_dir}`
- Put text files with detailed metrics into `output_dir`
+ :switch:`-d {output_dir}`
+ Put text files with detailed metrics into ``output_dir``
.. index:: -o (gnatmetric)
- :samp:`-o {file_suffix}`
- Use `file_suffix`, instead of :file:`.metrix`
+ :switch:`-o {file_suffix}`
+ Use ``file_suffix``, instead of :file:`.metrix`
in the name of the output file.
.. index:: -og (gnatmetric)
- :samp:`-og {file_name}`
- Put global metrics into `file_name`
+ :switch:`-og {file_name}`
+ Put global metrics into ``file_name``
.. index:: -ox (gnatmetric)
- :samp:`-ox {file_name}`
- Put the XML output into `file_name` (also implies *-x*)
+ :switch:`-ox {file_name}`
+ Put the XML output into ``file_name`` (also implies :switch:`-x`)
.. index:: -sfn (gnatmetric)
- :samp:`-sfn`
- Use 'short' source file names in the output. (The *gnatmetric*
+ :switch:`-sfn`
+ Use 'short' source file names in the output. (The ``gnatmetric``
output includes the name(s) of the Ada source file(s) from which the metrics
are computed. By default each name includes the absolute path. The
- *-sfn* switch causes *gnatmetric*
+ :switch:`-sfn` switch causes ``gnatmetric``
to exclude all directory information from the file names that are output.)
Disable Metrics For Local Units
-------------------------------
- *gnatmetric* relies on the GNAT compilation model --
+ ``gnatmetric`` relies on the GNAT compilation model --
one compilation
unit per one source file. It computes line metrics for the whole source
file, and it also computes syntax
and complexity metrics for the file's outermost unit.
- By default, *gnatmetric* will also compute all metrics for certain
+ By default, ``gnatmetric`` will also compute all metrics for certain
kinds of locally declared program units:
* subprogram (and generic subprogram) bodies;
.. index:: -nolocal (gnatmetric)
- :samp:`-nolocal`
+ :switch:`-nolocal`
Do not compute detailed metrics for eligible local program units
.. index:: Line metrics control in gnatmetric
For any (legal) source file, and for each of its
- eligible local program units, *gnatmetric* computes the following
+ eligible local program units, ``gnatmetric`` computes the following
metrics:
* the total number of lines;
bodies and statement sequences in package bodies (this metric is only computed
across the whole set of the analyzed units)
- *gnatmetric* sums the values of the line metrics for all the
+ ``gnatmetric`` sums the values of the line metrics for all the
files being processed and then generates the cumulative results. The tool
also computes for all the files being processed the average number of code
lines in bodies.
.. index:: --no-lines (gnatmetric)
- :samp:`--lines-all`
+ :switch:`--lines-all`
Report all the line metrics
- :samp:`--no-lines-all`
+ :switch:`--no-lines-all`
Do not report any of line metrics
- :samp:`--lines`
+ :switch:`--lines`
Report the number of all lines
- :samp:`--no-lines`
+ :switch:`--no-lines`
Do not report the number of all lines
- :samp:`--lines-code`
+ :switch:`--lines-code`
Report the number of code lines
- :samp:`--no-lines-code`
+ :switch:`--no-lines-code`
Do not report the number of code lines
- :samp:`--lines-comment`
+ :switch:`--lines-comment`
Report the number of comment lines
- :samp:`--no-lines-comment`
+ :switch:`--no-lines-comment`
Do not report the number of comment lines
- :samp:`--lines-eol-comment`
+ :switch:`--lines-eol-comment`
Report the number of code lines containing
end-of-line comments
- :samp:`--no-lines-eol-comment`
+ :switch:`--no-lines-eol-comment`
Do not report the number of code lines containing
end-of-line comments
- :samp:`--lines-ratio`
+ :switch:`--lines-ratio`
Report the comment percentage in the program text
- :samp:`--no-lines-ratio`
+ :switch:`--no-lines-ratio`
Do not report the comment percentage in the program text
- :samp:`--lines-blank`
+ :switch:`--lines-blank`
Report the number of blank lines
- :samp:`--no-lines-blank`
+ :switch:`--no-lines-blank`
Do not report the number of blank lines
- :samp:`--lines-average`
+ :switch:`--lines-average`
Report the average number of code lines in subprogram bodies, task bodies,
entry bodies and statement sequences in package bodies. The metric is computed
and reported for the whole set of processed Ada sources only.
- :samp:`--no-lines-average`
+ :switch:`--no-lines-average`
Do not report the average number of code lines in subprogram bodies,
task bodies, entry bodies and statement sequences in package bodies.
.. index:: Syntax metrics control in gnatmetric
- *gnatmetric* computes various syntactic metrics for the
+ ``gnatmetric`` computes various syntactic metrics for the
outermost unit and for each eligible local unit:
* *LSLOC ('Logical Source Lines Of Code')*
subprogram declaration but is not a completion of previous declaration.
This metric is not reported for generic and formal subprograms.
- For the outermost unit in the file, *gnatmetric* additionally computes
+ For the outermost unit in the file, ``gnatmetric`` additionally computes
the following metrics:
* *Public subprograms*
.. index:: --no-syntax (gnatmetric)
- :samp:`--syntax-all`
+ :switch:`--syntax-all`
Report all the syntax metrics
- :samp:`--no-syntax-all`
+ :switch:`--no-syntax-all`
Do not report any of syntax metrics
- :samp:`--declarations`
+ :switch:`--declarations`
Report the total number of declarations
- :samp:`--no-declarations`
+ :switch:`--no-declarations`
Do not report the total number of declarations
- :samp:`--statements`
+ :switch:`--statements`
Report the total number of statements
- :samp:`--no-statements`
+ :switch:`--no-statements`
Do not report the total number of statements
- :samp:`--public-subprograms`
+ :switch:`--public-subprograms`
Report the number of public subprograms in a compilation unit
- :samp:`--no-public-subprograms`
+ :switch:`--no-public-subprograms`
Do not report the number of public subprograms in a compilation unit
- :samp:`--all-subprograms`
+ :switch:`--all-subprograms`
Report the number of all the subprograms in a compilation unit
- :samp:`--no-all-subprograms`
+ :switch:`--no-all-subprograms`
Do not report the number of all the subprograms in a compilation unit
- :samp:`--public-types`
+ :switch:`--public-types`
Report the number of public types in a compilation unit
- :samp:`--no-public-types`
+ :switch:`--no-public-types`
Do not report the number of public types in a compilation unit
- :samp:`--all-types`
+ :switch:`--all-types`
Report the number of all the types in a compilation unit
- :samp:`--no-all-types`
+ :switch:`--no-all-types`
Do not report the number of all the types in a compilation unit
- :samp:`--unit-nesting`
+ :switch:`--unit-nesting`
Report the maximal program unit nesting level
- :samp:`--no-unit-nesting`
+ :switch:`--no-unit-nesting`
Do not report the maximal program unit nesting level
- :samp:`--construct-nesting`
+ :switch:`--construct-nesting`
Report the maximal construct nesting level
- :samp:`--no-construct-nesting`
+ :switch:`--no-construct-nesting`
Do not report the maximal construct nesting level
- :samp:`--param-number`
+ :switch:`--param-number`
Report the number of subprogram parameters
- :samp:`--no-param-number`
+ :switch:`--no-param-number`
Do not report the number of subprogram parameters
For a program unit that is an executable body (a subprogram body (including
generic bodies), task body, entry body or a package body containing
- its own statement sequence) *gnatmetric* computes the following
+ its own statement sequence) ``gnatmetric`` computes the following
complexity metrics:
* McCabe cyclomatic complexity;
* the complexity introduced by control
statements only, without taking into account short-circuit forms
- (referred as `statement complexity` in *gnatmetric* output),
+ (referred as ``statement complexity`` in ``gnatmetric`` output),
* the complexity introduced by short-circuit control forms only
- (referred as `expression complexity` in *gnatmetric* output), and
+ (referred as ``expression complexity`` in ``gnatmetric`` output), and
* the total
cyclomatic complexity, which is the sum of these two values
- (referred as `cyclomatic complexity` in *gnatmetric* output).
+ (referred as ``cyclomatic complexity`` in ``gnatmetric`` output).
The cyclomatic complexity is also computed for Ada 2012 expression functions.
An expression function cannot have statements as its components, so only one
The origin of cyclomatic complexity metric is the need to estimate the number
of independent paths in the control flow graph that in turn gives the number
of tests needed to satisfy paths coverage testing completeness criterion.
- Considered from the testing point of view, a static Ada `loop` (that is,
- the `loop` statement having static subtype in loop parameter
+ Considered from the testing point of view, a static Ada ``loop`` (that is,
+ the ``loop`` statement having static subtype in loop parameter
specification) does not add to cyclomatic complexity. By providing
- *--no-static-loop* option a user
+ :switch:`--no-static-loop` option a user
may specify that such loops should not be counted when computing the
cyclomatic complexity metric
The Ada essential complexity metric is a McCabe cyclomatic complexity metric
counted for the code that is reduced by excluding all the pure structural Ada
control statements. An compound statement is considered as a non-structural
- if it contains a `raise` or `return` statement as it subcomponent,
- or if it contains a `goto` statement that transfers the control outside
- the operator. A selective accept statement with `terminate` alternative
- is considered as non-structural statement. When computing this metric,
- `exit` statements are treated in the same way as `goto`
- statements unless *-ne* option is specified.
+ if it contains a ``raise`` or ``return`` statement as it subcomponent,
+ or if it contains a ``goto`` statement that transfers the control outside
+ the operator. A selective ``accept`` statement with a ``terminate`` alternative
+ is considered a non-structural statement. When computing this metric,
+ ``exit`` statements are treated in the same way as ``goto``
+ statements unless the :switch:`-ne` option is specified.
The Ada essential complexity metric defined here is intended to quantify
the extent to which the software is unstructured. It is adapted from
suitable for typical Ada usage. For example, short circuit forms
are not penalized as unstructured in the Ada essential complexity metric.
- When computing cyclomatic and essential complexity, *gnatmetric* skips
+ When computing cyclomatic and essential complexity, ``gnatmetric`` skips
the code in the exception handlers and in all the nested program units. The
code of assertions and predicates (that is, subprogram preconditions and
postconditions, subtype predicates and type invariants) is also skipped.
.. index:: --no-complexity (gnatmetric)
- :samp:`--complexity-all`
+ :switch:`--complexity-all`
Report all the complexity metrics
- :samp:`--no-complexity-all`
+ :switch:`--no-complexity-all`
Do not report any of complexity metrics
- :samp:`--complexity-cyclomatic`
+ :switch:`--complexity-cyclomatic`
Report the McCabe Cyclomatic Complexity
- :samp:`--no-complexity-cyclomatic`
+ :switch:`--no-complexity-cyclomatic`
Do not report the McCabe Cyclomatic Complexity
- :samp:`--complexity-essential`
+ :switch:`--complexity-essential`
Report the Essential Complexity
- :samp:`--no-complexity-essential`
+ :switch:`--no-complexity-essential`
Do not report the Essential Complexity
- :samp:`--loop-nesting`
+ :switch:`--loop-nesting`
Report maximal loop nesting level
- :samp:`-no-loop-nesting`
+ :switch:`-no-loop-nesting`
Do not report maximal loop nesting level
- :samp:`--complexity-average`
+ :switch:`--complexity-average`
Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
task bodies, entry bodies and statement sequences in package bodies.
The metric is computed and reported for whole set of processed Ada sources
only.
- :samp:`--no-complexity-average`
+ :switch:`--no-complexity-average`
Do not report the average McCabe Cyclomatic Complexity for all the subprogram
bodies, task bodies, entry bodies and statement sequences in package bodies
.. index:: -ne (gnatmetric)
- :samp:`-ne`
- Do not consider `exit` statements as `goto`\ s when
+ :switch:`-ne`
+ Do not consider ``exit`` statements as ``goto``\ s when
computing Essential Complexity
.. index:: --no-static-loop (gnatmetric)
- :samp:`--no-static-loop`
+ :switch:`--no-static-loop`
Do not consider static loops when computing cyclomatic complexity
- :samp:`--extra-exit-points`
+ :switch:`--extra-exit-points`
Report the extra exit points for subprogram bodies. As an exit point, this
- metric counts `return` statements and raise statements in case when the
+ metric counts ``return`` statements and raise statements in case when the
raised exception is not handled in the same body. In case of a function this
metric subtracts 1 from the number of exit points, because a function body
- must contain at least one `return` statement.
+ must contain at least one ``return`` statement.
- :samp:`--no-extra-exit-points`
+ :switch:`--no-extra-exit-points`
Do not report the extra exit points for subprogram bodies
entities in the program. This information is useful since high coupling
may signal potential issues with maintainability as the program evolves.
- *gnatmetric* computes the following coupling metrics:
+ ``gnatmetric`` computes the following coupling metrics:
* *object-oriented coupling*, for classes in traditional object-oriented
and/or method members). A *category* (of classes) is a group of closely
related classes that are reused and/or modified together.
- A class `K`'s fan-out coupling is the number of classes
- that `K` depends upon.
+ A class ``K``\ 's fan-out coupling is the number of classes
+ that ``K`` depends upon.
A category's fan-out coupling is the number of classes outside the
category that the classes inside the category depend upon.
- A class `K`'s fan-in coupling is the number of classes
- that depend upon `K`.
+ A class ``K``\ 's fan-in coupling is the number of classes
+ that depend upon ``K``.
A category's fan-in coupling is the number of classes outside the
category that depend on classes belonging to the category.
Similarly, for unit and control coupling an entity is considered to be the
conceptual construct consisting of the entity's specification, body, and
any subunits (transitively).
- *gnatmetric* computes
+ ``gnatmetric`` computes
the dependencies of all these units as a whole, but
metrics are only reported for spec
units (or for a subprogram body unit in case if there is no
end Fun;
end Pack;
- If we apply *gnatmetric* with the *--coupling-all* option to
+ If we apply ``gnatmetric`` with the :switch:`--coupling-all` option to
these units, the result will be:
::
coupling because none of the argument units contains a tagged type and
therefore none of these units can be treated as a class.
- The `Pack` package (spec and body) depends on two
- units -- `Lib_1` `and Lib_2` -- and so its unit fan-out coupling
+ The ``Pack`` package (spec and body) depends on two
+ units -- ``Lib_1`` and ``Lib_2`` -- and so its unit fan-out coupling
is 2. Since nothing depends on it, its unit fan-in coupling is 0, as
- is its control fan-in coupling. Only one of the units `Pack` depends
+ is its control fan-in coupling. Only one of the units ``Pack`` depends
upon defines a subprogram, so its control fan-out coupling is 1.
- `Lib_2` depends on nothing, so its fan-out metrics are 0. It does
+ ``Lib_2`` depends on nothing, so its fan-out metrics are 0. It does
not define any subprograms, so it has no control fan-in metric.
- One unit (`Pack`) depends on it , so its unit fan-in coupling is 1.
+ One unit (``Pack``) depends on it , so its unit fan-in coupling is 1.
- `Lib_1` is similar to `Lib_2`, but it does define a subprogram.
+ ``Lib_1`` is similar to ``Lib_2``, but it does define a subprogram.
Its control fan-in coupling is 1 (because there is one unit
depending on it).
- When computing coupling metrics, *gnatmetric* counts only
- dependencies between units that are arguments of the *gnatmetric*
+ When computing coupling metrics, ``gnatmetric`` counts only
+ dependencies between units that are arguments of the ``gnatmetric``
invocation. Coupling metrics are program-wide (or project-wide) metrics, so
- you should invoke *gnatmetric* for
+ you should invoke ``gnatmetric`` for
the complete set of sources comprising your program. This can be done
- by invoking *gnatmetric* with the corresponding project file
- and with the *-U* option.
+ by invoking ``gnatmetric`` with the corresponding project file
+ and with the :switch:`-U` option.
By default, all the coupling metrics are disabled. You can use the following
switches to specify the coupling metrics to be computed and reported:
.. index:: --unit-coupling (gnatmetric)
.. index:: --control-coupling (gnatmetric)
- :samp:`--coupling-all`
+ :switch:`--coupling-all`
Report all the coupling metrics
- :samp:`--tagged-coupling-out`
+ :switch:`--tagged-coupling-out`
Report tagged (class) fan-out coupling
- :samp:`--tagged-coupling-in`
+ :switch:`--tagged-coupling-in`
Report tagged (class) fan-in coupling
- :samp:`--hierarchy-coupling-out`
+ :switch:`--hierarchy-coupling-out`
Report hierarchy (category) fan-out coupling
- :samp:`--hierarchy-coupling-in`
+ :switch:`--hierarchy-coupling-in`
Report hierarchy (category) fan-in coupling
- :samp:`--unit-coupling-out`
+ :switch:`--unit-coupling-out`
Report unit fan-out coupling
- :samp:`--unit-coupling-in`
+ :switch:`--unit-coupling-in`
Report unit fan-in coupling
- :samp:`--control-coupling-out`
+ :switch:`--control-coupling-out`
Report control fan-out coupling
- :samp:`--control-coupling-in`
+ :switch:`--control-coupling-in`
Report control fan-in coupling
.. _Other_gnatmetric_Switches:
- Other `gnatmetric` Switches
- ---------------------------
+ Other ``gnatmetric`` Switches
+ -----------------------------
- Additional *gnatmetric* switches are as follows:
+ Additional ``gnatmetric`` switches are as follows:
.. index:: --version (gnatmetric)
- :samp:`--version`
+ :switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatmetric)
- :samp:`--help`
+ :switch:`--help`
Display usage, then exit disregarding all other options.
.. index:: -P (gnatmetric)
- :samp:`-P {file}`
+ :switch:`-P {file}`
Indicates the name of the project file that describes the set of sources
to be processed. The exact set of argument sources depends on other options
specified, see below.
.. index:: -U (gnatmetric)
- :samp:`-U`
+ :switch:`-U`
If a project file is specified and no argument source is explicitly
- specified (either directly or by means of *-files* option), process
+ specified (either directly or by means of :switch:`-files` option), process
all the units of the closure of the argument project. Otherwise this option
has no effect.
- :samp:`-U {main_unit}`
+ :switch:`-U {main_unit}`
If a project file is specified and no argument source is explicitly
- specified (either directly or by means of *-files* option), process
- the closure of units rooted at `main_unit`. Otherwise this option
+ specified (either directly or by means of :switch:`-files` option), process
+ the closure of units rooted at ``main_unit``. Otherwise this option
has no effect.
.. index:: -X (gnatmetric)
- :samp:`-X{name}={value}`
- Indicates that external variable `name` in the argument project
- has the value `value`. Has no effect if no project is specified as
+ :switch:`-X{name}={value}`
+ Indicates that external variable ``name`` in the argument project
+ has the value ``value``. Has no effect if no project is specified as
tool argument.
.. index:: --RTS (gnatmetric)
- :samp:`--RTS={rts-path}`
+ :switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (see :ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (see :ref:`Switches_for_gnatmake`).
.. index:: --subdirs=dir (gnatmetric)
- :samp:`--subdirs={dir}`
+ :switch:`--subdirs={dir}`
Use the specified subdirectory of the project objects file (or of the
project file directory if the project does not specify an object directory)
for tool output files. Has no effect if no project is specified as
- tool argument r if *--no_objects_dir* is specified.
+ tool argument r if :switch:`--no_objects_dir` is specified.
.. index:: --no_objects_dir (gnatmetric)
- :samp:`--no_objects_dir`
+ :switch:`--no_objects_dir`
Place all the result files into the current directory instead of
- project objects directory. This corresponds to the *gnatcheck*
+ project objects directory. This corresponds to the ``gnatcheck``
behavior when it is called with the project file from the
GNAT driver. Has no effect if no project is specified.
.. index:: -files (gnatmetric)
- :samp:`-files {filename}`
- Take the argument source files from the specified file. This file should be an
- ordinary text file containing file names separated by spaces or
- line breaks. You can use this switch more than once in the same call to
- *gnatmetric*. You also can combine this switch with
- an explicit list of files.
+ :switch:`-files {filename}`
+ Take as arguments the files listed in text file ``file``.
+ Text file ``file`` may contain empty lines that are ignored.
+ Each nonempty line should contain the name of an existing file.
+ Several such switches may be specified simultaneously.
.. index:: -j (gnatmetric)
- :samp:`-j{n}`
- Use `n` processes to carry out the tree creations (internal representations
+ :switch:`-j{n}`
+ Use ``n`` processes to carry out the tree creations (internal representations
of the argument sources). On a multiprocessor machine this speeds up processing
- of big sets of argument sources. If `n` is 0, then the maximum number of
+ of big sets of argument sources. If ``n`` is 0, then the maximum number of
parallel tree creations is the number of core processors on the platform.
.. index:: -t (gnatmetric)
- :samp:`-t`
+ :switch:`-t`
Print out execution time.
.. index:: -v (gnatmetric)
- :samp:`-v`
+ :switch:`-v`
Verbose mode;
- *gnatmetric* generates version information and then
+ ``gnatmetric`` generates version information and then
a trace of sources being processed.
.. index:: -q (gnatmetric)
- :samp:`-q`
+ :switch:`-q`
Quiet mode.
If a project file is specified and no argument source is explicitly
- specified (either directly or by means of *-files* option), and no
- *-U* is specified, then the set of processed sources is
+ specified (either directly or by means of :switch:`-files` option), and no
+ :switch:`-U` is specified, then the set of processed sources is
all the immediate units of the argument project.
.. _The_GNAT_Pretty-Printer_gnatpp:
- The GNAT Pretty-Printer *gnatpp*
- ================================
+ The GNAT Pretty-Printer ``gnatpp``
+ ==================================
.. index:: ! gnatpp
.. index:: Pretty-Printer
- The *gnatpp* tool is an ASIS-based utility
+ The ``gnatpp`` tool is an ASIS-based utility
for source reformatting / pretty-printing.
It takes an Ada source file as input and generates a reformatted
version as output.
You can specify various style directives via switches; e.g.,
identifier case conventions, rules of indentation, and comment layout.
- *gnatpp* is a project-aware tool
+ ``gnatpp`` is a project-aware tool
(see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches). The project file package that can specify
- *gnatpp* switches is named ``Pretty_Printer``.
+ ``gnatpp`` switches is named ``Pretty_Printer``.
- To produce a reformatted file, *gnatpp* invokes the Ada
+ To produce a reformatted file, ``gnatpp`` invokes the Ada
compiler and generates and uses the ASIS tree for the input source;
thus the input must be legal Ada code, and the tool should have all the
information needed to compile the input source. To provide this information,
(or you may call *gnatpp*
through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`).
Another possibility is to specify the source search
- path and needed configuration files in ``-cargs`` section of *gnatpp*
- call, see the description of the *gnatpp* switches below.
+ path and needed configuration files in ``-cargs`` section of ``gnatpp``
+ call, see the description of the ``gnatpp`` switches below.
- *gnatpp* cannot process sources that contain preprocessing directives.
+ ``gnatpp`` cannot process sources that contain preprocessing directives.
- The *gnatpp* command has the form
+ The ``gnatpp`` command has the form
::
- $ gnatpp [`switches`] `filename` [-cargs `gcc_switches`]
+ $ gnatpp [ switches ] filename [ -cargs gcc_switches ]
where
- * `switches` is an optional sequence of switches defining such properties as
+ * ``switches`` is an optional sequence of switches defining such properties as
the formatting rules, the source search path, and the destination for the
output source file
- * `filename` is the name (including the extension) of the source file to
+ * ``filename`` is the name (including the extension) of the source file to
reformat; wildcards or several file names on the same gnatpp command are
allowed. The file name may contain path information; it does not have to
follow the GNAT file naming rules
- * `gcc_switches` is a list of switches for
- *gcc*. They will be passed on to all compiler invocations made by
- *gnatpp* to generate the ASIS trees. Here you can provide
+ * ``gcc_switches`` is a list of switches for
+ ``gcc``. They will be passed on to all compiler invocations made by
+ ``gnatpp`` to generate the ASIS trees. Here you can provide
``-I`` switches to form the source search path,
use the ``-gnatec`` switch to set the configuration file, etc.
.. _Switches_for_gnatpp:
- Switches for *gnatpp*
- ---------------------
+ Switches for ``gnatpp``
+ -----------------------
The following subsections describe the various switches accepted by
- *gnatpp*, organized by category.
+ ``gnatpp``, organized by category.
You specify a switch by supplying a name and generally also a value.
In many cases the values for a switch with a given name are incompatible with
(for example the switch that controls the casing of a reserved word may have
exactly one value: upper case, lower case, or
mixed case) and thus exactly one such switch can be in effect for an
- invocation of *gnatpp*.
+ invocation of ``gnatpp``.
If more than one is supplied, the last one is used.
However, some values for the same switch are mutually compatible.
- You may supply several such switches to *gnatpp*, but then
+ You may supply several such switches to ``gnatpp``, but then
each must be specified in full, with both the name and the value.
Abbreviated forms (the name appearing once, followed by each value) are
not permitted.
.. index:: -A1 (gnatpp)
- :samp:`-A0`
+ :switch:`-A0`
Set alignment to OFF
- :samp:`-A1`
+ :switch:`-A1`
Set alignment to ON
.. _Casing_Control:
.. index:: Casing control in gnatpp
- *gnatpp* allows you to specify the casing for reserved words,
+ ``gnatpp`` allows you to specify the casing for reserved words,
pragma names, attribute designators and identifiers.
For identifiers you may define a
general rule for name casing but also override this rule
.. index:: -a (gnatpp)
- :samp:`-aL`
+ :switch:`-aL`
Attribute designators are lower case
- :samp:`-aU`
+ :switch:`-aU`
Attribute designators are upper case
- :samp:`-aM`
+ :switch:`-aM`
Attribute designators are mixed case (this is the default)
.. index:: -k (gnatpp)
- :samp:`-kL`
+ :switch:`-kL`
Keywords (technically, these are known in Ada as *reserved words*) are
lower case (this is the default)
- :samp:`-kU`
+ :switch:`-kU`
Keywords are upper case
.. index:: -n (gnatpp)
- :samp:`-nD`
+ :switch:`-nD`
Name casing for defining occurrences are as they appear in the source file
(this is the default)
- :samp:`-nU`
+ :switch:`-nU`
Names are in upper case
- :samp:`-nL`
+ :switch:`-nL`
Names are in lower case
- :samp:`-nM`
+ :switch:`-nM`
Names are in mixed case
.. index:: -ne (gnatpp)
- :samp:`-neD`
+ :switch:`-neD`
Enumeration literal casing for defining occurrences are as they appear in the
source file. Overrides -n casing setting.
- :samp:`-neU`
+ :switch:`-neU`
Enumeration literals are in upper case. Overrides -n casing
setting.
- :samp:`-neL`
+ :switch:`-neL`
Enumeration literals are in lower case. Overrides -n casing
setting.
- :samp:`-neM`
+ :switch:`-neM`
Enumeration literals are in mixed case. Overrides -n casing
setting.
.. index:: -nt (gnatpp)
- :samp:`-ntD`
+ :switch:`-ntD`
Names introduced by type and subtype declarations are always
cased as they appear in the declaration in the source file.
Overrides -n casing setting.
- :samp:`-ntU`
+ :switch:`-ntU`
Names introduced by type and subtype declarations are always in
upper case. Overrides -n casing setting.
- :samp:`-ntL`
+ :switch:`-ntL`
Names introduced by type and subtype declarations are always in
lower case. Overrides -n casing setting.
- :samp:`-ntM`
+ :switch:`-ntM`
Names introduced by type and subtype declarations are always in
mixed case. Overrides -n casing setting.
- :samp:`-nnU`
+ :switch:`-nnU`
Names introduced by number declarations are always in
upper case. Overrides -n casing setting.
- :samp:`-nnL`
+ :switch:`-nnL`
Names introduced by number declarations are always in
lower case. Overrides -n casing setting.
- :samp:`-nnM`
+ :switch:`-nnM`
Names introduced by number declarations are always in
mixed case. Overrides -n casing setting.
.. index:: -p (gnatpp)
- :samp:`-pL`
+ :switch:`-pL`
Pragma names are lower case
- :samp:`-pU`
+ :switch:`-pU`
Pragma names are upper case
- :samp:`-pM`
+ :switch:`-pM`
Pragma names are mixed case (this is the default)
.. index:: -D (gnatpp)
- :samp:`-D{file}`
- Use `file` as a *dictionary file* that defines
+ :switch:`-D{file}`
+ Use ``file`` as a *dictionary file* that defines
the casing for a set of specified names,
thereby overriding the effect on these names by
any explicit or implicit
To supply more than one dictionary file,
use several ``-D`` switches.
- *gnatpp* implicitly uses a *default dictionary file*
+ ``gnatpp`` implicitly uses a *default dictionary file*
to define the casing for the Ada predefined names and
the names declared in the GNAT libraries.
.. index:: -D- (gnatpp)
- :samp:`-D-`
+ :switch:`-D-`
Do not use the default dictionary file;
instead, use the casing
defined by a ``-n`` switch and any explicit
The structure of a dictionary file, and details on the conventions
used in the default dictionary file, are defined in :ref:`Name_Casing`.
- The ``-D-`` and
- ``-D-``\ `file` switches are mutually
+ The :switch:`-D-` and
+ :switch:`-D{file}` switches are mutually
compatible.
- This group of *gnatpp* switches controls the layout of comments and
+ This group of ``gnatpp`` switches controls the layout of comments and
complex syntactic constructs. See :ref:`Formatting_Comments` for details
on their effect.
.. index:: -c (gnatpp)
- :samp:`-c0`
+ :switch:`-c0`
All comments remain unchanged.
- :samp:`-c1`
+ :switch:`-c1`
GNAT-style comment line indentation.
This is the default.
- :samp:`-c3`
+ :switch:`-c3`
GNAT-style comment beginning.
- :samp:`-c4`
+ :switch:`-c4`
Fill comment blocks.
- :samp:`-c5`
+ :switch:`-c5`
Keep unchanged special form comments.
This is the default.
.. index:: --comments-only (gnatpp)
- :samp:`--comments-only`
+ :switch:`--comments-only`
Format just the comments.
.. index:: --no-end-id (gnatpp)
- :samp:`--no-end-id`
- Do not insert the name of a unit after `end`; leave whatever comes
- after `end`, if anything, alone.
+ :switch:`--no-end-id`
+ Do not insert the name of a unit after ``end``; leave whatever comes
+ after ``end``, if anything, alone.
.. index:: --no-separate-is (gnatpp)
- :samp:`--no-separate-is`
- Do not place the keyword `is` on a separate line in a subprogram body in
+ :switch:`--no-separate-is`
+ Do not place the keyword ``is`` on a separate line in a subprogram body in
case if the spec occupies more than one line.
.. index:: --separate-loop-then (gnatpp)
- :samp:`--separate-loop-then`
- Place the keyword `loop` in FOR and WHILE loop statements and the
- keyword `then` in IF statements on a separate line.
+ :switch:`--separate-loop-then`
+ Place the keyword ``loop`` in FOR and WHILE loop statements and the
+ keyword ``then`` in IF statements on a separate line.
.. index:: --no-separate-loop-then (gnatpp)
- :samp:`--no-separate-loop-then`
- Do not place the keyword `loop` in FOR and WHILE loop statements and the
- keyword `then` in IF statements on a separate line. This option is
- incompatible with ``--separate-loop-then`` option.
+ :switch:`--no-separate-loop-then`
+ Do not place the keyword ``loop`` in FOR and WHILE loop statements and the
+ keyword ``then`` in IF statements on a separate line. This option is
+ incompatible with the :switch:`--separate-loop-then` option.
.. index:: --use-on-new-line (gnatpp)
- :samp:`--use-on-new-line`
+ :switch:`--use-on-new-line`
Start each USE clause in a context clause from a separate line.
.. index:: --insert-blank-lines (gnatpp)
- :samp:`--insert-blank-lines`
+ :switch:`--insert-blank-lines`
Insert blank lines where appropriate (between bodies and other large
constructs).
.. index:: --preserve-blank-lines (gnatpp)
- :samp:`--preserve-blank-lines`
+ :switch:`--preserve-blank-lines`
Preserve blank lines in the input. By default, gnatpp will squeeze
multiple blank lines down to one.
.. index:: -M (gnatpp)
- :samp:`-M{nnn}`
- Maximum line length, `nnn` from 32...256, the default value is 79
+ :switch:`-M{nnn}`
+ Maximum line length, ``nnn`` from 32...256, the default value is 79
.. index:: -i (gnatpp)
- :samp:`-i{nnn}`
- Indentation level, `nnn` from 1...9, the default value is 3
+ :switch:`-i{nnn}`
+ Indentation level, ``nnn`` from 1...9, the default value is 3
.. index:: -cl (gnatpp)
- :samp:`-cl{nnn}`
+ :switch:`-cl{nnn}`
Indentation level for continuation lines (relative to the line being
- continued), `nnn` from 1...9.
+ continued), ``nnn`` from 1...9.
The default
value is one less than the (normal) indentation level, unless the
indentation is set to 1 (in which case the default value for continuation
.. index:: --decimal-grouping (gnatpp)
- :samp:`--decimal-grouping={n}`
+ :switch:`--decimal-grouping={n}`
Put underscores in decimal literals (numeric literals without a base)
- every `n` characters. If a literal already has one or more
+ every ``n`` characters. If a literal already has one or more
underscores, it is not modified. For example, with
- `--decimal-grouping=3`, `1000000` will be changed to
- `1_000_000`.
+ ``--decimal-grouping=3``, ``1000000`` will be changed to
+ ``1_000_000``.
.. index:: --based-grouping (gnatpp)
- :samp:`--based-grouping={n}`
- Same as `--decimal-grouping`, but for based literals. For
- example, with `--based-grouping=4`, `16#0001FFFE#` will be
- changed to `16#0001_FFFE#`.
+ :switch:`--based-grouping={n}`
+ Same as ``--decimal-grouping``, but for based literals. For
+ example, with ``--based-grouping=4``, ``16#0001FFFE#`` will be
+ changed to ``16#0001_FFFE#``.
.. index:: --split-line-before-op (gnatpp)
- :samp:`--split-line-before-op`
+ :switch:`--split-line-before-op`
If it is necessary to split a line at a binary operator, by default
the line is split after the operator. With this option, it is split
before the operator.
.. index:: --RM-style-spacing (gnatpp)
- :samp:`--RM-style-spacing`
+ :switch:`--RM-style-spacing`
Do not insert an extra blank before various occurrences of
'(' and ':'. This also turns off alignment.
.. index:: -ff (gnatpp)
- :samp:`-ff`
+ :switch:`-ff`
Insert a Form Feed character after a pragma Page.
.. index:: --call_threshold (gnatpp)
- :samp:`--call_threshold={nnn}`
- If the number of parameter associations is greater than `nnn` and if at
+ :switch:`--call_threshold={nnn}`
+ If the number of parameter associations is greater than ``nnn`` and if at
least one association uses named notation, start each association from
- a new line. If `nnn` is 0, no check for the number of associations
+ a new line. If ``nnn`` is 0, no check for the number of associations
is made; this is the default.
.. index:: --par_threshold (gnatpp)
- :samp:`--par_threshold={nnn}`
- If the number of parameter specifications is greater than `nnn`
- (or equal to `nnn` in case of a function), start each specification from
- a new line. If `nnn` is 0, and `--no-separate-is` was not specified, then
- the "is" is placed on a separate line. This feature is disabled by default.
+ :switch:`--par_threshold={nnn}`
+ If the number of parameter specifications is greater than ``nnn``
+ (or equal to ``nnn`` in case of a function), start each specification from
+ a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not specified, then
+ the ``is`` is placed on a separate line. This feature is disabled by default.
.. _Setting_the_Source_Search_Path:
Setting the Source Search Path
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- To define the search path for the input source file, *gnatpp*
+ To define the search path for the input source file, ``gnatpp``
uses the same switches as the GNAT compiler, with the same effects:
.. index:: -I (gnatpp)
- :samp:`-I{dir}`
+ :switch:`-I{dir}`
.. index:: -I- (gnatpp)
- :samp:`-I-`
+ :switch:`-I-`
.. index:: -gnatec (gnatpp)
- :samp:`-gnatec={path}`
+ :switch:`-gnatec={path}`
.. _Output_File_Control-gnatpp:
the :file:`.pp` suffix to the name of the input file.
If the file with this name already exists, it is overwritten.
Thus if the input file is :file:`my_ada_proc.adb` then
- *gnatpp* will produce :file:`my_ada_proc.adb.pp`
+ ``gnatpp`` will produce :file:`my_ada_proc.adb.pp`
as output file.
The output may be redirected by the following switches:
.. index:: --output-dir (gnatpp)
- :samp:`--output-dir={dir}`
+ :switch:`--output-dir={dir}`
Generate output file in directory :file:`dir` with the same name as the input
file. If :file:`dir` is the same as the directory containing the input file,
the input file is not processed; use ``-rnb``
.. index:: -pipe (gnatpp)
- :samp:`-pipe`
- Send the output to `Standard_Output`
+ :switch:`-pipe`
+ Send the output to ``Standard_Output``
.. index:: -o (gnatpp)
- :samp:`-o {output_file}`
- Write the output into `output_file`.
- If `output_file` already exists, *gnatpp* terminates without
+ :switch:`-o {output_file}`
+ Write the output into ``output_file``.
+ If ``output_file`` already exists, ``gnatpp`` terminates without
reading or processing the input file.
.. index:: -of (gnatpp)
- :samp:`-of {output_file}`
- Write the output into `output_file`, overwriting the existing file
+ :switch:`-of {output_file}`
+ Write the output into ``output_file``, overwriting the existing file
(if one is present).
.. index:: -r (gnatpp)
- :samp:`-r`
+ :switch:`-r`
Replace the input source file with the reformatted output, and copy the
original input source into the file whose name is obtained by appending the
:file:`.npp` suffix to the name of the input file.
- If a file with this name already exists, *gnatpp* terminates without
+ If a file with this name already exists, ``gnatpp`` terminates without
reading or processing the input file.
.. index:: -rf (gnatpp)
- :samp:`-rf`
+ :switch:`-rf`
Like ``-r`` except that if the file with the specified name
already exists, it is overwritten.
.. index:: -rnb (gnatpp)
- :samp:`-rnb`
+ :switch:`-rnb`
Replace the input source file with the reformatted output without
creating any backup copy of the input source.
.. index:: --eol (gnatpp)
- :samp:`--eol={xxx}`
- Specifies the line-ending style of the reformatted output file. The `xxx`
+ :switch:`--eol={xxx}`
+ Specifies the line-ending style of the reformatted output file. The ``xxx``
string specified with the switch may be:
* *dos* - MS DOS style, lines end with CR LF characters*
.. index:: -W (gnatpp)
- :samp:`-W{e}`
+ :switch:`-W{e}`
Specify the wide character encoding method for the input and output files.
- `e` is one of the following:
+ ``e`` is one of the following:
* *h* - Hex encoding
.. _Other_gnatpp_Switches:
- Other `gnatpp` Switches
- ^^^^^^^^^^^^^^^^^^^^^^^
+ Other ``gnatpp`` Switches
+ ^^^^^^^^^^^^^^^^^^^^^^^^^
- The additional *gnatpp* switches are defined in this subsection.
+ The additional ``gnatpp`` switches are defined in this subsection.
.. index:: --version (gnatpp)
- :samp:`--version`
+ :switch:`--version`
Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatpp)
- :samp:`--help`
+ :switch:`--help`
Display usage, then exit disregarding all other options.
.. index:: -P (gnatpp)
- :samp:`-P {file}`
+ :switch:`-P {file}`
Indicates the name of the project file that describes the set of sources
to be processed. The exact set of argument sources depends on other options
specified; see below.
.. index:: -U (gnatpp)
- :samp:`-U`
+ :switch:`-U`
If a project file is specified and no argument source is explicitly
specified (either directly or by means of ``-files`` option), process
all the units of the closure of the argument project. Otherwise this option
has no effect.
- :samp:`-U {main_unit}`
+ :switch:`-U {main_unit}`
If a project file is specified and no argument source is explicitly
specified (either directly or by means of ``-files`` option), process
- the closure of units rooted at `main_unit`. Otherwise this option
+ the closure of units rooted at ``main_unit``. Otherwise this option
has no effect.
.. index:: -X (gnatpp)
- :samp:`-X{name}={value}`
- Indicates that external variable `name` in the argument project
- has the value `value`. Has no effect if no project is specified as
+ :switch:`-X{name}={value}`
+ Indicates that external variable ``name`` in the argument project
+ has the value ``value``. Has no effect if no project is specified as
tool argument.
.. index:: --RTS (gnatpp)
- :samp:`--RTS={rts-path}`
+ :switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: --incremental (gnatpp)
- :samp:`--incremental`
+ :switch:`--incremental`
Incremental processing on a per-file basis. Source files are only
processed if they have been modified, or if files they depend on have
been modified. This is similar to the way gnatmake/gprbuild only
.. index:: --pp-off (gnatpp)
- :samp:`--pp-off={xxx}`
- Use `--xxx` as the command to turn off pretty printing, instead
- of the default `--!pp off`.
+ :switch:`--pp-off={xxx}`
+ Use :switch:`--xxx` as the command to turn off pretty printing, instead
+ of the default ``--!pp off``.
.. index:: --pp-on (gnatpp)
- :samp:`--pp-on={xxx}`
- Use `--xxx` as the command to turn pretty printing back on, instead
- of the default `--!pp on`.
+ :switch:`--pp-on={xxx}`
+ Use :switch:`--xxx` as the command to turn pretty printing back on, instead
+ of the default ``--!pp on``.
.. index:: -files (gnatpp)
- :samp:`-files {filename}`
- Take the argument source files from the specified file. This file should be an
- ordinary text file containing file names separated by spaces or
- line breaks. You can use this switch more than once in the same call to
- *gnatpp*. You also can combine this switch with an explicit list of
- files.
+ :switch:`-files {filename}`
+ Take as arguments the files listed in text file ``file``.
+ Text file ``file`` may contain empty lines that are ignored.
+ Each nonempty line should contain the name of an existing file.
+ Several such switches may be specified simultaneously.
.. index:: -j (gnatpp)
- :samp:`-j{n}`
- Without ``--incremental``, use `n` processes to carry out the
+ :switch:`-j{n}`
+ Without ``--incremental``, use *n* processes to carry out the
tree creations (internal representations of the argument sources). On
a multiprocessor machine this speeds up processing of big sets of
- argument sources. If `n` is 0, then the maximum number of parallel
+ argument sources. If *n* is 0, then the maximum number of parallel
tree creations is the number of core processors on the platform. This
- option cannot be used together with ``-r``,
- ``-rf`` or
- ``-rnb`` option.
+ option cannot be used together with the :switch:`-r`,
+ :switch:`-rf` or
+ :switch:`-rnb` options.
- With ``--incremental``, use `n` *gnatpp* processes to
- perform pretty-printing in parallel. `n` = 0 means the same as
- above. In this case, ``-r``,
- ``-rf`` or
- ``-rnb`` options are allowed.
+ With ``--incremental``, use *n* ``gnatpp`` processes to
+ perform pretty-printing in parallel. *n* = 0 means the same as
+ above. In this case, the :switch:`-r`,
+ :switch:`-rf` and
+ :switch:`-rnb` options are allowed.
.. index:: -t (gnatpp)
- :samp:`-t`
+ :switch:`-t`
Print out execution time.
.. index:: -v (gnatpp)
- :samp:`-v`
+ :switch:`-v`
Verbose mode
.. index:: -q (gnatpp)
- :samp:`-q`
+ :switch:`-q`
Quiet mode
If a project file is specified and no argument source is explicitly
Formatting Rules
----------------
- The following subsections show how *gnatpp* treats white space,
+ The following subsections show how ``gnatpp`` treats white space,
comments, program layout, and name casing.
They provide detailed descriptions of the switches shown above.
White Space and Empty Lines
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *gnatpp* does not have an option to control space characters.
+ ``gnatpp`` does not have an option to control space characters.
It will add or remove spaces according to the style illustrated by the
examples in the :title:`Ada Reference Manual`.
The output file will contain no lines with trailing white space.
turns off comment formatting.
Special-form comments such as SPARK-style ``--#...`` are left alone.
- For an end-of-line comment, *gnatpp* tries to leave the same
+ For an end-of-line comment, ``gnatpp`` tries to leave the same
number of spaces between the end of the preceding Ada code and the
beginning of the comment as appear in the original source.
effect:
* For each whole-line comment that does not end with two hyphens,
- *gnatpp* inserts spaces if necessary after the starting two hyphens
+ ``gnatpp`` inserts spaces if necessary after the starting two hyphens
to ensure that there are at least two spaces between these hyphens and the
first non-blank character of the comment.
``--comments-only -c4`` means to fill comment paragraphs, and do nothing else.
Likewise,
``--comments-only -c3`` ensures comments start with at least two
- spaces after `--`, and ``--comments-only -c3 -c4`` does
+ spaces after ``--``, and ``--comments-only -c3 -c4`` does
both. If ``--comments-only`` is given without ``-c3`` or
``-c4``, then gnatpp doesn't format anything.
Name Casing
^^^^^^^^^^^
- *gnatpp* always converts the usage occurrence of a (simple) name to
+ ``gnatpp`` always converts the usage occurrence of a (simple) name to
the same casing as the corresponding defining identifier.
You control the casing for defining occurrences via the
``-nM`` --
result in
upper, lower, or mixed case, respectively.
- If *gnatpp* changes the casing of a defining
+ If ``gnatpp`` changes the casing of a defining
occurrence, it analogously changes the casing of all the
usage occurrences of this name.
If the defining occurrence of a name is not in the source compilation unit
- currently being processed by *gnatpp*, the casing of each reference to
+ currently being processed by ``gnatpp``, the casing of each reference to
this name is changed according to the value of the ``-n``
switch (subject to the dictionary file mechanism described below).
- Thus *gnatpp* acts as though the ``-n`` switch
+ Thus ``gnatpp`` acts as though the ``-n`` switch
had affected the
casing for the defining occurrence of the name.
The options
- :samp:`-a{x}`,
- :samp:`-k{x}`,
- :samp:`-ne{x}`,
- :samp:`-nt{x}`,
- :samp:`-nn{x}`, and
- :samp:`-p{x}`
+ :switch:`-a{x}`,
+ :switch:`-k{x}`,
+ :switch:`-ne{x}`,
+ :switch:`-nt{x}`,
+ :switch:`-nn{x}`, and
+ :switch:`-p{x}`
allow finer-grained control over casing for
attributes, keywords, enumeration literals,
types, named numbers and pragmas, respectively.
- :samp:`-nt{x}` covers subtypes and
+ :switch:`-nt{x}` covers subtypes and
task and protected bodies as well.
Some names may need to be spelled with casing conventions that are not
any ``-n`` switch.
To handle the casing of Ada predefined names and the names from GNAT libraries,
- *gnatpp* assumes a default dictionary file.
+ ``gnatpp`` assumes a default dictionary file.
The name of each predefined entity is spelled with the same casing as is used
for the entity in the :title:`Ada Reference Manual` (usually mixed case).
The name of each entity in the GNAT libraries is spelled with the same casing
the default dictionary file. Instead, the casing for predefined and
GNAT-defined names will be established by the
``-n`` switch or explicit dictionary files. For
- example, by default the names `Ada.Text_IO` and
- `GNAT.OS_Lib` will appear as just shown, even in the presence of
+ example, by default the names ``Ada.Text_IO`` and
+ ``GNAT.OS_Lib`` will appear as just shown, even in the presence of
a ``-nU`` switch. To ensure that even
such names are rendered in uppercase, additionally supply the
-D- switch (or else place these names
::
- `casing_schema` ::= `identifier` | `simple_identifier`
+ casing_schema ::= identifier | simple_identifier
- `simple_identifier` ::= `letter`{`letter_or_digit`}
+ simple_identifier ::= letter{letter_or_digit}
(See :title:`Ada Reference Manual`, Section 2.3) for the definition of the
- `identifier` lexical element and the `letter_or_digit` category.)
+ ``identifier`` lexical element and the ``letter_or_digit`` category.)
The casing schema string can be followed by white space and/or an Ada-style
comment; any amount of white space is allowed before the string.
If a dictionary file is passed as
- the value of a :samp:`-D{file}` switch
+ the value of a :switch:`-D{file}` switch
then for every
- simple name and every identifier, *gnatpp* checks if the dictionary
+ simple name and every identifier, ``gnatpp`` checks if the dictionary
defines the casing for the name or for some of its parts (the term 'subword'
is used below to denote the part of a name which is delimited by '_' or by
the beginning or end of the word and which does not contain any '_' inside):
- * if the whole name is in the dictionary, *gnatpp* uses for this name
+ * if the whole name is in the dictionary, ``gnatpp`` uses for this name
the casing defined by the dictionary; no subwords are checked for this word
- * for every subword *gnatpp* checks if the dictionary contains the
- corresponding string of the form `*`simple_identifier`*`,
- and if it does, the casing of this `simple_identifier` is used
+ * for every subword ``gnatpp`` checks if the dictionary contains the
+ corresponding string of the form ``simple_identifier``,
+ and if it does, the casing of this ``simple_identifier`` is used
for this subword
* if the whole name does not contain any '_' inside, and if for this name
- the dictionary contains two entries - one of the form `identifier`,
- and another - of the form *`simple_identifier`*, then the first one
+ the dictionary contains two entries -- one of the form ``identifier``,
+ and another of the form ``simple_identifier`` -- then the first one
is applied to define the casing of this name
- * if more than one dictionary file is passed as *gnatpp* switches, each
+ * if more than one dictionary file is passed as ``gnatpp`` switches, each
dictionary adds new casing exceptions and overrides all the existing casing
exceptions set by the previous dictionaries
- * when *gnatpp* checks if the word or subword is in the dictionary,
+ * when ``gnatpp`` checks if the word or subword is in the dictionary,
this check is not case sensitive
For example, suppose we have the following source to reformat:
*dict2:*
*NAME3*
- If *gnatpp* is called with the following switches:
+ If ``gnatpp`` is called with the following switches:
::
$ gnatpp -nM -D dict1 -D dict2 test.adb
- then we will get the following name casing in the *gnatpp* output:
+ then we will get the following name casing in the ``gnatpp`` output:
.. code-block:: ada
.. index:: ! gnatstub
- *gnatstub* creates empty but compilable bodies
+ ``gnatstub`` creates empty but compilable bodies
for library unit declarations, and empty but compilable
subunit for body stubs.
- *gnatstub* is a project-aware tool.
+ ``gnatstub`` is a project-aware tool.
(See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches but note that *gnatstub* does not support
- the :samp:`-U`, :samp:`-U {main_unit}`, :samp:`--subdirs={dir}`, or
- :samp:`--no_objects_dir` switches.)
+ the project-related switches but note that ``gnatstub`` does not support
+ the :switch:`-U`, :switch:`-U {main_unit}`, :switch:`--subdirs={dir}`, or
+ :switch:`--no_objects_dir` switches.)
The project file package that can specify
- *gnatstub* switches is named ``gnatstub``.
+ ``gnatstub`` switches is named ``gnatstub``.
- To create a body or a subunit, *gnatstub* invokes the Ada
+ To create a body or a subunit, ``gnatstub`` invokes the Ada
compiler and generates and uses the ASIS tree for the input source;
thus the input must be legal Ada code, and the tool should have all the
information needed to compile the input source. To provide this information,
(or you may call *gnatstub*
through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`).
Another possibility is to specify the source search
- path and needed configuration files in ``-cargs`` section of *gnatstub*
- call, see the description of the *gnatstub* switches below.
+ path and needed configuration files in ``-cargs`` section of ``gnatstub``
+ call, see the description of the ``gnatstub`` switches below.
- If the *gnatstub* argument source contains preprocessing directives
+ If the ``gnatstub`` argument source contains preprocessing directives
then the needed options should be provided to run preprocessor as a part of
- the *gnatstub* call, and the generated body stub will correspond to
+ the ``gnatstub`` call, and the generated body stub will correspond to
the preprocessed source.
- By default, all the program unit bodies generated by `gnatstub`
- raise the predefined `Program_Error` exception, which will catch
+ By default, all the program unit bodies generated by ``gnatstub``
+ raise the predefined ``Program_Error`` exception, which will catch
accidental calls of generated stubs. This behavior can be changed with
option ``--no-exception`` (see below).
.. _Running_gnatstub:
- Running *gnatstub*
- ------------------
+ Running ``gnatstub``
+ --------------------
- *gnatstub* invocation has the following form:
+ ``gnatstub`` invocation has the following form:
::
- $ gnatstub [`switches`] `filename` [-cargs `gcc_switches`]
+ $ gnatstub [ switches ] filename [ -cargs gcc_switches ]
where
of seitches does not contain a project file that defines naming
conventions, the name of the body file must
be provided
- explicitly as the value of the :samp:`-o{body-name}` option.
+ explicitly as the value of the :switch:`-o{body-name}` option.
If the file name follows the GNAT file naming
conventions and the name of the body file is not provided,
- *gnatstub*
+ ``gnatstub``
takes the naming conventions for the generated source from the
project file provided as a parameter of ``-P`` switch if any,
or creates the name file to generate using the standard GNAT
* *gcc_switches* is a list of switches for *gcc*.
They will be passed on to all compiler invocations made by
- *gnatstub* to generate the ASIS trees. Here you can provide
+ ``gnatstub`` to generate the ASIS trees. Here you can provide
``-I`` switches to form the source search path,
use the ``-gnatec`` switch to set the configuration file,
use the ``-gnat05`` switch if sources should be compiled in
.. _Switches_for_gnatstub:
- Switches for *gnatstub*
- -----------------------
+ Switches for ``gnatstub``
+ -------------------------
.. index:: --version (gnatstub)
- :samp:`--version`
+ :switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatstub)
- :samp:`--help`
+ :switch:`--help`
Display usage, then exit disregarding all other options.
.. index:: -P (gnatstub)
- :samp:`-P {file}`
+ :switch:`-P {file}`
Indicates the name of the project file that describes the set of sources
to be processed.
.. index:: -X (gnatstub)
- :samp:`-X{name}={value}`
- Indicates that external variable `name` in the argument project
- has the value `value`. Has no effect if no project is specified as
+ :switch:`-X{name}={value}`
+ Indicates that external variable ``name`` in the argument project
+ has the value ``value``. Has no effect if no project is specified as
tool argument.
.. index:: --RTS (gnatstub)
- :samp:`--RTS={rts-path}`
+ :switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: --subunits (gnatstub)
- :samp:`--subunits`
+ :switch:`--subunits`
Generate subunits for body stubs. If this switch is specified,
- *gnatstub* expects a library unit body as an agrument file,
+ ``gnatstub`` expects a library unit body as an agrument file,
otherwise a library unit declaration is expected. If a body stub
- already has a corresponding subunit, *gnatstub* does not
+ already has a corresponding subunit, ``gnatstub`` does not
generate anything for it.
.. index:: -f (gnatstub)
- :samp:`-f`
+ :switch:`-f`
If the destination directory already contains a file with the name of the
body file
for the argument spec file, replace it with the generated body stub.
.. index:: -hs (gnatstub)
- :samp:`-hs`
+ :switch:`-hs`
Put the comment header (i.e., all the comments preceding the
compilation unit) from the source of the library unit declaration
into the body stub.
.. index:: -hg (gnatstub)
- :samp:`-hg`
+ :switch:`-hg`
Put a sample comment header into the body stub.
.. index:: --header-file (gnatstub)
- :samp:`--header-file={filename}`
+ :switch:`--header-file={filename}`
Use the content of the file as the comment header for a generated body stub.
.. index:: -IDIR (gnatstub)
.. index:: -I- (gnatstub)
- :samp:`-I{DIR}`, :samp:`-I-`
+ :switch:`-I{DIR}`, :switch:`-I-`
These switches have the same meaning as in calls to
- *gcc*.
+ ``gcc``.
They define the source search path in the call to
- *gcc* issued
- by *gnatstub* to compile an argument source file.
+ ``gcc`` issued
+ by ``gnatstub`` to compile an argument source file.
.. index:: -gnatec (gnatstub)
- :samp:`-gnatec{PATH}`
- This switch has the same meaning as in calls to *gcc*.
+ :switch:`-gnatec{PATH}`
+ This switch has the same meaning as in calls to ``gcc``.
It defines the additional configuration file to be passed to the call to
- *gcc* issued
- by *gnatstub* to compile an argument source file.
+ ``gcc`` issued
+ by ``gnatstub`` to compile an argument source file.
.. index:: -gnatyM (gnatstub)
- :samp:`-gnatyM{n}`
- (`n` is a non-negative integer). Set the maximum line length that is
+ :switch:`-gnatyM{n}`
+ (``n`` is a non-negative integer). Set the maximum line length that is
allowed in a source file. The default is 79. The maximum value that can be
specified is 32767. Note that in the special case of configuration
pragma files, the maximum is always 32767 regardless of whether or
.. index:: -gnaty (gnatstub)
- :samp:`-gnaty{n}`
- (`n` is a non-negative integer from 1 to 9). Set the indentation level in
- the generated body sample to `n`.
+ :switch:`-gnaty{n}`
+ (``n`` is a non-negative integer from 1 to 9). Set the indentation level in
+ the generated body sample to ``n``.
The default indentation is 3.
.. index:: -gnatyo (gnatstub)
- :samp:`-gnatyo`
+ :switch:`-gnatyo`
Order local bodies alphabetically. (By default local bodies are ordered
in the same way as the corresponding local specs in the argument spec file.)
.. index:: -i (gnatstub)
- :samp:`-i{n}`
- Same as :samp:`-gnaty{n}``
+ :switch:`-i{n}`
+ Same as :switch:`-gnaty{n}``
.. index:: -k (gnatstub)
- :samp:`-k`
+ :switch:`-k`
Do not remove the tree file (i.e., the snapshot of the compiler internal
- structures used by *gnatstub*) after creating the body stub.
+ structures used by ``gnatstub``) after creating the body stub.
.. index:: -l (gnatstub)
- :samp:`-l{n}`
+ :switch:`-l{n}`
Same as ``-gnatyM`n```
.. index:: --no-exception (gnatstub)
- :samp:`--no-exception`
+ :switch:`--no-exception`
Avoid raising PROGRAM_ERROR in the generated bodies of program unit stubs.
This is not always possible for function stubs.
.. index:: --no-local-header (gnatstub)
- :samp:`--no-local-header`
+ :switch:`--no-local-header`
Do not place local comment header with unit name before body stub for a
unit.
.. index:: -o (gnatstub)
- :samp:`-o {body-name}`
+ :switch:`-o {body-name}`
Body file name. This should be set if the argument file name does not
follow
the GNAT file naming
.. index:: --dir (gnatstub)
- :samp:`--dir={dir-name}`
+ :switch:`--dir={dir-name}`
The path to the directory to place the generated files into.
If this switch is not set, the generated library unit body is
placed in the current directory, and generated sununits -
.. index:: -W (gnatstub)
- :samp:`-W{e}`
+ :switch:`-W{e}`
Specify the wide character encoding method for the output body file.
- `e` is one of the following:
+ ``e`` is one of the following:
==== ==================================
*h* Hex encoding
.. index:: -q (gnatstub)
- :samp:`-q`
+ :switch:`-q`
Quiet mode: do not generate a confirmation when a body is
successfully created, and do not generate a message when a body is not
required for an
.. index:: -r (gnatstub)
- :samp:`-r`
+ :switch:`-r`
Reuse the tree file (if it exists) instead of creating it. Instead of
- creating the tree file for the library unit declaration, *gnatstub*
+ creating the tree file for the library unit declaration, ``gnatstub``
tries to find it in the current directory and use it for creating
a body. If the tree file is not found, no body is created. This option
also implies ``-k``, whether or not
.. index:: -t (gnatstub)
- :samp:`-t`
+ :switch:`-t`
Overwrite the existing tree file. If the current directory already
contains the file which, according to the GNAT file naming rules should
be considered as a tree file for the argument source file,
- *gnatstub*
+ ``gnatstub``
will refuse to create the tree file needed to create a sample body
unless this option is set.
.. index:: -v (gnatstub)
- :samp:`-v`
+ :switch:`-v`
Verbose mode: generate version information.
.. _The_Unit_Test_Generator_gnattest:
- The Unit Test Generator *gnattest*
- ==================================
+ The Unit Test Generator ``gnattest``
+ ====================================
.. index:: ! gnattest
- *gnattest* is an ASIS-based utility that creates unit-test skeletons
- as well as a test driver infrastructure (harness). *gnattest* creates
+ ``gnattest`` is an ASIS-based utility that creates unit-test skeletons
+ as well as a test driver infrastructure (harness). ``gnattest`` creates
a skeleton for each visible subprogram in the packages under consideration when
they do not exist already.
- *gnattest* is a project-aware tool.
+ ``gnattest`` is a project-aware tool.
(See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches but note that *gnattest* does not support
- the :samp:`-U`, :samp:`-eL`, :samp:`--subdirs={dir}`, or
- :samp:`--no_objects_dir` switches.)
+ the project-related switches but note that ``gnattest`` does not support
+ the :switch:`-U`, :switch:`-eL`, :switch:`--subdirs={dir}`, or
+ :switch:`--no_objects_dir` switches.)
The project file package that can specify
- *gnattest* switches is named ``gnattest``.
+ ``gnattest`` switches is named ``gnattest``.
The user can choose to generate a single test driver
that will run all individual tests, or separate test drivers for each test. The
allows to benefit from parallel tests execution to increase performance, and
provides stubbing support.
- *gnattest* also has a mode of operation where it acts as the test
+ ``gnattest`` also has a mode of operation where it acts as the test
aggregator when multiple test executables must be run, in particular when
the separate test drivers were generated. In this mode it handles individual
tests execution and upon completion reports the summary results of the test
run.
- In order to process source files from a project, *gnattest* has to
+ In order to process source files from a project, ``gnattest`` has to
semantically analyze the sources. Therefore, test skeletons can only be
generated for legal Ada units. If a unit is dependent on other units,
those units should be among the source files of the project or of other projects
Generated skeletons and harnesses are based on the AUnit testing framework.
AUnit is an Ada adaptation of the xxxUnit testing frameworks, similar to JUnit
for Java or CppUnit for C++. While it is advised that gnattest users read
- the AUnit manual, deep knowledge of AUnit is not necessary for using *gnattest*.
- For correct operation of *gnattest*, AUnit should be installed and
+ the AUnit manual, deep knowledge of AUnit is not necessary for using ``gnattest``.
+ For correct operation of ``gnattest``, AUnit should be installed and
aunit.gpr must be on the project path. Except for some special circumstances
(e.g. a custom run-time is used), this should normally be the case out of the box.
.. _Running_gnattest:
- Running *gnattest*
- ------------------
+ Running ``gnattest``
+ --------------------
- There are two ways of running *gnattest*.
+ There are two ways of running ``gnattest``.
.. _Framework_Generation_Mode:
Framework Generation Mode
^^^^^^^^^^^^^^^^^^^^^^^^^
- In this mode *gnattest* has the following command-line interface:
+ In this mode ``gnattest`` has the following command-line interface:
::
- $ gnattest `-Pprojname` [`switches`] [`filename`] [-cargs `gcc_switches`]
+ $ gnattest -Pprojname [ switches ] [ filename ] [ -cargs gcc_switches ]
where
- * :samp:`-P{projname}`
+ * :switch:`-P{projname}`
specifies the project defining the location of source files. When no
file names are provided on the command line, all sources in the project
are used as input. This switch is required.
- * :samp:`{filename}`
- is the name of the source file containing the library unit package declaration
- for which a test package will be created. The file name may be given with a
- path.
+ * :switch:`{filename}`
+ is the name of the source file containing the library unit package *declaration*
+ (the package "spec") for which a test package will be created. The file name
+ may be given with a path.
* :samp:`{switches}`
is an optional sequence of switches as described below.
* :samp:`{gcc_switches}`
is a list of additional switches for
- *gcc* that will be passed to all compiler invocations
- made by *gnattest* to generate a set of ASIS trees.
+ ``gcc`` that will be passed to all compiler invocations
+ made by ``gnattest`` to generate a set of ASIS trees.
- *gnattest* results can be found in two different places.
+ ``gnattest`` results can be found in two different places.
* *automatic harness*:
This is the harness code, which is located by default in
automatically and can be destroyed and regenerated at will, with the
exception of the file *gnattest_common.gpr*, which is created if absent,
but never overwritten. It is not recommended to modify other files
- manually, since these modifications will be lost if *gnattest* is re-run.
+ manually, since these modifications will be lost if ``gnattest`` is re-run.
The entry point in the harness code is
the project file named *test_driver.gpr*. Tests can be compiled and run
using a command such as:
Test Execution Mode
^^^^^^^^^^^^^^^^^^^
- In this mode *gnattest* has a the following command-line interface:
+ In this mode ``gnattest`` has a the following command-line interface:
::
- $ gnattest `test_drivers.list` [`switches`]
+ $ gnattest test_drivers.list [ switches ]
where
.. _Switches_for_gnattest_in_framework_generation_mode:
- Switches for *gnattest* in framework generation mode
- ----------------------------------------------------
+ Switches for ``gnattest`` in framework generation mode
+ ------------------------------------------------------
+
+ .. index:: --strict (gnattest)
+
+ :switch:`--strict`
+ Return error exit code if there are any compilation errors.
.. index:: -q (gnattest)
- :samp:`-q`
+ :switch:`-q`
Quiet mode: suppresses noncritical output messages.
.. index:: -v (gnattest)
- :samp:`-v`
+ :switch:`-v`
Verbose mode: produces additional output about the execution of the tool.
When specified alone on the command line, prints tool version and exits.
.. index:: -r (gnattest)
- :samp:`-r`
+ :switch:`-r`
Recursively considers all sources from all projects.
.. index:: -files (gnattest)
- :samp:`-files={filename}`
- The name of a text file containing a list of Ada source files to process.
+ :switch:`-files={filename}`
+ Take as arguments the files listed in text file ``file``.
+ Text file ``file`` may contain empty lines that are ignored.
+ Each nonempty line should contain the name of an existing file.
+ Several such switches may be specified simultaneously.
.. index:: --RTS (gnattest)
- :samp:`--RTS={rts-path}`
+ :switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
- equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). For restricted
- profiles, *gnattest* takes into account the run-time limitations when
+ equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`). For restricted
+ profiles, ``gnattest`` takes into account the run-time limitations when
generating the harness.
.. index:: --additional-tests (gnattest)
- :samp:`--additional-tests={projname}`
- Sources described in `projname` are considered potential additional
+ :switch:`--additional-tests={projname}`
+ Sources described in ``projname`` are considered potential additional
manual tests to be added to the test suite.
.. index:: --harness-only (gnattest)
- :samp:`--harness-only`
- When this option is given, *gnattest* creates a harness for all
+ :switch:`--harness-only`
+ When this option is given, ``gnattest`` creates a harness for all
sources, treating them as test packages.
.. index:: --separate-drivers (gnattest)
- :samp:`--separate-drivers[={val}]`
+ :switch:`--separate-drivers[={val}]`
Generates a separate test driver for each test or unit under test, rather
- than a single executable incorporating all tests. `val` can be "unit" or
+ than a single executable incorporating all tests. ``val`` can be "unit" or
"test", or may be omitted, which defaults to "unit".
.. index:: --stub (gnattest)
- :samp:`--stub`
+ :switch:`--stub`
Generates the testing framework that uses subsystem stubbing to isolate the
code under test.
.. index:: --harness-dir (gnattest)
- :samp:`--harness-dir={dirname}`
+ :switch:`--harness-dir={dirname}`
Specifies the directory that will hold the harness packages and project file
- for the test driver. If the `dirname` is a relative path, it is considered
+ for the test driver. If the ``dirname`` is a relative path, it is considered
relative to the object directory of the project file.
.. index:: --tests-dir (gnattest)
- :samp:`--tests-dir={dirname}`
- All test packages are placed in the `dirname` directory.
- If the `dirname` is a relative path, it is considered relative to the object
+ :switch:`--tests-dir={dirname}`
+ All test packages are placed in the ``dirname`` directory.
+ If the ``dirname`` is a relative path, it is considered relative to the object
directory of the project file. When all sources from all projects are taken
- recursively from all projects, `dirname` directories are created for each
+ recursively from all projects, ``dirname`` directories are created for each
project in their object directories and test packages are placed accordingly.
.. index:: --subdir (gnattest)
- :samp:`--subdir={dirname}`
+ :switch:`--subdir={dirname}`
Test packages are placed in a subdirectory of the corresponding source
- directory, with the name `dirname`. Thus, each set of unit tests is located
+ directory, with the name ``dirname``. Thus, each set of unit tests is located
in a subdirectory of the code under test. If the sources are in separate
- directories, each source directory has a test subdirectory named `dirname`.
+ directories, each source directory has a test subdirectory named ``dirname``.
.. index:: --tests-root (gnattest)
- :samp:`--tests-root={dirname}`
- The hierarchy of source directories, if any, is recreated in the `dirname`
+ :switch:`--tests-root={dirname}`
+ The hierarchy of source directories, if any, is recreated in the ``dirname``
directory, with test packages placed in directories corresponding to those
of the sources.
- If the `dirname` is a relative path, it is considered relative to the object
+ If the ``dirname`` is a relative path, it is considered relative to the object
directory of the project file. When projects are considered recursively,
directory hierarchies of tested sources are
recreated for each project in their object directories and test packages are
.. index:: --stubs-dir (gnattest)
- :samp:`--stubs-dir={dirname}`
+ :switch:`--stubs-dir={dirname}`
The hierarchy of directories containing stubbed units is recreated in
- the `dirname` directory, with stubs placed in directories corresponding to
+ the ``dirname`` directory, with stubs placed in directories corresponding to
projects they are derived from.
- If the `dirname` is a relative path, it is considered relative to the object
+ If the ``dirname`` is a relative path, it is considered relative to the object
directory of the project file. When projects are considered recursively,
directory hierarchies of stubs are
recreated for each project in their object directories and test packages are
.. index:: --exclude-from-stubbing (gnattest)
- :samp:`--exclude-from-stubbing={filename}`
- Disables stubbing of units listed in `filename`. The file should contain
+ :switch:`--exclude-from-stubbing={filename}`
+ Disables stubbing of units listed in ``filename``. The file should contain
corresponding spec files, one per line.
- :samp:`--exclude-from-stubbing:{unit}={filename}`
+ :switch:`--exclude-from-stubbing:{unit}={filename}`
Same as above, but corresponding units will not be stubbed only when testing
- specified `unit`.
+ specified ``unit``.
.. index:: --validate-type-extensions (gnattest)
- :samp:`--validate-type-extensions`
+ :switch:`--validate-type-extensions`
Enables substitution check: run all tests from all parents in order
to check substitutability in accordance with the Liskov substitution principle (LSP).
+ .. index:: --inheritance-check (gnattest)
+
+ :switch:`--inheritance-check`
+ Enables inheritance check: run inherited tests against descendants.
+
+ .. index:: --no-inheritance-check (gnattest)
+
+ :switch:`--no-inheritance-check`
+ Disables inheritance check.
+
+ .. index:: --no-inheritance-check (gnattest)
+
+ :switch:`--test-case-only`
+ Generates test skeletons only for subprograms that have at least one
+ associated pragma or aspect Test_Case.
.. index:: --skeleton-default (gnattest)
- :samp:`--skeleton-default={val}`
- Specifies the default behavior of generated skeletons. `val` can be either
+ :switch:`--skeleton-default={val}`
+ Specifies the default behavior of generated skeletons. ``val`` can be either
"fail" or "pass", "fail" being the default.
.. index:: --passed-tests (gnattest)
- :samp:`--passed-tests={val}`
- Specifies whether or not passed tests should be shown. `val` can be either
+ :switch:`--passed-tests={val}`
+ Specifies whether or not passed tests should be shown. ``val`` can be either
"show" or "hide", "show" being the default.
.. index:: --exit-status (gnattest)
- :samp:`--exit-status={val}`
+ :switch:`--exit-status={val}`
Specifies whether or not generated test driver should return failure exit
- status if at least one test fails or crashes. `val` can be either
+ status if at least one test fails or crashes. ``val`` can be either
"on" or "off", "off" being the default.
.. index:: --omit-sloc (gnattest)
- :samp:`--omit-sloc`
+ :switch:`--omit-sloc`
Suppresses comment line containing file name and line number of corresponding
subprograms in test skeletons.
.. index:: --no-command-line (gnattest)
- :samp:`--no-command-line`
+ :switch:`--no-command-line`
Don't add command line support to test driver. Note that regardless of this
- switch, *gnattest* will automatically refrain from adding command
+ switch, ``gnattest`` will automatically refrain from adding command
line support if it detects that the selected run-time doesn't provide
this capability.
.. index:: --separates (gnattest)
- :samp:`--separates`
+ :switch:`--separates`
Bodies of all test routines are generated as separates. Note that this mode is
kept for compatibility reasons only and it is not advised to use it due to
possible problems with hash in names of test skeletons when using an
.. index:: --transition (gnattest)
- :samp:`--transition`
+ :switch:`--transition`
This allows transition from separate test routines to monolith test packages.
All matching test routines are overwritten with contents of corresponding
separates. Note that if separate test routines had any manually added with
.. index:: --test-duration (gnattest)
- :samp:`--test-duration`
+ :switch:`--test-duration`
Adds time measurements for each test in generated test driver.
- :samp:`--tests_root`, ``--subdir`` and ``--tests-dir`` switches are mutually exclusive.
+ :switch:`--tests_root`, :switch:`--subdir` and :switch:`--tests-dir` switches are mutually exclusive.
.. _Switches_for_gnattest_in_test_execution_mode:
- Switches for *gnattest* in test execution mode
- ----------------------------------------------
+ Switches for ``gnattest`` in test execution mode
+ ------------------------------------------------
.. index:: --passed-tests (gnattest)
- :samp:`--passed-tests={val}`
- Specifies whether or not passed tests should be shown. `val` can be either
+ :switch:`--passed-tests={val}`
+ Specifies whether or not passed tests should be shown. ``val`` can be either
"show" or "hide", "show" being the default.
.. index:: --queues (gnattest)
.. index:: -j (gnattest)
- :samp:`--queues={n}`, :samp:`-j{n}`
- Runs `n` tests in parallel (default is 1).
+ :switch:`--queues={n}`, :switch:`-j{n}`
+ Runs ``n`` tests in parallel (default is 1).
.. _Project_Attributes_for_gnattest:
- Project Attributes for *gnattest*
- ---------------------------------
+ Project Attributes for ``gnattest``
+ -----------------------------------
Most of the command-line options can also be passed to the tool by adding
special attributes to the project file. Those attributes should be put in
- package **Gnattest**. Here is the list of attributes:
+ package ``Gnattest``. Here is the list of attributes:
* ``Tests_Root``
``--exclude-from-stubbing:unit=filename``.
Each of those attributes can be overridden from the command line if needed.
- Other *gnattest* switches can also be passed via the project
- file as an attribute list called *Gnattest_Switches*.
+ Other ``gnattest`` switches can also be passed via the project
+ file as an attribute list called ``Gnattest_Switches``.
.. _Simple_gnattest_Example:
Simple Example
--------------
- Let's take a very simple example using the first *gnattest* example
+ Let's take a very simple example using the first ``gnattest`` example
located in:
::
<install_prefix>/share/examples/gnattest/simple
- This project contains a simple package containing one subprogram. By running *gnattest*:
+ This project contains a simple package containing one subprogram. By running ``gnattest``:
::
bodies and are surrounded by special comment sections. Those comment sections
should not be removed or modified in order for gnattest to be able to regenerate
test packages and keep already written tests in place.
- The test routine `Test_Inc_5eaee3` located at ``simple-test_data-tests.adb`` contains
- a single statement: a call to procedure `Assert`. It has two arguments:
+ The test routine ``Test_Inc_5eaee3`` located at :file:`simple-test_data-tests.adb` contains
+ a single statement: a call to procedure ``Assert``. It has two arguments:
the Boolean expression we want to check and the diagnosis message to display if
the condition is false.
That is where actual testing code should be written after a proper setup.
- An actual check can be performed by replacing the `Assert` call with:
+ An actual check can be performed by replacing the ``Assert`` call with:
::
---------------------------------------------------
Besides test routines themselves, each test package has a parent package
- `Test_Data` that has two procedures: `Set_Up` and `Tear_Down`. This package is never
- overwritten by the tool. `Set_Up` is called before each test routine of the
- package, and `Tear_Down` is called after each test routine. Those two procedures
+ ``Test_Data`` that has two procedures: ``Set_Up`` and ``Tear_Down``. This package is never
+ overwritten by the tool. ``Set_Up`` is called before each test routine of the
+ package, and ``Tear_Down`` is called after each test routine. Those two procedures
can be used to perform necessary initialization and finalization,
- memory allocation, etc. Test type declared in `Test_Data` package is parent type
+ memory allocation, etc. Test type declared in ``Test_Data`` package is parent type
for the test type of test package and can have user-defined components whose
- values can be set by `Set_Up` routine and used in test routines afterwards.
+ values can be set by ``Set_Up`` routine and used in test routines afterwards.
.. _Regenerating_Tests:
Regenerating Tests
------------------
- Bodies of test routines and `Test_Data` packages are never overridden after they
+ Bodies of test routines and ``Test_Data`` packages are never overridden after they
have been created once. As long as the name of the subprogram, full expanded Ada
names and order of its parameters are the same, and comment sections are
intact, the old test routine will fit in its place and no test skeleton will be
This can be demonstrated with the previous example. By uncommenting declaration
and body of function Dec in ``simple.ads`` and ``simple.adb``, running
- *gnattest* on the project, and then running the test driver:
+ ``gnattest`` on the project, and then running the test driver:
::
$ test_runner
The old test is not replaced with a stub, nor is it lost, but a new test
- skeleton is created for function `Dec`.
+ skeleton is created for function ``Dec``.
The only way of regenerating tests skeletons is to remove the previously created
tests together with corresponding comment sections.
actually failing).
The test driver accepts a switch to specify this behavior:
- :samp:`--skeleton-default={val}`, where ``val`` is either ``pass`` or ``fail`` (exactly as for
- *gnattest*).
+ :switch:`--skeleton-default={val}`, where ``val`` is either ``pass`` or ``fail`` (exactly as for
+ ``gnattest``).
The default behavior of the test driver is set with the same switch
- as passed to *gnattest* when generating the test driver.
+ as passed to ``gnattest`` when generating the test driver.
Passing it to the driver generated on the first example:
Creation of test skeletons for primitive operations of tagged types entails
a number of features. Test routines for all primitives of a given tagged type
are placed in a separate child package named according to the tagged type. For
- example, if you have tagged type *T* in package *P*, all tests for primitives
- of *T* will be in *P.T_Test_Data.T_Tests*.
+ example, if you have tagged type ``T`` in package ``P``, all tests for primitives
+ of ``T`` will be in ``P.T_Test_Data.T_Tests``.
- Consider running *gnattest* on the second example (note: actual tests for this
+ Consider running ``gnattest`` on the second example (note: actual tests for this
example already exist, so there's no need to worry if the tool reports that
no new stubs were generated):
when generating test packages for primitive operations, there are some things
the user needs to know.
- Type *Test_Controller* has components that allow assignment of various
- derivations of type *Controller*. And if you look at the specification of
- package *Speed2.Auto_Controller*, you will see that *Test_Auto_Controller*
- actually derives from *Test_Controller* rather than AUnit type *Test_Fixture*.
+ Type ``Test_Controller`` has components that allow assignment of various
+ derivations of type ``Controller``. And if you look at the specification of
+ package *Speed2.Auto_Controller*, you will see that ``Test_Auto_Controller``
+ actually derives from ``Test_Controller`` rather than AUnit type ``Test_Fixture``.
Thus, test types mirror the hierarchy of tested types.
- The *Set_Up* procedure of *Test_Data* package corresponding to a test package
- of primitive operations of type *T* assigns to *Fixture* a reference to an
- object of that exact type *T*. Note, however, that if the tagged type has
- discriminants, the *Set_Up* only has a commented template for setting
+ The ``Set_Up`` procedure of ``Test_Data`` package corresponding to a test package
+ of primitive operations of type ``T`` assigns to ``Fixture`` a reference to an
+ object of that exact type ``T``. Note, however, that if the tagged type has
+ discriminants, the ``Set_Up`` only has a commented template for setting
up the fixture, since filling the discriminant with actual value is up
to the user.
*Tagged Type Substitutability Testing* is a way of verifying the global type
consistency by testing. Global type consistency is a principle stating that if
- *S* is a subtype of *T* (in Ada, *S* is a derived type of tagged type *T*),
- then objects of type *T* may be replaced with objects of type *S* (that is,
- objects of type *S* may be substituted for objects of type *T*), without
+ ``S`` is a subtype of ``T`` (in Ada, ``S`` is a derived type of tagged type ``T``),
+ then objects of type ``T`` may be replaced with objects of type ``S`` (that is,
+ objects of type ``S`` may be substituted for objects of type ``T``), without
altering any of the desirable properties of the program. When the properties
of the program are expressed in the form of subprogram preconditions and
postconditions (let's call them pre and post), the principle is formulated as
derived types.
In the example used in the previous section, there was clearly a violation of
- type consistency. The overriding primitive *Adjust_Speed* in package *Speed2*
+ type consistency. The overriding primitive ``Adjust_Speed`` in package ``Speed2``
removes the functionality of the overridden primitive and thus doesn't respect
the consistency principle.
- *Gnattest* has a special option to run overridden parent tests against objects
+ ``gnattest`` has a special option to run overridden parent tests against objects
of the type which have overriding primitives:
::
$ gprbuild -Ptest_driver
$ test_runner
- While all the tests pass by themselves, the parent test for *Adjust_Speed* fails
+ While all the tests pass by themselves, the parent test for ``Adjust_Speed`` fails
against objects of the derived type.
Non-overridden tests are already inherited for derived test types, so the
Testing with Contracts
----------------------
- *gnattest* supports pragmas *Pre*, *Post*, and *Test_Case*,
+ ``gnattest`` supports pragmas ``Pre``, ``Post``, and ``Test_Case``,
as well as the corresponding Ada 2012 aspects.
- Test routines are generated, one per each *Test_Case* associated with a tested
+ Test routines are generated, one per each ``Test_Case`` associated with a tested
subprogram. Those test routines have special wrappers for tested functions
that have composition of pre- and postcondition of the subprogram with
- "requires" and "ensures" of the *Test_Case* (depending on the mode, pre and post
- either count for *Nominal* mode or do **not** count for *Robustness* mode).
+ "requires" and "ensures" of the ``Test_Case`` (depending on the mode, pre and post
+ either count for ``Nominal`` mode or do *not* count for ``Robustness`` mode).
The third example demonstrates how this works:
Additional Tests
----------------
- *gnattest* can add user-written tests to the main suite of the test
- driver. *gnattest* traverses the given packages and searches for test
+ ``gnattest`` can add user-written tests to the main suite of the test
+ driver. ``gnattest`` traverses the given packages and searches for test
routines. All procedures with a single in out parameter of a type which is
derived from *AUnit.Test_Fixtures.Test_Fixture* and that are declared in package
specifications are added to the suites and are then executed by the test driver.
- (*Set_Up* and *Tear_Down* are filtered out.)
+ (``Set_Up`` and ``Tear_Down`` are filtered out.)
An example illustrates two ways of creating test harnesses for user-written
- tests. Directory `additional_tests` contains an AUnit-based test driver written
+ tests. Directory ``additional_tests`` contains an AUnit-based test driver written
by hand.
::
Individual Test Drivers
-----------------------
- By default, *gnattest* generates a monolithic test driver that
+ By default, ``gnattest`` generates a monolithic test driver that
aggregates the individual tests into a single executable. It is also possible
to generate separate executables for each test or each unit under test, by
passing the switch ``--separate-drivers`` with corresponding parameter. This
also provide a major performance benefit on multi-core systems by allowing
simultaneous execution of multiple tests.
- *gnattest* can take charge of executing the individual tests; for this,
+ ``gnattest`` can take charge of executing the individual tests; for this,
instead of passing a project file, a text file containing the list of
executables can be passed. Such a file is automatically generated by gnattest
under the name :file:`test_drivers.list`, but it can be
This mode of test harness generation is activated by the switch ``--stub``.
- The implementation approach chosen by *gnattest* is as follows.
+ The implementation approach chosen by ``gnattest`` is as follows.
For each package under consideration all the packages it is directly depending
on are stubbed, excluding the generic packages and package instantiations.
The stubs are shared for each package under test. The specs of packages to stub
.. note::
Developing a stubs-based testing campaign requires
- good understanding of the infrastructure created by *gnattest* for
+ good understanding of the infrastructure created by ``gnattest`` for
this purpose. We recommend following the two stubbing tutorials
- `simple_stubbing` and `advanced_stubbing` provided
+ ``simple_stubbing`` and ``advanced_stubbing`` provided
under :file:`<install_prefix>/share/examples/gnattest` before
attempting to use this powerful feature.
Integration with GNATcoverage
-----------------------------
- In addition to the harness, *gnattest* generates a Makefile. This Makefile
+ In addition to the harness, ``gnattest`` generates a Makefile. This Makefile
provides targets for building the test drivers and also the targets for
computing the coverage information using GNATcoverage framework when this
coverage analysis tool is available. The target ``coverage`` fully automates
Putting Tests under Version Control
-----------------------------------
- As has been stated earlier, *gnattest* generates two different types
+ As has been stated earlier, ``gnattest`` generates two different types
of code, test skeletons and harness. The harness is generated completely
automatically each time, does not require manual changes and therefore should
not be put under version control.
* generic tests for nested generic packages and their instantiations are
not supported;
* tests for protected subprograms and entries are not supported;
- * pragma *No_Run_Time* is not supported;
- * pragma *No_Secondary_Stack* is not supported;
+ * pragma ``No_Run_Time`` is not supported;
+ * pragma ``No_Secondary_Stack`` is not supported;
* if pragmas for interfacing with foreign languages are used, manual
adjustments might be necessary to make the test harness compilable;
* use of some constructs, such as elaboration-control pragmas, Type_Invariant
The following switches are used by the project-aware GNAT tools:
- :samp:`-P{project_file}`
+ :switch:`-P{project_file}`
Indicates the name of the project file whose source files are to
be processed. The exact set of sources depends on other options
specified, see below.
- :samp:`-U`
+ :switch:`-U`
If a project file is supplied, say for project ``proj``,
but no sources are specified for ``proj`` (either by a
project attribute or through a tool option that provides a list
from projects imported either directly or indirectly by ``proj``.
Otherwise this option has no effect.
- :samp:`-U {source_file}`
- Similar to :samp:`-U`, but if no sources are specified then
+ :switch:`-U {source_file}`
+ Similar to :switch:`-U`, but if no sources are specified then
process only those source files for units in the closure of
- the Ada source contained in `source_file`. Note that this option
+ the Ada source contained in ``source_file``. Note that this option
expects the source file name but not the Ada unit name as its
parameter.
- :samp:`-X{name}={val}`
+ :switch:`-X{name}={val}`
Indicates that the external variable ``name`` in the project has the
value ``val``. Has no effect if no project has been specified.
- :samp:`--subdirs={dir}`
- Use the `dir` subdirectory of the project's object directory (or the `dir`
+ :switch:`--subdirs={dir}`
+ Use the ``dir`` subdirectory of the project's object directory (or the ``dir``
subdirectory of the project file directory if the project does not specify
an object directory) for tool output files. Has no effect if no project
- has been specified or if :samp:`--no_objects_dir` is specified.
+ has been specified or if :switch:`--no_objects_dir` is specified.
- :samp:`--no_objects_dir`
+ :switch:`--no_objects_dir`
Place all the result files into the current directory (i.e., the directory
from which the tool invocation command is issued) instead of the project's
object directory. Has no effect if no project has been specified.
- :samp:`-eL`
+ :switch:`-eL`
Follow all symbolic links when processing project files.
- If a project file is specified and there is neither a :samp:`-U` option,
- nor a :samp:`-U {main_unit}` option, nor some other explicit option to
+ If a project file is specified and there is neither a :switch:`-U` option,
+ nor a :switch:`-U {main_unit}` option, nor some other explicit option to
specify the source files, then the sources to be processed are the
immediate sources of the specified project (i.e., the source files directly
defined by that project, either implicitly by residing in the project
+.. role:: switch(samp)
+
.. _Inline_Assembler:
****************
supported by GNAT. However, for small sections of code it may be simpler
or more efficient to include assembly language statements directly
in your Ada source program, using the facilities of the implementation-defined
-package `System.Machine_Code`, which incorporates the gcc
+package ``System.Machine_Code``, which incorporates the gcc
Inline Assembler. The Inline Assembler approach offers a number of advantages,
including the following:
The assembler used by GNAT and gcc is based not on the Intel assembly
language, but rather on a language that descends from the AT&T Unix
-assembler *as* (and which is often referred to as 'AT&T syntax').
-The following table summarizes the main features of *as* syntax
+assembler ``as`` (and which is often referred to as 'AT&T syntax').
+The following table summarizes the main features of ``as`` syntax
and points out the differences from the Intel conventions.
-See the gcc *as* and *gas* (an *as* macro
+See the gcc ``as`` and ``gas`` (an ``as`` macro
pre-processor) documentation for further information.
| *Register names*
-| gcc / *as*: Prefix with '%'; for example `%eax`
-| Intel: No extra punctuation; for example `eax`
+| gcc / ``as``: Prefix with '%'; for example ``%eax``
+| Intel: No extra punctuation; for example ``eax``
| *Immediate operand*
-| gcc / *as*: Prefix with '$'; for example `$4`
-| Intel: No extra punctuation; for example `4`
+| gcc / ``as``: Prefix with '$'; for example ``$4``
+| Intel: No extra punctuation; for example ``4``
| *Address*
-| gcc / *as*: Prefix with '$'; for example `$loc`
-| Intel: No extra punctuation; for example `loc`
+| gcc / ``as``: Prefix with '$'; for example ``$loc``
+| Intel: No extra punctuation; for example ``loc``
| *Memory contents*
-| gcc / *as*: No extra punctuation; for example `loc`
-| Intel: Square brackets; for example `[loc]`
+| gcc / ``as``: No extra punctuation; for example ``loc``
+| Intel: Square brackets; for example ``[loc]``
| *Register contents*
-| gcc / *as*: Parentheses; for example `(%eax)`
-| Intel: Square brackets; for example `[eax]`
+| gcc / ``as``: Parentheses; for example ``(%eax)``
+| Intel: Square brackets; for example ``[eax]``
| *Hexadecimal numbers*
-| gcc / *as*: Leading '0x' (C language syntax); for example `0xA0`
-| Intel: Trailing 'h'; for example `A0h`
+| gcc / ``as``: Leading '0x' (C language syntax); for example ``0xA0``
+| Intel: Trailing 'h'; for example ``A0h``
| *Operand size*
-| gcc / *as*: Explicit in op code; for example `movw` to move a 16-bit word
-| Intel: Implicit, deduced by assembler; for example `mov`
+| gcc / ``as``: Explicit in op code; for example ``movw`` to move a 16-bit word
+| Intel: Implicit, deduced by assembler; for example ``mov``
| *Instruction repetition*
-| gcc / *as*: Split into two lines; for example
-| `rep`
-| `stosl`
-| Intel: Keep on one line; for example `rep stosl`
+| gcc / ``as``: Split into two lines; for example
+| ``rep``
+| ``stosl``
+| Intel: Keep on one line; for example ``rep stosl``
| *Order of operands*
-| gcc / *as*: Source first; for example `movw $4, %eax`
-| Intel: Destination first; for example `mov eax, 4`
+| gcc / ``as``: Source first; for example ``movw $4, %eax``
+| Intel: Destination first; for example ``mov eax, 4``
.. _A_Simple_Example_of_Inline_Assembler:
====================================
The following example will generate a single assembly language statement,
-`nop`, which does nothing. Despite its lack of run-time effect,
+``nop``, which does nothing. Despite its lack of run-time effect,
the example will be useful in illustrating the basics of
the Inline Assembler facility.
Asm ("nop");
end Nothing;
-`Asm` is a procedure declared in package `System.Machine_Code`;
+``Asm`` is a procedure declared in package ``System.Machine_Code``;
here it takes one parameter, a *template string* that must be a static
expression and that will form the generated instruction.
-`Asm` may be regarded as a compile-time procedure that parses
+``Asm`` may be regarded as a compile-time procedure that parses
the template string and additional parameters (none here),
from which it generates a sequence of assembly language instructions.
The examples in this chapter will illustrate several of the forms
-for invoking `Asm`; a complete specification of the syntax
-is found in the `Machine_Code_Insertions` section of the
+for invoking ``Asm``; a complete specification of the syntax
+is found in the ``Machine_Code_Insertions`` section of the
:title:`GNAT Reference Manual`.
-Under the standard GNAT conventions, the `Nothing` procedure
+Under the standard GNAT conventions, the ``Nothing`` procedure
should be in a file named :file:`nothing.adb`.
You can build the executable in the usual way:
where the options are:
-* :samp:`-c`
+* :switch:`-c`
compile only (no bind or link)
-* :samp:`-S`
+* :switch:`-S`
generate assembler listing
-* :samp:`-fomit-frame-pointer`
+* :switch:`-fomit-frame-pointer`
do not set up separate stack frames
-* :samp:`-gnatp`
+* :switch:`-gnatp`
do not add runtime checks
This gives a human-readable assembler version of the code. The resulting
-file will have the same name as the Ada source file, but with a `.s`
+file will have the same name as the Ada source file, but with a ``.s``
extension. In our example, the file :file:`nothing.s` has the following
contents:
ret
The assembly code you included is clearly indicated by
-the compiler, between the `#APP` and `#NO_APP`
+the compiler, between the ``#APP`` and ``#NO_APP``
delimiters. The character before the 'APP' and 'NOAPP'
can differ on different targets. For example, GNU/Linux uses '#APP' while
on NT you will see '/APP'.
will report this error in a temporary file, which will be deleted when
the compilation is finished. Generating an assembler file will help
in such cases, since you can assemble this file separately using the
-*as* assembler that comes with gcc.
+``as`` assembler that comes with gcc.
Assembling the file using the command
will give you error messages whose lines correspond to the assembler
input file, so you can easily find and correct any mistakes you made.
-If there are no errors, *as* will generate an object file
+If there are no errors, ``as`` will generate an object file
:file:`nothing.out`.
When writing Inline Assembler instructions, you need to precede each register
and variable name with a percent sign. Since the assembler already requires
a percent sign at the beginning of a register name, you need two consecutive
-percent signs for such names in the Asm template string, thus `%%eax`.
+percent signs for such names in the Asm template string, thus ``%%eax``.
In the generated assembly code, one of the percent signs will be stripped off.
-Names such as `%0`, `%1`, `%2`, etc., denote input or output
-variables: operands you later define using `Input` or `Output`
-parameters to `Asm`.
+Names such as ``%0``, ``%1``, ``%2``, etc., denote input or output
+variables: operands you later define using ``Input`` or ``Output``
+parameters to ``Asm``.
An output variable is illustrated in
the third statement in the Asm template string:
movl %%eax, %0
The intent is to store the contents of the eax register in a variable that can
-be accessed in Ada. Simply writing `movl %%eax, Flags` would not
+be accessed in Ada. Simply writing ``movl %%eax, Flags`` would not
necessarily work, since the compiler might optimize by using a register
-to hold Flags, and the expansion of the `movl` instruction would not be
+to hold Flags, and the expansion of the ``movl`` instruction would not be
aware of this optimization. The solution is not to store the result directly
but rather to advise the compiler to choose the correct operand form;
-that is the purpose of the `%0` output variable.
+that is the purpose of the ``%0`` output variable.
-Information about the output variable is supplied in the `Outputs`
-parameter to `Asm`:
+Information about the output variable is supplied in the ``Outputs``
+parameter to ``Asm``:
.. code-block:: ada
Outputs => Unsigned_32'Asm_Output ("=g", Flags));
-The output is defined by the `Asm_Output` attribute of the target type;
+The output is defined by the ``Asm_Output`` attribute of the target type;
the general format is
.. code-block:: ada
Unsigned_32'Asm_Output ("=m", Flags);
-the `"m"` (memory) constraint tells the compiler that the variable
-`Flags` should be stored in a memory variable, thus preventing
+the ``"m"`` (memory) constraint tells the compiler that the variable
+``Flags`` should be stored in a memory variable, thus preventing
the optimizer from keeping it in a register. In contrast,
.. code-block:: ada
Unsigned_32'Asm_Output ("=r", Flags);
-uses the `"r"` (register) constraint, telling the compiler to
+uses the ``"r"`` (register) constraint, telling the compiler to
store the variable in a register.
If the constraint is preceded by the equal character '=', it tells
the compiler that the variable will be used to store data into it.
-In the `Get_Flags` example, we used the `"g"` (global) constraint,
+In the ``Get_Flags`` example, we used the ``"g"`` (global) constraint,
allowing the optimizer to choose whatever it deems best.
There are a fairly large number of constraints, but the ones that are
*q* use one of eax, ebx, ecx, edx, esi or edi
====== ==========================================
-The full set of constraints is described in the gcc and *as*
+The full set of constraints is described in the gcc and ``as``
documentation; note that it is possible to combine certain constraints
in one constraint string.
Outputs => Unsigned_32'Asm_Output ("=g", Flags));
-`%0` will be replaced in the expanded code by the appropriate operand,
+``%0`` will be replaced in the expanded code by the appropriate operand,
whatever
-the compiler decided for the `Flags` variable.
+the compiler decided for the ``Flags`` variable.
In general, you may have any number of output variables:
-* Count the operands starting at 0; thus `%0`, `%1`, etc.
+* Count the operands starting at 0; thus ``%0``, ``%1``, etc.
-* Specify the `Outputs` parameter as a parenthesized comma-separated list
- of `Asm_Output` attributes
+* Specify the ``Outputs`` parameter as a parenthesized comma-separated list
+ of ``Asm_Output`` attributes
For example:
Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B
Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C
-where `Var_A`, `Var_B`, and `Var_C` are variables
+where ``Var_A``, ``Var_B``, and ``Var_C`` are variables
in the Ada program.
-As a variation on the `Get_Flags` example, we can use the constraints
-string to direct the compiler to store the eax register into the `Flags`
+As a variation on the ``Get_Flags`` example, we can use the constraints
+string to direct the compiler to store the eax register into the ``Flags``
variable, instead of including the store instruction explicitly in the
-`Asm` template string:
+``Asm`` template string:
.. code-block:: ada
Put_Line ("Flags register:" & Flags'Img);
end Get_Flags_2;
-The `"a"` constraint tells the compiler that the `Flags`
+The ``"a"`` constraint tells the compiler that the ``Flags``
variable will come from the eax register. Here is the resulting code:
::
Put_Line ("Value after is" & Value'Img);
end Increment;
-The `Outputs` parameter to `Asm` specifies
+The ``Outputs`` parameter to ``Asm`` specifies
that the result will be in the eax register and that it is to be stored
-in the `Result` variable.
+in the ``Result`` variable.
-The `Inputs` parameter looks much like the `Outputs` parameter,
-but with an `Asm_Input` attribute.
-The `"="` constraint, indicating an output value, is not present.
+The ``Inputs`` parameter looks much like the ``Outputs`` parameter,
+but with an ``Asm_Input`` attribute.
+The ``"="`` constraint, indicating an output value, is not present.
You can have multiple input variables, in the same way that you can have more
than one output variable.
The parameter count (%0, %1) etc, still starts at the first output statement,
and continues with the input statements.
-Just as the `Outputs` parameter causes the register to be stored into the
+Just as the ``Outputs`` parameter causes the register to be stored into the
target variable after execution of the assembler statements, so does the
-`Inputs` parameter cause its variable to be loaded into the register
+``Inputs`` parameter cause its variable to be loaded into the register
before execution of the assembler statements.
-Thus the effect of the `Asm` invocation is:
+Thus the effect of the ``Asm`` invocation is:
-* load the 32-bit value of `Value` into eax
-* execute the `incl %eax` instruction
-* store the contents of eax into the `Result` variable
+* load the 32-bit value of ``Value`` into eax
+* execute the ``incl %eax`` instruction
+* store the contents of eax into the ``Result`` variable
-The resulting assembler file (with *-O2* optimization) contains:
+The resulting assembler file (with :switch:`-O2` optimization) contains:
::
Inlining Inline Assembler Code
==============================
-For a short subprogram such as the `Incr` function in the previous
+For a short subprogram such as the ``Incr`` function in the previous
section, the overhead of the call and return (creating / deleting the stack
frame) can be significant, compared to the amount of code in the subprogram
-body. A solution is to apply Ada's `Inline` pragma to the subprogram,
+body. A solution is to apply Ada's ``Inline`` pragma to the subprogram,
which directs the compiler to expand invocations of the subprogram at the
point(s) of call, instead of setting up a stack frame for out-of-line calls.
Here is the resulting program:
Put_Line ("Value after is" & Value'Img);
end Increment_2;
-Compile the program with both optimization (*-O2*) and inlining
-(*-gnatn*) enabled.
+Compile the program with both optimization (:switch:`-O2`) and inlining
+(:switch:`-gnatn`) enabled.
-The `Incr` function is still compiled as usual, but at the
-point in `Increment` where our function used to be called:
+The ``Incr`` function is still compiled as usual, but at the
+point in ``Increment`` where our function used to be called:
::
thus saving the overhead of stack frame setup and an out-of-line call.
-.. _Other_`Asm`_Functionality:
+.. _Other_Asm_Functionality:
-Other `Asm` Functionality
-=========================
+Other ``Asm`` Functionality
+===========================
-This section describes two important parameters to the `Asm`
-procedure: `Clobber`, which identifies register usage;
-and `Volatile`, which inhibits unwanted optimizations.
+This section describes two important parameters to the ``Asm``
+procedure: ``Clobber``, which identifies register usage;
+and ``Volatile``, which inhibits unwanted optimizations.
-.. _The_`Clobber`_Parameter:
+.. _The_Clobber_Parameter:
-The `Clobber` Parameter
------------------------
+The ``Clobber`` Parameter
+-------------------------
One of the dangers of intermixing assembly language and a compiled language
such as Ada is that the compiler needs to be aware of which registers are
being used by the assembly code. In some cases, such as the earlier examples,
the constraint string is sufficient to indicate register usage (e.g.,
-`"a"` for
+``"a"`` for
the eax register). But more generally, the compiler needs an explicit
identification of the registers that are used by the Inline Assembly
statements.
Using a register that the compiler doesn't know about
-could be a side effect of an instruction (like `mull`
+could be a side effect of an instruction (like ``mull``
storing its result in both eax and edx).
It can also arise from explicit register usage in your
assembly code; for example:
Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
Inputs => Unsigned_32'Asm_Input ("g", Var_In));
-where the compiler (since it does not analyze the `Asm` template string)
+where the compiler (since it does not analyze the ``Asm`` template string)
does not know you are using the ebx register.
-In such cases you need to supply the `Clobber` parameter to `Asm`,
+In such cases you need to supply the ``Clobber`` parameter to ``Asm``,
to identify the registers that will be used by your assembly code:
The Clobber parameter is a static string expression specifying the
register(s) you are using. Note that register names are *not* prefixed
by a percent sign. Also, if more than one register is used then their names
-are separated by commas; e.g., `"eax, ebx"`
+are separated by commas; e.g., ``"eax, ebx"``
-The `Clobber` parameter has several additional uses:
+The ``Clobber`` parameter has several additional uses:
-* Use 'register' name `cc` to indicate that flags might have changed
-* Use 'register' name `memory` if you changed a memory location
+* Use 'register' name ``cc`` to indicate that flags might have changed
+* Use 'register' name ``memory`` if you changed a memory location
-.. _The_`Volatile`_Parameter:
+.. _The_Volatile_Parameter:
-The `Volatile` Parameter
-------------------------
+The ``Volatile`` Parameter
+--------------------------
.. index:: Volatile parameter
Compiler optimizations in the presence of Inline Assembler may sometimes have
-unwanted effects. For example, when an `Asm` invocation with an input
+unwanted effects. For example, when an ``Asm`` invocation with an input
variable is inside a loop, the compiler might move the loading of the input
variable outside the loop, regarding it as a one-time initialization.
If this effect is not desired, you can disable such optimizations by setting
-the `Volatile` parameter to `True`; for example:
+the ``Volatile`` parameter to ``True``; for example:
.. code-block:: ada
Clobber => "ebx",
Volatile => True);
-By default, `Volatile` is set to `False` unless there is no
-`Outputs` parameter.
+By default, ``Volatile`` is set to ``False`` unless there is no
+``Outputs`` parameter.
-Although setting `Volatile` to `True` prevents unwanted
+Although setting ``Volatile`` to ``True`` prevents unwanted
optimizations, it will also disable other optimizations that might be
-important for efficiency. In general, you should set `Volatile`
-to `True` only if the compiler's optimizations have created
+important for efficiency. In general, you should set ``Volatile``
+to ``True`` only if the compiler's optimizations have created
problems.
+.. role:: switch(samp)
+
.. -- Non-breaking space in running text
-- E.g. Ada |nbsp| 95
.. index:: --RTS option
Selecting another run-time library temporarily can be
-achieved by using the *--RTS* switch, e.g., *--RTS=sjlj*
+achieved by using the :switch:`--RTS` switch, e.g., :switch:`--RTS=sjlj`
.. _Choosing_the_Scheduling_Policy:
------------------------------
When using a POSIX threads implementation, you have a choice of several
-scheduling policies: `SCHED_FIFO`, `SCHED_RR` and `SCHED_OTHER`.
+scheduling policies: ``SCHED_FIFO``, ``SCHED_RR`` and ``SCHED_OTHER``.
-Typically, the default is `SCHED_OTHER`, while using `SCHED_FIFO`
-or `SCHED_RR` requires special (e.g., root) privileges.
+Typically, the default is ``SCHED_OTHER``, while using ``SCHED_FIFO``
+or ``SCHED_RR`` requires special (e.g., root) privileges.
.. index:: pragma Time_Slice
.. index:: -T0 option
.. index:: pragma Task_Dispatching_Policy
-By default, GNAT uses the `SCHED_OTHER` policy. To specify
-`SCHED_FIFO`,
+By default, GNAT uses the ``SCHED_OTHER`` policy. To specify
+``SCHED_FIFO``,
you can use one of the following:
-* `pragma Time_Slice (0.0)`
-* the corresponding binder option *-T0*
-* `pragma Task_Dispatching_Policy (FIFO_Within_Priorities)`
+* ``pragma Time_Slice (0.0)``
+* the corresponding binder option :switch:`-T0`
+* ``pragma Task_Dispatching_Policy (FIFO_Within_Priorities)``
-To specify `SCHED_RR`,
-you should use `pragma Time_Slice` with a
-value greater than 0.0, or else use the corresponding *-T*
+To specify ``SCHED_RR``,
+you should use ``pragma Time_Slice`` with a
+value greater than 0.0, or else use the corresponding :switch:`-T`
binder option.
This run-time library has the advantage of being mostly shared across all
POSIX-compliant thread implementations, and it also provides under
-Solaris |nbsp| 8 the `PTHREAD_PRIO_INHERIT`
-and `PTHREAD_PRIO_PROTECT`
+Solaris |nbsp| 8 the ``PTHREAD_PRIO_INHERIT``
+and ``PTHREAD_PRIO_PROTECT``
semantics that can be selected using the predefined pragma
-`Locking_Policy`
+``Locking_Policy``
with respectively
-`Inheritance_Locking` and `Ceiling_Locking` as the policy.
+``Inheritance_Locking`` and ``Ceiling_Locking`` as the policy.
As explained above, the native run-time library is based on the Solaris thread
-library (`libthread`) and is the default library.
+library (``libthread``) and is the default library.
.. index:: GNAT_PROCESSOR environment variable (on Sparc Solaris)
========================= ===================================================================
``GNAT_PROCESSOR`` Value Effect
========================= ===================================================================
- *-2* Use the default configuration (run the program on all
- available processors) - this is the same as having `GNAT_PROCESSOR`
+ ``-2`` Use the default configuration (run the program on all
+ available processors) - this is the same as having ``GNAT_PROCESSOR``
unset
- *-1* Let the run-time implementation choose one processor and run the
+ ``-1`` Let the run-time implementation choose one processor and run the
program on that processor
- *0 .. Last_Proc* Run the program on the specified processor.
- `Last_Proc` is equal to `_SC_NPROCESSORS_CONF - 1`
- (where `_SC_NPROCESSORS_CONF` is a system variable).
+ ``0 .. Last_Proc`` Run the program on the specified processor.
+ ``Last_Proc`` is equal to ``_SC_NPROCESSORS_CONF - 1``
+ (where ``_SC_NPROCESSORS_CONF`` is a system variable).
========================= ===================================================================
.. index:: AIX resolver library
On AIX, the resolver library initializes some internal structure on
-the first call to `get*by*` functions, which are used to implement
-`GNAT.Sockets.Get_Host_By_Name` and
-`GNAT.Sockets.Get_Host_By_Address`.
+the first call to ``get*by*`` functions, which are used to implement
+``GNAT.Sockets.Get_Host_By_Name`` and
+``GNAT.Sockets.Get_Host_By_Address``.
If such initialization occurs within an Ada task, and the stack size for
the task is the default size, a stack overflow may occur.
To avoid this overflow, the user should either ensure that the first call
-to `GNAT.Sockets.Get_Host_By_Name` or
-`GNAT.Sockets.Get_Host_By_Addrss`
-occurs in the environment task, or use `pragma Storage_Size` to
+to ``GNAT.Sockets.Get_Host_By_Name`` or
+``GNAT.Sockets.Get_Host_By_Addrss``
+occurs in the environment task, or use ``pragma Storage_Size`` to
specify a sufficiently large size for the stack of the task that contains
this call.
using the command-line interface.
In order to install one of the GNAT installers from the command
- line you should pass parameter `/S` (and, optionally,
- `/D=<directory>`) as command-line arguments.
+ line you should pass parameter :switch:`/S` (and, optionally,
+ :switch:`/D=<directory>`) as command-line arguments.
.. only:: PRO
For example, for an unattended installation of
GNAT 7.0.2 into the default directory
- `C:\\GNATPRO\\7.0.2` you would run:
+ ``C:\\GNATPRO\\7.0.2`` you would run:
::
gnatpro-7.0.2-i686-pc-mingw32-bin.exe /S
- To install into a custom directory, say, `C:\\TOOLS\\GNATPRO\\7.0.2`:
+ To install into a custom directory, say, ``C:\\TOOLS\\GNATPRO\\7.0.2``:
::
.. only:: GPL
For example, for an unattended installation of
- GNAT 2012 into `C:\\GNAT\\2012`:
+ GNAT 2012 into ``C:\\GNAT\\2012``:
::
---------------------
One of the strengths of the GNAT technology is that its tool set
-(*gcc*, *gnatbind*, *gnatlink*, *gnatmake*, the
-`gdb` debugger, etc.) is used in the same way regardless of the
+(``gcc``, ``gnatbind``, ``gnatlink``, ``gnatmake``, the
+``gdb`` debugger, etc.) is used in the same way regardless of the
platform.
On Windows this tool set is complemented by a number of Microsoft-specific
when this is required. With these tools:
-* You can build applications using the `CONSOLE` or `WINDOWS`
+* You can build applications using the ``CONSOLE`` or ``WINDOWS``
subsystems.
* You can use any Dynamically Linked Library (DLL) in your Ada code (both
are listed in separate sections below.
-* It is not possible to use `GetLastError` and `SetLastError`
+* It is not possible to use ``GetLastError`` and ``SetLastError``
when tasking, protected records, or exceptions are used. In these
cases, in order to implement Ada semantics, the GNAT run-time system
calls certain Win32 routines that set the last error variable to 0 upon
- success. It should be possible to use `GetLastError` and
- `SetLastError` when tasking, protected record, and exception
+ success. It should be possible to use ``GetLastError`` and
+ ``SetLastError`` when tasking, protected record, and exception
features are not used, but it is not guaranteed to work.
* It is not possible to link against Microsoft C++ libraries except for
Make sure the system on which GNAT is installed is accessible from the
current machine, i.e., the install location is shared over the network.
Shared resources are accessed on Windows by means of UNC paths, which
-have the format `\\\\server\\sharename\\path`
+have the format ``\\\\server\\sharename\\path``
In order to use such a network installation, simply add the UNC path of the
:file:`bin` directory of your GNAT installation in front of your PATH. For
.. index:: WINDOWS Subsystem
.. index:: -mwindows
-There are two main subsystems under Windows. The `CONSOLE` subsystem
+There are two main subsystems under Windows. The ``CONSOLE`` subsystem
(which is the default subsystem) will always create a console when
launching the application. This is not something desirable when the
application has a Windows GUI. To get rid of this console the
-application must be using the `WINDOWS` subsystem. To do so
-the *-mwindows* linker option must be specified.
+application must be using the ``WINDOWS`` subsystem. To do so
+the :switch:`-mwindows` linker option must be specified.
::
.. index:: Command Line Argument Expansion
-By default, an executable compiled for the **Windows** platform will do
+By default, an executable compiled for the Windows platform will do
the following postprocessing on the arguments passed on the command
line:
Ada.Command_Line.Argument (1) -> "*.txt"
-Note that if the program is launched from a shell such as **Cygwin** **Bash**
+Note that if the program is launched from a shell such as Cygwin Bash
then quote removal might be performed by the shell.
In some contexts it might be useful to disable this feature (for example if
the program performs its own argument expansion). In order to do this, a C
symbol needs to be defined and set to ``0``. You can do this by
-adding the following code fragment in one of your **Ada** units:
+adding the following code fragment in one of your Ada units:
.. code-block:: ada
Windows C/C++ development environment conditions your overall
interoperability strategy.
-If you use *gcc* or Microsoft C to compile the non-Ada part of
+If you use ``gcc`` or Microsoft C to compile the non-Ada part of
your application, there are no Windows-specific restrictions that
affect the overall interoperability with your Ada code. If you do want
to use the Microsoft tools for your C++ code, you have two choices:
calling convention. All convention specifiers are ignored on this
platform.
-When a subprogram `F` (caller) calls a subprogram `G`
-(callee), there are several ways to push `G`'s parameters on the
+When a subprogram ``F`` (caller) calls a subprogram ``G``
+(callee), there are several ways to push ``G``\ 's parameters on the
stack and there are several possible scenarios to clean up the stack
-upon `G`'s return. A calling convention is an agreed upon software
-protocol whereby the responsibilities between the caller (`F`) and
-the callee (`G`) are clearly defined. Several calling conventions
+upon ``G``\ 's return. A calling convention is an agreed upon software
+protocol whereby the responsibilities between the caller (``F``) and
+the callee (``G``) are clearly defined. Several calling conventions
are available for Windows:
-* `C` (Microsoft defined)
+* ``C`` (Microsoft defined)
-* `Stdcall` (Microsoft defined)
+* ``Stdcall`` (Microsoft defined)
-* `Win32` (GNAT specific)
+* ``Win32`` (GNAT specific)
-* `DLL` (GNAT specific)
+* ``DLL`` (GNAT specific)
.. _C_Calling_Convention:
-`C` Calling Convention
-""""""""""""""""""""""
+``C`` Calling Convention
+""""""""""""""""""""""""
This is the default calling convention used when interfacing to C/C++
-routines compiled with either *gcc* or Microsoft Visual C++.
+routines compiled with either ``gcc`` or Microsoft Visual C++.
-In the `C` calling convention subprogram parameters are pushed on the
+In the ``C`` calling convention subprogram parameters are pushed on the
stack by the caller from right to left. The caller itself is in charge of
cleaning up the stack after the call. In addition, the name of a routine
-with `C` calling convention is mangled by adding a leading underscore.
+with ``C`` calling convention is mangled by adding a leading underscore.
The name to use on the Ada side when importing (or exporting) a routine
-with `C` calling convention is the name of the routine. For
+with ``C`` calling convention is the name of the routine. For
instance the C function:
::
function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
pragma Import (C, Get_Val, External_Name => "get_val");
-Note that in this particular case the `External_Name` parameter could
+Note that in this particular case the ``External_Name`` parameter could
have been omitted since, when missing, this parameter is taken to be the
-name of the Ada entity in lower case. When the `Link_Name` parameter
+name of the Ada entity in lower case. When the ``Link_Name`` parameter
is missing, as in the above example, this parameter is set to be the
-`External_Name` with a leading underscore.
+``External_Name`` with a leading underscore.
-When importing a variable defined in C, you should always use the `C`
+When importing a variable defined in C, you should always use the ``C``
calling convention unless the object containing the variable is part of a
-DLL (in which case you should use the `Stdcall` calling
+DLL (in which case you should use the ``Stdcall`` calling
convention, :ref:`Stdcall_Calling_Convention`).
.. _Stdcall_Calling_Convention:
-`Stdcall` Calling Convention
-""""""""""""""""""""""""""""
+``Stdcall`` Calling Convention
+""""""""""""""""""""""""""""""
This convention, which was the calling convention used for Pascal
programs, is used by Microsoft for all the routines in the Win32 API for
efficiency reasons. It must be used to import any routine for which this
convention was specified.
-In the `Stdcall` calling convention subprogram parameters are pushed
+In the ``Stdcall`` calling convention subprogram parameters are pushed
on the stack by the caller from right to left. The callee (and not the
caller) is in charge of cleaning the stack on routine exit. In addition,
-the name of a routine with `Stdcall` calling convention is mangled by
-adding a leading underscore (as for the `C` calling convention) and a
-trailing :samp:`@{nn}`, where `nn` is the overall size (in
+the name of a routine with ``Stdcall`` calling convention is mangled by
+adding a leading underscore (as for the ``C`` calling convention) and a
+trailing :samp:`@{nn}`, where ``nn`` is the overall size (in
bytes) of the parameters passed to the routine.
The name to use on the Ada side when importing a C routine with a
-`Stdcall` calling convention is the name of the C routine. The leading
+``Stdcall`` calling convention is the name of the C routine. The leading
underscore and trailing :samp:`@{nn}` are added automatically by
the compiler. For instance the Win32 function:
pragma Import (Stdcall, Get_Val);
-- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@4"
-As for the `C` calling convention, when the `External_Name`
+As for the ``C`` calling convention, when the ``External_Name``
parameter is missing, it is taken to be the name of the Ada entity in lower
case. If instead of writing the above import pragma you write:
function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val");
-then the imported routine is `_retrieve_val@4`. However, if instead
-of specifying the `External_Name` parameter you specify the
-`Link_Name` as in the following example:
+then the imported routine is ``_retrieve_val@4``. However, if instead
+of specifying the ``External_Name`` parameter you specify the
+``Link_Name`` as in the following example:
.. code-block:: ada
function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");
-then the imported routine is `retrieve_val`, that is, there is no
+then the imported routine is ``retrieve_val``, that is, there is no
decoration at all. No leading underscore and no Stdcall suffix
:samp:`@{nn}`.
pragma Import (Stdcall, My_Var);
Note that to ease building cross-platform bindings this convention
-will be handled as a `C` calling convention on non-Windows platforms.
+will be handled as a ``C`` calling convention on non-Windows platforms.
.. _Win32_Calling_Convention:
-`Win32` Calling Convention
-""""""""""""""""""""""""""
+``Win32`` Calling Convention
+""""""""""""""""""""""""""""
This convention, which is GNAT-specific is fully equivalent to the
-`Stdcall` calling convention described above.
+``Stdcall`` calling convention described above.
.. _DLL_Calling_Convention:
-`DLL` Calling Convention
-""""""""""""""""""""""""
+``DLL`` Calling Convention
+""""""""""""""""""""""""""
This convention, which is GNAT-specific is fully equivalent to the
-`Stdcall` calling convention described above.
+``Stdcall`` calling convention described above.
.. _Introduction_to_Dynamic_Link_Libraries_DLLs:
which is part of your application are initialized with the addresses
of the routines and variables in :file:`API.dll`.
-* If present in :file:`API.dll`, routines `DllMain` or
- `DllMainCRTStartup` are invoked. These routines typically contain
+* If present in :file:`API.dll`, routines ``DllMain`` or
+ ``DllMainCRTStartup`` are invoked. These routines typically contain
the initialization code needed for the well-being of the routines and
variables exported by the DLL.
application, a conflict will occur and the application will run
incorrectly. Hence, when possible, it is always preferable to use and
build relocatable DLLs. Both relocatable and non-relocatable DLLs are
-supported by GNAT. Note that the *-s* linker option (see GNU Linker
+supported by GNAT. Note that the :switch:`-s` linker option (see GNU Linker
User's Guide) removes the debugging symbols from the DLL but the DLL can
still be relocated.
* The actual DLL, :file:`API.dll`.
Once you have all the above, to compile an Ada application that uses the
-services of :file:`API.dll` and whose main subprogram is `My_Ada_App`,
+services of :file:`API.dll` and whose main subprogram is ``My_Ada_App``,
you simply issue the command
::
$ gnatmake my_ada_app -largs -lAPI
-The argument *-largs -lAPI* at the end of the *gnatmake* command
+The argument :switch:`-largs -lAPI` at the end of the ``gnatmake`` command
tells the GNAT linker to look for an import library. The linker will
look for a library name in this specific order:
pragma Linker_Options ("-lAPI");
-you do not have to add *-largs -lAPI* at the end of the
-*gnatmake* command.
+you do not have to add :switch:`-largs -lAPI` at the end of the
+``gnatmake`` command.
If any one of the items above is missing you will have to create it
yourself. The following sections explain how to do so using as an
As previously mentioned, and unlike Unix systems, the list of symbols
that are exported from a DLL must be provided explicitly in Windows.
The main goal of a definition file is precisely that: list the symbols
-exported by a DLL. A definition file (usually a file with a `.def`
+exported by a DLL. A definition file (usually a file with a ``.def``
suffix) has the following structure:
::
- [LIBRARY `name`]
- [DESCRIPTION `string`]
+ [LIBRARY ``name``]
+ [DESCRIPTION ``string``]
EXPORTS
- `symbol1`
- `symbol2`
+ ``symbol1``
+ ``symbol2``
...
-*LIBRARY `name`*
+*LIBRARY name*
This section, which is optional, gives the name of the DLL.
-*DESCRIPTION `string`*
+*DESCRIPTION string*
This section, which is optional, gives a description string that will be
embedded in the import library.
*EXPORTS*
This section gives the list of exported symbols (procedures, functions or
- variables). For instance in the case of :file:`API.dll` the `EXPORTS`
+ variables). For instance in the case of :file:`API.dll` the ``EXPORTS``
section of :file:`API.def` looks like:
::
You can automatically create the definition file :file:`API.def`
(see :ref:`The Definition File <The_Definition_File>`) from a DLL.
-For that use the `dlltool` program as follows:
+For that use the ``dlltool`` program as follows:
::
$ dlltool API.dll -z API.def --export-all-symbols
- Note that if some routines in the DLL have the `Stdcall` convention
+ Note that if some routines in the DLL have the ``Stdcall`` convention
(:ref:`Windows_Calling_Conventions`) with stripped :samp:`@{nn}`
suffix then you'll have to edit :file:`api.def` to add it, and specify
- *-k* to *gnatdll* when creating the import library.
+ :switch:`-k` to ``gnatdll`` when creating the import library.
Here are some hints to find the right :samp:`@{nn}` suffix.
- If you have the Microsoft import library (.lib), it is possible to get
- the right symbols by using Microsoft `dumpbin` tool (see the
+ the right symbols by using Microsoft ``dumpbin`` tool (see the
corresponding Microsoft documentation for further details).
::
.. rubric:: GNAT-Style Import Library
To create a static import library from :file:`API.dll` with the GNAT tools
-you should create the .def file, then use `gnatdll` tool
+you should create the .def file, then use ``gnatdll`` tool
(see :ref:`Using_gnatdll`) as follows:
::
$ gnatdll -e API.def -d API.dll
- `gnatdll` takes as input a definition file :file:`API.def` and the
+ ``gnatdll`` takes as input a definition file :file:`API.def` and the
name of the DLL containing the services listed in the definition file
:file:`API.dll`. The name of the static import library generated is
computed from the name of the definition file as follows: if the
- definition file name is `xyz``.def`, the import library name will
- be `lib``xyz``.a`. Note that in the previous example option
- *-e* could have been removed because the name of the definition
- file (before the '`.def`' suffix) is the same as the name of the
- DLL (:ref:`Using_gnatdll` for more information about `gnatdll`).
+ definition file name is :file:`xyz.def`, the import library name will
+ be :file:`libxyz.a`. Note that in the previous example option
+ :switch:`-e` could have been removed because the name of the definition
+ file (before the ``.def`` suffix) is the same as the name of the
+ DLL (:ref:`Using_gnatdll` for more information about ``gnatdll``).
.. _MSVS-Style_Import_Library:
To create a Microsoft-style import library for :file:`API.dll` you
should create the .def file, then build the actual import library using
-Microsoft's `lib` utility:
+Microsoft's ``lib`` utility:
::
LIBRARY "API"
See the Microsoft documentation for further details about the usage of
- `lib`.
+ ``lib``.
.. _Building_DLLs_with_GNAT_Project_files:
chapter of the *GPRbuild User's Guide*.
Due to a system limitation, it is not possible under Windows to create threads
-when inside the `DllMain` routine which is used for auto-initialization
+when inside the ``DllMain`` routine which is used for auto-initialization
of shared libraries, so it is not possible to have library level tasks in SALs.
* Building object files.
The first step is to build all objects files that are to be included
- into the DLL. This is done by using the standard *gnatmake* tool.
+ into the DLL. This is done by using the standard ``gnatmake`` tool.
* Building the DLL.
- To build the DLL you must use *gcc*'s *-shared* and
- *-shared-libgcc* options. It is quite simple to use this method:
+ To build the DLL you must use the ``gcc`` :switch:`-shared` and
+ :switch:`-shared-libgcc` options. It is quite simple to use this method:
::
It is important to note that in this case all symbols found in the
object files are automatically exported. It is possible to restrict
- the set of symbols to export by passing to *gcc* a definition
+ the set of symbols to export by passing to ``gcc`` a definition
file (see :ref:`The Definition File <The_Definition_File>`).
For example:
At this point it is possible to use the DLL by directly linking
against it. Note that you must use the GNAT shared runtime when using
-GNAT shared libraries. This is achieved by using *-shared* binder's
+GNAT shared libraries. This is achieved by using the :switch:`-shared` binder
option.
::
DLL support (:ref:`Building_DLLs_with_GNAT`) or to build DLLs.
This section explains how to build DLLs containing Ada code using
-`gnatdll`. These DLLs will be referred to as Ada DLLs in the
+``gnatdll``. These DLLs will be referred to as Ada DLLs in the
remainder of this section.
The steps required to build an Ada DLL that is to be used by Ada as well as
non-Ada applications are as follows:
-* You need to mark each Ada *entity* exported by the DLL with a `C` or
- `Stdcall` calling convention to avoid any Ada name mangling for the
+* You need to mark each Ada entity exported by the DLL with a ``C`` or
+ ``Stdcall`` calling convention to avoid any Ada name mangling for the
entities exported by the DLL
(see :ref:`Exporting Ada Entities <Exporting_Ada_Entities>`). You can
skip this step if you plan to use the Ada DLL only from Ada applications.
* Your Ada code must export an initialization routine which calls the routine
- `adainit` generated by *gnatbind* to perform the elaboration of
+ ``adainit`` generated by ``gnatbind`` to perform the elaboration of
the Ada code in the DLL (:ref:`Ada_DLLs_and_Elaboration`). The initialization
routine exported by the Ada DLL must be invoked by the clients of the DLL
to initialize the DLL.
* When useful, the DLL should also export a finalization routine which calls
- routine `adafinal` generated by *gnatbind* to perform the
+ routine ``adafinal`` generated by ``gnatbind`` to perform the
finalization of the Ada code in the DLL (:ref:`Ada_DLLs_and_Finalization`).
The finalization routine exported by the Ada DLL must be invoked by the
clients of the DLL when the DLL services are no further needed.
* You must provide a definition file listing the exported entities
(:ref:`The Definition File <The_Definition_File>`).
-* Finally you must use `gnatdll` to produce the DLL and the import
+* Finally you must use ``gnatdll`` to produce the DLL and the import
library (:ref:`Using_gnatdll`).
-Note that a relocatable DLL stripped using the `strip`
+Note that a relocatable DLL stripped using the ``strip``
binutils tool will not be relocatable anymore. To build a DLL without
-debug information pass `-largs -s` to `gnatdll`. This
+debug information pass :switch:`-largs -s` to ``gnatdll``. This
restriction does not apply to a DLL built using a Library Project.
See the *Library Projects* section in the *GNAT Project Manager*
chapter of the *GPRbuild User's Guide*.
It is therefore not possible to exchange GNAT run-time objects between the
Ada DLL and the main Ada program. Example of GNAT run-time objects are file
-handles (e.g., `Text_IO.File_Type`), tasks types, protected objects
+handles (e.g., ``Text_IO.File_Type``), tasks types, protected objects
types, etc.
It is completely safe to exchange plain elementary, array or record types,
Building a DLL is a way to encapsulate a set of services usable from any
application. As a result, the Ada entities exported by a DLL should be
-exported with the `C` or `Stdcall` calling conventions to avoid
+exported with the ``C`` or ``Stdcall`` calling conventions to avoid
any Ada name mangling. As an example here is an Ada package
-`API`, spec and body, exporting two procedures, a function, and a
+``API``, spec and body, exporting two procedures, a function, and a
variable:
end API;
If the Ada DLL you are building will only be used by Ada applications
-you do not have to export Ada entities with a `C` or `Stdcall`
+you do not have to export Ada entities with a ``C`` or ``Stdcall``
convention. As an example, the previous package could be written as
follows:
-- The remainder of this package body is unchanged.
end API;
-Note that if you do not export the Ada entities with a `C` or
-`Stdcall` convention you will have to provide the mangled Ada names
+Note that if you do not export the Ada entities with a ``C`` or
+``Stdcall`` convention you will have to provide the mangled Ada names
in the definition file of the Ada DLL
(:ref:`Creating_the_Definition_File`).
(:ref:`Elaboration_Order_Handling_in_GNAT`).
To achieve this you must export an initialization routine
-(`Initialize_API` in the previous example), which must be invoked
+(``Initialize_API`` in the previous example), which must be invoked
before using any of the DLL services. This elaboration routine must call
-the Ada elaboration routine `adainit` generated by the GNAT binder
+the Ada elaboration routine ``adainit`` generated by the GNAT binder
(:ref:`Binding_with_Non-Ada_Main_Programs`). See the body of
-`Initialize_Api` for an example. Note that the GNAT binder is
-automatically invoked during the DLL build process by the `gnatdll`
+``Initialize_Api`` for an example. Note that the GNAT binder is
+automatically invoked during the DLL build process by the ``gnatdll``
tool (:ref:`Using_gnatdll`).
When a DLL is loaded, Windows systematically invokes a routine called
-`DllMain`. It would therefore be possible to call `adainit`
-directly from `DllMain` without having to provide an explicit
+``DllMain``. It would therefore be possible to call ``adainit``
+directly from ``DllMain`` without having to provide an explicit
initialization routine. Unfortunately, it is not possible to call
-`adainit` from the `DllMain` if your program has library level
-tasks because access to the `DllMain` entry point is serialized by
+``adainit`` from the ``DllMain`` if your program has library level
+tasks because access to the ``DllMain`` entry point is serialized by
the system (that is, only a single thread can execute 'through' it at a
time), which means that the GNAT run time will deadlock waiting for the
newly created task to complete its initialization.
invoke the DLL finalization routine, if available. The DLL finalization
routine is in charge of releasing all resources acquired by the DLL. In the
case of the Ada code contained in the DLL, this is achieved by calling
-routine `adafinal` generated by the GNAT binder
+routine ``adafinal`` generated by the GNAT binder
(:ref:`Binding_with_Non-Ada_Main_Programs`).
-See the body of `Finalize_Api` for an
+See the body of ``Finalize_Api`` for an
example. As already pointed out the GNAT binder is automatically invoked
-during the DLL build process by the `gnatdll` tool
+during the DLL build process by the ``gnatdll`` tool
(:ref:`Using_gnatdll`).
To use the services exported by the Ada DLL from another programming
language (e.g., C), you have to translate the specs of the exported Ada
-entities in that language. For instance in the case of `API.dll`,
+entities in that language. For instance in the case of ``API.dll``,
the corresponding C header file could look like:
.. code-block:: c
It is important to understand that when building an Ada DLL to be used by
other Ada applications, you need two different specs for the packages
contained in the DLL: one for building the DLL and the other for using
-the DLL. This is because the `DLL` calling convention is needed to
+the DLL. This is because the ``DLL`` calling convention is needed to
use a variable defined in a DLL, but when building the DLL, the variable
-must have either the `Ada` or `C` calling convention. As an
-example consider a DLL comprising the following package `API`:
+must have either the ``Ada`` or ``C`` calling convention. As an
+example consider a DLL comprising the following package ``API``:
.. code-block:: ada
-- Remainder of the package omitted.
end API;
-After producing a DLL containing package `API`, the spec that
-must be used to import `API.Count` from Ada code outside of the
+After producing a DLL containing package ``API``, the spec that
+must be used to import ``API.Count`` from Ada code outside of the
DLL is:
.. code-block:: ada
The definition file is the last file needed to build the DLL. It lists
the exported symbols. As an example, the definition file for a DLL
-containing only package `API` (where all the entities are exported
-with a `C` calling convention) is:
+containing only package ``API`` (where all the entities are exported
+with a ``C`` calling convention) is:
::
finalize_api
initialize_api
-If the `C` calling convention is missing from package `API`,
+If the ``C`` calling convention is missing from package ``API``,
then the definition file contains the mangled Ada names of the above
entities, which in this case are:
.. _Using_gnatdll:
-Using `gnatdll`
-"""""""""""""""
+Using ``gnatdll``
+"""""""""""""""""
.. index:: gnatdll
-`gnatdll` is a tool to automate the DLL build process once all the Ada
+``gnatdll`` is a tool to automate the DLL build process once all the Ada
and non-Ada sources that make up your DLL have been compiled.
-`gnatdll` is actually in charge of two distinct tasks: build the
+``gnatdll`` is actually in charge of two distinct tasks: build the
static import library for the DLL and the actual DLL. The form of the
-`gnatdll` command is
+``gnatdll`` command is
::
- $ gnatdll [`switches`] `list-of-files` [-largs `opts`]
+ $ gnatdll [ switches ] list-of-files [ -largs opts ]
-where `list-of-files` is a list of ALI and object files. The object
+where ``list-of-files`` is a list of ALI and object files. The object
file list must be the exact list of objects corresponding to the non-Ada
sources whose services are to be included in the DLL. The ALI file list
must be the exact list of ALI files for the corresponding Ada sources
-whose services are to be included in the DLL. If `list-of-files` is
+whose services are to be included in the DLL. If ``list-of-files`` is
missing, only the static import library is generated.
-You may specify any of the following switches to `gnatdll`:
+You may specify any of the following switches to ``gnatdll``:
.. index:: -a (gnatdll)
-:samp:`-a[{address}]`
- Build a non-relocatable DLL at `address`. If `address` is not
- specified the default address `0x11000000` will be used. By default,
- when this switch is missing, `gnatdll` builds relocatable DLL. We
+:switch:`-a[{address}]`
+ Build a non-relocatable DLL at ``address``. If ``address`` is not
+ specified the default address ``0x11000000`` will be used. By default,
+ when this switch is missing, ``gnatdll`` builds relocatable DLL. We
advise the reader to build relocatable DLL.
.. index:: -b (gnatdll)
-:samp:`-b {address}`
+:switch:`-b {address}`
Set the relocatable DLL base address. By default the address is
- `0x11000000`.
+ ``0x11000000``.
.. index:: -bargs (gnatdll)
-:samp:`-bargs {opts}`
- Binder options. Pass `opts` to the binder.
+:switch:`-bargs {opts}`
+ Binder options. Pass ``opts`` to the binder.
.. index:: -d (gnatdll)
-:samp:`-d {dllfile}`
- `dllfile` is the name of the DLL. This switch must be present for
- `gnatdll` to do anything. The name of the generated import library is
- obtained algorithmically from `dllfile` as shown in the following
- example: if `dllfile` is `xyz.dll`, the import library name is
- `libxyz.dll.a`. The name of the definition file to use (if not specified
- by option *-e*) is obtained algorithmically from `dllfile`
+:switch:`-d {dllfile}`
+ ``dllfile`` is the name of the DLL. This switch must be present for
+ ``gnatdll`` to do anything. The name of the generated import library is
+ obtained algorithmically from ``dllfile`` as shown in the following
+ example: if ``dllfile`` is :file:`xyz.dll`, the import library name is
+ :file:`libxyz.dll.a`. The name of the definition file to use (if not specified
+ by option :switch:`-e`) is obtained algorithmically from ``dllfile``
as shown in the following example:
- if `dllfile` is `xyz.dll`, the definition
- file used is `xyz.def`.
+ if ``dllfile`` is :file:`xyz.dll`, the definition
+ file used is :file:`xyz.def`.
.. index:: -e (gnatdll)
-:samp:`-e {deffile}`
- `deffile` is the name of the definition file.
+:switch:`-e {deffile}`
+ ``deffile`` is the name of the definition file.
.. index:: -g (gnatdll)
-:samp:`-g`
+:switch:`-g`
Generate debugging information. This information is stored in the object
file and copied from there to the final DLL file by the linker,
where it can be read by the debugger. You must use the
- *-g* switch if you plan on using the debugger or the symbolic
+ :switch:`-g` switch if you plan on using the debugger or the symbolic
stack traceback.
.. index:: -h (gnatdll)
-:samp:`-h`
- Help mode. Displays `gnatdll` switch usage information.
+:switch:`-h`
+ Help mode. Displays ``gnatdll`` switch usage information.
.. index:: -I (gnatdll)
-:samp:`-I{dir}`
- Direct `gnatdll` to search the `dir` directory for source and
+:switch:`-I{dir}`
+ Direct ``gnatdll`` to search the ``dir`` directory for source and
object files needed to build the DLL.
(:ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
.. index:: -k (gnatdll)
-:samp:`-k`
+:switch:`-k`
Removes the :samp:`@{nn}` suffix from the import library's exported
names, but keeps them for the link names. You must specify this
- option if you want to use a `Stdcall` function in a DLL for which
+ option if you want to use a ``Stdcall`` function in a DLL for which
the :samp:`@{nn}` suffix has been removed. This is the case for most
of the Windows NT DLL for example. This option has no effect when
- *-n* option is specified.
+ :switch:`-n` option is specified.
.. index:: -l (gnatdll)
-:samp:`-l {file}`
+:switch:`-l {file}`
The list of ALI and object files used to build the DLL are listed in
- `file`, instead of being given in the command line. Each line in
- `file` contains the name of an ALI or object file.
+ ``file``, instead of being given in the command line. Each line in
+ ``file`` contains the name of an ALI or object file.
.. index:: -n (gnatdll)
-:samp:`-n`
+:switch:`-n`
No Import. Do not create the import library.
.. index:: -q (gnatdll)
-:samp:`-q`
+:switch:`-q`
Quiet mode. Do not display unnecessary messages.
.. index:: -v (gnatdll)
-:samp:`-v`
+:switch:`-v`
Verbose mode. Display extra information.
.. index:: -largs (gnatdll)
-:samp:`-largs {opts}`
- Linker options. Pass `opts` to the linker.
+:switch:`-largs {opts}`
+ Linker options. Pass ``opts`` to the linker.
-.. rubric:: `gnatdll` Example
+.. rubric:: ``gnatdll`` Example
As an example the command to build a relocatable DLL from :file:`api.adb`
once :file:`api.adb` has been compiled and :file:`api.def` created is
$ gnatdll -d api.dll
-.. rubric:: `gnatdll` behind the Scenes
+.. rubric:: ``gnatdll`` behind the Scenes
-This section details the steps involved in creating a DLL. `gnatdll`
+This section details the steps involved in creating a DLL. ``gnatdll``
does these steps for you. Unless you are interested in understanding what
goes on behind the scenes, you should skip this section.
-We use the previous example of a DLL containing the Ada package `API`,
+We use the previous example of a DLL containing the Ada package ``API``,
to illustrate the steps necessary to build a DLL. The starting point is a
set of objects that will make up the DLL and the corresponding ALI
files. In the case of this example this means that :file:`api.o` and
-:file:`api.ali` are available. To build a relocatable DLL, `gnatdll` does
+:file:`api.ali` are available. To build a relocatable DLL, ``gnatdll`` does
the following:
-* `gnatdll` builds the base file (:file:`api.base`). A base file gives
+* ``gnatdll`` builds the base file (:file:`api.base`). A base file gives
the information necessary to generate relocation information for the
DLL.
$ gnatbind -n api
$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
- In addition to the base file, the *gnatlink* command generates an
- output file :file:`api.jnk` which can be discarded. The *-mdll* switch
- asks *gnatlink* to generate the routines `DllMain` and
- `DllMainCRTStartup` that are called by the Windows loader when the DLL
+ In addition to the base file, the ``gnatlink`` command generates an
+ output file :file:`api.jnk` which can be discarded. The :switch:`-mdll` switch
+ asks ``gnatlink`` to generate the routines ``DllMain`` and
+ ``DllMainCRTStartup`` that are called by the Windows loader when the DLL
is loaded into memory.
-* `gnatdll` uses `dlltool` (see :ref:`Using dlltool <Using_dlltool>`) to build the
+* ``gnatdll`` uses ``dlltool`` (see :ref:`Using dlltool <Using_dlltool>`) to build the
export table (:file:`api.exp`). The export table contains the relocation
information in a form which can be used during the final link to ensure
that the Windows loader is able to place the DLL anywhere in memory.
$ dlltool --dllname api.dll --def api.def --base-file api.base \\
--output-exp api.exp
-* `gnatdll` builds the base file using the new export table. Note that
- *gnatbind* must be called once again since the binder generated file
- has been deleted during the previous call to *gnatlink*.
+* ``gnatdll`` builds the base file using the new export table. Note that
+ ``gnatbind`` must be called once again since the binder generated file
+ has been deleted during the previous call to ``gnatlink``.
::
-Wl,--base-file,api.base
-* `gnatdll` builds the new export table using the new base file and
+* ``gnatdll`` builds the new export table using the new base file and
generates the DLL import library :file:`libAPI.dll.a`.
$ dlltool --dllname api.dll --def api.def --base-file api.base \\
--output-exp api.exp --output-lib libAPI.a
-* Finally `gnatdll` builds the relocatable DLL using the final export
+* Finally ``gnatdll`` builds the relocatable DLL using the final export
table.
::
.. _Using_dlltool:
-.. rubric:: Using `dlltool`
+.. rubric:: Using ``dlltool``
-`dlltool` is the low-level tool used by `gnatdll` to build
+``dlltool`` is the low-level tool used by ``gnatdll`` to build
DLLs and static import libraries. This section summarizes the most
-common `dlltool` switches. The form of the `dlltool` command
+common ``dlltool`` switches. The form of the ``dlltool`` command
is
::
$ dlltool [`switches`]
-`dlltool` switches include:
+``dlltool`` switches include:
.. index:: --base-file (dlltool)
-:samp:`--base-file {basefile}`
- Read the base file `basefile` generated by the linker. This switch
+:switch:`--base-file {basefile}`
+ Read the base file ``basefile`` generated by the linker. This switch
is used to create a relocatable DLL.
.. index:: --def (dlltool)
-:samp:`--def {deffile}`
+:switch:`--def {deffile}`
Read the definition file.
.. index:: --dllname (dlltool)
-:samp:`--dllname {name}`
+:switch:`--dllname {name}`
Gives the name of the DLL. This switch is used to embed the name of the
- DLL in the static import library generated by `dlltool` with switch
- *--output-lib*.
+ DLL in the static import library generated by ``dlltool`` with switch
+ :switch:`--output-lib`.
.. index:: -k (dlltool)
-:samp:`-k`
+:switch:`-k`
Kill :samp:`@{nn}` from exported names
(:ref:`Windows_Calling_Conventions`
- for a discussion about `Stdcall`-style symbols.
+ for a discussion about ``Stdcall``-style symbols.
.. index:: --help (dlltool)
-:samp:`--help`
- Prints the `dlltool` switches with a concise description.
+:switch:`--help`
+ Prints the ``dlltool`` switches with a concise description.
.. index:: --output-exp (dlltool)
-:samp:`--output-exp {exportfile}`
- Generate an export file `exportfile`. The export file contains the
+:switch:`--output-exp {exportfile}`
+ Generate an export file ``exportfile``. The export file contains the
export table (list of symbols in the DLL) and is used to create the DLL.
.. index:: --output-lib (dlltool)
-:samp:`--output-lib {libfile}`
- Generate a static import library `libfile`.
+:switch:`--output-lib {libfile}`
+ Generate a static import library ``libfile``.
.. index:: -v (dlltool)
-:samp:`-v`
+:switch:`-v`
Verbose mode.
.. index:: --as (dlltool)
-:samp:`--as {assembler-name}`
- Use `assembler-name` as the assembler. The default is `as`.
+:switch:`--as {assembler-name}`
+ Use ``assembler-name`` as the assembler. The default is ``as``.
.. _GNAT_and_Windows_Resources:
END
END
-The value `0809` (langID) is for the U.K English language and
-`04E4` (charsetID), which is equal to `1252` decimal, for
+The value ``0809`` (langID) is for the U.K English language and
+``04E4`` (charsetID), which is equal to ``1252`` decimal, for
multilingual.
This section explains how to build, compile and use resources. Note that this
A resource file is an ASCII file. By convention resource files have an
:file:`.rc` extension.
The easiest way to build a resource file is to use Microsoft tools
-such as `imagedit.exe` to build bitmaps, icons and cursors and
-`dlgedit.exe` to build dialogs.
+such as ``imagedit.exe`` to build bitmaps, icons and cursors and
+``dlgedit.exe`` to build dialogs.
It is always possible to build an :file:`.rc` file yourself by writing a
resource script.
This section describes how to build a GNAT-compatible (COFF) object file
containing the resources. This is done using the Resource Compiler
-`windres` as follows:
+``windres`` as follows:
::
$ windres -i myres.rc -o myres.o
-By default `windres` will run *gcc* to preprocess the :file:`.rc`
+By default ``windres`` will run ``gcc`` to preprocess the :file:`.rc`
file. You can specify an alternate preprocessor (usually named
-:file:`cpp.exe`) using the `windres` *--preprocessor*
+:file:`cpp.exe`) using the ``windres`` :switch:`--preprocessor`
parameter. A list of all possible options may be obtained by entering
-the command `windres` *--help*.
+the command ``windres`` :switch:`--help`.
-It is also possible to use the Microsoft resource compiler `rc.exe`
+It is also possible to use the Microsoft resource compiler ``rc.exe``
to produce a :file:`.res` file (binary resource file). See the
corresponding Microsoft documentation for further details. In this case
-you need to use `windres` to translate the :file:`.res` file to a
+you need to use ``windres`` to translate the :file:`.res` file to a
GNAT-compatible object file as follows:
::
To include the resource file in your program just add the
GNAT-compatible object file for the resource(s) to the linker
-arguments. With *gnatmake* this is done by using the *-largs*
+arguments. With ``gnatmake`` this is done by using the :switch:`-largs`
option:
::
cookbook-style sequence of steps to follow:
1. First develop and build the GNAT shared library using a library project
- (let's assume the project is `mylib.gpr`, producing the library `libmylib.dll`):
+ (let's assume the project is :file:`mylib.gpr`, producing the library :file:`libmylib.dll`):
::
we have to deal with two different executable parts: the DLL and the
program that uses it. We have the following four possibilities:
-* The program and the DLL are built with `GCC/GNAT`.
+* The program and the DLL are built with GCC/GNAT.
* The program is built with foreign tools and the DLL is built with
- `GCC/GNAT`.
-* The program is built with `GCC/GNAT` and the DLL is built with
+ GCC/GNAT.
+* The program is built with GCC/GNAT and the DLL is built with
foreign tools.
In this section we address only cases one and two above.
There is no point in trying to debug
-a DLL with `GNU/GDB`, if there is no GDB-compatible debugging
+a DLL with GNU/GDB, if there is no GDB-compatible debugging
information in it. To do so you must use a debugger compatible with the
tools suite used to build the DLL.
Program and DLL Both Built with GCC/GNAT
""""""""""""""""""""""""""""""""""""""""
-This is the simplest case. Both the DLL and the program have `GDB`
+This is the simplest case. Both the DLL and the program have ``GDB``
compatible debugging information. It is then possible to break anywhere in
the process. Let's suppose here that the main procedure is named
-`ada_main` and that in the DLL there is an entry point named
-`ada_dll`.
+``ada_main`` and that in the DLL there is an entry point named
+``ada_dll``.
The DLL (:ref:`Introduction_to_Dynamic_Link_Libraries_DLLs`) and
program must have been built with the debugging information (see GNAT -g
switch). Here are the step-by-step instructions for debugging it:
-* Launch `GDB` on the main program.
+* Launch ``GDB`` on the main program.
::
In this case things are slightly more complex because it is not possible to
start the main program and then break at the beginning to load the DLL and the
associated DLL debugging information. It is not possible to break at the
-beginning of the program because there is no `GDB` debugging information,
+beginning of the program because there is no ``GDB`` debugging information,
and therefore there is no direct way of getting initial control. This
section addresses this issue by describing some methods that can be used
to break somewhere in the DLL to debug it.
-First suppose that the main procedure is named `main` (this is for
+First suppose that the main procedure is named ``main`` (this is for
example some C code built with Microsoft Visual C) and that there is a
-DLL named `test.dll` containing an Ada entry point named
-`ada_dll`.
+DLL named ``test.dll`` containing an Ada entry point named
+``ada_dll``.
The DLL (see :ref:`Introduction_to_Dynamic_Link_Libraries_DLLs`) must have
-been built with debugging information (see GNAT `-g` option).
+been built with debugging information (see the GNAT :switch:`-g` option).
.. rubric:: Debugging the DLL Directly
.. index:: DLL debugging, attach to process
-With `GDB` it is always possible to debug a running process by
+With ``GDB`` it is always possible to debug a running process by
attaching to it. It is possible to debug a DLL this way. The limitation
of this approach is that the DLL must run long enough to perform the
attach operation. It may be useful for instance to insert a time wasting
.. _Setting_Stack_Size_from_gnatlink:
-Setting Stack Size from *gnatlink*
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setting Stack Size from ``gnatlink``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It is possible to specify the program stack size at link time. On modern
versions of Windows, starting with XP, this is mostly useful to set the size of
In particular, Stack Overflow checks are made against this
link-time specified size.
-This setting can be done with *gnatlink* using either of the following:
+This setting can be done with ``gnatlink`` using either of the following:
-* *-Xlinker* linker option
+* :switch:`-Xlinker` linker option
::
This sets the stack reserve size to 0x10000 bytes and the stack commit
size to 0x1000 bytes.
-* *-Wl* linker option
+* :switch:`-Wl` linker option
::
$ gnatlink hello -Wl,--stack=0x1000000
This sets the stack reserve size to 0x1000000 bytes. Note that with
- *-Wl* option it is not possible to set the stack commit size
+ :switch:`-Wl` option it is not possible to set the stack commit size
because the comma is a separator for this option.
.. _Setting_Heap_Size_from_gnatlink:
-Setting Heap Size from *gnatlink*
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Setting Heap Size from ``gnatlink``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Under Windows systems, it is possible to specify the program heap size from
-*gnatlink* using either of the following:
+``gnatlink`` using either of the following:
-* *-Xlinker* linker option
+* :switch:`-Xlinker` linker option
::
This sets the heap reserve size to 0x10000 bytes and the heap commit
size to 0x1000 bytes.
-* *-Wl* linker option
+* :switch:`-Wl` linker option
::
This sets the heap reserve size to 0x1000000 bytes. Note that with
- *-Wl* option it is not possible to set the heap commit size
+ :switch:`-Wl` option it is not possible to set the heap commit size
because the comma is a separator for this option.
+.. role:: switch(samp)
+
.. |with| replace:: *with*
.. |withs| replace:: *with*\ s
.. |withed| replace:: *with*\ ed
for support of non-USA character sets). The format effector characters
are represented using their standard ASCII encodings, as follows:
- =========== ======================= =========
+ =========== ======================= ===========
Character Effect Code
- ----------- ----------------------- ---------
- :kbd:`VT` Vertical tab `16#0B#`
- :kbd:`HT` Horizontal tab `16#09#`
- :kbd:`CR` Carriage return `16#0D#`
- :kbd:`LF` Line feed `16#0A#`
- :kbd:`FF` Form feed `16#0C#`
- =========== ======================= =========
+ ----------- ----------------------- -----------
+ :kbd:`VT` Vertical tab ``16#0B#``
+ :kbd:`HT` Horizontal tab ``16#09#``
+ :kbd:`CR` Carriage return ``16#0D#``
+ :kbd:`LF` Line feed ``16#0A#``
+ :kbd:`FF` Form feed ``16#0C#``
+ =========== ======================= ===========
Source files are in standard text file format. In addition, GNAT will
recognize a wide variety of stream formats, in which the end of
physical lines is marked by any of the following sequences:
-`LF`, `CR`, `CR-LF`, or `LF-CR`. This is useful
+``LF``, ``CR``, ``CR-LF``, or ``LF-CR``. This is useful
in accommodating files that are imported from other operating systems.
.. index:: pair: End of source file; Source file, end
.. index:: SUB (control character)
The end of a source file is normally represented by the physical end of
-file. However, the control character `16#1A#` (:kbd:`SUB`) is also
+file. However, the control character ``16#1A#`` (:kbd:`SUB`) is also
recognized as signalling the end of the source file. Again, this is
provided for compatibility with other operating systems where this
code is used to represent the end of file.
Each file contains a single Ada compilation unit, including any pragmas
associated with the unit. For example, this means you must place a
-package declaration (a package `spec`) and the corresponding body in
-separate files. An Ada `compilation` (which is a sequence of
+package declaration (a package *spec*) and the corresponding body in
+separate files. An Ada *compilation* (which is a sequence of
compilation units) is represented using a sequence of files. Similarly,
you will place each subunit or child unit in a separate file.
.. index:: Latin-1
The basic character set is Latin-1. This character set is defined by ISO
-standard 8859, part 1. The lower half (character codes `16#00#`
-... `16#7F#)` is identical to standard ASCII coding, but the upper
+standard 8859, part 1. The lower half (character codes ``16#00#``
+... ``16#7F#)`` is identical to standard ASCII coding, but the upper
half is used to represent additional characters. These include extended letters
used by European languages, such as French accents, the vowels with umlauts
used in German, and the extra letter A-ring used in Swedish.
.. index:: Ada.Characters.Latin_1
For a complete list of Latin-1 codes and their encodings, see the source
-file of library unit `Ada.Characters.Latin_1` in file
+file of library unit ``Ada.Characters.Latin_1`` in file
:file:`a-chlat1.ads`.
You may use any of these extended characters freely in character or
string literals. In addition, the extended characters that represent
ESC a b c d
- where `a`, `b`, `c`, `d` are the four hexadecimal
+ where ``a``, ``b``, ``c``, ``d`` are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ESC A345 is used to represent the wide character with code
- `16#A345#`.
+ ``16#A345#``.
This scheme is compatible with use of the full Wide_Character set.
*Upper-Half Coding*
.. index:: Upper-Half Coding
- The wide character with encoding `16#abcd#` where the upper bit is on
+ The wide character with encoding ``16#abcd#`` where the upper bit is on
(in other words, 'a' is in the range 8-F) is represented as two bytes,
- `16#ab#` and `16#cd#`. The second byte cannot be a format control
+ ``16#ab#`` and ``16#cd#``. The second byte cannot be a format control
character, but is not required to be in the upper half. This method can
be also used for shift-JIS or EUC, where the internal coding matches the
external coding.
.. index:: Shift JIS Coding
A wide character is represented by a two-character sequence,
- `16#ab#` and
- `16#cd#`, with the restrictions described for upper-half encoding as
+ ``16#ab#`` and
+ ``16#cd#``, with the restrictions described for upper-half encoding as
described above. The internal character code is the corresponding JIS
character according to the standard algorithm for Shift-JIS
conversion. Only characters defined in the JIS code set table can be
.. index:: EUC Coding
A wide character is represented by a two-character sequence
- `16#ab#` and
- `16#cd#`, with both characters being in the upper half. The internal
+ ``16#ab#`` and
+ ``16#cd#``, with both characters being in the upper half. The internal
character code is the corresponding JIS character according to the EUC
encoding algorithm. Only characters defined in the JIS code set table
can be used with this encoding method.
10646-1/Am.2. Depending on the character value, the representation
is a one, two, or three byte sequence::
- 16#0000#-16#007f#: 2#0`xxxxxxx`#
- 16#0080#-16#07ff#: 2#110`xxxxx`# 2#10`xxxxxx`#
- 16#0800#-16#ffff#: 2#1110`xxxx`# 2#10`xxxxxx`# 2#10`xxxxxx`#
+ 16#0000#-16#007f#: 2#0xxxxxxx#
+ 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
+ 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
- where the `xxx` bits correspond to the left-padded bits of the
+ where the ``xxx`` bits correspond to the left-padded bits of the
16-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
[ " a b c d " ]
- where `a`, `b`, `c`, `d` are the four hexadecimal
+ where ``a``, ``b``, ``c``, ``d`` are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ['A345'] is used to represent the wide character with code
- `16#A345#`. It is also possible (though not required) to use the
+ ``16#A345#``. It is also possible (though not required) to use the
Brackets coding for upper half characters. For example, the code
- `16#A3#` can be represented as `['A3']`.
+ ``16#A3#`` can be represented as ``['A3']``.
This scheme is compatible with use of the full Wide_Character set,
and is also the method used for wide character encoding in some standard
10xxxxxx 10xxxxxx 10xxxxxx
- where the `xxx` bits correspond to the left-padded bits of the
+ where the ``xxx`` bits correspond to the left-padded bits of the
32-bit character value.
*Brackets Coding*
[ " a b c d e f " ]
[ " a b c d e f g h " ]
- where `a-h` are the six or eight hexadecimal
+ where ``a-h`` are the six or eight hexadecimal
characters (using uppercase letters) of the wide wide character code. For
example, ["1F4567"] is used to represent the wide wide character with code
- `16#001F_4567#`.
+ ``16#001F_4567#``.
This scheme is compatible with use of the full Wide_Wide_Character set,
and is also the method used for wide wide character encoding in some standard
An exception arises if the file name generated by the above rules starts
with one of the characters
-`a`, `g`, `i`, or `s`, and the second character is a
+``a``, ``g``, ``i``, or ``s``, and the second character is a
minus. In this case, the character tilde is used in place
of the minus. The reason for this special rule is to avoid clashes with
the standard names for child units of the packages System, Ada,
Interfaces, and GNAT, which use the prefixes
-`s-`, `a-`, `i-`, and `g-`,
+``s-``, ``a-``, ``i-``, and ``g-``,
respectively.
The file extension is :file:`.ads` for a spec and
(For details see :ref:`Renaming_Files_with_gnatchop`.)
Note: in the case of Windows or Mac OS operating systems, case is not
-significant. So for example on `Windows` if the canonical name is
-`main-sub.adb`, you can use the file name :file:`Main-Sub.adb` instead.
+significant. So for example on Windows if the canonical name is
+:file:`main-sub.adb`, you can use the file name :file:`Main-Sub.adb` instead.
However, case is significant for other operating systems, so for example,
if you want to use other than canonically cased file names on a Unix system,
you need to follow the procedures described in the next section.
source file name pragma. However, if the file name specified has an
extension other than :file:`.ads` or :file:`.adb` it is necessary to use
a special syntax when compiling the file. The name in this case must be
-preceded by the special sequence *-x* followed by a space and the name
-of the language, here `ada`, as in:
+preceded by the special sequence ``-x`` followed by a space and the name
+of the language, here ``ada``, as in:
.. code-block:: sh
$ gcc -c -x ada peculiar_file_name.sim
-`gnatmake` handles non-standard file names in the usual manner (the
+``gnatmake`` handles non-standard file names in the usual manner (the
non-standard file name for the main program is simply used as the
argument to gnatmake). Note that if the extension is also non-standard,
-then it must be included in the `gnatmake` command, it may not
+then it must be included in the ``gnatmake`` command, it may not
be omitted.
.. _Alternative_File_Naming_Schemes:
.. index:: File names
-The previous section described the use of the `Source_File_Name`
+The previous section described the use of the ``Source_File_Name``
pragma to allow arbitrary names to be assigned to individual source files.
However, this approach requires one pragma for each file, and especially in
large systems can result in very long :file:`gnat.adc` files, and also create
GNAT also provides a facility for specifying systematic file naming schemes
other than the standard default naming scheme previously described. An
alternative scheme for naming is specified by the use of
-`Source_File_Name` pragmas having the following format:
+``Source_File_Name`` pragmas having the following format:
.. code-block:: ada
FILE_NAME_PATTERN ::= STRING_LITERAL
CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
-The `FILE_NAME_PATTERN` string shows how the file name is constructed.
+The ``FILE_NAME_PATTERN`` string shows how the file name is constructed.
It contains a single asterisk character, and the unit name is substituted
systematically for this asterisk. The optional parameter
-`Casing` indicates
+``Casing`` indicates
whether the unit name is to be all upper-case letters, all lower-case letters,
or mixed-case. If no
-`Casing` parameter is used, then the default is all
+``Casing`` parameter is used, then the default is all
lower-case.
-The optional `Dot_Replacement` string is used to replace any periods
-that occur in subunit or child unit names. If no `Dot_Replacement`
+The optional ``Dot_Replacement`` string is used to replace any periods
+that occur in subunit or child unit names. If no ``Dot_Replacement``
argument is used then separating dots appear unchanged in the resulting
file name.
Although the above syntax indicates that the
-`Casing` argument must appear
-before the `Dot_Replacement` argument, but it
+``Casing`` argument must appear
+before the ``Dot_Replacement`` argument, but it
is also permissible to write these arguments in the opposite order.
As indicated, it is possible to specify different naming schemes for
bodies, specs, and subunits. Quite often the rule for subunits is the
same as the rule for bodies, in which case, there is no need to give
-a separate `Subunit_File_Name` rule, and in this case the
-`Body_File_name` rule is used for subunits as well.
+a separate ``Subunit_File_Name`` rule, and in this case the
+``Body_File_name`` rule is used for subunits as well.
The separate rule for subunits can also be used to implement the rather
unusual case of a compilation environment (e.g., a single directory) which
The file name translation works in the following steps:
-* If there is a specific `Source_File_Name` pragma for the given unit,
+* If there is a specific ``Source_File_Name`` pragma for the given unit,
then this is always used, and any general pattern rules are ignored.
-* If there is a pattern type `Source_File_Name` pragma that applies to
+* If there is a pattern type ``Source_File_Name`` pragma that applies to
the unit, then the resulting file name will be used if the file exists. If
more than one pattern matches, the latest one will be tried first, and the
first attempt resulting in a reference to a file that exists will be used.
-* If no pattern type `Source_File_Name` pragma that applies to the unit
+* If no pattern type ``Source_File_Name`` pragma that applies to the unit
for which the corresponding file exists, then the standard GNAT default
naming rules are used.
.. _Handling_Arbitrary_File_Naming_Conventions_with_gnatname:
-Handling Arbitrary File Naming Conventions with `gnatname`
-----------------------------------------------------------
+Handling Arbitrary File Naming Conventions with ``gnatname``
+------------------------------------------------------------
.. index:: File Naming Conventions
The GNAT compiler must be able to know the source file name of a compilation
unit. When using the standard GNAT default file naming conventions
-(`.ads` for specs, `.adb` for bodies), the GNAT compiler
+(``.ads`` for specs, ``.adb`` for bodies), the GNAT compiler
does not need additional information.
When the source file names do not follow the standard GNAT default file naming
a configuration pragmas file (:ref:`Configuration_Pragmas`)
or a project file.
When the non-standard file naming conventions are well-defined,
-a small number of pragmas `Source_File_Name` specifying a naming pattern
+a small number of pragmas ``Source_File_Name`` specifying a naming pattern
(:ref:`Alternative_File_Naming_Schemes`) may be sufficient. However,
if the file naming conventions are irregular or arbitrary, a number
-of pragma `Source_File_Name` for individual compilation units
+of pragma ``Source_File_Name`` for individual compilation units
must be defined.
To help maintain the correspondence between compilation unit names and
source file names within the compiler,
-GNAT provides a tool `gnatname` to generate the required pragmas for a
+GNAT provides a tool ``gnatname`` to generate the required pragmas for a
set of files.
.. _Running_gnatname:
-Running `gnatname`
-^^^^^^^^^^^^^^^^^^
+Running ``gnatname``
+^^^^^^^^^^^^^^^^^^^^
-The usual form of the `gnatname` command is:
+The usual form of the ``gnatname`` command is:
.. code-block:: sh
- $ gnatname [`switches`] `naming_pattern` [`naming_patterns`]
- [--and [`switches`] `naming_pattern` [`naming_patterns`]]
+ $ gnatname [ switches ] naming_pattern [ naming_patterns ]
+ [--and [ switches ] naming_pattern [ naming_patterns ]]
All of the arguments are optional. If invoked without any argument,
-`gnatname` will display its usage.
+``gnatname`` will display its usage.
-When used with at least one naming pattern, `gnatname` will attempt to
+When used with at least one naming pattern, ``gnatname`` will attempt to
find all the compilation units in files that follow at least one of the
naming patterns. To find these compilation units,
-`gnatname` will use the GNAT compiler in syntax-check-only mode on all
+``gnatname`` will use the GNAT compiler in syntax-check-only mode on all
regular files.
-One or several Naming Patterns may be given as arguments to `gnatname`.
+One or several Naming Patterns may be given as arguments to ``gnatname``.
Each Naming Pattern is enclosed between double quotes (or single
quotes on Windows).
A Naming Pattern is a regular expression similar to the wildcard patterns
used in file names by the Unix shells or the DOS prompt.
-`gnatname` may be called with several sections of directories/patterns.
-Sections are separated by switch `--and`. In each section, there must be
+``gnatname`` may be called with several sections of directories/patterns.
+Sections are separated by the switch :switch:`--and`. In each section, there must be
at least one pattern. If no directory is specified in a section, the current
-directory (or the project directory is `-P` is used) is implied.
+directory (or the project directory if :switch:`-P` is used) is implied.
The options other that the directory switches and the patterns apply globally
even if they are in different sections.
see the second kind of regular expressions described in :file:`g-regexp.ads`
(the 'Glob' regular expressions).
-When invoked with no switch `-P`, `gnatname` will create a
+When invoked without the switch :switch:`-P`, ``gnatname`` will create a
configuration pragmas file :file:`gnat.adc` in the current working directory,
-with pragmas `Source_File_Name` for each file that contains a valid Ada
+with pragmas ``Source_File_Name`` for each file that contains a valid Ada
unit.
.. _Switches_for_gnatname:
-Switches for `gnatname`
-^^^^^^^^^^^^^^^^^^^^^^^
+Switches for ``gnatname``
+^^^^^^^^^^^^^^^^^^^^^^^^^
-Switches for `gnatname` must precede any specified Naming Pattern.
+Switches for ``gnatname`` must precede any specified Naming Pattern.
-You may specify any of the following switches to `gnatname`:
+You may specify any of the following switches to ``gnatname``:
.. index:: --version (gnatname)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatname)
-:samp:`--help`
- If *--version* was not used, display usage, then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
-:samp:`--subdirs={dir}`
+:switch:`--subdirs={dir}`
Real object, library or exec directories are subdirectories <dir> of the
specified ones.
-:samp:`--no-backup`
+:switch:`--no-backup`
Do not create a backup copy of an existing project file.
-:samp:`--and`
+:switch:`--and`
Start another section of directories/patterns.
.. index:: -c (gnatname)
-:samp:`-c{filename}`
+:switch:`-c{filename}`
Create a configuration pragmas file :file:`filename` (instead of the default
:file:`gnat.adc`).
- There may be zero, one or more space between *-c* and
+ There may be zero, one or more space between :switch:`-c` and
:file:`filename`.
:file:`filename` may include directory information. :file:`filename` must be
- writable. There may be only one switch *-c*.
- When a switch *-c* is
- specified, no switch *-P* may be specified (see below).
+ writable. There may be only one switch :switch:`-c`.
+ When a switch :switch:`-c` is
+ specified, no switch :switch:`-P` may be specified (see below).
.. index:: -d (gnatname)
-:samp:`-d{dir}`
+:switch:`-d{dir}`
Look for source files in directory :file:`dir`. There may be zero, one or more
- spaces between *-d* and :file:`dir`.
- :file:`dir` may end with `/**`, that is it may be of the form
- `root_dir/**`. In this case, the directory `root_dir` and all of its
+ spaces between :switch:`-d` and :file:`dir`.
+ :file:`dir` may end with ``/**``, that is it may be of the form
+ ``root_dir/**``. In this case, the directory ``root_dir`` and all of its
subdirectories, recursively, have to be searched for sources.
- When a switch *-d*
+ When a switch :switch:`-d`
is specified, the current working directory will not be searched for source
- files, unless it is explicitly specified with a *-d*
- or *-D* switch.
- Several switches *-d* may be specified.
+ files, unless it is explicitly specified with a :switch:`-d`
+ or :switch:`-D` switch.
+ Several switches :switch:`-d` may be specified.
If :file:`dir` is a relative path, it is relative to the directory of
the configuration pragmas file specified with switch
- *-c*,
+ :switch:`-c`,
or to the directory of the project file specified with switch
- *-P* or,
- if neither switch *-c*
- nor switch *-P* are specified, it is relative to the
+ :switch:`-P` or,
+ if neither switch :switch:`-c`
+ nor switch :switch:`-P` are specified, it is relative to the
current working directory. The directory
- specified with switch *-d* must exist and be readable.
+ specified with switch :switch:`-d` must exist and be readable.
.. index:: -D (gnatname)
-:samp:`-D{filename}`
+:switch:`-D{filename}`
Look for source files in all directories listed in text file :file:`filename`.
- There may be zero, one or more spaces between *-D*
+ There may be zero, one or more spaces between :switch:`-D`
and :file:`filename`.
:file:`filename` must be an existing, readable text file.
Each nonempty line in :file:`filename` must be a directory.
- Specifying switch *-D* is equivalent to specifying as many
- switches *-d* as there are nonempty lines in
+ Specifying switch :switch:`-D` is equivalent to specifying as many
+ switches :switch:`-d` as there are nonempty lines in
:file:`file`.
-:samp:`-eL`
+:switch:`-eL`
Follow symbolic links when processing project files.
.. index:: -f (gnatname)
-:samp:`-f{pattern}`
+:switch:`-f{pattern}`
Foreign patterns. Using this switch, it is possible to add sources of languages
other than Ada to the list of sources of a project file.
It is only useful if a -P switch is used.
.. index:: -h (gnatname)
-:samp:`-h`
+:switch:`-h`
Output usage (help) information. The output is written to :file:`stdout`.
.. index:: -P (gnatname)
-:samp:`-P{proj}`
+:switch:`-P{proj}`
Create or update project file :file:`proj`. There may be zero, one or more space
- between *-P* and :file:`proj`. :file:`proj` may include directory
+ between :switch:`-P` and :file:`proj`. :file:`proj` may include directory
information. :file:`proj` must be writable.
- There may be only one switch *-P*.
- When a switch *-P* is specified,
- no switch *-c* may be specified.
- On all platforms, except on VMS, when `gnatname` is invoked for an
+ There may be only one switch :switch:`-P`.
+ When a switch :switch:`-P` is specified,
+ no switch :switch:`-c` may be specified.
+ On all platforms, except on VMS, when ``gnatname`` is invoked for an
existing project file <proj>.gpr, a backup copy of the project file is created
in the project directory with file name <proj>.gpr.saved_x. 'x' is the first
non negative number that makes this backup copy a new file.
.. index:: -v (gnatname)
-:samp:`-v`
+:switch:`-v`
Verbose mode. Output detailed explanation of behavior to :file:`stdout`.
This includes name of the file written, the name of the directories to search
and, for each file in those directories whose name matches at least one of
.. index:: -v -v (gnatname)
-:samp:`-v -v`
+:switch:`-v -v`
Very Verbose mode. In addition to the output produced in verbose mode,
for each file in the searched directories whose name matches none of
the Naming Patterns, an indication is given that there is no match.
.. index:: -x (gnatname)
-:samp:`-x{pattern}`
+:switch:`-x{pattern}`
Excluded patterns. Using this switch, it is possible to exclude some files
that would match the name patterns. For example,
.. _Examples_of_gnatname_Usage:
-Examples of `gnatname` Usage
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Examples of ``gnatname`` Usage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: sh
In this example, the directory :file:`/home/me` must already exist
and be writable. In addition, the directory
:file:`/home/me/sources` (specified by
-*-d sources*) must exist and be readable.
+:switch:`-d sources`) must exist and be readable.
-Note the optional spaces after *-c* and *-d*.
+Note the optional spaces after :switch:`-c` and :switch:`-d`.
.. code-block:: sh
$ gnatname -P/home/me/proj -x "*_nt_body.ada"
-dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
-Note that several switches *-d* may be used,
+Note that several switches :switch:`-d` may be used,
even in conjunction with one or several switches
-*-D*. Several Naming Patterns and one excluded pattern
+:switch:`-D`. Several Naming Patterns and one excluded pattern
are used in this example.
.. _File_Name_Krunching_with_gnatkr:
-File Name Krunching with `gnatkr`
----------------------------------
+File Name Krunching with ``gnatkr``
+-----------------------------------
.. index:: ! gnatkr
This section discusses the method used by the compiler to shorten
the default file names chosen for Ada units so that they do not
exceed the maximum length permitted. It also describes the
-`gnatkr` utility that can be used to determine the result of
+``gnatkr`` utility that can be used to determine the result of
applying this shortening.
.. _About_gnatkr:
-About `gnatkr`
-^^^^^^^^^^^^^^
+About ``gnatkr``
+^^^^^^^^^^^^^^^^
The default file naming rule in GNAT
is that the file name must be derived from
:samp:`s-`, :samp:`a-`, :samp:`i-`, and :samp:`g-`,
respectively.
-The :samp:`-gnatk{nn}`
+The :switch:`-gnatk{nn}`
switch of the compiler activates a 'krunching'
circuit that limits file names to nn characters (where nn is a decimal
integer).
-The `gnatkr` utility can be used to determine the krunched name for
+The ``gnatkr`` utility can be used to determine the krunched name for
a given file, when krunched to a specified maximum length.
.. _Using_gnatkr:
-Using `gnatkr`
-^^^^^^^^^^^^^^
+Using ``gnatkr``
+^^^^^^^^^^^^^^^^
-The `gnatkr` command has the form:
+The ``gnatkr`` command has the form:
.. code-block:: sh
- $ gnatkr `name` [`length`]
+ $ gnatkr name [ length ]
-`name` is the uncrunched file name, derived from the name of the unit
+``name`` is the uncrunched file name, derived from the name of the unit
in the standard manner described in the previous section (i.e., in particular
all dots are replaced by hyphens). The file name may or may not have an
extension (defined as a suffix of the form period followed by arbitrary
be preserved in the output. For example, when krunching :file:`hellofile.ads`
to eight characters, the result will be hellofil.ads.
-Note: for compatibility with previous versions of `gnatkr` dots may
+Note: for compatibility with previous versions of ``gnatkr`` dots may
appear in the name instead of hyphens, but the last dot will always be
-taken as the start of an extension. So if `gnatkr` is given an argument
+taken as the start of an extension. So if ``gnatkr`` is given an argument
such as :file:`Hello.World.adb` it will be treated exactly as if the first
period had been a hyphen, and for example krunching to eight characters
gives the result :file:`hellworl.adb`.
Note that the result is always all lower case.
Characters of the other case are folded as required.
-`length` represents the length of the krunched name. The default
+``length`` represents the length of the krunched name. The default
when no argument is given is 8 characters. A length of zero stands for
unlimited, in other words do not chop except for system files where the
implied crunching length is always eight characters.
for all letters, except that a hyphen in the second character position is
replaced by a tilde if the first character is
:samp:`a`, :samp:`i`, :samp:`g`, or :samp:`s`.
-The extension is `.ads` for a
-spec and `.adb` for a body.
+The extension is ``.ads`` for a
+spec and ``.adb`` for a body.
Krunching does not affect the extension, but the file name is shortened to
the specified length by following these rules:
Of course no file shortening algorithm can guarantee uniqueness over all
possible unit names, and if file name krunching is used then it is your
responsibility to ensure that no name clashes occur. The utility
-program `gnatkr` is supplied for conveniently determining the
+program ``gnatkr`` is supplied for conveniently determining the
krunched name of a file.
.. _Examples_of_gnatkr_Usage:
-Examples of `gnatkr` Usage
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Examples of ``gnatkr`` Usage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
::
.. _Renaming_Files_with_gnatchop:
-Renaming Files with `gnatchop`
-------------------------------
+Renaming Files with ``gnatchop``
+--------------------------------
.. index:: ! gnatchop
This section discusses how to handle files with multiple units by using
-the `gnatchop` utility. This utility is also useful in renaming
+the ``gnatchop`` utility. This utility is also useful in renaming
files to meet the standard GNAT default file naming conventions.
.. _Handling_Files_with_Multiple_Units:
compiler have only one unit and there be a strict correspondence
between the file name and the unit name.
-The `gnatchop` utility allows both of these rules to be relaxed,
+The ``gnatchop`` utility allows both of these rules to be relaxed,
allowing GNAT to process files which contain multiple compilation units
-and files with arbitrary file names. `gnatchop`
+and files with arbitrary file names. ``gnatchop``
reads the specified file and generates one or more output files,
containing one unit per file. The unit and the file name correspond,
as required by GNAT.
If you want to permanently restructure a set of 'foreign' files so that
they match the GNAT rules, and do the remaining development using the
-GNAT structure, you can simply use *gnatchop* once, generate the
+GNAT structure, you can simply use ``gnatchop`` once, generate the
new set of files and work with them from that point on.
Alternatively, if you want to keep your files in the 'foreign' format,
perhaps to maintain compatibility with some other Ada compilation
-system, you can set up a procedure where you use *gnatchop* each
+system, you can set up a procedure where you use ``gnatchop`` each
time you compile, regarding the source files that it writes as temporary
files that you throw away.
Operating gnatchop in Compilation Mode
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The basic function of `gnatchop` is to take a file with multiple units
+The basic function of ``gnatchop`` is to take a file with multiple units
and split it into separate files. The boundary between files is reasonably
clear, except for the issue of comments and pragmas. In default mode, the
rule is that any pragmas between units belong to the previous unit, except
the split point without needing to mark it explicitly and most users will
find this default to be what they want. In this default mode it is incorrect to
submit a file containing only configuration pragmas, or one that ends in
-configuration pragmas, to `gnatchop`.
+configuration pragmas, to ``gnatchop``.
However, using a special option to activate 'compilation mode',
-`gnatchop`
+``gnatchop``
can perform another function, which is to provide exactly the semantics
required by the RM for handling of configuration pragmas in a compilation.
In the absence of configuration pragmas (at the main file level), this
option has no effect, but it causes such configuration pragmas to be handled
in a quite different manner.
-First, in compilation mode, if `gnatchop` is given a file that consists of
+First, in compilation mode, if ``gnatchop`` is given a file that consists of
only configuration pragmas, then this file is appended to the
:file:`gnat.adc` file in the current directory. This behavior provides
the required behavior described in the RM for the actions to be taken
of a compilation environment. For more information on the
:file:`gnat.adc` file, see :ref:`Handling_of_Configuration_Pragmas`.
-Second, in compilation mode, if `gnatchop`
+Second, in compilation mode, if ``gnatchop``
is given a file that starts with
configuration pragmas, and contains one or more units, then these
configuration pragmas are prepended to each of the chopped files. This
pragmas other than those preceding the first compilation unit of a
compilation.
-For most purposes, `gnatchop` will be used in default mode. The
+For most purposes, ``gnatchop`` will be used in default mode. The
compilation mode described above is used only if you need exactly
accurate behavior with respect to compilations, and you have files
that contain multiple units and configuration pragmas. In this
-circumstance the use of `gnatchop` with the compilation mode
+circumstance the use of ``gnatchop`` with the compilation mode
switch provides the required behavior, and is for example the mode
in which GNAT processes the ACVC tests.
.. _Command_Line_for_gnatchop:
-Command Line for `gnatchop`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Command Line for ``gnatchop``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The `gnatchop` command has the form:
+The ``gnatchop`` command has the form:
.. code-block:: sh
contains one or more Ada units, in normal GNAT format, concatenated
together. As shown, more than one file may be presented to be chopped.
-When run in default mode, `gnatchop` generates one output file in
+When run in default mode, ``gnatchop`` generates one output file in
the current directory for each unit in each of the files.
-`directory`, if specified, gives the name of the directory to which
+``directory``, if specified, gives the name of the directory to which
the output files will be written. If it is not specified, all files are
written to the current directory.
.. _Switches_for_gnatchop:
-Switches for `gnatchop`
-^^^^^^^^^^^^^^^^^^^^^^^
+Switches for ``gnatchop``
+^^^^^^^^^^^^^^^^^^^^^^^^^
-*gnatchop* recognizes the following switches:
+``gnatchop`` recognizes the following switches:
.. index:: --version (gnatchop)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatchop)
-:samp:`--help`
- If *--version* was not used, display usage, then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: -c (gnatchop)
-:samp:`-c`
- Causes `gnatchop` to operate in compilation mode, in which
+:switch:`-c`
+ Causes ``gnatchop`` to operate in compilation mode, in which
configuration pragmas are handled according to strict RM rules. See
previous section for a full description of this mode.
-:samp:`-gnat{xxx}`
- This passes the given *-gnat`xxx*` switch to `gnat` which is
- used to parse the given file. Not all `xxx` options make sense,
- but for example, the use of *-gnati2* allows `gnatchop` to
+:switch:`-gnat{xxx}`
+ This passes the given :switch:`-gnat{xxx}` switch to ``gnat`` which is
+ used to parse the given file. Not all *xxx* options make sense,
+ but for example, the use of :switch:`-gnati2` allows ``gnatchop`` to
process a source file that uses Latin-2 coding for identifiers.
-:samp:`-h`
- Causes `gnatchop` to generate a brief help summary to the standard
+:switch:`-h`
+ Causes ``gnatchop`` to generate a brief help summary to the standard
output file showing usage information.
.. index:: -k (gnatchop)
-:samp:`-k{mm}`
- Limit generated file names to the specified number `mm`
+:switch:`-k{mm}`
+ Limit generated file names to the specified number ``mm``
of characters.
This is useful if the
resulting set of files is required to be interoperable with systems
which limit the length of file names.
- No space is allowed between the *-k* and the numeric value. The numeric
- value may be omitted in which case a default of *-k8*,
+ No space is allowed between the :switch:`-k` and the numeric value. The numeric
+ value may be omitted in which case a default of :switch:`-k8`,
suitable for use
- with DOS-like file systems, is used. If no *-k* switch
+ with DOS-like file systems, is used. If no :switch:`-k` switch
is present then
there is no limit on the length of file names.
.. index:: -p (gnatchop)
-:samp:`-p`
+:switch:`-p`
Causes the file modification time stamp of the input file to be
preserved and used for the time stamp of the output file(s). This may be
useful for preserving coherency of time stamps in an environment where
- `gnatchop` is used as part of a standard build process.
+ ``gnatchop`` is used as part of a standard build process.
.. index:: -q (gnatchop)
-:samp:`-q`
+:switch:`-q`
Causes output of informational messages indicating the set of generated
files to be suppressed. Warnings and error messages are unaffected.
.. index:: -r (gnatchop)
.. index:: Source_Reference pragmas
-:samp:`-r`
- Generate `Source_Reference` pragmas. Use this switch if the output
+:switch:`-r`
+ Generate ``Source_Reference`` pragmas. Use this switch if the output
files are regarded as temporary and development is to be done in terms
of the original unchopped file. This switch causes
- `Source_Reference` pragmas to be inserted into each of the
+ ``Source_Reference`` pragmas to be inserted into each of the
generated files to refers back to the original file name and line number.
The result is that all error messages refer back to the original
unchopped file.
In addition, the debugging information placed into the object file (when
- the *-g* switch of *gcc* or *gnatmake* is
+ the :switch:`-g` switch of ``gcc`` or ``gnatmake`` is
specified)
also refers back to this original file so that tools like profilers and
debuggers will give information in terms of the original unchopped file.
If the original file to be chopped itself contains
- a `Source_Reference`
+ a ``Source_Reference``
pragma referencing a third file, then gnatchop respects
- this pragma, and the generated `Source_Reference` pragmas
+ this pragma, and the generated ``Source_Reference`` pragmas
in the chopped file refer to the original file, with appropriate
- line numbers. This is particularly useful when `gnatchop`
- is used in conjunction with `gnatprep` to compile files that
+ line numbers. This is particularly useful when ``gnatchop``
+ is used in conjunction with ``gnatprep`` to compile files that
contain preprocessing statements and multiple units.
.. index:: -v (gnatchop)
-:samp:`-v`
- Causes `gnatchop` to operate in verbose mode. The version
+:switch:`-v`
+ Causes ``gnatchop`` to operate in verbose mode. The version
number and copyright notice are output, as well as exact copies of
the gnat1 commands spawned to obtain the chop control information.
.. index:: -w (gnatchop)
-:samp:`-w`
- Overwrite existing file names. Normally `gnatchop` regards it as a
+:switch:`-w`
+ Overwrite existing file names. Normally ``gnatchop`` regards it as a
fatal error if there is already a file with the same name as a
file it would otherwise output, in other words if the files to be
chopped contain duplicated units. This switch bypasses this
.. index:: --GCC= (gnatchop)
-:samp:`--GCC={xxxx}`
+:switch:`--GCC={xxxx}`
Specify the path of the GNAT parser to be used. When this switch is used,
no attempt is made to add the prefix to the GNAT parser executable.
.. _Examples_of_gnatchop_Usage:
-Examples of `gnatchop` Usage
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Examples of ``gnatchop`` Usage
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code-block:: sh
Chops the source file :file:`archive`
into the current directory. One
-useful application of `gnatchop` is in sending sets of sources
+useful application of ``gnatchop`` is in sending sets of sources
around, for example in email messages. The required sources are simply
-concatenated (for example, using a Unix `cat`
+concatenated (for example, using a Unix ``cat``
command), and then
-*gnatchop* is used at the other end to reconstitute the original
+``gnatchop`` is used at the other end to reconstitute the original
file names.
.. code-block:: sh
the resulting files in the directory :file:`direc`. Note that if any units
occur more than once anywhere within this set of files, an error message
is generated, and no files are written. To override this check, use the
-*-w* switch,
+:switch:`-w` switch,
in which case the last occurrence in the last file will
be the one that is output, and earlier duplicate occurrences for a given
unit will be skipped.
Configuration pragmas include those pragmas described as
such in the Ada Reference Manual, as well as
implementation-dependent pragmas that are configuration pragmas.
-See the `Implementation_Defined_Pragmas` chapter in the
+See the ``Implementation_Defined_Pragmas`` chapter in the
:title:`GNAT_Reference_Manual` for details on these
additional GNAT-specific configuration pragmas.
-Most notably, the pragma `Source_File_Name`, which allows
+Most notably, the pragma ``Source_File_Name``, which allows
specifying non-default names for source files, is a configuration
pragma. The following is a complete list of configuration pragmas
recognized by GNAT::
Assertion_Policy
Assume_No_Invalid_Values
C_Pass_By_Copy
+ Check_Float_Overflow
Check_Name
Check_Policy
Compile_Time_Error
Compile_Time_Warning
Compiler_Unit
+ Compiler_Unit_Warning
Component_Alignment
Convention_Identifier
Debug_Policy
Detect_Blocking
+ Default_Scalar_Storage_Order
Default_Storage_Pool
+ Disable_Atomic_Synchronization
Discard_Names
Elaboration_Checks
Eliminate
+ Enable_Atomic_Synchronization
Extend_System
Extensions_Allowed
External_Name_Casing
Fast_Math
Favor_Top_Level
- Float_Representation
+ Ignore_Pragma
Implicit_Packing
Initialize_Scalars
Interrupt_State
License
Locking_Policy
- Long_Float
+ No_Component_Reordering
+ No_Heap_Finalization
No_Run_Time
No_Strict_Aliasing
Normalize_Scalars
Optimize_Alignment
+ Overflow_Mode
+ Overriding_Renamings
+ Partition_Elaboration_Policy
Persistent_BSS
Polling
+ Prefix_Exception_Messages
Priority_Specific_Dispatching
Profile
Profile_Warnings
Propagate_Exceptions
Queuing_Policy
+ Rational
Ravenscar
Rename_Pragma
Restricted_Run_Time
Restrictions_Warnings
Reviewable
Short_Circuit_And_Or
+ Short_Descriptors
Source_File_Name
Source_File_Name_Project
SPARK_Mode
Suppress
Suppress_Exception_Locations
Task_Dispatching_Policy
+ Unevaluated_Use_Of_Old
Universal_Data
Unsuppress
Use_VADS_Size
Validity_Checks
+ Warning_As_Error
Warnings
Wide_Character_Encoding
unit, or they can appear in a configuration pragma file to apply to
all compilations performed in a given compilation environment.
-GNAT also provides the `gnatchop` utility to provide an automatic
+GNAT also provides the ``gnatchop`` utility to provide an automatic
way to handle configuration pragmas following the semantics for
compilations (that is, files with multiple units), described in the RM.
See :ref:`Operating_gnatchop_in_Compilation_Mode` for details.
:file:`gnat.adc` file that contains configuration pragmas directly,
as described in the following section.
-In the case of `Restrictions` pragmas appearing as configuration
+In the case of ``Restrictions`` pragmas appearing as configuration
pragmas in individual compilation units, the exact handling depends on
the type of restriction.
Restrictions that require partition-wide consistency (like
-`No_Tasking`) are
+``No_Tasking``) are
recognized wherever they appear
and can be freely inherited, e.g. from a |withed| unit to the |withing|
unit. This makes sense since the binder will in any case insist on seeing
directory is searched for a file whose name is :file:`gnat.adc`. If
this file is present, it is expected to contain one or more
configuration pragmas that will be applied to the current compilation.
-However, if the switch *-gnatA* is used, :file:`gnat.adc` is not
+However, if the switch :switch:`-gnatA` is used, :file:`gnat.adc` is not
considered. When taken into account, :file:`gnat.adc` is added to the
dependencies, so that if :file:`gnat.adc` is modified later, an invocation of
-*gnatmake* will recompile the source.
+``gnatmake`` will recompile the source.
Configuration pragmas may be entered into the :file:`gnat.adc` file
-either by running `gnatchop` on a source file that consists only of
+either by running ``gnatchop`` on a source file that consists only of
configuration pragmas, or more conveniently by direct editing of the
:file:`gnat.adc` file, which is a standard format source file.
Besides :file:`gnat.adc`, additional files containing configuration
pragmas may be applied to the current compilation using the switch
-:samp:`-gnatec={path}` where `path` must designate an existing file that
+:switch:`-gnatec={path}` where ``path`` must designate an existing file that
contains only configuration pragmas. These configuration pragmas are
in addition to those found in :file:`gnat.adc` (provided :file:`gnat.adc`
-is present and switch *-gnatA* is not used).
+is present and switch :switch:`-gnatA` is not used).
-It is allowable to specify several switches *-gnatec=*, all of which
+It is allowable to specify several switches :switch:`-gnatec=`, all of which
will be taken into account.
Files containing configuration pragmas specified with switches
-*-gnatec=* are added to the dependencies, unless they are
+:switch:`-gnatec=` are added to the dependencies, unless they are
temporary files. A file is considered temporary if its name ends in
:file:`.tmp` or :file:`.TMP`. Certain tools follow this naming
-convention because they pass information to *gcc* via
+convention because they pass information to ``gcc`` via
temporary files that are immediately deleted; it doesn't make sense to
depend on a file that no longer exists. Such tools include
-*gprbuild*, *gnatmake*, and *gnatcheck*.
+``gprbuild``, ``gnatmake``, and ``gnatcheck``.
If you are using project file, a separate mechanism is provided using
project attributes.
GNAT provides an option for compiling such files purely for the
purposes of checking correctness; such compilations are not required as
part of the process of building a program. To compile a file in this
-checking mode, use the *-gnatc* switch.
+checking mode, use the :switch:`-gnatc` switch.
.. _Source_Dependencies:
A given object file clearly depends on the source file which is compiled
to produce it. Here we are using "depends" in the sense of a typical
-`make` utility; in other words, an object file depends on a source
+``make`` utility; in other words, an object file depends on a source
file if changes to the source file require the object file to be
recompiled.
In addition to this basic dependency, a given object may depend on
additional source files as follows:
-* If a file being compiled |withs| a unit `X`, the object file
- depends on the file containing the spec of unit `X`. This includes
+* If a file being compiled |withs| a unit ``X``, the object file
+ depends on the file containing the spec of unit ``X``. This includes
files that are |withed| implicitly either because they are parents
of |withed| child units or they are run-time units required by the
language constructs used in a particular unit.
.. index:: -gnatn switch
* If a file being compiled contains a call to a subprogram for which
- pragma `Inline` applies and inlining is activated with the
- *-gnatn* switch, the object file depends on the file containing the
+ pragma ``Inline`` applies and inlining is activated with the
+ :switch:`-gnatn` switch, the object file depends on the file containing the
body of this subprogram as well as on the file containing the spec. Note
that for inlining to actually occur as a result of the use of this switch,
it is necessary to compile in optimizing mode.
.. index:: -gnatN switch
- The use of *-gnatN* activates inlining optimization
+ The use of :switch:`-gnatN` activates inlining optimization
that is performed by the front end of the compiler. This inlining does
- not require that the code generation be optimized. Like *-gnatn*,
+ not require that the code generation be optimized. Like :switch:`-gnatn`,
the use of this switch generates additional dependencies.
When using a gcc-based back end (in practice this means using any version
of GNAT other than for the JVM, .NET or GNAAMP platforms), then the use of
- *-gnatN* is deprecated, and the use of *-gnatn* is preferred.
+ :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
* The previous two rules meant that for purposes of computing dependencies and
recompilation, a body and all its subunits are treated as an indivisible whole.
- These rules are applied transitively: if unit `A` |withs|
- unit `B`, whose elaboration calls an inlined procedure in package
- `C`, the object file for unit `A` will depend on the body of
- `C`, in file :file:`c.adb`.
+ These rules are applied transitively: if unit ``A`` |withs|
+ unit ``B``, whose elaboration calls an inlined procedure in package
+ ``C``, the object file for unit ``A`` will depend on the body of
+ ``C``, in file :file:`c.adb`.
The set of dependent files described by these rules includes all the
files on which the unit is semantically dependent, as dictated by the
An object file must be recreated by recompiling the corresponding source
file if any of the source files on which it depends are modified. For
- example, if the `make` utility is used to control compilation,
+ example, if the ``make`` utility is used to control compilation,
the rule for an Ada object file must mention all the source files on
which the object file depends, according to the above definition.
The determination of the necessary
- recompilations is done automatically when one uses *gnatmake*.
+ recompilations is done automatically when one uses ``gnatmake``.
.. _The_Ada_Library_Information_Files:
* Main program information (including priority and time slice settings,
as well as the wide character encoding used during compilation).
-* List of arguments used in the *gcc* command for the compilation
+* List of arguments used in the ``gcc`` command for the compilation
* Attributes of the unit, including configuration pragmas used, an indication
of whether the compilation was successful, exception model used etc.
* A list of relevant restrictions applying to the unit (used for consistency)
checking.
-* Categorization information (e.g., use of pragma `Pure`).
+* Categorization information (e.g., use of pragma ``Pure``).
* Information on all |withed| units, including presence of
- Elaborate` or `Elaborate_All` pragmas.
+ ``Elaborate`` or ``Elaborate_All`` pragmas.
-* Information from any `Linker_Options` pragmas used in the unit
+* Information from any ``Linker_Options`` pragmas used in the unit
-* Information on the use of `Body_Version` or `Version`
+* Information on the use of ``Body_Version`` or ``Version``
attributes in the unit.
* Dependency information. This is a list of files, together with
if any of these units are modified.
* Cross-reference data. Contains information on all entities referenced
- in the unit. Used by tools like `gnatxref` and `gnatfind` to
+ in the unit. Used by tools like ``gnatxref`` and ``gnatfind`` to
provide cross-reference information.
For a full detailed description of the format of the :file:`ALI` file,
-see the source of the body of unit `Lib.Writ`, contained in file
+see the source of the body of unit ``Lib.Writ``, contained in file
:file:`lib-writ.adb` in the GNAT compiler sources.
a call to the main program. This Ada program is compiled to generate the
object file for the main program. The name of
the Ada file is :file:`b~xxx`.adb` (with the corresponding spec
-:file:`b~xxx`.ads`) where `xxx` is the name of the
+:file:`b~xxx`.ads`) where ``xxx`` is the name of the
main program unit.
Finally, the linker is used to build the resulting executable program,
chapter of the *GPRbuild User's Guide*).
A project is considered a library project, when two project-level attributes
-are defined in it: `Library_Name` and `Library_Dir`. In order to
+are defined in it: ``Library_Name`` and ``Library_Dir``. In order to
control different aspects of library configuration, additional optional
project-level attributes can be specified:
-* *Library_Kind*
+* ``Library_Kind``
This attribute controls whether the library is to be static or dynamic
-* *Library_Version*
+* ``Library_Version``
This attribute specifies the library version; this value is used
during dynamic linking of shared libraries to determine if the currently
installed versions of the binaries are compatible.
-* *Library_Options*
+* ``Library_Options``
-* *Library_GCC*
+* ``Library_GCC``
These attributes specify additional low-level options to be used during
library generation, and redefine the actual application used to generate
library.
with a conventional script. For simple libraries, it is also possible to create
a dummy main program which depends upon all the packages that comprise the
interface of the library. This dummy main program can then be given to
-*gnatmake*, which will ensure that all necessary objects are built.
+``gnatmake``, which will ensure that all necessary objects are built.
After this task is accomplished, you should follow the standard procedure
of the underlying operating system to produce the static or shared library.
Please note that the library must have a name of the form :file:`lib{xxx}.a`
or :file:`lib{xxx}.so` (or :file:`lib{xxx}.dll` on Windows) in order to
-be accessed by the directive :samp:`-l{xxx}` at link time.
+be accessed by the directive :switch:`-l{xxx}` at link time.
.. _Installing_a_library:
be :file:`adalib`).
You can also specify a new default path to the run-time library at compilation
-time with the switch *--RTS=rts-path*. You can thus choose / change
+time with the switch :switch:`--RTS=rts-path`. You can thus choose / change
the run-time library you want your program to be compiled with. This switch is
-recognized by *gcc*, *gnatmake*, *gnatbind*,
-*gnatls*, *gnatfind* and *gnatxref*.
+recognized by ``gcc``, ``gnatmake``, ``gnatbind``,
+``gnatls``, ``gnatfind`` and ``gnatxref``.
It is possible to install a library before or after the standard GNAT
library, by reordering the lines in the configuration files. In general, a
Once again, the project facility greatly simplifies the use of
libraries. In this context, using a library is just a matter of adding a
|with| clause in the user project. For instance, to make use of the
-library `My_Lib` shown in examples in earlier sections, you can
+library ``My_Lib`` shown in examples in earlier sections, you can
write:
.. code-block:: gpr
for Library_Kind use "static";
end Liba;
-This is an alternative to the use of `pragma Linker_Options`. It is
+This is an alternative to the use of ``pragma Linker_Options``. It is
especially interesting in the context of systems with several interdependent
static libraries where finding a proper linker order is not easy and best be
left to the tools having visibility over project dependence information.
variable :envvar:`ADA_OBJECTS_PATH`, or by the administrator to the file
:file:`ada_object_path`
-* a pragma `Linker_Options` has been added to one of the sources.
+* a pragma ``Linker_Options`` has been added to one of the sources.
For example:
.. code-block:: ada
applications when a new version of the library is installed. Specifically,
if the interface sources have not changed, client applications do not need to
be recompiled. If, furthermore, a SAL is provided in the shared form and its
-version, controlled by `Library_Version` attribute, is not changed,
+version, controlled by ``Library_Version`` attribute, is not changed,
then the clients do not need to be relinked.
SALs also allow the library providers to minimize the amount of library source
stand-alone libraries; see the *Stand-alone Library Projects* section
in the *GNAT Project Manager* chapter of the *GPRbuild User's Guide*.
To be a Stand-alone Library Project, in addition to the two attributes
-that make a project a Library Project (`Library_Name` and
-`Library_Dir`; see the *Library Projects* section in the
+that make a project a Library Project (``Library_Name`` and
+``Library_Dir``; see the *Library Projects* section in the
*GNAT Project Manager* chapter of the *GPRbuild User's Guide*),
-the attribute `Library_Interface` must be defined. For example:
+the attribute ``Library_Interface`` must be defined. For example:
.. code-block:: gpr
for Library_Name use "dummy";
for Library_Interface use ("int1", "int1.child");
-Attribute `Library_Interface` has a non-empty string list value,
+Attribute ``Library_Interface`` has a non-empty string list value,
each string in the list designating a unit contained in an immediate source
of the project file.
(:file:`b~dummy.ads/b` in the example above).
This binder-generated package includes initialization and
finalization procedures whose
-names depend on the library name (`dummyinit` and `dummyfinal`
+names depend on the library name (``dummyinit`` and ``dummyfinal``
in the example
above). The object corresponding to this package is included in the library.
You must ensure timely (e.g., prior to any use of interfaces in the SAL)
calling of these procedures if a static SAL is built, or if a shared SAL
is built
-with the project-level attribute `Library_Auto_Init` set to
-`"false"`.
+with the project-level attribute ``Library_Auto_Init`` set to
+``"false"``.
For a Stand-Alone Library, only the :file:`ALI` files of the Interface Units
-(those that are listed in attribute `Library_Interface`) are copied to
+(those that are listed in attribute ``Library_Interface``) are copied to
the Library Directory. As a consequence, only the Interface Units may be
imported from Ada units outside of the library. If other units are imported,
the binding phase will fail.
libraries. So an encapsulated library only depends on system
libraries, all other code, including the GNAT runtime, is embedded. To
build an encapsulated library the attribute
-`Library_Standalone` must be set to `encapsulated`:
+``Library_Standalone`` must be set to ``encapsulated``:
.. code-block:: gpr
for Library_Interface use ("int1", "int1.child");
for Library_Standalone use "encapsulated";
-The default value for this attribute is `standard` in which case
+The default value for this attribute is ``standard`` in which case
a stand-alone library is built.
-The attribute `Library_Src_Dir` may be specified for a
-Stand-Alone Library. `Library_Src_Dir` is a simple attribute that has a
+The attribute ``Library_Src_Dir`` may be specified for a
+Stand-Alone Library. ``Library_Src_Dir`` is a simple attribute that has a
single string value. Its value must be the path (absolute or relative to the
project directory) of an existing directory. This directory cannot be the
object directory or one of the source directories, but it can be the same as
Units of the library that are needed by an Ada client of the library will be
copied to the designated directory, called the Interface Copy directory.
These sources include the specs of the Interface Units, but they may also
-include bodies and subunits, when pragmas `Inline` or `Inline_Always`
+include bodies and subunits, when pragmas ``Inline`` or ``Inline_Always``
are used, or when there is a generic unit in the spec. Before the sources
are copied to the Interface Copy directory, an attempt is made to delete all
files in the Interface Copy directory.
* Compile all library sources.
-* Invoke the binder with the switch *-n* (No Ada main program),
+* Invoke the binder with the switch :switch:`-n` (No Ada main program),
with all the :file:`ALI` files of the interfaces, and
- with the switch *-L* to give specific names to the `init`
- and `final` procedures. For example:
+ with the switch :switch:`-L` to give specific names to the ``init``
+ and ``final`` procedures. For example:
.. code-block:: sh
$ gcc -c b~int2.adb
* Link the dynamic library with all the necessary object files,
- indicating to the linker the names of the `init` (and possibly
- `final`) procedures for automatic initialization (and finalization).
+ indicating to the linker the names of the ``init`` (and possibly
+ ``final``) procedures for automatic initialization (and finalization).
The built library should be placed in a directory different from
the object directory.
-* Copy the `ALI` files of the interface to the library directory,
+* Copy the ``ALI`` files of the interface to the library directory,
add in this copy an indication that it is an interface to a SAL
- (i.e., add a word *SL* on the line in the :file:`ALI` file that starts
+ (i.e., add a word ``SL`` on the line in the :file:`ALI` file that starts
with letter 'P') and make the modified copy of the :file:`ALI` file
read-only.
a non-Ada context.
The only extra step required is to ensure that library interface subprograms
-are compatible with the main program, by means of `pragma Export`
-or `pragma Convention`.
+are compatible with the main program, by means of ``pragma Export``
+or ``pragma Convention``.
Here is an example of simple library interface for use with C main program:
library interface; remember that it should contain elaboration routines in
addition to interface subprograms.
-The example below shows the content of `mylib_interface.h` (note
+The example below shows the content of :file:`mylib_interface.h` (note
that there is no rule for the naming of this file, any name can be used)
.. code-block:: c
extern void do_something_else (void);
Libraries built as explained above can be used from any program, provided
-that the elaboration procedures (named `mylibinit` in the previous
+that the elaboration procedures (named ``mylibinit`` in the previous
example) are called before the library services are used. Any number of
libraries can be used simultaneously, as long as the elaboration
procedure of each library is called.
-Below is an example of a C program that uses the `mylib` library.
+Below is an example of a C program that uses the ``mylib`` library.
.. code-block:: c
}
Note that invoking any library finalization procedure generated by
-`gnatbind` shuts down the Ada run-time environment.
+``gnatbind`` shuts down the Ada run-time environment.
Consequently, the
finalization of all Ada libraries must be performed at the end of the program.
No call to these libraries or to the Ada run-time library should be made
The pragmas listed below should be used with caution inside libraries,
as they can create incompatibilities with other Ada libraries:
-* pragma `Locking_Policy`
-* pragma `Partition_Elaboration_Policy`
-* pragma `Queuing_Policy`
-* pragma `Task_Dispatching_Policy`
-* pragma `Unreserve_All_Interrupts`
+* pragma ``Locking_Policy``
+* pragma ``Partition_Elaboration_Policy``
+* pragma ``Queuing_Policy``
+* pragma ``Task_Dispatching_Policy``
+* pragma ``Unreserve_All_Interrupts``
When using a library that contains such pragmas, the user must make sure
that all libraries use the same pragmas with the same values. Otherwise,
-`Program_Error` will
+``Program_Error`` will
be raised during the elaboration of the conflicting
libraries. The usage of these pragmas and its consequences for the user
should therefore be well documented.
Otherwise, Program_Error will be raised during the elaboration of the
conflicting libraries.
-If the `Version` or `Body_Version`
+If the ``Version`` or ``Body_Version``
attributes are used inside a library, then you need to
-perform a `gnatbind` step that specifies all :file:`ALI` files in all
+perform a ``gnatbind`` step that specifies all :file:`ALI` files in all
libraries, so that version identifiers can be properly computed.
In practice these attributes are rarely used, so this is unlikely
to be a consideration.
It may be useful to recompile the GNAT library in various contexts, the
most important one being the use of partition-wide configuration pragmas
-such as `Normalize_Scalars`. A special Makefile called
-`Makefile.adalib` is provided to that effect and can be found in
+such as ``Normalize_Scalars``. A special Makefile called
+:file:`Makefile.adalib` is provided to that effect and can be found in
the directory containing the GNAT library. The location of this
directory depends on the way the GNAT environment has been installed and can
be determined by means of the command:
...
end if;
-Not only will the code inside the `if` statement not be executed if
-the constant Boolean is `False`, but it will also be completely
+Not only will the code inside the ``if`` statement not be executed if
+the constant Boolean is ``False``, but it will also be completely
deleted from the program.
-However, the code is only deleted after the `if` statement
+However, the code is only deleted after the ``if`` statement
has been checked for syntactic and semantic correctness.
(In contrast, with preprocessors the code is deleted before the
compiler ever gets to see it, so it is not checked until the switch
...
end Config;
-The `Config` package exists in multiple forms for the various targets,
-with an appropriate script selecting the version of `Config` needed.
+The ``Config`` package exists in multiple forms for the various targets,
+with an appropriate script selecting the version of ``Config`` needed.
Then any other unit requiring conditional compilation can do a |with|
-of `Config` to make the constants visible.
+of ``Config`` to make the constants visible.
.. _Debugging_-_A_Special_Case:
Since this is a common case, there are special features to deal with
this in a convenient manner. For the case of tests, Ada 2005 has added
-a pragma `Assert` that can be used for such tests. This pragma is modeled
-on the `Assert` pragma that has always been available in GNAT, so this
+a pragma ``Assert`` that can be used for such tests. This pragma is modeled
+on the ``Assert`` pragma that has always been available in GNAT, so this
feature may be used with GNAT even if you are not using Ada 2005 features.
-The use of pragma `Assert` is described in the
+The use of pragma ``Assert`` is described in the
:title:`GNAT_Reference_Manual`, but as an
example, the last test could be written:
pragma Assert (Temperature <= 999.0);
In both cases, if assertions are active and the temperature is excessive,
-the exception `Assert_Failure` will be raised, with the given string in
+the exception ``Assert_Failure`` will be raised, with the given string in
the first case or a string indicating the location of the pragma in the second
case used as the exception message.
.. index:: pragma Assertion_Policy
-You can turn assertions on and off by using the `Assertion_Policy`
+You can turn assertions on and off by using the ``Assertion_Policy``
pragma.
.. index:: -gnata switch
This is an Ada 2005 pragma which is implemented in all modes by
-GNAT. Alternatively, you can use the *-gnata* switch
+GNAT. Alternatively, you can use the :switch:`-gnata` switch
to enable assertions from the command line, which applies to
all versions of Ada.
.. index:: pragma Debug
-For the example above with the `Put_Line`, the GNAT-specific pragma
-`Debug` can be used:
+For the example above with the ``Put_Line``, the GNAT-specific pragma
+``Debug`` can be used:
.. code-block:: ada
pragma Debug (Put_Line ("got to the first stage!"));
If debug pragmas are enabled, the argument, which must be of the form of
-a procedure call, is executed (in this case, `Put_Line` will be called).
+a procedure call, is executed (in this case, ``Put_Line`` will be called).
Only one call can be present, but of course a special debugging procedure
containing any code you like can be included in the program and then
-called in a pragma `Debug` argument as needed.
+called in a pragma ``Debug`` argument as needed.
-One advantage of pragma `Debug` over the `if Debugging then`
-construct is that pragma `Debug` can appear in declarative contexts,
+One advantage of pragma ``Debug`` over the ``if Debugging then``
+construct is that pragma ``Debug`` can appear in declarative contexts,
such as at the very beginning of a procedure, before local declarations have
been elaborated.
.. index:: pragma Debug_Policy
-Debug pragmas are enabled using either the *-gnata* switch that also
+Debug pragmas are enabled using either the :switch:`-gnata` switch that also
controls assertions, or with a separate Debug_Policy pragma.
The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used
in Ada 95 and Ada 83 programs as well), and is analogous to
-pragma `Assertion_Policy` to control assertions.
+pragma ``Assertion_Policy`` to control assertions.
-`Assertion_Policy` and `Debug_Policy` are configuration pragmas,
+``Assertion_Policy`` and ``Debug_Policy`` are configuration pragmas,
and thus they can appear in :file:`gnat.adc` if you are not using a
project file, or in the file designated to contain configuration pragmas
in a project file.
They then apply to all subsequent compilations. In practice the use of
-the *-gnata* switch is often the most convenient method of controlling
+the :switch:`-gnata` switch is often the most convenient method of controlling
the status of these pragmas.
Note that a pragma is not a statement, so in contexts where a statement
sequence is required, you can't just write a pragma on its own. You have
-to add a `null` statement.
+to add a ``null`` statement.
.. code-block:: ada
compiler so this can only be used where both declarations are legal,
even though one of them will not be used.
-Another approach is to define integer constants, e.g., `Bits_Per_Word`,
-or Boolean constants, e.g., `Little_Endian`, and then write declarations
+Another approach is to define integer constants, e.g., ``Bits_Per_Word``,
+or Boolean constants, e.g., ``Little_Endian``, and then write declarations
that are parameterized by these constants. For example
.. code-block:: ada
Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word;
end record;
-If `Bits_Per_Word` is set to 32, this generates either
+If ``Bits_Per_Word`` is set to 32, this generates either
.. code-block:: ada
notation is usable for creating static constants, clever use of this
feature can often solve quite difficult problems in conditionalizing
compilation (note incidentally that in Ada 95, the little endian
-constant was introduced as `System.Default_Bit_Order`, so you do not
+constant was introduced as ``System.Default_Bit_Order``, so you do not
need to define this one yourself).
.. _Use_of_Alternative_Implementations:
... not quite as neat Ada 95 code
end if;
-where `Ada_2005` is a Boolean constant.
+where ``Ada_2005`` is a Boolean constant.
-But this won't work when `Ada_2005` is set to `False`,
-since the `then` clause will be illegal for an Ada 95 compiler.
+But this won't work when ``Ada_2005`` is set to ``False``,
+since the ``then`` clause will be illegal for an Ada 95 compiler.
(Recall that although such unreachable code would eventually be deleted
by the compiler, it still needs to be legal. If it uses features
introduced in Ada 2005, it will be illegal in Ada 95.)
procedure Insert is separate;
-Then we have two files for the subunit `Insert`, with the two sets of
+Then we have two files for the subunit ``Insert``, with the two sets of
code.
-If the package containing this is called `File_Queries`, then we might
+If the package containing this is called ``File_Queries``, then we might
have two files
* :file:`file_queries-insert-2005.adb`
Another style for arranging alternative implementations is through Ada's
access-to-subprogram facility.
In case some functionality is to be conditionally included,
-you can declare an access-to-procedure variable `Ref` that is initialized
-to designate a 'do nothing' procedure, and then invoke `Ref.all`
+you can declare an access-to-procedure variable ``Ref`` that is initialized
+to designate a 'do nothing' procedure, and then invoke ``Ref.all``
when appropriate.
-In some library package, set `Ref` to `Proc'Access` for some
-procedure `Proc` that performs the relevant processing.
+In some library package, set ``Ref`` to ``Proc'Access`` for some
+procedure ``Proc`` that performs the relevant processing.
The initialization only occurs if the library package is included in the
program.
The same idea can also be implemented using tagged types and dispatching
The preprocessor may be used in two separate modes. It can be used quite
separately from the compiler, to generate a separate output source file
that is then fed to the compiler as a separate step. This is the
-`gnatprep` utility, whose use is fully described in
+``gnatprep`` utility, whose use is fully described in
:ref:`Preprocessing_with_gnatprep`.
The preprocessing language allows such constructs as
completely different sequence of declarations
#end if;
-The values of the symbols `DEBUG` and `PRIORITY` can be
+The values of the symbols ``DEBUG`` and ``PRIORITY`` can be
defined either on the command line or in a separate file.
The other way of running the preprocessor is even closer to the C style and
often more convenient. In this approach the preprocessing is integrated into
the compilation process. The compiler is given the preprocessor input which
-includes `#if` lines etc, and then the compiler carries out the
+includes ``#if`` lines etc, and then the compiler carries out the
preprocessing internally and processes the resulting output.
For more details on this approach, see :ref:`Integrated_Preprocessing`.
.. _Preprocessing_with_gnatprep:
-Preprocessing with `gnatprep`
------------------------------
+Preprocessing with ``gnatprep``
+-------------------------------
.. index:: ! gnatprep
.. index:: Preprocessing (gnatprep)
-This section discusses how to use GNAT's `gnatprep` utility for simple
+This section discusses how to use GNAT's ``gnatprep`` utility for simple
preprocessing.
-Although designed for use with GNAT, `gnatprep` does not depend on any
+Although designed for use with GNAT, ``gnatprep`` does not depend on any
special GNAT features.
For further discussion of conditional compilation in general, see
:ref:`Conditional_Compilation`.
.. _Using_gnatprep:
-Using `gnatprep`
-^^^^^^^^^^^^^^^^
+Using ``gnatprep``
+^^^^^^^^^^^^^^^^^^
-To call `gnatprep` use:
+To call ``gnatprep`` use:
.. code-block:: sh
- $ gnatprep [`switches`] `infile` `outfile` [`deffile`]
+ $ gnatprep [ switches ] infile outfile [ deffile ]
where
* *outfile*
is the full name of the output file, which is an Ada source
in standard Ada form. When used with GNAT, this file name will
- normally have an *ads* or *adb* suffix.
+ normally have an ``ads`` or ``adb`` suffix.
-* *deffile*
+* ``deffile``
is the full name of a text file containing definitions of
preprocessing symbols to be referenced by the preprocessor. This argument is
- optional, and can be replaced by the use of the *-D* switch.
+ optional, and can be replaced by the use of the :switch:`-D` switch.
.. _Switches_for_gnatprep:
-Switches for `gnatprep`
-^^^^^^^^^^^^^^^^^^^^^^^
+Switches for ``gnatprep``
+^^^^^^^^^^^^^^^^^^^^^^^^^
.. index:: --version (gnatprep)
-:samp:`--version`
+:switch:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatprep)
-:samp:`--help`
- If :option:`--version` was not used, display usage and then exit disregarding
+:switch:`--help`
+ If :switch:`--version` was not used, display usage and then exit disregarding
all other options.
.. index:: -b (gnatprep)
-:samp:`-b`
+:switch:`-b`
Causes both preprocessor lines and the lines deleted by
preprocessing to be replaced by blank lines in the output source file,
preserving line numbers in the output file.
.. index:: -c (gnatprep)
-:samp:`-c`
+:switch:`-c`
Causes both preprocessor lines and the lines deleted
by preprocessing to be retained in the output source as comments marked
- with the special string `"--! "`. This option will result in line numbers
+ with the special string ``"--! "``. This option will result in line numbers
being preserved in the output file.
.. index:: -C (gnatprep)
-:samp:`-C`
+:switch:`-C`
Causes comments to be scanned. Normally comments are ignored by gnatprep.
If this option is specified, then comments are scanned and any $symbol
substitutions performed as in program text. This is particularly useful
.. index:: -D (gnatprep)
-:samp:`-D{symbol}[={value}]`
+:switch:`-D{symbol}[={value}]`
Defines a new preprocessing symbol with the specified value. If no value is given
- on the command line, then symbol is considered to be `True`. This switch
+ on the command line, then symbol is considered to be ``True``. This switch
can be used in place of a definition file.
.. index:: -r (gnatprep)
-:samp:`-r`
- Causes a `Source_Reference` pragma to be generated that
+:switch:`-r`
+ Causes a ``Source_Reference`` pragma to be generated that
references the original input file, so that error messages will use
the file name of this original file. The use of this switch implies
that preprocessor lines are not to be removed from the file, so its
- use will force *-b* mode if *-c*
+ use will force ``-b`` mode if ``-c``
has not been specified explicitly.
Note that if the file to be preprocessed contains multiple units, then
- it will be necessary to `gnatchop` the output file from
- `gnatprep`. If a `Source_Reference` pragma is present
+ it will be necessary to ``gnatchop`` the output file from
+ ``gnatprep``. If a ``Source_Reference`` pragma is present
in the preprocessed file, it will be respected by
- `gnatchop -r`
+ ``gnatchop -r``
so that the final chopped files will correctly refer to the original
- input source file for `gnatprep`.
+ input source file for ``gnatprep``.
.. index:: -s (gnatprep)
-:samp:`-s`
+:switch:`-s`
Causes a sorted list of symbol names and values to be
listed on the standard output file.
.. index:: -T (gnatprep)
-:samp:`-T`
+:switch:`-T`
Use LF as line terminators when writing files. By default the line terminator
of the host (LF under unix, CR/LF under Windows) is used.
.. index:: -u (gnatprep)
-:samp:`-u`
+:switch:`-u`
Causes undefined symbols to be treated as having the value FALSE in the context
of a preprocessor test. In the absence of this option, an undefined symbol in
- a `#if` or `#elsif` test will be treated as an error.
+ a ``#if`` or ``#elsif`` test will be treated as an error.
.. index:: -v (gnatprep)
-:samp:`-v`
+:switch:`-v`
Verbose mode: generates more output about work done.
-Note: if neither *-b* nor *-c* is present,
+Note: if neither :switch:`-b` nor :switch:`-c` is present,
then preprocessor lines and
deleted lines are completely removed from the output, unless -r is
specified, in which case -b is assumed.
symbol := value
-where `symbol` is a preprocessing symbol, and `value` is one of the following:
+where ``symbol`` is a preprocessing symbol, and ``value`` is one of the following:
* Empty, corresponding to a null substitution,
* A string literal using normal Ada syntax, or
.. _Form_of_Input_Text_for_gnatprep:
-Form of Input Text for `gnatprep`
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Form of Input Text for ``gnatprep``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The input text may contain preprocessor conditional inclusion lines,
as well as general symbol substitution sequences.
For the first test (<expression> ::= <symbol>) the symbol must have
either the value true or false, that is to say the right-hand of the
symbol definition must be one of the (case-insensitive) literals
-`True` or `False`. If the value is true, then the
+``True`` or ``False``. If the value is true, then the
corresponding lines are included, and if the value is false, they are
excluded.
in the range 0 .. 2**31-1 are supported.
The test (<expression> ::= <symbol>'Defined) is true only if
-the symbol has been defined in the definition file or by a *-D*
+the symbol has been defined in the definition file or by a :switch:`-D`
switch on the command line. Otherwise, the test is false.
The equality tests are case insensitive, as are all the preprocessor lines.
If the symbol referenced is not defined in the symbol definitions file,
-then the effect depends on whether or not switch *-u*
+then the effect depends on whether or not switch :switch:`-u`
is specified. If so, then the symbol is treated as if it had the value
false and the test fails. If this switch is not specified, then
it is an error to reference an undefined symbol. It is also an error to
-reference a symbol that is defined with a value other than `True`
-or `False`.
+reference a symbol that is defined with a value other than ``True``
+or ``False``.
-The use of the `not` operator inverts the sense of this logical test.
-The `not` operator cannot be combined with the `or` or `and`
+The use of the ``not`` operator inverts the sense of this logical test.
+The ``not`` operator cannot be combined with the ``or`` or ``and``
operators, without parentheses. For example, "if not X or Y then" is not
allowed, but "if (not X) or Y then" and "if not (X or Y) then" are.
-The `then` keyword is optional as shown
+The ``then`` keyword is optional as shown
-The `#` must be the first non-blank character on a line, but
+The ``#`` must be the first non-blank character on a line, but
otherwise the format is free form. Spaces or tabs may appear between
-the `#` and the keyword. The keywords and the symbols are case
+the ``#`` and the keyword. The keywords and the symbols are case
insensitive as in normal Ada code. Comments may be used on a
preprocessor line, but other than that, no other tokens may appear on a
-preprocessor line. Any number of `elsif` clauses can be present,
-including none at all. The `else` is optional, as in Ada.
+preprocessor line. Any number of ``elsif`` clauses can be present,
+including none at all. The ``else`` is optional, as in Ada.
-The `#` marking the start of a preprocessor line must be the first
+The ``#`` marking the start of a preprocessor line must be the first
non-blank character on the line, i.e., it must be preceded only by
spaces or horizontal tabs.
anywhere within a source line, except in a comment or within a
string literal. The identifier
-following the `$` must match one of the symbols defined in the symbol
+following the ``$`` must match one of the symbols defined in the symbol
definition file, and the result is to substitute the value of the
-symbol in place of `$symbol` in the output file.
+symbol in place of ``$symbol`` in the output file.
Note that although the substitution of strings within a string literal
is not possible, it is possible to have a symbol whose defined value is
-a string literal. So instead of setting XYZ to `hello` and writing:
+a string literal. So instead of setting XYZ to ``hello`` and writing:
.. code-block:: c
Header : String := "$XYZ";
-you should set XYZ to `"hello"` and write:
+you should set XYZ to ``"hello"`` and write:
.. code-block:: c
As noted above, a file to be preprocessed consists of Ada source code
in which preprocessing lines have been inserted. However,
-instead of using *gnatprep* to explicitly preprocess a file as a separate
+instead of using ``gnatprep`` to explicitly preprocess a file as a separate
step before compilation, you can carry out the preprocessing implicitly
as part of compilation. Such *integrated preprocessing*, which is the common
style with C, is performed when either or both of the following switches
are passed to the compiler:
- * :option:`-gnatep`, which specifies the *preprocessor data file*.
+ * :switch:`-gnatep`, which specifies the *preprocessor data file*.
This file dictates how the source files will be preprocessed (e.g., which
symbol definition files apply to which sources).
- * :option:`-gnateD`, which defines values for preprocessing symbols.
+ * :switch:`-gnateD`, which defines values for preprocessing symbols.
Integrated preprocessing applies only to Ada source files, it is
not available for configuration pragma files.
With integrated preprocessing, the output from the preprocessor is not,
by default, written to any external file. Instead it is passed
internally to the compiler. To preserve the result of
-preprocessing in a file, either run *gnatprep*
-in standalone mode or else supply the :option:`-gnateG` switch
+preprocessing in a file, either run ``gnatprep``
+in standalone mode or else supply the :switch:`-gnateG` switch
(described below) to the compiler.
-The *gnatmake* switch :option:`-s` should be used with integrated
+The ``gnatmake`` switch :switch:`-s` should be used with integrated
preprocessing; otherwise the use of a different preprocessor data file
without changing the sources will not cause recompilation.
-Note that the *gnatmake* switch :option:`-m` will almost
+Note that the ``gnatmake`` switch :switch:`-m` will almost
always trigger recompilation for sources that are preprocessed,
-because *gnatmake* cannot compute the checksum of the source after
+because ``gnatmake`` cannot compute the checksum of the source after
preprocessing.
The actual preprocessing function is described in detail in
.. index:: -gnatep (gcc)
-:samp:`-gnatep={preprocessor_data_file}`
+:switch:`-gnatep={preprocessor_data_file}`
This switch specifies the file name (without directory
information) of the preprocessor data file. Either place this file
in one of the source directories, or, when using project
A preprocessor data file is a text file that contains *preprocessor
control lines*. A preprocessor control line directs the preprocessing of
- either a particular source file, or, analogous to *others* in Ada,
+ either a particular source file, or, analogous to ``others`` in Ada,
all sources not specified elsewhere in the preprocessor data file.
A preprocessor control line
can optionally identify a *definition file* that assigns values to
compiler in one of the source directories. In some cases, when compiling
a source in a directory other than the current directory, if the definition
file is in the current directory, it may be necessary to add the current
- directory as a source directory through the :option:`-I` switch; otherwise
+ directory as a source directory through the :switch:`-I` switch; otherwise
the compiler would not find the definition file.
- Finally, switches similar to those of *gnatprep* may optionally appear:
+ Finally, switches similar to those of ``gnatprep`` may optionally appear:
- :samp:`-b`
+ :switch:`-b`
Causes both preprocessor lines and the lines deleted by
preprocessing to be replaced by blank lines, preserving the line number.
- This switch is always implied; however, if specified after :option:`-c`
- it cancels the effect of :option:`-c`.
+ This switch is always implied; however, if specified after :switch:`-c`
+ it cancels the effect of :switch:`-c`.
- :samp:`-c`
+ :switch:`-c`
Causes both preprocessor lines and the lines deleted
by preprocessing to be retained as comments marked
with the special string '`--!`'.
- :samp:`-D{symbol}={new_value}`
- Define or redefine *symbol* to have *new_value* as its value.
- The permitted form for *symbol* is either an Ada identifier, or any Ada reserved word
- aside from `if`,
- `else`, `elsif`, `end`, `and`, `or` and `then`.
- The permitted form for `new_value` is a literal string, an Ada identifier or any Ada reserved
+ :switch:`-D{symbol}={new_value}`
+ Define or redefine ``symbol`` to have ``new_value`` as its value.
+ The permitted form for ``symbol`` is either an Ada identifier, or any Ada reserved word
+ aside from ``if``,
+ ``else``, ``elsif``, ``end``, ``and``, ``or`` and ``then``.
+ The permitted form for ``new_value`` is a literal string, an Ada identifier or any Ada reserved
word. A symbol declared with this switch replaces a symbol with the
same name defined in a definition file.
- :samp:`-s`
+ :switch:`-s`
Causes a sorted list of symbol names and values to be
listed on the standard output file.
- :samp:`-u`
- Causes undefined symbols to be treated as having the value `FALSE`
+ :switch:`-u`
+ Causes undefined symbols to be treated as having the value ``FALSE``
in the context
of a preprocessor test. In the absence of this option, an undefined symbol in
- a `#if` or `#elsif` test will be treated as an error.
+ a ``#if`` or ``#elsif`` test will be treated as an error.
.. index:: -gnateD (gcc)
-:samp:`-gnateD{symbol}[={new_value}]`
- Define or redefine *symbol* to have *new_value* as its value. If no value
- is supplied, then the value of *symbol* is `True`.
- The form of *symbol* is an identifier, following normal Ada (case-insensitive)
- rules for its syntax, and *new_value* is either an arbitrary string between double
+:switch:`-gnateD{symbol}[={new_value}]`
+ Define or redefine ``symbol`` to have ``new_value`` as its value. If no value
+ is supplied, then the value of ``symbol`` is ``True``.
+ The form of ``symbol`` is an identifier, following normal Ada (case-insensitive)
+ rules for its syntax, and ``new_value`` is either an arbitrary string between double
quotes or any sequence (including an empty sequence) of characters from the
set (letters, digits, period, underline).
- Ada reserved words may be used as symbols, with the exceptions of `if`,
- `else`, `elsif`, `end`, `and`, `or` and `then`.
+ Ada reserved words may be used as symbols, with the exceptions of ``if``,
+ ``else``, ``elsif``, ``end``, ``and``, ``or`` and ``then``.
Examples:
A symbol declared with this switch on the command line replaces a
symbol with the same name either in a definition file or specified with a
- switch :option:`-D` in the preprocessor data file.
+ switch :switch:`-D` in the preprocessor data file.
- This switch is similar to switch :option:`-D` of `gnatprep`.
+ This switch is similar to switch :switch:`-D` of ``gnatprep``.
-:samp:`-gnateG`
+:switch:`-gnateG`
When integrated preprocessing is performed on source file :file:`filename.extension`,
create or overwrite :file:`filename.extension.prep` to contain
the result of the preprocessing.
Interfacing Ada with a foreign language such as C involves using
compiler directives to import and/or export entity definitions in each
-language -- using `extern` statements in C, for instance, and the
-`Import`, `Export`, and `Convention` pragmas in Ada.
+language -- using ``extern`` statements in C, for instance, and the
+``Import``, ``Export``, and ``Convention`` pragmas in Ada.
A full treatment of these topics is provided in Appendix B, section 1
of the Ada Reference Manual.
$ gnatmake -c unit2.adb
* Run the Ada binder on every generated ALI file. Make sure to use the
- :option:`-n` option to specify a foreign main program:
+ :switch:`-n` option to specify a foreign main program:
.. code-block:: sh
This procedure yields a binary executable called :file:`exec_file`.
Depending on the circumstances (for example when your non-Ada main object
-does not provide symbol `main`), you may also need to instruct the
+does not provide symbol ``main``), you may also need to instruct the
GNAT linker not to include the standard startup objects by passing the
-:option:`-nostartfiles` switch to `gnatlink`.
+:switch:`-nostartfiles` switch to ``gnatlink``.
.. _Calling_Conventions:
.. index:: Convention Ada
-*Ada*
+``Ada``
This indicates that the standard Ada calling sequence will be
used and all Ada data items may be passed without any limitations in the
case where GNAT is used to generate both the caller and callee. It is also
.. index:: Convention Assembler
-*Assembler*
+``Assembler``
Specifies assembler as the convention. In practice this has the
same effect as convention Ada (but is not equivalent in the sense of being
considered the same convention).
.. index:: Asm
-*Asm*
+``Asm``
Equivalent to Assembler.
.. index:: Interfacing to COBOL
.. index:: COBOL
-*COBOL*
+``COBOL``
Data will be passed according to the conventions described
in section B.4 of the Ada Reference Manual.
.. index:: Convention C
-*C*
+``C``
Data will be passed according to the conventions described
in section B.3 of the Ada Reference Manual.
.. index:: Interfacing to C varargs function
.. index:: varargs function interfaces
- In C, `varargs` allows a function to take a variable number of
+ In C, ``varargs`` allows a function to take a variable number of
arguments. There is no direct equivalent in this to Ada. One
approach that can be used is to create a C wrapper for each
different profile and then interface to this C wrapper. For
- example, to print an `int` value using `printf`,
- create a C function `printfi` that takes two arguments, a
- pointer to a string and an int, and calls `printf`.
- Then in the Ada program, use pragma `Import` to
- interface to `printfi`.
+ example, to print an ``int`` value using ``printf``,
+ create a C function ``printfi`` that takes two arguments, a
+ pointer to a string and an int, and calls ``printf``.
+ Then in the Ada program, use pragma ``Import`` to
+ interface to ``printfi``.
It may work on some platforms to directly interface to
- a `varargs` function by providing a specific Ada profile
+ a ``varargs`` function by providing a specific Ada profile
for a particular call. However, this does not work on
all platforms, since there is no guarantee that the
calling sequence for a two argument normal C function
- is the same as for calling a `varargs` C function with
+ is the same as for calling a ``varargs`` C function with
the same two arguments.
.. index:: Convention Default
.. index:: Default
-*Default*
+``Default``
Equivalent to C.
.. index:: Convention External
.. index:: External
-*External*
+``External``
Equivalent to C.
.. index:: C++
.. index:: Convention C++
-*C_Plus_Plus (or CPP)*
+``C_Plus_Plus`` (or ``CPP``)
This stands for C++. For most purposes this is identical to C.
See the separate description of the specialized GNAT pragmas relating to
C++ interfacing for further details.
.. index:: Convention Fortran
-*Fortran*
+``Fortran``
Data will be passed according to the conventions described
in section B.5 of the Ada Reference Manual.
-*Intrinsic*
+``Intrinsic``
This applies to an intrinsic operation, as defined in the Ada
Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram,
this means that the body of the subprogram is provided by the compiler itself,
* General subprogram entities. This is used to bind an Ada subprogram
declaration to
a compiler builtin by name with back-ends where such interfaces are
- available. A typical example is the set of `__builtin` functions
+ available. A typical example is the set of ``__builtin`` functions
exposed by the GCC back-end, as in the following example:
.. index:: Stdcall
.. index:: Convention Stdcall
-*Stdcall*
+``Stdcall``
This is relevant only to Windows implementations of GNAT,
- and specifies that the `Stdcall` calling sequence will be used,
+ and specifies that the ``Stdcall`` calling sequence will be used,
as defined by the NT API. Nevertheless, to ease building
- cross-platform bindings this convention will be handled as a `C` calling
+ cross-platform bindings this convention will be handled as a ``C`` calling
convention on non-Windows platforms.
.. index:: DLL
.. index:: Convention DLL
-*DLL*
- This is equivalent to `Stdcall`.
+``DLL``
+ This is equivalent to ``Stdcall``.
.. index:: Win32
.. index:: Convention Win32
-*Win32*
- This is equivalent to `Stdcall`.
+``Win32``
+ This is equivalent to ``Stdcall``.
.. index:: Stubbed
.. index:: Convention Stubbed
-*Stubbed*
+``Stubbed``
This is a special convention that indicates that the compiler
- should provide a stub body that raises `Program_Error`.
+ should provide a stub body that raises ``Program_Error``.
-GNAT additionally provides a useful pragma `Convention_Identifier`
+GNAT additionally provides a useful pragma ``Convention_Identifier``
that can be used to parameterize conventions and allow additional synonyms
to be specified. For example if you have legacy code in which the convention
identifier Fortran77 was used for Fortran, you can use the configuration
pragma Convention_Identifier (Fortran77, Fortran);
And from now on the identifier Fortran77 may be used as a convention
-identifier (for example in an `Import` pragma) with the same
+identifier (for example in an ``Import`` pragma) with the same
meaning as Fortran.
Interface ---see http://www.codesourcery.com/archives/cxx-abi).
Interfacing can be done at 3 levels: simple data, subprograms, and
-classes. In the first two cases, GNAT offers a specific `Convention C_Plus_Plus`
-(or `CPP`) that behaves exactly like `Convention C`.
+classes. In the first two cases, GNAT offers a specific ``Convention C_Plus_Plus``
+(or ``CPP``) that behaves exactly like ``Convention C``.
Usually, C++ mangles the names of subprograms. To generate proper mangled
names automatically, see :ref:`Generating_Ada_Bindings_for_C_and_C++_headers`).
This problem can also be addressed manually in two ways:
* by modifying the C++ code in order to force a C convention using
- the `extern "C"` syntax.
+ the ``extern "C"`` syntax.
-* by figuring out the mangled name (using e.g. *nm*) and using it as the
+* by figuring out the mangled name (using e.g. ``nm``) and using it as the
Link_Name argument of the pragma import.
Interfacing at the class level can be achieved by using the GNAT specific
-pragmas such as `CPP_Constructor`. See the :title:`GNAT_Reference_Manual` for additional information.
+pragmas such as ``CPP_Constructor``. See the :title:`GNAT_Reference_Manual` for additional information.
.. _Linking_a_Mixed_C++_and_Ada_Program:
* Using GNAT and G++ (GNU C++ compiler) from the same GCC installation:
The C++ linker can simply be called by using the C++ specific driver
- called `g++`.
+ called ``g++``.
Note that if the C++ code uses inline functions, you will need to
- compile your C++ code with the `-fkeep-inline-functions` switch in
+ compile your C++ code with the :switch:`-fkeep-inline-functions` switch in
order to provide an existing function implementation that the Ada code can
link with.
improperly if set during invocation of the wrong compiler. It is also
very important that the linker uses the proper :file:`libgcc.a` GCC
library -- that is, the one from the C++ compiler installation. The
- implicit link command as suggested in the `gnatmake` command
+ implicit link command as suggested in the ``gnatmake`` command
from the former example can be replaced by an explicit link command with
the full-verbosity option in order to verify which library is used:
a few more parameters to the link command line, depending on the exception
mechanism used.
- If the `setjmp/longjmp` exception mechanism is used, only the paths
- to the libgcc libraries are required:
+ If the ``setjmp`` / ``longjmp`` exception mechanism is used, only the paths
+ to the ``libgcc`` libraries are required:
.. code-block:: sh
$ cat ./my_script
#!/bin/sh
- CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a`
+ CC $* gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
where CC is the name of the non-GNU C++ compiler.
- If the `zero cost` exception mechanism is used, and the platform
+ If the "zero cost" exception mechanism is used, and the platform
supports automatic registration of exception tables (e.g., Solaris),
paths to more objects are required:
$ cat ./my_script
#!/bin/sh
- CC `gcc -print-file-name=crtbegin.o` $* \\
- `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \\
- `gcc -print-file-name=crtend.o`
+ CC gcc -print-file-name=crtbegin.o $* \\
+ gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a \\
+ gcc -print-file-name=crtend.o
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to interface with C++ constructors GNAT provides the
-`pragma CPP_Constructor` (see the :title:`GNAT_Reference_Manual`
+``pragma CPP_Constructor`` (see the :title:`GNAT_Reference_Manual`
for additional information).
In this section we present some common uses of C++ constructors
in mixed-languages programs in GNAT.
Constructors can only appear in the following contexts:
-* On the right side of an initialization of an object of type `T`.
-* On the right side of an initialization of a record component of type `T`.
+* On the right side of an initialization of an object of type ``T``.
+* On the right side of an initialization of a record component of type ``T``.
* In an Ada 2005 limited aggregate.
* In an Ada 2005 nested limited aggregate.
* In an Ada 2005 limited aggregate that initializes an object built in
The first two declarations are equivalent: in both cases the default C++
constructor is invoked (in the former case the call to the constructor is
implicit, and in the latter case the call is explicit in the object
-declaration). `Obj3` is initialized by the C++ non-default constructor
-that takes an integer argument, and `Obj4` is initialized by the
+declaration). ``Obj3`` is initialized by the C++ non-default constructor
+that takes an integer argument, and ``Obj4`` is initialized by the
non-default C++ constructor that takes two integers.
Let us derive the imported C++ class in the Ada side. For example:
Obj6 : DT := Function_Returning_DT (50);
Obj7 : DT := (Constructor (30,40) with C_Value => 50);
-The declaration of `Obj5` invokes the default constructors: the
+The declaration of ``Obj5`` invokes the default constructors: the
C++ default constructor of the parent type takes care of the initialization
of the components inherited from Root, and GNAT takes care of the default
initialization of the additional Ada components of type DT (that is,
-`C_Value` is initialized to value 2009). The order of invocation of
+``C_Value`` is initialized to value 2009). The order of invocation of
the constructors is consistent with the order of elaboration required by
Ada and C++. That is, the constructor of the parent type is always called
before the constructor of the derived type.
Data2 : Root := Constructor (D, 30);
end record;
-The initialization of an object of type `Rec2` will call the
+The initialization of an object of type ``Rec2`` will call the
non-default C++ constructors specified for the imported components.
For example:
others => <>);
The above declaration uses an Ada 2005 limited aggregate to
-initialize `Obj9`, and the C++ constructor that has two integer
-arguments is invoked to initialize the `Data1` component instead
-of the constructor specified in the declaration of type `Rec1`. In
+initialize ``Obj9``, and the C++ constructor that has two integer
+arguments is invoked to initialize the ``Data1`` component instead
+of the constructor specified in the declaration of type ``Rec1``. In
Ada 2005 the box in the aggregate indicates that unspecified components
are initialized using the expression (if any) available in the component
-declaration. That is, in this case discriminant `D` is initialized
-to value `20`, `Value` is initialized to value 1000, and the
+declaration. That is, in this case discriminant ``D`` is initialized
+to value ``20``, ``Value`` is initialized to value 1000, and the
non-default C++ constructor that handles two integers takes care of
-initializing component `Data2` with values `20,30`.
+initializing component ``Data2`` with values ``20,30``.
In Ada 2005 we can use the extended return statement to build the Ada
equivalent to C++ non-default constructors. For example:
constructors are defined on the C++ side and imported from the Ada
side, and latter the reverse case.
-The root of our derivation will be the `Animal` class, with a
-single private attribute (the `Age` of the animal), a constructor,
+The root of our derivation will be the ``Animal`` class, with a
+single private attribute (the ``Age`` of the animal), a constructor,
and two public primitives to set and get the value of this attribute.
.. code-block:: cpp
Abstract interface types are defined in C++ by means of classes with pure
virtual functions and no data members. In our example we will use two
-interfaces that provide support for the common management of `Carnivore`
-and `Domestic` animals:
+interfaces that provide support for the common management of ``Carnivore``
+and ``Domestic`` animals:
.. code-block:: cpp
virtual void Set_Owner (char* Name) = 0;
};
-Using these declarations, we can now say that a `Dog` is an animal that is
+Using these declarations, we can now say that a ``Dog`` is an animal that is
both Carnivore and Domestic, that is:
.. code-block:: cpp
};
In the following examples we will assume that the previous declarations are
-located in a file named `animals.h`. The following package demonstrates
+located in a file named :file:`animals.h`. The following package demonstrates
how to import these C++ declarations from the Ada side:
.. code-block:: ada
the two languages.
Regarding the abstract interfaces, we must indicate to the GNAT compiler by
-means of a `pragma Convention (C_Plus_Plus)`, the convention used to pass
+means of a ``pragma Convention (C_Plus_Plus)``, the convention used to pass
the arguments to the called primitives will be the same as for C++. For the
-imported classes we use `pragma Import` with convention `C_Plus_Plus`
+imported classes we use ``pragma Import`` with convention ``C_Plus_Plus``
to indicate that they have been defined on the C++ side; this is required
because the dispatch table associated with these tagged types will be built
in the C++ side and therefore will not contain the predefined Ada primitives
associated with each subprogram because it is assumed that all the calls to
these primitives will be dispatching calls. The only exception is the
constructor, which must be registered with the compiler by means of
-`pragma CPP_Constructor` and needs to provide its associated C++
+``pragma CPP_Constructor`` and needs to provide its associated C++
mangled name because the Ada compiler generates direct calls to it.
With the above packages we can now declare objects of type Dog on the Ada side
end Animals;
Compared with our previous example the only differences are the use of
-`pragma Convention` (instead of `pragma Import`), and the use of
-`pragma Export` to indicate to the GNAT compiler that the primitives will
+``pragma Convention`` (instead of ``pragma Import``), and the use of
+``pragma Export`` to indicate to the GNAT compiler that the primitives will
be available to C++. Thanks to the ABI compatibility, on the C++ side there is
nothing else to be done; as explained above, the only requirement is that all
the primitives and components are declared in exactly the same order.
For completeness, let us see a brief C++ main program that uses the
-declarations available in `animals.h` (presented in our first example) to
+declarations available in :file:`animals.h` (presented in our first example) to
import and use the declarations from the Ada side, properly initializing and
finalizing the Ada run-time system along the way:
* some extensions (e.g. vector types) are not supported
* pointers to pointers or complex structures are mapped to System.Address
* identifiers with identical name (except casing) will generate compilation
- errors (e.g. `shm_get` vs `SHM_GET`).
+ errors (e.g. ``shm_get`` vs ``SHM_GET``).
The code generated is using the Ada 2005 syntax, which makes it
easier to interface with other languages than previous versions of Ada.
Running the Binding Generator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The binding generator is part of the *gcc* compiler and can be
-invoked via the *-fdump-ada-spec* switch, which will generate Ada
+The binding generator is part of the ``gcc`` compiler and can be
+invoked via the :switch:`-fdump-ada-spec` switch, which will generate Ada
spec files for the header files specified on the command line, and all
header files needed by these files transitively. For example:
will generate, under GNU/Linux, the following files: :file:`time_h.ads`,
:file:`bits_time_h.ads`, :file:`stddef_h.ads`, :file:`bits_types_h.ads` which
correspond to the files :file:`/usr/include/time.h`,
-:file:`/usr/include/bits/time.h`, etc..., and will then compile in Ada 2005
-mode these Ada specs.
+:file:`/usr/include/bits/time.h`, etc..., and will then compile these Ada specs
+in Ada 2005 mode.
-The `-C` switch tells *gcc* to extract comments from headers,
+The :switch:`-C` switch tells ``gcc`` to extract comments from headers,
and will attempt to generate corresponding Ada comments.
If you want to generate a single Ada file and not the transitive closure, you
-can use instead the *-fdump-ada-spec-slim* switch.
+can use instead the :switch:`-fdump-ada-spec-slim` switch.
You can optionally specify a parent unit, of which all generated units will
-be children, using `-fada-spec-parent=<unit>`.
+be children, using :switch:`-fada-spec-parent={unit}`.
Note that we recommend when possible to use the *g++* driver to
generate bindings, even for most C headers, since this will in general
mandatory to use the *g++* command, or *gcc -x c++* which
is equivalent in this case. If *g++* cannot work on your C headers
because of incompatibilities between C and C++, then you can fallback to
-*gcc* instead.
+``gcc`` instead.
For an example of better bindings generated from the C++ front-end,
the name of the parameters (when available) are actually ignored by the C
extern void foo (int variable);
-with the C front-end, `variable` is ignored, and the above is handled as:
+with the C front-end, ``variable`` is ignored, and the above is handled as:
.. code-block:: c
procedure foo (variable : int);
In some cases, the generated bindings will be more complete or more meaningful
-when defining some macros, which you can do via the *-D* switch. This
+when defining some macros, which you can do via the :switch:`-D` switch. This
is for example the case with :file:`Xlib.h` under GNU/Linux:
.. code-block:: sh
$ g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
The above will generate more complete bindings than a straight call without
-the *-DXLIB_ILLEGAL_ACCESS* switch.
+the :switch:`-DXLIB_ILLEGAL_ACCESS` switch.
In other cases, it is not possible to parse a header file in a stand-alone
manner, because other include files need to be included first. In this
case, the solution is to create a small header file including the needed
-`#include` and possible `#define` directives. For example, to
+``#include`` and possible ``#define`` directives. For example, to
generate Ada bindings for :file:`readline/readline.h`, you need to first
include :file:`stdio.h`, so you can create a file with the following two
lines in e.g. :file:`readline1.h`:
bindings by hand more extensively when using C++ headers.
In this mode, C++ classes will be mapped to Ada tagged types, constructors
-will be mapped using the `CPP_Constructor` pragma, and when possible,
+will be mapped using the ``CPP_Constructor`` pragma, and when possible,
multiple inheritance of abstract classes will be mapped to Ada interfaces
(see the *Interfacing to C++* section in the :title:`GNAT Reference Manual`
for additional information on interfacing to C++).
.. index:: -fdump-ada-spec (gcc)
-:samp:`-fdump-ada-spec`
+:switch:`-fdump-ada-spec`
Generate Ada spec files for the given header files transitively (including
all header files that these headers depend upon).
.. index:: -fdump-ada-spec-slim (gcc)
-:samp:`-fdump-ada-spec-slim`
+:switch:`-fdump-ada-spec-slim`
Generate Ada spec files for the header files specified on the command line
only.
.. index:: -fada-spec-parent (gcc)
-:samp:`-fada-spec-parent={unit}`
- Specifies that all files generated by *-fdump-ada-spec** are
+:switch:`-fada-spec-parent={unit}`
+ Specifies that all files generated by :switch:`-fdump-ada-spec` are
to be child units of the specified parent unit.
.. index:: -C (gcc)
-:samp:`-C`
+:switch:`-C`
Extract comments from headers and generate Ada comments in the Ada spec files.
.. _Generating_C_Headers_for_Ada_Specifications:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The C header generator is part of the GNAT compiler and can be invoked via
-the *-gnatceg* combination of switches, which will generate a :file:`.h`
+the :switch:`-gnatceg` combination of switches, which will generate a :file:`.h`
file corresponding to the given input file (Ada spec or body). Note that
only spec files are processed in any case, so giving a spec or a body file
as input is equivalent. For example:
procedure Proc2 (R : in out Rec);
end Pack1;
-The above `gcc` command will generate the following :file:`pack1.h` file:
+The above ``gcc`` command will generate the following :file:`pack1.h` file:
.. code-block:: c
extern void pack1__proc2(pack1__rec *r);
#endif /* PACK1_ADS */
-You can then `include` :file:`pack1.h` from a C source file and use the types,
+You can then ``include`` :file:`pack1.h` from a C source file and use the types,
call subprograms, reference objects, and constants.
.. _GNAT_and_Other_Compilation_Models:
The GNAT model of compilation is close to the C and C++ models. You can
think of Ada specs as corresponding to header files in C. As in C, you
don't need to compile specs; they are compiled when they are used. The
-Ada |with| is similar in effect to the `#include` of a C
+Ada |with| is similar in effect to the ``#include`` of a C
header.
One notable difference is that, in Ada, you may compile specs separately
issues. There are also elaboration issues in C++ that are handled
automatically. This automatic handling has the advantage of being
simpler to use, but the C++ programmer has no control over elaboration.
-Where `gnatbind` might complain there was no valid order of
+Where ``gnatbind`` might complain there was no valid order of
elaboration, a C++ compiler would simply construct a program that
malfunctioned at run time.
.. index:: pragma Export
-The variable `MN` has a full expanded Ada name of `QRS.MN`, so
-the corresponding link name is `qrs__mn`.
-Of course if a `pragma Export` is used this may be overridden:
+The variable ``MN`` has a full expanded Ada name of ``QRS.MN``, so
+the corresponding link name is ``qrs__mn``.
+Of course if a ``pragma Export`` is used this may be overridden:
.. code-block:: ada
pragma Export (Var2, C, Link_Name => "var2_link_name");
end Exports;
-In this case, the link name for `Var1` is whatever link name the
-C compiler would assign for the C function `var1_name`. This typically
-would be either `var1_name` or `_var1_name`, depending on operating
+In this case, the link name for ``Var1`` is whatever link name the
+C compiler would assign for the C function ``var1_name``. This typically
+would be either ``var1_name`` or ``_var1_name``, depending on operating
system conventions, but other possibilities exist. The link name for
-`Var2` is `var2_link_name`, and this is not operating system
+``Var2`` is ``var2_link_name``, and this is not operating system
dependent.
One exception occurs for library level procedures. A potential ambiguity
-arises between the required name `_main` for the C main program,
+arises between the required name ``_main`` for the C main program,
and the name we would otherwise assign to an Ada library level procedure
-called `Main` (which might well not be the main program).
+called ``Main`` (which might well not be the main program).
-To avoid this ambiguity, we attach the prefix `_ada_` to such
+To avoid this ambiguity, we attach the prefix ``_ada_`` to such
names. So if we have a library level procedure such as:
.. code-block:: ada
procedure Hello (S : String);
-the external name of this procedure will be `_ada_hello`.
+the external name of this procedure will be ``_ada_hello``.
@copying
@quotation
-GNAT Reference Manual , Apr 25, 2017
+GNAT Reference Manual , Sep 08, 2017
AdaCore
* Pragma Main_Storage::
* Pragma Max_Queue_Length::
* Pragma No_Body::
+* Pragma No_Component_Reordering::
* Pragma No_Elaboration_Code_All::
* Pragma No_Heap_Finalization::
* Pragma No_Inline::
* Aspect Lock_Free::
* Aspect Max_Queue_Length::
* Aspect No_Elaboration_Code_All::
+* Aspect No_Inline::
* Aspect No_Tagged_Streams::
* Aspect Object_Size::
* Aspect Obsolescent::
* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads.
* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads.
* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads.
+* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads.
+* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads.
+* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads.
* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads.
* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads.
* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads.
@itemize *
@item
-@cite{Functions}, @cite{utility program names}, @cite{standard names},
-and @cite{classes}.
+@code{Functions}, @code{utility program names}, @code{standard names},
+and @code{classes}.
@item
-@cite{Option flags}
+@code{Option flags}
@item
@code{File names}
@item
-@cite{Variables}
+@code{Variables}
@item
@emph{Emphasis}
* Pragma Main_Storage::
* Pragma Max_Queue_Length::
* Pragma No_Body::
+* Pragma No_Component_Reordering::
* Pragma No_Elaboration_Code_All::
* Pragma No_Heap_Finalization::
* Pragma No_Inline::
@end example
This pragma must appear at the start of the statement sequence of a
-handled sequence of statements (right after the @cite{begin}). It has
+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).
ABSTRACT_STATE ::= name
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Abstract_State} in
+For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in
the SPARK 2014 Reference Manual, section 7.1.4.
@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas
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 @cite{(<>)} notation. In addition, some but not all of the additional
+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
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 @cite{Ada} and @cite{System}
+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
A configuration pragma that establishes Ada 2012 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 @cite{Ada} and @cite{System}
+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 2012 features, but which is intended to be usable from
pragma Allow_Integer_Address;
@end example
-In almost all versions of GNAT, @cite{System.Address} is a private
+In almost all versions of GNAT, @code{System.Address} is a private
type in accordance with the implementation advice in the RM. This
means that integer values,
in particular integer literals, are not allowed as address values.
If the configuration pragma
-@cite{Allow_Integer_Address} is given, then integer expressions may
-be used anywhere a value of type @cite{System.Address} is required.
+@code{Allow_Integer_Address} is given, then integer expressions may
+be used anywhere a value of type @code{System.Address} is required.
The effect is to introduce an implicit unchecked conversion from the
-integer value to type @cite{System.Address}. The reverse case of using
+integer value to type @code{System.Address}. The reverse case of using
an address where an integer type is required is handled analogously.
The following example compiles without errors:
end AddrAsInt;
@end example
-Note that pragma @cite{Allow_Integer_Address} is ignored if @cite{System.Address}
-is not a private type. In implementations of @cite{GNAT} where
+Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address}
+is not a private type. In implementations of @code{GNAT} where
System.Address is a visible integer type,
this pragma serves no purpose but is ignored
rather than rejected to allow common sets of sources to be used
ARG ::= NAME | EXPRESSION
@end example
-This pragma is used to annotate programs. @cite{identifier} identifies
+This pragma is used to annotate programs. IDENTIFIER identifies
the type of annotation. GNAT verifies that it is an identifier, but does
not otherwise analyze it. The second optional identifier is also left
unanalyzed, and by convention is used to control the action of the tool to
-which the annotation is addressed. The remaining @cite{arg} arguments
+which the annotation is addressed. The remaining ARG arguments
can be either string literals or more generally expressions.
String literals are assumed to be either of type
-@cite{Standard.String} or else @cite{Wide_String} or @cite{Wide_Wide_String}
+@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String}
depending on the character literals they contain.
All other kinds of arguments are analyzed as expressions, and must be
unambiguous. The last argument if present must have the identifier
-@cite{Entity} and GNAT verifies that a local name is given.
+@code{Entity} and GNAT verifies that a local name is given.
The analyzed pragma is retained in the tree, but not otherwise processed
by any part of the GNAT compiler, except to generate corresponding note
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 @cite{file}:@cite{nnn},
-where @cite{file} is the name of the source file containing the assert,
-and @cite{nnn} is the line number of the assert.
+argument is given, the default message is @code{file}:@code{nnn},
+where @code{file} is the name of the source file containing the assert,
+and @code{nnn} is the line number of the assert.
-Note that, as with the @cite{if} statement to which it is equivalent, the
-type of the expression is either @cite{Standard.Boolean}, or any type derived
+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.
Assert checks can be either checked or ignored. By default they are ignored.
They will be checked if either the command line switch @emph{-gnata} is
-used, or if an @cite{Assertion_Policy} or @cite{Check_Policy} pragma is used
-to enable @cite{Assert_Checks}.
+used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used
+to enable @code{Assert_Checks}.
If assertions are ignored, then there
is no run-time effect (and in particular, any side effects from the
mentioned here for the first time).
If assertions are checked, then the given expression is tested, and if
-it is @cite{False} then @cite{System.Assertions.Raise_Assert_Failure} is called
-which results in the raising of @cite{Assert_Failure} with the given message.
+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
semantic correctness whether or not assertions are enabled, so turning
assertions on and off cannot affect the legality of a program.
-Note that the implementation defined policy @cite{DISABLE}, given in a
-pragma @cite{Assertion_Policy}, can be used to suppress this semantic analysis.
+Note that the implementation defined policy @code{DISABLE}, given in a
+pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis.
Note: this is a standard language-defined pragma in versions
of Ada from 2005 on. In GNAT, it is implemented in all versions
[, string_EXPRESSION]);
@end example
-The effect of this pragma is identical to that of pragma @cite{Assert},
-except that in an @cite{Assertion_Policy} pragma, the identifier
-@cite{Assert_And_Cut} is used to control whether it is ignored or checked
+The effect of this pragma is identical to that of pragma @code{Assert},
+except that in an @code{Assertion_Policy} pragma, the identifier
+@code{Assert_And_Cut} is used to control whether it is ignored or checked
(or disabled).
The intention is that this be used within a subprogram when the
This is a standard Ada 2012 pragma that is available as an
implementation-defined pragma in earlier versions of Ada.
-The assertion kinds @cite{RM_ASSERTION_KIND} are those defined in
-the Ada standard. The assertion kinds @cite{ID_ASSERTION_KIND}
+The assertion kinds @code{RM_ASSERTION_KIND} are those defined in
+the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND}
are implementation defined additions recognized by the GNAT compiler.
The pragma applies in both cases to pragmas and aspects with matching
-names, e.g. @cite{Pre} applies to the Pre aspect, and @cite{Precondition}
-applies to both the @cite{Precondition} pragma
-and the aspect @cite{Precondition}. Note that the identifiers for
+names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition}
+applies to both the @code{Precondition} pragma
+and the aspect @code{Precondition}. Note that the identifiers for
pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not
Pre_Class and Post_Class), since these pragmas are intended to be
identical to the corresponding aspects).
-If the policy is @cite{CHECK}, then assertions are enabled, i.e.
+If the policy is @code{CHECK}, then assertions are enabled, i.e.
the corresponding pragma or aspect is activated.
-If the policy is @cite{IGNORE}, then assertions are ignored, i.e.
+If the policy is @code{IGNORE}, then assertions are ignored, i.e.
the corresponding pragma or aspect is deactivated.
This pragma overrides the effect of the @emph{-gnata} switch on the
command line.
-If the policy is @cite{SUPPRESSIBLE}, then assertions are enabled by default,
+If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default,
however, if the @emph{-gnatp} switch is specified all assertions are ignored.
-The implementation defined policy @cite{DISABLE} is like
-@cite{IGNORE} except that it completely disables semantic
+The implementation defined policy @code{DISABLE} is like
+@code{IGNORE} except that it completely disables semantic
checking of the corresponding pragma or aspect. This is
useful when the pragma or aspect argument references subprograms
in a with'ed package which is replaced by a dummy package
for the final build.
-The implementation defined assertion kind @cite{Assertions} applies to all
+The implementation defined assertion kind @code{Assertions} applies to all
assertion kinds. The form with no assertion kind given implies this
choice, so it applies to all assertion kinds (RM defined, and
implementation defined).
-The implementation defined assertion kind @cite{Statement_Assertions}
-applies to @cite{Assert}, @cite{Assert_And_Cut},
-@cite{Assume}, @cite{Loop_Invariant}, and @cite{Loop_Variant}.
+The implementation defined assertion kind @code{Statement_Assertions}
+applies to @code{Assert}, @code{Assert_And_Cut},
+@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}.
@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2a}
[, string_EXPRESSION]);
@end example
-The effect of this pragma is identical to that of pragma @cite{Assert},
-except that in an @cite{Assertion_Policy} pragma, the identifier
-@cite{Assume} is used to control whether it is ignored or checked
+The effect of this pragma is identical to that of pragma @code{Assert},
+except that in an @code{Assertion_Policy} pragma, the identifier
+@code{Assume} is used to control whether it is ignored or checked
(or disabled).
The intention is that this be used for assumptions about the
or informally that the condition is met, this must be
established by examining things outside the program itself.
For example, we may have code that depends on the size of
-@cite{Long_Long_Integer} being at least 64. So we could write:
+@code{Long_Long_Integer} being at least 64. So we could write:
@example
pragma Assume (Long_Long_Integer'Size >= 64);
if V1 and V2 have valid values, then the loop is known at compile
time not to execute since the lower bound must be greater than the
upper bound. However in default mode, no such assumption is made,
-and the loop may execute. If @cite{Assume_No_Invalid_Values (On)}
+and the loop may execute. If @code{Assume_No_Invalid_Values (On)}
is given, the compiler will assume that any occurrence of a variable
-other than in an explicit @cite{'Valid} test always has a valid
+other than in an explicit @code{'Valid} test always has a valid
value, and the loop above will be optimized away.
-The use of @cite{Assume_No_Invalid_Values (On)} is appropriate if
+The use of @code{Assume_No_Invalid_Values (On)} is appropriate if
you know your code is free of uninitialized variables and other
possible sources of invalid representations, and may result in
more efficient code. A program that accesses an invalid representation
pragma Asynch_Readers [ (boolean_EXPRESSION) ];
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Async_Readers} in
+For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in
the SPARK 2014 Reference Manual, section 7.1.2.
@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas
pragma Asynch_Writers [ (boolean_EXPRESSION) ];
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Async_Writers} in
+For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in
the SPARK 2014 Reference Manual, section 7.1.2.
@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas
[Expression =>] EXPRESSION | NAME);
@end example
-If @cite{Attribute} is a known attribute name, this pragma is equivalent to
+If @code{Attribute} is a known attribute name, this pragma is equivalent to
the attribute definition clause:
@example
for Entity'Attribute use Expression;
@end example
-If @cite{Attribute} is not a recognized attribute name, the pragma is
+If @code{Attribute} is not a recognized attribute name, the pragma is
ignored, and a warning is emitted. This allows source
code to be written that takes advantage of some new attribute, while remaining
compilable with earlier compilers.
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 @cite{C_Pass_By_Copy} to change
+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:
@item
The size of the record type does not exceed the value specified for
-@cite{Max_Size}.
+@code{Max_Size}.
@item
-The record type has @cite{Convention C}.
+The record type has @code{Convention C}.
@item
The formal parameter has this record type, and the subprogram has a
C prototype is a struct (rather than a pointer to a struct).
You can also pass records by copy by specifying the convention
-@cite{C_Pass_By_Copy} for the record type, or by using the extended
-@cite{Import} and @cite{Export} pragmas, which allow specification of
+@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,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas
Invariant'Class
@end example
-This pragma is similar to the predefined pragma @cite{Assert} except that an
+This pragma is similar to the predefined pragma @code{Assert} except that an
extra identifier argument is present. In conjunction with pragma
-@cite{Check_Policy}, this can be used to define groups of assertions that can
-be independently controlled. The identifier @cite{Assertion} is special, it
-refers to the normal set of pragma @cite{Assert} statements.
+@code{Check_Policy}, this can be used to define groups of assertions that can
+be independently controlled. The identifier @code{Assertion} is special, it
+refers to the normal set of pragma @code{Assert} statements.
Checks introduced by this pragma are normally deactivated by default. They can
be activated either by the command line option @emph{-gnata}, which turns on
-all checks, or individually controlled using pragma @cite{Check_Policy}.
+all checks, or individually controlled using pragma @code{Check_Policy}.
-The identifiers @cite{Assertions} and @cite{Statement_Assertions} are not
+The identifiers @code{Assertions} and @code{Statement_Assertions} are not
permitted as check kinds, since this would cause confusion with the use
-of these identifiers in @cite{Assertion_Policy} and @cite{Check_Policy}
+of these identifiers in @code{Assertion_Policy} and @code{Check_Policy}
pragmas, where they are used to refer to sets of assertions.
@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas
pragma Check_Float_Overflow;
@end example
-In Ada, the predefined floating-point types (@cite{Short_Float},
-@cite{Float}, @cite{Long_Float}, @cite{Long_Long_Float}) are
+In Ada, the predefined floating-point types (@code{Short_Float},
+@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are
defined to be @emph{unconstrained}. This means that even though each
has a well-defined base range, an operation that delivers a result
outside this base range is not required to raise an exception.
subtype My_Float is Float range Float'Range;
@end example
-Here @cite{My_Float} has the same range as
-@cite{Float} but is constrained, so operations on
-@cite{My_Float} values will be checked for overflow
+Here @code{My_Float} has the same range as
+@code{Float} but is constrained, so operations on
+@code{My_Float} values will be checked for overflow
against this range.
This style will achieve the desired goal, but
it is often more convenient to be able to simply use
the standard predefined floating-point types as long
as overflow checking could be guaranteed.
-The @cite{Check_Float_Overflow}
+The @code{Check_Float_Overflow}
configuration pragma achieves this effect. If a unit is compiled
subject to this configuration pragma, then all operations
on predefined floating-point types including operations on
base types of these floating-point types will be treated as
though those types were constrained, and overflow checks
-will be generated. The @cite{Constraint_Error}
+will be generated. The @code{Constraint_Error}
exception is raised if the result is out of range.
This mode can also be set by use of the compiler
check name is introduced.
An implementation defined check name introduced with this pragma may
-be used in only three contexts: @cite{pragma Suppress},
-@cite{pragma Unsuppress},
-and as the prefix of a @cite{Check_Name'Enabled} attribute reference. For
+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 @cite{with} clauses).
+are mentioned in @code{with} clauses).
Check names introduced by this pragma are subject to control by compiler
switches (in particular -gnatp) in the usual manner.
@end example
This pragma is used to set the checking policy for assertions (specified
-by aspects or pragmas), the @cite{Debug} pragma, or additional checks
-to be checked using the @cite{Check} pragma. It may appear either as
+by aspects or pragmas), the @code{Debug} pragma, or additional checks
+to be checked using the @code{Check} pragma. It may appear either as
a configuration pragma, or within a declarative part of package. In the
latter case, it applies from the point where it appears to the end of
-the declarative region (like pragma @cite{Suppress}).
+the declarative region (like pragma @code{Suppress}).
-The @cite{Check_Policy} pragma is similar to the
-predefined @cite{Assertion_Policy} pragma,
+The @code{Check_Policy} pragma is similar to the
+predefined @code{Assertion_Policy} pragma,
and if the check kind corresponds to one of the assertion kinds that
-are allowed by @cite{Assertion_Policy}, then the effect is identical.
+are allowed by @code{Assertion_Policy}, then the effect is identical.
If the first argument is Debug, then the policy applies to Debug pragmas,
-disabling their effect if the policy is @cite{OFF}, @cite{DISABLE}, or
-@cite{IGNORE}, and allowing them to execute with normal semantics if
-the policy is @cite{ON} or @cite{CHECK}. In addition if the policy is
-@cite{DISABLE}, then the procedure call in @cite{Debug} pragmas will
+disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or
+@code{IGNORE}, and allowing them to execute with normal semantics if
+the policy is @code{ON} or @code{CHECK}. In addition if the policy is
+@code{DISABLE}, then the procedure call in @code{Debug} pragmas will
be totally ignored and not analyzed semantically.
Finally the first argument may be some other identifier than the above
possibilities, in which case it controls a set of named assertions
-that can be checked using pragma @cite{Check}. For example, if the pragma:
+that can be checked using pragma @code{Check}. For example, if the pragma:
@example
pragma Check_Policy (Critical_Error, OFF);
@end example
-is given, then subsequent @cite{Check} pragmas whose first argument is also
-@cite{Critical_Error} will be disabled.
+is given, then subsequent @code{Check} pragmas whose first argument is also
+@code{Critical_Error} will be disabled.
-The check policy is @cite{OFF} to turn off corresponding checks, and @cite{ON}
+The check policy is @code{OFF} to turn off corresponding checks, and @code{ON}
to turn on corresponding checks. The default for a set of checks for which no
-@cite{Check_Policy} is given is @cite{OFF} unless the compiler switch
+@code{Check_Policy} is given is @code{OFF} unless the compiler switch
@emph{-gnata} is given, which turns on all checks by default.
-The check policy settings @cite{CHECK} and @cite{IGNORE} are recognized
-as synonyms for @cite{ON} and @cite{OFF}. These synonyms are provided for
-compatibility with the standard @cite{Assertion_Policy} pragma. The check
-policy setting @cite{DISABLE} causes the second argument of a corresponding
-@cite{Check} pragma to be completely ignored and not analyzed.
+The check policy settings @code{CHECK} and @code{IGNORE} are recognized
+as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for
+compatibility with the standard @code{Assertion_Policy} pragma. The check
+policy setting @code{DISABLE} causes the second argument of a corresponding
+@code{Check} pragma to be completely ignored and not analyzed.
@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{36}
pragma Comment (static_string_EXPRESSION);
@end example
-This is almost identical in effect to pragma @cite{Ident}. It allows the
+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 @cite{Comment}, unlike @cite{Ident}, has
+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.
@end example
This pragma enables the shared use of variables stored in overlaid
-linker areas corresponding to the use of @cite{COMMON}
+linker areas corresponding to the use of @code{COMMON}
in Fortran. The single
-object @cite{LOCAL_NAME} is assigned to the area designated by
-the @cite{External} argument.
+object @code{LOCAL_NAME} is assigned to the area designated by
+the @code{External} argument.
You may define a record to correspond to a series
-of fields. The @cite{Size} argument
+of fields. The @code{Size} argument
is syntax checked in GNAT, but otherwise ignored.
-@cite{Common_Object} is not supported on all platforms. If no
+@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.
([Entity =>] LOCAL_NAME);
@end example
-The @cite{Entity} argument must be the name of a record type which has
+The @code{Entity} argument must be the name of a record type which has
two fields of the same floating-point type. The effect of this pragma is
to force gcc to use the special internal complex representation form for
this record, which may be more efficient. Note that this may result in
@end example
Specifies the alignment of components in array or record types.
-The meaning of the @cite{Form} argument is as follows:
+The meaning of the @code{Form} argument is as follows:
@quotation
Specifies that array or record components are byte aligned, i.e.,
aligned on boundaries determined by the value of the constant
-@cite{System.Storage_Unit}.
+@code{System.Storage_Unit}.
@geindex Default (in pragma Component_Alignment)
Specifies that array or record components are aligned on default
boundaries, appropriate to the underlying hardware or operating system or
-both. The @cite{Default} choice is the same as @cite{Component_Size} (natural
+both. The @code{Default} choice is the same as @code{Component_Size} (natural
alignment).
@end table
-If the @cite{Name} parameter is present, @cite{type_LOCAL_NAME} must
+If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must
refer to a local record or array type, and the specified alignment
choice applies to the specified type. The use of
-@cite{Component_Alignment} together with a pragma @cite{Pack} causes the
-@cite{Component_Alignment} pragma to be ignored. The use of
-@cite{Component_Alignment} together with a record representation clause
+@code{Component_Alignment} together with a pragma @code{Pack} causes the
+@code{Component_Alignment} pragma to be ignored. The use of
+@code{Component_Alignment} together with a record representation clause
is only effective for fields not specified by the representation clause.
-If the @cite{Name} parameter is absent, the pragma can be used as either
+If the @code{Name} parameter is absent, the pragma can be used as either
a configuration pragma, in which case it applies to one or more units in
accordance with the normal rules for configuration pragmas, or it can be
used within a declarative part, in which case it applies to types that
representation.
If the alignment for a record or array type is not specified (using
-pragma @cite{Pack}, pragma @cite{Component_Alignment}, or a record rep
+pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
clause), the GNAT uses the default alignment as described previously.
@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas
@end example
For the semantics of this pragma, see the entry for aspect
-@cite{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1.
+@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1.
@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{42}
CONSEQUENCE ::= boolean_EXPRESSION
@end example
-The @cite{Contract_Cases} pragma allows defining fine-grain specifications
+The @code{Contract_Cases} pragma allows defining fine-grain specifications
that can complement or replace the contract given by a precondition and a
-postcondition. Additionally, the @cite{Contract_Cases} pragma can be used
+postcondition. Additionally, the @code{Contract_Cases} pragma can be used
by testing and formal verification tools. The compiler checks its validity and,
depending on the assertion policy at the point of declaration of the pragma,
it may insert a check in the executable. For code generation, the contract
the corrresponding consequence is True on exit. Other consequence expressions
are not evaluated.
-A precondition @cite{P} and postcondition @cite{Q} can also be
+A precondition @code{P} and postcondition @code{Q} can also be
expressed as contract cases:
@example
pragma Contract_Cases (P => Q);
@end example
-The placement and visibility rules for @cite{Contract_Cases} pragmas are
+The placement and visibility rules for @code{Contract_Cases} pragmas are
identical to those described for preconditions and postconditions.
The compiler checks that boolean expressions given in conditions and
consequences are valid, where the rules for conditions are the same as
-the rule for an expression in @cite{Precondition} and the rules for
+the rule for an expression in @code{Precondition} and the rules for
consequences are the same as the rule for an expression in
-@cite{Postcondition}. In particular, attributes @cite{'Old} and
-@cite{'Result} can only be used within consequence expressions.
-The condition for the last contract case may be @cite{others}, to denote
+@code{Postcondition}. In particular, attributes @code{'Old} and
+@code{'Result} can only be used within consequence expressions.
+The condition for the last contract case may be @code{others}, to denote
any case not captured by the previous cases. The
following is an example of use within a package spec:
@end example
This pragma provides a mechanism for supplying synonyms for existing
-convention identifiers. The @cite{Name} identifier can subsequently
+convention identifiers. The @code{Name} identifier can subsequently
be used as a synonym for the given convention in other pragmas (including
-for example pragma @cite{Import} or another @cite{Convention_Identifier}
+for example pragma @code{Import} or another @code{Convention_Identifier}
pragma). As an example of the use of this, suppose you had legacy code
which used Fortran77 as the identifier for Fortran. Then the pragma:
pragma Convention_Identifier (Fortran77, Fortran);
@end example
-would allow the use of the convention identifier @cite{Fortran77} in
+would allow the use of the convention identifier @code{Fortran77} in
subsequent code, avoiding the need to modify the sources. As another
example, you could use this to parameterize convention requirements
-according to systems. Suppose you needed to use @cite{Stdcall} on
-windows systems, and @cite{C} on some other system, then you could
-define a convention identifier @cite{Library} and use a single
-@cite{Convention_Identifier} pragma to specify which convention
+according to systems. Suppose you needed to use @code{Stdcall} on
+windows systems, and @code{C} on some other system, then you could
+define a convention identifier @code{Library} and use a single
+@code{Convention_Identifier} pragma to specify which convention
would be used system-wide.
@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas
that C++ would lay out the type. If the C++ class has virtual primitives
then the record must be declared as a tagged record type.
-Types for which @cite{CPP_Class} is specified do not have assignment or
+Types for which @code{CPP_Class} is specified do not have assignment or
equality operators defined (such operations can be imported or declared
as subprograms as required). Initialization is allowed only by constructor
-functions (see pragma @cite{CPP_Constructor}). Such types are implicitly
+functions (see pragma @code{CPP_Constructor}). Such types are implicitly
limited if not explicitly declared as limited or derived from a limited
type, and an error is issued in that case.
See @ref{45,,Interfacing to C++} for related information.
-Note: Pragma @cite{CPP_Class} is currently obsolete. It is supported
+Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
for backward compatibility but its functionality is available
-using pragma @cite{Import} with @cite{Convention} = @cite{CPP}.
+using pragma @code{Import} with @code{Convention} = @code{CPP}.
@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{46}
@end example
This pragma identifies an imported function (imported in the usual way
-with pragma @cite{Import}) as corresponding to a C++ constructor. If
-@cite{External_Name} and @cite{Link_Name} are not specified then the
-@cite{Entity} argument is a name that must have been previously mentioned
-in a pragma @cite{Import} with @cite{Convention} = @cite{CPP}. Such name
+with pragma @code{Import}) as corresponding to a C++ constructor. If
+@code{External_Name} and @code{Link_Name} are not specified then the
+@code{Entity} argument is a name that must have been previously mentioned
+in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
must be of one of the following forms:
@itemize *
@item
-@strong{function} @cite{Fname} @strong{return} T`
+@strong{function} @code{Fname} @strong{return} T`
@item
-@strong{function} @cite{Fname} @strong{return} T'Class
+@strong{function} @code{Fname} @strong{return} T'Class
@item
-@strong{function} @cite{Fname} (...) @strong{return} T`
+@strong{function} @code{Fname} (...) @strong{return} T`
@item
-@strong{function} @cite{Fname} (...) @strong{return} T'Class
+@strong{function} @code{Fname} (...) @strong{return} T'Class
@end itemize
-where @cite{T} is a limited record type imported from C++ with pragma
-@cite{Import} and @cite{Convention} = @cite{CPP}.
+where @code{T} is a limited record type imported from C++ with pragma
+@code{Import} and @code{Convention} = @code{CPP}.
The first two forms import the default constructor, used when an object
-of type @cite{T} is created on the Ada side with no explicit constructor.
+of type @code{T} is created on the Ada side with no explicit constructor.
The latter two forms cover all the non-default constructors of the type.
See the GNAT User's Guide for details.
If no constructors are imported, it is impossible to create any objects
on the Ada side and the type is implicitly declared abstract.
-Pragma @cite{CPP_Constructor} is intended primarily for automatic generation
-using an automatic binding generator tool (such as the @cite{-fdump-ada-spec}
+Pragma @code{CPP_Constructor} is intended primarily for automatic generation
+using an automatic binding generator tool (such as the @code{-fdump-ada-spec}
GCC switch).
See @ref{45,,Interfacing to C++} for more related information.
@end example
For the semantics of this pragma, see the entry for aspect
-@cite{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3.
+@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3.
@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4d}
to False, this pragma has no effect. If debug pragmas are enabled, the
semantics of the pragma is exactly equivalent to the procedure call statement
corresponding to the argument with a terminating semicolon. Pragmas are
-permitted in sequences of declarations, so you can use pragma @cite{Debug} to
+permitted in sequences of declarations, so you can use pragma @code{Debug} to
intersperse calls to debug procedures in the middle of declarations. Debug
pragmas can be enabled either by use of the command line switch @emph{-gnata}
-or by use of the pragma @cite{Check_Policy} with a first argument of
-@cite{Debug}.
+or by use of the pragma @code{Check_Policy} with a first argument of
+@code{Debug}.
@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{4e}
pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF);
@end example
-This pragma is equivalent to a corresponding @cite{Check_Policy} pragma
-with a first argument of @cite{Debug}. It is retained for historical
+This pragma is equivalent to a corresponding @code{Check_Policy} pragma
+with a first argument of @code{Debug}. It is retained for historical
compatibility reasons.
@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas
pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First);
@end example
-Normally if no explicit @cite{Scalar_Storage_Order} is given for a record
+Normally if no explicit @code{Scalar_Storage_Order} is given for a record
type or array type, then the scalar storage order defaults to the ordinary
default for the target. But this default may be overridden using this pragma.
The pragma may appear as a configuration pragma, or locally within a package
end DSSO1;
@end example
-In this example record types L.. have @cite{Low_Order_First} scalar
-storage order, and record types H.. have @cite{High_Order_First}.
-Note that in the case of @cite{H4a}, the order is not inherited
-from the parent type. Only an explicitly set @cite{Scalar_Storage_Order}
+In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar
+storage order, and record types with names starting with @emph{H} have @code{High_Order_First}.
+Note that in the case of @code{H4a}, the order is not inherited
+from the parent type. Only an explicitly set @code{Scalar_Storage_Order}
gets inherited on type derivation.
If this pragma is used as a configuration pragma which appears within a
where FUNCTION_RESULT is a function Result attribute_reference
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Depends} in the
+For the semantics of this pragma, see the entry for aspect @code{Depends} in the
SPARK 2014 Reference Manual, section 6.1.5.
@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas
required.
The placement and scope rules for this pragma are the same as those
-for @cite{pragma Suppress}. In particular it can be used as a
+for @code{pragma Suppress}. In particular it can be used as a
configuration pragma, or in a declaration sequence where it applies
-till the end of the scope. If an @cite{Entity} argument is present,
+till the end of the scope. If an @code{Entity} argument is present,
the action applies only to that entity.
@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas
pragma Effective_Reads [ (boolean_EXPRESSION) ];
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Effective_Reads} in
+For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in
the SPARK 2014 Reference Manual, section 7.1.2.
@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas
pragma Effective_Writes [ (boolean_EXPRESSION) ];
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Effective_Writes}
+For the semantics of this pragma, see the entry for aspect @code{Effective_Writes}
in the SPARK 2014 Reference Manual, section 7.1.2.
@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas
This is a configuration pragma that provides control over the
elaboration model used by the compilation affected by the
-pragma. If the parameter is @cite{Dynamic},
+pragma. If the parameter is @code{Dynamic},
then the dynamic elaboration
model described in the Ada Reference Manual is used, as though
the @emph{-gnatE} switch had been specified on the command
-line. If the parameter is @cite{Static}, then the default GNAT static
+line. If the parameter is @code{Static}, then the default GNAT static
model is used. This configuration pragma overrides the setting
of the command line. For full details on the elaboration models
used by the GNAT compiler, see the chapter on elaboration order handling
Syntax:
@example
-pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR,
- [Source_Location =>] STRING_LITERAL);
+pragma Eliminate (
+ [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT ,
+ [ Entity => ] IDENTIFIER |
+ SELECTED_COMPONENT |
+ STRING_LITERAL
+ [, Source_Location => SOURCE_TRACE ] );
+
+ SOURCE_TRACE ::= STRING_LITERAL
@end example
-The string literal given for the source location is a string which
-specifies the line number of the occurrence of the entity, using
-the syntax for SOURCE_TRACE given below:
+This pragma indicates that the given entity is not used in the program to be
+compiled and built, thus allowing the compiler to
+eliminate the code or data associated with the named entity. Any reference to
+an eliminated entity causes a compile-time or link-time error.
-@example
-SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET]
+The pragma has the following semantics, where @code{U} is the unit specified by
+the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity}
+argument:
-LBRACKET ::= [
-RBRACKET ::= ]
-SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
+@itemize *
-LINE_NUMBER ::= DIGIT @{DIGIT@}
-@end example
+@item
+@code{E} must be a subprogram that is explicitly declared either:
-Spaces around the colon in a @cite{Source_Reference} are optional.
-
-The @cite{DEFINING_DESIGNATOR} matches the defining designator used in an
-explicit subprogram declaration, where the @cite{entity} name in this
-designator appears on the source line specified by the source location.
-
-The source trace that is given as the @cite{Source_Location} shall obey the
-following rules. The @cite{FILE_NAME} is the short name (with no directory
-information) of an Ada source file, given using exactly the required syntax
-for the underlying file system (e.g. case is important if the underlying
-operating system is case sensitive). @cite{LINE_NUMBER} gives the line
-number of the occurrence of the @cite{entity}
-as a decimal literal without an exponent or point. If an @cite{entity} is not
-declared in a generic instantiation (this includes generic subprogram
-instances), the source trace includes only one source reference. If an entity
-is declared inside a generic instantiation, its source trace (when parsing
-from left to right) starts with the source location of the declaration of the
-entity in the generic unit and ends with the source location of the
-instantiation (it is given in square brackets). This approach is recursively
-used in case of nested instantiations: the rightmost (nested most deeply in
-square brackets) element of the source trace is the location of the outermost
-instantiation, the next to left element is the location of the next (first
-nested) instantiation in the code of the corresponding generic unit, and so
-on, and the leftmost element (that is out of any square brackets) is the
-location of the declaration of the entity to eliminate in a generic unit.
-
-Note that the @cite{Source_Location} argument specifies which of a set of
-similarly named entities is being eliminated, dealing both with overloading,
-and also appearance of the same entity name in different scopes.
+o Within @code{U}, or
-This pragma indicates that the given entity is not used in the program to be
-compiled and built. 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 causes a compile-time or link-time error.
+o Within a generic package that is instantiated in @code{U}, or
+
+o As an instance of generic subprogram instantiated in @code{U}.
+
+Otherwise the pragma is ignored.
-The intention of pragma @cite{Eliminate} is to allow a program to be compiled
-in a system-independent manner, with unused entities eliminated, without
+@item
+If @code{E} is overloaded within @code{U} then, in the absence of a
+@code{Source_Location} argument, all overloadings are eliminated.
+
+@item
+If @code{E} is overloaded within @code{U} and only some overloadings
+are to be eliminated, then each overloading to be eliminated
+must be specified in a corresponding pragma @code{Eliminate}
+with a @code{Source_Location} argument identifying the line where the
+declaration appears, as described below.
+
+@item
+If @code{E} is declared as the result of a generic instantiation, then
+a @code{Source_Location} argument is needed, as described below
+@end itemize
+
+Pragma @code{Eliminate} allows a program to be compiled in a system-independent
+manner, so that unused entities are eliminated but without
needing to modify the source text. Normally the required set of
-@cite{Eliminate} pragmas is constructed automatically using the gnatelim tool.
+@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool.
Any source file change that removes, splits, or
-adds lines may make the set of Eliminate pragmas invalid because their
-@cite{Source_Location} argument values may get out of date.
+adds lines may make the set of @code{Eliminate} pragmas invalid because their
+@code{Source_Location} argument values may get out of date.
-Pragma @cite{Eliminate} may be used where the referenced entity is a dispatching
+Pragma @code{Eliminate} may be used where the referenced entity is a dispatching
operation. In this case all the subprograms to which the given operation can
dispatch are considered to be unused (are never called as a result of a direct
or a dispatching call).
+The string literal given for the source location specifies the line number
+of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}:
+
+@example
+SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ]
+
+LBRACKET ::= '['
+RBRACKET ::= ']'
+
+SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
+
+LINE_NUMBER ::= DIGIT @{DIGIT@}
+@end example
+
+Spaces around the colon in a @code{SOURCE_REFERENCE} are optional.
+
+The source trace that is given as the @code{Source_Location} must obey the
+following rules (or else the pragma is ignored), where @code{U} is
+the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the
+subprogram specified by the @code{Entity} argument:
+
+
+@itemize *
+
+@item
+@code{FILE_NAME} is the short name (with no directory
+information) of the Ada source file for @code{U}, using the required syntax
+for the underlying file system (e.g. case is significant if the underlying
+operating system is case sensitive).
+If @code{U} is a package and @code{E} is a subprogram declared in the package
+specification and its full declaration appears in the package body,
+then the relevant source file is the one for the package specification;
+analogously if @code{U} is a generic package.
+
+@item
+If @code{E} is not declared in a generic instantiation (this includes
+generic subprogram instances), the source trace includes only one source
+line reference. @code{LINE_NUMBER} gives the line number of the occurrence
+of the declaration of @code{E} within the source file (as a decimal literal
+without an exponent or point).
+
+@item
+If @code{E} is declared by a generic instantiation, its source trace
+(from left to right) starts with the source location of the
+declaration of @code{E} in the generic unit and ends with the source
+location of the instantiation, given in square brackets. This approach is
+applied recursively with nested instantiations: the rightmost (nested
+most deeply in square brackets) element of the source trace is the location
+of the outermost instantiation, and the leftmost element (that is, outside
+of any square brackets) is the location of the declaration of @code{E} in
+the generic unit.
+@end itemize
+
+Examples:
+
+@quotation
+
+@example
+pragma Eliminate (Pkg0, Proc);
+-- Eliminate (all overloadings of) Proc in Pkg0
+
+pragma Eliminate (Pkg1, Proc,
+ Source_Location => "pkg1.ads:8");
+-- Eliminate overloading of Proc at line 8 in pkg1.ads
+
+-- Assume the following file contents:
+-- gen_pkg.ads
+-- 1: generic
+-- 2: type T is private;
+-- 3: package Gen_Pkg is
+-- 4: procedure Proc(N : T);
+-- ... ...
+-- ... end Gen_Pkg;
+--
+-- q.adb
+-- 1: with Gen_Pkg;
+-- 2: procedure Q is
+-- 3: package Inst_Pkg is new Gen_Pkg(Integer);
+-- ... -- No calls on Inst_Pkg.Proc
+-- ... end Q;
+
+-- The following pragma eliminates Inst_Pkg.Proc from Q
+pragma Eliminate (Q, Proc,
+ Source_Location => "gen_pkg.ads:4[q.adb:3]");
+@end example
+@end quotation
+
@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5c}
@section Pragma Enable_Atomic_Synchronization
Particularly in the case of multi-processors this may require special
handling, e.g. the generation of memory barriers. This synchronization
is performed by default, but can be turned off using
-@cite{pragma Disable_Atomic_Synchronization}. The
-@cite{Enable_Atomic_Synchronization} pragma can be used to turn
+@code{pragma Disable_Atomic_Synchronization}. The
+@code{Enable_Atomic_Synchronization} pragma can be used to turn
it back on.
The placement and scope rules for this pragma are the same as those
-for @cite{pragma Unsuppress}. In particular it can be used as a
+for @code{pragma Unsuppress}. In particular it can be used as a
configuration pragma, or in a declaration sequence where it applies
-till the end of the scope. If an @cite{Entity} argument is present,
+till the end of the scope. If an @code{Entity} argument is present,
the action applies only to that entity.
@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas
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
-@cite{Export}, which must precede the pragma @cite{Export_Function}.
-GNAT does not require a separate pragma @cite{Export}, but if none is
-present, @cite{Convention Ada} is assumed, which is usually
+@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 @cite{Export} or @cite{Convention}
+pragma in conjunction with a @code{Export} or @code{Convention}
pragma that specifies the desired foreign convention.
-Pragma @cite{Export_Function}
-(and @cite{Export}, if present) must appear in the same declarative
+Pragma @code{Export_Function}
+(and @code{Export}, if present) must appear in the same declarative
region as the function to which they apply.
-@cite{internal_name} must uniquely designate the function to which the
+The @code{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 @cite{Parameter_Types} and
-@cite{Result_Type} parameters is mandatory to achieve the required
-unique designation. @cite{subtype_mark`s in these parameters must exactly match the subtypes in the corresponding function specification@comma{} using positional notation to match parameters with subtype marks. The form with an `'Access} attribute can be used to match an
+the declarative part you must use the @code{Parameter_Types} and
+@code{Result_Type} parameters to achieve the required
+unique designation. The @cite{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.
@geindex Suppressing external name
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 @cite{Export} pragma applied to an object. You may use a
+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. @cite{Size} is syntax checked,
+of portability), but it is not required. @code{Size} is syntax checked,
but otherwise ignored by GNAT.
@node Pragma Export_Procedure,Pragma Export_Value,Pragma Export_Object,Implementation Defined Pragmas
MECHANISM_NAME ::= Value | Reference
@end example
-This pragma is identical to @cite{Export_Function} except that it
+This pragma is identical to @code{Export_Function} except that it
applies to a procedure rather than a function and the parameters
-@cite{Result_Type} and @cite{Result_Mechanism} are not permitted.
-GNAT does not require a separate pragma @cite{Export}, but if none is
-present, @cite{Convention Ada} is assumed, which is usually
+@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 @cite{Export} or @cite{Convention}
+pragma in conjunction with a @code{Export} or @code{Convention}
pragma that specifies the desired foreign convention.
@geindex Suppressing external name
MECHANISM_NAME ::= Value | Reference
@end example
-This pragma is identical to @cite{Export_Procedure} except that the
-first parameter of @cite{LOCAL_NAME}, which must be present, must be of
-mode @cite{OUT}, and externally the subprogram is treated as a function
+This pragma is identical to @code{Export_Procedure} except that the
+first parameter of @code{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 @cite{OUT} and @cite{IN OUT}
+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 @cite{Export}, but if none is
-present, @cite{Convention Ada} is assumed, which is almost certainly
+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 @cite{Export} or @cite{Convention}
+pragma in conjunction with a @code{Export} or @code{Convention}
pragma that specifies the desired foreign convention.
@geindex Suppressing external name
@end example
This pragma is used to provide backwards compatibility with other
-implementations that extend the facilities of package @cite{System}. In
-GNAT, @cite{System} contains only the definitions that are present in
+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 @cite{System}.
+implementation, provide many extensions to package @code{System}.
For each such implementation accommodated by this pragma, GNAT provides a
-package @cite{Aux_`xxx`}, e.g., @cite{Aux_DEC} for the DEC Ada 83
+package @code{Aux_@emph{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 @cite{with} it in the normal
-way and access entities either by selection or using a @cite{use}
+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
-@cite{System.`xxx`} where @cite{xxx} is an entity in the extended
-definitions provided in package @cite{System}, you may use this pragma
-to extend visibility in @cite{System} in a non-standard way that
+@code{System.@emph{xxx}} where @emph{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
-@cite{Extend_System} is a configuration pragma whose single argument is
+@code{Extend_System} is a configuration pragma whose single argument is
the name of the package containing the extended definition
-(e.g., @cite{Aux_DEC} for the DEC Ada case). A unit compiled under
+(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 @cite{System.Aux_`xxx`} where
-@cite{Aux_`xxx`} is the pragma argument for any entity referenced in
-package @cite{System}, but not found in package @cite{System}.
+processing that looks in package @code{System.Aux_@emph{xxx}} where
+@code{Aux_@emph{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 @cite{System}
-extension supplied with the compiler, for example @cite{Aux_DEC} or
+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 following the above
-definition. Note that such a package is a child of @cite{System}
+definition. Note that such a package is a child of @code{System}
and thus is considered part of the implementation.
To compile it you will have to use the @emph{-gnatg} switch
for compiling System units, as explained in the
@item @emph{Constrained attribute for generic objects}
-The @cite{Constrained} attribute is permitted for objects of
+The @code{Constrained} attribute is permitted for objects of
generic types. The result indicates if the corresponding actual
is constrained.
@end table
pragma Extensions_Visible [ (boolean_EXPRESSION) ];
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Extensions_Visible}
+For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible}
in the SPARK 2014 Reference Manual, section 6.1.7.
@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas
@end example
This pragma is identical in syntax and semantics to pragma
-@cite{Export} as defined in the Ada Reference Manual. It is
+@code{Export} as defined in the Ada Reference Manual. It is
provided for compatibility with some Ada 83 compilers that
used this pragma for exactly the same purposes as pragma
-@cite{Export} before the latter was standardized.
+@code{Export} before the latter was standardized.
@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{67}
casing of the external name, and so a convention is needed. In GNAT the
default treatment is that such names are converted to all lower case
letters. This corresponds to the normal C style in many environments.
-The first argument of pragma @cite{External_Name_Casing} can be used to
-control this treatment. If @cite{Uppercase} is specified, then the name
-will be forced to all uppercase letters. If @cite{Lowercase} is specified,
+The first argument of pragma @code{External_Name_Casing} can be used to
+control this treatment. If @code{Uppercase} is specified, then the name
+will be forced to all uppercase letters. If @code{Lowercase} is specified,
then the normal default of all lower case letters will be used.
This same implicit treatment is also used in the case of extended DEC Ada 83
In this case, the string literal normally provides the exact casing required
for the external name. The second argument of pragma
-@cite{External_Name_Casing} may be used to modify this behavior.
-If @cite{Uppercase} is specified, then the name
-will be forced to all uppercase letters. If @cite{Lowercase} is specified,
+@code{External_Name_Casing} may be used to modify this behavior.
+If @code{Uppercase} is specified, then the name
+will be forced to all uppercase letters. If @code{Lowercase} is specified,
then the name will be forced to all lowercase letters. A specification of
-@cite{As_Is} provides the normal default behavior in which the casing is
+@code{As_Is} provides the normal default behavior in which the casing is
taken from the string provided.
@end itemize
overflows for numbers near the end of the range. The Ada standard requires that
this situation be detected and corrected by scaling, but in Fast_Math mode such
cases will simply result in overflow. Note that to take advantage of this you
-must instantiate your own version of @cite{Ada.Numerics.Generic_Complex_Types}
+must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types}
under control of the pragma, rather than use the preinstantiated versions.
@end table
pragma Favor_Top_Level (type_NAME);
@end example
-The argument of pragma @cite{Favor_Top_Level} must be a named access-to-subprogram
+The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram
type. This pragma is an efficiency hint to the compiler, regarding the use of
-@cite{'Access} or @cite{'Unrestricted_Access} on nested (non-library-level) subprograms.
+@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms.
The pragma means that nested subprograms are not used with this type, or are
rare, so that the generated code should be efficient in the top-level case.
When this pragma is used, dynamically generated trampolines may be used on some
-targets for nested subprograms. See restriction @cite{No_Implicit_Dynamic_Code}.
+targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}.
@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6b}
pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
@end example
-The argument of pragma @cite{Finalize_Storage_Only} must denote a local type which
-is derived from @cite{Ada.Finalization.Controlled} or @cite{Limited_Controlled}. The
-pragma suppresses the call to @cite{Finalize} for declared library-level objects
+The argument of pragma @code{Finalize_Storage_Only} must denote a local type which
+is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The
+pragma suppresses the call to @code{Finalize} for declared library-level objects
of the argument type. This is mostly useful for types where finalization is
only used to deal with storage reclamation since in most environments it is
not necessary to reclaim memory just before terminating execution, hence the
name. Note that this pragma does not suppress Finalize calls for library-level
-heap-allocated objects (see pragma @cite{No_Heap_Finalization}).
+heap-allocated objects (see pragma @code{No_Heap_Finalization}).
@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6c}
In the one argument form, this pragma is a configuration pragma which
allows control over the internal representation chosen for the predefined
-floating point types declared in the packages @cite{Standard} and
-@cite{System}. This pragma is only provided for compatibility and has no effect.
+floating point types declared in the packages @code{Standard} and
+@code{System}. This pragma is only provided for compatibility and has no effect.
The two argument form specifies the representation to be used for
the specified floating-point type. The argument must
-be @cite{IEEE_Float} to specify the use of IEEE format, as follows:
+be @code{IEEE_Float} to specify the use of IEEE format, as follows:
@itemize *
pragma Ghost [ (boolean_EXPRESSION) ];
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Ghost} in the SPARK
+For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK
2014 Reference Manual, section 6.9.
@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas
GLOBAL_ITEM ::= NAME
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Global} in the
+For the semantics of this pragma, see the entry for aspect @code{Global} in the
SPARK 2014 Reference Manual, section 6.1.4.
@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas
pragma Ident (static_string_EXPRESSION);
@end example
-This pragma is identical in effect to pragma @cite{Comment}. It is provided
+This pragma is identical in effect to pragma @code{Comment}. It is provided
for compatibility with other Ada compilers providing this pragma.
@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas
use of a pragma whose pragma identifier matches this argument will be
silently ignored. This may be useful when legacy code or code intended
for compilation with some other compiler contains pragmas that match the
-name, but not the exact implementation, of a @cite{GNAT} pragma. The use of this
-pragma allows such pragmas to be ignored, which may be useful in @cite{CodePeer}
+name, but not the exact implementation, of a GNAT pragma. The use of this
+pragma allows such pragmas to be ignored, which may be useful in CodePeer
mode, or during porting of legacy code.
@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas
| Reference
@end example
-This pragma is used in conjunction with a pragma @cite{Import} to
+This pragma is used in conjunction with a pragma @code{Import} to
specify additional information for an imported function. The pragma
-@cite{Import} (or equivalent pragma @cite{Interface}) must precede the
-@cite{Import_Function} pragma and both must appear in the same
+@code{Import} (or equivalent pragma @code{Interface}) must precede the
+@code{Import_Function} pragma and both must appear in the same
declarative part as the function specification.
-The @cite{Internal} argument must uniquely designate
+The @code{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 @cite{Parameter_Types} and
-@cite{Result_Type} parameters to achieve the required unique
+the declarative part you must use the @code{Parameter_Types} and
+@code{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 @cite{'Access} attribute can be used to match an
+The form with an @code{'Access} attribute can be used to match an
anonymous access parameter.
-You may optionally use the @cite{Mechanism} and @cite{Result_Mechanism}
+You may optionally use the @code{Mechanism} and @code{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
This pragma designates an object as imported, and apart from the
extended rules for external symbols, is identical in effect to the use of
-the normal @cite{Import} pragma applied to an object. Unlike the
-subprogram case, you need not use a separate @cite{Import} pragma,
+the normal @code{Import} pragma applied to an object. Unlike the
+subprogram case, you need not use a separate @code{Import} pragma,
although you may do so (and probably should do so from a portability
-point of view). @cite{size} is syntax checked, but otherwise ignored by
+point of view). @code{size} is syntax checked, but otherwise ignored by
GNAT.
@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas
MECHANISM_NAME ::= Value | Reference
@end example
-This pragma is identical to @cite{Import_Function} except that it
+This pragma is identical to @code{Import_Function} except that it
applies to a procedure rather than a function and the parameters
-@cite{Result_Type} and @cite{Result_Mechanism} are not permitted.
+@code{Result_Type} and @code{Result_Mechanism} are not permitted.
@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{79}
MECHANISM_NAME ::= Value | Reference
@end example
-This pragma is identical to @cite{Import_Procedure} except that the
-first parameter of @cite{LOCAL_NAME}, which must be present, must be of
-mode @cite{OUT}, and externally the subprogram is treated as a function
+This pragma is identical to @code{Import_Procedure} except that the
+first parameter of @code{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. The purpose of this
-capability is to allow the use of @cite{OUT} and @cite{IN OUT}
+capability is to allow the use of @code{out} and @code{in out}
parameters in interfacing to external functions (which are not permitted
-in Ada functions). You may optionally use the @cite{Mechanism}
+in Ada functions). You may optionally use the @code{Mechanism}
parameters to specify passing mechanisms for the parameters.
If you specify a single mechanism name, it applies to all parameters.
Otherwise you may specify a mechanism on a parameter by parameter
pragma Initial_Condition (boolean_EXPRESSION);
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Initial_Condition}
+For the semantics of this pragma, see the entry for aspect @code{Initial_Condition}
in the SPARK 2014 Reference Manual, section 7.1.6.
@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas
pragma Initialize_Scalars;
@end example
-This pragma is similar to @cite{Normalize_Scalars} conceptually but has
+This pragma is similar to @code{Normalize_Scalars} conceptually but has
two important differences. First, there is no requirement for the pragma
to be used uniformly in all units of a partition, in particular, it is fine
to use this just for some or all of the application units of a partition,
the need to rebind with a different switch using an environment variable.
See the GNAT User's Guide for details.
-Note that pragma @cite{Initialize_Scalars} is particularly useful in
+Note that pragma @code{Initialize_Scalars} is particularly useful in
conjunction with the enhanced validity checking that is now provided
in GNAT, which checks for invalid values under more conditions.
Using this feature (see description of the @emph{-gnatV} flag in the
GNAT User's Guide) in conjunction with
-pragma @cite{Initialize_Scalars}
+pragma @code{Initialize_Scalars}
provides a powerful new tool to assist in the detection of problems
caused by uninitialized variables.
-Note: the use of @cite{Initialize_Scalars} has a fairly extensive
+Note: the use of @code{Initialize_Scalars} has a fairly extensive
effect on the generated code. This may cause your code to be
substantially larger. It may also cause an increase in the amount
of stack required, so it is probably a good idea to turn on stack
INPUT ::= name
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Initializes} in the
+For the semantics of this pragma, see the entry for aspect @code{Initializes} in the
SPARK 2014 Reference Manual, section 7.1.5.
@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas
pragma Inline_Always (NAME [, NAME]);
@end example
-Similar to pragma @cite{Inline} except that inlining is unconditional.
+Similar to pragma @code{Inline} except that inlining is unconditional.
Inline_Always instructs the compiler to inline every direct call to the
subprogram or else to emit a compilation error, independently of any
option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level.
-It is an error to take the address or access of @cite{NAME}. It is also an error to
+It is an error to take the address or access of @code{NAME}. It is also an error to
apply this pragma to a primitive operation of a tagged type. Thanks to such
-restrictions, the compiler is allowed to remove the out-of-line body of @cite{NAME}.
+restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}.
@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{83}
@end example
This pragma is provided for compatibility with Dec Ada 83. It has
-no effect in @cite{GNAT} (which always inlines generics), other
+no effect in GNAT (which always inlines generics), other
than to check that the given names are all names of generic units or
generic instances.
@end example
This pragma is identical in syntax and semantics to
-the standard Ada pragma @cite{Import}. It is provided for compatibility
+the standard Ada pragma @code{Import}. It is provided for compatibility
with Ada 83. The definition is upwards compatible both with pragma
-@cite{Interface} as defined in the Ada 83 Reference Manual, and also
+@code{Interface} as defined in the Ada 83 Reference Manual, and also
with some extended implementations of this pragma in certain Ada 83
-implementations. The only difference between pragma @cite{Interface}
-and pragma @cite{Import} is that there is special circuitry to allow
+implementations. The only difference between pragma @code{Interface}
+and pragma @code{Import} is that there is special circuitry to allow
both pragmas to appear for the same subprogram entity (normally it
-is illegal to have multiple @cite{Import} pragmas. This is useful in
+is illegal to have multiple @code{Import} pragmas. This is useful in
maintaining Ada 83/Ada 95 compatibility and is compatible with other
Ada 83 compilers.
This pragma provides an alternative way of specifying the interface name
for an interfaced subprogram, and is provided for compatibility with Ada
83 compilers that use the pragma for this purpose. You must provide at
-least one of @cite{External_Name} or @cite{Link_Name}.
+least one of @code{External_Name} or @code{Link_Name}.
@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{86}
that are declared at the library level (which includes procedures
declared at the top level of a library package). In the case of AAMP,
when this pragma is applied to a nonprotected procedure, the instruction
-@cite{IERET} is generated for returns from the procedure, enabling
+@code{IERET} is generated for returns from the procedure, enabling
maskable interrupts, in place of the normal return instruction.
@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas
Normally certain interrupts are reserved to the implementation. Any attempt
to attach an interrupt causes Program_Error to be raised, as described in
-RM C.3.2(22). A typical example is the @cite{SIGINT} interrupt used in
+RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is
reserved to the implementation, so that @code{Ctrl-C} can be used to
-interrupt execution. Additionally, signals such as @cite{SIGSEGV},
-@cite{SIGABRT}, @cite{SIGFPE} and @cite{SIGILL} are often mapped to specific
+interrupt execution. Additionally, signals such as @code{SIGSEGV},
+@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
Ada exceptions, or used to implement run-time functions such as the
-@cite{abort} statement and stack overflow checking.
+@code{abort} statement and stack overflow checking.
-Pragma @cite{Interrupt_State} provides a general mechanism for overriding
+Pragma @code{Interrupt_State} provides a general mechanism for overriding
such uses of interrupts. It subsumes the functionality of pragma
-@cite{Unreserve_All_Interrupts}. Pragma @cite{Interrupt_State} is not
+@code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
available on Windows or VMS. On all other platforms than VxWorks,
it applies to signals; on VxWorks, it applies to vectored hardware interrupts
and may be used to mark interrupts required by the board support package
some other action.
@end itemize
-These states are the allowed values of the @cite{State} parameter of the
-pragma. The @cite{Name} parameter is a value of the type
-@cite{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
-@cite{Ada.Interrupts.Names}.
+These states are the allowed values of the @code{State} parameter of the
+pragma. The @code{Name} parameter is a value of the type
+@code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
+@code{Ada.Interrupts.Names}.
This is a configuration pragma, and the binder will check that there
are no inconsistencies between different units in a partition in how a
Note that certain signals on many operating systems cannot be caught and
handled by applications. In such cases, the pragma is ignored. See the
-operating system documentation, or the value of the array @cite{Reserved}
-declared in the spec of package @cite{System.OS_Interface}.
+operating system documentation, or the value of the array @code{Reserved}
+declared in the spec of package @code{System.OS_Interface}.
Overriding the default state of signals used by the Ada runtime may interfere
with an application's runtime behavior in the cases of the synchronous signals,
-and in the case of the signal used to implement the @cite{abort} statement.
+and in the case of the signal used to implement the @code{abort} statement.
@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{88}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{89}
pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
@end example
-The @cite{LOCAL_NAME} argument
+The @code{LOCAL_NAME} argument
must refer to an enumeration first subtype
in the current declarative part. The effect is to retain the enumeration
-literal names for use by @cite{Image} and @cite{Value} even if a global
-@cite{Discard_Names} pragma applies. This is useful when you want to
+literal names for use by @code{Image} and @code{Value} even if a global
+@code{Discard_Names} pragma applies. This is useful when you want to
generally suppress enumeration literal names and for example you therefore
-use a @cite{Discard_Names} pragma in the @code{gnat.adc} file, but you
+use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you
want to retain the names for specific enumeration types.
@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas
This pragma is provided to allow automated checking for appropriate license
conditions with respect to the standard and modified GPL. A pragma
-@cite{License}, which is a configuration pragma that typically appears at
+@code{License}, which is a configuration pragma that typically appears at
the start of a source file or in a separate @code{gnat.adc} file, specifies
the licensing conditions of a unit as follows:
@item
GPL
This is used for a unit that is licensed under the unmodified GPL, and which
-therefore cannot be @cite{with}'ed by a restricted unit.
+therefore cannot be @code{with}ed by a restricted unit.
@item
Modified_GPL
This is used for a unit that is restricted in that it is not permitted to
depend on units that are licensed under the GPL. Typical examples are
proprietary code that is to be released under more restrictive license
-conditions. Note that restricted units are permitted to @cite{with} units
+conditions. Note that restricted units are permitted to @code{with} units
which are licensed under the modified GPL (this is the whole point of the
modified GPL).
@end itemize
-Normally a unit with no @cite{License} pragma is considered to have an
+Normally a unit with no @code{License} pragma is considered to have an
unknown license, and no checking is done. However, standard GNAT headers
are recognized, and license information is derived from them as follows.
These default actions means that a program with a restricted license pragma
will automatically get warnings if a GPL unit is inappropriately
-@cite{with}'ed. For example, the program:
+@code{with}ed. For example, the program:
@example
with Sem_Ch3;
end Secret_Stuff
@end example
-if compiled with pragma @cite{License} (@cite{Restricted}) in a
+if compiled with pragma @code{License} (@code{Restricted}) in a
@code{gnat.adc} file will generate the warning:
@example
3. procedure Secret_Stuff is
@end example
-Here we get a warning on @cite{Sem_Ch3} since it is part of the GNAT
+Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
compiler and is licensed under the
-GPL, but no warning for @cite{GNAT.Sockets} which is part of the GNAT
+GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
run time, and is therefore licensed under the modified GPL.
@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas
@end example
This pragma is provided for compatibility with certain Ada 83 compilers.
-It has exactly the same effect as pragma @cite{Linker_Options} except
+It has exactly the same effect as pragma @code{Linker_Options} except
that spaces occurring within one of the string expressions are treated
as separators. For example, in the following case:
pragma Link_With ("-labc -ldef");
@end example
-results in passing the strings @cite{-labc} and @cite{-ldef} as two
+results in passing the strings @code{-labc} and @code{-ldef} as two
separate arguments to the linker. In addition pragma Link_With allows
multiple arguments, with the same effect as successive pragmas.
[Target =>] static_string_EXPRESSION);
@end example
-@cite{LOCAL_NAME} must refer to an object that is declared at the library
+@code{LOCAL_NAME} must refer to an object that is declared at the library
level. This pragma establishes the given entity as a linker alias for the
-given target. It is equivalent to @cite{__attribute__((alias))} in GNU C
-and causes @cite{LOCAL_NAME} to be emitted as an alias for the symbol
-@cite{static_string_EXPRESSION} in the object file, that is to say no space
-is reserved for @cite{LOCAL_NAME} by the assembler and it will be resolved
-to the same address as @cite{static_string_EXPRESSION} by the linker.
+given target. It is equivalent to @code{__attribute__((alias))} in GNU C
+and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol
+@code{static_string_EXPRESSION} in the object file, that is to say no space
+is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved
+to the same address as @code{static_string_EXPRESSION} by the linker.
The actual linker name for the target must be used (e.g., the fully
encoded name with qualification in Ada, or the mangled name in C++),
-or it must be declared using the C convention with @cite{pragma Import}
-or @cite{pragma Export}.
+or it must be declared using the C convention with @code{pragma Import}
+or @code{pragma Export}.
Not all target machines support this pragma. On some of them it is accepted
-only if @cite{pragma Weak_External} has been applied to @cite{LOCAL_NAME}.
+only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}.
@example
-- Example of the use of pragma Linker_Alias
pragma Linker_Constructor (procedure_LOCAL_NAME);
@end example
-@cite{procedure_LOCAL_NAME} must refer to a parameterless procedure that
+@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that
is declared at the library level. A procedure to which this pragma is
applied will be treated as an initialization routine by the linker.
-It is equivalent to @cite{__attribute__((constructor))} in GNU C and
-causes @cite{procedure_LOCAL_NAME} to be invoked before the entry point
+It is equivalent to @code{__attribute__((constructor))} in GNU C and
+causes @code{procedure_LOCAL_NAME} to be invoked before the entry point
of the executable is called (or immediately after the shared library is
loaded if the procedure is linked in a shared library), in particular
before the Ada run-time environment is set up.
pragma Linker_Destructor (procedure_LOCAL_NAME);
@end example
-@cite{procedure_LOCAL_NAME} must refer to a parameterless procedure that
+@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that
is declared at the library level. A procedure to which this pragma is
applied will be treated as a finalization routine by the linker.
-It is equivalent to @cite{__attribute__((destructor))} in GNU C and
-causes @cite{procedure_LOCAL_NAME} to be invoked after the entry point
+It is equivalent to @code{__attribute__((destructor))} in GNU C and
+causes @code{procedure_LOCAL_NAME} to be invoked after the entry point
of the executable has exited (or immediately before the shared library
is unloaded if the procedure is linked in a shared library), in particular
after the Ada run-time environment is shut down.
-See @cite{pragma Linker_Constructor} for the set of restrictions that apply
+See @code{pragma Linker_Constructor} for the set of restrictions that apply
because of these specific contexts.
@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas
[Section =>] static_string_EXPRESSION);
@end example
-@cite{LOCAL_NAME} must refer to an object, type, or subprogram that is
+@code{LOCAL_NAME} must refer to an object, type, or subprogram that is
declared at the library level. This pragma specifies the name of the
linker section for the given entity. It is equivalent to
-@cite{__attribute__((section))} in GNU C and causes @cite{LOCAL_NAME} to
-be placed in the @cite{static_string_EXPRESSION} section of the
+@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to
+be placed in the @code{static_string_EXPRESSION} section of the
executable (assuming the linker doesn't rename the section).
GNAT also provides an implementation defined aspect of the same name.
In the case of specifying this aspect for a type, the effect is to
-specify the corresponding for all library level objects of the type which
-do not have an explicit linker section set. Note that this only applies to
-whole objects, not to components of composite objects.
+specify the corresponding section for all library-level objects of
+the type that do not have an explicit linker section set. Note that
+this only applies to whole objects, not to components of composite objects.
In the case of a subprogram, the linker section applies to all previously
declared matching overloaded subprograms in the current declarative part
The compiler normally places library-level entities in standard sections
depending on the class: procedures and functions generally go in the
-@cite{.text} section, initialized variables in the @cite{.data} section
-and uninitialized variables in the @cite{.bss} section.
+@code{.text} section, initialized variables in the @code{.data} section
+and uninitialized variables in the @code{.bss} section.
Other, special sections may exist on given target machines to map special
hardware, for example I/O ports or flash memory. This pragma is a means to
Some file formats do not support arbitrary sections so not all target
machines support this pragma. The use of this pragma may cause a program
execution to be erroneous if it is used to place an entity into an
-inappropriate section (e.g., a modified variable into the @cite{.text}
-section). See also @cite{pragma Persistent_BSS}.
+inappropriate section (e.g., a modified variable into the @code{.text}
+section). See also @code{pragma Persistent_BSS}.
@example
-- Example of the use of pragma Linker_Section
pragma Loop_Invariant ( boolean_EXPRESSION );
@end example
-The effect of this pragma is similar to that of pragma @cite{Assert},
-except that in an @cite{Assertion_Policy} pragma, the identifier
-@cite{Loop_Invariant} is used to control whether it is ignored or checked
+The effect of this pragma is similar to that of pragma @code{Assert},
+except that in an @code{Assertion_Policy} pragma, the identifier
+@code{Loop_Invariant} is used to control whether it is ignored or checked
(or disabled).
-@cite{Loop_Invariant} can only appear as one of the items in the sequence
+@code{Loop_Invariant} can only appear as one of the items in the sequence
of statements of a loop body, or nested inside block statements that
appear in the sequence of statements of a loop body.
The intention is that it be used to
time through the loop, and which can be used to show that the loop is
achieving its purpose.
-Multiple @cite{Loop_Invariant} and @cite{Loop_Variant} pragmas that
+Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
apply to the same loop should be grouped in the same sequence of
statements.
-To aid in writing such invariants, the special attribute @cite{Loop_Entry}
+To aid in writing such invariants, the special attribute @code{Loop_Entry}
may be used to refer to the value of an expression on entry to the loop. This
-attribute can only be used within the expression of a @cite{Loop_Invariant}
-pragma. For full details, see documentation of attribute @cite{Loop_Entry}.
+attribute can only be used within the expression of a @code{Loop_Invariant}
+pragma. For full details, see documentation of attribute @code{Loop_Entry}.
@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{95}
CHANGE_DIRECTION ::= Increases | Decreases
@end example
-@cite{Loop_Variant} can only appear as one of the items in the sequence
+@code{Loop_Variant} can only appear as one of the items in the sequence
of statements of a loop body, or nested inside block statements that
appear in the sequence of statements of a loop body.
It allows the specification of quantities which must always
@end example
specifies that each time through the loop either X increases, or X stays
-the same and Y decreases. A @cite{Loop_Variant} pragma ensures that the
+the same and Y decreases. A @code{Loop_Variant} pragma ensures that the
loop is making progress. It can be useful in helping to show informally
or prove formally that the loop always terminates.
-@cite{Loop_Variant} is an assertion whose effect can be controlled using
-an @cite{Assertion_Policy} with a check name of @cite{Loop_Variant}. The
-policy can be @cite{Check} to enable the loop variant check, @cite{Ignore}
+@code{Loop_Variant} is an assertion whose effect can be controlled using
+an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The
+policy can be @code{Check} to enable the loop variant check, @code{Ignore}
to ignore the check (in which case the pragma has no effect on the program),
-or @cite{Disable} in which case the pragma is not even checked for correct
+or @code{Disable} in which case the pragma is not even checked for correct
syntax.
-Multiple @cite{Loop_Invariant} and @cite{Loop_Variant} pragmas that
+Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
apply to the same loop should be grouped in the same sequence of
statements.
-The @cite{Loop_Entry} attribute may be used within the expressions of the
-@cite{Loop_Variant} pragma to refer to values on entry to the loop.
+The @code{Loop_Entry} attribute may be used within the expressions of the
+@code{Loop_Variant} pragma to refer to values on entry to the loop.
@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas
@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{97}
Machine-dependent attributes can be specified for types and/or
declarations. This pragma is semantically equivalent to
-@cite{__attribute__((`attribute_name}))` (if @cite{info} is not
-specified) or @cite{__attribute__((`attribute_name`(`info})))
-in GNU C, where @code{attribute_name} is recognized by the
-compiler middle-end or the @cite{TARGET_ATTRIBUTE_TABLE} machine
-specific macro. A string literal for the optional parameter @cite{info}
+@code{__attribute__((@emph{attribute_name}))} (if @code{info} is not
+specified) or @code{__attribute__((@emph{attribute_name(info})))}
+in GNU C, where @emph{attribute_name} is recognized by the
+compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine
+specific macro. A string literal for the optional parameter @code{info}
is transformed into an identifier, which may make this pragma unusable
for some attributes.
For further information see @cite{GNU Compiler Collection (GCC) Internals}.
no effect in GNAT, other than being syntax checked.
@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9a}
+@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9a}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9b}
@section Pragma Max_Queue_Length
positive integer as a parameter and must appear after the declaration
of an entry.
-@node Pragma No_Body,Pragma No_Elaboration_Code_All,Pragma Max_Queue_Length,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9b}
+@node Pragma No_Body,Pragma No_Component_Reordering,Pragma Max_Queue_Length,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9c}
@section Pragma No_Body
dummy body with a No_Body pragma ensures that there is no interference from
earlier versions of the package body.
-@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Body,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9c}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{9d}
+@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Body,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{9d}
+@section Pragma No_Component_Reordering
+
+
+Syntax:
+
+@example
+pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)];
+@end example
+
+@code{type_LOCAL_NAME} must refer to a record type declaration in the current
+declarative part. The effect is to preclude any reordering of components
+for the layout of the record, i.e. the record is laid out by the compiler
+in the order in which the components are declared textually. The form with
+no argument is a configuration pragma which applies to all record types
+declared in units to which the pragma applies and there is a requirement
+that this pragma be used consistently within a partition.
+
+@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas
+@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{9f}
@section Pragma No_Elaboration_Code_All
@end example
This is a program unit pragma (there is also an equivalent aspect of the
-same name) that establishes the restriction @cite{No_Elaboration_Code} for
+same name) that establishes the restriction @code{No_Elaboration_Code} for
the current unit and any extended main source units (body and subunits).
It also has the effect of enforcing a transitive application of this
aspect, so that if any unit is implicitly or explicitly with'ed by the
It may be applied to package or subprogram specs or their generic versions.
@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{9e}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a0}
@section Pragma No_Heap_Finalization
pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ];
@end example
-Pragma @cite{No_Heap_Finalization} may be used as a configuration pragma or as a
+Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a
type-specific pragma.
In its configuration form, the pragma must appear within a configuration file
such as gnat.adc, without an argument. The pragma suppresses the call to
-@cite{Finalize} for heap-allocated objects created through library-level named
+@code{Finalize} for heap-allocated objects created through library-level named
access-to-object types in cases where the designated type requires finalization
actions.
In its type-specific form, the argument of the pragma must denote a
library-level named access-to-object type. The pragma suppresses the call to
-@cite{Finalize} for heap-allocated objects created through the specific access type
+@code{Finalize} for heap-allocated objects created through the specific access type
in cases where the designated type requires finalization actions.
It is still possible to finalize such heap-allocated objects by explicitly
deallocating them.
A library-level named access-to-object type declared within a generic unit will
-lose its @cite{No_Heap_Finalization} pragma when the corresponding instance does not
+lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not
appear at the library level.
@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{9f}
+@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a2}
@section Pragma No_Inline
@end example
This pragma suppresses inlining for the callable entity or the instances of
-the generic subprogram designated by @cite{NAME}, including inlining that
-results from the use of pragma @cite{Inline}. This pragma is always active,
+the generic subprogram designated by @code{NAME}, including inlining that
+results from the use of pragma @code{Inline}. This pragma is always active,
in particular it is not subject to the use of option @emph{-gnatn} or
-@emph{-gnatN}. It is illegal to specify both pragma @cite{No_Inline} and
-pragma @cite{Inline_Always} for the same @cite{NAME}.
+@emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and
+pragma @code{Inline_Always} for the same @code{NAME}.
@node Pragma No_Return,Pragma No_Run_Time,Pragma No_Inline,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a0}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a3}
@section Pragma No_Return
pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
@end example
-Each @cite{procedure_LOCAL_NAME} argument must refer to one or more procedure
+Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure
declarations in the current declarative part. A procedure to which this
-pragma is applied may not contain any explicit @cite{return} statements.
+pragma is applied may not contain any explicit @code{return} statements.
In addition, if the procedure contains any implicit returns from falling
off the end of a statement sequence, then execution of that implicit
return will cause Program_Error to be raised.
pragma.
@node Pragma No_Run_Time,Pragma No_Strict_Aliasing,Pragma No_Return,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-run-time}@anchor{a1}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-run-time}@anchor{a4}
@section Pragma No_Run_Time
This is an obsolete configuration pragma that historically was used to
set up a runtime library with no object code. It is now used only for
internal testing. The pragma has been superseded by the reconfigurable
-runtime capability of @cite{GNAT}.
+runtime capability of GNAT.
@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Run_Time,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a2}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a5}
@section Pragma No_Strict_Aliasing
pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
@end example
-@cite{type_LOCAL_NAME} must refer to an access type
+@code{type_LOCAL_NAME} must refer to an access type
declaration in the current declarative part. The effect is to inhibit
strict aliasing optimization for the given type. The form with no
arguments is a configuration pragma which applies to all access types
This pragma currently has no effects on access to unconstrained array types.
@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{a3}@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{a4}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{a6}@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a7}
@section Pragma No_Tagged_Streams
Syntax:
@example
-pragma No_Tagged_Streams;
pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)];
@end example
of code which is wasted space if stream routines are not needed for the
type in question.
-The @cite{No_Tagged_Streams} pragma causes the generation of these stream
+The @code{No_Tagged_Streams} pragma causes the generation of these stream
routines to be skipped, and any attempt to use stream operations on
types subject to this pragma will be statically rejected as illegal.
dispatching versions of the stream routines).
@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{a5}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{a8}
@section Pragma Normalize_Scalars
@item @emph{Enumeration types}
Objects of an enumeration type are initialized to all one-bits, i.e., to
-the value @cite{2 ** typ'Size - 1} unless the subtype excludes the literal
+the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
whose Pos value is zero, in which case a code of zero is used. This choice
will always generate an invalid value if one exists.
@end table
@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{a6}@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a7}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{a9}@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{aa}
@section Pragma Obsolescent
The effect of this pragma is to output a warning message on a reference to
an entity thus marked that the subprogram is obsolescent if the appropriate
-warning option in the compiler is activated. If the Message parameter is
+warning option in the compiler is activated. If the @code{Message} parameter is
present, then a second warning message is given containing this text. In
addition, a reference to the entity is considered to be a violation of pragma
-Restrictions (No_Obsolescent_Features).
+@code{Restrictions (No_Obsolescent_Features)}.
This pragma can also be used as a program unit pragma for a package,
in which case the entity name is the name of the package, and the
pragma indicates that the entire package is considered
-obsolescent. In this case a client @cite{with}'ing such a package
-violates the restriction, and the @cite{with} statement is
+obsolescent. In this case a client @code{with}ing such a package
+violates the restriction, and the @code{with} clause is
flagged with warnings if the warning option is set.
-If the Version parameter is present (which must be exactly
-the identifier Ada_05, no other argument is allowed), then the
+If the @code{Version} parameter is present (which must be exactly
+the identifier @code{Ada_05}, no other argument is allowed), then the
indication of obsolescence applies only when compiling in Ada 2005
mode. This is primarily intended for dealing with the situations
in the predefined library where subprograms or packages
have become defined as obsolescent in Ada 2005
-(e.g., in Ada.Characters.Handling), but may be used anywhere.
+(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere.
The following examples show typical uses of this pragma:
Note that, as for all pragmas, if you use a pragma argument identifier,
then all subsequent parameters must also use a pragma argument identifier.
-So if you specify "Entity =>" for the Entity argument, and a Message
-argument is present, it must be preceded by "Message =>".
+So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message}
+argument is present, it must be preceded by @code{Message =>}.
@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{a8}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ab}
@section Pragma Optimize_Alignment
with a size of 8 bytes. This is a valid choice, since sizes of objects are
allowed to be bigger than the size of the type, but it can waste space if for
example fields of type R appear in an enclosing record. If the above type is
-compiled in @cite{Optimize_Alignment (Space)} mode, the alignment is set to 1.
+compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
However, there is one case in which SPACE is ignored. If a variable length
record (that is a discriminated record with a component which is an array
@end example
The default alignment for this record is normally 1, but if this type is
-compiled in @cite{Optimize_Alignment (Time)} mode, then the alignment is set
+compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
to 4, which wastes space for objects of the type, since they are now 4 bytes
long, but results in more efficient access when the whole record is referenced.
pragma appears at the start of the file.
@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{a9}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{ac}
@section Pragma Ordered
type Color is (Red, Blue, Green, Yellow);
@end example
-By Ada semantics @cite{Blue > Red} and @cite{Green > Blue},
+By Ada semantics @code{Blue > Red} and @code{Green > Blue},
but really these relations make no sense; the enumeration type merely
specifies a set of possible colors, and the order is unimportant.
the code in the client should list the possibilities, or an
appropriate subtype should be declared in the unit that declares
the original enumeration type. E.g., the following subtype could
-be declared along with the type @cite{Color}:
+be declared along with the type @code{Color}:
@example
subtype RBG is Color range Red .. Green;
rather than one to mark them as unordered, since in our experience,
the great majority of enumeration types are conceptually unordered.
-The types @cite{Boolean}, @cite{Character}, @cite{Wide_Character},
-and @cite{Wide_Wide_Character}
+The types @code{Boolean}, @code{Character}, @code{Wide_Character},
+and @code{Wide_Wide_Character}
are considered to be ordered types, so each is declared with a
-pragma @cite{Ordered} in package @cite{Standard}.
+pragma @code{Ordered} in package @code{Standard}.
-Normally pragma @cite{Ordered} serves only as documentation and a guide for
+Normally pragma @code{Ordered} serves only as documentation and a guide for
coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that
requests warnings for inappropriate uses (comparisons and explicit
subranges) for unordered types. If this switch is used, then any
-enumeration type not marked with pragma @cite{Ordered} will be considered
+enumeration type not marked with pragma @code{Ordered} will be considered
as unordered, and will generate warnings for inappropriate uses.
Note that generic types are not considered ordered or unordered (since the
@emph{-gnatw.u} switch in the GNAT User's Guide.
@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{aa}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{ad}
@section Pragma Overflow_Mode
This pragma sets the current overflow mode to the given setting. For details
of the meaning of these modes, please refer to the
'Overflow Check Handling in GNAT' appendix in the
-GNAT User's Guide. If only the @cite{General} parameter is present,
+GNAT User's Guide. If only the @code{General} parameter is present,
the given mode applies to all expressions. If both parameters are present,
-the @cite{General} mode applies to expressions outside assertions, and
-the @cite{Eliminated} mode applies to expressions within assertions.
+the @code{General} mode applies to expressions outside assertions, and
+the @code{Eliminated} mode applies to expressions within assertions.
-The case of the @cite{MODE} parameter is ignored,
-so @cite{MINIMIZED}, @cite{Minimized} and
-@cite{minimized} all have the same effect.
+The case of the @code{MODE} parameter is ignored,
+so @code{MINIMIZED}, @code{Minimized} and
+@code{minimized} all have the same effect.
-The @cite{Overflow_Mode} pragma has the same scoping and placement
-rules as pragma @cite{Suppress}, so it can occur either as a
+The @code{Overflow_Mode} pragma has the same scoping and placement
+rules as pragma @code{Suppress}, so it can occur either as a
configuration pragma, specifying a default for the whole
program, or in a declarative scope, where it applies to the
remaining declarations and statements in that scope.
-The pragma @cite{Suppress (Overflow_Check)} suppresses
+The pragma @code{Suppress (Overflow_Check)} suppresses
overflow checking, but does not affect the overflow mode.
-The pragma @cite{Unsuppress (Overflow_Check)} unsuppresses (enables)
+The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables)
overflow checking, but does not affect the overflow mode.
@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{ab}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{ae}
@section Pragma Overriding_Renamings
declaration of the overriding operation.
@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{ac}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{af}
@section Pragma Partition_Elaboration_Policy
See Ada 2012 Reference Manual for details.
@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{ad}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{ae}
+@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{b0}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b1}
@section Pragma Part_Of
ABSTRACT_STATE ::= NAME
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Part_Of} in the
+For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the
SPARK 2014 Reference Manual, section 7.2.6.
@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{af}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b2}
@section Pragma Passive
Syntax checked, but otherwise ignored by GNAT. This is recognized for
compatibility with DEC Ada 83 implementations, where it is used within a
task definition to request that a task be made passive. If the argument
-@cite{Semaphore} is present, or the argument is omitted, then DEC Ada 83
+@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
treats the pragma as an assertion that the containing task is passive
and that optimization of context switch with this task is permitted and
-desired. If the argument @cite{No} is present, the task must not be
+desired. If the argument @code{No} is present, the task must not be
optimized. GNAT does not attempt to optimize any tasks in this manner
(since protected objects are available in place of passive tasks).
'Passive Task Optimization' in the GNAT Users Guide.
@node Pragma Persistent_BSS,Pragma Polling,Pragma Passive,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b0}@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{b1}
+@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b3}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b4}
@section Pragma Persistent_BSS
pragma Persistent_BSS [(LOCAL_NAME)]
@end example
-This pragma allows selected objects to be placed in the @cite{.persistent_bss}
+This pragma allows selected objects to be placed in the @code{.persistent_bss}
section. On some targets the linker and loader provide for special
treatment of this section, allowing a program to be reloaded without
affecting the contents of this data (hence the name persistent).
There are two forms of usage. If an argument is given, it must be the
-local name of a library level object, with no explicit initialization
+local name of a library-level object, with no explicit initialization
and whose type is potentially persistent. If no argument is given, then
-the pragma is a configuration pragma, and applies to all library level
+the pragma is a configuration pragma, and applies to all library-level
objects with no explicit initialization of potentially persistent types.
A potentially persistent type is a scalar type, or an untagged,
type is potentially persistent.
If this pragma is used on a target where this feature is not supported,
-then the pragma will be ignored. See also @cite{pragma Linker_Section}.
+then the pragma will be ignored. See also @code{pragma Linker_Section}.
@node Pragma Polling,Pragma Post,Pragma Persistent_BSS,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-polling}@anchor{b2}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-polling}@anchor{b5}
@section Pragma Polling
@end example
This pragma controls the generation of polling code. This is normally off.
-If @cite{pragma Polling (ON)} is used then periodic calls are generated to
-the routine @cite{Ada.Exceptions.Poll}. This routine is a separate unit in the
+If @code{pragma Polling (ON)} is used then periodic calls are generated to
+the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
runtime library, and can be found in file @code{a-excpol.adb}.
-Pragma @cite{Polling} can appear as a configuration pragma (for example it
+Pragma @code{Polling} can appear as a configuration pragma (for example it
can be placed in the @code{gnat.adc} file) to enable polling globally, or it
can be used in the statement or declaration sequence to control polling
more locally.
A call to the polling routine is generated at the start of every loop and
-at the start of every subprogram call. This guarantees that the @cite{Poll}
+at the start of every subprogram call. This guarantees that the @code{Poll}
routine is called frequently, and places an upper bound (determined by
-the complexity of the code) on the period between two @cite{Poll} calls.
+the complexity of the code) on the period between two @code{Poll} calls.
The primary purpose of the polling interface is to enable asynchronous
aborts on targets that cannot otherwise support it (for example Windows
NT), but it may be used for any other purpose requiring periodic polling.
The standard version is null, and can be replaced by a user program. This
-will require re-compilation of the @cite{Ada.Exceptions} package that can
+will require re-compilation of the @code{Ada.Exceptions} package that can
be found in files @code{a-except.ads} and @code{a-except.adb}.
A standard alternative unit (in file @code{4wexcpol.adb} in the standard GNAT
distribution) is used to enable the asynchronous abort capability on
targets that do not normally support the capability. The version of
-@cite{Poll} in this file makes a call to the appropriate runtime routine
+@code{Poll} in this file makes a call to the appropriate runtime routine
to test for an abort condition.
Note that polling can also be enabled by use of the @emph{-gnatP} switch.
See the section on switches for gcc in the @cite{GNAT User's Guide}.
@node Pragma Post,Pragma Postcondition,Pragma Polling,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b3}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b6}
@section Pragma Post
pragma Post (Boolean_Expression);
@end example
-The @cite{Post} pragma is intended to be an exact replacement for
+The @code{Post} pragma is intended to be an exact replacement for
the language-defined
-@cite{Post} aspect, and shares its restrictions and semantics.
+@code{Post} aspect, and shares its restrictions and semantics.
It must appear either immediately following the corresponding
subprogram declaration (only other pragmas may intervene), or
if there is no separate subprogram declaration, then it can
(preceded only by other pragmas).
@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b4}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b7}
@section Pragma Postcondition
[,[Message =>] String_Expression]);
@end example
-The @cite{Postcondition} pragma allows specification of automatic
+The @code{Postcondition} pragma allows specification of automatic
postcondition checks for subprograms. These checks are similar to
assertions, but are automatically inserted just prior to the return
statements of the subprogram with which they are associated (including
must be true may contain references to function'Result in the case
of a function to refer to the returned value.
-@cite{Postcondition} pragmas may appear either immediately following the
+@code{Postcondition} pragmas may appear either immediately following the
(separate) declaration of a subprogram, or at the start of the
declarations of a subprogram body. Only other pragmas may intervene
(that is appear between the subprogram declaration and its
before any return (implicit or explicit) in the subprogram body.
A postcondition is only recognized if postconditions are active
at the time the pragma is encountered. The compiler switch @emph{gnata}
-turns on all postconditions by default, and pragma @cite{Check_Policy}
-with an identifier of @cite{Postcondition} can also be used to
+turns on all postconditions by default, and pragma @code{Check_Policy}
+with an identifier of @code{Postcondition} can also be used to
control whether postconditions are active.
The general approach is that postconditions are placed in the spec
end Sqrt
@end example
-As this example, shows, the use of the @cite{Old} attribute
+As this example, shows, the use of the @code{Old} attribute
is often useful in postconditions to refer to the state on
entry to the subprogram.
raising an exception, then the postconditions are not checked.
If a postcondition fails, then the exception
-@cite{System.Assertions.Assert_Failure} is raised. If
+@code{System.Assertions.Assert_Failure} is raised. If
a message argument was supplied, then the given string
will be used as the exception message. If no message
argument was supplied, then the default message has
@end example
There are no restrictions on the complexity or form of
-conditions used within @cite{Postcondition} pragmas.
+conditions used within @code{Postcondition} pragmas.
The following example shows that it is even possible
to verify performance behavior.
by the compiler, but are ignored at run-time even if postcondition
checking is enabled.
-Note that pragma @cite{Postcondition} differs from the language-defined
-@cite{Post} aspect (and corresponding @cite{Post} pragma) in allowing
+Note that pragma @code{Postcondition} differs from the language-defined
+@code{Post} aspect (and corresponding @code{Post} pragma) in allowing
multiple occurrences, allowing occurences in the body even if there
is a separate spec, and allowing a second string parameter, and the
-use of the pragma identifier @cite{Check}. Historically, pragma
-@cite{Postcondition} was implemented prior to the development of
+use of the pragma identifier @code{Check}. Historically, pragma
+@code{Postcondition} was implemented prior to the development of
Ada 2012, and has been retained in its original form for
compatibility purposes.
@node Pragma Post_Class,Pragma Rename_Pragma,Pragma Postcondition,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{b5}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{b8}
@section Pragma Post_Class
pragma Post_Class (Boolean_Expression);
@end example
-The @cite{Post_Class} pragma is intended to be an exact replacement for
+The @code{Post_Class} pragma is intended to be an exact replacement for
the language-defined
-@cite{Post'Class} aspect, and shares its restrictions and semantics.
+@code{Post'Class} aspect, and shares its restrictions and semantics.
It must appear either immediately following the corresponding
subprogram declaration (only other pragmas may intervene), or
if there is no separate subprogram declaration, then it can
appear at the start of the declarations in a subprogram body
(preceded only by other pragmas).
-Note: This pragma is called @cite{Post_Class} rather than
-@cite{Post'Class} because the latter would not be strictly
+Note: This pragma is called @code{Post_Class} rather than
+@code{Post'Class} because the latter would not be strictly
conforming to the allowed syntax for pragmas. The motivation
for provinding pragmas equivalent to the aspects is to allow a program
to be written using the pragmas, and then compiled if necessary
using an Ada compiler that does not recognize the pragmas or
aspects, but is prepared to ignore the pragmas. The assertion
-policy that controls this pragma is @cite{Post'Class}, not
-@cite{Post_Class}.
+policy that controls this pragma is @code{Post'Class}, not
+@code{Post_Class}.
@node Pragma Rename_Pragma,Pragma Pre,Pragma Post_Class,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{b6}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{b9}
@section Pragma Rename_Pragma
@end example
This pragma provides a mechanism for supplying new names for existing
-pragmas. The @cite{New_Name} identifier can subsequently be used as a synonym for
+pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for
the Renamed pragma. For example, suppose you have code that was originally
developed on a compiler that supports Inline_Only as an implementation defined
pragma. And suppose the semantics of pragma Inline_Only are identical to (or at
compiler; it's up to you to make sure the semantics are close enough.
@node Pragma Pre,Pragma Precondition,Pragma Rename_Pragma,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{b7}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{ba}
@section Pragma Pre
pragma Pre (Boolean_Expression);
@end example
-The @cite{Pre} pragma is intended to be an exact replacement for
+The @code{Pre} pragma is intended to be an exact replacement for
the language-defined
-@cite{Pre} aspect, and shares its restrictions and semantics.
+@code{Pre} aspect, and shares its restrictions and semantics.
It must appear either immediately following the corresponding
subprogram declaration (only other pragmas may intervene), or
if there is no separate subprogram declaration, then it can
(preceded only by other pragmas).
@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{b8}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bb}
@section Pragma Precondition
[,[Message =>] String_Expression]);
@end example
-The @cite{Precondition} pragma is similar to @cite{Postcondition}
+The @code{Precondition} pragma is similar to @code{Postcondition}
except that the corresponding checks take place immediately upon
entry to the subprogram, and if a precondition fails, the exception
is raised in the context of the caller, and the attribute 'Result
end Math_Functions;
@end example
-@cite{Precondition} pragmas may appear either immediately following the
+@code{Precondition} pragmas may appear either immediately following the
(separate) declaration of a subprogram, or at the start of the
declarations of a subprogram body. Only other pragmas may intervene
(that is appear between the subprogram declaration and its
by the compiler, but are ignored at run-time even if precondition
checking is enabled.
-Note that pragma @cite{Precondition} differs from the language-defined
-@cite{Pre} aspect (and corresponding @cite{Pre} pragma) in allowing
+Note that pragma @code{Precondition} differs from the language-defined
+@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing
multiple occurrences, allowing occurences in the body even if there
is a separate spec, and allowing a second string parameter, and the
-use of the pragma identifier @cite{Check}. Historically, pragma
-@cite{Precondition} was implemented prior to the development of
+use of the pragma identifier @code{Check}. Historically, pragma
+@code{Precondition} was implemented prior to the development of
Ada 2012, and has been retained in its original form for
compatibility purposes.
@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{b9}@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ba}
+@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{bc}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{bd}
@section Pragma Predicate
@end example
This pragma (available in all versions of Ada in GNAT) encompasses both
-the @cite{Static_Predicate} and @cite{Dynamic_Predicate} aspects in
+the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in
Ada 2012. A predicate is regarded as static if it has an allowed form
-for @cite{Static_Predicate} and is otherwise treated as a
-@cite{Dynamic_Predicate}. Otherwise, predicates specified by this
+for @code{Static_Predicate} and is otherwise treated as a
+@code{Dynamic_Predicate}. Otherwise, predicates specified by this
pragma behave exactly as described in the Ada 2012 reference manual.
For example, if we have
Dynamic_Predicate => F(Q) or G(Q);
@end example
-Note that there are no pragmas @cite{Dynamic_Predicate}
-or @cite{Static_Predicate}. That is
+Note that there are no pragmas @code{Dynamic_Predicate}
+or @code{Static_Predicate}. That is
because these pragmas would affect legality and semantics of
the program and thus do not have a neutral effect if ignored.
The motivation behind providing pragmas equivalent to
static and dynamic predicates, since if the corresponding
pragmas are ignored, then the behavior of the program is
fundamentally changed (for example a membership test
-@cite{A in B} would not take into account a predicate
+@code{A in B} would not take into account a predicate
defined for subtype B). When following this approach, the
use of predicates should be avoided.
@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{bb}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{be}
@section Pragma Predicate_Failure
[Message =>] String_Expression);
@end example
-The @cite{Predicate_Failure} pragma is intended to be an exact replacement for
+The @code{Predicate_Failure} pragma is intended to be an exact replacement for
the language-defined
-@cite{Predicate_Failure} aspect, and shares its restrictions and semantics.
+@code{Predicate_Failure} aspect, and shares its restrictions and semantics.
@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{bc}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{bf}
@section Pragma Preelaborable_Initialization
See Ada 2012 Reference Manual for details.
@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{bd}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c0}
@section Pragma Prefix_Exception_Messages
than a static string constant, since the assumption in this case is that
the program computes exactly the string it wants. If you still want the
prefixing in this case, you can always call
-@cite{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually.
+@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually.
@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{be}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c1}
@section Pragma Pre_Class
pragma Pre_Class (Boolean_Expression);
@end example
-The @cite{Pre_Class} pragma is intended to be an exact replacement for
+The @code{Pre_Class} pragma is intended to be an exact replacement for
the language-defined
-@cite{Pre'Class} aspect, and shares its restrictions and semantics.
+@code{Pre'Class} aspect, and shares its restrictions and semantics.
It must appear either immediately following the corresponding
subprogram declaration (only other pragmas may intervene), or
if there is no separate subprogram declaration, then it can
appear at the start of the declarations in a subprogram body
(preceded only by other pragmas).
-Note: This pragma is called @cite{Pre_Class} rather than
-@cite{Pre'Class} because the latter would not be strictly
+Note: This pragma is called @code{Pre_Class} rather than
+@code{Pre'Class} because the latter would not be strictly
conforming to the allowed syntax for pragmas. The motivation
for providing pragmas equivalent to the aspects is to allow a program
to be written using the pragmas, and then compiled if necessary
using an Ada compiler that does not recognize the pragmas or
aspects, but is prepared to ignore the pragmas. The assertion
-policy that controls this pragma is @cite{Pre'Class}, not
-@cite{Pre_Class}.
+policy that controls this pragma is @code{Pre'Class}, not
+@code{Pre_Class}.
@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{bf}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c2}
@section Pragma Priority_Specific_Dispatching
See Ada 2012 Reference Manual for details.
@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c0}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c3}
@section Pragma Profile
This pragma is standard in Ada 2005, but is available in all earlier
versions of Ada as an implementation-defined pragma. This is a
configuration pragma that establishes a set of configuration pragmas
-that depend on the argument. @cite{Ravenscar} is standard in Ada 2005.
-The other possibilities (@cite{Restricted}, @cite{Rational},
-@cite{GNAT_Extended_Ravenscar}, @cite{GNAT_Ravenscar_EDF})
+that depend on the argument. @code{Ravenscar} is standard in Ada 2005.
+The other possibilities (@code{Restricted}, @code{Rational},
+@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF})
are implementation-defined. The set of configuration pragmas
is defined in the following sections.
@item
Pragma Profile (Ravenscar)
-The @cite{Ravenscar} profile is standard in Ada 2005,
+The @code{Ravenscar} profile is standard in Ada 2005,
but is available in all earlier
versions of Ada as an implementation-defined pragma. This profile
establishes the following set of configuration pragmas:
@end itemize
@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c1}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c4}
@section Pragma Profile_Warnings
@end example
This is an implementation-defined pragma that is similar in
-effect to @cite{pragma Profile} except that instead of
-generating @cite{Restrictions} pragmas, it generates
-@cite{Restriction_Warnings} pragmas. The result is that
+effect to @code{pragma Profile} except that instead of
+generating @code{Restrictions} pragmas, it generates
+@code{Restriction_Warnings} pragmas. The result is that
violations of the profile generate warning messages instead
of error messages.
@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c2}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c5}
@section Pragma Propagate_Exceptions
a now-obsolete mechanism for implementation of exceptions.
@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c3}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c6}
@section Pragma Provide_Shift_Operators
with the pragma Import (Intrinsic, ...) statements.
@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c4}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c7}
@section Pragma Psect_Object
| static_string_EXPRESSION
@end example
-This pragma is identical in effect to pragma @cite{Common_Object}.
+This pragma is identical in effect to pragma @code{Common_Object}.
@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{c5}@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{c6}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{c8}@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{c9}
@section Pragma Pure_Function
This pragma appears in the same declarative part as a function
declaration (or a set of function declarations if more than one
overloaded declaration exists, in which case the pragma applies
-to all entities). It specifies that the function @cite{Entity} is
+to all entities). It specifies that the function @code{Entity} is
to be considered pure for the purposes of code generation. This means
that the compiler can assume that there are no side effects, and
in particular that two calls with identical arguments produce the
address clause.
Note that, quite deliberately, there are no static checks to try
-to ensure that this promise is met, so @cite{Pure_Function} can be used
+to ensure that this promise is met, so @code{Pure_Function} can be used
with functions that are conceptually pure, even if they do modify
global variables. For example, a square root function that is
instrumented to count the number of times it is called is still
if that results in unexpected behavior, the proper action is not to
use the pragma for subprograms that are not (conceptually) pure.
-Note: Most functions in a @cite{Pure} package are automatically pure, and
-there is no need to use pragma @cite{Pure_Function} for such functions. One
+Note: Most functions in a @code{Pure} package are automatically pure, and
+there is no need to use pragma @code{Pure_Function} for such functions. One
exception is any function that has at least one formal of type
-@cite{System.Address} or a type derived from it. Such functions are not
+@code{System.Address} or a type derived from it. Such functions are not
considered pure by default, since the compiler assumes that the
-@cite{Address} parameter may be functioning as a pointer and that the
+@code{Address} parameter may be functioning as a pointer and that the
referenced data may change even if the address value does not.
Similarly, imported functions are not considered to be pure by default,
since there is no way of checking that they are in fact pure. The use
-of pragma @cite{Pure_Function} for such a function will override these default
+of pragma @code{Pure_Function} for such a function will override these default
assumption, and cause the compiler to treat a designated subprogram as pure
in these cases.
-Note: If pragma @cite{Pure_Function} is applied to a renamed function, it
+Note: If pragma @code{Pure_Function} is applied to a renamed function, it
applies to the underlying renamed function. This can be used to
disambiguate cases of overloading where some but not all functions
in a set of overloaded functions are to be designated as pure.
-If pragma @cite{Pure_Function} is applied to a library level function, the
+If pragma @code{Pure_Function} is applied to a library-level function, the
function is also considered pure from an optimization point of view, but the
unit is not a Pure unit in the categorization sense. So for example, a function
-thus marked is free to @cite{with} non-pure units.
+thus marked is free to @code{with} non-pure units.
@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{c7}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{ca}
@section Pragma Rational
@end example
@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{c8}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cb}
@section Pragma Ravenscar
pragma Profile (Ravenscar);
@end example
-which is the preferred method of setting the @cite{Ravenscar} profile.
+which is the preferred method of setting the @code{Ravenscar} profile.
@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{c9}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{ca}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{cc}@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{cd}
@section Pragma Refined_Depends
where FUNCTION_RESULT is a function Result attribute_reference
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Refined_Depends} in
+For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in
the SPARK 2014 Reference Manual, section 6.1.5.
@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{cb}@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{cc}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{ce}@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cf}
@section Pragma Refined_Global
GLOBAL_ITEM ::= NAME
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Refined_Global} in
+For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in
the SPARK 2014 Reference Manual, section 6.1.4.
@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{cd}@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{ce}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d0}@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{d1}
@section Pragma Refined_Post
pragma Refined_Post (boolean_EXPRESSION);
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Refined_Post} in
+For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in
the SPARK 2014 Reference Manual, section 7.2.7.
@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{cf}@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{d0}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d3}
@section Pragma Refined_State
CONSTITUENT ::= object_NAME | state_NAME
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Refined_State} in
+For the semantics of this pragma, see the entry for aspect @code{Refined_State} in
the SPARK 2014 Reference Manual, section 7.2.2.
@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d1}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d4}
@section Pragma Relative_Deadline
See Ada 2012 Reference Manual for details.
@node Pragma Remote_Access_Type,Pragma Restricted_Run_Time,Pragma Relative_Deadline,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{d2}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d3}
+@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d6}
@section Pragma Remote_Access_Type
the use of a remote access to class-wide type as actual for a formal
access type.
-When this pragma applies to a formal access type @cite{Entity}, that
+When this pragma applies to a formal access type @code{Entity}, that
type is treated as a remote access to class-wide type in the generic.
It must be a formal general access type, and its designated type must
be the class-wide type of a formal tagged limited private type from the
actual type must be a remote access to class-wide type.
@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Remote_Access_Type,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d4}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d7}
@section Pragma Restricted_Run_Time
profile.
@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{d5}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{d8}
@section Pragma Restriction_Warnings
This pragma allows a series of restriction identifiers to be
specified (the list of allowed identifiers is the same as for
-pragma @cite{Restrictions}). For each of these identifiers
+pragma @code{Restrictions}). For each of these identifiers
the compiler checks for violations of the restriction, but
generates a warning message rather than an error message
if the restriction is violated.
defined pragmas will cause a warning to be generated.
@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{d6}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{d9}
@section Pragma Reviewable
information.
@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d7}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{d8}
+@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{da}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{db}
@section Pragma Secondary_Stack_Size
@end example
This pragma appears within the task definition of a single task declaration
-or a task type declaration (like pragma @cite{Storage_Size}) and applies to all
+or a task type declaration (like pragma @code{Storage_Size}) and applies to all
task objects of that type. The argument specifies the size of the secondary
stack to be used by these task objects, and must be of an integer type. The
secondary stack is used to handle functions that return a variable-sized
VxWorks 653 and bare board targets, where a fixed block for the
secondary stack is allocated from the primary stack of the task. By default,
these targets assign a percentage of the primary stack for the secondary stack,
-as defined by @cite{System.Parameter.Sec_Stack_Percentage}. With this pragma,
-an @cite{integer_EXPRESSION} of bytes is assigned from the primary stack instead.
+as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma,
+an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead.
For most targets, the pragma does not apply as the secondary stack grows on
demand: allocated as a chain of blocks in the heap. The default size of these
-blocks can be modified via the @cite{-D} binder option as described in
+blocks can be modified via the @code{-D} binder option as described in
@cite{GNAT User's Guide}.
Note that no check is made to see if the secondary stack can fit inside the
primary stack.
-Note the pragma cannot appear when the restriction @cite{No_Secondary_Stack}
+Note the pragma cannot appear when the restriction @code{No_Secondary_Stack}
is in effect.
@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{d9}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{dc}
@section Pragma Share_Generic
@end example
This pragma is provided for compatibility with Dec Ada 83. It has
-no effect in @cite{GNAT} (which does not implement shared generics), other
+no effect in GNAT (which does not implement shared generics), other
than to check that the given names are all names of generic units or
generic instances.
@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{da}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{db}
+@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{dd}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{de}
@section Pragma Shared
semantics are identical to pragma Atomic.
@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{dc}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{df}
@section Pragma Short_Circuit_And_Or
There is no requirement that all units in a partition use this option.
@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{dd}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e0}
@section Pragma Short_Descriptors
is recognized but ignored by all current versions of GNAT.
@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{df}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e1}@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{e2}
@section Pragma Simple_Storage_Pool_Type
@end example
A type can be established as a 'simple storage pool type' by applying
-the representation pragma @cite{Simple_Storage_Pool_Type} to the type.
+the representation pragma @code{Simple_Storage_Pool_Type} to the type.
A type named in the pragma must be a library-level immutably limited record
type or limited tagged type declared immediately within a package declaration.
The type can also be a limited private type whose full type is allowed as
a simple storage pool type.
-For a simple storage pool type @cite{SSP}, nonabstract primitive subprograms
-@cite{Allocate}, @cite{Deallocate}, and @cite{Storage_Size} can be declared that
+For a simple storage pool type @code{SSP}, nonabstract primitive subprograms
+@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that
are subtype conformant with the following subprogram declarations:
@example
return System.Storage_Elements.Storage_Count;
@end example
-Procedure @cite{Allocate} must be declared, whereas @cite{Deallocate} and
-@cite{Storage_Size} are optional. If @cite{Deallocate} is not declared, then
+Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and
+@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then
applying an unchecked deallocation has no effect other than to set its actual
-parameter to null. If @cite{Storage_Size} is not declared, then the
-@cite{Storage_Size} attribute applied to an access type associated with
+parameter to null. If @code{Storage_Size} is not declared, then the
+@code{Storage_Size} attribute applied to an access type associated with
a pool object of type SSP returns zero. Additional operations can be declared
for a simple storage pool type (such as for supporting a mark/release
storage-management discipline).
An object of a simple storage pool type can be associated with an access
type by specifying the attribute
-@ref{e0,,Simple_Storage_Pool}. For example:
+@ref{e3,,Simple_Storage_Pool}. For example:
@example
My_Pool : My_Simple_Storage_Pool_Type;
for Acc'Simple_Storage_Pool use My_Pool;
@end example
-See attribute @ref{e0,,Simple_Storage_Pool}
+See attribute @ref{e3,,Simple_Storage_Pool}
for further details.
@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{e1}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e2}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e4}@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e5}
@section Pragma Source_File_Name
pragma, and so has the usual applicability of configuration pragmas
(i.e., it applies to either an entire partition, or to all units in a
compilation, or to a single unit, depending on how it is used.
-@cite{unit_name} is mapped to @cite{file_name_literal}. The identifier for
+@code{unit_name} is mapped to @code{file_name_literal}. The identifier for
the second argument is required, and indicates whether this is the file
name for the spec or for the body.
The optional Index argument should be used when a file contains multiple
-units, and when you do not want to use @cite{gnatchop} to separate then
+units, and when you do not want to use @code{gnatchop} to separate then
into multiple files (which is the recommended procedure to limit the
number of recompilations that are needed when some sources change).
For instance, if the source file @code{source.ada} contains
(A, Body_File_Name => "source.ada", Index => 2);
@end example
-Note that the @cite{gnatname} utility can also be used to generate those
+Note that the @code{gnatname} utility can also be used to generate those
configuration pragmas.
-Another form of the @cite{Source_File_Name} pragma allows
+Another form of the @code{Source_File_Name} pragma allows
the specification of patterns defining alternative file naming schemes
to apply to all files.
be aware of the intended naming conventions. If you are using project files,
file naming is controlled by Source_File_Name_Project pragmas, which are
usually supplied automatically by the project manager. A pragma
-Source_File_Name cannot appear after a @ref{e3,,Pragma Source_File_Name_Project}.
+Source_File_Name cannot appear after a @ref{e6,,Pragma Source_File_Name_Project}.
-For more details on the use of the @cite{Source_File_Name} pragma, see the
-sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes' in the :title:`GNAT User's Guide}.
+For more details on the use of the @code{Source_File_Name} pragma, see the
+sections on @code{Using Other File Names} and @cite{Alternative File Naming Schemes' in the :title:`GNAT User's Guide}.
@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e3}@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{e4}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e6}@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e7}
@section Pragma Source_File_Name_Project
This pragma has the same syntax and semantics as pragma Source_File_Name.
It is only allowed as a stand-alone configuration pragma.
-It cannot appear after a @ref{e2,,Pragma Source_File_Name}, and
+It cannot appear after a @ref{e4,,Pragma Source_File_Name}, and
most importantly, once pragma Source_File_Name_Project appears,
no further Source_File_Name pragmas are allowed.
known to the project manager).
@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{e5}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{e8}
@section Pragma Source_Reference
@end example
This pragma must appear as the first line of a source file.
-@cite{integer_literal} is the logical line number of the line following
+@code{integer_literal} is the logical line number of the line following
the pragma line (for use in error messages and debugging
-information). @cite{string_literal} is a static string constant that
+information). @code{string_literal} is a static string constant that
specifies the file name to be used in error messages and debugging
-information. This is most notably used for the output of @cite{gnatchop}
+information. This is most notably used for the output of @code{gnatchop}
with the @emph{-r} switch, to make sure that the original unchopped
source file is the one referred to.
is needed for error messages issued by all phases of the compiler.
@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{e6}@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e7}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{e9}@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{ea}
@section Pragma SPARK_Mode
Immediately within a library-level package body
@item
-Immediately following the @cite{private} keyword of a library-level
+Immediately following the @code{private} keyword of a library-level
package spec
@item
-Immediately following the @cite{begin} keyword of a library-level
+Immediately following the @code{begin} keyword of a library-level
package body
@item
by pragma within the spec or body as above.
The basic consistency rule is that you can't turn SPARK_Mode back
-@cite{On}, once you have explicitly (with a pragma) turned if
-@cite{Off}. So the following rules apply:
+@code{On}, once you have explicitly (with a pragma) turned if
+@code{Off}. So the following rules apply:
-If a subprogram spec has SPARK_Mode @cite{Off}, then the body must
-also have SPARK_Mode @cite{Off}.
+If a subprogram spec has SPARK_Mode @code{Off}, then the body must
+also have SPARK_Mode @code{Off}.
For a package, we have four parts:
the body of the package
@item
-the elaboration code after @cite{begin}
+the elaboration code after @code{begin}
@end itemize
For a package, the rule is that if you explicitly turn SPARK_Mode
-@cite{Off} for any part, then all the following parts must have
-SPARK_Mode @cite{Off}. Note that this may require repeating a pragma
-SPARK_Mode (@cite{Off}) in the body. For example, if we have a
-configuration pragma SPARK_Mode (@cite{On}) that turns the mode on by
+@code{Off} for any part, then all the following parts must have
+SPARK_Mode @code{Off}. Note that this may require repeating a pragma
+SPARK_Mode (@code{Off}) in the body. For example, if we have a
+configuration pragma SPARK_Mode (@code{On}) that turns the mode on by
default everywhere, and one particular package spec has pragma
-SPARK_Mode (@cite{Off}), then that pragma will need to be repeated in
+SPARK_Mode (@code{Off}), then that pragma will need to be repeated in
the package body.
@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{e8}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{eb}
@section Pragma Static_Elaboration_Desired
choice.)
@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{e9}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ec}
@section Pragma Stream_Convert
subtype, and whose returned type must be the type given as the first
argument to the pragma.
-The meaning of the @cite{Read} parameter is that if a stream attribute directly
+The meaning of the @code{Read} parameter is that if a stream attribute directly
or indirectly specifies reading of the type given as the first parameter,
then a value of the type given as the argument to the Read function is
read from the stream, and then the Read function is used to convert this
to the required target type.
-Similarly the @cite{Write} parameter specifies how to treat write attributes
+Similarly the @code{Write} parameter specifies how to treat write attributes
that directly or indirectly apply to the type given as the first parameter.
It must have an input parameter of the type specified by the first parameter,
and the return type must be the same as the input type of the Read function.
The effect is that if the value of an unbounded string is written to a stream,
then the representation of the item in the stream is in the same format that
-would be used for @cite{Standard.String'Output}, and this same representation
+would be used for @code{Standard.String'Output}, and this same representation
is expected when a value of this type is read from the stream. Note that the
value written always includes the bounds, even for Unbounded_String'Write,
since Unbounded_String is not an array type.
-Note that the @cite{Stream_Convert} pragma is not effective in the case of
+Note that the @code{Stream_Convert} pragma is not effective in the case of
a derived type of a non-limited tagged type. If such a type is specified then
the pragma is silently ignored, and the default implementation of the stream
attributes is used instead.
@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ea}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ed}
@section Pragma Style_Checks
@end example
@end itemize
-The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the @cite{gnaty} switch with no options.
+The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent
+to the use of the @code{gnaty} switch with no options.
See the @cite{GNAT User's Guide} for details.)
-Note: the behavior is slightly different in GNAT mode (@emph{-gnatg} used).
-In this case, ALL_CHECKS implies the standard set of GNAT mode style check
-options (i.e. equivalent to @emph{-gnatyg}).
+Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used).
+In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check
+options (i.e. equivalent to @code{-gnatyg}).
-The forms with @cite{Off} and @cite{On}
+The forms with @code{Off} and @code{On}
can be used to temporarily disable style checks
as shown in the following example:
@end example
Finally the two argument form is allowed only if the first argument is
-@cite{On} or @cite{Off}. The effect is to turn of semantic style checks
+@code{On} or @code{Off}. The effect is to turn of semantic style checks
for the specified entity, as shown in the following example:
@example
@end example
@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{eb}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{ee}
@section Pragma Subtitle
but is ignored by GNAT.
@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{ec}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{ef}
@section Pragma Suppress
@itemize *
@item
-@cite{Alignment_Check} can be used to suppress alignment checks
+@code{Alignment_Check} can be used to suppress alignment checks
on addresses used in address clauses. Such checks can also be suppressed
-by suppressing range checks, but the specific use of @cite{Alignment_Check}
+by suppressing range checks, but the specific use of @code{Alignment_Check}
allows suppression of alignment checks without suppressing other range checks.
-Note that @cite{Alignment_Check} is suppressed by default on machines (such as
+Note that @code{Alignment_Check} is suppressed by default on machines (such as
the x86) with non-strict alignment.
@item
-@cite{Atomic_Synchronization} can be used to suppress the special memory
+@code{Atomic_Synchronization} can be used to suppress the special memory
synchronization instructions that are normally generated for access to
-@cite{Atomic} variables to ensure correct synchronization between tasks
+@code{Atomic} variables to ensure correct synchronization between tasks
that use such variables for synchronization purposes.
@item
-@cite{Duplicated_Tag_Check} Can be used to suppress the check that is generated
+@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated
for a duplicated tag value when a tagged type is declared.
@item
-@cite{Container_Checks} Can be used to suppress all checks within Ada.Containers
+@code{Container_Checks} Can be used to suppress all checks within Ada.Containers
and instances of its children, including Tampering_Check.
@item
-@cite{Tampering_Check} Can be used to suppress tampering check in the containers.
+@code{Tampering_Check} Can be used to suppress tampering check in the containers.
@item
-@cite{Predicate_Check} can be used to control whether predicate checks are
+@code{Predicate_Check} can be used to control whether predicate checks are
active. It is applicable only to predicates for which the policy is
-@cite{Check}. Unlike @cite{Assertion_Policy}, which determines if a given
+@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given
predicate is ignored or checked for the whole program, the use of
-@cite{Suppress} and @cite{Unsuppress} with this check name allows a given
+@code{Suppress} and @code{Unsuppress} with this check name allows a given
predicate to be turned on and off at specific points in the program.
@item
-@cite{Validity_Check} can be used specifically to control validity checks.
-If @cite{Suppress} is used to suppress validity checks, then no validity
+@code{Validity_Check} can be used specifically to control validity checks.
+If @code{Suppress} is used to suppress validity checks, then no validity
checks are performed, including those specified by the appropriate compiler
-switch or the @cite{Validity_Checks} pragma.
+switch or the @code{Validity_Checks} pragma.
@item
-Additional check names previously introduced by use of the @cite{Check_Name}
+Additional check names previously introduced by use of the @code{Check_Name}
pragma are also allowed.
@end itemize
that they will not fail, whether or not checks are suppressed.
@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{ed}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f0}
@section Pragma Suppress_All
@end example
This pragma can appear anywhere within a unit.
-The effect is to apply @cite{Suppress (All_Checks)} to the unit
+The effect is to apply @code{Suppress (All_Checks)} to the unit
in which it appears. This pragma is implemented for compatibility with DEC
Ada 83 usage where it appears at the end of a unit, and for compatibility
with Rational Ada, where it appears as a program unit pragma.
-The use of the standard Ada pragma @cite{Suppress (All_Checks)}
+The use of the standard Ada pragma @code{Suppress (All_Checks)}
as a normal configuration pragma is the preferred usage in GNAT.
@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{ee}@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{ef}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f1}@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{f2}
@section Pragma Suppress_Debug_Info
the debugger, and navigating around debugger problems.
@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f0}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f3}
@section Pragma Suppress_Exception_Locations
an exception message giving the file name and line number for the location
of the raise. This is useful for debugging and logging purposes, but this
entails extra space for the strings for the messages. The configuration
-pragma @cite{Suppress_Exception_Locations} can be used to suppress the
+pragma @code{Suppress_Exception_Locations} can be used to suppress the
generation of these strings, with the result that space is saved, but the
exception message for such raises is null. This configuration pragma may
appear in a global configuration pragma file, or in a specific unit as
with this pragma and others compiled in normal mode without it.
@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{f1}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f2}
+@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f4}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f5}
@section Pragma Suppress_Initialization
Suppress_Initialization, as described above.
@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f3}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f6}
@section Pragma Task_Name
@end example
This pragma appears within a task definition (like pragma
-@cite{Priority}) and applies to the task in which it appears. The
+@code{Priority}) and applies to the task in which it appears. The
argument must be of type String, and provides a name to be used for
the task instance when the task is created. Note that this expression
is not required to be static, and in particular, it can contain
The task name is recorded internally in the run-time structures
and is accessible to tools like the debugger. In addition the
-routine @cite{Ada.Task_Identification.Image} will return this
+routine @code{Ada.Task_Identification.Image} will return this
string, with a unique task address appended.
@example
@end example
@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f4}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f7}
@section Pragma Task_Storage
area is an additional storage area allocated to a task. A value of zero
means that either no guard area is created or a minimal guard area is
created, depending on the target. This pragma can appear anywhere a
-@cite{Storage_Size} attribute definition clause is allowed for a task
+@code{Storage_Size} attribute definition clause is allowed for a task
type.
@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{f5}@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{f6}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{f8}@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f9}
@section Pragma Test_Case
[, Ensures => Boolean_Expression]);
@end example
-The @cite{Test_Case} pragma allows defining fine-grain specifications
+The @code{Test_Case} pragma allows defining fine-grain specifications
for use by testing tools.
-The compiler checks the validity of the @cite{Test_Case} pragma, but its
+The compiler checks the validity of the @code{Test_Case} pragma, but its
presence does not lead to any modification of the code generated by the
compiler.
-@cite{Test_Case} pragmas may only appear immediately following the
+@code{Test_Case} pragmas may only appear immediately following the
(separate) declaration of a subprogram in a package declaration, inside
a package spec unit. Only other pragmas may intervene (that is appear
between the subprogram declaration and a test case).
-The compiler checks that boolean expressions given in @cite{Requires} and
-@cite{Ensures} are valid, where the rules for @cite{Requires} are the
-same as the rule for an expression in @cite{Precondition} and the rules
-for @cite{Ensures} are the same as the rule for an expression in
-@cite{Postcondition}. In particular, attributes @cite{'Old} and
-@cite{'Result} can only be used within the @cite{Ensures}
+The compiler checks that boolean expressions given in @code{Requires} and
+@code{Ensures} are valid, where the rules for @code{Requires} are the
+same as the rule for an expression in @code{Precondition} and the rules
+for @code{Ensures} are the same as the rule for an expression in
+@code{Postcondition}. In particular, attributes @code{'Old} and
+@code{'Result} can only be used within the @code{Ensures}
expression. The following is an example of use within a package spec:
@example
@end example
The meaning of a test case is that there is at least one context where
-@cite{Requires} holds such that, if the associated subprogram is executed in
-that context, then @cite{Ensures} holds when the subprogram returns.
-Mode @cite{Nominal} indicates that the input context should also satisfy the
+@code{Requires} holds such that, if the associated subprogram is executed in
+that context, then @code{Ensures} holds when the subprogram returns.
+Mode @code{Nominal} indicates that the input context should also satisfy the
precondition of the subprogram, and the output context should also satisfy its
-postcondition. Mode @cite{Robustness} indicates that the precondition and
+postcondition. Mode @code{Robustness} indicates that the precondition and
postcondition of the subprogram should be ignored for this test case.
@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{f7}@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f8}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{fb}
@section Pragma Thread_Local_Storage
@end example
This pragma specifies that the specified entity, which must be
-a variable declared in a library level package, is to be marked as
-"Thread Local Storage" (@cite{TLS}). On systems supporting this (which
+a variable declared in a library-level package, is to be marked as
+"Thread Local Storage" (@code{TLS}). On systems supporting this (which
include Windows, Solaris, GNU/Linux and VxWorks 6), this causes each
thread (and hence each Ada task) to see a distinct copy of the variable.
The variable may not have default initialization, and if there is
-an explicit initialization, it must be either @cite{null} for an
+an explicit initialization, it must be either @code{null} for an
access variable, or a static expression for a scalar variable.
This provides a low level mechanism similar to that provided by
-the @cite{Ada.Task_Attributes} package, but much more efficient
+the @code{Ada.Task_Attributes} package, but much more efficient
and is also useful in writing interface code that will interact
with foreign threads.
-If this pragma is used on a system where @cite{TLS} is not supported,
+If this pragma is used on a system where @code{TLS} is not supported,
then an error message will be generated and the program will be rejected.
@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{f9}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fc}
@section Pragma Time_Slice
or if it appears in other than the main program unit.
@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{fa}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{fd}
@section Pragma Title
following the normal rules for procedure calls in Ada.
@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{fb}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{fe}
@section Pragma Type_Invariant
[Check =>] EXPRESSION);
@end example
-The @cite{Type_Invariant} pragma is intended to be an exact
-replacement for the language-defined @cite{Type_Invariant}
+The @code{Type_Invariant} pragma is intended to be an exact
+replacement for the language-defined @code{Type_Invariant}
aspect, and shares its restrictions and semantics. It differs
-from the language defined @cite{Invariant} pragma in that it
+from the language defined @code{Invariant} pragma in that it
does not permit a string parameter, and it is
-controlled by the assertion identifier @cite{Type_Invariant}
-rather than @cite{Invariant}.
+controlled by the assertion identifier @code{Type_Invariant}
+rather than @code{Invariant}.
@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{fc}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{fd}
+@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{ff}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{100}
@section Pragma Type_Invariant_Class
[Check =>] EXPRESSION);
@end example
-The @cite{Type_Invariant_Class} pragma is intended to be an exact
-replacement for the language-defined @cite{Type_Invariant'Class}
+The @code{Type_Invariant_Class} pragma is intended to be an exact
+replacement for the language-defined @code{Type_Invariant'Class}
aspect, and shares its restrictions and semantics.
-Note: This pragma is called @cite{Type_Invariant_Class} rather than
-@cite{Type_Invariant'Class} because the latter would not be strictly
+Note: This pragma is called @code{Type_Invariant_Class} rather than
+@code{Type_Invariant'Class} because the latter would not be strictly
conforming to the allowed syntax for pragmas. The motivation
for providing pragmas equivalent to the aspects is to allow a program
to be written using the pragmas, and then compiled if necessary
using an Ada compiler that does not recognize the pragmas or
aspects, but is prepared to ignore the pragmas. The assertion
-policy that controls this pragma is @cite{Type_Invariant'Class},
-not @cite{Type_Invariant_Class}.
+policy that controls this pragma is @code{Type_Invariant'Class},
+not @code{Type_Invariant_Class}.
@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{fe}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{101}
@section Pragma Unchecked_Union
details, consult the Ada 2012 Reference Manual, section B.3.3.
@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{ff}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{102}
@section Pragma Unevaluated_Use_Of_Old
Although the rule guarantees against this possibility, it is sometimes
too restrictive. For example if we know that the string has a lower
bound of 1, then we will never raise an exception.
-The pragma @cite{Unevaluated_Use_Of_Old} can be
-used to modify this behavior. If the argument is @cite{Error} then an
+The pragma @code{Unevaluated_Use_Of_Old} can be
+used to modify this behavior. If the argument is @code{Error} then an
error is given (this is the default RM behavior). If the argument is
-@cite{Warn} then the usage is allowed as legal but with a warning
-that an exception might be raised. If the argument is @cite{Allow}
+@code{Warn} then the usage is allowed as legal but with a warning
+that an exception might be raised. If the argument is @code{Allow}
then the usage is allowed as legal without generating a warning.
This pragma may appear as a configuration pragma, or in a declarative
sequence of package declarations.
@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{100}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{103}
@section Pragma Unimplemented_Unit
If this pragma occurs in a unit that is processed by the compiler, GNAT
aborts with the message @code{xxx not implemented}, where
-@cite{xxx} is the name of the current compilation unit. This pragma is
+@code{xxx} is the name of the current compilation unit. This pragma is
intended to allow the compiler to handle unimplemented library units in
a clean manner.
specs of unimplemented packages in syntax or semantic checking mode.
@node Pragma Universal_Aliasing,Pragma Universal_Data,Pragma Unimplemented_Unit,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{101}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{102}
+@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{104}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{105}
@section Pragma Universal_Aliasing
pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
@end example
-@cite{type_LOCAL_NAME} must refer to a type declaration in the current
+@code{type_LOCAL_NAME} must refer to a type declaration in the current
declarative part. The effect is to inhibit strict type-based aliasing
optimization for the given type. In other words, the effect is as though
access types designating this type were subject to pragma No_Strict_Aliasing.
For a detailed description of the strict aliasing optimization, and the
situations in which it must be suppressed, see the section on
-@cite{Optimization and Strict Aliasing} in the @cite{GNAT User's Guide}.
+@code{Optimization and Strict Aliasing} in the @cite{GNAT User's Guide}.
@node Pragma Universal_Data,Pragma Unmodified,Pragma Universal_Aliasing,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-data}@anchor{103}@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{104}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-data}@anchor{106}@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{107}
@section Pragma Universal_Data
compilations of units where universal addressing of the data is desired.
@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Data,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{105}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{106}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{108}@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{109}
@section Pragma Unmodified
@end example
This pragma signals that the assignable entities (variables,
-@cite{out} parameters, @cite{in out} parameters) whose names are listed are
+@code{out} parameters, @code{in out} parameters) whose names are listed are
deliberately not assigned in the current source unit. This
suppresses warnings about the
entities being referenced but not assigned, and in addition a warning will be
For the variable case, warnings are never given for unreferenced variables
whose name contains one of the substrings
-@cite{DISCARD@comma{} DUMMY@comma{} IGNORE@comma{} JUNK@comma{} UNUSED} in any casing. Such names
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
are typically to be used in cases where such warnings are expected.
-Thus it is never necessary to use @cite{pragma Unmodified} for such
+Thus it is never necessary to use @code{pragma Unmodified} for such
variables, though it is harmless to do so.
@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{107}@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{108}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10b}
@section Pragma Unreferenced
objects declared only for their initialization or finalization side
effects.
-If @cite{LOCAL_NAME} identifies more than one matching homonym in the
+If @code{LOCAL_NAME} identifies more than one matching homonym in the
current scope, then the entity most recently declared is the one to which
the pragma applies. Note that in the case of accept formals, the pragma
-Unreferenced may appear immediately after the keyword @cite{do} which
+Unreferenced may appear immediately after the keyword @code{do} which
allows the indication of whether or not accept formals are referenced
or not to be given individually for each accept statement.
regardless of whether they occur in the same unit as the subprogram
declaration, then this pragma should not be used (calls from another
unit would not be flagged); pragma Obsolescent can be used instead
-for this purpose, see @ref{a6,,Pragma Obsolescent}.
+for this purpose, see @ref{a9,,Pragma Obsolescent}.
-The second form of pragma @cite{Unreferenced} is used within a context
+The second form of pragma @code{Unreferenced} is used within a context
clause. In this case the arguments must be unit names of units previously
-mentioned in @cite{with} clauses (similar to the usage of pragma
-@cite{Elaborate_All}. The effect is to suppress warnings about unreferenced
+mentioned in @code{with} clauses (similar to the usage of pragma
+@code{Elaborate_All}. The effect is to suppress warnings about unreferenced
units and unreferenced entities within these units.
For the variable case, warnings are never given for unreferenced variables
whose name contains one of the substrings
-@cite{DISCARD@comma{} DUMMY@comma{} IGNORE@comma{} JUNK@comma{} UNUSED} in any casing. Such names
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
are typically to be used in cases where such warnings are expected.
-Thus it is never necessary to use @cite{pragma Unreferenced} for such
+Thus it is never necessary to use @code{pragma Unreferenced} for such
variables, though it is harmless to do so.
@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{109}@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{10a}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10d}
@section Pragma Unreferenced_Objects
not being referenced.
@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10b}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10e}
@section Pragma Unreserve_All_Interrupts
Normally certain interrupts are reserved to the implementation. Any attempt
to attach an interrupt causes Program_Error to be raised, as described in
-RM C.3.2(22). A typical example is the @cite{SIGINT} interrupt used in
+RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is
reserved to the implementation, so that @code{Ctrl-C} can be used to
interrupt execution.
-If the pragma @cite{Unreserve_All_Interrupts} appears anywhere in any unit in
+If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
a program, then all such interrupts are unreserved. This allows the
program to handle these interrupts, but disables their standard
functions. For example, if this pragma is used, then pressing
@code{Ctrl-C} will not automatically interrupt execution. However,
-a program can then handle the @cite{SIGINT} interrupt as it chooses.
+a program can then handle the @code{SIGINT} interrupt as it chooses.
For a full list of the interrupts handled in a specific implementation,
-see the source code for the spec of @cite{Ada.Interrupts.Names} in
+see the source code for the spec of @code{Ada.Interrupts.Names} in
file @code{a-intnam.ads}. This is a target dependent file that contains the
list of interrupts recognized for a given target. The documentation in
this file also specifies what interrupts are affected by the use of
-the @cite{Unreserve_All_Interrupts} pragma.
+the @code{Unreserve_All_Interrupts} pragma.
For a more general facility for controlling what interrupts can be
-handled, see pragma @cite{Interrupt_State}, which subsumes the functionality
-of the @cite{Unreserve_All_Interrupts} pragma.
+handled, see pragma @code{Interrupt_State}, which subsumes the functionality
+of the @code{Unreserve_All_Interrupts} pragma.
@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10c}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10f}
@section Pragma Unsuppress
pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
@end example
-This pragma undoes the effect of a previous pragma @cite{Suppress}. If
-there is no corresponding pragma @cite{Suppress} in effect, it has no
+This pragma undoes the effect of a previous pragma @code{Suppress}. If
+there is no corresponding pragma @code{Suppress} in effect, it has no
effect. The range of the effect is the same as for pragma
-@cite{Suppress}. The meaning of the arguments is identical to that used
-in pragma @cite{Suppress}.
+@code{Suppress}. The meaning of the arguments is identical to that used
+in pragma @code{Suppress}.
One important application is to ensure that checks are on in cases where
code depends on the checks for its correct functioning, so that the code
Note that in addition to the checks defined in the Ada RM, GNAT recogizes a
number of implementation-defined check names. See the description of pragma
-@cite{Suppress} for full details.
+@code{Suppress} for full details.
@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{10d}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{110}
@section Pragma Use_VADS_Size
attribute for further details.
@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{10e}@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10f}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{111}@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{112}
@section Pragma Unused
@end example
This pragma signals that the assignable entities (variables,
-@cite{out} parameters, and @cite{in out} parameters) whose names are listed
+@code{out} parameters, and @code{in out} parameters) whose names are listed
deliberately do not get assigned or referenced in the current source unit
after the occurrence of the pragma in the current source unit. This
suppresses warnings about the entities that are unreferenced and/or not
For the variable case, warnings are never given for unreferenced
variables whose name contains one of the substrings
-@cite{DISCARD@comma{} DUMMY@comma{} IGNORE@comma{} JUNK@comma{} UNUSED} in any casing. Such names
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
are typically to be used in cases where such warnings are expected.
-Thus it is never necessary to use @cite{pragma Unmodified} for such
+Thus it is never necessary to use @code{pragma Unmodified} for such
variables, though it is harmless to do so.
@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{110}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{113}
@section Pragma Validity_Checks
specifies the exact set of options required. The form of this string
is exactly as described for the @emph{-gnatVx} compiler switch (see the
GNAT User's Guide for details). For example the following two
-methods can be used to enable validity checking for mode @cite{in} and
-@cite{in out} subprogram parameters:
+methods can be used to enable validity checking for mode @code{in} and
+@code{in out} subprogram parameters:
@itemize *
@end itemize
The form ALL_CHECKS activates all standard checks (its use is equivalent
-to the use of the @cite{gnatva} switch.
+to the use of the @code{gnatva} switch.
-The forms with @cite{Off} and @cite{On}
+The forms with @code{Off} and @code{On}
can be used to temporarily disable validity checks
as shown in the following example:
@end example
@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{111}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{114}
@section Pragma Volatile
implementation in DEC Ada 83.
@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{112}@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{113}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{115}@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{116}
@section Pragma Volatile_Full_Access
The intention is that this be suitable for use with memory-mapped I/O devices
on some machines. Note that there are two important respects in which this is
-different from @cite{pragma Atomic}. First a reference to a @cite{Volatile_Full_Access}
+different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access}
object is not a sequential action in the RM 9.10 sense and, therefore, does
-not create a synchronization point. Second, in the case of @cite{pragma Atomic},
+not create a synchronization point. Second, in the case of @code{pragma Atomic},
there is no guarantee that all the bits will be accessed if the reference
is not to the whole object; the compiler is allowed (and generally will)
access only part of the object in this case.
-It is not permissible to specify @cite{Atomic} and @cite{Volatile_Full_Access} for
+It is not permissible to specify @code{Atomic} and @code{Volatile_Full_Access} for
the same object.
-It is not permissible to specify @cite{Volatile_Full_Access} for a composite
-(record or array) type or object that has at least one @cite{Aliased} component.
+It is not permissible to specify @code{Volatile_Full_Access} for a composite
+(record or array) type or object that has at least one @code{Aliased} component.
@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{114}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{115}
+@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{117}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{118}
@section Pragma Volatile_Function
pragma Volatile_Function [ (boolean_EXPRESSION) ];
@end example
-For the semantics of this pragma, see the entry for aspect @cite{Volatile_Function}
+For the semantics of this pragma, see the entry for aspect @code{Volatile_Function}
in the SPARK 2014 Reference Manual, section 7.1.2.
@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{116}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{119}
@section Pragma Warning_As_Error
The pattern may contain asterisks, which match zero or more characters in
the message. For example, you can use
-@cite{pragma Warning_As_Error ("bits of*unused")} to treat the warning
-message @cite{warning: 960 bits of "a" unused} as an error. No other regular
+@code{pragma Warning_As_Error ("bits of*unused")} to treat the warning
+message @code{warning: 960 bits of "a" unused} as an error. No other regular
expression notations are permitted. All characters other than asterisk in
these three specific cases are treated as literal characters in the match.
The match is case insensitive, for example XYZ matches xyz.
The above use of patterns to match the message applies only to warning
messages generated by the front end. This pragma can also be applied to
-warnings provided by the back end and mentioned in @ref{117,,Pragma Warnings}.
+warnings provided by the back end and mentioned in @ref{11a,,Pragma Warnings}.
By using a single full @emph{-Wxxx} switch in the pragma, such warnings
can also be treated as errors.
"[warning-as-error]" is appended to the end of the message.
@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{117}@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{118}
+@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11a}
@section Pragma Warnings
Note: in Ada 83 mode, a string literal may be used in place of a static string
expression (which does not exist in Ada 83).
-Note if the second argument of @cite{DETAILS} is a @cite{local_NAME} then the
+Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the
second form is always understood. If the intention is to use
-the fourth form, then you can write @cite{NAME & ""} to force the
-intepretation as a @cite{static_string_EXPRESSION}.
+the fourth form, then you can write @code{NAME & ""} to force the
+intepretation as a @emph{static_string_EXPRESSION}.
-Note: if the first argument is a valid @cite{TOOL_NAME}, it will be interpreted
-that way. The use of the @cite{TOOL_NAME} argument is relevant only to users
+Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted
+that way. The use of the @code{TOOL_NAME} argument is relevant only to users
of SPARK and GNATprove, see last part of this section for details.
Normally warnings are enabled, with the output being controlled by
-the command line switch. Warnings (@cite{Off}) turns off generation of
-warnings until a Warnings (@cite{On}) is encountered or the end of the
+the command line switch. Warnings (@code{Off}) turns off generation of
+warnings until a Warnings (@code{On}) is encountered or the end of the
current unit. If generation of warnings is turned off using this
pragma, then some or all of the warning messages are suppressed,
regardless of the setting of the command line switches.
-The @cite{Reason} parameter may optionally appear as the last argument
+The @code{Reason} parameter may optionally appear as the last argument
in any of the forms of this pragma. It is intended purely for the
-purposes of documenting the reason for the @cite{Warnings} pragma.
+purposes of documenting the reason for the @code{Warnings} pragma.
The compiler will check that the argument is a static string but
otherwise ignore this argument. Other tools may provide specialized
processing for this string.
The form with a single argument (or two arguments if Reason present),
-where the first argument is @cite{ON} or @cite{OFF}
+where the first argument is @code{ON} or @code{OFF}
may be used as a configuration pragma.
-If the @cite{LOCAL_NAME} parameter is present, warnings are suppressed for
+If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for
the specified entity. This suppression is effective from the point where
it occurs till the end of the extended scope of the variable (similar to
-the scope of @cite{Suppress}). This form cannot be used as a configuration
+the scope of @code{Suppress}). This form cannot be used as a configuration
pragma.
-In the case where the first argument is other than @cite{ON} or
-@cite{OFF},
+In the case where the first argument is other than @code{ON} or
+@code{OFF},
the third form with a single static_string_EXPRESSION argument (and possible
reason) provides more precise
control over which warnings are active. The string is a list of letters
line switch controlling warnings. For a brief summary, use the gnatmake
command with no arguments, which will generate usage information containing
the list of warnings switches supported. For
-full details see the section on @cite{Warning Message Control} in the
+full details see the section on @code{Warning Message Control} in the
@cite{GNAT User's Guide}.
This form can also be used as a configuration pragma.
-The warnings controlled by the @emph{-gnatw} switch are generated by the
+The warnings controlled by the @code{-gnatw} switch are generated by the
front end of the compiler. The GCC back end can provide additional warnings
-and they are controlled by the @emph{-W} switch. Such warnings can be
-identified by the appearance of a string of the form @cite{[-Wxxx]} in the
-message which designates the @emph{-Wxxx} switch that controls the message.
-The form with a single static_string_EXPRESSION argument also works for these
-warnings, but the string must be a single full @emph{-Wxxx} switch in this
+and they are controlled by the @code{-W} switch. Such warnings can be
+identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the
+message which designates the @code{-W@emph{xxx}} switch that controls the message.
+The form with a single @emph{static_string_EXPRESSION} argument also works for these
+warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this
case. The above reference lists a few examples of these additional warnings.
The specified warnings will be in effect until the end of the program
-or another pragma Warnings is encountered. The effect of the pragma is
+or another pragma @code{Warnings} is encountered. The effect of the pragma is
cumulative. Initially the set of warnings is the standard default set
as possibly modified by compiler switches. Then each pragma Warning
modifies this set of warnings as specified. This form of the pragma may
also be used as a configuration pragma.
-The fourth form, with an @cite{On|Off} parameter and a string, is used to
+The fourth form, with an @code{On|Off} parameter and a string, is used to
control individual messages, based on their text. The string argument
is a pattern that is used to match against the text of individual
warning messages (not including the initial "warning: " tag).
The pattern may contain asterisks, which match zero or more characters in
the message. For example, you can use
-@cite{pragma Warnings (Off@comma{} "bits of*unused")} to suppress the warning
-message @cite{warning: 960 bits of "a" unused}. No other regular
+@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning
+message @code{warning: 960 bits of "a" unused}. No other regular
expression notations are permitted. All characters other than asterisk in
these three specific cases are treated as literal characters in the match.
The match is case insensitive, for example XYZ matches xyz.
The above use of patterns to match the message applies only to warning
messages generated by the front end. This form of the pragma with a string
argument can also be used to control warnings provided by the back end and
-mentioned above. By using a single full @emph{-Wxxx} switch in the pragma,
+mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma,
such warnings can be turned on and off.
There are two ways to use the pragma in this form. The OFF form can be used
warning must be suppressed.
Note: to write a string that will match any warning, use the string
-@cite{"***"}. It will not work to use a single asterisk or two
+@code{"***"}. It will not work to use a single asterisk or two
asterisks since this looks like an operator name. This form with three
-asterisks is similar in effect to specifying @cite{pragma Warnings (Off)} except (if @emph{-gnatw.w} is given) that a matching
-@cite{pragma Warnings (On@comma{} "***")} will be required. This can be
+asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching
+@code{pragma Warnings (On, "***")} will be required. This can be
helpful in avoiding forgetting to turn warnings back on.
-Note: the debug flag -gnatd.i (@cite{/NOWARNINGS_PRAGMAS} in VMS) can be
+Note: the debug flag @code{-gnatd.i} (@code{/NOWARNINGS_PRAGMAS} in VMS) can be
used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
be useful in checking whether obsolete pragmas in existing programs are hiding
real problems.
separate entry for pragma Style_Checks for control of style messages.
Users of the formal verification tool GNATprove for the SPARK subset of Ada may
-use the version of the pragma with a @cite{TOOL_NAME} parameter.
+use the version of the pragma with a @code{TOOL_NAME} parameter.
-If present, @cite{TOOL_NAME} is the name of a tool, currently either @cite{GNAT} for the
-compiler or @cite{GNATprove} for the formal verification tool. A given tool only
+If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the
+compiler or @code{GNATprove} for the formal verification tool. A given tool only
takes into account pragma Warnings that do not specify a tool name, or that
specify the matching tool name. This makes it possible to disable warnings
selectively for each tool, and as a consequence to detect useless pragma
-Warnings with switch @cite{-gnatw.w}.
+Warnings with switch @code{-gnatw.w}.
@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{119}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11c}
@section Pragma Weak_External
pragma Weak_External ([Entity =>] LOCAL_NAME);
@end example
-@cite{LOCAL_NAME} must refer to an object that is declared at the library
+@code{LOCAL_NAME} must refer to an object that is declared at the library
level. This pragma specifies that the given entity should be marked as a
-weak symbol for the linker. It is equivalent to @cite{__attribute__((weak))}
-in GNU C and causes @cite{LOCAL_NAME} to be emitted as a weak symbol instead
+weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
+in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead
of a regular symbol, that is to say a symbol that does not have to be
resolved by the linker if used in conjunction with a pragma Import.
@end example
@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas
-@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11a}
+@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11d}
@section Pragma Wide_Character_Encoding
effect, causing "illegal character" errors.
The argument can be an identifier or a character literal. In the identifier
-case, it is one of @cite{HEX}, @cite{UPPER}, @cite{SHIFT_JIS},
-@cite{EUC}, @cite{UTF8}, or @cite{BRACKETS}. In the character literal
+case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
+@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
case it is correspondingly one of the characters @code{h}, @code{u},
@code{s}, @code{e}, @code{8}, or @code{b}.
or subunits.
@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top
-@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{11b}@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11c}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{11d}
+@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{11e}@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11f}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{120}
@chapter Implementation Defined Aspects
* Aspect Lock_Free::
* Aspect Max_Queue_Length::
* Aspect No_Elaboration_Code_All::
+* Aspect No_Inline::
* Aspect No_Tagged_Streams::
* Aspect Object_Size::
* Aspect Obsolescent::
@end menu
@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{11e}
+@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{121}
@section Aspect Abstract_State
This aspect is equivalent to @ref{1c,,pragma Abstract_State}.
@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{11f}
+@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{122}
@section Aspect Annotate
@item @emph{Annotate => ID}
-Equivalent to @cite{pragma Annotate (ID@comma{} Entity => Name);}
+Equivalent to @code{pragma Annotate (ID, Entity => Name);}
@item @emph{Annotate => (ID)}
-Equivalent to @cite{pragma Annotate (ID@comma{} Entity => Name);}
+Equivalent to @code{pragma Annotate (ID, Entity => Name);}
@item @emph{Annotate => (ID ,ID @{, ARG@})}
-Equivalent to @cite{pragma Annotate (ID@comma{} ID @{@comma{} ARG@}@comma{} Entity => Name);}
+Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);}
@end table
@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{120}
+@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{123}
@section Aspect Async_Readers
This boolean aspect is equivalent to @ref{2c,,pragma Async_Readers}.
@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{121}
+@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{124}
@section Aspect Async_Writers
This boolean aspect is equivalent to @ref{2f,,pragma Async_Writers}.
@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{122}
+@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{125}
@section Aspect Constant_After_Elaboration
This aspect is equivalent to @ref{40,,pragma Constant_After_Elaboration}.
@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{123}
+@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{126}
@section Aspect Contract_Cases
aggregate.
@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{124}
+@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{127}
@section Aspect Depends
This aspect is equivalent to @ref{51,,pragma Depends}.
@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{125}
+@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{128}
@section Aspect Default_Initial_Condition
This aspect is equivalent to @ref{4c,,pragma Default_Initial_Condition}.
@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{126}
+@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{129}
@section Aspect Dimension
@geindex Dimension
-The @cite{Dimension} aspect is used to specify the dimensions of a given
+The @code{Dimension} aspect is used to specify the dimensions of a given
subtype of a dimensioned numeric type. The aspect also specifies a symbol
used when doing formatted output of dimensioned quantities. The syntax is:
@end example
This aspect can only be applied to a subtype whose parent type has
-a @cite{Dimension_System} aspect. The aspect must specify values for
+a @code{Dimension_System} aspect. The aspect must specify values for
all dimensions of the system. The rational values are the powers of the
corresponding dimensions that are used by the compiler to verify that
physical (numeric) computations are dimensionally consistent. For example,
the computation of a force must result in dimensions (L => 1, M => 1, T => -2).
For further examples of the usage
-of this aspect, see package @cite{System.Dim.Mks}.
+of this aspect, see package @code{System.Dim.Mks}.
Note that when the dimensioned type is an integer type, then any
dimension value must be an integer literal.
@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{127}
+@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12a}
@section Aspect Dimension_System
@geindex Dimension_System
-The @cite{Dimension_System} aspect is used to define a system of
+The @code{Dimension_System} aspect is used to define a system of
dimensions that will be used in subsequent subtype declarations with
-@cite{Dimension} aspects that reference this system. The syntax is:
+@code{Dimension} aspects that reference this system. The syntax is:
@example
with Dimension_System => (DIMENSION @{, DIMENSION@});
This aspect is applied to a type, which must be a numeric derived type
(typically a floating-point type), that
-will represent values within the dimension system. Each @cite{DIMENSION}
+will represent values within the dimension system. Each @code{DIMENSION}
corresponds to one particular dimension. A maximum of 7 dimensions may
-be specified. @cite{Unit_Name} is the name of the dimension (for example
-@cite{Meter}). @cite{Unit_Symbol} is the shorthand used for quantities
-of this dimension (for example @cite{m} for @cite{Meter}).
-@cite{Dim_Symbol} gives
+be specified. @code{Unit_Name} is the name of the dimension (for example
+@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities
+of this dimension (for example @code{m} for @code{Meter}).
+@code{Dim_Symbol} gives
the identification within the dimension system (typically this is a
-single letter, e.g. @cite{L} standing for length for unit name @cite{Meter}).
-The @cite{Unit_Symbol} is used in formatted output of dimensioned quantities.
-The @cite{Dim_Symbol} is used in error messages when numeric operations have
+single letter, e.g. @code{L} standing for length for unit name @code{Meter}).
+The @code{Unit_Symbol} is used in formatted output of dimensioned quantities.
+The @code{Dim_Symbol} is used in error messages when numeric operations have
inconsistent dimensions.
GNAT provides the standard definition of the International MKS system in
-the run-time package @cite{System.Dim.Mks}. You can easily define
+the run-time package @code{System.Dim.Mks}. You can easily define
similar packages for cgs units or British units, and define conversion factors
between values in different systems. The MKS system is characterized by the
following aspect:
(Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
@end example
-Note that in the above type definition, we use the @cite{at} symbol (@code{@@}) to
+Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to
represent a theta character (avoiding the use of extended Latin-1
characters in this context).
Guide for detailed examples of use of the dimension system.
@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{128}
+@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12b}
@section Aspect Disable_Controlled
@geindex Disable_Controlled
-The aspect @cite{Disable_Controlled} is defined for controlled record types. If
-active, this aspect causes suppression of all related calls to @cite{Initialize},
-@cite{Adjust}, and @cite{Finalize}. The intended use is for conditional compilation,
+The aspect @code{Disable_Controlled} is defined for controlled record types. If
+active, this aspect causes suppression of all related calls to @code{Initialize},
+@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation,
where for example you might want a record to be controlled or not depending on
whether some run-time check is enabled or suppressed.
@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{129}
+@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12c}
@section Aspect Effective_Reads
This aspect is equivalent to @ref{57,,pragma Effective_Reads}.
@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12a}
+@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12d}
@section Aspect Effective_Writes
This aspect is equivalent to @ref{59,,pragma Effective_Writes}.
@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12b}
+@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12e}
@section Aspect Extensions_Visible
This aspect is equivalent to @ref{65,,pragma Extensions_Visible}.
@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{12c}
+@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{12f}
@section Aspect Favor_Top_Level
This boolean aspect is equivalent to @ref{6a,,pragma Favor_Top_Level}.
@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{12d}
+@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{130}
@section Aspect Ghost
This aspect is equivalent to @ref{6d,,pragma Ghost}.
@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{12e}
+@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{131}
@section Aspect Global
This aspect is equivalent to @ref{6f,,pragma Global}.
@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{12f}
+@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{132}
@section Aspect Initial_Condition
This aspect is equivalent to @ref{7d,,pragma Initial_Condition}.
@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{130}
+@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{133}
@section Aspect Initializes
This aspect is equivalent to @ref{7f,,pragma Initializes}.
@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{131}
+@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{134}
@section Aspect Inline_Always
This boolean aspect is equivalent to @ref{82,,pragma Inline_Always}.
@node Aspect Invariant,Aspect Invariant'Class,Aspect Inline_Always,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{132}
+@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{135}
@section Aspect Invariant
@geindex Invariant
This aspect is equivalent to @ref{89,,pragma Invariant}. It is a
-synonym for the language defined aspect @cite{Type_Invariant} except
-that it is separately controllable using pragma @cite{Assertion_Policy}.
+synonym for the language defined aspect @code{Type_Invariant} except
+that it is separately controllable using pragma @code{Assertion_Policy}.
@node Aspect Invariant'Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{133}
+@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{136}
@section Aspect Invariant'Class
@geindex Invariant'Class
-This aspect is equivalent to @ref{fd,,pragma Type_Invariant_Class}. It is a
-synonym for the language defined aspect @cite{Type_Invariant'Class} except
-that it is separately controllable using pragma @cite{Assertion_Policy}.
+This aspect is equivalent to @ref{100,,pragma Type_Invariant_Class}. It is a
+synonym for the language defined aspect @code{Type_Invariant'Class} except
+that it is separately controllable using pragma @code{Assertion_Policy}.
@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant'Class,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{134}
+@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{137}
@section Aspect Iterable
This aspect provides a light-weight mechanism for loops and quantified
expressions over container types, without the overhead imposed by the tampering
checks of standard Ada 2012 iterators. The value of the aspect is an aggregate
-with four named components: @cite{First}, @cite{Next}, @cite{Has_Element}, and @cite{Element} (the
+with four named components: @code{First}, @code{Next}, @code{Has_Element}, and @code{Element} (the
last one being optional). When only 3 components are specified, only the
-@cite{for .. in} form of iteration over cursors is available. When all 4 components
-are specified, both this form and the @cite{for .. of} form of iteration over
+@code{for .. in} form of iteration over cursors is available. When all 4 components
+are specified, both this form and the @code{for .. of} form of iteration over
elements are available. The following is a typical example of use:
@example
@itemize *
@item
-The value denoted by @cite{First} must denote a primitive operation of the
-container type that returns a @cite{Cursor}, which must a be a type declared in
+The value denoted by @code{First} must denote a primitive operation of the
+container type that returns a @code{Cursor}, which must a be a type declared in
the container package or visible from it. For example:
@end itemize
@itemize *
@item
-The value of @cite{Next} is a primitive operation of the container type that takes
+The value of @code{Next} is a primitive operation of the container type that takes
both a container and a cursor and yields a cursor. For example:
@end itemize
@itemize *
@item
-The value of @cite{Has_Element} is a primitive operation of the container type
+The value of @code{Has_Element} is a primitive operation of the container type
that takes both a container and a cursor and yields a boolean. For example:
@end itemize
@itemize *
@item
-The value of @cite{Element} is a primitive operation of the container type that
-takes both a container and a cursor and yields an @cite{Element_Type}, which must
+The value of @code{Element} is a primitive operation of the container type that
+takes both a container and a cursor and yields an @code{Element_Type}, which must
be a type declared in the container package or visible from it. For example:
@end itemize
This aspect is used in the GNAT-defined formal container packages.
@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{135}
+@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{138}
@section Aspect Linker_Section
This aspect is equivalent to @ref{91,,pragma Linker_Section}.
@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{136}
+@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{139}
@section Aspect Lock_Free
This boolean aspect is equivalent to @ref{93,,pragma Lock_Free}.
@node Aspect Max_Queue_Length,Aspect No_Elaboration_Code_All,Aspect Lock_Free,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{137}
+@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13a}
@section Aspect Max_Queue_Length
@geindex Max_Queue_Length
-This aspect is equivalent to pragma Max_Queue_Length.
+This aspect is equivalent to @ref{9b,,pragma Max_Queue_Length}.
-@node Aspect No_Elaboration_Code_All,Aspect No_Tagged_Streams,Aspect Max_Queue_Length,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{138}
+@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect Max_Queue_Length,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13b}
@section Aspect No_Elaboration_Code_All
@geindex No_Elaboration_Code_All
-This aspect is equivalent to @ref{9d,,pragma No_Elaboration_Code_All}
+This aspect is equivalent to @ref{9f,,pragma No_Elaboration_Code_All}
for a program unit.
-@node Aspect No_Tagged_Streams,Aspect Object_Size,Aspect No_Elaboration_Code_All,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{139}
+@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{13c}
+@section Aspect No_Inline
+
+
+@geindex No_Inline
+
+This boolean aspect is equivalent to @ref{a2,,pragma No_Inline}.
+
+@node Aspect No_Tagged_Streams,Aspect Object_Size,Aspect No_Inline,Implementation Defined Aspects
+@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13d}
@section Aspect No_Tagged_Streams
@geindex No_Tagged_Streams
-This aspect is equivalent to @ref{a3,,pragma No_Tagged_Streams} with an
+This aspect is equivalent to @ref{a6,,pragma No_Tagged_Streams} with an
argument specifying a root tagged type (thus this aspect can only be
applied to such a type).
@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Tagged_Streams,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{13a}
+@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{13e}
@section Aspect Object_Size
@geindex Object_Size
-This aspect is equivalent to @ref{13b,,attribute Object_Size}.
+This aspect is equivalent to @ref{13f,,attribute Object_Size}.
@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{13c}
+@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{140}
@section Aspect Obsolescent
@geindex Obsolsecent
-This aspect is equivalent to @ref{a6,,pragma Obsolescent}. Note that the
+This aspect is equivalent to @ref{a9,,pragma Obsolescent}. Note that the
evaluation of this aspect happens at the point of occurrence, it is not
delayed until the freeze point.
@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{13d}
+@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{141}
@section Aspect Part_Of
@geindex Part_Of
-This aspect is equivalent to @ref{ae,,pragma Part_Of}.
+This aspect is equivalent to @ref{b1,,pragma Part_Of}.
@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{13e}
+@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{142}
@section Aspect Persistent_BSS
@geindex Persistent_BSS
-This boolean aspect is equivalent to @ref{b0,,pragma Persistent_BSS}.
+This boolean aspect is equivalent to @ref{b4,,pragma Persistent_BSS}.
@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{13f}
+@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{143}
@section Aspect Predicate
@geindex Predicate
-This aspect is equivalent to @ref{b9,,pragma Predicate}. It is thus
-similar to the language defined aspects @cite{Dynamic_Predicate}
-and @cite{Static_Predicate} except that whether the resulting
+This aspect is equivalent to @ref{bd,,pragma Predicate}. It is thus
+similar to the language defined aspects @code{Dynamic_Predicate}
+and @code{Static_Predicate} except that whether the resulting
predicate is static or dynamic is controlled by the form of the
expression. It is also separately controllable using pragma
-@cite{Assertion_Policy}.
+@code{Assertion_Policy}.
@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{140}
+@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{144}
@section Aspect Pure_Function
@geindex Pure_Function
-This boolean aspect is equivalent to @ref{c5,,pragma Pure_Function}.
+This boolean aspect is equivalent to @ref{c8,,pragma Pure_Function}.
@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{141}
+@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{145}
@section Aspect Refined_Depends
@geindex Refined_Depends
-This aspect is equivalent to @ref{ca,,pragma Refined_Depends}.
+This aspect is equivalent to @ref{cc,,pragma Refined_Depends}.
@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{142}
+@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{146}
@section Aspect Refined_Global
@geindex Refined_Global
-This aspect is equivalent to @ref{cb,,pragma Refined_Global}.
+This aspect is equivalent to @ref{ce,,pragma Refined_Global}.
@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{143}
+@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{147}
@section Aspect Refined_Post
@geindex Refined_Post
-This aspect is equivalent to @ref{cd,,pragma Refined_Post}.
+This aspect is equivalent to @ref{d0,,pragma Refined_Post}.
@node Aspect Refined_State,Aspect Remote_Access_Type,Aspect Refined_Post,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{144}
+@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{148}
@section Aspect Refined_State
@geindex Refined_State
-This aspect is equivalent to @ref{cf,,pragma Refined_State}.
+This aspect is equivalent to @ref{d2,,pragma Refined_State}.
@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Refined_State,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{145}
+@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{149}
@section Aspect Remote_Access_Type
@geindex Remote_Access_Type
-This aspect is equivalent to @ref{d3,,pragma Remote_Access_Type}.
+This aspect is equivalent to @ref{d6,,pragma Remote_Access_Type}.
@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{146}
+@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14a}
@section Aspect Secondary_Stack_Size
@geindex Secondary_Stack_Size
-This aspect is equivalent to @ref{d8,,pragma Secondary_Stack_Size}.
+This aspect is equivalent to @ref{db,,pragma Secondary_Stack_Size}.
@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{147}
+@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14b}
@section Aspect Scalar_Storage_Order
@geindex Scalar_Storage_Order
-This aspect is equivalent to a @ref{148,,attribute Scalar_Storage_Order}.
+This aspect is equivalent to a @ref{14c,,attribute Scalar_Storage_Order}.
@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{149}
+@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{14d}
@section Aspect Shared
@geindex Shared
-This boolean aspect is equivalent to @ref{db,,pragma Shared}
-and is thus a synonym for aspect @cite{Atomic}.
+This boolean aspect is equivalent to @ref{de,,pragma Shared}
+and is thus a synonym for aspect @code{Atomic}.
@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{14a}
+@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{14e}
@section Aspect Simple_Storage_Pool
@geindex Simple_Storage_Pool
-This aspect is equivalent to @ref{e0,,attribute Simple_Storage_Pool}.
+This aspect is equivalent to @ref{e3,,attribute Simple_Storage_Pool}.
@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{14b}
+@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{14f}
@section Aspect Simple_Storage_Pool_Type
@geindex Simple_Storage_Pool_Type
-This boolean aspect is equivalent to @ref{de,,pragma Simple_Storage_Pool_Type}.
+This boolean aspect is equivalent to @ref{e1,,pragma Simple_Storage_Pool_Type}.
@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{14c}
+@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{150}
@section Aspect SPARK_Mode
@geindex SPARK_Mode
-This aspect is equivalent to @ref{e6,,pragma SPARK_Mode} and
+This aspect is equivalent to @ref{e9,,pragma SPARK_Mode} and
may be specified for either or both of the specification and body
of a subprogram or package.
@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{14d}
+@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{151}
@section Aspect Suppress_Debug_Info
@geindex Suppress_Debug_Info
-This boolean aspect is equivalent to @ref{ee,,pragma Suppress_Debug_Info}.
+This boolean aspect is equivalent to @ref{f1,,pragma Suppress_Debug_Info}.
@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{14e}
+@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{152}
@section Aspect Suppress_Initialization
@geindex Suppress_Initialization
-This boolean aspect is equivalent to @ref{f2,,pragma Suppress_Initialization}.
+This boolean aspect is equivalent to @ref{f5,,pragma Suppress_Initialization}.
@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{14f}
+@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{153}
@section Aspect Test_Case
@geindex Test_Case
-This aspect is equivalent to @ref{f5,,pragma Test_Case}.
+This aspect is equivalent to @ref{f8,,pragma Test_Case}.
@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{150}
+@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{154}
@section Aspect Thread_Local_Storage
@geindex Thread_Local_Storage
-This boolean aspect is equivalent to @ref{f7,,pragma Thread_Local_Storage}.
+This boolean aspect is equivalent to @ref{fa,,pragma Thread_Local_Storage}.
@node Aspect Universal_Aliasing,Aspect Universal_Data,Aspect Thread_Local_Storage,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{151}
+@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{155}
@section Aspect Universal_Aliasing
@geindex Universal_Aliasing
-This boolean aspect is equivalent to @ref{102,,pragma Universal_Aliasing}.
+This boolean aspect is equivalent to @ref{105,,pragma Universal_Aliasing}.
@node Aspect Universal_Data,Aspect Unmodified,Aspect Universal_Aliasing,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-universal-data}@anchor{152}
+@anchor{gnat_rm/implementation_defined_aspects aspect-universal-data}@anchor{156}
@section Aspect Universal_Data
@geindex Universal_Data
-This aspect is equivalent to @ref{103,,pragma Universal_Data}.
+This aspect is equivalent to @ref{106,,pragma Universal_Data}.
@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Data,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{153}
+@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{157}
@section Aspect Unmodified
@geindex Unmodified
-This boolean aspect is equivalent to @ref{106,,pragma Unmodified}.
+This boolean aspect is equivalent to @ref{108,,pragma Unmodified}.
@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{154}
+@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{158}
@section Aspect Unreferenced
@geindex Unreferenced
-This boolean aspect is equivalent to @ref{107,,pragma Unreferenced}. Note that
+This boolean aspect is equivalent to @ref{10a,,pragma Unreferenced}. Note that
in the case of formal parameters, it is not permitted to have aspects for
a formal parameter, so in this case the pragma form must be used.
@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{155}
+@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{159}
@section Aspect Unreferenced_Objects
@geindex Unreferenced_Objects
-This boolean aspect is equivalent to @ref{109,,pragma Unreferenced_Objects}.
+This boolean aspect is equivalent to @ref{10c,,pragma Unreferenced_Objects}.
@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{156}
+@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15a}
@section Aspect Value_Size
@geindex Value_Size
-This aspect is equivalent to @ref{157,,attribute Value_Size}.
+This aspect is equivalent to @ref{15b,,attribute Value_Size}.
@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{158}
+@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{15c}
@section Aspect Volatile_Full_Access
@geindex Volatile_Full_Access
-This boolean aspect is equivalent to @ref{112,,pragma Volatile_Full_Access}.
+This boolean aspect is equivalent to @ref{115,,pragma Volatile_Full_Access}.
@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{159}
+@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{15d}
@section Aspect Volatile_Function
@geindex Volatile_Function
-This boolean aspect is equivalent to @ref{115,,pragma Volatile_Function}.
+This boolean aspect is equivalent to @ref{118,,pragma Volatile_Function}.
@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects
-@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{15a}
+@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{15e}
@section Aspect Warnings
@geindex Warnings
-This aspect is equivalent to the two argument form of @ref{117,,pragma Warnings},
-where the first argument is @cite{ON} or @cite{OFF} and the second argument
+This aspect is equivalent to the two argument form of @ref{11a,,pragma Warnings},
+where the first argument is @code{ON} or @code{OFF} and the second argument
is the entity.
@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top
-@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{15b}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{15c}
+@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{15f}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{160}
@chapter Implementation Defined Attributes
@end menu
@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{15d}
+@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{161}
@section Attribute Abort_Signal
@geindex Abort_Signal
-@cite{Standard'Abort_Signal} (@cite{Standard} is the only allowed
+@code{Standard'Abort_Signal} (@code{Standard} is the only allowed
prefix) provides the entity for the special exception used to signal
task abort or asynchronous transfer of control. Normally this attribute
should only be used in the tasking runtime (it is highly peculiar, and
intercept the abort exception).
@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{15e}
+@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{162}
@section Attribute Address_Size
-@geindex Size of `Address`
+@geindex Size of `@w{`}Address`@w{`}
@geindex Address_Size
-@cite{Standard'Address_Size} (@cite{Standard} is the only allowed
+@code{Standard'Address_Size} (@code{Standard} is the only allowed
prefix) is a static constant giving the number of bits in an
-@cite{Address}. It is the same value as System.Address'Size,
+@code{Address}. It is the same value as System.Address'Size,
but has the advantage of being static, while a direct
reference to System.Address'Size is nonstatic because Address
is a private type.
@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{15f}
+@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{163}
@section Attribute Asm_Input
@geindex Asm_Input
-The @cite{Asm_Input} attribute denotes a function that takes two
+The @code{Asm_Input} attribute denotes a function that takes two
parameters. The first is a string, the second is an expression of the
type designated by the prefix. The first (string) argument is required
to be a static expression, and is the constraint for the parameter,
value to be used as the input argument. The possible values for the
constant are the same as those used in the RTL, and are dependent on
the configuration file used to built the GCC back end.
-@ref{160,,Machine Code Insertions}
+@ref{164,,Machine Code Insertions}
@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{161}
+@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{165}
@section Attribute Asm_Output
@geindex Asm_Output
-The @cite{Asm_Output} attribute denotes a function that takes two
+The @code{Asm_Output} attribute denotes a function that takes two
parameters. The first is a string, the second is the name of a variable
of the type designated by the attribute prefix. The first (string)
argument is required to be a static expression and designates the
result. The possible values for constraint are the same as those used in
the RTL, and are dependent on the configuration file used to build the
GCC back end. If there are no output operands, then this argument may
-either be omitted, or explicitly given as @cite{No_Output_Operands}.
-@ref{160,,Machine Code Insertions}
+either be omitted, or explicitly given as @code{No_Output_Operands}.
+@ref{164,,Machine Code Insertions}
@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{162}
+@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{166}
@section Attribute Atomic_Always_Lock_Free
@geindex Atomic_Always_Lock_Free
-The prefix of the @cite{Atomic_Always_Lock_Free} attribute is a type.
+The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type.
The result is a Boolean value which is True if the type has discriminants,
and False otherwise. The result indicate whether atomic operations are
supported by the target for the given type.
@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{163}
+@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{167}
@section Attribute Bit
@geindex Bit
-@code{obj'Bit}, where @cite{obj} is any object, yields the bit
+@code{obj'Bit}, where @code{obj} is any object, yields the bit
offset within the storage unit (byte) that contains the first bit of
storage allocated for the object. The value of this attribute is of the
-type @cite{Universal_Integer}, and is always a non-negative number not
-exceeding the value of @cite{System.Storage_Unit}.
+type @emph{universal_integer}, and is always a non-negative number not
+exceeding the value of @code{System.Storage_Unit}.
For an object that is a variable or a constant allocated in a register,
the value is zero. (The use of this attribute does not force the
matching actual parameter.
For an access object the value is zero. Note that
-@code{obj.all'Bit} is subject to an @cite{Access_Check} for the
+@code{obj.all'Bit} is subject to an @code{Access_Check} for the
designated object. Similarly for a record component
@code{X.C'Bit} is subject to a discriminant check and
@code{X(I).Bit} and @code{X(I1..I2)'Bit}
are subject to index checks.
This attribute is designed to be compatible with the DEC Ada 83 definition
-and implementation of the @cite{Bit} attribute.
+and implementation of the @code{Bit} attribute.
@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{164}
+@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{168}
@section Attribute Bit_Position
@geindex Bit_Position
-@code{R.C'Bit_Position}, where @cite{R} is a record object and @cite{C} is one
+@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one
of the fields of the record type, yields the bit
offset within the record contains the first bit of
storage allocated for the object. The value of this attribute is of the
-type @cite{Universal_Integer}. The value depends only on the field
-@cite{C} and is independent of the alignment of
-the containing record @cite{R}.
+type @emph{universal_integer}. The value depends only on the field
+@code{C} and is independent of the alignment of
+the containing record @code{R}.
@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{165}
+@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{169}
@section Attribute Code_Address
@geindex Address of subprogram code
-The @cite{'Address}
+The @code{'Address}
attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
intended effect seems to be to provide
an address value which can be used to call the subprogram by means of
pragma Import (Ada, L);
@end example
-A call to @cite{L} is then expected to result in a call to @cite{K}.
+A call to @code{L} is then expected to result in a call to @code{K}.
In Ada 83, where there were no access-to-subprogram values, this was
a common work-around for getting the effect of an indirect call.
-GNAT implements the above use of @cite{Address} and the technique
+GNAT implements the above use of @code{Address} and the technique
illustrated by the example code works correctly.
However, for some purposes, it is useful to have the address of the start
of the generated code for the subprogram. On some architectures, this is
-not necessarily the same as the @cite{Address} value described above.
-For example, the @cite{Address} value may reference a subprogram
+not necessarily the same as the @code{Address} value described above.
+For example, the @code{Address} value may reference a subprogram
descriptor rather than the subprogram itself.
-The @cite{'Code_Address} attribute, which can only be applied to
+The @code{'Code_Address} attribute, which can only be applied to
subprogram entities, always returns the address of the start of the
generated code of the specified subprogram, which may or may not be
-the same value as is returned by the corresponding @cite{'Address}
+the same value as is returned by the corresponding @code{'Address}
attribute.
@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{166}
+@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16a}
@section Attribute Compiler_Version
@geindex Compiler_Version
-@cite{Standard'Compiler_Version} (@cite{Standard} is the only allowed
+@code{Standard'Compiler_Version} (@code{Standard} is the only allowed
prefix) yields a static string identifying the version of the compiler
being used to compile the unit containing the attribute reference.
@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{167}
+@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16b}
@section Attribute Constrained
@geindex Constrained
-In addition to the usage of this attribute in the Ada RM, @cite{GNAT}
-also permits the use of the @cite{'Constrained} attribute
+In addition to the usage of this attribute in the Ada RM, GNAT
+also permits the use of the @code{'Constrained} attribute
in a generic template
for any type, including types without discriminants. The value of this
attribute in the generic instance when applied to a scalar type or a
-record type without discriminants is always @cite{True}. This usage is
+record type without discriminants is always @code{True}. This usage is
compatible with older Ada compilers, including notably DEC Ada.
@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{168}
+@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{16c}
@section Attribute Default_Bit_Order
@geindex Default_Bit_Order
-@cite{Standard'Default_Bit_Order} (@cite{Standard} is the only
-permissible prefix), provides the value @cite{System.Default_Bit_Order}
-as a @cite{Pos} value (0 for @cite{High_Order_First}, 1 for
-@cite{Low_Order_First}). This is used to construct the definition of
-@cite{Default_Bit_Order} in package @cite{System}.
+@code{Standard'Default_Bit_Order} (@code{Standard} is the only
+permissible prefix), provides the value @code{System.Default_Bit_Order}
+as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
+@code{Low_Order_First}). This is used to construct the definition of
+@code{Default_Bit_Order} in package @code{System}.
@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{169}
+@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{16d}
@section Attribute Default_Scalar_Storage_Order
@geindex Default_Scalar_Storage_Order
-@cite{Standard'Default_Scalar_Storage_Order} (@cite{Standard} is the only
+@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only
permissible prefix), provides the current value of the default scalar storage
-order (as specified using pragma @cite{Default_Scalar_Storage_Order}, or
-equal to @cite{Default_Bit_Order} if unspecified) as a
-@cite{System.Bit_Order} value. This is a static attribute.
+order (as specified using pragma @code{Default_Scalar_Storage_Order}, or
+equal to @code{Default_Bit_Order} if unspecified) as a
+@code{System.Bit_Order} value. This is a static attribute.
@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{16a}
+@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{16e}
@section Attribute Deref
@geindex Deref
-The attribute @cite{typ'Deref(expr)} where @cite{expr} is of type @cite{System.Address} yields
-the variable of type @cite{typ} that is located at the given address. It is similar
-to @cite{(totyp (expr).all)}, where @cite{totyp} is an unchecked conversion from address to
+The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields
+the variable of type @code{typ} that is located at the given address. It is similar
+to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to
a named access-to-@cite{typ} type, except that it yields a variable, so it can be
used on the left side of an assignment.
@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{16b}
+@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{16f}
@section Attribute Descriptor_Size
@geindex Descriptor_Size
-Nonstatic attribute @cite{Descriptor_Size} returns the size in bits of the
+Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the
descriptor allocated for a type. The result is non-zero only for unconstrained
array types and the returned value is of type universal integer. In GNAT, an
array descriptor contains bounds information and is located immediately before
The attribute takes into account any additional padding due to type alignment.
In the example above, the descriptor contains two values of type
-@cite{Positive} representing the low and high bound. Since @cite{Positive} has
-a size of 31 bits and an alignment of 4, the descriptor size is @cite{2 * Positive'Size + 2} or 64 bits.
+@code{Positive} representing the low and high bound. Since @code{Positive} has
+a size of 31 bits and an alignment of 4, the descriptor size is @code{2 * Positive'Size + 2} or 64 bits.
@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{16c}
+@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{170}
@section Attribute Elaborated
@geindex Elaborated
-The prefix of the @cite{'Elaborated} attribute must be a unit name. The
+The prefix of the @code{'Elaborated} attribute must be a unit name. The
value is a Boolean which indicates whether or not the given unit has been
elaborated. This attribute is primarily intended for internal use by the
generated code for dynamic elaboration checking, but it can also be used
elaboration, the value is always False for such units.
@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{16d}
+@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{171}
@section Attribute Elab_Body
error.
@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{16e}
+@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{172}
@section Attribute Elab_Spec
some error.
@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{16f}
+@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{173}
@section Attribute Elab_Subp_Body
otherwise.
@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{170}
+@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{174}
@section Attribute Emax
@geindex Emax
-The @cite{Emax} attribute is provided for compatibility with Ada 83. See
+The @code{Emax} attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{171}
+@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{175}
@section Attribute Enabled
@geindex Enabled
-The @cite{Enabled} attribute allows an application program to check at compile
+The @code{Enabled} attribute allows an application program to check at compile
time to see if the designated check is currently enabled. The prefix is a
simple identifier, referencing any predefined check name (other than
-@cite{All_Checks}) or a check name introduced by pragma Check_Name. If
+@code{All_Checks}) or a check name introduced by pragma Check_Name. If
no argument is given for the attribute, the check is for the general state
of the check, if an argument is given, then it is an entity name, and the
-check indicates whether an @cite{Suppress} or @cite{Unsuppress} has been
+check indicates whether an @code{Suppress} or @code{Unsuppress} has been
given naming the entity (if not, then the argument is ignored).
Note that instantiations inherit the check status at the point of the
instantiation, so a useful idiom is to have a library package that
-introduces a check name with @cite{pragma Check_Name}, and then contains
-generic packages or subprograms which use the @cite{Enabled} attribute
+introduces a check name with @code{pragma Check_Name}, and then contains
+generic packages or subprograms which use the @code{Enabled} attribute
to see if the check is enabled. A user of this package can then issue
-a @cite{pragma Suppress} or @cite{pragma Unsuppress} before instantiating
+a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating
the package or subprogram, controlling whether the check will be present.
@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{172}
+@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{176}
@section Attribute Enum_Rep
@geindex Enum_Rep
-For every enumeration subtype @cite{S}, @code{S'Enum_Rep} denotes a
+For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a
function with the following spec:
@example
function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>;
@end example
-It is also allowable to apply @cite{Enum_Rep} directly to an object of an
+It is also allowable to apply @code{Enum_Rep} directly to an object of an
enumeration type or to a non-overloaded enumeration
literal. In this case @code{S'Enum_Rep} is equivalent to
-@code{typ'Enum_Rep(S)} where @cite{typ} is the type of the
+@code{typ'Enum_Rep(S)} where @code{typ} is the type of the
enumeration literal or object.
The function returns the representation value for the given enumeration
-value. This will be equal to value of the @cite{Pos} attribute in the
+value. This will be equal to value of the @code{Pos} attribute in the
absence of an enumeration representation clause. This is a static
attribute (i.e.,:the result is static if the argument is static).
@code{S'Enum_Rep} can also be used with integer types and objects,
in which case it simply returns the integer value. The reason for this
-is to allow it to be used for @cite{(<>)} discrete formal arguments in
+is to allow it to be used for @code{(<>)} discrete formal arguments in
a generic unit that can be instantiated with either enumeration types
-or integer types. Note that if @cite{Enum_Rep} is used on a modular
+or integer types. Note that if @code{Enum_Rep} is used on a modular
type whose upper bound exceeds the upper bound of the largest signed
integer type, and the argument is a variable, so that the universal
-integer calculation is done at run time, then the call to @cite{Enum_Rep}
-may raise @cite{Constraint_Error}.
+integer calculation is done at run time, then the call to @code{Enum_Rep}
+may raise @code{Constraint_Error}.
@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{173}
+@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{177}
@section Attribute Enum_Val
@geindex Enum_Val
-For every enumeration subtype @cite{S}, @code{S'Enum_Val} denotes a
+For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a
function with the following spec:
@example
The function returns the enumeration value whose representation matches the
argument, or raises Constraint_Error if no enumeration literal of the type
has the matching value.
-This will be equal to value of the @cite{Val} attribute in the
+This will be equal to value of the @code{Val} attribute in the
absence of an enumeration representation clause. This is a static
attribute (i.e., the result is static if the argument is static).
@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{174}
+@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{178}
@section Attribute Epsilon
@geindex Epsilon
-The @cite{Epsilon} attribute is provided for compatibility with Ada 83. See
+The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{175}
+@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{179}
@section Attribute Fast_Math
@geindex Fast_Math
-@cite{Standard'Fast_Math} (@cite{Standard} is the only allowed
+@code{Standard'Fast_Math} (@code{Standard} is the only allowed
prefix) yields a static Boolean value that is True if pragma
-@cite{Fast_Math} is active, and False otherwise.
+@code{Fast_Math} is active, and False otherwise.
@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{176}
+@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17a}
@section Attribute Finalization_Size
@geindex Finalization_Size
-The prefix of attribute @cite{Finalization_Size} must be an object or
+The prefix of attribute @code{Finalization_Size} must be an object or
a non-class-wide type. This attribute returns the size of any hidden data
reserved by the compiler to handle finalization-related actions. The type of
-the attribute is @cite{universal_integer}.
+the attribute is @emph{universal_integer}.
-@cite{Finalization_Size} yields a value of zero for a type with no controlled
+@code{Finalization_Size} yields a value of zero for a type with no controlled
parts, an object whose type has no controlled parts, or an object of a
class-wide type whose tag denotes a type with no controlled parts.
Note that only heap-allocated objects contain finalization data.
@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{177}
+@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17b}
@section Attribute Fixed_Value
@geindex Fixed_Value
-For every fixed-point type @cite{S}, @code{S'Fixed_Value} denotes a
+For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a
function with the following specification:
@example
function S'Fixed_Value (Arg : <Universal_Integer>) return S;
@end example
-The value returned is the fixed-point value @cite{V} such that:
+The value returned is the fixed-point value @code{V} such that:
@example
V = Arg * S'Small
@end example
The effect is thus similar to first converting the argument to the
-integer type used to represent @cite{S}, and then doing an unchecked
+integer type used to represent @code{S}, and then doing an unchecked
conversion to the fixed-point type. The difference is
that there are full range checks, to ensure that the result is in range.
This attribute is primarily intended for use in implementation of the
input-output functions for fixed-point values.
@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{178}
+@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{17c}
@section Attribute From_Any
stubs in the context of the Distributed Systems Annex.
@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{179}
+@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{17d}
@section Attribute Has_Access_Values
@geindex Has_Access_Values
-The prefix of the @cite{Has_Access_Values} attribute is a type. The result
+The prefix of the @code{Has_Access_Values} attribute is a type. The result
is a Boolean value which is True if the is an access type, or is a composite
type with a component (at any nesting depth) that is an access type, and is
False otherwise.
indicates whether or not the corresponding actual type has access values.
@node Attribute Has_Discriminants,Attribute Img,Attribute Has_Access_Values,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{17a}
+@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{17e}
@section Attribute Has_Discriminants
@geindex Has_Discriminants
-The prefix of the @cite{Has_Discriminants} attribute is a type. The result
+The prefix of the @code{Has_Discriminants} attribute is a type. The result
is a Boolean value which is True if the type has discriminants, and False
otherwise. The intended use of this attribute is in conjunction with generic
definitions. If the attribute is applied to a generic private type, it
indicates whether or not the corresponding actual type has discriminants.
@node Attribute Img,Attribute Integer_Value,Attribute Has_Discriminants,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{17b}
+@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{17f}
@section Attribute Img
@geindex Img
-The @cite{Img} attribute differs from @cite{Image} in that it is applied
+The @code{Img} attribute differs from @code{Image} in that it is applied
directly to an object, and yields the same result as
-@cite{Image} for the subtype of the object. This is convenient for
+@code{Image} for the subtype of the object. This is convenient for
debugging:
@example
Put_Line ("X = " & T'Image (X));
@end example
-where @cite{T} is the (sub)type of the object @cite{X}.
+where @code{T} is the (sub)type of the object @code{X}.
-Note that technically, in analogy to @cite{Image},
-@cite{X'Img} returns a parameterless function
+Note that technically, in analogy to @code{Image},
+@code{X'Img} returns a parameterless function
that returns the appropriate string when called. This means that
-@cite{X'Img} can be renamed as a function-returning-string, or used
+@code{X'Img} can be renamed as a function-returning-string, or used
in an instantiation as a function parameter.
@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Img,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{17c}
+@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{180}
@section Attribute Integer_Value
@geindex Integer_Value
-For every integer type @cite{S}, @code{S'Integer_Value} denotes a
+For every integer type @code{S}, @code{S'Integer_Value} denotes a
function with the following spec:
@example
function S'Integer_Value (Arg : <Universal_Fixed>) return S;
@end example
-The value returned is the integer value @cite{V}, such that:
+The value returned is the integer value @code{V}, such that:
@example
Arg = V * T'Small
@end example
-where @cite{T} is the type of @cite{Arg}.
+where @code{T} is the type of @code{Arg}.
The effect is thus similar to first doing an unchecked conversion from
the fixed-point type to its corresponding implementation type, and then
converting the result to the target integer type. The difference is
standard input-output functions for fixed-point values.
@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{17d}
+@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{181}
@section Attribute Invalid_Value
relevant environment variables at run time.
@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{17e}
+@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{182}
@section Attribute Iterable
Equivalent to Aspect Iterable.
@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{17f}
+@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{183}
@section Attribute Large
@geindex Large
-The @cite{Large} attribute is provided for compatibility with Ada 83. See
+The @code{Large} attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
@node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{180}
+@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{184}
@section Attribute Library_Level
@geindex Library_Level
-@cite{P'Library_Level}, where P is an entity name,
+@code{P'Library_Level}, where P is an entity name,
returns a Boolean value which is True if the entity is declared
at the library level, and False otherwise. Note that within a
generic instantition, the name of the generic unit denotes the
@end example
@node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{181}
+@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{185}
@section Attribute Lock_Free
@geindex Lock_Free
-@cite{P'Lock_Free}, where P is a protected object, returns True if a
-pragma @cite{Lock_Free} applies to P.
+@code{P'Lock_Free}, where P is a protected object, returns True if a
+pragma @code{Lock_Free} applies to P.
@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{182}
+@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{186}
@section Attribute Loop_Entry
X'Loop_Entry [(loop_name)]
@end example
-The @cite{Loop_Entry} attribute is used to refer to the value that an
+The @code{Loop_Entry} attribute is used to refer to the value that an
expression had upon entry to a given loop in much the same way that the
-@cite{Old} attribute in a subprogram postcondition can be used to refer
+@code{Old} attribute in a subprogram postcondition can be used to refer
to the value an expression had upon entry to the subprogram. The
relevant loop is either identified by the given loop name, or it is the
innermost enclosing loop when no loop name is given.
-A @cite{Loop_Entry} attribute can only occur within a
-@cite{Loop_Variant} or @cite{Loop_Invariant} pragma. A common use of
-@cite{Loop_Entry} is to compare the current value of objects with their
-initial value at loop entry, in a @cite{Loop_Invariant} pragma.
+A @code{Loop_Entry} attribute can only occur within a
+@code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of
+@code{Loop_Entry} is to compare the current value of objects with their
+initial value at loop entry, in a @code{Loop_Invariant} pragma.
-The effect of using @cite{X'Loop_Entry} is the same as declaring
-a constant initialized with the initial value of @cite{X} at loop
+The effect of using @code{X'Loop_Entry} is the same as declaring
+a constant initialized with the initial value of @code{X} at loop
entry. This copy is not performed if the loop is not entered, or if the
corresponding pragmas are ignored or disabled.
@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{183}
+@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{187}
@section Attribute Machine_Size
@geindex Machine_Size
-This attribute is identical to the @cite{Object_Size} attribute. It is
+This attribute is identical to the @code{Object_Size} attribute. It is
provided for compatibility with the DEC Ada 83 attribute of this name.
@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{184}
+@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{188}
@section Attribute Mantissa
@geindex Mantissa
-The @cite{Mantissa} attribute is provided for compatibility with Ada 83. See
+The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
@node Attribute Maximum_Alignment,Attribute Mechanism_Code,Attribute Mantissa,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{185}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{186}
+@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{189}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18a}
@section Attribute Maximum_Alignment
@geindex Maximum_Alignment
-@cite{Standard'Maximum_Alignment} (@cite{Standard} is the only
+@code{Standard'Maximum_Alignment} (@code{Standard} is the only
permissible prefix) provides the maximum useful alignment value for the
target. This is a static value that can be used to specify the alignment
for an object, guaranteeing that it is properly aligned in all
cases.
@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Maximum_Alignment,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{187}
+@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{18b}
@section Attribute Mechanism_Code
@geindex Mechanism_Code
-@code{function'Mechanism_Code} yields an integer code for the
-mechanism used for the result of function, and
-@code{subprogram'Mechanism_Code (n)} yields the mechanism
-used for formal parameter number @cite{n} (a static integer value with 1
-meaning the first parameter) of @cite{subprogram}. The code returned is:
+@code{func'Mechanism_Code} yields an integer code for the
+mechanism used for the result of function @code{func}, and
+@code{subprog'Mechanism_Code (n)} yields the mechanism
+used for formal parameter number @emph{n} (a static integer value, with 1
+meaning the first parameter) of subprogram @code{subprog}. The code returned is:
@table @asis
@end table
@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{188}
+@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{18c}
@section Attribute Null_Parameter
@geindex Null_Parameter
A reference @code{T'Null_Parameter} denotes an imaginary object of
-type or subtype @cite{T} allocated at machine address zero. The attribute
+type or subtype @code{T} allocated at machine address zero. The attribute
is allowed only as the default expression of a formal parameter, or as
an actual expression of a subprogram call. In either case, the
subprogram must be imported.
This capability is needed to specify that a zero address should be
passed for a record or other composite object passed by reference.
-There is no way of indicating this without the @cite{Null_Parameter}
+There is no way of indicating this without the @code{Null_Parameter}
attribute.
@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{13b}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{189}
+@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{13f}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{18d}
@section Attribute Object_Size
The size of an object is not necessarily the same as the size of the type
of an object. This is because by default object sizes are increased to be
a multiple of the alignment of the object. For example,
-@cite{Natural'Size} is
-31, but by default objects of type @cite{Natural} will have a size of 32 bits.
+@code{Natural'Size} is
+31, but by default objects of type @code{Natural} will have a size of 32 bits.
Similarly, a record containing an integer and a character:
@example
end record;
@end example
-will have a size of 40 (that is @cite{Rec'Size} will be 40). The
+will have a size of 40 (that is @code{Rec'Size} will be 40). The
alignment will be 4, because of the
integer field, and so the default size of record objects for this type
will be 64 (8 bytes).
A consequence of this capability is that different object sizes can be
given to subtypes that would otherwise be considered in Ada to be
statically matching. But it makes no sense to consider such subtypes
-as statically matching. Consequently, in @cite{GNAT} we add a rule
+as statically matching. Consequently, GNAT adds a rule
to the static matching rules that requires object sizes to match.
Consider this example:
@end example
In the absence of lines 5 and 6,
-types @cite{R1} and @cite{R2} statically match and
+types @code{R1} and @code{R2} statically match and
hence the conversion on line 12 is legal. But since lines 5 and 6
-cause the object sizes to differ, @cite{GNAT} considers that types
-@cite{R1} and @cite{R2} are not statically matching, and line 12
+cause the object sizes to differ, GNAT considers that types
+@code{R1} and @code{R2} are not statically matching, and line 12
generates the diagnostic shown above.
Similar additional checks are performed in other contexts requiring
statically matching subtypes.
@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{18a}
+@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{18e}
@section Attribute Old
@geindex Old
-In addition to the usage of @cite{Old} defined in the Ada 2012 RM (usage
-within @cite{Post} aspect), GNAT also permits the use of this attribute
-in implementation defined pragmas @cite{Postcondition},
-@cite{Contract_Cases} and @cite{Test_Case}. Also usages of
-@cite{Old} which would be illegal according to the Ada 2012 RM
+In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage
+within @code{Post} aspect), GNAT also permits the use of this attribute
+in implementation defined pragmas @code{Postcondition},
+@code{Contract_Cases} and @code{Test_Case}. Also usages of
+@code{Old} which would be illegal according to the Ada 2012 RM
definition are allowed under control of
-implementation defined pragma @cite{Unevaluated_Use_Of_Old}.
+implementation defined pragma @code{Unevaluated_Use_Of_Old}.
@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{18b}
+@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{18f}
@section Attribute Passed_By_Reference
@geindex Passed_By_Reference
-@code{type'Passed_By_Reference} for any subtype @cite{type} returns
-a value of type @cite{Boolean} value that is @cite{True} if the type is
-normally passed by reference and @cite{False} if the type is normally
-passed by copy in calls. For scalar types, the result is always @cite{False}
+@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns
+a value of type @code{Boolean} value that is @code{True} if the type is
+normally passed by reference and @code{False} if the type is normally
+passed by copy in calls. For scalar types, the result is always @code{False}
and is static. For non-scalar types, the result is nonstatic.
@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{18c}
+@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{190}
@section Attribute Pool_Address
@geindex Pool_Address
-@code{X'Pool_Address} for any object @cite{X} returns the address
+@code{X'Pool_Address} for any object @code{X} returns the address
of X within its storage pool. This is the same as
@code{X'Address}, except that for an unconstrained array whose
bounds are allocated just before the first component,
@code{wherever the object is allocated}, which could be a
user-defined storage pool,
the global heap, on the stack, or in a static memory area.
-For an object created by @cite{new}, @code{Ptr.all'Pool_Address} is
-what is passed to @cite{Allocate} and returned from @cite{Deallocate}.
+For an object created by @code{new}, @code{Ptr.all'Pool_Address} is
+what is passed to @code{Allocate} and returned from @code{Deallocate}.
@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{18d}
+@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{191}
@section Attribute Range_Length
@geindex Range_Length
-@code{type'Range_Length} for any discrete type @cite{type} yields
+@code{typ'Range_Length} for any discrete type @cite{typ} yields
the number of values represented by the subtype (zero for a null
-range). The result is static for static subtypes. @cite{Range_Length}
+range). The result is static for static subtypes. @code{Range_Length}
applied to the index subtype of a one dimensional array always gives the
-same result as @cite{Length} applied to the array itself.
+same result as @code{Length} applied to the array itself.
@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{18e}
+@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{192}
@section Attribute Restriction_Set
In the case of the first form, the only restriction names
allowed are parameterless restrictions that are checked
for consistency at bind time. For a complete list see the
-subtype @cite{System.Rident.Partition_Boolean_Restrictions}.
+subtype @code{System.Rident.Partition_Boolean_Restrictions}.
The result returned is True if the restriction is known to
be in effect, and False if the restriction is known not to
so they do not have a type.
@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{18f}
+@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{193}
@section Attribute Result
see the description of pragma Postcondition.
@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{190}
+@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{194}
@section Attribute Safe_Emax
@geindex Safe_Emax
-The @cite{Safe_Emax} attribute is provided for compatibility with Ada 83. See
+The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{191}
+@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{195}
@section Attribute Safe_Large
@geindex Safe_Large
-The @cite{Safe_Large} attribute is provided for compatibility with Ada 83. See
+The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
@node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{192}
+@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{196}
@section Attribute Safe_Small
@geindex Safe_Small
-The @cite{Safe_Small} attribute is provided for compatibility with Ada 83. See
+The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See
the Ada 83 reference manual for an exact description of the semantics of
this attribute.
@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{193}@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{148}
+@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{197}@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{14c}
@section Attribute Scalar_Storage_Order
@geindex Scalar_Storage_Order
-For every array or record type @cite{S}, the representation attribute
-@cite{Scalar_Storage_Order} denotes the order in which storage elements
+For every array or record type @code{S}, the representation attribute
+@code{Scalar_Storage_Order} denotes the order in which storage elements
that make up scalar components are ordered within S. The value given must
be a static expression of type System.Bit_Order. The following is an example
of the use of this feature:
-- the former is used.
@end example
-Other properties are as for standard representation attribute @cite{Bit_Order},
-as defined by Ada RM 13.5.3(4). The default is @cite{System.Default_Bit_Order}.
+Other properties are as for standard representation attribute @code{Bit_Order},
+as defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}.
-For a record type @cite{T}, if @code{T'Scalar_Storage_Order} is
+For a record type @code{T}, if @code{T'Scalar_Storage_Order} is
specified explicitly, it shall be equal to @code{T'Bit_Order}. Note:
-this means that if a @cite{Scalar_Storage_Order} attribute definition
-clause is not confirming, then the type's @cite{Bit_Order} shall be
+this means that if a @code{Scalar_Storage_Order} attribute definition
+clause is not confirming, then the type's @code{Bit_Order} shall be
specified explicitly and set to the same value.
Derived types inherit an explicitly set scalar storage order from their parent
storage order for the derived type. For a record extension, the derived type
must have the same scalar storage order as the parent type.
-A component of a record or array type that is a bit-packed array, or that
-does not start on a byte boundary, must have the same scalar storage order
-as the enclosing record or array type.
+A component of a record type that is itself a record or an array and that does
+not start and end on a byte boundary must have have the same scalar storage
+order as the record type. A component of a bit-packed array type that is itself
+a record or an array must have the same scalar storage order as the array type.
-No component of a type that has an explicit @cite{Scalar_Storage_Order}
+No component of a type that has an explicit @code{Scalar_Storage_Order}
attribute definition may be aliased.
-A confirming @cite{Scalar_Storage_Order} attribute definition clause (i.e.
-with a value equal to @cite{System.Default_Bit_Order}) has no effect.
+A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e.
+with a value equal to @code{System.Default_Bit_Order}) has no effect.
If the opposite storage order is specified, then whenever the value of
-a scalar component of an object of type @cite{S} is read, the storage
+a scalar component of an object of type @code{S} is read, the storage
elements of the enclosing machine scalar are first reversed (before
retrieving the component value, possibly applying some shift and mask
operatings on the enclosing machine scalar), and the opposite operation
@item
the underlying storage elements are those at positions
-@cite{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)}
+@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)}
@item
the sequence of underlying storage elements shall have
@item
the enclosing machine scalar is defined as the smallest machine
scalar starting at a position no greater than
-@cite{position + first_bit / storage_element_size} and covering
-storage elements at least up to @cite{position + (last_bit + storage_element_size - 1) / storage_element_size}
+@code{position + first_bit / storage_element_size} and covering
+storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`}
@item
the position of the component is interpreted relative to that machine
If no scalar storage order is specified for a type (either directly, or by
inheritance in the case of a derived type), then the default is normally
the native ordering of the target, but this default can be overridden using
-pragma @cite{Default_Scalar_Storage_Order}.
+pragma @code{Default_Scalar_Storage_Order}.
-Note that if a component of @cite{T} is itself of a record or array type,
-the specfied @cite{Scalar_Storage_Order} does @emph{not} apply to that nested type:
+Note that if a component of @code{T} is itself of a record or array type,
+the specfied @code{Scalar_Storage_Order} does @emph{not} apply to that nested type:
an explicit attribute definition clause must be provided for the component
type as well if desired.
attributes.
@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e0}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{194}
+@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e3}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{198}
@section Attribute Simple_Storage_Pool
@geindex Simple_Storage_Pool
-For every nonformal, nonderived access-to-object type @cite{Acc}, the
-representation attribute @cite{Simple_Storage_Pool} may be specified
+For every nonformal, nonderived access-to-object type @code{Acc}, the
+representation attribute @code{Simple_Storage_Pool} may be specified
via an attribute_definition_clause (or by specifying the equivalent aspect):
@example
@end example
The name given in an attribute_definition_clause for the
-@cite{Simple_Storage_Pool} attribute shall denote a variable of
+@code{Simple_Storage_Pool} attribute shall denote a variable of
a 'simple storage pool type' (see pragma @cite{Simple_Storage_Pool_Type}).
The use of this attribute is only allowed for a prefix denoting a type
of the variable specified as the simple storage pool of the access type,
and the attribute denotes that variable.
-It is illegal to specify both @cite{Storage_Pool} and @cite{Simple_Storage_Pool}
+It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool}
for the same access type.
-If the @cite{Simple_Storage_Pool} attribute has been specified for an access
-type, then applying the @cite{Storage_Pool} attribute to the type is flagged
-with a warning and its evaluation raises the exception @cite{Program_Error}.
+If the @code{Simple_Storage_Pool} attribute has been specified for an access
+type, then applying the @code{Storage_Pool} attribute to the type is flagged
+with a warning and its evaluation raises the exception @code{Program_Error}.
If the Simple_Storage_Pool attribute has been specified for an access
-type @cite{S}, then the evaluation of the attribute @code{S'Storage_Size}
+type @code{S}, then the evaluation of the attribute @code{S'Storage_Size}
returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)},
which is intended to indicate the number of storage elements reserved for
the simple storage pool. If the Storage_Size function has not been defined
for the simple storage pool type, then this attribute returns zero.
-If an access type @cite{S} has a specified simple storage pool of type
-@cite{SSP}, then the evaluation of an allocator for that access type calls
-the primitive @cite{Allocate} procedure for type @cite{SSP}, passing
+If an access type @code{S} has a specified simple storage pool of type
+@code{SSP}, then the evaluation of an allocator for that access type calls
+the primitive @code{Allocate} procedure for type @code{SSP}, passing
@code{S'Simple_Storage_Pool} as the pool parameter. The detailed
semantics of such allocators is the same as those defined for allocators
in section 13.11 of the @cite{Ada Reference Manual}, with the term
-@cite{simple storage pool} substituted for @cite{storage pool}.
+@emph{simple storage pool} substituted for @emph{storage pool}.
-If an access type @cite{S} has a specified simple storage pool of type
-@cite{SSP}, then a call to an instance of the @cite{Ada.Unchecked_Deallocation}
-for that access type invokes the primitive @cite{Deallocate} procedure
-for type @cite{SSP}, passing @code{S'Simple_Storage_Pool} as the pool
+If an access type @code{S} has a specified simple storage pool of type
+@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation}
+for that access type invokes the primitive @code{Deallocate} procedure
+for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool
parameter. The detailed semantics of such unchecked deallocations is the same
as defined in section 13.11.2 of the Ada Reference Manual, except that the
-term 'simple storage pool' is substituted for 'storage pool'.
+term @emph{simple storage pool} is substituted for @emph{storage pool}.
@node Attribute Small,Attribute Storage_Unit,Attribute Simple_Storage_Pool,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{195}
+@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{199}
@section Attribute Small
@geindex Small
-The @cite{Small} attribute is defined in Ada 95 (and Ada 2005) only for
+The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for
fixed-point types.
GNAT also allows this attribute to be applied to floating-point types
for compatibility with Ada 83. See
this attribute when applied to floating-point types.
@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{196}
+@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{19a}
@section Attribute Storage_Unit
@geindex Storage_Unit
-@cite{Standard'Storage_Unit} (@cite{Standard} is the only permissible
-prefix) provides the same value as @cite{System.Storage_Unit}.
+@code{Standard'Storage_Unit} (@code{Standard} is the only permissible
+prefix) provides the same value as @code{System.Storage_Unit}.
@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{197}
+@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{19b}
@section Attribute Stub_Type
remote call, if necessary, using the information in the stub object
to locate the target partition, etc.
-For a prefix @cite{T} that denotes a remote access-to-classwide type,
-@cite{T'Stub_Type} denotes the type of the corresponding stub objects.
+For a prefix @code{T} that denotes a remote access-to-classwide type,
+@code{T'Stub_Type} denotes the type of the corresponding stub objects.
-By construction, the layout of @cite{T'Stub_Type} is identical to that of
-type @cite{RACW_Stub_Type} declared in the internal implementation-defined
-unit @cite{System.Partition_Interface}. Use of this attribute will create
+By construction, the layout of @code{T'Stub_Type} is identical to that of
+type @code{RACW_Stub_Type} declared in the internal implementation-defined
+unit @code{System.Partition_Interface}. Use of this attribute will create
an implicit dependency on this unit.
@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{198}
+@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{19c}
@section Attribute System_Allocator_Alignment
@geindex System_Allocator_Alignment
-@cite{Standard'System_Allocator_Alignment} (@cite{Standard} is the only
+@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only
permissible prefix) provides the observable guaranted to be honored by
the system allocator (malloc). This is a static value that can be used
in user storage pools based on malloc either to reject allocation
alignment request is larger than this value.
@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{199}
+@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{19d}
@section Attribute Target_Name
@geindex Target_Name
-@cite{Standard'Target_Name} (@cite{Standard} is the only permissible
+@code{Standard'Target_Name} (@code{Standard} is the only permissible
prefix) provides a static string value that identifies the target
for the current compilation. For GCC implementations, this is the
standard gcc target name without the terminating slash (for
example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{19a}
+@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{19e}
@section Attribute To_Address
@geindex To_Address
-The @cite{System'To_Address}
-(@cite{System} is the only permissible prefix)
+The @code{System'To_Address}
+(@code{System} is the only permissible prefix)
denotes a function identical to
-@cite{System.Storage_Elements.To_Address} except that
+@code{System.Storage_Elements.To_Address} except that
it is a static attribute. This means that if its argument is
a static expression, then the result of the attribute is a
static expression. This means that such an expression can be
a 32 bits machine).
@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{19b}
+@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{19f}
@section Attribute To_Any
stubs in the context of the Distributed Systems Annex.
@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{19c}
+@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a0}
@section Attribute Type_Class
@geindex Type_Class
-@code{type'Type_Class} for any type or subtype @cite{type} yields
-the value of the type class for the full type of @cite{type}. If
-@cite{type} is a generic formal type, the value is the value for the
+@code{typ'Type_Class} for any type or subtype @cite{typ} yields
+the value of the type class for the full type of @cite{typ}. If
+@cite{typ} is a generic formal type, the value is the value for the
corresponding actual subtype. The value of this attribute is of type
@code{System.Aux_DEC.Type_Class}, which has the following definition:
Type_Class_Address);
@end example
-Protected types yield the value @cite{Type_Class_Task}, which thus
+Protected types yield the value @code{Type_Class_Task}, which thus
applies to all concurrent types. This attribute is designed to
be compatible with the DEC Ada 83 attribute of the same name.
@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{19d}
+@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a1}
@section Attribute Type_Key
@geindex Type_Key
-The @cite{Type_Key} attribute is applicable to a type or subtype and
+The @code{Type_Key} attribute is applicable to a type or subtype and
yields a value of type Standard.String containing encoded information
about the type or subtype. This provides improved compatibility with
other implementations that support this attribute.
@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{19e}
+@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1a2}
@section Attribute TypeCode
stubs in the context of the Distributed Systems Annex.
@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{19f}
+@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1a3}
@section Attribute Unconstrained_Array
@geindex Unconstrained_Array
-The @cite{Unconstrained_Array} attribute can be used with a prefix that
+The @code{Unconstrained_Array} attribute can be used with a prefix that
denotes any type or subtype. It is a static attribute that yields
-@cite{True} if the prefix designates an unconstrained array,
-and @cite{False} otherwise. In a generic instance, the result is
+@code{True} if the prefix designates an unconstrained array,
+and @code{False} otherwise. In a generic instance, the result is
still static, and yields the result of applying this test to the
generic actual.
@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1a0}
+@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1a4}
@section Attribute Universal_Literal_String
@geindex Universal_Literal_String
-The prefix of @cite{Universal_Literal_String} must be a named
+The prefix of @code{Universal_Literal_String} must be a named
number. The static result is the string consisting of the characters of
the number as defined in the original source. This allows the user
program to access the actual text of named numbers without intermediate
@end example
@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1a1}
+@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1a5}
@section Attribute Unrestricted_Access
@geindex Unrestricted_Access
-The @cite{Unrestricted_Access} attribute is similar to @cite{Access}
+The @code{Unrestricted_Access} attribute is similar to @code{Access}
except that all accessibility and aliased view checks are omitted. This
is a user-beware attribute.
-For objects, it is similar to @cite{Address}, for which it is a
+For objects, it is similar to @code{Address}, for which it is a
desirable replacement where the value desired is an access type.
In other words, its effect is similar to first applying the
-@cite{Address} attribute and then doing an unchecked conversion to a
+@code{Address} attribute and then doing an unchecked conversion to a
desired access type.
-For subprograms, @cite{P'Unrestricted_Access} may be used where
-@cite{P'Access} would be illegal, to construct a value of a
+For subprograms, @code{P'Unrestricted_Access} may be used where
+@code{P'Access} would be illegal, to construct a value of a
less-nested named access type that designates a more-nested
subprogram. This value may be used in indirect calls, so long as the
more-nested subprogram still exists; once the subprogram containing it
called after P2 returns, it would be an erroneous use of a dangling
pointer.
-For objects, it is possible to use @cite{Unrestricted_Access} for any
+For objects, it is possible to use @code{Unrestricted_Access} for any
type. However, if the result is of an access-to-unconstrained array
subtype, then the resulting pointer has the same scope as the context
of the attribute, and must not be returned to some enclosing scope.
-For instance, if a function uses @cite{Unrestricted_Access} to create
+For instance, if a function uses @code{Unrestricted_Access} to create
an access-to-unconstrained-array and returns that value to the caller,
the result will involve dangling pointers. In addition, it is only
valid to create pointers to unconstrained arrays using this attribute
A normal unconstrained array value
or a constrained array object marked as aliased has the bounds in memory
just before the array, so a thin pointer can retrieve both the data and
-the bounds. But in this case, the non-aliased object @cite{X} does not have the
-bounds before the string. If the size clause for type @cite{A}
+the bounds. But in this case, the non-aliased object @code{X} does not have the
+bounds before the string. If the size clause for type @code{A}
were not present, then the pointer
would be a fat pointer, where one component is a pointer to the bounds,
and all would be well. But with the size clause present, the conversion from
fat pointer to thin pointer in the call loses the bounds, and so this
-is erroneous, and the program likely raises a @cite{Program_Error} exception.
+is erroneous, and the program likely raises a @code{Program_Error} exception.
In general, it is advisable to completely
avoid mixing the use of thin pointers and the use of
-@cite{Unrestricted_Access} where the designated type is an
+@code{Unrestricted_Access} where the designated type is an
unconstrained array. The use of thin pointers should be restricted to
cases of porting legacy code that implicitly assumes the size of pointers,
and such code should not in any case be using this attribute.
or may not notice this attempt, and subsequent references to P may yield
either the value 3 or the value 4 or the assignment may blow up if the
compiler decides to put P in read-only memory. One particular case where
-@cite{Unrestricted_Access} can be used in this way is to modify the
-value of an @cite{IN} parameter:
+@code{Unrestricted_Access} can be used in this way is to modify the
+value of an @code{in} parameter:
@example
procedure K (S : in String) is
@end example
In general this is a risky approach. It may appear to "work" but such uses of
-@cite{Unrestricted_Access} are potentially non-portable, even from one version
-of @cite{GNAT} to another, so are best avoided if possible.
+@code{Unrestricted_Access} are potentially non-portable, even from one version
+of GNAT to another, so are best avoided if possible.
@node Attribute Update,Attribute Valid_Scalars,Attribute Unrestricted_Access,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1a2}
+@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1a6}
@section Attribute Update
@geindex Update
-The @cite{Update} attribute creates a copy of an array or record value
+The @code{Update} attribute creates a copy of an array or record value
with one or more modified components. The syntax is:
@example
INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} )
@end example
-where @cite{PREFIX} is the name of an array or record object, the
-association list in parentheses does not contain an @cite{others}
-choice and the box symbol @cite{<>} may not appear in any
+where @code{PREFIX} is the name of an array or record object, the
+association list in parentheses does not contain an @code{others}
+choice and the box symbol @code{<>} may not appear in any
expression. The effect is to yield a copy of the array or record value
which is unchanged apart from the components mentioned in the
association list, which are changed to the indicated value. The
Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
@end example
-yields a value for @cite{Avar2} of 1,10,20,20,5 with @cite{Avar1}
+yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1}
begin unmodified. Similarly:
@example
Rvar2 : Rec := Rvar1'Update (B => 20);
@end example
-yields a value for @cite{Rvar2} of (A => 1, B => 20, C => 3),
-with @cite{Rvar1} being unmodifed.
+yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3),
+with @code{Rvar1} being unmodifed.
Note that the value of the attribute reference is computed
completely before it is used. This means that if you write:
Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
@end example
-then the value of @cite{Avar1} is not modified if @cite{Function_Call}
+then the value of @code{Avar1} is not modified if @code{Function_Call}
raises an exception, unlike the effect of a series of direct assignments
-to elements of @cite{Avar1}. In general this requires that
+to elements of @code{Avar1}. In general this requires that
two extra complete copies of the object are required, which should be
kept in mind when considering efficiency.
-The @cite{Update} attribute cannot be applied to prefixes of a limited
+The @code{Update} attribute cannot be applied to prefixes of a limited
type, and cannot reference discriminants in the case of a record type.
The accessibility level of an Update attribute result object is defined
as for an aggregate.
which changes element (1,2) to 20 and (3,4) to 30.
@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Update,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1a3}
+@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1a7}
@section Attribute Valid_Scalars
@geindex Valid_Scalars
-The @cite{'Valid_Scalars} attribute is intended to make it easier to
+The @code{'Valid_Scalars} attribute is intended to make it easier to
check the validity of scalar subcomponents of composite objects. It
-is defined for any prefix @cite{X} that denotes an object.
+is defined for any prefix @code{X} that denotes an object.
The value of this attribute is of the predefined type Boolean.
-@cite{X'Valid_Scalars} yields True if and only if evaluation of
-@cite{P'Valid} yields True for every scalar part P of X or if X has
+@code{X'Valid_Scalars} yields True if and only if evaluation of
+@code{P'Valid} yields True for every scalar part P of X or if X has
no scalar parts. It is not specified in what order the scalar parts
are checked, nor whether any more are checked after any one of them
-is determined to be invalid. If the prefix @cite{X} is of a class-wide
-type @cite{T'Class} (where @cite{T} is the associated specific type),
-or if the prefix @cite{X} is of a specific tagged type @cite{T}, then
-only the scalar parts of components of @cite{T} are traversed; in other
-words, components of extensions of @cite{T} are not traversed even if
-@cite{T'Class (X)'Tag /= T'Tag} . The compiler will issue a warning if it can
+is determined to be invalid. If the prefix @code{X} is of a class-wide
+type @code{T'Class} (where @code{T} is the associated specific type),
+or if the prefix @code{X} is of a specific tagged type @code{T}, then
+only the scalar parts of components of @code{T} are traversed; in other
+words, components of extensions of @code{T} are not traversed even if
+@code{T'Class (X)'Tag /= T'Tag} . The compiler will issue a warning if it can
be determined at compile time that the prefix of the attribute has no
scalar parts (e.g., if the prefix is of an access type, an interface type,
an undiscriminated task type, or an undiscriminated protected type).
-For scalar types, @cite{Valid_Scalars} is equivalent to @cite{Valid}. The use
-of this attribute is not permitted for @cite{Unchecked_Union} types for which
+For scalar types, @code{Valid_Scalars} is equivalent to @code{Valid}. The use
+of this attribute is not permitted for @code{Unchecked_Union} types for which
in general it is not possible to determine the values of the discriminants.
-Note: @cite{Valid_Scalars} can generate a lot of code, especially in the case
+Note: @code{Valid_Scalars} can generate a lot of code, especially in the case
of a large variant record. If the attribute is called in many places in the
same program applied to objects of the same type, it can reduce program size
to write a function with a single use of the attribute, and then call that
function from multiple places.
@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1a4}
+@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1a8}
@section Attribute VADS_Size
@geindex VADS_Size
-The @cite{'VADS_Size} attribute is intended to make it easier to port
-legacy code which relies on the semantics of @cite{'Size} as implemented
+The @code{'VADS_Size} attribute is intended to make it easier to port
+legacy code which relies on the semantics of @code{'Size} as implemented
by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
-same semantic interpretation. In particular, @cite{'VADS_Size} applied
+same semantic interpretation. In particular, @code{'VADS_Size} applied
to a predefined or other primitive type with no Size clause yields the
-Object_Size (for example, @cite{Natural'Size} is 32 rather than 31 on
-typical machines). In addition @cite{'VADS_Size} applied to an object
+Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
+typical machines). In addition @code{'VADS_Size} applied to an object
gives the result that would be obtained by applying the attribute to
the corresponding type.
@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1a5}@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{157}
+@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1a9}@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{15b}
@section Attribute Value_Size
@code{type'Value_Size} is the number of bits required to represent
a value of the given subtype. It is the same as @code{type'Size},
-but, unlike @cite{Size}, may be set for non-first subtypes.
+but, unlike @code{Size}, may be set for non-first subtypes.
@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1a6}
+@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1aa}
@section Attribute Wchar_T_Size
@geindex Wchar_T_Size
-@cite{Standard'Wchar_T_Size} (@cite{Standard} is the only permissible
-prefix) provides the size in bits of the C @cite{wchar_t} type
+@code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
+prefix) provides the size in bits of the C @code{wchar_t} type
primarily for constructing the definition of this type in
-package @cite{Interfaces.C}. The result is a static constant.
+package @code{Interfaces.C}. The result is a static constant.
@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes
-@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1a7}
+@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1ab}
@section Attribute Word_Size
@geindex Word_Size
-@cite{Standard'Word_Size} (@cite{Standard} is the only permissible
-prefix) provides the value @cite{System.Word_Size}. The result is
+@code{Standard'Word_Size} (@code{Standard} is the only permissible
+prefix) provides the value @code{System.Word_Size}. The result is
a static constant.
@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9}@anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1a8}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1a9}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9}@anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1ac}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1ad}
@chapter Standard and Implementation Defined Restrictions
@end menu
@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1aa}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1ab}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1ae}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1af}
@section Partition-Wide Restrictions
@end menu
@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1ac}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b0}
@subsection Immediate_Reclamation
immediately reclaimed when the object no longer exists.
@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1ad}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1b1}
@subsection Max_Asynchronous_Select_Nesting
other than zero cause Storage_Error to be raised.
@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1ae}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1b2}
@subsection Max_Entry_Queue_Length
@geindex Max_Entry_Queue_Depth
-The restriction @cite{Max_Entry_Queue_Depth} is recognized as a
-synonym for @cite{Max_Entry_Queue_Length}. This is retained for historical
+The restriction @code{Max_Entry_Queue_Depth} is recognized as a
+synonym for @code{Max_Entry_Queue_Length}. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on obsolescent features are activated).
@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1af}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1b3}
@subsection Max_Protected_Entries
defined by a discriminant of a subtype whose corresponding bound is static.
@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1b0}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1b4}
@subsection Max_Select_Alternatives
[RM D.7] Specifies the maximum number of alternatives in a selective accept.
@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1b1}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1b5}
@subsection Max_Storage_At_Blocking
restriction causes Storage_Error to be raised.
@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1b2}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1b6}
@subsection Max_Task_Entries
corresponding bound is static.
@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1b3}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1b7}
@subsection Max_Tasks
Storage_Error to be raised.
@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1b4}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1b8}
@subsection No_Abort_Statements
no calls to Task_Identification.Abort_Task.
@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1b5}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1b9}
@subsection No_Access_Parameter_Allocators
parameter.
@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1b6}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1ba}
@subsection No_Access_Subprograms
declarations of access-to-subprogram types.
@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1b7}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1bb}
@subsection No_Allocators
occurrences of an allocator.
@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1b8}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1bc}
@subsection No_Anonymous_Allocators
occurrences of an allocator of anonymous access type.
@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1b9}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1bd}
@subsection No_Asynchronous_Control
dependences on the predefined package Asynchronous_Task_Control.
@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1ba}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1be}
@subsection No_Calendar
dependences on package Calendar.
@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1bb}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1bf}
@subsection No_Coextensions
coextensions. See 3.10.2.
@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1bc}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c0}
@subsection No_Default_Initialization
initializer (including the case of OUT scalar parameters).
@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1bd}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1c1}
@subsection No_Delay
delay statements and no semantic dependences on package Calendar.
@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1be}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1c2}
@subsection No_Dependence
dependences on a library unit.
@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1bf}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1c3}
@subsection No_Direct_Boolean_Operators
composite boolean operations.
@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1c0}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1c4}
@subsection No_Dispatch
@geindex No_Dispatch
[RM H.4] This restriction ensures at compile time that there are no
-occurrences of @cite{T'Class}, for any (tagged) subtype @cite{T}.
+occurrences of @code{T'Class}, for any (tagged) subtype @code{T}.
@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1c1}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1c5}
@subsection No_Dispatching_Calls
membership test is allowed in the presence of this restriction, because its
implementation requires no dispatching.
This restriction is comparable to the official Ada restriction
-@cite{No_Dispatch} except that it is a bit less restrictive in that it allows
+@code{No_Dispatch} except that it is a bit less restrictive in that it allows
all classwide constructs that do not imply dispatching.
The following example indicates constructs that violate this restriction.
@end example
@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1c2}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1c6}
@subsection No_Dynamic_Attachment
@geindex No_Dynamic_Interrupts
-The restriction @cite{No_Dynamic_Interrupts} is recognized as a
-synonym for @cite{No_Dynamic_Attachment}. This is retained for historical
+The restriction @code{No_Dynamic_Interrupts} is recognized as a
+synonym for @code{No_Dynamic_Attachment}. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on obsolescent features are activated).
@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1c3}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1c7}
@subsection No_Dynamic_Priorities
[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1c4}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1c8}
@subsection No_Entry_Calls_In_Elaboration_Code
in a task can be executed at elaboration time.
@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1c5}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1c9}
@subsection No_Enumeration_Maps
to enumeration types).
@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1c6}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1ca}
@subsection No_Exception_Handlers
represents the line number in the source program where the raise occurs.
@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1c7}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1cb}
@subsection No_Exception_Propagation
statements (raise with no operand) are not permitted.
@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1c8}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1cc}
@subsection No_Exception_Registration
of exceptions when they are declared.
@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1c9}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1cd}
@subsection No_Exceptions
raise statements and no exception handlers.
@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1ca}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1ce}
@subsection No_Finalization
@itemize *
@item
-@cite{Ada.Finalization.Controlled}
+@code{Ada.Finalization.Controlled}
@item
-@cite{Ada.Finalization.Limited_Controlled}
+@code{Ada.Finalization.Limited_Controlled}
@item
-Derivations from @cite{Controlled} or @cite{Limited_Controlled}
+Derivations from @code{Controlled} or @code{Limited_Controlled}
@item
Class-wide types
deallocation of a controlled object no longer finalizes its contents.
@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1cb}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1cf}
@subsection No_Fixed_Point
occurrences of fixed point types and operations.
@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1cc}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d0}
@subsection No_Floating_Point
occurrences of floating point types and operations.
@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1cd}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1d1}
@subsection No_Implicit_Conditionals
of composite objects and the Max/Min attributes.
@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1ce}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1d2}
@subsection No_Implicit_Dynamic_Code
[GNAT] This restriction prevents the compiler from building 'trampolines'.
This is a structure that is built on the stack and contains dynamic
code to be executed at run time. On some targets, a trampoline is
-built for the following features: @cite{Access},
-@cite{Unrestricted_Access}, or @cite{Address} of a nested subprogram;
+built for the following features: @code{Access},
+@code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
nested task bodies; primitive operations of nested tagged types.
Trampolines do not work on machines that prevent execution of stack
data. For example, on windows systems, enabling DEP (data execution
version of system.ads for your target --- if it has
Always_Compatible_Rep equal to False, then trampolines are largely
eliminated. In particular, a trampoline is built for the following
-features: @cite{Address} of a nested subprogram;
-@cite{Access} or @cite{Unrestricted_Access} of a nested subprogram,
+features: @code{Address} of a nested subprogram;
+@code{Access} or @code{Unrestricted_Access} of a nested subprogram,
but only if pragma Favor_Top_Level applies, or the access type has a
foreign-language convention; primitive operations of nested tagged
types.
@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1cf}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1d3}
@subsection No_Implicit_Heap_Allocations
[RM D.7] No constructs are allowed to cause implicit heap allocation.
@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1d0}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1d4}
@subsection No_Implicit_Protected_Object_Allocations
protected object.
@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1d1}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1d5}
@subsection No_Implicit_Task_Allocations
[GNAT] No constructs are allowed to cause implicit heap allocation of a task.
@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1d2}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1d6}
@subsection No_Initialize_Scalars
are otherwise generated for some record and array types.
@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1d3}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1d7}
@subsection No_IO
Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO.
@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1d4}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1d8}
@subsection No_Local_Allocators
and entry bodies.
@node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1d5}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1d9}
@subsection No_Local_Protected_Objects
only declared at the library level.
@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1d6}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1da}
@subsection No_Local_Timing_Events
declared at the library level.
@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1d7}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1db}
@subsection No_Long_Long_Integers
Long_Integer'Size.
@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1d8}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1dc}
@subsection No_Multiple_Elaboration
by the binder.
@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1d9}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1dd}
@subsection No_Nested_Finalization
[RM D.7] All objects requiring finalization are declared at the library level.
@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1da}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1de}
@subsection No_Protected_Type_Allocators
expressions that attempt to allocate protected objects.
@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1db}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1df}
@subsection No_Protected_Types
declarations of protected types or protected objects.
@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1dc}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e0}
@subsection No_Recursion
part of its execution.
@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1dd}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1e1}
@subsection No_Reentrancy
two tasks at the same time.
@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1de}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1e2}
@subsection No_Relative_Delay
@geindex No_Relative_Delay
[RM D.7] This restriction ensures at compile time that there are no delay
-relative statements and prevents expressions such as @cite{delay 1.23;} from
+relative statements and prevents expressions such as @code{delay 1.23;} from
appearing in source code.
@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1df}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1e3}
@subsection No_Requeue_Statements
@geindex No_Requeue_Statements
[RM D.7] This restriction ensures at compile time that no requeue statements
-are permitted and prevents keyword @cite{requeue} from being used in source
+are permitted and prevents keyword @code{requeue} from being used in source
code.
@geindex No_Requeue
-The restriction @cite{No_Requeue} is recognized as a
-synonym for @cite{No_Requeue_Statements}. This is retained for historical
+The restriction @code{No_Requeue} is recognized as a
+synonym for @code{No_Requeue_Statements}. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on oNobsolescent features are activated).
@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1e0}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1e4}
@subsection No_Secondary_Stack
secondary stacks for tasks (excluding the environment task) at run time.
@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1e1}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1e5}
@subsection No_Select_Statements
@geindex No_Select_Statements
[RM D.7] This restriction ensures at compile time no select statements of any
-kind are permitted, that is the keyword @cite{select} may not appear.
+kind are permitted, that is the keyword @code{select} may not appear.
@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1e2}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1e6}
@subsection No_Specific_Termination_Handlers
or to Ada.Task_Termination.Specific_Handler.
@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1e3}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1e7}
@subsection No_Specification_of_Aspect
given aspect.
@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1e4}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1e8}
@subsection No_Standard_Allocators_After_Elaboration
is raised.
@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1e5}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1e9}
@subsection No_Standard_Storage_Pools
user-defined storage pool.
@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1e6}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1ea}
@subsection No_Stream_Optimizations
@geindex No_Stream_Optimizations
[GNAT] This restriction affects the performance of stream operations on types
-@cite{String}, @cite{Wide_String} and @cite{Wide_Wide_String}. By default, the
-compiler uses block reads and writes when manipulating @cite{String} objects
+@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the
+compiler uses block reads and writes when manipulating @code{String} objects
due to their supperior performance. When this restriction is in effect, the
compiler performs all IO operations on a per-character basis.
@node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1e7}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1eb}
@subsection No_Streams
[GNAT] This restriction ensures at compile/bind time that there are no
stream objects created and no use of stream attributes.
This restriction does not forbid dependences on the package
-@cite{Ada.Streams}. So it is permissible to with
-@cite{Ada.Streams} (or another package that does so itself)
+@code{Ada.Streams}. So it is permissible to with
+@code{Ada.Streams} (or another package that does so itself)
as long as no actual stream objects are created and no
stream attributes are used.
though this is not required.
@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1e8}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1ec}
@subsection No_Task_Allocators
or types containing task subcomponents.
@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1e9}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1ed}
@subsection No_Task_At_Interrupt_Priority
that an interrupt priority.
@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1ea}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1ee}
@subsection No_Task_Attributes_Package
@geindex No_Task_Attributes_Package
[GNAT] This restriction ensures at compile time that there are no implicit or
-explicit dependencies on the package @cite{Ada.Task_Attributes}.
+explicit dependencies on the package @code{Ada.Task_Attributes}.
@geindex No_Task_Attributes
-The restriction @cite{No_Task_Attributes} is recognized as a synonym
-for @cite{No_Task_Attributes_Package}. This is retained for historical
+The restriction @code{No_Task_Attributes} is recognized as a synonym
+for @code{No_Task_Attributes_Package}. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on obsolescent features are activated).
@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1eb}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1ef}
@subsection No_Task_Hierarchy
directly on the environment task of the partition.
@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1ec}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f0}
@subsection No_Task_Termination
[RM D.7] Tasks that terminate are erroneous.
@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1ed}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1f1}
@subsection No_Tasking
[GNAT] This restriction prevents the declaration of tasks or task types
throughout the partition. It is similar in effect to the use of
-@cite{Max_Tasks => 0} except that violations are caught at compile time
+@code{Max_Tasks => 0} except that violations are caught at compile time
and cause an error message to be output either by the compiler or
binder.
@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1ee}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1f2}
@subsection No_Terminate_Alternatives
[RM D.7] There are no selective accepts with terminate alternatives.
@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1ef}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1f3}
@subsection No_Unchecked_Access
occurrences of the Unchecked_Access attribute.
@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1f0}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1f4}
@subsection No_Unchecked_Conversion
dependences on the predefined generic function Unchecked_Conversion.
@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1f1}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1f5}
@subsection No_Unchecked_Deallocation
dependences on the predefined generic procedure Unchecked_Deallocation.
@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1f2}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1f6}
@subsection No_Use_Of_Entity
@end example
@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{1f3}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{1f7}
@subsection Pure_Barriers
@itemize *
@item
-simple variables defined in the private part of the
-protected type/object,
+components of the protected object (excluding selection from dereferences),
@item
constant declarations,
uses of the Standard."not" operator,
@item
-short-circuit operator
+short-circuit operator,
+
+@item
+the Count attribute
@end itemize
This restriction is a relaxation of the Simple_Barriers restriction,
during the evaluation of the barriers.
@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{1f4}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{1f8}
@subsection Simple_Barriers
@geindex Boolean_Entry_Barriers
-The restriction @cite{Boolean_Entry_Barriers} is recognized as a
-synonym for @cite{Simple_Barriers}. This is retained for historical
+The restriction @code{Boolean_Entry_Barriers} is recognized as a
+synonym for @code{Simple_Barriers}. This is retained for historical
compatibility purposes (and a warning will be generated for its use if
warnings on obsolescent features are activated).
@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{1f5}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{1f9}
@subsection Static_Priorities
[GNAT] This restriction ensures at compile time that all priority expressions
are static, and that there are no dependences on the package
-@cite{Ada.Dynamic_Priorities}.
+@code{Ada.Dynamic_Priorities}.
@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{1f6}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{1fa}
@subsection Static_Storage_Size
in a Storage_Size pragma or attribute definition clause is static.
@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{1f7}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{1f8}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{1fb}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{1fc}
@section Program Unit Level Restrictions
@end menu
@node No_Elaboration_Code,No_Dynamic_Sized_Objects,,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{1f9}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{1fd}
@subsection No_Elaboration_Code
[GNAT] This restriction ensures at compile time that no elaboration code is
generated. Note that this is not the same condition as is enforced
-by pragma @cite{Preelaborate}. There are cases in which pragma
-@cite{Preelaborate} still permits code to be generated (e.g., code
+by pragma @code{Preelaborate}. There are cases in which pragma
+@code{Preelaborate} still permits code to be generated (e.g., code
to initialize a large array to all zeroes), and there are cases of units
-which do not meet the requirements for pragma @cite{Preelaborate},
+which do not meet the requirements for pragma @code{Preelaborate},
but for which no elaboration code is generated. Generally, it is
the case that preelaborable units will meet the restrictions, with
the exception of large aggregates initialized with an others_clause,
In the case of aggregates with others, if the aggregate has a dynamic
size, there is no way to eliminate the elaboration code (such dynamic
-bounds would be incompatible with @cite{Preelaborate} in any case). If
+bounds would be incompatible with @code{Preelaborate} in any case). If
the bounds are static, then use of this restriction actually modifies
the code choice of the compiler to avoid generating a loop, and instead
generate the aggregate statically if possible, no matter how many times
before elaboration and to control multiple elaboration attempts.
@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Elaboration_Code,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{1fa}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{1fe}
@subsection No_Dynamic_Sized_Objects
with No_Secondary_Stack.
@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{1fb}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{1ff}
@subsection No_Entry_Queue
is made to queue a second task on such an entry.
@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{1fc}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{200}
@subsection No_Implementation_Aspect_Specifications
aspects that can be used are those defined in the Ada Reference Manual.
@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{1fd}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{201}
@subsection No_Implementation_Attributes
Manual.
@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{1fe}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{202}
@subsection No_Implementation_Identifiers
occur within language-defined packages.
@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{1ff}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{203}
@subsection No_Implementation_Pragmas
pragmas that can be used are those defined in the Ada Reference Manual.
@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{200}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{204}
@subsection No_Implementation_Restrictions
@geindex No_Implementation_Restrictions
[GNAT] This restriction checks at compile time that no GNAT-defined restriction
-identifiers (other than @cite{No_Implementation_Restrictions} itself)
+identifiers (other than @code{No_Implementation_Restrictions} itself)
are present. With this restriction, the only other restriction identifiers
that can be used are those defined in the Ada Reference Manual.
@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{201}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{205}
@subsection No_Implementation_Units
of packages Ada, Interfaces, or System.
@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{202}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{206}
@subsection No_Implicit_Aliasing
the standard attribute Unchecked_Access which is preferable.
@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{203}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{207}
@subsection No_Implicit_Loops
@geindex No_Implicit_Loops
[GNAT] This restriction ensures that the generated code of the unit marked
-with this restriction does not contain any implicit @cite{for} loops, either by
+with this restriction does not contain any implicit @code{for} loops, either by
modifying the generated code where possible, or by rejecting any construct
-that would otherwise generate an implicit @cite{for} loop. If this restriction is
+that would otherwise generate an implicit @code{for} loop. If this restriction is
active, it is possible to build large array aggregates with all static
components without generating an intermediate temporary, and without generating
a loop to initialize individual components. Otherwise, a loop is created for
is set in the spec of a package, it will not apply to its body.
@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{204}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{208}
@subsection No_Obsolescent_Features
features are used, as defined in Annex J of the Ada Reference Manual.
@node No_Wide_Characters,SPARK_05,No_Obsolescent_Features,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{205}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{209}
@subsection No_Wide_Characters
@geindex No_Wide_Characters
[GNAT] This restriction ensures at compile time that no uses of the types
-@cite{Wide_Character} or @cite{Wide_String} or corresponding wide
+@code{Wide_Character} or @code{Wide_String} or corresponding wide
wide types
appear, and that no wide or wide wide string or character literals
appear in the program (that is literals representing characters not in
-type @cite{Character}).
+type @code{Character}).
@node SPARK_05,,No_Wide_Characters,Program Unit Level Restrictions
-@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{206}
+@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{20a}
@subsection SPARK_05
@geindex SPARK
-The restriction @cite{SPARK} is recognized as a
-synonym for @cite{SPARK_05}. This is retained for historical
+The restriction @code{SPARK} is recognized as a
+synonym for @code{SPARK_05}. This is retained for historical
compatibility purposes (and an unconditional warning will be generated
-for its use, advising replacement by @cite{SPARK}).
+for its use, advising replacement by @code{SPARK}).
This is not a replacement for the semantic checks performed by the
SPARK Examiner tool, as the compiler currently only deals with code,
Thus it may well be the case that code which passes the compiler with
the SPARK restriction is rejected by the SPARK Examiner, e.g. due to
the different visibility rules of the Examiner based on SPARK 2005
-@cite{inherit} annotations.
+@code{inherit} annotations.
This restriction can be useful in providing an initial filter for code
developed using SPARK 2005, or in examining legacy code to see how far
instead of SPARK 2005.
@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top
-@anchor{gnat_rm/implementation_advice doc}@anchor{207}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}@anchor{gnat_rm/implementation_advice id1}@anchor{208}
+@anchor{gnat_rm/implementation_advice doc}@anchor{20b}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}@anchor{gnat_rm/implementation_advice id1}@anchor{20c}
@chapter Implementation Advice
@end menu
@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{209}
+@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{20d}
@section RM 1.1.3(20): Error Detection
@quotation
"If an implementation detects the use of an unsupported Specialized Needs
-Annex feature at run time, it should raise @cite{Program_Error} if
+Annex feature at run time, it should raise @code{Program_Error} if
feasible."
@end quotation
@geindex Child Units
@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{20a}
+@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{20e}
@section RM 1.1.3(31): Child Units
@geindex Bounded errors
@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{20b}
+@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{20f}
@section RM 1.1.5(12): Bounded Errors
@quotation
"If an implementation detects a bounded error or erroneous
-execution, it should raise @cite{Program_Error}."
+execution, it should raise @code{Program_Error}."
@end quotation
Followed in all cases in which the implementation detects a bounded
@geindex Pragmas
@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice
-@anchor{gnat_rm/implementation_advice id2}@anchor{20c}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{20d}
+@anchor{gnat_rm/implementation_advice id2}@anchor{210}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{211}
@section RM 2.8(16): Pragmas
@ref{7,,Implementation Defined Pragmas}.
@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{20e}
+@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{212}
@section RM 2.8(17-19): Pragmas
@itemize *
@item
-A pragma used to complete a declaration, such as a pragma @cite{Import};
+A pragma used to complete a declaration, such as a pragma @code{Import};
@item
A pragma used to configure the environment by adding, removing, or
-replacing @cite{library_items}."
+replacing @code{library_items}."
@end itemize
@end quotation
-See @ref{20d,,RM 2.8(16); Pragmas}.
+See @ref{211,,RM 2.8(16); Pragmas}.
@geindex Character Sets
@geindex Alternative Character Sets
@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{20f}
+@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{213}
@section RM 3.5.2(5): Alternative Character Sets
@quotation
"If an implementation supports a mode with alternative interpretations
-for @cite{Character} and @cite{Wide_Character}, the set of graphic
-characters of @cite{Character} should nevertheless remain a proper
-subset of the set of graphic characters of @cite{Wide_Character}. Any
+for @code{Character} and @code{Wide_Character}, the set of graphic
+characters of @code{Character} should nevertheless remain a proper
+subset of the set of graphic characters of @code{Wide_Character}. Any
character set 'localizations' should be reflected in the results of
the subprograms defined in the language-defined package
-@cite{Characters.Handling} (see A.3) available in such a mode. In a mode with
-an alternative interpretation of @cite{Character}, the implementation should
+@code{Characters.Handling} (see A.3) available in such a mode. In a mode with
+an alternative interpretation of @code{Character}, the implementation should
also support a corresponding change in what is a legal
-@cite{identifier_letter}."
+@code{identifier_letter}."
@end quotation
Not all wide character modes follow this advice, in particular the JIS
@geindex Integer types
@node RM 3 5 4 28 Integer Types,RM 3 5 4 29 Integer Types,RM 3 5 2 5 Alternative Character Sets,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{210}
+@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{214}
@section RM 3.5.4(28): Integer Types
@quotation
-"An implementation should support @cite{Long_Integer} in addition to
-@cite{Integer} if the target machine supports 32-bit (or longer)
+"An implementation should support @code{Long_Integer} in addition to
+@code{Integer} if the target machine supports 32-bit (or longer)
arithmetic. No other named integer subtypes are recommended for package
-@cite{Standard}. Instead, appropriate named integer subtypes should be
-provided in the library package @cite{Interfaces} (see B.2)."
+@code{Standard}. Instead, appropriate named integer subtypes should be
+provided in the library package @code{Interfaces} (see B.2)."
@end quotation
-@cite{Long_Integer} is supported. Other standard integer types are supported
+@code{Long_Integer} is supported. Other standard integer types are supported
so this advice is not fully followed. These types
are supported for convenient interface to C, and so that all hardware
types of the machine are easily available.
@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{211}
+@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{215}
@section RM 3.5.4(29): Integer Types
"An implementation for a two's complement machine should support
modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
-implementation should support a non-binary modules up to @cite{Integer'Last}."
+implementation should support a non-binary modules up to @code{Integer'Last}."
@end quotation
Followed.
@geindex Enumeration values
@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{212}
+@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{216}
@section RM 3.5.5(8): Enumeration Values
subtype, if the value of the operand does not correspond to the internal
code for any enumeration literal of its type (perhaps due to an
un-initialized variable), then the implementation should raise
-@cite{Program_Error}. This is particularly important for enumeration
+@code{Program_Error}. This is particularly important for enumeration
types with noncontiguous internal codes specified by an
enumeration_representation_clause."
@end quotation
@geindex Float types
@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{213}
+@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{217}
@section RM 3.5.7(17): Float Types
@quotation
-"An implementation should support @cite{Long_Float} in addition to
-@cite{Float} if the target machine supports 11 or more digits of
+"An implementation should support @code{Long_Float} in addition to
+@code{Float} if the target machine supports 11 or more digits of
precision. No other named floating point subtypes are recommended for
-package @cite{Standard}. Instead, appropriate named floating point subtypes
-should be provided in the library package @cite{Interfaces} (see B.2)."
+package @code{Standard}. Instead, appropriate named floating point subtypes
+should be provided in the library package @code{Interfaces} (see B.2)."
@end quotation
-@cite{Short_Float} and @cite{Long_Long_Float} are also provided. The
+@code{Short_Float} and @code{Long_Long_Float} are also provided. The
former provides improved compatibility with other implementations
supporting this type. The latter corresponds to the highest precision
floating-point type supported by the hardware. On most machines, this
-will be the same as @cite{Long_Float}, but on some machines, it will
+will be the same as @code{Long_Float}, but on some machines, it will
correspond to the IEEE extended form. The notable case is all ia32
-(x86) implementations, where @cite{Long_Long_Float} corresponds to
+(x86) implementations, where @code{Long_Long_Float} corresponds to
the 80-bit extended precision format supported in hardware on this
processor. Note that the 128-bit format on SPARC is not supported,
since this is a software rather than a hardware format.
@geindex multidimensional
@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration'Small,RM 3 5 7 17 Float Types,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{214}
+@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{218}
@section RM 3.6.2(11): Multidimensional Arrays
"An implementation should normally represent multidimensional arrays in
row-major order, consistent with the notation used for multidimensional
-array aggregates (see 4.3.3). However, if a pragma @cite{Convention}
-(@cite{Fortran}, ...) applies to a multidimensional array type, then
-column-major order should be used instead (see B.5, @cite{Interfacing with Fortran})."
+array aggregates (see 4.3.3). However, if a pragma @code{Convention}
+(@code{Fortran}, ...) applies to a multidimensional array type, then
+column-major order should be used instead (see B.5, @emph{Interfacing with Fortran})."
@end quotation
Followed.
@geindex Duration'Small
@node RM 9 6 30-31 Duration'Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{215}
+@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{219}
@section RM 9.6(30-31): Duration'Small
@quotation
-"Whenever possible in an implementation, the value of @cite{Duration'Small}
+"Whenever possible in an implementation, the value of @code{Duration'Small}
should be no greater than 100 microseconds."
@end quotation
-Followed. (@cite{Duration'Small} = 10**(-9)).
+Followed. (@code{Duration'Small} = 10**(-9)).
@quotation
-"The time base for @cite{delay_relative_statements} should be monotonic;
-it need not be the same time base as used for @cite{Calendar.Clock}."
+"The time base for @code{delay_relative_statements} should be monotonic;
+it need not be the same time base as used for @code{Calendar.Clock}."
@end quotation
Followed.
@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration'Small,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{216}
+@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{21a}
@section RM 10.2.1(12): Consistent Representation
@geindex Exception information
@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{217}
+@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{21b}
@section RM 11.4.1(19): Exception Information
@quotation
-"@cite{Exception_Message} by default and @cite{Exception_Information}
+"@code{Exception_Message} by default and @code{Exception_Information}
should produce information useful for
-debugging. @cite{Exception_Message} should be short, about one
-line. @cite{Exception_Information} can be long. @cite{Exception_Message}
+debugging. @code{Exception_Message} should be short, about one
+line. @code{Exception_Information} can be long. @code{Exception_Message}
should not include the
-@cite{Exception_Name}. @cite{Exception_Information} should include both
-the @cite{Exception_Name} and the @cite{Exception_Message}."
+@code{Exception_Name}. @code{Exception_Information} should include both
+the @code{Exception_Name} and the @code{Exception_Message}."
@end quotation
Followed. For each exception that doesn't have a specified
-@cite{Exception_Message}, the compiler generates one containing the location
+@code{Exception_Message}, the compiler generates one containing the location
of the raise statement. This location has the form 'file_name:line', where
file_name is the short file name (without path information) and line is the line
number in the file. Note that in the case of the Zero Cost Exception
mechanism, these messages become redundant with the Exception_Information that
contains a full backtrace of the calling sequence, so they are disabled.
To disable explicitly the generation of the source location message, use the
-Pragma @cite{Discard_Names}.
+Pragma @code{Discard_Names}.
@geindex Suppression of checks
@geindex suppression of
@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{218}
+@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{21c}
@section RM 11.5(28): Suppression of Checks
@geindex Representation clauses
@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{219}
+@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{21d}
@section RM 13.1 (21-24): Representation Clauses
for Y'Address use X'Address;>>
-"An implementation need not support a specification for the `Size`
+"An implementation need not support a specification for the `@w{`}Size`@w{`}
for a given composite subtype, nor the size or storage place for an
object (including a component) of a given composite subtype, unless the
constraints on the subtype and its composite subcomponents (if any) are
@geindex Packed types
@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{21a}
+@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{21e}
@section RM 13.2(6-8): Packed Types
speed of accessing components, subject to reasonable complexity in
addressing calculations.
-The recommended level of support pragma @cite{Pack} is:
+The recommended level of support pragma @code{Pack} is:
For a packed record type, the components should be packed as tightly as
possible subject to the Sizes of the component subtypes, and subject to
-any @cite{record_representation_clause} that applies to the type; the
+any @emph{record_representation_clause} that applies to the type; the
implementation may, but need not, reorder components or cross aligned
-word boundaries to improve the packing. A component whose @cite{Size} is
+word boundaries to improve the packing. A component whose @code{Size} is
greater than the word size may be allocated an integral number of words."
@end quotation
@geindex Address clauses
@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{21b}
+@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{21f}
@section RM 13.3(14-19): Address Clauses
@quotation
-"For an array @cite{X}, @code{X'Address} should point at the first
+"For an array @code{X}, @code{X'Address} should point at the first
component of the array, and not at the array bounds."
@end quotation
@quotation
-"The recommended level of support for the @cite{Address} attribute is:
+"The recommended level of support for the @code{Address} attribute is:
-@code{X'Address} should produce a useful result if @cite{X} is an
+@code{X'Address} should produce a useful result if @code{X} is an
object that is aliased or of a by-reference type, or is an entity whose
-@cite{Address} has been specified."
+@code{Address} has been specified."
@end quotation
Followed. A valid address will be produced even if none of those
@quotation
-"An implementation should support @cite{Address} clauses for imported
+"An implementation should support @code{Address} clauses for imported
subprograms."
@end quotation
@quotation
-"If the @cite{Address} of an object is specified, or it is imported or exported,
+"If the @code{Address} of an object is specified, or it is imported or exported,
then the implementation should not perform optimizations based on
assumptions of no aliases."
@end quotation
@geindex Alignment clauses
@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{21c}
+@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{220}
@section RM 13.3(29-35): Alignment Clauses
@quotation
-"The recommended level of support for the @cite{Alignment} attribute for
+"The recommended level of support for the @code{Alignment} attribute for
subtypes is:
An implementation should support specified Alignments that are factors
@quotation
"An implementation need not support specified Alignments that are
-greater than the maximum @cite{Alignment} the implementation ever returns by
+greater than the maximum @code{Alignment} the implementation ever returns by
default."
@end quotation
@quotation
-"The recommended level of support for the @cite{Alignment} attribute for
+"The recommended level of support for the @code{Alignment} attribute for
objects is:
Same as above, for subtypes, but in addition:"
@geindex Size clauses
@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{21d}
+@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{221}
@section RM 13.3(42-43): Size Clauses
@quotation
-"The recommended level of support for the @cite{Size} attribute of
+"The recommended level of support for the @code{Size} attribute of
objects is:
-A @cite{Size} clause should be supported for an object if the specified
-@cite{Size} is at least as large as its subtype's @cite{Size}, and
+A @code{Size} clause should be supported for an object if the specified
+@code{Size} is at least as large as its subtype's @code{Size}, and
corresponds to a size in storage elements that is a multiple of the
-object's @cite{Alignment} (if the @cite{Alignment} is nonzero)."
+object's @code{Alignment} (if the @code{Alignment} is nonzero)."
@end quotation
Followed.
@node RM 13 3 50-56 Size Clauses,RM 13 3 71-73 Component Size Clauses,RM 13 3 42-43 Size Clauses,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{21e}
+@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{222}
@section RM 13.3(50-56): Size Clauses
@quotation
-"If the @cite{Size} of a subtype is specified, and allows for efficient
+"If the @code{Size} of a subtype is specified, and allows for efficient
independent addressability (see 9.10) on the target architecture, then
-the @cite{Size} of the following objects of the subtype should equal the
-@cite{Size} of the subtype:
+the @code{Size} of the following objects of the subtype should equal the
+@code{Size} of the subtype:
Aliased objects (including components)."
@end quotation
@quotation
-"The recommended level of support for the @cite{Size} attribute of subtypes is:
+"The recommended level of support for the @code{Size} attribute of subtypes is:
-The @cite{Size} (if not specified) of a static discrete or fixed point
+The @code{Size} (if not specified) of a static discrete or fixed point
subtype should be the number of bits needed to represent each value
belonging to the subtype using an unbiased representation, leaving space
for a sign bit only if the subtype contains negative values. If such a
subtype is a first subtype, then an implementation should support a
-specified @cite{Size} for it that reflects this representation."
+specified @code{Size} for it that reflects this representation."
@end quotation
Followed.
@quotation
-"For a subtype implemented with levels of indirection, the @cite{Size}
+"For a subtype implemented with levels of indirection, the @code{Size}
should include the size of the pointers, but not the size of what they
point at."
@end quotation
@geindex Component_Size clauses
@node RM 13 3 71-73 Component Size Clauses,RM 13 4 9-10 Enumeration Representation Clauses,RM 13 3 50-56 Size Clauses,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{21f}
+@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{223}
@section RM 13.3(71-73): Component Size Clauses
@quotation
-"The recommended level of support for the @cite{Component_Size}
+"The recommended level of support for the @code{Component_Size}
attribute is:
-An implementation need not support specified @cite{Component_Sizes} that are
-less than the @cite{Size} of the component subtype."
+An implementation need not support specified @code{Component_Sizes} that are
+less than the @code{Size} of the component subtype."
@end quotation
Followed.
@geindex enumeration
@node RM 13 4 9-10 Enumeration Representation Clauses,RM 13 5 1 17-22 Record Representation Clauses,RM 13 3 71-73 Component Size Clauses,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{220}
+@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{224}
@section RM 13.4(9-10): Enumeration Representation Clauses
An implementation need not support enumeration representation clauses
for boolean types, but should at minimum support the internal codes in
-the range @cite{System.Min_Int .. System.Max_Int}."
+the range @code{System.Min_Int .. System.Max_Int}."
@end quotation
Followed.
@geindex records
@node RM 13 5 1 17-22 Record Representation Clauses,RM 13 5 2 5 Storage Place Attributes,RM 13 4 9-10 Enumeration Representation Clauses,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{221}
+@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{225}
@section RM 13.5.1(17-22): Record Representation Clauses
@quotation
"The recommended level of support for
-@cite{record_representation_clauses} is:
+@emph{record_representation_clause}s is:
An implementation should support storage places that can be extracted
with a load, mask, shift sequence of machine code, and set with a load,
@quotation
"A storage place should be supported if its size is equal to the
-@cite{Size} of the component subtype, and it starts and ends on a
-boundary that obeys the @cite{Alignment} of the component subtype."
+@code{Size} of the component subtype, and it starts and ends on a
+boundary that obeys the @code{Alignment} of the component subtype."
@end quotation
Followed.
@quotation
"If the default bit ordering applies to the declaration of a given type,
-then for a component whose subtype's @cite{Size} is less than the word
+then for a component whose subtype's @code{Size} is less than the word
size, any storage place that does not cross an aligned word boundary
should be supported."
@end quotation
@quotation
-"An implementation need not support a @cite{component_clause} for a
+"An implementation need not support a @emph{component_clause} for a
component of an extension part if the storage place is not after the
storage places of all components of the parent type, whether or not
those storage places had been specified."
@geindex Storage place attributes
@node RM 13 5 2 5 Storage Place Attributes,RM 13 5 3 7-8 Bit Ordering,RM 13 5 1 17-22 Record Representation Clauses,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{222}
+@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{226}
@section RM 13.5.2(5): Storage Place Attributes
@geindex Bit ordering
@node RM 13 5 3 7-8 Bit Ordering,RM 13 7 37 Address as Private,RM 13 5 2 5 Storage Place Attributes,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{223}
+@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{227}
@section RM 13.5.3(7-8): Bit Ordering
"The recommended level of support for the non-default bit ordering is:
-If @cite{Word_Size} = @cite{Storage_Unit}, then the implementation
+If @code{Word_Size} = @code{Storage_Unit}, then the implementation
should support the non-default bit ordering in addition to the default
bit ordering."
@end quotation
@geindex as private type
@node RM 13 7 37 Address as Private,RM 13 7 1 16 Address Operations,RM 13 5 3 7-8 Bit Ordering,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{224}
+@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{228}
@section RM 13.7(37): Address as Private
Followed.
@geindex Operations
-@geindex on `Address`
+@geindex on `@w{`}Address`@w{`}
@geindex Address
@geindex operations of
@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{225}
+@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{229}
@section RM 13.7.1(16): Address Operations
@quotation
-"Operations in @cite{System} and its children should reflect the target
+"Operations in @code{System} and its children should reflect the target
environment semantics as closely as is reasonable. For example, on most
machines, it makes sense for address arithmetic to 'wrap around'.
-Operations that do not make sense should raise @cite{Program_Error}."
+Operations that do not make sense should raise @code{Program_Error}."
@end quotation
Followed. Address arithmetic is modular arithmetic that wraps around. No
-operation raises @cite{Program_Error}, since all operations make sense.
+operation raises @code{Program_Error}, since all operations make sense.
@geindex Unchecked conversion
@node RM 13 9 14-17 Unchecked Conversion,RM 13 11 23-25 Implicit Heap Usage,RM 13 7 1 16 Address Operations,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{226}
+@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{22a}
@section RM 13.9(14-17): Unchecked Conversion
@quotation
-"The @cite{Size} of an array object should not include its bounds; hence,
+"The @code{Size} of an array object should not include its bounds; hence,
the bounds should not be part of the converted data."
@end quotation
@quotation
"The implementation should not generate unnecessary run-time checks to
-ensure that the representation of @cite{S} is a representation of the
+ensure that the representation of @code{S} is a representation of the
target type. It should take advantage of the permission to return by
reference when possible. Restrictions on unchecked conversions should be
avoided unless required by the target environment."
@geindex implicit
@node RM 13 11 23-25 Implicit Heap Usage,RM 13 11 2 17 Unchecked Deallocation,RM 13 9 14-17 Unchecked Conversion,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{227}
+@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{22b}
@section RM 13.11(23-25): Implicit Heap Usage
@geindex Unchecked deallocation
@node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 17 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{228}
+@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{22c}
@section RM 13.11.2(17): Unchecked Deallocation
@quotation
-"For a standard storage pool, @cite{Free} should actually reclaim the
+"For a standard storage pool, @code{Free} should actually reclaim the
storage."
@end quotation
@geindex Stream oriented attributes
@node RM 13 13 2 17 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-13-13-2-17-stream-oriented-attributes}@anchor{229}
+@anchor{gnat_rm/implementation_advice rm-13-13-2-17-stream-oriented-attributes}@anchor{22d}
@section RM 13.13.2(17): Stream Oriented Attributes
@quotation
"If a stream element is the same size as a storage element, then the
-normal in-memory representation should be used by @cite{Read} and
-@cite{Write} for scalar objects. Otherwise, @cite{Read} and @cite{Write}
+normal in-memory representation should be used by @code{Read} and
+@code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write}
should use the smallest number of stream elements needed to represent
all values in the base range of the scalar type."
@end quotation
However, such an implementation is based on direct binary
representations and is therefore target- and endianness-dependent.
To address this issue, GNAT also supplies an alternate implementation
-of the stream attributes @cite{Read} and @cite{Write},
+of the stream attributes @code{Read} and @code{Write},
which uses the target-independent XDR standard representation
for scalar types.
@geindex Stream oriented attributes
The XDR implementation is provided as an alternative body of the
-@cite{System.Stream_Attributes} package, in the file
+@code{System.Stream_Attributes} package, in the file
@code{s-stratt-xdr.adb} in the GNAT library.
There is no @code{s-stratt-xdr.ads} file.
In order to install the XDR implementation, do the following:
@item
Replace the default implementation of the
-@cite{System.Stream_Attributes} package with the XDR implementation.
+@code{System.Stream_Attributes} package with the XDR implementation.
For example on a Unix platform issue the commands:
@example
@item
Rebuild the GNAT run-time library as documented in
-the @cite{GNAT and Libraries} section of the @cite{GNAT User's Guide}.
+the @emph{GNAT and Libraries} section of the @cite{GNAT User's Guide}.
@end itemize
@node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 17 Stream Oriented Attributes,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{22a}
+@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{22e}
@section RM A.1(52): Names of Predefined Numeric Types
@geindex Ada.Characters.Handling
@node RM A 3 2 49 Ada Characters Handling,RM A 4 4 106 Bounded-Length String Handling,RM A 1 52 Names of Predefined Numeric Types,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{22b}
-@section RM A.3.2(49): @cite{Ada.Characters.Handling}
+@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{22f}
+@section RM A.3.2(49): @code{Ada.Characters.Handling}
@quotation
-"If an implementation provides a localized definition of @cite{Character}
-or @cite{Wide_Character}, then the effects of the subprograms in
-@cite{Characters.Handling} should reflect the localizations.
+"If an implementation provides a localized definition of @code{Character}
+or @code{Wide_Character}, then the effects of the subprograms in
+@code{Characters.Handling} should reflect the localizations.
See also 3.5.2."
@end quotation
@geindex Bounded-length strings
@node RM A 4 4 106 Bounded-Length String Handling,RM A 5 2 46-47 Random Number Generation,RM A 3 2 49 Ada Characters Handling,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{22c}
+@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{230}
@section RM A.4.4(106): Bounded-Length String Handling
@geindex Random number generation
@node RM A 5 2 46-47 Random Number Generation,RM A 10 7 23 Get_Immediate,RM A 4 4 106 Bounded-Length String Handling,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{22d}
+@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{231}
@section RM A.5.2(46-47): Random Number Generation
@quotation
-"Any storage associated with an object of type @cite{Generator} should be
+"Any storage associated with an object of type @code{Generator} should be
reclaimed on exit from the scope of the object."
@end quotation
"If the generator period is sufficiently long in relation to the number
of distinct initiator values, then each possible value of
-@cite{Initiator} passed to @cite{Reset} should initiate a sequence of
+@code{Initiator} passed to @code{Reset} should initiate a sequence of
random numbers that does not, in a practical sense, overlap the sequence
initiated by any other value. If this is not possible, then the mapping
between initiator values and generator states should be a rapidly
@geindex Get_Immediate
@node RM A 10 7 23 Get_Immediate,RM B 1 39-41 Pragma Export,RM A 5 2 46-47 Random Number Generation,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{22e}
-@section RM A.10.7(23): @cite{Get_Immediate}
+@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{232}
+@section RM A.10.7(23): @code{Get_Immediate}
@quotation
-"The @cite{Get_Immediate} procedures should be implemented with
+"The @code{Get_Immediate} procedures should be implemented with
unbuffered input. For a device such as a keyboard, input should be
available if a key has already been typed, whereas for a disk
file, input should always be available except at end of file. For a file
associated with a keyboard-like device, any line-editing features of the
underlying operating system should be disabled during the execution of
-@cite{Get_Immediate}."
+@code{Get_Immediate}."
@end quotation
Followed on all targets except VxWorks. For VxWorks, there is no way to
provide this functionality that does not result in the input buffer being
-flushed before the @cite{Get_Immediate} call. A special unit
-@cite{Interfaces.Vxworks.IO} is provided that contains routines to enable
+flushed before the @code{Get_Immediate} call. A special unit
+@code{Interfaces.Vxworks.IO} is provided that contains routines to enable
this functionality.
@geindex Export
@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 10 7 23 Get_Immediate,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{22f}
-@section RM B.1(39-41): Pragma @cite{Export}
+@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{233}
+@section RM B.1(39-41): Pragma @code{Export}
@quotation
-"If an implementation supports pragma @cite{Export} to a given language,
+"If an implementation supports pragma @code{Export} 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
-@cite{adainit} and @cite{adafinal}. @cite{adainit} should contain the
-elaboration code for library units. @cite{adafinal} should contain the
+@code{adainit} and @code{adafinal}. @code{adainit} should contain the
+elaboration code for library units. @code{adafinal} should contain the
finalization code. These subprograms should have no effect the second
and subsequent time they are called."
@end quotation
@quotation
"Automatic elaboration of pre-elaborated packages should be
-provided when pragma @cite{Export} is supported."
+provided when pragma @code{Export} is supported."
@end quotation
Followed when the main program is in Ada. If the main program is in a
foreign language, then
-@cite{adainit} must be called to elaborate pre-elaborated
+@code{adainit} must be called to elaborate pre-elaborated
packages.
@quotation
-"For each supported convention @cite{L} other than @cite{Intrinsic}, an
-implementation should support @cite{Import} and @cite{Export} pragmas
-for objects of @cite{L}-compatible types and for subprograms, and pragma
-@cite{Convention} for @cite{L}-eligible types and for subprograms,
+"For each supported convention @emph{L} other than @code{Intrinsic}, an
+implementation should support @code{Import} and @code{Export} pragmas
+for objects of @emph{L}-compatible types and for subprograms, and pragma
+@cite{Convention} for @emph{L}-eligible types and for subprograms,
presuming the other language has corresponding features. Pragma
-@cite{Convention} need not be supported for scalar types."
+@code{Convention} need not be supported for scalar types."
@end quotation
Followed.
@geindex Interfaces
@node RM B 2 12-13 Package Interfaces,RM B 3 63-71 Interfacing with C,RM B 1 39-41 Pragma Export,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{230}
-@section RM B.2(12-13): Package @cite{Interfaces}
+@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{234}
+@section RM B.2(12-13): Package @code{Interfaces}
@quotation
interfacing to the language (implementation) represented by the
convention. Any declarations useful for interfacing to any language on
the given hardware architecture should be provided directly in
-@cite{Interfaces}."
+@code{Interfaces}."
@end quotation
Followed.
@geindex interfacing with
@node RM B 3 63-71 Interfacing with C,RM B 4 95-98 Interfacing with COBOL,RM B 2 12-13 Package Interfaces,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{231}
+@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{235}
@section RM B.3(63-71): Interfacing with C
@quotation
-"An Ada @cite{in} scalar parameter is passed as a scalar argument to a C
+"An Ada @code{in} scalar parameter is passed as a scalar argument to a C
function."
@end quotation
@quotation
-"An Ada @cite{in} parameter of an access-to-object type with designated
-type @cite{T} is passed as a @code{t*} argument to a C function,
-where @code{t} is the C type corresponding to the Ada type @cite{T}."
+"An Ada @code{in} parameter of an access-to-object type with designated
+type @code{T} is passed as a @code{t*} argument to a C function,
+where @code{t} is the C type corresponding to the Ada type @code{T}."
@end quotation
Followed.
@quotation
-"An Ada access @cite{T} parameter, or an Ada @cite{out} or @cite{in out}
-parameter of an elementary type @cite{T}, is passed as a @code{t*}
+"An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out}
+parameter of an elementary type @code{T}, is passed as a @code{t*}
argument to a C function, where @code{t} is the C type corresponding to
-the Ada type @cite{T}. In the case of an elementary @cite{out} or
-@cite{in out} parameter, a pointer to a temporary copy is used to
+the Ada type @code{T}. In the case of an elementary @code{out} or
+@code{in out} parameter, a pointer to a temporary copy is used to
preserve by-copy semantics."
@end quotation
@quotation
-"An Ada parameter of a record type @cite{T}, of any mode, is passed as a
+"An Ada parameter of a record type @code{T}, of any mode, is passed as a
@code{t*} argument to a C function, where @code{t} is the C
-structure corresponding to the Ada type @cite{T}."
+structure corresponding to the Ada type @code{T}."
@end quotation
Followed. This convention may be overridden by the use of the C_Pass_By_Copy
@quotation
-"An Ada parameter of an array type with component type @cite{T}, of any
+"An Ada parameter of an array type with component type @code{T}, of any
mode, is passed as a @code{t*} argument to a C function, where
-@code{t} is the C type corresponding to the Ada type @cite{T}."
+@code{t} is the C type corresponding to the Ada type @code{T}."
@end quotation
Followed.
@geindex interfacing with
@node RM B 4 95-98 Interfacing with COBOL,RM B 5 22-26 Interfacing with Fortran,RM B 3 63-71 Interfacing with C,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{232}
+@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{236}
@section RM B.4(95-98): Interfacing with COBOL
@quotation
-"An Ada access @cite{T} parameter is passed as a @code{BY REFERENCE} data item of
-the COBOL type corresponding to @cite{T}."
+"An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of
+the COBOL type corresponding to @code{T}."
@end quotation
Followed.
@geindex interfacing with
@node RM B 5 22-26 Interfacing with Fortran,RM C 1 3-5 Access to Machine Operations,RM B 4 95-98 Interfacing with COBOL,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{233}
+@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{237}
@section RM B.5(22-26): Interfacing with Fortran
@quotation
-"An Ada parameter of an elementary, array, or record type @cite{T} is
-passed as a @cite{T} argument to a Fortran procedure, where @cite{T} is
-the Fortran type corresponding to the Ada type @cite{T}, and where the
+"An Ada parameter of an elementary, array, or record type @code{T} is
+passed as a @code{T} argument to a Fortran procedure, where @code{T} is
+the Fortran type corresponding to the Ada type @code{T}, and where the
INTENT attribute of the corresponding dummy argument matches the Ada
formal parameter mode; the Fortran implementation's parameter passing
conventions are used. For elementary types, a local copy is used if
@geindex Machine operations
@node RM C 1 3-5 Access to Machine Operations,RM C 1 10-16 Access to Machine Operations,RM B 5 22-26 Interfacing with Fortran,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{234}
+@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{238}
@section RM C.1(3-5): Access to Machine Operations
"The interfacing pragmas (see Annex B) should support interface to
assembler; the default assembler should be associated with the
-convention identifier @cite{Assembler}."
+convention identifier @code{Assembler}."
@end quotation
Followed.
Followed.
@node RM C 1 10-16 Access to Machine Operations,RM C 3 28 Interrupt Support,RM C 1 3-5 Access to Machine Operations,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{235}
+@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{239}
@section RM C.1(10-16): Access to Machine Operations
@geindex Interrupt support
@node RM C 3 28 Interrupt Support,RM C 3 1 20-21 Protected Procedure Handlers,RM C 1 10-16 Access to Machine Operations,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{236}
+@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{23a}
@section RM C.3(28): Interrupt Support
@quotation
-"If the @cite{Ceiling_Locking} policy is not in effect, the
+"If the @code{Ceiling_Locking} policy is not in effect, the
implementation should provide means for the application to specify which
interrupts are to be blocked during protected actions, if the underlying
system allows for a finer-grain control of interrupt blocking."
@geindex Protected procedure handlers
@node RM C 3 1 20-21 Protected Procedure Handlers,RM C 3 2 25 Package Interrupts,RM C 3 28 Interrupt Support,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{237}
+@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{23b}
@section RM C.3.1(20-21): Protected Procedure Handlers
Followed. Compile time warnings are given when possible.
-@geindex Package `Interrupts`
+@geindex Package `@w{`}Interrupts`@w{`}
@geindex Interrupts
@node RM C 3 2 25 Package Interrupts,RM C 4 14 Pre-elaboration Requirements,RM C 3 1 20-21 Protected Procedure Handlers,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{238}
-@section RM C.3.2(25): Package @cite{Interrupts}
+@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{23c}
+@section RM C.3.2(25): Package @code{Interrupts}
@quotation
"If implementation-defined forms of interrupt handler procedures are
supported, such as protected procedures with parameters, then for each
-such form of a handler, a type analogous to @cite{Parameterless_Handler}
-should be specified in a child package of @cite{Interrupts}, with the
+such form of a handler, a type analogous to @code{Parameterless_Handler}
+should be specified in a child package of @code{Interrupts}, with the
same operations as in the predefined package Interrupts."
@end quotation
@geindex Pre-elaboration requirements
@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{239}
+@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{23d}
@section RM C.4(14): Pre-elaboration Requirements
to initialize large arrays.
@node RM C 5 8 Pragma Discard_Names,RM C 7 2 30 The Package Task_Attributes,RM C 4 14 Pre-elaboration Requirements,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{23a}
-@section RM C.5(8): Pragma @cite{Discard_Names}
+@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{23e}
+@section RM C.5(8): Pragma @code{Discard_Names}
@quotation
@geindex Task_Attributes
@node RM C 7 2 30 The Package Task_Attributes,RM D 3 17 Locking Policies,RM C 5 8 Pragma Discard_Names,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{23b}
+@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{23f}
@section RM C.7.2(30): The Package Task_Attributes
recommended that the storage for task attributes will be pre-allocated
statically and not from the heap. This can be accomplished by either
placing restrictions on the number and the size of the task's
-attributes, or by using the pre-allocated storage for the first @cite{N}
+attributes, or by using the pre-allocated storage for the first @code{N}
attribute objects, and the heap for the others. In the latter case,
-@cite{N} should be documented."
+@code{N} should be documented."
@end quotation
Not followed. This implementation is not targeted to such a domain.
@geindex Locking Policies
@node RM D 3 17 Locking Policies,RM D 4 16 Entry Queuing Policies,RM C 7 2 30 The Package Task_Attributes,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{23c}
+@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{240}
@section RM D.3(17): Locking Policies
@end quotation
Followed. Two implementation-defined locking policies are defined,
-whose names (@cite{Inheritance_Locking} and
-@cite{Concurrent_Readers_Locking}) follow this suggestion.
+whose names (@code{Inheritance_Locking} and
+@code{Concurrent_Readers_Locking}) follow this suggestion.
@geindex Entry queuing policies
@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{23d}
+@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{241}
@section RM D.4(16): Entry Queuing Policies
@geindex Preemptive abort
@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{23e}
+@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{242}
@section RM D.6(9-10): Preemptive Abort
@quotation
-"Even though the @cite{abort_statement} is included in the list of
+"Even though the @emph{abort_statement} is included in the list of
potentially blocking operations (see 9.5.1), it is recommended that this
statement be implemented in a way that never requires the task executing
-the @cite{abort_statement} to block."
+the @emph{abort_statement} to block."
@end quotation
Followed.
@geindex Tasking restrictions
@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{23f}
+@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{243}
@section RM D.7(21): Tasking Restrictions
GNAT currently takes advantage of these restrictions by providing an optimized
run time when the Ravenscar profile and the GNAT restricted run time set
-of restrictions are specified. See pragma @cite{Profile (Ravenscar)} and
-pragma @cite{Profile (Restricted)} for more details.
+of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
+pragma @code{Profile (Restricted)} for more details.
@geindex Time
@geindex monotonic
@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{240}
+@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{244}
@section RM D.8(47-49): Monotonic Time
@quotation
"When appropriate, implementations should provide configuration
-mechanisms to change the value of @cite{Tick}."
+mechanisms to change the value of @code{Tick}."
@end quotation
Such configuration mechanisms are not appropriate to this implementation
@quotation
-"It is recommended that @cite{Calendar.Clock} and @cite{Real_Time.Clock}
+"It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
be implemented as transformations of the same time base."
@end quotation
"It is recommended that the best time base which exists in
the underlying system be available to the application through
-@cite{Clock}. @cite{Best} may mean highest accuracy or largest range."
+@code{Clock}. @cite{Best} may mean highest accuracy or largest range."
@end quotation
Followed.
@geindex PCS
@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{241}
+@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{245}
@section RM E.5(28-29): Partition Communication Subsystem
@quotation
-"The @cite{Write} operation on a stream of type @cite{Params_Stream_Type}
-should raise @cite{Storage_Error} if it runs out of space trying to
-write the @cite{Item} into the stream."
+"The @code{Write} operation on a stream of type @code{Params_Stream_Type}
+should raise @code{Storage_Error} if it runs out of space trying to
+write the @code{Item} into the stream."
@end quotation
Followed by GLADE, a separately supplied PCS that can be used with
@geindex COBOL support
@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{242}
+@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{246}
@section RM F(7): COBOL Support
"If COBOL (respectively, C) is widely supported in the target
environment, implementations supporting the Information Systems Annex
-should provide the child package @cite{Interfaces.COBOL} (respectively,
-@cite{Interfaces.C}) specified in Annex B and should support a
-@cite{convention_identifier} of COBOL (respectively, C) in the interfacing
+should provide the child package @code{Interfaces.COBOL} (respectively,
+@code{Interfaces.C}) specified in Annex B and should support a
+@code{convention_identifier} of COBOL (respectively, C) in the interfacing
pragmas (see Annex B), thus allowing Ada programs to interface with
programs written in that language."
@end quotation
@geindex Decimal radix support
@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{243}
+@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{247}
@section RM F.1(2): Decimal Radix Support
@quotation
"Packed decimal should be used as the internal representation for objects
-of subtype @cite{S} when @cite{S}'Machine_Radix = 10."
+of subtype @code{S} when @code{S}'Machine_Radix = 10."
@end quotation
-Not followed. GNAT ignores @cite{S}'Machine_Radix and always uses binary
+Not followed. GNAT ignores @code{S}'Machine_Radix and always uses binary
representations.
@geindex Numerics
@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{244}
+@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{248}
@section RM G: Numerics
"If Fortran (respectively, C) is widely supported in the target
environment, implementations supporting the Numerics Annex
-should provide the child package @cite{Interfaces.Fortran} (respectively,
-@cite{Interfaces.C}) specified in Annex B and should support a
-@cite{convention_identifier} of Fortran (respectively, C) in the interfacing
+should provide the child package @code{Interfaces.Fortran} (respectively,
+@code{Interfaces.C}) specified in Annex B and should support a
+@code{convention_identifier} of Fortran (respectively, C) in the interfacing
pragmas (see Annex B), thus allowing Ada programs to interface with
programs written in that language."
@end quotation
@geindex Complex types
@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{245}
+@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{249}
@section RM G.1.1(56-58): Complex Types
complex operand and a real operand is that the imaginary operand remains
unchanged, an implementation should not perform this operation by first
promoting the real operand to complex type and then performing a full
-complex addition. In implementations in which the @cite{Signed_Zeros}
-attribute of the component type is @cite{True} (and which therefore
+complex addition. In implementations in which the @code{Signed_Zeros}
+attribute of the component type is @code{True} (and which therefore
conform to IEC 559:1989 in regard to the handling of the sign of zero in
predefined arithmetic operations), the latter technique will not
generate the required result when the imaginary component of the complex
@quotation
-"Implementations in which @cite{Real'Signed_Zeros} is @cite{True} should
+"Implementations in which @code{Real'Signed_Zeros} is @code{True} should
attempt to provide a rational treatment of the signs of zero results and
-result components. As one example, the result of the @cite{Argument}
+result components. As one example, the result of the @code{Argument}
function should have the sign of the imaginary component of the
-parameter @cite{X} when the point represented by that parameter lies on
+parameter @code{X} when the point represented by that parameter lies on
the positive real axis; as another, the sign of the imaginary component
-of the @cite{Compose_From_Polar} function should be the same as
-(respectively, the opposite of) that of the @cite{Argument} parameter when that
-parameter has a value of zero and the @cite{Modulus} parameter has a
+of the @code{Compose_From_Polar} function should be the same as
+(respectively, the opposite of) that of the @code{Argument} parameter when that
+parameter has a value of zero and the @code{Modulus} parameter has a
nonnegative (respectively, negative) value."
@end quotation
@geindex Complex elementary functions
@node RM G 1 2 49 Complex Elementary Functions,RM G 2 4 19 Accuracy Requirements,RM G 1 1 56-58 Complex Types,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{246}
+@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{24a}
@section RM G.1.2(49): Complex Elementary Functions
@quotation
-"Implementations in which @cite{Complex_Types.Real'Signed_Zeros} is
-@cite{True} should attempt to provide a rational treatment of the signs
+"Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
+@code{True} should attempt to provide a rational treatment of the signs
of zero results and result components. For example, many of the complex
elementary functions have components that are odd functions of one of
the parameter components; in these cases, the result component should
@geindex Accuracy requirements
@node RM G 2 4 19 Accuracy Requirements,RM G 2 6 15 Complex Arithmetic Accuracy,RM G 1 2 49 Complex Elementary Functions,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{247}
+@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{24b}
@section RM G.2.4(19): Accuracy Requirements
@quotation
"The versions of the forward trigonometric functions without a
-@cite{Cycle} parameter should not be implemented by calling the
-corresponding version with a @cite{Cycle} parameter of
-@cite{2.0*Numerics.Pi}, since this will not provide the required
+@code{Cycle} parameter should not be implemented by calling the
+corresponding version with a @code{Cycle} parameter of
+@code{2.0*Numerics.Pi}, since this will not provide the required
accuracy in some portions of the domain. For the same reason, the
-version of @cite{Log} without a @cite{Base} parameter should not be
-implemented by calling the corresponding version with a @cite{Base}
-parameter of @cite{Numerics.e}."
+version of @code{Log} without a @code{Base} parameter should not be
+implemented by calling the corresponding version with a @code{Base}
+parameter of @code{Numerics.e}."
@end quotation
Followed.
@geindex complex arithmetic
@node RM G 2 6 15 Complex Arithmetic Accuracy,RM H 6 15/2 Pragma Partition_Elaboration_Policy,RM G 2 4 19 Accuracy Requirements,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{248}
+@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{24c}
@section RM G.2.6(15): Complex Arithmetic Accuracy
@quotation
-"The version of the @cite{Compose_From_Polar} function without a
-@cite{Cycle} parameter should not be implemented by calling the
-corresponding version with a @cite{Cycle} parameter of
-@cite{2.0*Numerics.Pi}, since this will not provide the required
+"The version of the @code{Compose_From_Polar} function without a
+@code{Cycle} parameter should not be implemented by calling the
+corresponding version with a @code{Cycle} parameter of
+@code{2.0*Numerics.Pi}, since this will not provide the required
accuracy in some portions of the domain."
@end quotation
@geindex Sequential elaboration policy
@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice
-@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{249}
+@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{24d}
@section RM H.6(15/2): Pragma Partition_Elaboration_Policy
@quotation
-"If the partition elaboration policy is @cite{Sequential} and the
+"If the partition elaboration policy is @code{Sequential} and the
Environment task becomes permanently blocked during elaboration then the
partition is deadlocked and it is recommended that the partition be
immediately terminated."
Not followed.
@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top
-@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{24a}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{24b}
+@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{24e}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{24f}
@chapter Implementation Defined Characteristics
interactions. See 1.1.3(10)."
@end itemize
-Any @cite{code_statement} can potentially cause external interactions.
+Any @emph{code_statement} can potentially cause external interactions.
@itemize *
@itemize *
@item
-"Effect of pragma @cite{Optimize}. See 2.8(27)."
+"Effect of pragma @code{Optimize}. See 2.8(27)."
@end itemize
-Pragma @cite{Optimize}, if given with a @cite{Time} or @cite{Space}
+Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
parameter, checks that the optimization flag is set, and aborts if it is
not.
@item
"The sequence of characters of the value returned by
@code{S'Image} when some of the graphic characters of
-@code{S'Wide_Image} are not defined in @cite{Character}. See
+@code{S'Wide_Image} are not defined in @code{Character}. See
3.5(37)."
@end itemize
@item
"The predefined integer types declared in
-@cite{Standard}. See 3.5.4(25)."
+@code{Standard}. See 3.5.4(25)."
@end itemize
@item
"The predefined floating point types declared in
-@cite{Standard}. See 3.5.7(16)."
+@code{Standard}. See 3.5.7(16)."
@end itemize
"The small of an ordinary fixed point type. See 3.5.9(8)."
@end itemize
-@cite{Fine_Delta} is 2**(-63)
+@code{Fine_Delta} is 2**(-63)
@itemize *
@end itemize
Any combinations are permitted that do not result in a small less than
-@cite{Fine_Delta} and do not result in a mantissa larger than 63 bits.
+@code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
If the mantissa is larger than 53 bits on machines where Long_Long_Float
is 64 bits (true of all architectures except ia32), then the output from
Text_IO is accurate to only 53 bits, rather than the full mantissa. This
@itemize *
@item
-"The result of @cite{Tags.Expanded_Name} for types declared
-within an unnamed @cite{block_statement}. See 3.9(10)."
+"The result of @code{Tags.Expanded_Name} for types declared
+within an unnamed @emph{block_statement}. See 3.9(10)."
@end itemize
-Block numbers of the form @cite{B`nnn`}, where @cite{nnn} is a
+Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a
decimal integer are allocated.
@end itemize
See 9.6(20). The time base used is that provided by the C library
-function @cite{gettimeofday}.
+function @code{gettimeofday}.
@itemize *
@item
-"The time base of the type @cite{Calendar.Time}. See
+"The time base of the type @code{Calendar.Time}. See
9.6(23)."
@end itemize
The time base used is that provided by the C library function
-@cite{gettimeofday}.
+@code{gettimeofday}.
@itemize *
@item
-"The time zone used for package @cite{Calendar}
+"The time zone used for package @code{Calendar}
operations. See 9.6(24)."
@end itemize
-The time zone used by package @cite{Calendar} is the current system time zone
+The time zone used by package @code{Calendar} is the current system time zone
setting for local time, as accessed by the C library function
-@cite{localtime}.
+@code{localtime}.
@itemize *
@item
-"Any limit on @cite{delay_until_statements} of
-@cite{select_statements}. See 9.6(29)."
+"Any limit on @emph{delay_until_statements} of
+@emph{select_statements}. See 9.6(29)."
@end itemize
There are no such limits.
@item
"Whether or not two non-overlapping parts of a composite
object are independently addressable, in the case where packing, record
-layout, or @cite{Component_Size} is specified for the object. See
+layout, or @code{Component_Size} is specified for the object. See
9.10(1)."
@end itemize
this case a list of units can be explicitly supplied to the binder for
inclusion in the partition (all units needed by these units will also
be included automatically). For full details on the use of these
-options, refer to the @cite{GNAT Make Program gnatmake} in the
+options, refer to @emph{GNAT Make Program gnatmake} in the
@cite{GNAT User's Guide}.
@itemize *
@item
-"The order of elaboration of @cite{library_items}. See
+"The order of elaboration of @emph{library_items}. See
10.2(18)."
@end itemize
The main program has no parameters. It may be a procedure, or a function
returning an integer type. In the latter case, the returned integer
value is the return code of the program (overriding any value that
-may have been set by a call to @cite{Ada.Command_Line.Set_Exit_Status}).
+may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
@itemize *
@itemize *
@item
-"The information returned by @cite{Exception_Message}. See
+"The information returned by @code{Exception_Message}. See
11.4.1(10)."
@end itemize
@itemize *
@item
-"The result of @cite{Exceptions.Exception_Name} for types
-declared within an unnamed @cite{block_statement}. See 11.4.1(12)."
+"The result of @code{Exceptions.Exception_Name} for types
+declared within an unnamed @emph{block_statement}. See 11.4.1(12)."
@end itemize
-Blocks have implementation defined names of the form @cite{B`nnn`}
-where @cite{nnn} is an integer.
+Blocks have implementation defined names of the form @code{B@emph{nnn}}
+where @emph{nnn} is an integer.
@itemize *
@item
"The information returned by
-@cite{Exception_Information}. See 11.4.1(13)."
+@code{Exception_Information}. See 11.4.1(13)."
@end itemize
-@cite{Exception_Information} returns a string in the following format:
+@code{Exception_Information} returns a string in the following format:
@example
*Exception_Name:* nnnnn
@itemize *
@item
-@cite{nnnn} is the fully qualified name of the exception in all upper
+@code{nnnn} is the fully qualified name of the exception in all upper
case letters. This line is always present.
@item
-@cite{mmmm} is the message (this line present only if message is non-null)
+@code{mmmm} is the message (this line present only if message is non-null)
@item
-@cite{ppp} is the Process Id value as a decimal integer (this line is
+@code{ppp} is the Process Id value as a decimal integer (this line is
present only if the Process Id is nonzero). Currently we are
not making use of this field.
the main executable. The values are given in C style format, with lower case
letters for a-f, and only as many digits present as are necessary.
The line terminator sequence at the end of each line, including
-the last line is a single @cite{LF} character (@cite{16#0A#}).
+the last line is a single @code{LF} character (@code{16#0A#}).
@end itemize
@end quotation
Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks,
Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user
program can add implementation-defined check names by means of the pragma
-Check_Name. See the description of pragma @cite{Suppress} for full details.
+Check_Name. See the description of pragma @code{Suppress} for full details.
@itemize *
@itemize *
@item
-"The meaning of @cite{Size} for indefinite subtypes. See
+"The meaning of @code{Size} for indefinite subtypes. See
13.3(48)."
@end itemize
@itemize *
@item
-"If @cite{Word_Size} = @cite{Storage_Unit}, the default bit
+"If @code{Word_Size} = @code{Storage_Unit}, the default bit
ordering. See 13.5.3(5)."
@end itemize
-@cite{Word_Size} (32) is not the same as @cite{Storage_Unit} (8) for this
+@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
implementation, so no non-default bit ordering is supported. The default
bit ordering corresponds to the natural endianness of the target architecture.
@itemize *
@item
-"The contents of the visible part of package @cite{System}
+"The contents of the visible part of package @code{System}
and its language-defined children. See 13.7(2)."
@end itemize
@item
"The contents of the visible part of package
-@cite{System.Machine_Code}, and the meaning of
-@cite{code_statements}. See 13.8(7)."
+@code{System.Machine_Code}, and the meaning of
+@emph{code_statements}. See 13.8(7)."
@end itemize
See the definition and documentation in file @code{s-maccod.ads}.
@item
"The manner of choosing a storage pool for an access type
-when @cite{Storage_Pool} is not specified for the type. See 13.11(17)."
+when @code{Storage_Pool} is not specified for the type. See 13.11(17)."
@end itemize
There are 3 different standard pools used by the compiler when
-@cite{Storage_Pool} is not specified depending whether the type is local
+@code{Storage_Pool} is not specified depending whether the type is local
to a subprogram or defined at the library level and whether
-@cite{Storage_Size`is specified or not. See documentation in the runtime library units `System.Pool_Global}, @cite{System.Pool_Size} and
-@cite{System.Pool_Local} in files @code{s-poosiz.ads},
+@code{Storage_Size`@w{`}is specified or not. See documentation in the runtime
+library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and
+@code{System.Pool_Local} in files @code{s-poosiz.ads},
@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the
default pools used.
@end itemize
See documentation in the sources of the run time mentioned in the previous
-paragraph. All these pools are accessible by means of @cite{with}'ing
+paragraph. All these pools are accessible by means of @cite{with}ing
these units.
@itemize *
@item
-"The meaning of @cite{Storage_Size}. See 13.11(18)."
+"The meaning of @code{Storage_Size}. See 13.11(18)."
@end itemize
-@cite{Storage_Size} is measured in storage units, and refers to the
+@code{Storage_Size} is measured in storage units, and refers to the
total space available for an access type collection, or to the primary
stack space for a task.
@item
"The set of restrictions allowed in a pragma
-@cite{Restrictions}. See 13.12(7)."
+@code{Restrictions}. See 13.12(7)."
@end itemize
See @ref{9,,Standard and Implementation Defined Restrictions}.
@item
"The consequences of violating limitations on
-@cite{Restrictions} pragmas. See 13.12(9)."
+@code{Restrictions} pragmas. See 13.12(9)."
@end itemize
Restrictions that can be checked at compile time result in illegalities
@itemize *
@item
-"The representation used by the @cite{Read} and
-@cite{Write} attributes of elementary types in terms of stream
+"The representation used by the @code{Read} and
+@code{Write} attributes of elementary types in terms of stream
elements. See 13.13.2(9)."
@end itemize
@item
"The names and characteristics of the numeric subtypes
-declared in the visible part of package @cite{Standard}. See A.1(3)."
+declared in the visible part of package @code{Standard}. See A.1(3)."
@end itemize
See items describing the integer and floating-point types supported.
@itemize *
@item
-"The string returned by @cite{Character_Set_Version}.
+"The string returned by @code{Character_Set_Version}.
See A.3.5(3)."
@end itemize
-@cite{Ada.Wide_Characters.Handling.Character_Set_Version} returns
+@code{Ada.Wide_Characters.Handling.Character_Set_Version} returns
the string "Unicode 4.0", referring to version 4.0 of the
Unicode specification.
@item
"The sign of a zero result from some of the operators or
-functions in @cite{Numerics.Generic_Elementary_Functions}, when
-@cite{Float_Type'Signed_Zeros} is @cite{True}. See A.5.1(46)."
+functions in @code{Numerics.Generic_Elementary_Functions}, when
+@code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46)."
@end itemize
The sign of zeroes follows the requirements of the IEEE 754 standard on
@item
"The value of
-@cite{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27)."
+@code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27)."
@end itemize
Maximum image width is 6864, see library file @code{s-rannum.ads}.
@item
"The value of
-@cite{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27)."
+@code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27)."
@end itemize
Maximum image width is 6864, see library file @code{s-rannum.ads}.
@itemize *
@item
-"The values of the @cite{Model_Mantissa},
-@cite{Model_Emin}, @cite{Model_Epsilon}, @cite{Model},
-@cite{Safe_First}, and @cite{Safe_Last} attributes, if the Numerics
+"The values of the @code{Model_Mantissa},
+@code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
+@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
Annex is not supported. See A.5.3(72)."
@end itemize
Run the compiler with @emph{-gnatS} to produce a listing of package
-@cite{Standard}, has the values of all numeric attributes.
+@code{Standard}, has the values of all numeric attributes.
@itemize *
@itemize *
@item
-"The value of @cite{Buffer_Size} in @cite{Storage_IO}. See
+"The value of @code{Buffer_Size} in @code{Storage_IO}. See
A.9(10)."
@end itemize
-All type representations are contiguous, and the @cite{Buffer_Size} is
+All type representations are contiguous, and the @code{Buffer_Size} is
the value of @code{type'Size} rounded up to the next storage unit
boundary.
@itemize *
@item
-"The accuracy of the value produced by @cite{Put}. See
+"The accuracy of the value produced by @code{Put}. See
A.10.9(36)."
@end itemize
@itemize *
@item
-"The meaning of @cite{Argument_Count}, @cite{Argument}, and
-@cite{Command_Name}. See A.15(1)."
+"The meaning of @code{Argument_Count}, @code{Argument}, and
+@code{Command_Name}. See A.15(1)."
@end itemize
-These are mapped onto the @cite{argv} and @cite{argc} parameters of the
+These are mapped onto the @code{argv} and @code{argc} parameters of the
main program in the natural manner.
@itemize *
@item
-"The interpretation of the @cite{Form} parameter in procedure
-@cite{Create_Directory}. See A.16(56)."
+"The interpretation of the @code{Form} parameter in procedure
+@code{Create_Directory}. See A.16(56)."
@end itemize
-The @cite{Form} parameter is not used.
+The @code{Form} parameter is not used.
@itemize *
@item
-"The interpretation of the @cite{Form} parameter in procedure
-@cite{Create_Path}. See A.16(60)."
+"The interpretation of the @code{Form} parameter in procedure
+@code{Create_Path}. See A.16(60)."
@end itemize
-The @cite{Form} parameter is not used.
+The @code{Form} parameter is not used.
@itemize *
@item
-"The interpretation of the @cite{Form} parameter in procedure
-@cite{Copy_File}. See A.16(68)."
+"The interpretation of the @code{Form} parameter in procedure
+@code{Copy_File}. See A.16(68)."
@end itemize
-The @cite{Form} parameter is case-insensitive.
-Two fields are recognized in the @cite{Form} parameter:
+The @code{Form} parameter is case-insensitive.
+Two fields are recognized in the @code{Form} parameter:
@example
*preserve=<value>*
@itemize *
@item
-"The interpretation of the @cite{Pattern} parameter, when not the null string,
-in the @cite{Start_Search} and @cite{Search} procedures.
+"The interpretation of the @code{Pattern} parameter, when not the null string,
+in the @code{Start_Search} and @code{Search} procedures.
See A.16(104) and A.16(112)."
@end itemize
-When the @cite{Pattern} parameter is not the null string, it is interpreted
+When the @code{Pattern} parameter is not the null string, it is interpreted
according to the syntax of regular expressions as defined in the
-@cite{GNAT.Regexp} package.
+@code{GNAT.Regexp} package.
-See @ref{24c,,GNAT.Regexp (g-regexp.ads)}.
+See @ref{250,,GNAT.Regexp (g-regexp.ads)}.
@itemize *
@tab
-For support of pragma @cite{Import} with convention Intrinsic, see
+For support of pragma @code{Import} with convention Intrinsic, see
separate section on Intrinsic Subprograms.
@item
Stubbed is a special convention used to indicate that the body of the
subprogram will be entirely ignored. Any call to the subprogram
-is converted into a raise of the @cite{Program_Error} exception. If a
-pragma @cite{Import} specifies convention @cite{stubbed} then no body need
+is converted into a raise of the @code{Program_Error} exception. If a
+pragma @code{Import} specifies convention @code{stubbed} then no body need
be present at all. This convention is useful during development for the
inclusion of subprograms whose body has not yet been written.
In addition, all otherwise unrecognized convention names are also
@itemize *
@item
-"The effect of pragma @cite{Linker_Options}. See B.1(37)."
+"The effect of pragma @code{Linker_Options}. See B.1(37)."
@end itemize
-The string passed to @cite{Linker_Options} is presented uninterpreted as
+The string passed to @code{Linker_Options} is presented uninterpreted as
an argument to the link command, unless it contains ASCII.NUL characters.
NUL characters if they appear act as argument separators, so for example
pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
@end example
-causes two separate arguments @cite{-labc} and @cite{-ldef} to be passed to the
+causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
linker. The order of linker options is preserved for a given unit. The final
list of options passed to the linker is in reverse order of the elaboration
order. For example, linker options for a body always appear before the options
@item
"The contents of the visible part of package
-@cite{Interfaces} and its language-defined descendants. See B.2(1)."
+@code{Interfaces} and its language-defined descendants. See B.2(1)."
@end itemize
See files with prefix @code{i-} in the distributed library.
@item
"Implementation-defined children of package
-@cite{Interfaces}. The contents of the visible part of package
-@cite{Interfaces}. See B.2(11)."
+@code{Interfaces}. The contents of the visible part of package
+@code{Interfaces}. See B.2(11)."
@end itemize
See files with prefix @code{i-} in the distributed library.
@itemize *
@item
-"The types @cite{Floating}, @cite{Long_Floating},
-@cite{Binary}, @cite{Long_Binary}, @cite{Decimal_ Element}, and
-@cite{COBOL_Character}; and the initialization of the variables
-@cite{Ada_To_COBOL} and @cite{COBOL_To_Ada}, in
-@cite{Interfaces.COBOL}. See B.4(50)."
+"The types @code{Floating}, @code{Long_Floating},
+@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
+@code{COBOL_Character}; and the initialization of the variables
+@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
+@code{Interfaces.COBOL}. See B.4(50)."
@end itemize
Interrupts are mapped to signals or conditions as appropriate. See
definition of unit
-@cite{Ada.Interrupt_Names} in source file @code{a-intnam.ads} for details
+@code{Ada.Interrupt_Names} in source file @code{a-intnam.ads} for details
on the interrupts supported on a particular target.
@itemize *
@item
-"The semantics of pragma @cite{Discard_Names}. See C.5(7)."
+"The semantics of pragma @code{Discard_Names}. See C.5(7)."
@end itemize
-Pragma @cite{Discard_Names} causes names of enumeration literals to
+Pragma @code{Discard_Names} causes names of enumeration literals to
be suppressed. In the presence of this pragma, the Image attribute
provides the image of the Pos of the literal, and Value accepts
Pos values.
@itemize *
@item
-"The result of the @cite{Task_Identification.Image}
+"The result of the @code{Task_Identification.Image}
attribute. See C.7.1(7)."
@end itemize
The result of this attribute is a string that identifies
-the object or component that denotes a given task. If a variable @cite{Var}
-has a task type, the image for this task will have the form @cite{Var_`XXXXXXXX`},
-where the suffix
+the object or component that denotes a given task. If a variable @code{Var}
+has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}},
+where the suffix @emph{XXXXXXXX}
is the hexadecimal representation of the virtual address of the corresponding
task control block. If the variable is an array of tasks, the image of each
task will have the form of an indexed component indicating the position of a
-given task in the array, e.g., @cite{Group(5)_`XXXXXXX`}. If the task is a
+given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a
component of a record, the image of the task will have the form of a selected
component. These rules are fully recursive, so that the image of a task that
is a subcomponent of a composite object corresponds to the expression that
@itemize *
@item
-"The value of @cite{Current_Task} when in a protected entry
+"The value of @code{Current_Task} when in a protected entry
or interrupt handler. See C.7.1(17)."
@end itemize
Protected entries or interrupt handlers can be executed by any
-convenient thread, so the value of @cite{Current_Task} is undefined.
+convenient thread, so the value of @code{Current_Task} is undefined.
@itemize *
@item
-"The effect of calling @cite{Current_Task} from an entry
+"The effect of calling @code{Current_Task} from an entry
body or interrupt handler. See C.7.1(19)."
@end itemize
-The effect of calling @cite{Current_Task} from an entry body or
-interrupt handler is to return the identification of the task currently
-executing the code.
+When GNAT can determine statically that @code{Current_Task} is called directly in
+the body of an entry (or barrier) then a warning is emitted and @code{Program_Error}
+is raised at run time. Otherwise, the effect of calling @code{Current_Task} from an
+entry body or interrupt handler is to return the identification of the task
+currently executing the code.
@itemize *
@item
"Implementation-defined aspects of
-@cite{Task_Attributes}. See C.7.2(19)."
+@code{Task_Attributes}. See C.7.2(19)."
@end itemize
-There are no implementation-defined aspects of @cite{Task_Attributes}.
+There are no implementation-defined aspects of @code{Task_Attributes}.
@itemize *
@item
-"Values of all @cite{Metrics}. See D(2)."
+"Values of all @code{Metrics}. See D(2)."
@end itemize
The metrics information for GNAT depends on the performance of the
@itemize *
@item
-"The declarations of @cite{Any_Priority} and
-@cite{Priority}. See D.1(11)."
+"The declarations of @code{Any_Priority} and
+@code{Priority}. See D.1(11)."
@end itemize
See declarations in file @code{system.ads}.
@itemize *
@item
-"Implementation-defined @cite{policy_identifiers} allowed
-in a pragma @cite{Task_Dispatching_Policy}. See D.2.2(3)."
+"Implementation-defined @emph{policy_identifiers} allowed
+in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3)."
@end itemize
There are no implementation-defined policy-identifiers allowed in this
@itemize *
@item
-"Implementation-defined @cite{policy_identifiers} allowed
-in a pragma @cite{Locking_Policy}. See D.3(4)."
+"Implementation-defined @emph{policy_identifiers} allowed
+in a pragma @code{Locking_Policy}. See D.3(4)."
@end itemize
The two implementation defined policies permitted in GNAT are
-@cite{Inheritance_Locking} and @cite{Concurrent_Readers_Locking}. On
-targets that support the @cite{Inheritance_Locking} policy, locking is
+@code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On
+targets that support the @code{Inheritance_Locking} policy, locking is
implemented by inheritance, i.e., the task owning the lock operates
at a priority equal to the highest priority of any task currently
requesting the lock. On targets that support the
-@cite{Concurrent_Readers_Locking} policy, locking is implemented with a
+@code{Concurrent_Readers_Locking} policy, locking is implemented with a
read/write lock allowing multiple protected object functions to enter
concurrently.
@end itemize
The ceiling priority of protected objects of the type
-@cite{System.Interrupt_Priority'Last} as described in the Ada
+@code{System.Interrupt_Priority'Last} as described in the Ada
Reference Manual D.3(10),
@end itemize
The ceiling priority of internal protected objects is
-@cite{System.Priority'Last}.
+@code{System.Priority'Last}.
@itemize *
@item
"What happens when a task terminates in the presence of
-pragma @cite{No_Task_Termination}. See D.7(15)."
+pragma @code{No_Task_Termination}. See D.7(15)."
@end itemize
Execution is erroneous in that case.
@item
"Implementation-defined aspects of pragma
-@cite{Restrictions}. See D.7(20)."
+@code{Restrictions}. See D.7(20)."
@end itemize
There are no such implementation-defined aspects.
@item
"Implementation-defined aspects of package
-@cite{Real_Time}. See D.8(17)."
+@code{Real_Time}. See D.8(17)."
@end itemize
-There are no implementation defined aspects of package @cite{Real_Time}.
+There are no implementation defined aspects of package @code{Real_Time}.
@itemize *
@item
"Implementation-defined aspects of
-@cite{delay_statements}. See D.9(8)."
+@emph{delay_statements}. See D.9(8)."
@end itemize
Any difference greater than one microsecond will cause the task to be
@item
"The values of named numbers in the package
-@cite{Decimal}. See F.2(7)."
+@code{Decimal}. See F.2(7)."
@end itemize
@itemize *
@item
-"The value of @cite{Max_Picture_Length} in the package
-@cite{Text_IO.Editing}. See F.3.3(16)."
+"The value of @code{Max_Picture_Length} in the package
+@code{Text_IO.Editing}. See F.3.3(16)."
@end itemize
64
@itemize *
@item
-"The value of @cite{Max_Picture_Length} in the package
-@cite{Wide_Text_IO.Editing}. See F.3.4(5)."
+"The value of @code{Max_Picture_Length} in the package
+@code{Wide_Text_IO.Editing}. See F.3.4(5)."
@end itemize
64
@item
"The sign of a zero result (or a component thereof) from
-any operator or function in @cite{Numerics.Generic_Complex_Types}, when
-@cite{Real'Signed_Zeros} is True. See G.1.1(53)."
+any operator or function in @code{Numerics.Generic_Complex_Types}, when
+@code{Real'Signed_Zeros} is True. See G.1.1(53)."
@end itemize
The signs of zero values are as recommended by the relevant
@item
"The sign of a zero result (or a component thereof) from
any operator or function in
-@cite{Numerics.Generic_Complex_Elementary_Functions}, when
-@cite{Real'Signed_Zeros} is @cite{True}. See G.1.2(45)."
+@code{Numerics.Generic_Complex_Elementary_Functions}, when
+@code{Real'Signed_Zeros} is @code{True}. See G.1.2(45)."
@end itemize
The signs of zero values are as recommended by the relevant
@item
"The result of a floating point arithmetic operation in
-overflow situations, when the @cite{Machine_Overflows} attribute of the
-result type is @cite{False}. See G.2.1(13)."
+overflow situations, when the @code{Machine_Overflows} attribute of the
+result type is @code{False}. See G.2.1(13)."
@end itemize
Infinite and NaN values are produced as dictated by the IEEE
@itemize *
@item
-"Conditions on a @cite{universal_real} operand of a fixed
+"Conditions on a @emph{universal_real} operand of a fixed
point multiplication or division for which the result shall be in the
perfect result set. See G.2.3(22)."
@end itemize
@item
"The result of a fixed point arithmetic operation in
-overflow situations, when the @cite{Machine_Overflows} attribute of the
-result type is @cite{False}. See G.2.3(27)."
+overflow situations, when the @code{Machine_Overflows} attribute of the
+result type is @code{False}. See G.2.3(27)."
@end itemize
-Not relevant, @cite{Machine_Overflows} is @cite{True} for fixed-point
+Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
types.
@item
"The result of an elementary function reference in
-overflow situations, when the @cite{Machine_Overflows} attribute of the
-result type is @cite{False}. See G.2.4(4)."
+overflow situations, when the @code{Machine_Overflows} attribute of the
+result type is @code{False}. See G.2.4(4)."
@end itemize
IEEE infinite and Nan values are produced as appropriate.
@item
"The result of a complex arithmetic operation or complex
elementary function reference in overflow situations, when the
-@cite{Machine_Overflows} attribute of the corresponding real type is
-@cite{False}. See G.2.6(5)."
+@code{Machine_Overflows} attribute of the corresponding real type is
+@code{False}. See G.2.6(5)."
@end itemize
IEEE infinite and Nan values are produced as appropriate.
@item
"Implementation-defined aspects of pragma
-@cite{Inspection_Point}. See H.3.2(8)."
+@code{Inspection_Point}. See H.3.2(8)."
@end itemize
-Pragma @cite{Inspection_Point} ensures that the variable is live and can
+Pragma @code{Inspection_Point} ensures that the variable is live and can
be examined by the debugger at the inspection point.
@item
"Implementation-defined aspects of pragma
-@cite{Restrictions}. See H.4(25)."
+@code{Restrictions}. See H.4(25)."
@end itemize
-There are no implementation-defined aspects of pragma @cite{Restrictions}. The
-use of pragma @cite{Restrictions [No_Exceptions]} has no effect on the
-generated code. Checks must suppressed by use of pragma @cite{Suppress}.
+There are no implementation-defined aspects of pragma @code{Restrictions}. The
+use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
+generated code. Checks must suppressed by use of pragma @code{Suppress}.
@itemize *
@item
-"Any restrictions on pragma @cite{Restrictions}. See
+"Any restrictions on pragma @code{Restrictions}. See
H.4(27)."
@end itemize
-There are no restrictions on pragma @cite{Restrictions}.
+There are no restrictions on pragma @code{Restrictions}.
@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top
-@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{24d}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{24e}
+@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{251}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{252}
@chapter Intrinsic Subprograms
@end menu
@node Intrinsic Operators,Compilation_Date,,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{24f}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{250}
+@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{253}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{254}
@section Intrinsic Operators
@geindex Intrinsic operator
All the predefined numeric operators in package Standard
-in @cite{pragma Import (Intrinsic@comma{}..)}
+in @code{pragma Import (Intrinsic,..)}
declarations. In the binary operator case, the operands must have the same
size. The operand or operands must also be appropriate for
the operator. For example, for addition, the operands must
both be floating-point or both be fixed-point, and the
-right operand for @cite{"**"} must have a root type of
-@cite{Standard.Integer'Base}.
+right operand for @code{"**"} must have a root type of
+@code{Standard.Integer'Base}.
You can use an intrinsic operator declaration as in the following example:
@example
@end example
This declaration would permit 'mixed mode' arithmetic on items
-of the differing types @cite{Int1} and @cite{Int2}.
+of the differing types @code{Int1} and @code{Int2}.
It is also possible to specify such operators for private types, if the
full views are appropriate arithmetic types.
@node Compilation_Date,Compilation_Time,Intrinsic Operators,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{251}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{252}
+@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{255}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{256}
@section Compilation_Date
@geindex Compilation_Date
This intrinsic subprogram is used in the implementation of the
-library package @cite{GNAT.Source_Info}. The only useful use of the
+library package @code{GNAT.Source_Info}. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-@cite{GNAT.Source_Info.Compilation_Date} to obtain the date of
-the current compilation (in local time format MMM DD YYYY).
+@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of
+the current compilation (in local time format YYYY-MM-DD).
@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{253}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{254}
+@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{257}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{258}
@section Compilation_Time
@geindex Compilation_Time
This intrinsic subprogram is used in the implementation of the
-library package @cite{GNAT.Source_Info}. The only useful use of the
+library package @code{GNAT.Source_Info}. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-@cite{GNAT.Source_Info.Compilation_Time} to obtain the time of
+@code{GNAT.Source_Info.Compilation_Time} to obtain the time of
the current compilation (in local time format HH:MM:SS).
@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{255}@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{256}
+@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{259}@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{25a}
@section Enclosing_Entity
@geindex Enclosing_Entity
This intrinsic subprogram is used in the implementation of the
-library package @cite{GNAT.Source_Info}. The only useful use of the
+library package @code{GNAT.Source_Info}. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-@cite{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
+@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
the current subprogram, package, task, entry, or protected subprogram.
@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{257}@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{258}
+@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{25b}@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{25c}
@section Exception_Information
@geindex Exception_Information'
This intrinsic subprogram is used in the implementation of the
-library package @cite{GNAT.Current_Exception}. The only useful
+library package @code{GNAT.Current_Exception}. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
-@cite{GNAT.Current_Exception.Exception_Information} to obtain
+@code{GNAT.Current_Exception.Exception_Information} to obtain
the exception information associated with the current exception.
@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{259}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{25a}
+@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{25d}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{25e}
@section Exception_Message
@geindex Exception_Message
This intrinsic subprogram is used in the implementation of the
-library package @cite{GNAT.Current_Exception}. The only useful
+library package @code{GNAT.Current_Exception}. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
-@cite{GNAT.Current_Exception.Exception_Message} to obtain
+@code{GNAT.Current_Exception.Exception_Message} to obtain
the message associated with the current exception.
@node Exception_Name,File,Exception_Message,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{25b}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{25c}
+@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{260}
@section Exception_Name
@geindex Exception_Name
This intrinsic subprogram is used in the implementation of the
-library package @cite{GNAT.Current_Exception}. The only useful
+library package @code{GNAT.Current_Exception}. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
-@cite{GNAT.Current_Exception.Exception_Name} to obtain
+@code{GNAT.Current_Exception.Exception_Name} to obtain
the name of the current exception.
@node File,Line,Exception_Name,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms file}@anchor{25d}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{25e}
+@anchor{gnat_rm/intrinsic_subprograms file}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{262}
@section File
@geindex File
This intrinsic subprogram is used in the implementation of the
-library package @cite{GNAT.Source_Info}. The only useful use of the
+library package @code{GNAT.Source_Info}. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-@cite{GNAT.Source_Info.File} to obtain the name of the current
+@code{GNAT.Source_Info.File} to obtain the name of the current
file.
@node Line,Shifts and Rotates,File,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{260}
+@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{264}
@section Line
@geindex Line
This intrinsic subprogram is used in the implementation of the
-library package @cite{GNAT.Source_Info}. The only useful use of the
+library package @code{GNAT.Source_Info}. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-@cite{GNAT.Source_Info.Line} to obtain the number of the current
+@code{GNAT.Source_Info.Line} to obtain the number of the current
source line.
@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{262}
+@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{266}
@section Shifts and Rotates
@geindex Rotate_Right
In standard Ada, the shift and rotate functions are available only
-for the predefined modular types in package @cite{Interfaces}. However, in
+for the predefined modular types in package @code{Interfaces}. However, in
GNAT it is possible to define these functions for any integer
type (signed or modular), as in this example:
Rotate_Right. T must be an integer type. T'Size must be
8, 16, 32 or 64 bits; if T is modular, the modulus
must be 2**8, 2**16, 2**32 or 2**64.
-The result type must be the same as the type of @cite{Value}.
+The result type must be the same as the type of @code{Value}.
The shift amount must be Natural.
The formal parameter names can be anything.
and corresponding pragma Import's for all five shift functions.
@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms
-@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{264}
+@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{268}
@section Source_Location
@geindex Source_Location
This intrinsic subprogram is used in the implementation of the
-library routine @cite{GNAT.Source_Info}. The only useful use of the
+library routine @code{GNAT.Source_Info}. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
-@cite{GNAT.Source_Info.Source_Location} to obtain the current
+@code{GNAT.Source_Info.Source_Location} to obtain the current
source file location.
@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top
-@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{265}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{266}
+@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{269}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{26a}
@chapter Representation Clauses and Pragmas
@end menu
@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{267}@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{268}
+@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{26b}@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{26c}
@section Alignment Clauses
@emph{Elementary Types}.
For elementary types, the alignment is the minimum of the actual size of
-objects of the type divided by @cite{Storage_Unit},
+objects of the type divided by @code{Storage_Unit},
and the maximum alignment supported by the target.
(This maximum alignment is given by the GNAT-specific attribute
-@cite{Standard'Maximum_Alignment}; see @ref{185,,Attribute Maximum_Alignment}.)
+@code{Standard'Maximum_Alignment}; see @ref{189,,Attribute Maximum_Alignment}.)
@geindex Maximum_Alignment attribute
-For example, for type @cite{Long_Float}, the object size is 8 bytes, and the
+For example, for type @code{Long_Float}, the object size is 8 bytes, and the
default alignment will be 8 on any target that supports alignments
this large, but on some targets, the maximum alignment may be smaller
-than 8, in which case objects of type @cite{Long_Float} will be maximally
+than 8, in which case objects of type @code{Long_Float} will be maximally
aligned.
@item
For the normal non-packed case, the alignment of a record is equal to
the maximum alignment of any of its components. For tagged records, this
-includes the implicit access type used for the tag. If a pragma @cite{Pack}
+includes the implicit access type used for the tag. If a pragma @code{Pack}
is used and all components are packable (see separate section on pragma
-@cite{Pack}), then the resulting alignment is 1, unless the layout of the
+@code{Pack}), then the resulting alignment is 1, unless the layout of the
record makes it profitable to increase it.
A special case is when:
for Small'Size use 16;
@end example
-then the default alignment of the record type @cite{Small} is 2, not 1. This
+then the default alignment of the record type @code{Small} is 2, not 1. This
leads to more efficient code when the record is treated as a unit, and also
-allows the type to specified as @cite{Atomic} on architectures requiring
+allows the type to specified as @code{Atomic} on architectures requiring
strict alignment.
@end itemize
An alignment clause may specify a larger alignment than the default value
up to some maximum value dependent on the target (obtainable by using the
-attribute reference @cite{Standard'Maximum_Alignment}). It may also specify
+attribute reference @code{Standard'Maximum_Alignment}). It may also specify
a smaller alignment than the default value for enumeration, integer and
fixed point types, as well as for record types, for example
@geindex Alignment
@geindex default
-The default alignment for the type @cite{V} is 4, as a result of the
+The default alignment for the type @code{V} is 4, as a result of the
Integer field in the record, but it is permissible, as shown, to
override the default alignment of the record with a smaller value.
@end example
The alignment clause specifies an alignment of 1 for the first named subtype
-@cite{R} but this does not necessarily apply to @cite{RS}. When writing
+@code{R} but this does not necessarily apply to @code{RS}. When writing
portable Ada code, you should avoid writing code that explicitly or
implicitly relies on the alignment of such subtypes.
For the GNAT compiler, if an explicit alignment clause is given, this
value is also used for any subsequent subtypes. So for GNAT, in the
-above example, you can count on the alignment of @cite{RS} being 1. But this
+above example, you can count on the alignment of @code{RS} being 1. But this
assumption is non-portable, and other compilers may choose different
-alignments for the subtype @cite{RS}.
+alignments for the subtype @code{RS}.
@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{269}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{26a}
+@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{26d}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{26e}
@section Size Clauses
@geindex Size Clause
-The default size for a type @cite{T} is obtainable through the
-language-defined attribute @cite{T'Size} and also through the
-equivalent GNAT-defined attribute @cite{T'Value_Size}.
-For objects of type @cite{T}, GNAT will generally increase the type size
+The default size for a type @code{T} is obtainable through the
+language-defined attribute @code{T'Size} and also through the
+equivalent GNAT-defined attribute @code{T'Value_Size}.
+For objects of type @code{T}, GNAT will generally increase the type size
so that the object size (obtainable through the GNAT-defined attribute
-@cite{T'Object_Size})
-is a multiple of @cite{T'Alignment * Storage_Unit}.
+@code{T'Object_Size})
+is a multiple of @code{T'Alignment * Storage_Unit}.
For example:
end record;
@end example
-In this example, @cite{Smallint'Size} = @cite{Smallint'Value_Size} = 3,
+In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
as specified by the RM rules,
but objects of this type will have a size of 8
-(@cite{Smallint'Object_Size} = 8),
+(@code{Smallint'Object_Size} = 8),
since objects by default occupy an integral number
of storage units. On some targets, notably older
versions of the Digital Alpha, the size of stand
alone objects of this type may be 32, reflecting
the inability of the hardware to do byte load/stores.
-Similarly, the size of type @cite{Rec} is 40 bits
-(@cite{Rec'Size} = @cite{Rec'Value_Size} = 40), but
+Similarly, the size of type @code{Rec} is 40 bits
+(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
the alignment is 4, so objects of this type will have
their size increased to 64 bits so that it is a multiple
of the alignment (in bits). This decision is
@quotation
-"A @cite{Size} clause should be supported for an object if the specified
-@cite{Size} is at least as large as its subtype's @cite{Size}, and corresponds
+"A @code{Size} clause should be supported for an object if the specified
+@code{Size} is at least as large as its subtype's @code{Size}, and corresponds
to a size in storage elements that is a multiple of the object's
-@cite{Alignment} (if the @cite{Alignment} is nonzero)."
+@code{Alignment} (if the @code{Alignment} is nonzero)."
@end quotation
An explicit size clause may be used to override the default size by
type Integer.
@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{26b}@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{26c}
+@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{26f}@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{270}
@section Storage_Size Clauses
@geindex Storage_Size Clause
-For tasks, the @cite{Storage_Size} clause specifies the amount of space
+For tasks, the @code{Storage_Size} clause specifies the amount of space
to be allocated for the task stack. This cannot be extended, and if the
-stack is exhausted, then @cite{Storage_Error} will be raised (if stack
-checking is enabled). Use a @cite{Storage_Size} attribute definition clause,
-or a @cite{Storage_Size} pragma in the task definition to set the
+stack is exhausted, then @code{Storage_Error} will be raised (if stack
+checking is enabled). Use a @code{Storage_Size} attribute definition clause,
+or a @code{Storage_Size} pragma in the task definition to set the
appropriate required size. A useful technique is to include in every
task definition a pragma of the form:
pragma Storage_Size (Default_Stack_Size);
@end example
-Then @cite{Default_Stack_Size} can be defined in a global package, and
+Then @code{Default_Stack_Size} can be defined in a global package, and
modified as required. Any tasks requiring stack sizes different from the
default can have an appropriate alternative reference in the pragma.
You can also use the @emph{-d} binder switch to modify the default stack
size.
-For access types, the @cite{Storage_Size} clause specifies the maximum
+For access types, the @code{Storage_Size} clause specifies the maximum
space available for allocation of objects of the type. If this space is
-exceeded then @cite{Storage_Error} will be raised by an allocation attempt.
+exceeded then @code{Storage_Error} will be raised by an allocation attempt.
In the case where the access type is declared local to a subprogram, the
-use of a @cite{Storage_Size} clause triggers automatic use of a special
-predefined storage pool (@cite{System.Pool_Size}) that ensures that all
+use of a @code{Storage_Size} clause triggers automatic use of a special
+predefined storage pool (@code{System.Pool_Size}) that ensures that all
space for the pool is automatically reclaimed on exit from the scope in
which the type is declared.
A special case recognized by the compiler is the specification of a
-@cite{Storage_Size} of zero for an access type. This means that no
+@code{Storage_Size} of zero for an access type. This means that no
items can be allocated from the pool, and this is recognized at compile
time, and all the overhead normally associated with maintaining a fixed
size storage pool is eliminated. Consider the following example:
case of such an access declaration.
@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{26d}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{26e}
+@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{271}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{272}
@section Size of Variant Record Objects
in the general case, even fewer bits may be needed at any particular
point during the program execution.
-As can be seen from the output of this program, the @cite{'Size}
+As can be seen from the output of this program, the @code{'Size}
attribute applied to such an object in GNAT gives the actual allocated
size of the variable, which is the largest size of any of the variants.
The Ada Reference Manual is not completely clear on what choice should
16
@end example
-Here we see that while the @cite{'Size} attribute always returns
+Here we see that while the @code{'Size} attribute always returns
the maximum size, regardless of the current variant value, the
-@cite{Size} function does indeed return the size of the current
+@code{Size} function does indeed return the size of the current
variant value.
@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{26f}@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{270}
+@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{273}@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{274}
@section Biased Representation
for Small'Size use 2;
@end example
-Although the default size of type @cite{Small} is 4, the @cite{Size}
+Although the default size of type @code{Small} is 4, the @code{Size}
clause is accepted by GNAT and results in the following representation
scheme:
-4 is represented as 2#11#
@end example
-Biased representation is only used if the specified @cite{Size} clause
+Biased representation is only used if the specified @code{Size} clause
cannot be accepted in any other manner. These reduced sizes that force
biased representation can be used for all discrete types except for
enumeration types for which a representation clause is given.
@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{271}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{272}
+@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{275}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{276}
@section Value_Size and Object_Size Clauses
@geindex Size
@geindex of objects
-In Ada 95 and Ada 2005, @cite{T'Size} for a type @cite{T} is the minimum
-number of bits required to hold values of type @cite{T}.
+In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum
+number of bits required to hold values of type @code{T}.
Although this interpretation was allowed in Ada 83, it was not required,
and this requirement in practice can cause some significant difficulties.
-For example, in most Ada 83 compilers, @cite{Natural'Size} was 32.
+For example, in most Ada 83 compilers, @code{Natural'Size} was 32.
However, in Ada 95 and Ada 2005,
-@cite{Natural'Size} is
+@code{Natural'Size} is
typically 31. This means that code may change in behavior when moving
from Ada 83 to Ada 95 or Ada 2005. For example, consider:
end record;
@end example
-In the above code, since the typical size of @cite{Natural} objects
-is 32 bits and @cite{Natural'Size} is 31, the above code can cause
+In the above code, since the typical size of @code{Natural} objects
+is 32 bits and @code{Natural'Size} is 31, the above code can cause
unexpected inefficient packing in Ada 95 and Ada 2005, and in general
there are cases where the fact that the object size can exceed the
size of the type causes surprises.
To help get around this problem GNAT provides two implementation
-defined attributes, @cite{Value_Size} and @cite{Object_Size}. When
+defined attributes, @code{Value_Size} and @code{Object_Size}. When
applied to a type, these attributes yield the size of the type
(corresponding to the RM defined size attribute), and the size of
objects of the type respectively.
-The @cite{Object_Size} is used for determining the default size of
+The @code{Object_Size} is used for determining the default size of
objects and components. This size value can be referred to using the
-@cite{Object_Size} attribute. The phrase 'is used' here means that it is
+@code{Object_Size} attribute. The phrase 'is used' here means that it is
the basis of the determination of the size. The backend is free to
pad this up if necessary for efficiency, e.g., an 8-bit stand-alone
character might be stored in 32 bits on a machine with no efficient
byte access instructions such as the Alpha.
-The default rules for the value of @cite{Object_Size} for
+The default rules for the value of @code{Object_Size} for
discrete types are as follows:
@itemize *
@item
-The @cite{Object_Size} for base subtypes reflect the natural hardware
+The @code{Object_Size} for base subtypes reflect the natural hardware
size in bits (run the compiler with @emph{-gnatS} to find those values
for numeric types). Enumeration types and fixed-point base subtypes have
8, 16, 32, or 64 bits for this size, depending on the range of values
to be stored.
@item
-The @cite{Object_Size} of a subtype is the same as the
-@cite{Object_Size} of
+The @code{Object_Size} of a subtype is the same as the
+@code{Object_Size} of
the type from which it is obtained.
@item
-The @cite{Object_Size} of a derived base type is copied from the parent
-base type, and the @cite{Object_Size} of a derived first subtype is copied
+The @code{Object_Size} of a derived base type is copied from the parent
+base type, and the @code{Object_Size} of a derived first subtype is copied
from the parent first subtype.
@end itemize
-The @cite{Value_Size} attribute
+The @code{Value_Size} attribute
is the (minimum) number of bits required to store a value
of the type.
This value is used to determine how tightly to pack
records or arrays with components of this type, and also affects
the semantics of unchecked conversion (unchecked conversions where
-the @cite{Value_Size} values differ generate a warning, and are potentially
+the @code{Value_Size} values differ generate a warning, and are potentially
target dependent).
-The default rules for the value of @cite{Value_Size} are as follows:
+The default rules for the value of @code{Value_Size} are as follows:
@itemize *
@item
-The @cite{Value_Size} for a base subtype is the minimum number of bits
+The @code{Value_Size} for a base subtype is the minimum number of bits
required to store all values of the type (including the sign bit
only if negative values are possible).
@item
If a subtype statically matches the first subtype of a given type, then it has
-by default the same @cite{Value_Size} as the first subtype. This is a
+by default the same @code{Value_Size} as the first subtype. This is a
consequence of RM 13.1(14): "if two subtypes statically match,
then their subtype-specific aspects are the same".)
@item
-All other subtypes have a @cite{Value_Size} corresponding to the minimum
+All other subtypes have a @code{Value_Size} corresponding to the minimum
number of bits required to store all values of the subtype. For
dynamic bounds, it is assumed that the value can range down or up
to the corresponding bound of the ancestor
@end itemize
-The RM defined attribute @cite{Size} corresponds to the
-@cite{Value_Size} attribute.
+The RM defined attribute @code{Size} corresponds to the
+@code{Value_Size} attribute.
-The @cite{Size} attribute may be defined for a first-named subtype. This sets
-the @cite{Value_Size} of
+The @code{Size} attribute may be defined for a first-named subtype. This sets
+the @code{Value_Size} of
the first-named subtype to the given value, and the
-@cite{Object_Size} of this first-named subtype to the given value padded up
+@code{Object_Size} of this first-named subtype to the given value padded up
to an appropriate boundary. It is a consequence of the default rules
-above that this @cite{Object_Size} will apply to all further subtypes. On the
-other hand, @cite{Value_Size} is affected only for the first subtype, any
+above that this @code{Object_Size} will apply to all further subtypes. On the
+other hand, @code{Value_Size} is affected only for the first subtype, any
dynamic subtypes obtained from it directly, and any statically matching
-subtypes. The @cite{Value_Size} of any other static subtypes is not affected.
+subtypes. The @code{Value_Size} of any other static subtypes is not affected.
-@cite{Value_Size} and
-@cite{Object_Size} may be explicitly set for any subtype using
+@code{Value_Size} and
+@code{Object_Size} may be explicitly set for any subtype using
an attribute definition clause. Note that the use of these attributes
can cause the RM 13.1(14) rule to be violated. If two access types
-reference aliased objects whose subtypes have differing @cite{Object_Size}
+reference aliased objects whose subtypes have differing @code{Object_Size}
values as a result of explicit attribute definition clauses, then it
is illegal to convert from one access subtype to the other. For a more
complete description of this additional legality rule, see the
-description of the @cite{Object_Size} attribute.
+description of the @code{Object_Size} attribute.
To get a feel for the difference, consider the following examples (note
-that in each case the base is @cite{Short_Short_Integer} with a size of 8):
+that in each case the base is @code{Short_Short_Integer} with a size of 8):
@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx}
possible dynamic values for the bounds at run-time.
So far, so good, but GNAT has to obey the RM rules, so the question is
-under what conditions must the RM @cite{Size} be used.
+under what conditions must the RM @code{Size} be used.
The following is a list
-of the occasions on which the RM @cite{Size} must be used:
+of the occasions on which the RM @code{Size} must be used:
@itemize *
Component size for packed arrays or records
@item
-Value of the attribute @cite{Size} for a type
+Value of the attribute @code{Size} for a type
@item
Warning about sizes not matching for unchecked conversion
@end itemize
-For record types, the @cite{Object_Size} is always a multiple of the
+For record types, the @code{Object_Size} is always a multiple of the
alignment of the type (this is true for all types). In some cases the
-@cite{Value_Size} can be smaller. Consider:
+@code{Value_Size} can be smaller. Consider:
@example
type R is record
On a typical 32-bit architecture, the X component will be four bytes, and
require four-byte alignment, and the Y component will be one byte. In this
-case @cite{R'Value_Size} will be 40 (bits) since this is the minimum size
+case @code{R'Value_Size} will be 40 (bits) since this is the minimum size
required to store a value of this type, and for example, it is permissible
to have a component of type R in an outer array whose component size is
-specified to be 48 bits. However, @cite{R'Object_Size} will be 64 (bits),
+specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits),
since it must be rounded up so that this value is a multiple of the
alignment (4 bytes = 32 bits).
-For all other types, the @cite{Object_Size}
-and @cite{Value_Size} are the same (and equivalent to the RM attribute @cite{Size}).
-Only @cite{Size} may be specified for such types.
+For all other types, the @code{Object_Size}
+and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}).
+Only @code{Size} may be specified for such types.
-Note that @cite{Value_Size} can be used to force biased representation
+Note that @code{Value_Size} can be used to force biased representation
for a particular subtype. Consider this example:
@example
subtype REF is R range E .. F;
@end example
-By default, @cite{RAB}
+By default, @code{RAB}
has a size of 1 (sufficient to accommodate the representation
-of @cite{A} and @cite{B}, 0 and 1), and @cite{REF}
+of @code{A} and @code{B}, 0 and 1), and @code{REF}
has a size of 3 (sufficient to accommodate the representation
-of @cite{E} and @cite{F}, 4 and 5). But if we add the
-following @cite{Value_Size} attribute definition clause:
+of @code{E} and @code{F}, 4 and 5). But if we add the
+following @code{Value_Size} attribute definition clause:
@example
for REF'Value_Size use 1;
@end example
-then biased representation is forced for @cite{REF},
-and 0 will represent @cite{E} and 1 will represent @cite{F}.
-A warning is issued when a @cite{Value_Size} attribute
+then biased representation is forced for @code{REF},
+and 0 will represent @code{E} and 1 will represent @code{F}.
+A warning is issued when a @code{Value_Size} attribute
definition clause forces biased representation. This
-warning can be turned off using @cite{-gnatw.B}.
+warning can be turned off using @code{-gnatw.B}.
@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{273}@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{274}
+@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{277}@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{278}
@section Component_Size Clauses
clauses are given, the pragma Pack will be ignored.
@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{275}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{276}
+@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{27a}
@section Bit_Order Clauses
@geindex ordering
@geindex of bits
-For record subtypes, GNAT permits the specification of the @cite{Bit_Order}
+For record subtypes, GNAT permits the specification of the @code{Bit_Order}
attribute. The specification may either correspond to the default bit
order for the target, in which case the specification has no effect and
places no additional restrictions, or it may be for the non-standard
Components fitting within a single storage unit.
These are unrestricted, and the effect is merely to renumber bits. For
-example if we are on a little-endian machine with @cite{Low_Order_First}
+example if we are on a little-endian machine with @code{Low_Order_First}
being the default, then the following two declarations have exactly
the same effect:
@end example
The useful application here is to write the second declaration with the
-@cite{Bit_Order} attribute definition clause, and know that it will be treated
+@code{Bit_Order} attribute definition clause, and know that it will be treated
the same, regardless of whether the target is little-endian or big-endian.
@item
These are components that exactly fit in two or more bytes. Such component
declarations are allowed, but have no effect, since it is important to realize
-that the @cite{Bit_Order} specification does not affect the ordering of bytes.
+that the @code{Bit_Order} specification does not affect the ordering of bytes.
In particular, the following attempt at getting an endian-independent integer
does not work:
little-endian machine, and a big-endian integer on a big-endian machine.
If byte flipping is required for interoperability between big- and
little-endian machines, this must be explicitly programmed. This capability
-is not provided by @cite{Bit_Order}.
+is not provided by @code{Bit_Order}.
@item
Components that are positioned across byte boundaries.
Since the misconception that Bit_Order automatically deals with all
endian-related incompatibilities is a common one, the specification of
a component field that is an integral number of bytes will always
-generate a warning. This warning may be suppressed using @cite{pragma Warnings (Off)}
+generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)}
if desired. The following section contains additional
details regarding the issue of byte ordering.
@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{277}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{278}
+@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{27b}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{27c}
@section Effect of Bit_Order on Byte Ordering
@geindex ordering
@geindex of bytes
-In this section we will review the effect of the @cite{Bit_Order} attribute
+In this section we will review the effect of the @code{Bit_Order} attribute
definition clause on byte ordering. Briefly, it has no effect at all, but
a detailed example will be helpful. Before giving this
example, let us review the precise
-definition of the effect of defining @cite{Bit_Order}. The effect of a
+definition of the effect of defining @code{Bit_Order}. The effect of a
non-standard bit order is described in section 13.5.3 of the Ada
Reference Manual:
@end quotation
The critical point here is that storage places are taken from
-the values after normalization, not before. So the @cite{Bit_Order}
+the values after normalization, not before. So the @code{Bit_Order}
interpretation applies to normalized values. The interpretation
is described in the later part of the 13.5.3 paragraph:
It is a nuisance to have to rewrite the clause, especially if
the code has to be maintained on both machines. However,
this is a case that we can handle with the
-@cite{Bit_Order} attribute if it is implemented.
+@code{Bit_Order} attribute if it is implemented.
Note that the implementation is not required on byte addressed
machines, but it is indeed implemented in GNAT.
This means that we can simply use the
machine.
The important point to understand is that byte ordering is not affected.
-A @cite{Bit_Order} attribute definition never affects which byte a field
+A @code{Bit_Order} attribute definition never affects which byte a field
ends up in, only where it ends up in that byte.
To make this clear, let us rewrite the record rep clause of the previous
example as:
end record;
@end example
-Why are they equivalent? Well take a specific field, the @cite{Slave_V2}
+Why are they equivalent? Well take a specific field, the @code{Slave_V2}
field. The storage place attributes are obtained by normalizing the
-values given so that the @cite{First_Bit} value is less than 8. After
+values given so that the @code{First_Bit} value is less than 8. After
normalizing the values (0,10,10) we get (1,2,2) which is exactly what
we specified in the other case.
-Now one might expect that the @cite{Bit_Order} attribute might affect
+Now one might expect that the @code{Bit_Order} attribute might affect
bit numbering within the entire record component (two bytes in this
case, thus affecting which byte fields end up in), but that is not
the way this feature is defined, it only affects numbering of bits,
Consequently it never makes sense to specify a starting bit number
greater than 7 (for a byte addressable field) if an attribute
-definition for @cite{Bit_Order} has been given, and indeed it
+definition for @code{Bit_Order} has been given, and indeed it
may be actively confusing to specify such a value, so the compiler
generates a warning for such usage.
@end example
Now to switch between machines, all that is necessary is
-to set the boolean constant @cite{Master_Byte_First} in
+to set the boolean constant @code{Master_Byte_First} in
an appropriate manner.
@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{27a}
+@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{27e}
@section Pragma Pack for Arrays
@geindex Pragma Pack (for arrays)
-Pragma @cite{Pack} applied to an array has an effect that depends upon whether the
+Pragma @code{Pack} applied to an array has an effect that depends upon whether the
component type is @emph{packable}. For a component type to be @emph{packable}, it must
be one of the following cases:
@end itemize
For all these cases, if the component subtype size is in the range
-1 through 64, then the effect of the pragma @cite{Pack} is exactly as though a
+1 through 64, then the effect of the pragma @code{Pack} is exactly as though a
component size were specified giving the component subtype size.
All other types are non-packable, they occupy an integral number of storage
pragma Pack (ar);
@end example
-Then the component size of @cite{ar} will be set to 5 (i.e., to @cite{r'size},
-and the size of the array @cite{ar} will be exactly 40 bits).
+Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size},
+and the size of the array @code{ar} will be exactly 40 bits).
Note that in some cases this rather fierce approach to packing can produce
unexpected effects. For example, in Ada 95 and Ada 2005,
-subtype @cite{Natural} typically has a size of 31, meaning that if you
-pack an array of @cite{Natural}, you get 31-bit
+subtype @code{Natural} typically has a size of 31, meaning that if you
+pack an array of @code{Natural}, you get 31-bit
close packing, which saves a few bits, but results in far less efficient
access. Since many other Ada compilers will ignore such a packing request,
-GNAT will generate a warning on some uses of pragma @cite{Pack} that it guesses
+GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
might not be what is intended. You can easily remove this warning by
-using an explicit @cite{Component_Size} setting instead, which never generates
+using an explicit @code{Component_Size} setting instead, which never generates
a warning, since the intention of the programmer is clear in this case.
GNAT treats packed arrays in one of two ways. If the size of the array is
One special case that is worth noting occurs when the base type of the
component size is 8/16/32 and the subtype is one bit less. Notably this
-occurs with subtype @cite{Natural}. Consider:
+occurs with subtype @code{Natural}. Consider:
@example
type Arr is array (1 .. 32) of Natural;
@end example
In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
-since typically @cite{Natural'Size} is 32 in Ada 83, and in any case most
+since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
Ada 83 compilers did not attempt 31 bit packing.
-In Ada 95 and Ada 2005, @cite{Natural'Size} is required to be 31. Furthermore,
+In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore,
GNAT really does pack 31-bit subtype to 31 bits. This may result in a
substantial unintended performance penalty when porting legacy Ada 83 code.
To help prevent this, GNAT generates a warning in such cases. If you really
since in this case the programmer intention is clear.
@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{27b}@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{27c}
+@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{280}
@section Pragma Pack for Records
@geindex Pragma Pack (for records)
-Pragma @cite{Pack} applied to a record will pack the components to reduce
+Pragma @code{Pack} applied to a record will pack the components to reduce
wasted space from alignment gaps and by reducing the amount of space
taken by components. We distinguish between @emph{packable} components and
@emph{non-packable} components.
Small simple records, where the size is statically known, are also packable.
@end itemize
-For all these cases, if the 'Size value is in the range 1 through 64, the
+For all these cases, if the @code{'Size} value is in the range 1 through 64, the
components occupy the exact number of bits corresponding to this value
and are packed with no padding bits, i.e. they can start on an arbitrary
bit boundary.
All other types are non-packable, they occupy an integral number of storage
-units and the only effect of pragma Pack is to remove alignment gaps.
+units and the only effect of pragma @code{Pack} is to remove alignment gaps.
For example, consider the record
pragma Pack (X2);
@end example
-The representation for the record X2 is as follows:
+The representation for the record @code{X2} is as follows:
@example
for X2'Size use 224;
end record;
@end example
-Studying this example, we see that the packable fields @cite{L1}
-and @cite{L2} are
+Studying this example, we see that the packable fields @code{L1}
+and @code{L2} are
of length equal to their sizes, and placed at specific bit boundaries (and
not byte boundaries) to
-eliminate padding. But @cite{L3} is of a non-packable float type (because
+eliminate padding. But @code{L3} is of a non-packable float type (because
it is aliased), so it is on the next appropriate alignment boundary.
-The next two fields are fully packable, so @cite{L4} and @cite{L5} are
-minimally packed with no gaps. However, type @cite{Rb2} is a packed
+The next two fields are fully packable, so @code{L4} and @code{L5} are
+minimally packed with no gaps. However, type @code{Rb2} is a packed
array that is longer than 64 bits, so it is itself non-packable. Thus
-the @cite{L6} field is aligned to the next byte boundary, and takes an
+the @code{L6} field is aligned to the next byte boundary, and takes an
integral number of bytes, i.e., 72 bits.
@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{27e}
+@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{282}
@section Record Representation Clauses
@geindex Component Clause
For all components of an elementary type, the only restriction on component
-clauses is that the size must be at least the 'Size value of the type
+clauses is that the size must be at least the @code{'Size} value of the type
(actually the Value_Size). There are no restrictions due to alignment,
and such components may freely cross storage boundaries.
for R'Size use 49;
@end example
-then a component clause for a component of type R may start on any
+then a component clause for a component of type @code{R} may start on any
specified bit boundary, and may specify a value of 49 bits or greater.
For packed bit arrays that are longer than 64 bits, there are two
tag. When a tagged type appears as a component, the tag field must have
proper alignment
-In the case of a record extension T1, of a type T, no component clause applied
-to the type T1 can specify a storage location that would overlap the first
-T'Size bytes of the record.
+In the case of a record extension @code{T1}, of a type @code{T}, no component clause applied
+to the type @code{T1} can specify a storage location that would overlap the first
+@code{T'Size} bytes of the record.
For all other component types, including non-bit-packed arrays,
the component can be placed at an arbitrary bit boundary,
end record;
@end example
-Note: the above rules apply to recent releases of GNAT 5.
-In GNAT 3, there are more severe restrictions on larger components.
-For composite types, including packed arrays with a size greater than
-64 bits, component clauses must respect the alignment requirement of the
-type, in particular, always starting on a byte boundary, and the length
-must be a multiple of the storage unit.
-
@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{280}
+@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{284}
@section Handling of Records with Holes
@end example
@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{282}
+@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{286}
@section Enumeration Clauses
@end example
The array type t corresponds to a vector with exactly three elements and
-has a default size equal to @cite{3*Character'Size}. This ensures efficient
+has a default size equal to @code{3*Character'Size}. This ensures efficient
use of space, but means that accesses to elements of the array will incur
the overhead of converting representation values to the corresponding
-positional values, (i.e., the value delivered by the @cite{Pos} attribute).
+positional values, (i.e., the value delivered by the @code{Pos} attribute).
@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{284}
+@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{288}
@section Address Clauses
Additionally, GNAT treats as static an address clause that is an
unchecked_conversion of a static integer value. This simplifies the porting
of legacy code, and provides a portable equivalent to the GNAT attribute
-@cite{To_Address}.
+@code{To_Address}.
Another issue with address clauses is the interaction with alignment
requirements. When an address clause is given for an object, the address
machines with strict alignment requirements, GNAT
checks (at compile time if possible, generating a warning, or at execution
time with a run-time check) that the alignment is appropriate. If the
-run-time check fails, then @cite{Program_Error} is raised. This run-time
+run-time check fails, then @code{Program_Error} is raised. This run-time
check is suppressed if range checks are suppressed, or if the special GNAT
check Alignment_Check is suppressed, or if
-@cite{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also
+@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also
suppressed by default on non-strict alignment machines (such as the x86).
Finally, GNAT does not permit overlaying of objects of class-wide types. In
for B'Address use Addr;
@end example
-In both of these cases, @cite{A} and @cite{B} become aliased to one another
+In both of these cases, @code{A} and @code{B} become aliased to one another
via the address clause. This use of address clauses to overlay
variables, achieving an effect similar to unchecked conversion
was erroneous in Ada 83, but in Ada 95 and Ada 2005
the effect is implementation defined. Furthermore, the
Ada RM specifically recommends that in a situation
-like this, @cite{B} should be subject to the following
+like this, @code{B} should be subject to the following
implementation advice (RM 13.3(19)):
@quotation
@end quotation
GNAT follows this recommendation, and goes further by also applying
-this recommendation to the overlaid variable (@cite{A} in the above example)
+this recommendation to the overlaid variable (@code{A} in the above example)
in this case. This means that the overlay works "as expected", in that
a modification to one of the variables will affect the value of the other.
More generally, GNAT interprets this recommendation conservatively for
address clauses: in the cases other than overlays, it considers that the
-object is effectively subject to pragma @cite{Volatile} and implements the
+object is effectively subject to pragma @code{Volatile} and implements the
associated semantics.
Note that when address clause overlays are used in this way, there is an
end Overwrite_Record;
@end example
-Here the default initialization of @cite{Y} will clobber the value
-of @cite{X}, which justifies the warning. The warning notes that
-this effect can be eliminated by adding a @cite{pragma Import}
+Here the default initialization of @code{Y} will clobber the value
+of @code{X}, which justifies the warning. The warning notes that
+this effect can be eliminated by adding a @code{pragma Import}
which suppresses the initialization:
@example
end Overwrite_Record;
@end example
-Note that the use of @cite{pragma Initialize_Scalars} may cause variables to
+Note that the use of @code{pragma Initialize_Scalars} may cause variables to
be initialized when they would not otherwise have been in the absence
of the use of this pragma. This may cause an overlay to have this
unintended clobbering effect. The compiler avoids this for scalar
types, but not for composite objects (where in general the effect
-of @cite{Initialize_Scalars} is part of the initialization routine
+of @code{Initialize_Scalars} is part of the initialization routine
for the composite object:
@example
@end example
The above program generates the warning as shown, and at execution
-time, prints @cite{X was clobbered}. If the @cite{pragma Import} is
+time, prints @code{X was clobbered}. If the @code{pragma Import} is
added as suggested:
@example
@end example
then the program compiles without the warning and when run will generate
-the output @cite{X was not clobbered}.
+the output @code{X was not clobbered}.
@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{286}
+@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{28a}
@section Use of Address Clauses for Memory-Mapped I/O
components to be atomic if you want the byte store, or explicitly writing
the full word access sequence if that is what the hardware requires.
Alternatively, if the full word access sequence is required, GNAT also
-provides the pragma @cite{Volatile_Full_Access} which can be used in lieu of
-pragma @cite{Atomic} and will give the additional guarantee.
+provides the pragma @code{Volatile_Full_Access} which can be used in lieu of
+pragma @code{Atomic} and will give the additional guarantee.
@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{288}
+@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{28c}
@section Effect of Convention on Representation
@end example
8 bits is sufficient to store all values of the type, so by default, objects
-of type @cite{Color} will be represented using 8 bits. However, normal C
+of type @code{Color} will be represented using 8 bits. However, normal C
convention is to use 32 bits for all enum values in C, since enum values
-are essentially of type int. If pragma @cite{Convention C} is specified for an
+are essentially of type int. If pragma @code{Convention C} is specified for an
Ada enumeration type, then the size is modified as necessary (usually to
32 bits) to be consistent with the C convention for enum values.
true. In Ada, the normal convention is that two specific values, typically
0/1, are used to represent false/true respectively.
-Fortran has a similar convention for @cite{LOGICAL} values (any nonzero
+Fortran has a similar convention for @code{LOGICAL} values (any nonzero
value represents true).
To accommodate the Fortran and C conventions, if a pragma Convention specifies
@end itemize
@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{28a}
+@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{28e}
@section Conventions and Anonymous Access Types
@end example
@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas
-@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{28c}
+@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{290}
@section Determining the Representations chosen by GNAT
of what the compiler actually does. For example, if a partial record
representation clause specifies the location of some components and not
others, then where are the non-specified components placed? Or if pragma
-@cite{Pack} is used on a record, then exactly where are the resulting
-fields placed? The section on pragma @cite{Pack} in this chapter can be
+@code{Pack} is used on a record, then exactly where are the resulting
+fields placed? The section on pragma @code{Pack} in this chapter can be
used to answer the second question, but it is often easier to just see
what the compiler does.
of the parent type of r2, i.e., r1.
The component size and size clauses for types rb1 and rb2 show
-the exact effect of pragma @cite{Pack} on these arrays, and the record
+the exact effect of pragma @code{Pack} on these arrays, and the record
representation clause for type x2 shows how pragma @cite{Pack} affects
this record type.
the actual representation to be used.
@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top
-@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}@anchor{gnat_rm/standard_library_routines doc}@anchor{28d}@anchor{gnat_rm/standard_library_routines id1}@anchor{28e}
+@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}@anchor{gnat_rm/standard_library_routines doc}@anchor{291}@anchor{gnat_rm/standard_library_routines id1}@anchor{292}
@chapter Standard Library Routines
@item @code{Ada.Assertions} @emph{(11.4.2)}
-@cite{Assertions} provides the @cite{Assert} subprograms, and also
-the declaration of the @cite{Assertion_Error} exception.
+@code{Assertions} provides the @code{Assert} subprograms, and also
+the declaration of the @code{Assertion_Error} exception.
@item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)}
-@cite{Asynchronous_Task_Control} provides low level facilities for task
+@code{Asynchronous_Task_Control} provides low level facilities for task
synchronization. It is typically not implemented. See package spec for details.
@item @code{Ada.Calendar} @emph{(9.6)}
-@cite{Calendar} provides time of day access, and routines for
+@code{Calendar} provides time of day access, and routines for
manipulating times and durations.
@item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)}
This package provides additional arithmetic
-operations for @cite{Calendar}.
+operations for @code{Calendar}.
@item @code{Ada.Calendar.Formatting} @emph{(9.6.1)}
-This package provides formatting operations for @cite{Calendar}.
+This package provides formatting operations for @code{Calendar}.
@item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)}
-This package provides additional @cite{Calendar} facilities
+This package provides additional @code{Calendar} facilities
for handling time zones.
@item @code{Ada.Characters} @emph{(A.3.1)}
that appear in type CHARACTER. It is useful for writing programs that
will run in international environments. For example, if you want an
upper case E with an acute accent in a string, it is often better to use
-the definition of @cite{UC_E_Acute} in this package. Then your program
+the definition of @code{UC_E_Acute} in this package. Then your program
will print in an understandable manner even if your environment does not
support these extended characters.
@item @code{Ada.Command_Line} @emph{(A.15)}
This package provides access to the command line parameters and the name
-of the current program (analogous to the use of @cite{argc} and @cite{argv}
+of the current program (analogous to the use of @code{argc} and @code{argv}
in C), and also allows the exit status for the program to be set in a
system-independent manner.
@item @code{Ada.Locales} @emph{(A.19)}
This package provides declarations providing information (Language
-and Country) about the current locale.
+and Country) about the current locale. This package is currently not
+implemented other than by providing stubs which will always return
+Language_Unknown/Country_Unknown.
@item @code{Ada.Numerics}
Provides the implementation of standard elementary functions (such as
log and trigonometric functions) operating on complex numbers using the
-standard @cite{Float} and the @cite{Complex} and @cite{Imaginary} types
-created by the package @cite{Numerics.Complex_Types}.
+standard @code{Float} and the @code{Complex} and @code{Imaginary} types
+created by the package @code{Numerics.Complex_Types}.
@item @code{Ada.Numerics.Complex_Types}
This is a predefined instantiation of
-@cite{Numerics.Generic_Complex_Types} using @cite{Standard.Float} to
-build the type @cite{Complex} and @cite{Imaginary}.
+@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
+build the type @code{Complex} and @code{Imaginary}.
@item @code{Ada.Numerics.Discrete_Random}
@item
@code{Short_Float}
-@cite{Ada.Numerics.Short_Complex_Elementary_Functions}
+@code{Ada.Numerics.Short_Complex_Elementary_Functions}
@item
@code{Float}
-@cite{Ada.Numerics.Complex_Elementary_Functions}
+@code{Ada.Numerics.Complex_Elementary_Functions}
@item
@code{Long_Float}
-@cite{Ada.Numerics.Long_Complex_Elementary_Functions}
+@code{Ada.Numerics.Long_Complex_Elementary_Functions}
@end itemize
@item @code{Ada.Numerics.Generic_Complex_Types}
@item
@code{Short_Float}
-@cite{Ada.Numerics.Short_Complex_Complex_Types}
+@code{Ada.Numerics.Short_Complex_Complex_Types}
@item
@code{Float}
-@cite{Ada.Numerics.Complex_Complex_Types}
+@code{Ada.Numerics.Complex_Complex_Types}
@item
@code{Long_Float}
-@cite{Ada.Numerics.Long_Complex_Complex_Types}
+@code{Ada.Numerics.Long_Complex_Complex_Types}
@end itemize
@item @code{Ada.Numerics.Generic_Elementary_Functions}
@item
@code{Short_Float}
-@cite{Ada.Numerics.Short_Elementary_Functions}
+@code{Ada.Numerics.Short_Elementary_Functions}
@item
@code{Float}
-@cite{Ada.Numerics.Elementary_Functions}
+@code{Ada.Numerics.Elementary_Functions}
@item
@code{Long_Float}
-@cite{Ada.Numerics.Long_Elementary_Functions}
+@code{Ada.Numerics.Long_Elementary_Functions}
@end itemize
@item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)}
@item @code{Ada.Real_Time} @emph{(D.8)}
-This package provides facilities similar to those of @cite{Calendar}, but
+This package provides facilities similar to those of @code{Calendar}, but
operating with a finer clock suitable for real time control. Note that
annex D requires that there be no backward clock jumps, and GNAT generally
guarantees this behavior, but of course if the external clock on which
@item @code{Ada.Streams} @emph{(13.13.1)}
This is a generic package that provides the basic support for the
-concept of streams as used by the stream attributes (@cite{Input},
-@cite{Output}, @cite{Read} and @cite{Write}).
+concept of streams as used by the stream attributes (@code{Input},
+@code{Output}, @code{Read} and @code{Write}).
@item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)}
-This package is a specialization of the type @cite{Streams} defined in
-package @cite{Streams} together with a set of operations providing
+This package is a specialization of the type @code{Streams} defined in
+package @code{Streams} together with a set of operations providing
Stream_IO capability. The Stream_IO model permits both random and
sequential access to a file which can contain an arbitrary set of values
of one or more Ada types.
These packages provide analogous capabilities to the corresponding
packages without @code{Wide_} in the name, but operate with the types
-@cite{Wide_String} and @cite{Wide_Character} instead of @cite{String}
-and @cite{Character}. Versions of all the child packages are available.
+@code{Wide_String} and @code{Wide_Character} instead of @code{String}
+and @code{Character}. Versions of all the child packages are available.
@end table
@code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)}
These packages provide analogous capabilities to the corresponding
packages without @code{Wide_} in the name, but operate with the types
-@cite{Wide_Wide_String} and @cite{Wide_Wide_Character} instead
-of @cite{String} and @cite{Character}.
+@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
+of @code{String} and @code{Character}.
@item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)}
@item
@code{Short_Float}
-@cite{Short_Float_Text_IO}
+@code{Short_Float_Text_IO}
@item
@code{Float}
-@cite{Float_Text_IO}
+@code{Float_Text_IO}
@item
@code{Long_Float}
-@cite{Long_Float_Text_IO}
+@code{Long_Float_Text_IO}
@end itemize
@item @code{Ada.Text_IO.Integer_IO}
@item
@code{Short_Short_Integer}
-@cite{Ada.Short_Short_Integer_Text_IO}
+@code{Ada.Short_Short_Integer_Text_IO}
@item
@code{Short_Integer}
-@cite{Ada.Short_Integer_Text_IO}
+@code{Ada.Short_Integer_Text_IO}
@item
@code{Integer}
-@cite{Ada.Integer_Text_IO}
+@code{Ada.Integer_Text_IO}
@item
@code{Long_Integer}
-@cite{Ada.Long_Integer_Text_IO}
+@code{Ada.Long_Integer_Text_IO}
@item
@code{Long_Long_Integer}
-@cite{Ada.Long_Long_Integer_Text_IO}
+@code{Ada.Long_Long_Integer_Text_IO}
@end itemize
@item @code{Ada.Text_IO.Modular_IO}
@item @code{Ada.Wide_Text_IO} @emph{(A.11)}
-This package is similar to @cite{Ada.Text_IO}, except that the external
+This package is similar to @code{Ada.Text_IO}, except that the external
file supports wide character representations, and the internal types are
-@cite{Wide_Character} and @cite{Wide_String} instead of @cite{Character}
-and @cite{String}. The corresponding set of nested packages and child
+@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
+and @code{String}. The corresponding set of nested packages and child
packages are defined.
@item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)}
-This package is similar to @cite{Ada.Text_IO}, except that the external
+This package is similar to @code{Ada.Text_IO}, except that the external
file supports wide character representations, and the internal types are
-@cite{Wide_Character} and @cite{Wide_String} instead of @cite{Character}
-and @cite{String}. The corresponding set of nested packages and child
+@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
+and @code{String}. The corresponding set of nested packages and child
packages are defined.
@end table
available in GNAT, see the Ada 2012 RM for full details.
@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top
-@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f}@anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{28f}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{290}
+@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f}@anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{293}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{294}
@chapter The Implementation of Standard I/O
@end menu
@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{291}@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{292}
+@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{295}@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{296}
@section Standard I/O Packages
@itemize *
@item
-All files are opened using @cite{fopen}.
+All files are opened using @code{fopen}.
@item
-All input/output operations use @cite{fread}/@cite{fwrite}.
+All input/output operations use @code{fread}/@cite{fwrite}.
@end itemize
There is no internal buffering of any kind at the Ada library level. The only
elaborating the Ada code.
@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{293}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{294}
+@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{297}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{298}
@section FORM Strings
and not considered invalid.
@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{295}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{296}
+@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{299}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{29a}
@section Direct_IO
sequence, with the first record starting at offset zero, and subsequent
records following. There is no control information of any kind. For
example, if 32-bit integers are being written, each record takes
-4-bytes, so the record at index @cite{K} starts at offset
-(@cite{K}-1)*4.
+4-bytes, so the record at index @code{K} starts at offset
+(@code{K}-1)*4.
There is no limit on the size of Direct_IO files, they are expanded as
necessary to accommodate whatever records are written to the file.
@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{297}@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{298}
+@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{29b}@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{29c}
@section Sequential_IO
For the indefinite type case, the elements written consist of two
parts. First is the size of the data item, written as the memory image
-of a @cite{Interfaces.C.size_t} value, followed by the memory image of
+of a @code{Interfaces.C.size_t} value, followed by the memory image of
the data value. The resulting file can only be read using the same
(unconstrained) type. Normal assignment checks are performed on these
-read operations, and if these checks fail, @cite{Data_Error} is
+read operations, and if these checks fail, @code{Data_Error} is
raised. In particular, in the array case, the lengths must match, and in
the variant record case, if the variable for a particular read operation
is constrained, the discriminants must match.
Note that it is not possible to use Sequential_IO to write variable
length array items, and then read the data back into different length
-arrays. For example, the following will raise @cite{Data_Error}:
+arrays. For example, the following will raise @code{Data_Error}:
@example
package IO is new Sequential_IO (String);
Put_Line (S);
@end example
-On some Ada implementations, this will print @cite{hell}, but the program is
+On some Ada implementations, this will print @code{hell}, but the program is
clearly incorrect, since there is only one element in the file, and that
-element is the string @cite{hello!}.
+element is the string @code{hello!}.
In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
using Stream_IO, and this is the preferred mechanism. In particular, the
above program fragment rewritten to use Stream_IO will work correctly.
@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{299}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{29a}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{29d}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{29e}
@section Text_IO
@itemize *
@item
-The character @cite{LF} is used only as a line mark, i.e., to mark the end
+The character @code{LF} is used only as a line mark, i.e., to mark the end
of the line.
@item
-The character @cite{FF} is used only as a page mark, i.e., to mark the
+The character @code{FF} is used only as a page mark, i.e., to mark the
end of a page and consequently can appear only immediately following a
-@cite{LF} (line mark) character.
+@code{LF} (line mark) character.
@item
-The file ends with either @cite{LF} (line mark) or @cite{LF}-@cite{FF}
+The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF}
(line mark, page mark). In the former case, the page mark is implicitly
assumed to be present.
@end itemize
A file written using Text_IO will be in canonical form provided that no
-explicit @cite{LF} or @cite{FF} characters are written using @cite{Put}
-or @cite{Put_Line}. There will be no @cite{FF} character at the end of
-the file unless an explicit @cite{New_Page} operation was performed
+explicit @code{LF} or @code{FF} characters are written using @code{Put}
+or @code{Put_Line}. There will be no @code{FF} character at the end of
+the file unless an explicit @code{New_Page} operation was performed
before closing the file.
A canonical Text_IO file that is a regular file (i.e., not a device or a
@itemize *
@item
-The file contains @cite{FF} characters not immediately following a
-@cite{LF} character.
+The file contains @code{FF} characters not immediately following a
+@code{LF} character.
@item
-The file contains @cite{LF} or @cite{FF} characters written by
-@cite{Put} or @cite{Put_Line}, which are not logically considered to be
+The file contains @code{LF} or @code{FF} characters written by
+@code{Put} or @code{Put_Line}, which are not logically considered to be
line marks or page marks.
@item
-The file ends in a character other than @cite{LF} or @cite{FF},
+The file ends in a character other than @code{LF} or @code{FF},
i.e., there is no explicit line mark or page mark at the end of the file.
@end itemize
Text_IO can be used to read such non-standard text files but subprograms
to do with line or page numbers do not have defined meanings. In
-particular, a @cite{FF} character that does not follow a @cite{LF}
+particular, a @code{FF} character that does not follow a @code{LF}
character may or may not be treated as a page mark from the point of
-view of page and line numbering. Every @cite{LF} character is considered
-to end a line, and there is an implied @cite{LF} character at the end of
+view of page and line numbering. Every @code{LF} character is considered
+to end a line, and there is an implied @code{LF} character at the end of
the file.
@menu
@end menu
@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{29b}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{29c}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{29f}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2a0}
@subsection Stream Pointer Positioning
-@cite{Ada.Text_IO} has a definition of current position for a file that
+@code{Ada.Text_IO} has a definition of current position for a file that
is being read. No internal buffering occurs in Text_IO, and usually the
physical position in the stream used to implement the file corresponds
to this logical position defined by Text_IO. There are two exceptions:
@itemize *
@item
-After a call to @cite{End_Of_Page} that returns @cite{True}, the stream
-is positioned past the @cite{LF} (line mark) that precedes the page
+After a call to @code{End_Of_Page} that returns @code{True}, the stream
+is positioned past the @code{LF} (line mark) that precedes the page
mark. Text_IO maintains an internal flag so that subsequent read
operations properly handle the logical position which is unchanged by
-the @cite{End_Of_Page} call.
+the @code{End_Of_Page} call.
@item
-After a call to @cite{End_Of_File} that returns @cite{True}, if the
+After a call to @code{End_Of_File} that returns @code{True}, if the
Text_IO file was positioned before the line mark at the end of file
before the call, then the logical position is unchanged, but the stream
is physically positioned right at the end of file (past the line mark,
situations.
@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{29d}@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{29e}
+@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2a1}@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2a2}
@subsection Reading and Writing Non-Regular Files
look-ahead as follows:
An input file that is not a regular file is considered to have no page
-marks. Any @cite{Ascii.FF} characters (the character normally used for a
+marks. Any @code{Ascii.FF} characters (the character normally used for a
page mark) appearing in the file are considered to be data
characters. In particular:
@itemize *
@item
-@cite{Get_Line} and @cite{Skip_Line} do not test for a page mark
+@code{Get_Line} and @code{Skip_Line} do not test for a page mark
following a line mark. If a page mark appears, it will be treated as a
data character.
entered from the pipe to complete one of these operations.
@item
-@cite{End_Of_Page} always returns @cite{False}
+@code{End_Of_Page} always returns @code{False}
@item
-@cite{End_Of_File} will return @cite{False} if there is a page mark at
+@code{End_Of_File} will return @code{False} if there is a page mark at
the end of the file.
@end itemize
Output to non-regular files is the same as for regular files. Page marks
-may be written to non-regular files using @cite{New_Page}, but as noted
+may be written to non-regular files using @code{New_Page}, but as noted
above they will not be treated as page marks on input if the output is
piped to another Ada program.
of file indication is not 'sticky'. If an end of file is entered, e.g., by
pressing the @code{EOT} key,
then end of file
-is signaled once (i.e., the test @cite{End_Of_File}
-will yield @cite{True}, or a read will
-raise @cite{End_Error}), but then reading can resume
+is signaled once (i.e., the test @code{End_Of_File}
+will yield @code{True}, or a read will
+raise @code{End_Error}), but then reading can resume
to read data past that end of
file indication, until another end of file indication is entered.
@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{29f}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2a0}
+@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2a3}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2a4}
@subsection Get_Immediate
page mark.
@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2a1}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2a2}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2a5}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2a6}
@subsection Treating Text_IO Files as Streams
@geindex Stream files
-The package @cite{Text_IO.Streams} allows a Text_IO file to be treated
-as a stream. Data written to a Text_IO file in this stream mode is
-binary data. If this binary data contains bytes 16#0A# (@cite{LF}) or
-16#0C# (@cite{FF}), the resulting file may have non-standard
+The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated
+as a stream. Data written to a @code{Text_IO} file in this stream mode is
+binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
+16#0C# (@code{FF}), the resulting file may have non-standard
format. Similarly if read operations are used to read from a Text_IO
-file treated as a stream, then @cite{LF} and @cite{FF} characters may be
+file treated as a stream, then @code{LF} and @code{FF} characters may be
skipped and the effect is similar to that described above for
-@cite{Get_Immediate}.
+@code{Get_Immediate}.
@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2a3}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2a4}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2a8}
@subsection Text_IO Extensions
@geindex Text_IO extensions
A package GNAT.IO_Aux in the GNAT library provides some useful extensions
-to the standard @cite{Text_IO} package:
+to the standard @code{Text_IO} package:
@itemize *
@end itemize
@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2a5}@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2a6}
+@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2aa}
@subsection Text_IO Facilities for Unbounded Strings
@geindex Unbounded_String
@geindex Text_IO operations
-The package @cite{Ada.Strings.Unbounded.Text_IO}
-in library files @cite{a-suteio.ads/adb} contains some GNAT-specific
+The package @code{Ada.Strings.Unbounded.Text_IO}
+in library files @code{a-suteio.ads/adb} contains some GNAT-specific
subprograms useful for Text_IO operations on unbounded strings:
procedure Put (File : File_Type; U : Unbounded_String);
Writes the value of the given unbounded string to the specified file
Similar to the effect of
-@cite{Put (To_String (U))} except that an extra copy is avoided.
+@code{Put (To_String (U))} except that an extra copy is avoided.
@item
procedure Put_Line (File : File_Type; U : Unbounded_String);
Writes the value of the given unbounded string to the specified file,
-followed by a @cite{New_Line}.
-Similar to the effect of @cite{Put_Line (To_String (U))} except
+followed by a @code{New_Line}.
+Similar to the effect of @code{Put_Line (To_String (U))} except
that an extra copy is avoided.
@end itemize
-In the above procedures, @cite{File} is of type @cite{Ada.Text_IO.File_Type}
+In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
and is optional. If the parameter is omitted, then the standard input or
output file is referenced as appropriate.
-The package @cite{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
+The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended
-@cite{Wide_Text_IO} functionality for unbounded wide strings.
+@code{Wide_Text_IO} functionality for unbounded wide strings.
-The package @cite{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
+The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended
-@cite{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
+@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2a8}
+@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2ac}
@section Wide_Text_IO
-@cite{Wide_Text_IO} is similar in most respects to Text_IO, except that
+@code{Wide_Text_IO} is similar in most respects to Text_IO, except that
both input and output files may contain special sequences that represent
wide character values. The encoding scheme for a given file may be
specified using a FORM parameter:
@end example
as part of the FORM string (WCEM = wide character encoding method),
-where @cite{x} is one of the following characters
+where @code{x} is one of the following characters
@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx}
@quotation
-where @cite{a}, @cite{b}, @cite{c}, @cite{d} are the four hexadecimal
+where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
characters (using upper case letters) of the wide character code. For
example, ESC A345 is used to represent the wide character with code
16#A345#. This scheme is compatible with use of the full
-@cite{Wide_Character} set.
+@code{Wide_Character} set.
@end quotation
@quotation
-where the @cite{xxx} bits correspond to the left-padded bits of the
+where the @code{xxx} bits correspond to the left-padded bits of the
16-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
@quotation
-where @cite{a}, @cite{b}, @cite{c}, @cite{d} are the four hexadecimal
+where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
-example, @cite{["A345"]} is used to represent the wide character with code
-@cite{16#A345#}.
+example, @code{["A345"]} is used to represent the wide character with code
+@code{16#A345#}.
This scheme is compatible with use of the full Wide_Character set.
On input, brackets coding can also be used for upper half characters,
-e.g., @cite{["C1"]} for lower case a. However, on output, brackets notation
-is only used for wide characters with a code greater than @cite{16#FF#}.
+e.g., @code{["C1"]} for lower case a. However, on output, brackets notation
+is only used for wide characters with a code greater than @code{16#FF#}.
Note that brackets coding is not normally used in the context of
Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
@end menu
@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2aa}
+@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2ae}
@subsection Stream Pointer Positioning
-@cite{Ada.Wide_Text_IO} is similar to @cite{Ada.Text_IO} in its handling
-of stream pointer positioning (@ref{29a,,Text_IO}). There is one additional
+@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
+of stream pointer positioning (@ref{29e,,Text_IO}). There is one additional
case:
-If @cite{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
+If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
normal lower ASCII set (i.e., a character in the range:
@example
@end example
then although the logical position of the file pointer is unchanged by
-the @cite{Look_Ahead} call, the stream is physically positioned past the
+the @code{Look_Ahead} call, the stream is physically positioned past the
wide character sequence. Again this is to avoid the need for buffering
-or backup, and all @cite{Wide_Text_IO} routines check the internal
+or backup, and all @code{Wide_Text_IO} routines check the internal
indication that this situation has occurred so that this is not visible
-to a normal program using @cite{Wide_Text_IO}. However, this discrepancy
+to a normal program using @code{Wide_Text_IO}. However, this discrepancy
can be observed if the wide text file shares a stream with another file.
@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2ac}
+@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2b0}
@subsection Reading and Writing Non-Regular Files
As in the case of Text_IO, when a non-regular file is read, it is
assumed that the file contains no page marks (any form characters are
-treated as data characters), and @cite{End_Of_Page} always returns
-@cite{False}. Similarly, the end of file indication is not sticky, so
+treated as data characters), and @code{End_Of_Page} always returns
+@code{False}. Similarly, the end of file indication is not sticky, so
it is possible to read beyond an end of file.
@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2ae}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2b2}
@section Wide_Wide_Text_IO
-@cite{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
+@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
both input and output files may contain special sequences that represent
wide wide character values. The encoding scheme for a given file may be
specified using a FORM parameter:
@end example
as part of the FORM string (WCEM = wide character encoding method),
-where @cite{x} is one of the following characters
+where @code{x} is one of the following characters
@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx}
@quotation
-where the @cite{xxx} bits correspond to the left-padded bits of the
+where the @code{xxx} bits correspond to the left-padded bits of the
21-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
@quotation
-where @cite{a}, @cite{b}, @cite{c}, @cite{d}, @cite{e}, and @cite{f}
+where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
are the four or six hexadecimal
characters (using uppercase letters) of the wide wide character code. For
-example, @cite{["01A345"]} is used to represent the wide wide character
-with code @cite{16#01A345#}.
+example, @code{["01A345"]} is used to represent the wide wide character
+with code @code{16#01A345#}.
This scheme is compatible with use of the full Wide_Wide_Character set.
On input, brackets coding can also be used for upper half characters,
-e.g., @cite{["C1"]} for lower case a. However, on output, brackets notation
-is only used for wide characters with a code greater than @cite{16#FF#}.
+e.g., @code{["C1"]} for lower case a. However, on output, brackets notation
+is only used for wide characters with a code greater than @code{16#FF#}.
@end quotation
If is also possible to use the other Wide_Character encoding methods,
@end menu
@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2b0}
+@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2b4}
@subsection Stream Pointer Positioning
-@cite{Ada.Wide_Wide_Text_IO} is similar to @cite{Ada.Text_IO} in its handling
-of stream pointer positioning (@ref{29a,,Text_IO}). There is one additional
+@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
+of stream pointer positioning (@ref{29e,,Text_IO}). There is one additional
case:
-If @cite{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
+If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
normal lower ASCII set (i.e., a character in the range:
@example
@end example
then although the logical position of the file pointer is unchanged by
-the @cite{Look_Ahead} call, the stream is physically positioned past the
+the @code{Look_Ahead} call, the stream is physically positioned past the
wide character sequence. Again this is to avoid the need for buffering
-or backup, and all @cite{Wide_Wide_Text_IO} routines check the internal
+or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
indication that this situation has occurred so that this is not visible
-to a normal program using @cite{Wide_Wide_Text_IO}. However, this discrepancy
+to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
can be observed if the wide text file shares a stream with another file.
@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO
-@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2b2}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2b6}
@subsection Reading and Writing Non-Regular Files
As in the case of Text_IO, when a non-regular file is read, it is
assumed that the file contains no page marks (any form characters are
-treated as data characters), and @cite{End_Of_Page} always returns
-@cite{False}. Similarly, the end of file indication is not sticky, so
+treated as data characters), and @code{End_Of_Page} always returns
+@code{False}. Similarly, the end of file indication is not sticky, so
it is possible to read beyond an end of file.
@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2b4}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2b8}
@section Stream_IO
A stream file is a sequence of bytes, where individual elements are
written to the file as described in the Ada Reference Manual. The type
-@cite{Stream_Element} is simply a byte. There are two ways to read or
+@code{Stream_Element} is simply a byte. There are two ways to read or
write a stream file.
@itemize *
@item
-The operations @cite{Read} and @cite{Write} directly read or write a
+The operations @code{Read} and @code{Write} directly read or write a
sequence of stream elements with no control information.
@item
@end itemize
@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2b6}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2ba}
@section Text Translation
@end itemize
@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2b8}
+@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2bc}
@section Shared Files
@item
In the absence of a @code{shared=xxx} form parameter, an attempt
to open two or more files with the same full name is considered an error
-and is not supported. The exception @cite{Use_Error} will be
+and is not supported. The exception @code{Use_Error} will be
raised. Note that a file that is not explicitly closed by the program
remains open until the program terminates.
When a program that opens multiple files with the same name is ported
from another Ada compiler to GNAT, the effect will be that
-@cite{Use_Error} is raised.
+@code{Use_Error} is raised.
The documentation of the original compiler and the documentation of the
program should then be examined to determine if file sharing was
-expected, and @code{shared=xxx} parameters added to @cite{Open}
-and @cite{Create} calls as required.
+expected, and @code{shared=xxx} parameters added to @code{Open}
+and @code{Create} calls as required.
When a program is ported from GNAT to some other Ada compiler, no
special attention is required unless the @code{shared=xxx} form
for this purpose (using the stream attributes)
@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2ba}
+@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2be}
@section Filenames encoding
UTF-8 natively.
@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2bc}
+@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2c0}
@section File content encoding
This encoding is only supported on the Windows platform.
@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2be}
+@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2c2}
@section Open Modes
-@cite{Open} and @cite{Create} calls result in a call to @cite{fopen}
+@code{Open} and @code{Create} calls result in a call to @code{fopen}
using the mode shown in the following table:
@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx}
@headitem
-@cite{Open} and @cite{Create} Call Modes
+@code{Open} and @code{Create} Call Modes
@tab
A special case occurs with Stream_IO. As shown in the above table, the
file is initially opened in @code{r} or @code{w} mode for the
-@cite{In_File} and @cite{Out_File} cases. If a @cite{Set_Mode} operation
+@code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
subsequently requires switching from reading to writing or vice-versa,
then the file is reopened in @code{r+} mode to permit the required operation.
@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2c0}
+@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2c4}
@section Operations on C Streams
-The package @cite{Interfaces.C_Streams} provides an Ada program with direct
+The package @code{Interfaces.C_Streams} provides an Ada program with direct
access to the C library functions for operations on C streams:
@example
@end example
@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O
-@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2c2}
+@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2c6}
@section Interfacing to C Streams
end Ada.Stream_IO.C_Streams;
@end example
-In each of these six packages, the @cite{C_Stream} function obtains the
-@cite{FILE} pointer from a currently opened Ada file. It is then
-possible to use the @cite{Interfaces.C_Streams} package to operate on
+In each of these six packages, the @code{C_Stream} function obtains the
+@code{FILE} pointer from a currently opened Ada file. It is then
+possible to use the @code{Interfaces.C_Streams} package to operate on
this stream, or the stream can be passed to a C program which can
operate on it directly. Of course the program is responsible for
ensuring that only appropriate sequences of operations are executed.
One particular use of relevance to an Ada program is that the
-@cite{setvbuf} function can be used to control the buffering of the
+@code{setvbuf} function can be used to control the buffering of the
stream used by an Ada file. In the absence of such a call the standard
default buffering is used.
-The @cite{Open} procedures in these packages open a file giving an
+The @code{Open} procedures in these packages open a file giving an
existing C Stream instead of a file name. Typically this stream is
imported from a C program, allowing an Ada file to operate on an
existing C file.
@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top
-@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}@anchor{gnat_rm/the_gnat_library doc}@anchor{2c3}@anchor{gnat_rm/the_gnat_library id1}@anchor{2c4}
+@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}@anchor{gnat_rm/the_gnat_library doc}@anchor{2c7}@anchor{gnat_rm/the_gnat_library id1}@anchor{2c8}
@chapter The GNAT Library
the SPITBOL pattern matching capability, including a full tutorial and
extensive examples, look in the @code{g-spipat.ads} file in the library.
-For each entry here, the package name (as it would appear in a @cite{with}
+For each entry here, the package name (as it would appear in a @code{with}
clause) is given, followed by the name of the corresponding spec file in
-parentheses. The packages are children in four hierarchies, @cite{Ada},
-@cite{Interfaces}, @cite{System}, and @cite{GNAT}, the latter being a
+parentheses. The packages are children in four hierarchies, @code{Ada},
+@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
GNAT-specific hierarchy.
Note that an application program should only use packages in one of these
four hierarchies if the package is defined in the Ada Reference Manual,
or is listed in this section of the GNAT Programmers Reference Manual.
All other units should be considered internal implementation units and
-should not be directly @cite{with}'ed by application code. The use of
-a @cite{with} statement that references one of these internal implementation
+should not be directly @code{with}ed by application code. The use of
+a @code{with} clause that references one of these internal implementation
units makes an application potentially dependent on changes in versions
of GNAT, and will generate a warning message.
* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads.
* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads.
* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads.
+* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads.
+* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads.
+* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads.
* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads.
* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads.
* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads.
@end menu
@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id2}@anchor{2c5}@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2c6}
-@section @cite{Ada.Characters.Latin_9} (@code{a-chlat9.ads})
+@anchor{gnat_rm/the_gnat_library id2}@anchor{2c9}@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2ca}
+@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads})
@geindex Ada.Characters.Latin_9 (a-chlat9.ads)
@geindex Latin_9 constants for Character
-This child of @cite{Ada.Characters}
+This child of @code{Ada.Characters}
provides a set of definitions corresponding to those in the
-RM-defined package @cite{Ada.Characters.Latin_1} but with the
-few modifications required for @cite{Latin-9}
+RM-defined package @code{Ada.Characters.Latin_1} but with the
+few modifications required for @code{Latin-9}
The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
@node Ada Characters Wide_Latin_1 a-cwila1 ads,Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Latin_9 a-chlat9 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2c7}@anchor{gnat_rm/the_gnat_library id3}@anchor{2c8}
-@section @cite{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads})
+@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2cb}@anchor{gnat_rm/the_gnat_library id3}@anchor{2cc}
+@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads})
@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
@geindex Latin_1 constants for Wide_Character
-This child of @cite{Ada.Characters}
+This child of @code{Ada.Characters}
provides a set of definitions corresponding to those in the
-RM-defined package @cite{Ada.Characters.Latin_1} but with the
-types of the constants being @cite{Wide_Character}
-instead of @cite{Character}. The provision of such a package
+RM-defined package @code{Ada.Characters.Latin_1} but with the
+types of the constants being @code{Wide_Character}
+instead of @code{Character}. The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
@node Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id4}@anchor{2c9}@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2ca}
-@section @cite{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads})
+@anchor{gnat_rm/the_gnat_library id4}@anchor{2cd}@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2ce}
+@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads})
@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads)
@geindex Latin_9 constants for Wide_Character
-This child of @cite{Ada.Characters}
+This child of @code{Ada.Characters}
provides a set of definitions corresponding to those in the
-GNAT defined package @cite{Ada.Characters.Latin_9} but with the
-types of the constants being @cite{Wide_Character}
-instead of @cite{Character}. The provision of such a package
+GNAT defined package @code{Ada.Characters.Latin_9} but with the
+types of the constants being @code{Wide_Character}
+instead of @code{Character}. The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
@node Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Characters Wide_Latin_9 a-cwila1 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2cb}@anchor{gnat_rm/the_gnat_library id5}@anchor{2cc}
-@section @cite{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads})
+@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2cf}@anchor{gnat_rm/the_gnat_library id5}@anchor{2d0}
+@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads})
@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
@geindex Latin_1 constants for Wide_Wide_Character
-This child of @cite{Ada.Characters}
+This child of @code{Ada.Characters}
provides a set of definitions corresponding to those in the
-RM-defined package @cite{Ada.Characters.Latin_1} but with the
-types of the constants being @cite{Wide_Wide_Character}
-instead of @cite{Character}. The provision of such a package
+RM-defined package @code{Ada.Characters.Latin_1} but with the
+types of the constants being @code{Wide_Wide_Character}
+instead of @code{Character}. The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
@node Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2cd}@anchor{gnat_rm/the_gnat_library id6}@anchor{2ce}
-@section @cite{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads})
+@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2d1}@anchor{gnat_rm/the_gnat_library id6}@anchor{2d2}
+@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads})
@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
@geindex Latin_9 constants for Wide_Wide_Character
-This child of @cite{Ada.Characters}
+This child of @code{Ada.Characters}
provides a set of definitions corresponding to those in the
-GNAT defined package @cite{Ada.Characters.Latin_9} but with the
-types of the constants being @cite{Wide_Wide_Character}
-instead of @cite{Character}. The provision of such a package
+GNAT defined package @code{Ada.Characters.Latin_9} but with the
+types of the constants being @code{Wide_Wide_Character}
+instead of @code{Character}. The provision of such a package
is specifically authorized by the Ada Reference Manual
(RM A.3.3(27)).
@node Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,Ada Containers Formal_Hashed_Maps a-cfhama ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id7}@anchor{2cf}@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2d0}
-@section @cite{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads})
+@anchor{gnat_rm/the_gnat_library id7}@anchor{2d3}@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2d4}
+@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads})
@geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)
@geindex Formal container for doubly linked lists
-This child of @cite{Ada.Containers} defines a modified version of the
+This child of @code{Ada.Containers} defines a modified version of the
Ada 2005 container for doubly linked lists, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
does not have the complex overhead required to detect cursor tampering.
@node Ada Containers Formal_Hashed_Maps a-cfhama ads,Ada Containers Formal_Hashed_Sets a-cfhase ads,Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id8}@anchor{2d1}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2d2}
-@section @cite{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads})
+@anchor{gnat_rm/the_gnat_library id8}@anchor{2d5}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2d6}
+@section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads})
@geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)
@geindex Formal container for hashed maps
-This child of @cite{Ada.Containers} defines a modified version of the
+This child of @code{Ada.Containers} defines a modified version of the
Ada 2005 container for hashed maps, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
does not have the complex overhead required to detect cursor tampering.
@node Ada Containers Formal_Hashed_Sets a-cfhase ads,Ada Containers Formal_Ordered_Maps a-cforma ads,Ada Containers Formal_Hashed_Maps a-cfhama ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id9}@anchor{2d3}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2d4}
-@section @cite{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads})
+@anchor{gnat_rm/the_gnat_library id9}@anchor{2d7}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2d8}
+@section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads})
@geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)
@geindex Formal container for hashed sets
-This child of @cite{Ada.Containers} defines a modified version of the
+This child of @code{Ada.Containers} defines a modified version of the
Ada 2005 container for hashed sets, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
does not have the complex overhead required to detect cursor tampering.
@node Ada Containers Formal_Ordered_Maps a-cforma ads,Ada Containers Formal_Ordered_Sets a-cforse ads,Ada Containers Formal_Hashed_Sets a-cfhase ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id10}@anchor{2d5}@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2d6}
-@section @cite{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads})
+@anchor{gnat_rm/the_gnat_library id10}@anchor{2d9}@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2da}
+@section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads})
@geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)
@geindex Formal container for ordered maps
-This child of @cite{Ada.Containers} defines a modified version of the
+This child of @code{Ada.Containers} defines a modified version of the
Ada 2005 container for ordered maps, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
does not have the complex overhead required to detect cursor tampering.
@node Ada Containers Formal_Ordered_Sets a-cforse ads,Ada Containers Formal_Vectors a-cofove ads,Ada Containers Formal_Ordered_Maps a-cforma ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2d7}@anchor{gnat_rm/the_gnat_library id11}@anchor{2d8}
-@section @cite{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads})
+@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2db}@anchor{gnat_rm/the_gnat_library id11}@anchor{2dc}
+@section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads})
@geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)
@geindex Formal container for ordered sets
-This child of @cite{Ada.Containers} defines a modified version of the
+This child of @code{Ada.Containers} defines a modified version of the
Ada 2005 container for ordered sets, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
does not have the complex overhead required to detect cursor tampering.
@node Ada Containers Formal_Vectors a-cofove ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Formal_Ordered_Sets a-cforse ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id12}@anchor{2d9}@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2da}
-@section @cite{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads})
+@anchor{gnat_rm/the_gnat_library id12}@anchor{2dd}@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2de}
+@section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads})
@geindex Ada.Containers.Formal_Vectors (a-cofove.ads)
@geindex Formal container for vectors
-This child of @cite{Ada.Containers} defines a modified version of the
+This child of @code{Ada.Containers} defines a modified version of the
Ada 2005 container for vectors, meant to facilitate formal
verification of code using such containers. The specification of this
unit is compatible with SPARK 2014.
efficient version than the one defined in the standard. In particular it
does not have the complex overhead required to detect cursor tampering.
-@node Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Bounded_Holders a-coboho ads,Ada Containers Formal_Vectors a-cofove ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id13}@anchor{2db}@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2dc}
-@section @cite{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads})
+@node Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Functional_Vectors a-cofuve ads,Ada Containers Formal_Vectors a-cofove ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id13}@anchor{2df}@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2e0}
+@section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads})
@geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads)
@geindex Formal container for vectors
-This child of @cite{Ada.Containers} defines a modified version of the
+This child of @code{Ada.Containers} defines a modified version of the
Ada 2005 container for vectors of indefinite elements, meant to
facilitate formal verification of code using such containers. The
specification of this unit is compatible with SPARK 2014.
efficient version than the one defined in the standard. In particular it
does not have the complex overhead required to detect cursor tampering.
-@node Ada Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id14}@anchor{2dd}@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2de}
-@section @cite{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads})
+@node Ada Containers Functional_Vectors a-cofuve ads,Ada Containers Functional_Sets a-cofuse ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id14}@anchor{2e1}@anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2e2}
+@section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads})
+
+
+@geindex Ada.Containers.Functional_Vectors (a-cofuve.ads)
+
+@geindex Functional vectors
+
+This child of @code{Ada.Containers} defines immutable vectors. These
+containers are unbounded and may contain indefinite elements. Furthermore, to
+be usable in every context, they are neither controlled nor limited. As they
+are functional, that is, no primitives are provided which would allow modifying
+an existing container, these containers can still be used safely.
+
+Their API features functions creating new containers from existing ones.
+As a consequence, these containers are highly inefficient. They are also
+memory consuming, as the allocated memory is not reclaimed when the container
+is no longer referenced. Thus, they should in general be used in ghost code
+and annotations, so that they can be removed from the final executable. The
+specification of this unit is compatible with SPARK 2014.
+
+@node Ada Containers Functional_Sets a-cofuse ads,Ada Containers Functional_Maps a-cofuma ads,Ada Containers Functional_Vectors a-cofuve ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2e3}@anchor{gnat_rm/the_gnat_library id15}@anchor{2e4}
+@section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads})
+
+
+@geindex Ada.Containers.Functional_Sets (a-cofuse.ads)
+
+@geindex Functional sets
+
+This child of @code{Ada.Containers} defines immutable sets. These containers are
+unbounded and may contain indefinite elements. Furthermore, to be usable in
+every context, they are neither controlled nor limited. As they are functional,
+that is, no primitives are provided which would allow modifying an existing
+container, these containers can still be used safely.
+
+Their API features functions creating new containers from existing ones.
+As a consequence, these containers are highly inefficient. They are also
+memory consuming, as the allocated memory is not reclaimed when the container
+is no longer referenced. Thus, they should in general be used in ghost code
+and annotations, so that they can be removed from the final executable. The
+specification of this unit is compatible with SPARK 2014.
+
+@node Ada Containers Functional_Maps a-cofuma ads,Ada Containers Bounded_Holders a-coboho ads,Ada Containers Functional_Sets a-cofuse ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library id16}@anchor{2e5}@anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2e6}
+@section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads})
+
+
+@geindex Ada.Containers.Functional_Maps (a-cofuma.ads)
+
+@geindex Functional maps
+
+This child of @code{Ada.Containers} defines immutable maps. These containers are
+unbounded and may contain indefinite elements. Furthermore, to be usable in
+every context, they are neither controlled nor limited. As they are functional,
+that is, no primitives are provided which would allow modifying an existing
+container, these containers can still be used safely.
+
+Their API features functions creating new containers from existing ones.
+As a consequence, these containers are highly inefficient. They are also
+memory consuming, as the allocated memory is not reclaimed when the container
+is no longer referenced. Thus, they should in general be used in ghost code
+and annotations, so that they can be removed from the final executable. The
+specification of this unit is compatible with SPARK 2014.
+
+@node Ada Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Containers Functional_Maps a-cofuma ads,The GNAT Library
+@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id17}@anchor{2e8}
+@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads})
@geindex Ada.Containers.Bounded_Holders (a-coboho.ads)
@geindex Formal container for vectors
-This child of @cite{Ada.Containers} defines a modified version of
+This child of @code{Ada.Containers} defines a modified version of
Indefinite_Holders that avoids heap allocation.
@node Ada Command_Line Environment a-colien ads,Ada Command_Line Remove a-colire ads,Ada Containers Bounded_Holders a-coboho ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2df}@anchor{gnat_rm/the_gnat_library id15}@anchor{2e0}
-@section @cite{Ada.Command_Line.Environment} (@code{a-colien.ads})
+@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2e9}@anchor{gnat_rm/the_gnat_library id18}@anchor{2ea}
+@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads})
@geindex Ada.Command_Line.Environment (a-colien.ads)
@geindex Environment entries
-This child of @cite{Ada.Command_Line}
+This child of @code{Ada.Command_Line}
provides a mechanism for obtaining environment values on systems
where this concept makes sense.
@node Ada Command_Line Remove a-colire ads,Ada Command_Line Response_File a-clrefi ads,Ada Command_Line Environment a-colien ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id16}@anchor{2e1}@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2e2}
-@section @cite{Ada.Command_Line.Remove} (@code{a-colire.ads})
+@anchor{gnat_rm/the_gnat_library id19}@anchor{2eb}@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2ec}
+@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads})
@geindex Ada.Command_Line.Remove (a-colire.ads)
@geindex Command line
@geindex argument removal
-This child of @cite{Ada.Command_Line}
+This child of @code{Ada.Command_Line}
provides a mechanism for logically removing
arguments from the argument list. Once removed, an argument is not visible
-to further calls on the subprograms in @cite{Ada.Command_Line} will not
+to further calls on the subprograms in @code{Ada.Command_Line} will not
see the removed argument.
@node Ada Command_Line Response_File a-clrefi ads,Ada Direct_IO C_Streams a-diocst ads,Ada Command_Line Remove a-colire ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2e3}@anchor{gnat_rm/the_gnat_library id17}@anchor{2e4}
-@section @cite{Ada.Command_Line.Response_File} (@code{a-clrefi.ads})
+@anchor{gnat_rm/the_gnat_library id20}@anchor{2ed}@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2ee}
+@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads})
@geindex Ada.Command_Line.Response_File (a-clrefi.ads)
@geindex Command line
@geindex handling long command lines
-This child of @cite{Ada.Command_Line} provides a mechanism facilities for
+This child of @code{Ada.Command_Line} provides a mechanism facilities for
getting command line arguments from a text file, called a "response file".
Using a response file allow passing a set of arguments to an executable longer
than the maximum allowed by the system on the command line.
@node Ada Direct_IO C_Streams a-diocst ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Command_Line Response_File a-clrefi ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id18}@anchor{2e5}@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2e6}
-@section @cite{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads})
+@anchor{gnat_rm/the_gnat_library id21}@anchor{2ef}@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2f0}
+@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads})
@geindex Ada.Direct_IO.C_Streams (a-diocst.ads)
@geindex Interfacing with Direct_IO
This package provides subprograms that allow interfacing between
-C streams and @cite{Direct_IO}. The stream identifier can be
+C streams and @code{Direct_IO}. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
@node Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Direct_IO C_Streams a-diocst ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id19}@anchor{2e7}@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2e8}
-@section @cite{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads})
+@anchor{gnat_rm/the_gnat_library id22}@anchor{2f1}@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2f2}
+@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads})
@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
@geindex testing for
This child subprogram provides a way of testing for the null
-exception occurrence (@cite{Null_Occurrence}) without raising
+exception occurrence (@code{Null_Occurrence}) without raising
an exception.
@node Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Exceptions Traceback a-exctra ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id20}@anchor{2e9}@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2ea}
-@section @cite{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads})
+@anchor{gnat_rm/the_gnat_library id23}@anchor{2f3}@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2f4}
+@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads})
@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
terminating the program. Note that this subprogram never returns.
@node Ada Exceptions Traceback a-exctra ads,Ada Sequential_IO C_Streams a-siocst ads,Ada Exceptions Last_Chance_Handler a-elchha ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id21}@anchor{2ec}
-@section @cite{Ada.Exceptions.Traceback} (@code{a-exctra.ads})
+@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id24}@anchor{2f6}
+@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads})
@geindex Ada.Exceptions.Traceback (a-exctra.ads)
@geindex Traceback for Exception Occurrence
-This child package provides the subprogram (@cite{Tracebacks}) to
+This child package provides the subprogram (@code{Tracebacks}) to
give a traceback array of addresses based on an exception
occurrence.
@node Ada Sequential_IO C_Streams a-siocst ads,Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Exceptions Traceback a-exctra ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2ed}@anchor{gnat_rm/the_gnat_library id22}@anchor{2ee}
-@section @cite{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads})
+@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id25}@anchor{2f8}
+@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads})
@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads)
@geindex Interfacing with Sequential_IO
This package provides subprograms that allow interfacing between
-C streams and @cite{Sequential_IO}. The stream identifier can be
+C streams and @code{Sequential_IO}. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
@node Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Strings Unbounded Text_IO a-suteio ads,Ada Sequential_IO C_Streams a-siocst ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id23}@anchor{2ef}@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2f0}
-@section @cite{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads})
+@anchor{gnat_rm/the_gnat_library id26}@anchor{2f9}@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2fa}
+@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads})
@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
@geindex Interfacing with Stream_IO
This package provides subprograms that allow interfacing between
-C streams and @cite{Stream_IO}. The stream identifier can be
+C streams and @code{Stream_IO}. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
@node Ada Strings Unbounded Text_IO a-suteio ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Streams Stream_IO C_Streams a-ssicst ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{2f1}@anchor{gnat_rm/the_gnat_library id24}@anchor{2f2}
-@section @cite{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads})
+@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id27}@anchor{2fc}
+@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads})
@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
with ordinary strings.
@node Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Strings Unbounded Text_IO a-suteio ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id25}@anchor{2f3}@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{2f4}
-@section @cite{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads})
+@anchor{gnat_rm/the_gnat_library id28}@anchor{2fd}@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{2fe}
+@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads})
@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
with ordinary wide strings.
@node Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id26}@anchor{2f6}
-@section @cite{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads})
+@anchor{gnat_rm/the_gnat_library id29}@anchor{2ff}@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{300}
+@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads})
@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
with ordinary wide wide strings.
@node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id27}@anchor{2f8}
-@section @cite{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads})
+@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id30}@anchor{302}
+@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads})
@geindex Ada.Text_IO.C_Streams (a-tiocst.ads)
@geindex C Streams
-@geindex Interfacing with `Text_IO`
+@geindex Interfacing with `@w{`}Text_IO`@w{`}
This package provides subprograms that allow interfacing between
-C streams and @cite{Text_IO}. The stream identifier can be
+C streams and @code{Text_IO}. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
@node Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Wide_Characters Unicode a-wichun ads,Ada Text_IO C_Streams a-tiocst ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id28}@anchor{2f9}@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{2fa}
-@section @cite{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads})
+@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id31}@anchor{304}
+@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads})
@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
interactive).
@node Ada Wide_Characters Unicode a-wichun ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id29}@anchor{2fb}@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{2fc}
-@section @cite{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads})
+@anchor{gnat_rm/the_gnat_library id32}@anchor{305}@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{306}
+@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads})
@geindex Ada.Wide_Characters.Unicode (a-wichun.ads)
Wide_Character values according to Unicode categories.
@node Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Characters Unicode a-wichun ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{2fd}@anchor{gnat_rm/the_gnat_library id30}@anchor{2fe}
-@section @cite{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads})
+@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id33}@anchor{308}
+@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads})
@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
@geindex C Streams
-@geindex Interfacing with `Wide_Text_IO`
+@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`}
This package provides subprograms that allow interfacing between
-C streams and @cite{Wide_Text_IO}. The stream identifier can be
+C streams and @code{Wide_Text_IO}. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
@node Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id31}@anchor{300}
-@section @cite{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads})
+@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{309}@anchor{gnat_rm/the_gnat_library id34}@anchor{30a}
+@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads})
@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
interactive).
@node Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id32}@anchor{301}@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{302}
-@section @cite{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads})
+@anchor{gnat_rm/the_gnat_library id35}@anchor{30b}@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{30c}
+@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads})
@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
Wide_Wide_Character values according to Unicode categories.
@node Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id33}@anchor{303}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{304}
-@section @cite{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads})
+@anchor{gnat_rm/the_gnat_library id36}@anchor{30d}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{30e}
+@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads})
@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
@geindex C Streams
-@geindex Interfacing with `Wide_Wide_Text_IO`
+@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`}
This package provides subprograms that allow interfacing between
-C streams and @cite{Wide_Wide_Text_IO}. The stream identifier can be
+C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
extracted from a file opened on the Ada side, and an Ada file
can be constructed from a stream opened on the C side.
@node Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,GNAT Altivec g-altive ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id34}@anchor{305}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{306}
-@section @cite{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads})
+@anchor{gnat_rm/the_gnat_library id37}@anchor{30f}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{310}
+@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads})
@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
redefined to be interactive).
@node GNAT Altivec g-altive ads,GNAT Altivec Conversions g-altcon ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id35}@anchor{308}
-@section @cite{GNAT.Altivec} (@code{g-altive.ads})
+@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id38}@anchor{312}
+@section @code{GNAT.Altivec} (@code{g-altive.ads})
@geindex GNAT.Altivec (g-altive.ads)
binding.
@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id36}@anchor{309}@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{30a}
-@section @cite{GNAT.Altivec.Conversions} (@code{g-altcon.ads})
+@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{313}@anchor{gnat_rm/the_gnat_library id39}@anchor{314}
+@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads})
@geindex GNAT.Altivec.Conversions (g-altcon.ads)
This package provides the Vector/View conversion routines.
@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id37}@anchor{30b}@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{30c}
-@section @cite{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads})
+@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id40}@anchor{316}
+@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads})
@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads)
is common to both bindings.
@node GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Vector_Views g-alvevi ads,GNAT Altivec Vector_Operations g-alveop ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id38}@anchor{30e}
-@section @cite{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads})
+@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{317}@anchor{gnat_rm/the_gnat_library id41}@anchor{318}
+@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads})
@geindex GNAT.Altivec.Vector_Types (g-alvety.ads)
to AltiVec facilities.
@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id39}@anchor{310}
-@section @cite{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads})
+@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id42}@anchor{31a}
+@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads})
@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads)
objects.
@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id40}@anchor{312}
-@section @cite{GNAT.Array_Split} (@code{g-arrspl.ads})
+@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id43}@anchor{31c}
+@section @code{GNAT.Array_Split} (@code{g-arrspl.ads})
@geindex GNAT.Array_Split (g-arrspl.ads)
to the resulting slices.
@node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id41}@anchor{313}@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{314}
-@section @cite{GNAT.AWK} (@code{g-awk.ads})
+@anchor{gnat_rm/the_gnat_library id44}@anchor{31d}@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{31e}
+@section @code{GNAT.AWK} (@code{g-awk.ads})
@geindex GNAT.AWK (g-awk.ads)
where each record is a line and a field is a data element in this line.
@node GNAT Bind_Environment g-binenv ads,GNAT Bounded_Buffers g-boubuf ads,GNAT AWK g-awk ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id42}@anchor{316}
-@section @cite{GNAT.Bind_Environment} (@code{g-binenv.ads})
+@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id45}@anchor{320}
+@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads})
@geindex GNAT.Bind_Environment (g-binenv.ads)
@geindex Bind environment
Provides access to key=value associations captured at bind time.
-These associations can be specified using the @cite{-V} binder command
+These associations can be specified using the @code{-V} binder command
line switch.
@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Bind_Environment g-binenv ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{317}@anchor{gnat_rm/the_gnat_library id43}@anchor{318}
-@section @cite{GNAT.Bounded_Buffers} (@code{g-boubuf.ads})
+@anchor{gnat_rm/the_gnat_library id46}@anchor{321}@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{322}
+@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads})
@geindex GNAT.Bounded_Buffers (g-boubuf.ads)
such as mailboxes.
@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id44}@anchor{319}@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{31a}
-@section @cite{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads})
+@anchor{gnat_rm/the_gnat_library id47}@anchor{323}@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{324}
+@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads})
@geindex GNAT.Bounded_Mailboxes (g-boumai.ads)
Provides a thread-safe asynchronous intertask mailbox communication facility.
@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id45}@anchor{31c}
-@section @cite{GNAT.Bubble_Sort} (@code{g-bubsor.ads})
+@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id48}@anchor{326}
+@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads})
@geindex GNAT.Bubble_Sort (g-bubsor.ads)
access-to-procedure values.
@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id46}@anchor{31d}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{31e}
-@section @cite{GNAT.Bubble_Sort_A} (@code{g-busora.ads})
+@anchor{gnat_rm/the_gnat_library id49}@anchor{327}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{328}
+@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads})
@geindex GNAT.Bubble_Sort_A (g-busora.ads)
Provides a general implementation of bubble sort usable for sorting arbitrary
data items. Move and comparison procedures are provided by passing
access-to-procedure values. This is an older version, retained for
-compatibility. Usually @cite{GNAT.Bubble_Sort} will be preferable.
+compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
@node GNAT Bubble_Sort_G g-busorg ads,GNAT Byte_Order_Mark g-byorma ads,GNAT Bubble_Sort_A g-busora ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id47}@anchor{31f}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{320}
-@section @cite{GNAT.Bubble_Sort_G} (@code{g-busorg.ads})
+@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id50}@anchor{32a}
+@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads})
@geindex GNAT.Bubble_Sort_G (g-busorg.ads)
@geindex Bubble sort
-Similar to @cite{Bubble_Sort_A} except that the move and sorting procedures
+Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
are provided as generic parameters, this improves efficiency, especially
if the procedures can be inlined, at the expense of duplicating code for
multiple instantiations.
@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id48}@anchor{322}
-@section @cite{GNAT.Byte_Order_Mark} (@code{g-byorma.ads})
+@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id51}@anchor{32c}
+@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads})
@geindex GNAT.Byte_Order_Mark (g-byorma.ads)
sequences for various UCS input formats.
@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id49}@anchor{324}
-@section @cite{GNAT.Byte_Swapping} (@code{g-bytswa.ads})
+@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id52}@anchor{32e}
+@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads})
@geindex GNAT.Byte_Swapping (g-bytswa.ads)
Machine-specific implementations are available in some cases.
@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id50}@anchor{325}@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{326}
-@section @cite{GNAT.Calendar} (@code{g-calend.ads})
+@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id53}@anchor{330}
+@section @code{GNAT.Calendar} (@code{g-calend.ads})
@geindex GNAT.Calendar (g-calend.ads)
@geindex Calendar
-Extends the facilities provided by @cite{Ada.Calendar} to include handling
-of days of the week, an extended @cite{Split} and @cite{Time_Of} capability.
-Also provides conversion of @cite{Ada.Calendar.Time} values to and from the
-C @cite{timeval} format.
+Extends the facilities provided by @code{Ada.Calendar} to include handling
+of days of the week, an extended @code{Split} and @code{Time_Of} capability.
+Also provides conversion of @code{Ada.Calendar.Time} values to and from the
+C @code{timeval} format.
@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id51}@anchor{328}
-@section @cite{GNAT.Calendar.Time_IO} (@code{g-catiio.ads})
+@anchor{gnat_rm/the_gnat_library id54}@anchor{331}@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{332}
+@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads})
@geindex Calendar
@geindex GNAT.Calendar.Time_IO (g-catiio.ads)
@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id52}@anchor{329}@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{32a}
-@section @cite{GNAT.CRC32} (@code{g-crc32.ads})
+@anchor{gnat_rm/the_gnat_library id55}@anchor{333}@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{334}
+@section @code{GNAT.CRC32} (@code{g-crc32.ads})
@geindex GNAT.CRC32 (g-crc32.ads)
Aug. 1988. Sarwate, D.V.
@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id53}@anchor{32c}
-@section @cite{GNAT.Case_Util} (@code{g-casuti.ads})
+@anchor{gnat_rm/the_gnat_library id56}@anchor{335}@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{336}
+@section @code{GNAT.Case_Util} (@code{g-casuti.ads})
@geindex GNAT.Case_Util (g-casuti.ads)
@geindex Casing utilities
-@geindex Character handling (`GNAT.Case_Util`)
+@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`})
A set of simple routines for handling upper and lower casing of strings
without the overhead of the full casing tables
-in @cite{Ada.Characters.Handling}.
+in @code{Ada.Characters.Handling}.
@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id54}@anchor{32d}@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{32e}
-@section @cite{GNAT.CGI} (@code{g-cgi.ads})
+@anchor{gnat_rm/the_gnat_library id57}@anchor{337}@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{338}
+@section @code{GNAT.CGI} (@code{g-cgi.ads})
@geindex GNAT.CGI (g-cgi.ads)
with this table.
@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id55}@anchor{330}
-@section @cite{GNAT.CGI.Cookie} (@code{g-cgicoo.ads})
+@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id58}@anchor{33a}
+@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads})
@geindex GNAT.CGI.Cookie (g-cgicoo.ads)
cookies (piece of information kept in the Web client software).
@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id56}@anchor{332}
-@section @cite{GNAT.CGI.Debug} (@code{g-cgideb.ads})
+@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id59}@anchor{33c}
+@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads})
@geindex GNAT.CGI.Debug (g-cgideb.ads)
programs written in Ada.
@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id57}@anchor{333}@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{334}
-@section @cite{GNAT.Command_Line} (@code{g-comlin.ads})
+@anchor{gnat_rm/the_gnat_library id60}@anchor{33d}@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{33e}
+@section @code{GNAT.Command_Line} (@code{g-comlin.ads})
@geindex GNAT.Command_Line (g-comlin.ads)
@geindex Command line
-Provides a high level interface to @cite{Ada.Command_Line} facilities,
+Provides a high level interface to @code{Ada.Command_Line} facilities,
including the ability to scan for named switches with optional parameters
and expand file names using wild card notations.
@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{335}@anchor{gnat_rm/the_gnat_library id58}@anchor{336}
-@section @cite{GNAT.Compiler_Version} (@code{g-comver.ads})
+@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id61}@anchor{340}
+@section @code{GNAT.Compiler_Version} (@code{g-comver.ads})
@geindex GNAT.Compiler_Version (g-comver.ads)
of a partition).
@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id59}@anchor{338}
-@section @cite{GNAT.Ctrl_C} (@code{g-ctrl_c.ads})
+@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id62}@anchor{342}
+@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads})
@geindex GNAT.Ctrl_C (g-ctrl_c.ads)
Provides a simple interface to handle Ctrl-C keyboard events.
@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id60}@anchor{339}@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{33a}
-@section @cite{GNAT.Current_Exception} (@code{g-curexc.ads})
+@anchor{gnat_rm/the_gnat_library id63}@anchor{343}@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{344}
+@section @code{GNAT.Current_Exception} (@code{g-curexc.ads})
@geindex GNAT.Current_Exception (g-curexc.ads)
obtaining information about exceptions provided by Ada 83 compilers.
@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id61}@anchor{33c}
-@section @cite{GNAT.Debug_Pools} (@code{g-debpoo.ads})
+@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{345}@anchor{gnat_rm/the_gnat_library id64}@anchor{346}
+@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads})
@geindex GNAT.Debug_Pools (g-debpoo.ads)
Provide a debugging storage pools that helps tracking memory corruption
problems.
-See @cite{The GNAT Debug_Pool Facility} section in the @cite{GNAT User's Guide}.
+See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User's Guide}.
@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id62}@anchor{33e}
-@section @cite{GNAT.Debug_Utilities} (@code{g-debuti.ads})
+@anchor{gnat_rm/the_gnat_library id65}@anchor{347}@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{348}
+@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads})
@geindex GNAT.Debug_Utilities (g-debuti.ads)
for hexadecimal literals.
@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id63}@anchor{340}
-@section @cite{GNAT.Decode_String} (@code{g-decstr.ads})
+@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id66}@anchor{34a}
+@section @code{GNAT.Decode_String} (@code{g-decstr.ads})
@geindex GNAT.Decode_String (g-decstr.ads)
preinstantiation for UTF-8. See next entry.
@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id64}@anchor{342}
-@section @cite{GNAT.Decode_UTF8_String} (@code{g-deutst.ads})
+@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{34b}@anchor{gnat_rm/the_gnat_library id67}@anchor{34c}
+@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads})
@geindex GNAT.Decode_UTF8_String (g-deutst.ads)
A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id65}@anchor{343}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{344}
-@section @cite{GNAT.Directory_Operations} (@code{g-dirope.ads})
+@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id68}@anchor{34e}
+@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads})
@geindex GNAT.Directory_Operations (g-dirope.ads)
directory.
@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id66}@anchor{345}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{346}
-@section @cite{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads})
+@anchor{gnat_rm/the_gnat_library id69}@anchor{34f}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{350}
+@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads})
@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads)
for iterating through directories.
@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id67}@anchor{347}@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{348}
-@section @cite{GNAT.Dynamic_HTables} (@code{g-dynhta.ads})
+@anchor{gnat_rm/the_gnat_library id70}@anchor{351}@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{352}
+@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads})
@geindex GNAT.Dynamic_HTables (g-dynhta.ads)
data. Provided in two forms, a simple form with built in hash functions,
and a more complex form in which the hash function is supplied.
-This package provides a facility similar to that of @cite{GNAT.HTable},
+This package provides a facility similar to that of @code{GNAT.HTable},
except that this package declares a type that can be used to define
dynamic instances of the hash table, while an instantiation of
-@cite{GNAT.HTable} creates a single instance of the hash table.
+@code{GNAT.HTable} creates a single instance of the hash table.
@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id68}@anchor{34a}
-@section @cite{GNAT.Dynamic_Tables} (@code{g-dyntab.ads})
+@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id71}@anchor{354}
+@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads})
@geindex GNAT.Dynamic_Tables (g-dyntab.ads)
A generic package providing a single dimension array abstraction where the
length of the array can be dynamically modified.
-This package provides a facility similar to that of @cite{GNAT.Table},
+This package provides a facility similar to that of @code{GNAT.Table},
except that this package declares a type that can be used to define
dynamic instances of the table, while an instantiation of
-@cite{GNAT.Table} creates a single instance of the table type.
+@code{GNAT.Table} creates a single instance of the table type.
@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id69}@anchor{34b}@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{34c}
-@section @cite{GNAT.Encode_String} (@code{g-encstr.ads})
+@anchor{gnat_rm/the_gnat_library id72}@anchor{355}@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{356}
+@section @code{GNAT.Encode_String} (@code{g-encstr.ads})
@geindex GNAT.Encode_String (g-encstr.ads)
Note there is a preinstantiation for UTF-8. See next entry.
@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id70}@anchor{34e}
-@section @cite{GNAT.Encode_UTF8_String} (@code{g-enutst.ads})
+@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id73}@anchor{358}
+@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads})
@geindex GNAT.Encode_UTF8_String (g-enutst.ads)
A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id71}@anchor{34f}@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{350}
-@section @cite{GNAT.Exception_Actions} (@code{g-excact.ads})
+@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id74}@anchor{35a}
+@section @code{GNAT.Exception_Actions} (@code{g-excact.ads})
@geindex GNAT.Exception_Actions (g-excact.ads)
can be used for instance to force a core dump to ease debugging.
@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-expect ads,GNAT Exception_Actions g-excact ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id72}@anchor{351}@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{352}
-@section @cite{GNAT.Exception_Traces} (@code{g-exctra.ads})
+@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id75}@anchor{35c}
+@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads})
@geindex GNAT.Exception_Traces (g-exctra.ads)
occurrences.
@node GNAT Exceptions g-expect ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id73}@anchor{353}@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-expect-ads}@anchor{354}
-@section @cite{GNAT.Exceptions} (@code{g-expect.ads})
+@anchor{gnat_rm/the_gnat_library id76}@anchor{35d}@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-expect-ads}@anchor{35e}
+@section @code{GNAT.Exceptions} (@code{g-expect.ads})
@geindex GNAT.Exceptions (g-expect.ads)
Normally it is not possible to raise an exception with
a message from a subprogram in a pure package, since the
-necessary types and subprograms are in @cite{Ada.Exceptions}
-which is not a pure unit. @cite{GNAT.Exceptions} provides a
+necessary types and subprograms are in @code{Ada.Exceptions}
+which is not a pure unit. @code{GNAT.Exceptions} provides a
facility for getting around this limitation for a few
predefined exceptions, and for example allow raising
-@cite{Constraint_Error} with a message from a pure subprogram.
+@code{Constraint_Error} with a message from a pure subprogram.
@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-expect ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id74}@anchor{356}
-@section @cite{GNAT.Expect} (@code{g-expect.ads})
+@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id77}@anchor{360}
+@section @code{GNAT.Expect} (@code{g-expect.ads})
@geindex GNAT.Expect (g-expect.ads)
with the standard Tcl Expect tool.
It allows you to easily spawn and communicate with an external process.
You can send commands or inputs to the process, and compare the output
-with some expected regular expression. Currently @cite{GNAT.Expect}
+with some expected regular expression. Currently @code{GNAT.Expect}
is implemented on all native GNAT ports.
It is not implemented for cross ports, and in particular is not
implemented for VxWorks or LynxOS.
@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id75}@anchor{358}
-@section @cite{GNAT.Expect.TTY} (@code{g-exptty.ads})
+@anchor{gnat_rm/the_gnat_library id78}@anchor{361}@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{362}
+@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads})
@geindex GNAT.Expect.TTY (g-exptty.ads)
As GNAT.Expect but using pseudo-terminal.
-Currently @cite{GNAT.Expect.TTY} is implemented on all native GNAT
+Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT
ports. It is not implemented for cross ports, and
in particular is not implemented for VxWorks or LynxOS.
@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id76}@anchor{359}@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{35a}
-@section @cite{GNAT.Float_Control} (@code{g-flocon.ads})
+@anchor{gnat_rm/the_gnat_library id79}@anchor{363}@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{364}
+@section @code{GNAT.Float_Control} (@code{g-flocon.ads})
@geindex GNAT.Float_Control (g-flocon.ads)
in this package can be used to reestablish the required mode.
@node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id77}@anchor{35c}
-@section @cite{GNAT.Formatted_String} (@code{g-forstr.ads})
+@anchor{gnat_rm/the_gnat_library id80}@anchor{365}@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{366}
+@section @code{GNAT.Formatted_String} (@code{g-forstr.ads})
@geindex GNAT.Formatted_String (g-forstr.ads)
formatted string.
@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id78}@anchor{35e}
-@section @cite{GNAT.Heap_Sort} (@code{g-heasor.ads})
+@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id81}@anchor{368}
+@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads})
@geindex GNAT.Heap_Sort (g-heasor.ads)
that performs approximately N*log(N) comparisons in the worst case.
@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id79}@anchor{35f}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{360}
-@section @cite{GNAT.Heap_Sort_A} (@code{g-hesora.ads})
+@anchor{gnat_rm/the_gnat_library id82}@anchor{369}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{36a}
+@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads})
@geindex GNAT.Heap_Sort_A (g-hesora.ads)
data items. Move and comparison procedures are provided by passing
access-to-procedure values. The algorithm used is a modified heap sort
that performs approximately N*log(N) comparisons in the worst case.
-This differs from @cite{GNAT.Heap_Sort} in having a less convenient
+This differs from @code{GNAT.Heap_Sort} in having a less convenient
interface, but may be slightly more efficient.
@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id80}@anchor{361}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{362}
-@section @cite{GNAT.Heap_Sort_G} (@code{g-hesorg.ads})
+@anchor{gnat_rm/the_gnat_library id83}@anchor{36b}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{36c}
+@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads})
@geindex GNAT.Heap_Sort_G (g-hesorg.ads)
@geindex Sorting
-Similar to @cite{Heap_Sort_A} except that the move and sorting procedures
+Similar to @code{Heap_Sort_A} except that the move and sorting procedures
are provided as generic parameters, this improves efficiency, especially
if the procedures can be inlined, at the expense of duplicating code for
multiple instantiations.
@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id81}@anchor{363}@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{364}
-@section @cite{GNAT.HTable} (@code{g-htable.ads})
+@anchor{gnat_rm/the_gnat_library id84}@anchor{36d}@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{36e}
+@section @code{GNAT.HTable} (@code{g-htable.ads})
@geindex GNAT.HTable (g-htable.ads)
allowing arbitrary dynamic hash tables.
@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id82}@anchor{365}@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{366}
-@section @cite{GNAT.IO} (@code{g-io.ads})
+@anchor{gnat_rm/the_gnat_library id85}@anchor{36f}@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{370}
+@section @code{GNAT.IO} (@code{g-io.ads})
@geindex GNAT.IO (g-io.ads)
Standard_Output or Standard_Error.
@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id83}@anchor{367}@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{368}
-@section @cite{GNAT.IO_Aux} (@code{g-io_aux.ads})
+@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id86}@anchor{372}
+@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads})
@geindex GNAT.IO_Aux (g-io_aux.ads)
for whether a file exists, and functions for reading a line of text.
@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id84}@anchor{36a}
-@section @cite{GNAT.Lock_Files} (@code{g-locfil.ads})
+@anchor{gnat_rm/the_gnat_library id87}@anchor{373}@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{374}
+@section @code{GNAT.Lock_Files} (@code{g-locfil.ads})
@geindex GNAT.Lock_Files (g-locfil.ads)
providing program level synchronization.
@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id85}@anchor{36b}@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{36c}
-@section @cite{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads})
+@anchor{gnat_rm/the_gnat_library id88}@anchor{375}@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{376}
+@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads})
@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads)
@geindex Random number generation
-The original implementation of @cite{Ada.Numerics.Discrete_Random}. Uses
+The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses
a modified version of the Blum-Blum-Shub generator.
@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id86}@anchor{36d}@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{36e}
-@section @cite{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads})
+@anchor{gnat_rm/the_gnat_library id89}@anchor{377}@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{378}
+@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads})
@geindex GNAT.MBBS_Float_Random (g-mbflra.ads)
@geindex Random number generation
-The original implementation of @cite{Ada.Numerics.Float_Random}. Uses
+The original implementation of @code{Ada.Numerics.Float_Random}. Uses
a modified version of the Blum-Blum-Shub generator.
@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id87}@anchor{36f}@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{370}
-@section @cite{GNAT.MD5} (@code{g-md5.ads})
+@anchor{gnat_rm/the_gnat_library id90}@anchor{379}@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{37a}
+@section @code{GNAT.MD5} (@code{g-md5.ads})
@geindex GNAT.MD5 (g-md5.ads)
FIPS PUB 198.
@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id88}@anchor{371}@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{372}
-@section @cite{GNAT.Memory_Dump} (@code{g-memdum.ads})
+@anchor{gnat_rm/the_gnat_library id91}@anchor{37b}@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{37c}
+@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads})
@geindex GNAT.Memory_Dump (g-memdum.ads)
output.
@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id89}@anchor{373}@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{374}
-@section @cite{GNAT.Most_Recent_Exception} (@code{g-moreex.ads})
+@anchor{gnat_rm/the_gnat_library id92}@anchor{37d}@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{37e}
+@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads})
@geindex GNAT.Most_Recent_Exception (g-moreex.ads)
Ada 83 implementation dependent extensions.
@node GNAT OS_Lib g-os_lib ads,GNAT Perfect_Hash_Generators g-pehage ads,GNAT Most_Recent_Exception g-moreex ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id90}@anchor{375}@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{376}
-@section @cite{GNAT.OS_Lib} (@code{g-os_lib.ads})
+@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id93}@anchor{380}
+@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads})
@geindex GNAT.OS_Lib (g-os_lib.ads)
and error return codes.
@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id91}@anchor{378}
-@section @cite{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads})
+@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id94}@anchor{382}
+@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads})
@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads)
convenient for use with realtime applications.
@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id92}@anchor{37a}
-@section @cite{GNAT.Random_Numbers} (@code{g-rannum.ads})
+@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{383}@anchor{gnat_rm/the_gnat_library id95}@anchor{384}
+@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads})
@geindex GNAT.Random_Numbers (g-rannum.ads)
standard Ada library and are more convenient to use.
@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{24c}@anchor{gnat_rm/the_gnat_library id93}@anchor{37b}
-@section @cite{GNAT.Regexp} (@code{g-regexp.ads})
+@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{250}@anchor{gnat_rm/the_gnat_library id96}@anchor{385}
+@section @code{GNAT.Regexp} (@code{g-regexp.ads})
@geindex GNAT.Regexp (g-regexp.ads)
suitable for 'file globbing' applications.
@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id94}@anchor{37c}@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{37d}
-@section @cite{GNAT.Registry} (@code{g-regist.ads})
+@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{386}@anchor{gnat_rm/the_gnat_library id97}@anchor{387}
+@section @code{GNAT.Registry} (@code{g-regist.ads})
@geindex GNAT.Registry (g-regist.ads)
package provided with the Win32Ada binding
@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{37e}@anchor{gnat_rm/the_gnat_library id95}@anchor{37f}
-@section @cite{GNAT.Regpat} (@code{g-regpat.ads})
+@anchor{gnat_rm/the_gnat_library id98}@anchor{388}@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{389}
+@section @code{GNAT.Regpat} (@code{g-regpat.ads})
@geindex GNAT.Regpat (g-regpat.ads)
Henry Spencer (and binary compatible with this C library).
@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id96}@anchor{380}@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{381}
-@section @cite{GNAT.Rewrite_Data} (@code{g-rewdat.ads})
+@anchor{gnat_rm/the_gnat_library id99}@anchor{38a}@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{38b}
+@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads})
@geindex GNAT.Rewrite_Data (g-rewdat.ads)
this interface usable for large files or socket streams.
@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{382}@anchor{gnat_rm/the_gnat_library id97}@anchor{383}
-@section @cite{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads})
+@anchor{gnat_rm/the_gnat_library id100}@anchor{38c}@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{38d}
+@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads})
@geindex GNAT.Secondary_Stack_Info (g-sestin.ads)
secondary stack.
@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id98}@anchor{384}@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{385}
-@section @cite{GNAT.Semaphores} (@code{g-semaph.ads})
+@anchor{gnat_rm/the_gnat_library id101}@anchor{38e}@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{38f}
+@section @code{GNAT.Semaphores} (@code{g-semaph.ads})
@geindex GNAT.Semaphores (g-semaph.ads)
Provides classic counting and binary semaphores using protected types.
@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{386}@anchor{gnat_rm/the_gnat_library id99}@anchor{387}
-@section @cite{GNAT.Serial_Communications} (@code{g-sercom.ads})
+@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{390}@anchor{gnat_rm/the_gnat_library id102}@anchor{391}
+@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads})
@geindex GNAT.Serial_Communications (g-sercom.ads)
port. This is only supported on GNU/Linux and Windows.
@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{388}@anchor{gnat_rm/the_gnat_library id100}@anchor{389}
-@section @cite{GNAT.SHA1} (@code{g-sha1.ads})
+@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{392}@anchor{gnat_rm/the_gnat_library id103}@anchor{393}
+@section @code{GNAT.SHA1} (@code{g-sha1.ads})
@geindex GNAT.SHA1 (g-sha1.ads)
in RFC 2104 and FIPS PUB 198.
@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id101}@anchor{38a}@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{38b}
-@section @cite{GNAT.SHA224} (@code{g-sha224.ads})
+@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{394}@anchor{gnat_rm/the_gnat_library id104}@anchor{395}
+@section @code{GNAT.SHA224} (@code{g-sha224.ads})
@geindex GNAT.SHA224 (g-sha224.ads)
in RFC 2104 and FIPS PUB 198.
@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id102}@anchor{38c}@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{38d}
-@section @cite{GNAT.SHA256} (@code{g-sha256.ads})
+@anchor{gnat_rm/the_gnat_library id105}@anchor{396}@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{397}
+@section @code{GNAT.SHA256} (@code{g-sha256.ads})
@geindex GNAT.SHA256 (g-sha256.ads)
in RFC 2104 and FIPS PUB 198.
@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id103}@anchor{38e}@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{38f}
-@section @cite{GNAT.SHA384} (@code{g-sha384.ads})
+@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id106}@anchor{399}
+@section @code{GNAT.SHA384} (@code{g-sha384.ads})
@geindex GNAT.SHA384 (g-sha384.ads)
in RFC 2104 and FIPS PUB 198.
@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{390}@anchor{gnat_rm/the_gnat_library id104}@anchor{391}
-@section @cite{GNAT.SHA512} (@code{g-sha512.ads})
+@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id107}@anchor{39b}
+@section @code{GNAT.SHA512} (@code{g-sha512.ads})
@geindex GNAT.SHA512 (g-sha512.ads)
in RFC 2104 and FIPS PUB 198.
@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{392}@anchor{gnat_rm/the_gnat_library id105}@anchor{393}
-@section @cite{GNAT.Signals} (@code{g-signal.ads})
+@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{39c}@anchor{gnat_rm/the_gnat_library id108}@anchor{39d}
+@section @code{GNAT.Signals} (@code{g-signal.ads})
@geindex GNAT.Signals (g-signal.ads)
targets.
@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{394}@anchor{gnat_rm/the_gnat_library id106}@anchor{395}
-@section @cite{GNAT.Sockets} (@code{g-socket.ads})
+@anchor{gnat_rm/the_gnat_library id109}@anchor{39e}@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{39f}
+@section @code{GNAT.Sockets} (@code{g-socket.ads})
@geindex GNAT.Sockets (g-socket.ads)
A high level and portable interface to develop sockets based applications.
This package is based on the sockets thin binding found in
-@cite{GNAT.Sockets.Thin}. Currently @cite{GNAT.Sockets} is implemented
+@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
on all native GNAT ports and on VxWorks cross prots. It is not implemented for
the LynxOS cross port.
@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{396}@anchor{gnat_rm/the_gnat_library id107}@anchor{397}
-@section @cite{GNAT.Source_Info} (@code{g-souinf.ads})
+@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id110}@anchor{3a1}
+@section @code{GNAT.Source_Info} (@code{g-souinf.ads})
@geindex GNAT.Source_Info (g-souinf.ads)
Provides subprograms that give access to source code information known at
compile time, such as the current file name and line number. Also provides
subprograms yielding the date and time of the current compilation (like the
-C macros @cite{__DATE__} and @cite{__TIME__})
+C macros @code{__DATE__} and @code{__TIME__})
@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id108}@anchor{399}
-@section @cite{GNAT.Spelling_Checker} (@code{g-speche.ads})
+@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id111}@anchor{3a3}
+@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads})
@geindex GNAT.Spelling_Checker (g-speche.ads)
near misspelling of another string.
@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id109}@anchor{39a}@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{39b}
-@section @cite{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads})
+@anchor{gnat_rm/the_gnat_library id112}@anchor{3a4}@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3a5}
+@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads})
@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads)
string.
@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id110}@anchor{39c}@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{39d}
-@section @cite{GNAT.Spitbol.Patterns} (@code{g-spipat.ads})
+@anchor{gnat_rm/the_gnat_library id113}@anchor{3a6}@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3a7}
+@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads})
@geindex GNAT.Spitbol.Patterns (g-spipat.ads)
efficient algorithm developed by Robert Dewar for the SPITBOL system.
@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id111}@anchor{39e}@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{39f}
-@section @cite{GNAT.Spitbol} (@code{g-spitbo.ads})
+@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id114}@anchor{3a9}
+@section @code{GNAT.Spitbol} (@code{g-spitbo.ads})
@geindex GNAT.Spitbol (g-spitbo.ads)
the SNOBOL4 TABLE function.
@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id112}@anchor{3a0}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3a1}
-@section @cite{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads})
+@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id115}@anchor{3ab}
+@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads})
@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
@geindex SPITBOL Tables
-A library level of instantiation of @cite{GNAT.Spitbol.Patterns.Table}
-for type @cite{Standard.Boolean}, giving an implementation of sets of
+A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
+for type @code{Standard.Boolean}, giving an implementation of sets of
string values.
@node GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol Table_VString g-sptavs ads,GNAT Spitbol Table_Boolean g-sptabo ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id113}@anchor{3a2}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3a3}
-@section @cite{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads})
+@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id116}@anchor{3ad}
+@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads})
@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads)
@geindex SPITBOL Tables
-A library level of instantiation of @cite{GNAT.Spitbol.Patterns.Table}
-for type @cite{Standard.Integer}, giving an implementation of maps
+A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
+for type @code{Standard.Integer}, giving an implementation of maps
from string to integer values.
@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id114}@anchor{3a4}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3a5}
-@section @cite{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads})
+@anchor{gnat_rm/the_gnat_library id117}@anchor{3ae}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3af}
+@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads})
@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads)
@geindex SPITBOL Tables
-A library level of instantiation of @cite{GNAT.Spitbol.Patterns.Table} for
+A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
a variable length string type, giving an implementation of general
maps from strings to strings.
@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id115}@anchor{3a6}@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3a7}
-@section @cite{GNAT.SSE} (@code{g-sse.ads})
+@anchor{gnat_rm/the_gnat_library id118}@anchor{3b0}@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3b1}
+@section @code{GNAT.SSE} (@code{g-sse.ads})
@geindex GNAT.SSE (g-sse.ads)
introduction to the binding contents and use.
@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id116}@anchor{3a9}
-@section @cite{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads})
+@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id119}@anchor{3b3}
+@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads})
@geindex GNAT.SSE.Vector_Types (g-ssvety.ads)
SSE vector types for use with SSE related intrinsics.
@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id117}@anchor{3ab}
-@section @cite{GNAT.String_Hash} (@code{g-strhas.ads})
+@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id120}@anchor{3b5}
+@section @code{GNAT.String_Hash} (@code{g-strhas.ads})
@geindex GNAT.String_Hash (g-strhas.ads)
type and the hash result type are parameters.
@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id118}@anchor{3ac}@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3ad}
-@section @cite{GNAT.Strings} (@code{g-string.ads})
+@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id121}@anchor{3b7}
+@section @code{GNAT.Strings} (@code{g-string.ads})
@geindex GNAT.Strings (g-string.ads)
defines a string access and an array of string access types.
@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id119}@anchor{3af}
-@section @cite{GNAT.String_Split} (@code{g-strspl.ads})
+@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id122}@anchor{3b9}
+@section @code{GNAT.String_Split} (@code{g-strspl.ads})
@geindex GNAT.String_Split (g-strspl.ads)
Useful string manipulation routines: given a set of separators, split
a string wherever the separators appear, and provide direct access
to the resulting slices. This package is instantiated from
-@cite{GNAT.Array_Split}.
+@code{GNAT.Array_Split}.
@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id120}@anchor{3b1}
-@section @cite{GNAT.Table} (@code{g-table.ads})
+@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id123}@anchor{3bb}
+@section @code{GNAT.Table} (@code{g-table.ads})
@geindex GNAT.Table (g-table.ads)
A generic package providing a single dimension array abstraction where the
length of the array can be dynamically modified.
-This package provides a facility similar to that of @cite{GNAT.Dynamic_Tables},
+This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
except that this package declares a single instance of the table type,
-while an instantiation of @cite{GNAT.Dynamic_Tables} creates a type that can be
+while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
used to define dynamic instances of the table.
@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id121}@anchor{3b3}
-@section @cite{GNAT.Task_Lock} (@code{g-tasloc.ads})
+@anchor{gnat_rm/the_gnat_library id124}@anchor{3bc}@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3bd}
+@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads})
@geindex GNAT.Task_Lock (g-tasloc.ads)
between tasks is very rarely expected.
@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id122}@anchor{3b5}
-@section @cite{GNAT.Time_Stamp} (@code{g-timsta.ads})
+@anchor{gnat_rm/the_gnat_library id125}@anchor{3be}@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3bf}
+@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads})
@geindex GNAT.Time_Stamp (g-timsta.ads)
routine with minimal code and there are no dependencies on any other unit.
@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id123}@anchor{3b7}
-@section @cite{GNAT.Threads} (@code{g-thread.ads})
+@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id126}@anchor{3c1}
+@section @code{GNAT.Threads} (@code{g-thread.ads})
@geindex GNAT.Threads (g-thread.ads)
environment which then accesses Ada code.
@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id124}@anchor{3b8}@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3b9}
-@section @cite{GNAT.Traceback} (@code{g-traceb.ads})
+@anchor{gnat_rm/the_gnat_library id127}@anchor{3c2}@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3c3}
+@section @code{GNAT.Traceback} (@code{g-traceb.ads})
@geindex GNAT.Traceback (g-traceb.ads)
in various debugging situations.
@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id125}@anchor{3bb}
-@section @cite{GNAT.Traceback.Symbolic} (@code{g-trasym.ads})
+@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id128}@anchor{3c5}
+@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads})
@geindex GNAT.Traceback.Symbolic (g-trasym.ads)
@geindex Trace back facilities
@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id126}@anchor{3bc}@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3bd}
-@section @cite{GNAT.UTF_32} (@code{g-table.ads})
+@anchor{gnat_rm/the_gnat_library id129}@anchor{3c6}@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3c7}
+@section @code{GNAT.UTF_32} (@code{g-table.ads})
@geindex GNAT.UTF_32 (g-table.ads)
@geindex Wide character codes
This is a package intended to be used in conjunction with the
-@cite{Wide_Character} type in Ada 95 and the
-@cite{Wide_Wide_Character} type in Ada 2005 (available
-in @cite{GNAT} in Ada 2005 mode). This package contains
+@code{Wide_Character} type in Ada 95 and the
+@code{Wide_Wide_Character} type in Ada 2005 (available
+in @code{GNAT} in Ada 2005 mode). This package contains
Unicode categorization routines, as well as lexical
categorization routines corresponding to the Ada 2005
lexical rules for identifiers and strings, and also a
the Ada 2005 rules for identifier equivalence.
@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3be}@anchor{gnat_rm/the_gnat_library id127}@anchor{3bf}
-@section @cite{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads})
+@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id130}@anchor{3c9}
+@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads})
@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads)
using the UTF_32_String type defined in System.Wch_Cnv.
@node GNAT Wide_Spelling_Checker g-wispch ads,GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Spelling_Checker g-u3spch ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id128}@anchor{3c1}
-@section @cite{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads})
+@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3ca}@anchor{gnat_rm/the_gnat_library id131}@anchor{3cb}
+@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads})
@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads)
near misspelling of another wide string.
@node GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Spelling_Checker g-wispch ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id129}@anchor{3c3}
-@section @cite{GNAT.Wide_String_Split} (@code{g-wistsp.ads})
+@anchor{gnat_rm/the_gnat_library id132}@anchor{3cc}@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3cd}
+@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads})
@geindex GNAT.Wide_String_Split (g-wistsp.ads)
Useful wide string manipulation routines: given a set of separators, split
a wide string wherever the separators appear, and provide direct access
to the resulting slices. This package is instantiated from
-@cite{GNAT.Array_Split}.
+@code{GNAT.Array_Split}.
@node GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Wide_String_Split g-zistsp ads,GNAT Wide_String_Split g-wistsp ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id130}@anchor{3c5}
-@section @cite{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads})
+@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id133}@anchor{3cf}
+@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads})
@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
near misspelling of another wide wide string.
@node GNAT Wide_Wide_String_Split g-zistsp ads,Interfaces C Extensions i-cexten ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id131}@anchor{3c7}
-@section @cite{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads})
+@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id134}@anchor{3d1}
+@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads})
@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads)
Useful wide wide string manipulation routines: given a set of separators, split
a wide wide string wherever the separators appear, and provide direct access
to the resulting slices. This package is instantiated from
-@cite{GNAT.Array_Split}.
+@code{GNAT.Array_Split}.
@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id132}@anchor{3c9}
-@section @cite{Interfaces.C.Extensions} (@code{i-cexten.ads})
+@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id135}@anchor{3d3}
+@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads})
@geindex Interfaces.C.Extensions (i-cexten.ads)
to C libraries.
@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id133}@anchor{3ca}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3cb}
-@section @cite{Interfaces.C.Streams} (@code{i-cstrea.ads})
+@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3d4}@anchor{gnat_rm/the_gnat_library id136}@anchor{3d5}
+@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads})
@geindex Interfaces.C.Streams (i-cstrea.ads)
on C streams.
@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3cc}@anchor{gnat_rm/the_gnat_library id134}@anchor{3cd}
-@section @cite{Interfaces.Packed_Decimal} (@code{i-pacdec.ads})
+@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3d6}@anchor{gnat_rm/the_gnat_library id137}@anchor{3d7}
+@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads})
@geindex Interfaces.Packed_Decimal (i-pacdec.ads)
mainframes.
@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id135}@anchor{3cf}
-@section @cite{Interfaces.VxWorks} (@code{i-vxwork.ads})
+@anchor{gnat_rm/the_gnat_library id138}@anchor{3d8}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3d9}
+@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads})
@geindex Interfaces.VxWorks (i-vxwork.ads)
VxWorks hardware interrupt facilities.
@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id136}@anchor{3d1}
-@section @cite{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads})
+@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3da}@anchor{gnat_rm/the_gnat_library id139}@anchor{3db}
+@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads})
@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads)
handlers.
@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id137}@anchor{3d3}
-@section @cite{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads})
+@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3dc}@anchor{gnat_rm/the_gnat_library id140}@anchor{3dd}
+@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads})
@geindex Interfaces.VxWorks.IO (i-vxwoio.ads)
to enable the use of Get_Immediate under VxWorks.
@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id138}@anchor{3d4}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3d5}
-@section @cite{System.Address_Image} (@code{s-addima.ads})
+@anchor{gnat_rm/the_gnat_library id141}@anchor{3de}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3df}
+@section @code{System.Address_Image} (@code{s-addima.ads})
@geindex System.Address_Image (s-addima.ads)
string which identifies an address.
@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id139}@anchor{3d6}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3d7}
-@section @cite{System.Assertions} (@code{s-assert.ads})
+@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3e0}@anchor{gnat_rm/the_gnat_library id142}@anchor{3e1}
+@section @code{System.Assertions} (@code{s-assert.ads})
@geindex System.Assertions (s-assert.ads)
is used internally to raise this assertion.
@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id140}@anchor{3d8}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3d9}
-@section @cite{System.Atomic_Counters} (@code{s-atocou.ads})
+@anchor{gnat_rm/the_gnat_library id143}@anchor{3e2}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3e3}
+@section @code{System.Atomic_Counters} (@code{s-atocou.ads})
@geindex System.Atomic_Counters (s-atocou.ads)
x86, and x86_64 platforms.
@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3da}@anchor{gnat_rm/the_gnat_library id141}@anchor{3db}
-@section @cite{System.Memory} (@code{s-memory.ads})
+@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3e4}@anchor{gnat_rm/the_gnat_library id144}@anchor{3e5}
+@section @code{System.Memory} (@code{s-memory.ads})
@geindex System.Memory (s-memory.ads)
realloc. The body of this unit may be modified to provide alternative
allocation mechanisms for the default pool, and in addition, direct
calls to this unit may be made for low level allocation uses (for
-example see the body of @cite{GNAT.Tables}).
+example see the body of @code{GNAT.Tables}).
@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3dc}@anchor{gnat_rm/the_gnat_library id142}@anchor{3dd}
-@section @cite{System.Multiprocessors} (@code{s-multip.ads})
+@anchor{gnat_rm/the_gnat_library id145}@anchor{3e6}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3e7}
+@section @code{System.Multiprocessors} (@code{s-multip.ads})
@geindex System.Multiprocessors (s-multip.ads)
technically an implementation-defined addition).
@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3de}@anchor{gnat_rm/the_gnat_library id143}@anchor{3df}
-@section @cite{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads})
+@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3e8}@anchor{gnat_rm/the_gnat_library id146}@anchor{3e9}
+@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads})
@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads)
technically an implementation-defined addition).
@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id144}@anchor{3e0}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3e1}
-@section @cite{System.Partition_Interface} (@code{s-parint.ads})
+@anchor{gnat_rm/the_gnat_library id147}@anchor{3ea}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3eb}
+@section @code{System.Partition_Interface} (@code{s-parint.ads})
@geindex System.Partition_Interface (s-parint.ads)
This package provides facilities for partition interfacing. It
is used primarily in a distribution context when using Annex E
-with @cite{GLADE}.
+with @code{GLADE}.
@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id145}@anchor{3e2}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3e3}
-@section @cite{System.Pool_Global} (@code{s-pooglo.ads})
+@anchor{gnat_rm/the_gnat_library id148}@anchor{3ec}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3ed}
+@section @code{System.Pool_Global} (@code{s-pooglo.ads})
@geindex System.Pool_Global (s-pooglo.ads)
do any automatic reclamation.
@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3e4}@anchor{gnat_rm/the_gnat_library id146}@anchor{3e5}
-@section @cite{System.Pool_Local} (@code{s-pooloc.ads})
+@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3ee}@anchor{gnat_rm/the_gnat_library id149}@anchor{3ef}
+@section @code{System.Pool_Local} (@code{s-pooloc.ads})
@geindex System.Pool_Local (s-pooloc.ads)
be freed automatically when the pool is finalized.
@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id147}@anchor{3e6}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3e7}
-@section @cite{System.Restrictions} (@code{s-restri.ads})
+@anchor{gnat_rm/the_gnat_library id150}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3f1}
+@section @code{System.Restrictions} (@code{s-restri.ads})
@geindex System.Restrictions (s-restri.ads)
are violated by one or more packages in the partition.
@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3e8}@anchor{gnat_rm/the_gnat_library id148}@anchor{3e9}
-@section @cite{System.Rident} (@code{s-rident.ads})
+@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3f2}@anchor{gnat_rm/the_gnat_library id151}@anchor{3f3}
+@section @code{System.Rident} (@code{s-rident.ads})
@geindex System.Rident (s-rident.ads)
This package provides definitions of the restrictions
identifiers supported by GNAT, and also the format of
the restrictions provided in package System.Restrictions.
-It is not normally necessary to @cite{with} this generic package
+It is not normally necessary to @code{with} this generic package
since the necessary instantiation is included in
package System.Restrictions.
@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library id149}@anchor{3ea}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3eb}
-@section @cite{System.Strings.Stream_Ops} (@code{s-ststop.ads})
+@anchor{gnat_rm/the_gnat_library id152}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3f5}
+@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads})
@geindex System.Strings.Stream_Ops (s-ststop.ads)
package can be used directly by application programs.
@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3ec}@anchor{gnat_rm/the_gnat_library id150}@anchor{3ed}
-@section @cite{System.Unsigned_Types} (@code{s-unstyp.ads})
+@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3f6}@anchor{gnat_rm/the_gnat_library id153}@anchor{3f7}
+@section @code{System.Unsigned_Types} (@code{s-unstyp.ads})
@geindex System.Unsigned_Types (s-unstyp.ads)
used by the compiler in connection with packed array types.
@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{3ee}@anchor{gnat_rm/the_gnat_library id151}@anchor{3ef}
-@section @cite{System.Wch_Cnv} (@code{s-wchcnv.ads})
+@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{3f8}@anchor{gnat_rm/the_gnat_library id154}@anchor{3f9}
+@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads})
@geindex System.Wch_Cnv (s-wchcnv.ads)
This package provides routines for converting between
wide and wide wide characters and a representation as a value of type
-@cite{Standard.String}, using a specified wide character
+@code{Standard.String}, using a specified wide character
encoding method. It uses definitions in
-package @cite{System.Wch_Con}.
+package @code{System.Wch_Con}.
@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library
-@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{3f0}@anchor{gnat_rm/the_gnat_library id152}@anchor{3f1}
-@section @cite{System.Wch_Con} (@code{s-wchcon.ads})
+@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{3fa}@anchor{gnat_rm/the_gnat_library id155}@anchor{3fb}
+@section @code{System.Wch_Con} (@code{s-wchcon.ads})
@geindex System.Wch_Con (s-wchcon.ads)
This package provides definitions and descriptions of
the various methods used for encoding wide characters
in ordinary strings. These definitions are used by
-the package @cite{System.Wch_Cnv}.
+the package @code{System.Wch_Cnv}.
@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top
-@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{3f2}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{3f3}
+@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{3fc}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{3fd}
@chapter Interfacing to Other Languages
@end menu
@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages
-@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{3f4}@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{3f5}
+@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{3fe}@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{3ff}
@section Interfacing to C
@itemize *
@item
-The types in the package @cite{Interfaces.C} may be used.
+The types in the package @code{Interfaces.C} may be used.
@item
Standard Ada types may be used directly. This may be less portable to
correspondence between the C and Ada types.
@end itemize
-Pragma @cite{Convention C} may be applied to Ada types, but mostly has no
+Pragma @code{Convention C} may be applied to Ada types, but mostly has no
effect, since this is the default. The following table shows the
correspondence between Ada scalar types and the corresponding C types.
@item
Ada enumeration types map to C enumeration types directly if pragma
-@cite{Convention C} is specified, which causes them to have int
-length. Without pragma @cite{Convention C}, Ada enumeration types map to
-8, 16, or 32 bits (i.e., C types @cite{signed char}, @cite{short},
-@cite{int}, respectively) depending on the number of values passed.
-This is the only case in which pragma @cite{Convention C} affects the
+@code{Convention C} is specified, which causes them to have int
+length. Without pragma @code{Convention C}, Ada enumeration types map to
+8, 16, or 32 bits (i.e., C types @code{signed char}, @code{short},
+@code{int}, respectively) depending on the number of values passed.
+This is the only case in which pragma @code{Convention C} affects the
representation of an Ada type.
@item
@end itemize
@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages
-@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{3f6}@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{45}
+@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{400}@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{45}
@section Interfacing to C++
@table @asis
-@item @emph{pragma CPP_Class ([Entity =>] `LOCAL_NAME`)}
+@item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})}
The argument denotes an entity in the current declarative region that is
declared as a tagged or untagged record type. It indicates that the type
corresponds to an externally declared C++ class type, and is to be laid
out the same way that C++ would lay out the type.
-Note: Pragma @cite{CPP_Class} is currently obsolete. It is supported
+Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
for backward compatibility but its functionality is available
-using pragma @cite{Import} with @cite{Convention} = @cite{CPP}.
+using pragma @code{Import} with @code{Convention} = @code{CPP}.
-@item @emph{pragma CPP_Constructor ([Entity =>] `LOCAL_NAME`)}
+@item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})}
This pragma identifies an imported function (imported in the usual way
-with pragma @cite{Import}) as corresponding to a C++ constructor.
+with pragma @code{Import}) as corresponding to a C++ constructor.
@end table
-A few restrictions are placed on the use of the @cite{Access} attribute
-in conjunction with subprograms subject to convention @cite{CPP}: the
+A few restrictions are placed on the use of the @code{Access} attribute
+in conjunction with subprograms subject to convention @code{CPP}: the
attribute may be used neither on primitive operations of a tagged
-record type with convention @cite{CPP}, imported or not, nor on
-subprograms imported with pragma @cite{CPP_Constructor}.
+record type with convention @code{CPP}, imported or not, nor on
+subprograms imported with pragma @code{CPP_Constructor}.
In addition, C++ exceptions are propagated and can be handled in an
-@cite{others} choice of an exception handler. The corresponding Ada
+@code{others} choice of an exception handler. The corresponding Ada
occurrence has no message, and the simple name of the exception identity
contains @code{Foreign_Exception}. Finalization and awaiting dependent
tasks works properly when such foreign exceptions are propagated.
[External_Name =>] static_string_EXPRESSION);
@end example
-The @cite{External_Name} is the name of the C++ RTTI symbol. You can then
+The @code{External_Name} is the name of the C++ RTTI symbol. You can then
cover a specific C++ exception in an exception handler.
@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages
-@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{3f7}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{3f8}
+@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{401}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{402}
@section Interfacing to COBOL
the Ada Reference Manual.
@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages
-@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{3f9}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{3fa}
+@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{403}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{404}
@section Interfacing to Fortran
Interfacing to Fortran is achieved as described in section B.5 of the
-Ada Reference Manual. The pragma @cite{Convention Fortran}, applied to a
+Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a
multi-dimensional array causes the array to be stored in column-major
order as required for convenient interface to Fortran.
@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages
-@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{3fb}@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{3fc}
+@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{405}@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{406}
@section Interfacing to non-GNAT Ada code
-It is possible to specify the convention @cite{Ada} in a pragma
-@cite{Import} or pragma @cite{Export}. However this refers to
+It is possible to specify the convention @code{Ada} in a pragma
+@code{Import} or pragma @code{Export}. However this refers to
the calling conventions used by GNAT, which may or may not be
similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
compiler to allow interoperation.
types with fixed bounds.
@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top
-@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{3fd}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{3fe}
+@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{407}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{408}
@chapter Specialized Needs Annexes
@end table
@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top
-@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13}@anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{3ff}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{400}
+@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13}@anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{409}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{40a}
@chapter Implementation of Specific Ada Features
@end menu
@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{160}@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{401}
+@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{164}@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{40b}
@section Machine Code Insertions
@geindex Machine Code insertions
-Package @cite{Machine_Code} provides machine code support as described
+Package @code{Machine_Code} provides machine code support as described
in the Ada Reference Manual in two separate forms:
instruction, see the section on Extended Asm in
@cite{Using_the_GNU_Compiler_Collection_(GCC)}.
-Calls to the function @cite{Asm} and the procedure @cite{Asm} have identical
+Calls to the function @code{Asm} and the procedure @code{Asm} have identical
semantic restrictions and effects as described below. Both are provided so
that the procedure call can be used as a statement, and the function call
can be used to form a code_statement.
-Consider this C @cite{asm} instruction:
+Consider this C @code{asm} instruction:
@example
asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
My_Float'Asm_Input ("f", angle));
@end example
-The first argument to @cite{Asm} is the assembler template, and is
+The first argument to @code{Asm} is the assembler template, and is
identical to what is used in GNU C. This string must be a static
expression. The second argument is the output operand list. It is
-either a single @cite{Asm_Output} attribute reference, or a list of such
+either a single @code{Asm_Output} attribute reference, or a list of such
references enclosed in parentheses (technically an array aggregate of
such references).
-The @cite{Asm_Output} attribute denotes a function that takes two
+The @code{Asm_Output} attribute denotes a function that takes two
parameters. The first is a string, the second is the name of a variable
of the type designated by the attribute prefix. The first (string)
argument is required to be a static expression and designates the
result. The possible values for constraint are the same as those used in
the RTL, and are dependent on the configuration file used to build the
GCC back end. If there are no output operands, then this argument may
-either be omitted, or explicitly given as @cite{No_Output_Operands}.
+either be omitted, or explicitly given as @code{No_Output_Operands}.
No support is provided for GNU C's symbolic names for output parameters.
The second argument of @code{my_float'Asm_Output} functions as
-though it were an @cite{out} parameter, which is a little curious, but
+though it were an @code{out} parameter, which is a little curious, but
all names have the form of expressions, so there is no syntactic
irregularity, even though normally functions would not be permitted
-@cite{out} parameters. The third argument is the list of input
-operands. It is either a single @cite{Asm_Input} attribute reference, or
+@code{out} parameters. The third argument is the list of input
+operands. It is either a single @code{Asm_Input} attribute reference, or
a list of such references enclosed in parentheses (technically an array
aggregate of such references).
-The @cite{Asm_Input} attribute denotes a function that takes two
+The @code{Asm_Input} attribute denotes a function that takes two
parameters. The first is a string, the second is an expression of the
type designated by the prefix. The first (string) argument is required
to be a static expression, and is the constraint for the parameter,
No support is provided for GNU C's symbolic names for input parameters.
If there are no input operands, this argument may either be omitted, or
-explicitly given as @cite{No_Input_Operands}. The fourth argument, not
+explicitly given as @code{No_Input_Operands}. The fourth argument, not
present in the above example, is a list of register names, called the
@emph{clobber} argument. This argument, if given, must be a static string
expression, and is a space or comma separated list of names of registers
-that must be considered destroyed as a result of the @cite{Asm} call. If
+that must be considered destroyed as a result of the @code{Asm} call. If
this argument is the null string (the default value), then the code
generator assumes that no additional registers are destroyed.
-In addition to registers, the special clobbers @cite{memory} and
-@cite{cc} as described in the GNU C docs are both supported.
+In addition to registers, the special clobbers @code{memory} and
+@code{cc} as described in the GNU C docs are both supported.
The fifth argument, not present in the above example, called the
-@emph{volatile} argument, is by default @cite{False}. It can be set to
-the literal value @cite{True} to indicate to the code generator that all
+@emph{volatile} argument, is by default @code{False}. It can be set to
+the literal value @code{True} to indicate to the code generator that all
optimizations with respect to the instruction specified should be
suppressed, and in particular an instruction that has outputs
will still be generated, even if none of the outputs are
that is missing either input or output operands or to avoid unwanted
optimizations. A warning is generated if this advice is not followed.
-No support is provided for GNU C's @cite{asm goto} feature.
+No support is provided for GNU C's @code{asm goto} feature.
-The @cite{Asm} subprograms may be used in two ways. First the procedure
+The @code{Asm} subprograms may be used in two ways. First the procedure
forms can be used anywhere a procedure call would be valid, and
correspond to what the RM calls 'intrinsic' routines. Such calls can
be used to intersperse machine instructions with other Ada statements.
Second, the function forms, which return a dummy value of the limited
-private type @cite{Asm_Insn}, can be used in code statements, and indeed
+private type @code{Asm_Insn}, can be used in code statements, and indeed
this is the only context where such calls are allowed. Code statements
appear as aggregates of the form:
Typically the form using intrinsic procedure calls is more convenient
and more flexible. The code statement form is provided to meet the RM
suggestion that such a facility should be made available. The following
-is the exact syntax of the call to @cite{Asm}. As usual, if named notation
+is the exact syntax of the call to @code{Asm}. As usual, if named notation
is used, the arguments may be given in arbitrary order, following the
normal rules for use of positional and named arguments:
SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
@end example
-The identifiers @cite{No_Input_Operands} and @cite{No_Output_Operands}
-are declared in the package @cite{Machine_Code} and must be referenced
+The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
+are declared in the package @code{Machine_Code} and must be referenced
according to normal visibility rules. In particular if there is no
-@cite{use} clause for this package, then appropriate package name
+@code{use} clause for this package, then appropriate package name
qualification is required.
@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{402}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{403}
+@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{40c}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{40d}
@section GNAT Implementation of Tasking
@end menu
@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking
-@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{404}@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{405}
+@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{40e}@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{40f}
@subsection Mapping Ada Tasks onto the Underlying Kernel Threads
@geindex Forking a new process
@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking
-@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{406}@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{407}
+@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{410}@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{411}
@subsection Ensuring Compliance with the Real-Time Annex
complications when it comes to respecting the scheduling semantics
specified in the real-time annex (Annex D).
-For instance the Annex D requirement for the @cite{FIFO_Within_Priorities}
+For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
scheduling policy states:
@quotation
@c Support_for_Locking_Policies
@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking
-@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{408}
+@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{412}
@subsection Support for Locking Policies
This section specifies which policies specified by pragma Locking_Policy
are supported on which platforms.
-GNAT supports the standard @cite{Ceiling_Locking} policy, and the
-implementation defined @cite{Inheritance_Locking} and
-@cite{Concurrent_Readers_Locking} policies.
+GNAT supports the standard @code{Ceiling_Locking} policy, and the
+implementation defined @code{Inheritance_Locking} and
+@code{Concurrent_Readers_Locking} policies.
-@cite{Ceiling_Locking} is supported on all platforms if the operating system
-supports it. In particular, @cite{Ceiling_Locking} is not supported on
+@code{Ceiling_Locking} is supported on all platforms if the operating system
+supports it. In particular, @code{Ceiling_Locking} is not supported on
VxWorks.
-@cite{Inheritance_Locking} is supported on
+@code{Inheritance_Locking} is supported on
Linux,
Darwin (Mac OS X),
LynxOS 178,
and VxWorks.
-@cite{Concurrent_Readers_Locking} is supported on Linux.
-
-Note that on Linux, @cite{Ceiling_Locking} requires the program to be running
-with root privileges. Otherwise, the policy is ignored.
+@code{Concurrent_Readers_Locking} is supported on Linux.
+
+Notes about @code{Ceiling_Locking} on Linux:
+If the process is running as 'root', ceiling locking is used.
+If the capabilities facility is installed
+("sudo apt-get --assume-yes install libcap-dev" on Ubuntu,
+for example),
+and the program is linked against that library
+("-largs -lcap"),
+and the executable file has the cap_sys_nice capability
+("sudo /sbin/setcap cap_sys_nice=ep executable_file_name"),
+then ceiling locking is used.
+Otherwise, the @code{Ceiling_Locking} policy is ignored.
@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{409}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{40a}
+@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{413}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{414}
@section GNAT Implementation of Shared Passive Packages
GNAT fully implements the
@geindex pragma Shared_Passive
pragma
-@cite{Shared_Passive} for
+@code{Shared_Passive} for
the purpose of designating shared passive packages.
This allows the use of passive partitions in the
context described in the Ada Reference Manual; i.e., for communication
@geindex SHARED_MEMORY_DIRECTORY environment variable
-The environment variable @cite{SHARED_MEMORY_DIRECTORY} should be
+The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
set to the directory to be used for these files.
The files in this directory
have names that correspond to their fully qualified names. For
end X;
@end example
-and the environment variable is set to @cite{/stemp/}, then the files created
+and the environment variable is set to @code{/stemp/}, then the files created
will have the names:
@example
the elaboration process, since elaboration of passive packages elaborates the
initial values, but does not create the files.
-The files are written using normal @cite{Stream_IO} access.
+The files are written using normal @code{Stream_IO} access.
If you want to be able
to communicate between programs or partitions running on different
architectures, then you should use the XDR versions of the stream attribute
except for OpenVMS.
@node Code Generation for Array Aggregates,The Size of Discriminated Records with Default Discriminants,GNAT Implementation of Shared Passive Packages,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{40b}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{40c}
+@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{415}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{416}
@section Code Generation for Array Aggregates
@end menu
@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates
-@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{40d}@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{40e}
+@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{417}@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{418}
@subsection Static constant aggregates with static bounds
@end example
@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates
-@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{40f}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{410}
+@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{419}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{41a}
@subsection Constant aggregates with unconstrained nominal types
In such cases the aggregate itself establishes the subtype, so that
-associations with @cite{others} cannot be used. GNAT determines the
+associations with @code{others} cannot be used. GNAT determines the
bounds for the actual subtype of the aggregate, and allocates the
aggregate statically as well. No code is generated for the following:
@end example
@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates
-@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{411}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{412}
+@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{41b}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{41c}
@subsection Aggregates with static bounds
@end example
@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates
-@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{413}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{414}
+@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{41e}
@subsection Aggregates with nonstatic bounds
compatible subtypes.
@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates
-@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{415}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{416}
+@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{41f}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{420}
@subsection Aggregates in assignment statements
that temporary will be copied onto the target.
@node The Size of Discriminated Records with Default Discriminants,Strict Conformance to the Ada Reference Manual,Code Generation for Array Aggregates,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{417}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{418}
+@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{421}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{422}
@section The Size of Discriminated Records with Default Discriminants
-If a discriminated type @cite{T} has discriminants with default values, it is
+If a discriminated type @code{T} has discriminants with default values, it is
possible to declare an object of this type without providing an explicit
constraint:
In order to support this behavior efficiently, an unconstrained object is
given the maximum size that any value of the type requires. In the case
-above, @cite{Word} has storage for the discriminant and for
-a @cite{String} of length 100.
+above, @code{Word} has storage for the discriminant and for
+a @code{String} of length 100.
It is important to note that unconstrained objects do not require dynamic
allocation. It would be an improper implementation to place on the heap those
components whose size depends on discriminants. (This improper implementation
-was used by some Ada83 compilers, where the @cite{Name} component above
+was used by some Ada83 compilers, where the @code{Name} component above
would have
been stored as a pointer to a dynamic string). Following the principle that
dynamic storage management should never be introduced implicitly,
@end example
is flagged by the compiler with a warning:
-an attempt to create @cite{Too_Large} will raise @cite{Storage_Error},
-because the required size includes @cite{Positive'Last}
+an attempt to create @code{Too_Large} will raise @code{Storage_Error},
+because the required size includes @code{Positive'Last}
bytes. As the first example indicates, the proper approach is to declare an
index type of 'reasonable' range so that unconstrained objects are not too
large.
-One final wrinkle: if the object is declared to be @cite{aliased}, or if it is
+One final wrinkle: if the object is declared to be @code{aliased}, or if it is
created in the heap by means of an allocator, then it is @emph{not}
unconstrained:
it is constrained by the default values of the discriminants, and those values
remain invariant.
@node Strict Conformance to the Ada Reference Manual,,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features
-@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{419}@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{41a}
+@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{423}@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{424}
@section Strict Conformance to the Ada Reference Manual
(@emph{-fstack-check}).
Note that the result of a floating point arithmetic operation in overflow and
-invalid situations, when the @cite{Machine_Overflows} attribute of the result
-type is @cite{False}, is to generate IEEE NaN and infinite values. This is the
+invalid situations, when the @code{Machine_Overflows} attribute of the result
+type is @code{False}, is to generate IEEE NaN and infinite values. This is the
case for machines compliant with the IEEE floating-point standard, but on
machines that are not fully compliant with this standard, such as Alpha, the
@emph{-mieee} compiler flag must be used for achieving IEEE confirming
infinite and NaN values are properly generated.
@node Implementation of Ada 2012 Features,Obsolescent Features,Implementation of Specific Ada Features,Top
-@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{41b}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{41c}
+@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{425}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{426}
@chapter Implementation of Ada 2012 Features
Generally, these features are only
available if the @emph{-gnat12} (Ada 2012 features enabled) option is set,
which is the default behavior,
-or if the configuration pragma @cite{Ada_2012} is used.
+or if the configuration pragma @code{Ada_2012} is used.
However, new pragmas, attributes, and restrictions are
unconditionally available, since the Ada 95 standard allows the addition of
@emph{AI-0163 Pragmas in place of null (2010-07-01)}
A statement sequence may be composed entirely of pragmas. It is no longer
-necessary to add a dummy @cite{null} statement to make the sequence legal.
+necessary to add a dummy @code{null} statement to make the sequence legal.
RM References: 2.08 (7) 2.08 (16)
@end itemize
@end itemize
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx}
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx}
@headitem
Supported Aspect
@item
-@cite{Ada_2005}
+@code{Ada_2005}
@tab
@item
-@cite{Ada_2012}
+@code{Ada_2012}
@tab
@item
-@cite{Address}
+@code{Address}
@tab
@item
-@cite{Alignment}
+@code{Alignment}
@tab
@item
-@cite{Atomic}
+@code{Atomic}
@tab
@item
-@cite{Atomic_Components}
+@code{Atomic_Components}
@tab
@item
-@cite{Bit_Order}
+@code{Bit_Order}
@tab
@item
-@cite{Component_Size}
+@code{Component_Size}
@tab
@item
-@cite{Contract_Cases}
+@code{Contract_Cases}
@tab
@item
-@cite{Discard_Names}
+@code{Discard_Names}
@tab
@item
-@cite{External_Tag}
+@code{External_Tag}
@tab
@item
-@cite{Favor_Top_Level}
+@code{Favor_Top_Level}
@tab
@item
-@cite{Inline}
+@code{Inline}
@tab
@item
-@cite{Inline_Always}
+@code{Inline_Always}
@tab
@item
-@cite{Invariant}
+@code{Invariant}
@tab
@item
-@cite{Machine_Radix}
+@code{Machine_Radix}
@tab
@item
-@cite{No_Return}
+@code{No_Return}
@tab
@item
-@cite{Object_Size}
+@code{Object_Size}
@tab
@item
-@cite{Pack}
+@code{Pack}
@tab
@item
-@cite{Persistent_BSS}
+@code{Persistent_BSS}
@tab
@item
-@cite{Post}
+@code{Post}
@tab
@item
-@cite{Pre}
+@code{Pre}
@tab
@item
-@cite{Predicate}
+@code{Predicate}
@tab
@item
-@cite{Preelaborable_Initialization}
+@code{Preelaborable_Initialization}
@tab
@item
-@cite{Pure_Function}
+@code{Pure_Function}
@tab
@item
-@cite{Remote_Access_Type}
+@code{Remote_Access_Type}
@tab
@item
-@cite{Shared}
+@code{Shared}
@tab
@item
-@cite{Size}
+@code{Size}
@tab
@item
-@cite{Storage_Pool}
+@code{Storage_Pool}
@tab
@item
-@cite{Storage_Size}
+@code{Storage_Size}
@tab
@item
-@cite{Stream_Size}
+@code{Stream_Size}
@tab
@item
-@cite{Suppress}
+@code{Suppress}
@tab
@item
-@cite{Suppress_Debug_Info}
+@code{Suppress_Debug_Info}
@tab
@item
-@cite{Test_Case}
+@code{Test_Case}
@tab
@item
-@cite{Thread_Local_Storage}
+@code{Thread_Local_Storage}
@tab
@item
-@cite{Type_Invariant}
+@code{Type_Invariant}
@tab
@item
-@cite{Unchecked_Union}
+@code{Unchecked_Union}
@tab
@item
-@cite{Universal_Aliasing}
+@code{Universal_Aliasing}
@tab
@item
-@cite{Unmodified}
+@code{Unmodified}
@tab
@item
-@cite{Unreferenced}
+@code{Unreferenced}
@tab
@item
-@cite{Unreferenced_Objects}
+@code{Unreferenced_Objects}
@tab
@item
-@cite{Unsuppress}
+@code{Unsuppress}
@tab
@item
-@cite{Value_Size}
+@code{Value_Size}
@tab
@item
-@cite{Volatile}
+@code{Volatile}
@tab
@item
-@cite{Volatile_Components}
+@code{Volatile_Components}
@tab
@item
-@cite{Warnings}
+@code{Warnings}
@tab
@quotation
-Note that for aspects with an expression, e.g. @cite{Size}, the expression is
+Note that for aspects with an expression, e.g. @code{Size}, the expression is
treated like a default expression (visibility is analyzed at the point of
occurrence of the aspect, but evaluation of the expression occurs at the
freeze point of the entity involved).
@emph{AI-0003 Qualified expressions as names (2010-07-11)}
In Ada 2012, a qualified expression is considered to be syntactically a name,
-meaning that constructs such as @cite{A'(F(X)).B} are now legal. This is
+meaning that constructs such as @code{A'(F(X)).B} are now legal. This is
useful in disambiguating some cases of overloading.
RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3)
The wording in the RM implied that if you have a general access to a
constrained object, it could be used to modify the discriminants. This was
-obviously not intended. @cite{Constraint_Error} should be raised, and GNAT
+obviously not intended. @code{Constraint_Error} should be raised, and GNAT
has always done so in this situation.
RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2)
@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)}
From Ada 2005 on, soft hyphen is considered a non-graphic character, which
-means that it has a special name (@cite{SOFT_HYPHEN}) in conjunction with the
-@cite{Image} and @cite{Value} attributes for the character types. Strictly
+means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the
+@code{Image} and @code{Value} attributes for the character types. Strictly
speaking this is an inconsistency with Ada 95, but in practice the use of
these attributes is so obscure that it will not cause problems.
@itemize *
@item
-@emph{AI-0182 Additional forms for `Character'Value} (0000-00-00)`
+@emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)}
-This AI allows @cite{Character'Value} to accept the string @cite{'?'} where
-@cite{?} is any character including non-graphic control characters. GNAT has
+This AI allows @code{Character'Value} to accept the string @code{'?'} where
+@code{?} is any character including non-graphic control characters. GNAT has
always accepted such strings. It also allows strings such as
-@cite{HEX_00000041} to be accepted, but GNAT does not take advantage of this
-permission and raises @cite{Constraint_Error}, as is certainly still
+@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this
+permission and raises @code{Constraint_Error}, as is certainly still
permitted.
RM References: 3.05 (56/2)
@item
@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)}
-The function @cite{Ada.Tags.Type_Is_Abstract} returns @cite{True} if invoked
-with the tag of an abstract type, and @cite{False} otherwise.
+The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked
+with the tag of an abstract type, and @code{False} otherwise.
RM References: 3.09 (7.4/2) 3.09 (12.4/2)
@end itemize
@item
@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)}
-This AI confirms that an association of the form @cite{Indx => <>} in an
-array aggregate must raise @cite{Constraint_Error} if @cite{Indx}
+This AI confirms that an association of the form @code{Indx => <>} in an
+array aggregate must raise @code{Constraint_Error} if @code{Indx}
is out of range. The RM specified a range check on other associations, but
not when the value of the association was defaulted. GNAT has always inserted
a constraint check on the index value.
Equality of untagged record composes, so that the predefined equality for a
composite type that includes a component of some untagged record type
-@cite{R} uses the equality operation of @cite{R} (which may be user-defined
+@code{R} uses the equality operation of @code{R} (which may be user-defined
or predefined). This makes the behavior of untagged records identical to that
of tagged types in this respect.
The new syntax for iterating over arrays and containers is now implemented.
Iteration over containers is for now limited to read-only iterators. Only
-default iterators are supported, with the syntax: @cite{for Elem of C}.
+default iterators are supported, with the syntax: @code{for Elem of C}.
RM References: 5.05
@end itemize
@item
@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)}
-Null exclusion checks are not made for @cite{**out**} parameters when
+Null exclusion checks are not made for @code{out} parameters when
evaluating the actual parameters. GNAT has never generated these checks.
RM References: 6.04.01 (13)
@item
@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)}
-The implementation permissions for raising @cite{Constraint_Error} early on a function call
+The implementation permissions for raising @code{Constraint_Error} early on a function call
when it was clear an exception would be raised were over-permissive and allowed
mishandling of discriminants in some cases. GNAT did
not take advantage of these incorrect permissions in any case.
Requeue is permitted to a protected, synchronized or task interface primitive
providing it is known that the overriding operation is an entry. Otherwise
the requeue statement has the same effect as a procedure call. Use of pragma
-@cite{Implemented} provides a way to impose a static requirement on the
+@code{Implemented} provides a way to impose a static requirement on the
overriding operation by adhering to one of the implementation kinds: entry,
protected procedure or any of the above.
@item
@emph{AI-0201 Independence of atomic object components (2010-07-22)}
-If an Atomic object has a pragma @cite{Pack} or a @cite{Component_Size}
+If an Atomic object has a pragma @code{Pack} or a @code{Component_Size}
attribute, then individual components may not be addressable by independent
tasks. However, if the representation clause has no effect (is confirming),
then independence is not compromised. Furthermore, in GNAT, specification of
@item
@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)}
-This AI introduces the new pragmas @cite{Independent} and
-@cite{Independent_Components},
+This AI introduces the new pragmas @code{Independent} and
+@code{Independent_Components},
which control guaranteeing independence of access to objects and components.
The AI also requires independence not unaffected by confirming rep clauses.
@item
@emph{AI-0072 Task signalling using 'Terminated (0000-00-00)}
-This AI clarifies that task signalling for reading @cite{'Terminated} only
+This AI clarifies that task signalling for reading @code{'Terminated} only
occurs if the result is True. GNAT semantics has always been consistent with
this notion of task signalling.
This AI concerns giving names to various representation aspects, but the
practical effect is simply to make the use of duplicate
-@cite{Atomic[_Components]},
-@cite{Volatile[_Components]}, and
-@cite{Independent[_Components]} pragmas illegal, and GNAT
+@code{Atomic[_Components]},
+@code{Volatile[_Components]}, and
+@code{Independent[_Components]} pragmas illegal, and GNAT
now performs this required check.
RM References: 13.01 (8)
@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)}
It is now illegal to give an inappropriate component size or a pragma
-@cite{Pack} that attempts to change the component size in the case of atomic
+@code{Pack} that attempts to change the component size in the case of atomic
or aliased components. Previously GNAT ignored such an attempt with a
warning.
@item
@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)}
-The prefix of @cite{'Address} cannot statically denote a subprogram with
-convention @cite{Intrinsic}. The use of the @cite{Address} attribute raises
-@cite{Program_Error} if the prefix denotes a subprogram with convention
-@cite{Intrinsic}.
+The prefix of @code{'Address} cannot statically denote a subprogram with
+convention @code{Intrinsic}. The use of the @code{Address} attribute raises
+@code{Program_Error} if the prefix denotes a subprogram with convention
+@code{Intrinsic}.
RM References: 13.03 (11/1)
@end itemize
@emph{AI-0146 Type invariants (2009-09-21)}
Type invariants may be specified for private types using the aspect notation.
-Aspect @cite{Type_Invariant} may be specified for any private type,
-@cite{Type_Invariant'Class} can
+Aspect @code{Type_Invariant} may be specified for any private type,
+@code{Type_Invariant'Class} can
only be specified for tagged types, and is inherited by any descendent of the
tagged types. The invariant is a boolean expression that is tested for being
true in the following situations: conversions to the private type, object
[@strong{in}] @strong{out}
parameters and returned result on return from any primitive operation for
the type that is visible to a client.
-GNAT defines the synonyms @cite{Invariant} for @cite{Type_Invariant} and
-@cite{Invariant'Class} for @cite{Type_Invariant'Class}.
+GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and
+@code{Invariant'Class} for @code{Type_Invariant'Class}.
RM References: 13.03.03 (00)
@end itemize
@item
@emph{AI-0193 Alignment of allocators (2010-09-16)}
-This AI introduces a new attribute @cite{Max_Alignment_For_Allocation},
-analogous to @cite{Max_Size_In_Storage_Elements}, but for alignment instead
+This AI introduces a new attribute @code{Max_Alignment_For_Allocation},
+analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead
of size.
RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1)
@item
@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)}
-A new restriction @cite{No_Default_Stream_Attributes} prevents the use of any
+A new restriction @code{No_Default_Stream_Attributes} prevents the use of any
of the default stream attributes for elementary types. If this restriction is
in force, then it is necessary to provide explicit subprograms for any
stream attributes used.
@item
@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)}
-The @cite{Stream_Size} attribute returns the default number of bits in the
+The @code{Stream_Size} attribute returns the default number of bits in the
stream representation of the given type.
This value is not affected by the presence
of stream subprogram attributes for the type. GNAT has always implemented
@item
@emph{AI-0114 Classification of letters (0000-00-00)}
-The code points 170 (@cite{FEMININE ORDINAL INDICATOR}),
-181 (@cite{MICRO SIGN}), and
-186 (@cite{MASCULINE ORDINAL INDICATOR}) are technically considered
+The code points 170 (@code{FEMININE ORDINAL INDICATOR}),
+181 (@code{MICRO SIGN}), and
+186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered
lower case letters by Unicode.
However, they are not allowed in identifiers, and they
-return @cite{False} to @cite{Ada.Characters.Handling.Is_Letter/Is_Lower}.
+return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}.
This behavior is consistent with that defined in Ada 95.
RM References: A.03.02 (59) A.04.06 (7)
@item
@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)}
-Two new packages @cite{Ada.Wide_[Wide_]Characters.Handling} provide
-classification functions for @cite{Wide_Character} and
-@cite{Wide_Wide_Character}, as well as providing
-case folding routines for @cite{Wide_[Wide_]Character} and
-@cite{Wide_[Wide_]String}.
+Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide
+classification functions for @code{Wide_Character} and
+@code{Wide_Wide_Character}, as well as providing
+case folding routines for @code{Wide_[Wide_]Character} and
+@code{Wide_[Wide_]String}.
RM References: A.03.05 (0) A.03.06 (0)
@end itemize
@item
@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)}
-A new version of @cite{Find_Token} is added to all relevant string packages,
-with an extra parameter @cite{From}. Instead of starting at the first
+A new version of @code{Find_Token} is added to all relevant string packages,
+with an extra parameter @code{From}. Instead of starting at the first
character of the string, the search for a matching Token starts at the
-character indexed by the value of @cite{From}.
+character indexed by the value of @code{From}.
These procedures are available in all versions of Ada
but if used in versions earlier than Ada 2012 they will generate a warning
that an Ada 2012 subprogram is being used.
@emph{AI-0056 Index on null string returns zero (0000-00-00)}
The wording in the Ada 2005 RM implied an incompatible handling of the
-@cite{Index} functions, resulting in raising an exception instead of
+@code{Index} functions, resulting in raising an exception instead of
returning zero in some situations.
This was not intended and has been corrected.
GNAT always returned zero, and is thus consistent with this AI.
@item
@emph{AI-0137 String encoding package (2010-03-25)}
-The packages @cite{Ada.Strings.UTF_Encoding}, together with its child
-packages, @cite{Conversions}, @cite{Strings}, @cite{Wide_Strings},
-and @cite{Wide_Wide_Strings} have been
+The packages @code{Ada.Strings.UTF_Encoding}, together with its child
+packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings},
+and @code{Wide_Wide_Strings} have been
implemented. These packages (whose documentation can be found in the spec
files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads},
@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of
-@cite{String}, @cite{Wide_String}, and @cite{Wide_Wide_String}
+@code{String}, @code{Wide_String}, and @code{Wide_Wide_String}
values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and
UTF-16), as well as conversions between the different UTF encodings. With
-the exception of @cite{Wide_Wide_Strings}, these packages are available in
+the exception of @code{Wide_Wide_Strings}, these packages are available in
Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
-The @cite{Wide_Wide_Strings package}
+The @code{Wide_Wide_Strings} package
is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95
-mode since it uses @cite{Wide_Wide_Character}).
+mode since it uses @code{Wide_Wide_Character}).
RM References: A.04.11
@end itemize
The compiler is not required to support exporting an Ada subprogram with
convention C if there are parameters or a return type of an unconstrained
-array type (such as @cite{String}). GNAT allows such declarations but
+array type (such as @code{String}). GNAT allows such declarations but
generates warnings. It is possible, but complicated, to write the
corresponding C code and certainly such code would be specific to GNAT and
non-portable.
@item
@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)}
-It is clearly the intention that @cite{No_Task_Hierarchy} is intended to
+It is clearly the intention that @code{No_Task_Hierarchy} is intended to
forbid tasks declared locally within subprograms, or functions returning task
objects, and that is the implementation that GNAT has always provided.
However the language in the RM was not sufficiently clear on this point.
@item
@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)}
-The restriction @cite{No_Relative_Delays} forbids any calls to the subprogram
-@cite{Ada.Real_Time.Timing_Events.Set_Handler}.
+The restriction @code{No_Relative_Delays} forbids any calls to the subprogram
+@code{Ada.Real_Time.Timing_Events.Set_Handler}.
RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2)
@end itemize
@item
@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)}
-This AI introduces a new pragma @cite{Default_Storage_Pool}, which can be
+This AI introduces a new pragma @code{Default_Storage_Pool}, which can be
used to control storage pools globally.
In particular, you can force every access
type that is used for allocation (@strong{new}) to have an explicit storage pool,
@item
@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)}
-This AI introduces a new restriction @cite{No_Allocators_After_Elaboration},
+This AI introduces a new restriction @code{No_Allocators_After_Elaboration},
which says that no dynamic allocation will occur once elaboration is
completed.
In general this requires a run-time check, which is not required, and which
@item
@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)}
-A new package @cite{System.Multiprocessors} is added, together with the
-definition of pragma @cite{CPU} for controlling task affinity. A new no
-dependence restriction, on @cite{System.Multiprocessors.Dispatching_Domains},
+A new package @code{System.Multiprocessors} is added, together with the
+definition of pragma @code{CPU} for controlling task affinity. A new no
+dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains},
is added to the Ravenscar profile.
RM References: D.13.01 (4/2) D.16
@item
@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)}
-Restriction @cite{No_Anonymous_Allocators} prevents the use of allocators
+Restriction @code{No_Anonymous_Allocators} prevents the use of allocators
where the type of the returned value is an anonymous access type.
RM References: H.04 (8/1)
@end itemize
@node Obsolescent Features,Compatibility and Porting Guide,Implementation of Ada 2012 Features,Top
-@anchor{gnat_rm/obsolescent_features id1}@anchor{41d}@anchor{gnat_rm/obsolescent_features doc}@anchor{41e}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{15}
+@anchor{gnat_rm/obsolescent_features id1}@anchor{427}@anchor{gnat_rm/obsolescent_features doc}@anchor{428}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{15}
@chapter Obsolescent Features
@end menu
@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features
-@anchor{gnat_rm/obsolescent_features id2}@anchor{41f}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{420}
+@anchor{gnat_rm/obsolescent_features id2}@anchor{429}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{42a}
@section pragma No_Run_Time
-The pragma @cite{No_Run_Time} is used to achieve an affect similar
+The pragma @code{No_Run_Time} is used to achieve an affect similar
to the use of the "Zero Foot Print" configurable run time, but without
requiring a specially configured run time. The result of using this
pragma, which must be used for all units in a partition, is to restrict
includes just those features that are to be made accessible.
@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features
-@anchor{gnat_rm/obsolescent_features id3}@anchor{421}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{422}
+@anchor{gnat_rm/obsolescent_features id3}@anchor{42b}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{42c}
@section pragma Ravenscar
-The pragma @cite{Ravenscar} has exactly the same effect as pragma
-@cite{Profile (Ravenscar)}. The latter usage is preferred since it
+The pragma @code{Ravenscar} has exactly the same effect as pragma
+@code{Profile (Ravenscar)}. The latter usage is preferred since it
is part of the new Ada 2005 standard.
@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features
-@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{423}@anchor{gnat_rm/obsolescent_features id4}@anchor{424}
+@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{42d}@anchor{gnat_rm/obsolescent_features id4}@anchor{42e}
@section pragma Restricted_Run_Time
-The pragma @cite{Restricted_Run_Time} has exactly the same effect as
-pragma @cite{Profile (Restricted)}. The latter usage is
-preferred since the Ada 2005 pragma @cite{Profile} is intended for
+The pragma @code{Restricted_Run_Time} has exactly the same effect as
+pragma @code{Profile (Restricted)}. The latter usage is
+preferred since the Ada 2005 pragma @code{Profile} is intended for
this kind of implementation dependent addition.
@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features
-@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{425}@anchor{gnat_rm/obsolescent_features id5}@anchor{426}
+@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{42f}@anchor{gnat_rm/obsolescent_features id5}@anchor{430}
@section pragma Task_Info
-The functionality provided by pragma @cite{Task_Info} is now part of the
-Ada language. The @cite{CPU} aspect and the package
-@cite{System.Multiprocessors} offer a less system-dependent way to specify
+The functionality provided by pragma @code{Task_Info} is now part of the
+Ada language. The @code{CPU} aspect and the package
+@code{System.Multiprocessors} offer a less system-dependent way to specify
task affinity or to query the number of processsors.
Syntax
@end example
This pragma appears within a task definition (like pragma
-@cite{Priority}) and applies to the task in which it appears. The
-argument must be of type @cite{System.Task_Info.Task_Info_Type}.
-The @cite{Task_Info} pragma provides system dependent control over
+@code{Priority}) and applies to the task in which it appears. The
+argument must be of type @code{System.Task_Info.Task_Info_Type}.
+The @code{Task_Info} pragma provides system dependent control over
aspects of tasking implementation, for example, the ability to map
tasks to specific processors. For details on the facilities available
for the version of GNAT that you are using, see the documentation
library.
@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features
-@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{427}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{428}
+@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{431}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{432}
@section package System.Task_Info (@code{s-tasinf.ads})
This package provides target dependent functionality that is used
-to support the @cite{Task_Info} pragma. The predefined Ada package
-@cite{System.Multiprocessors} and the @cite{CPU} aspect now provide a
-standard replacement for GNAT's @cite{Task_Info} functionality.
+to support the @code{Task_Info} pragma. The predefined Ada package
+@code{System.Multiprocessors} and the @code{CPU} aspect now provide a
+standard replacement for GNAT's @code{Task_Info} functionality.
@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top
-@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{16}@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{429}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{42a}
+@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{16}@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{433}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{434}
@chapter Compatibility and Porting Guide
@end menu
@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide
-@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{42b}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{42c}
+@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{435}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{436}
@section Writing Portable Fixed-Point Declarations
The Ada Reference Manual gives an implementation freedom to choose bounds
-that are narrower by @cite{Small} from the given bounds.
+that are narrower by @code{Small} from the given bounds.
For example, if we write
@example
First, why does this freedom exist, and why would an implementation
take advantage of it? To answer this, take a closer look at the type
-declaration for @cite{F1} above. If the compiler uses the given bounds,
+declaration for @code{F1} above. If the compiler uses the given bounds,
it would need 9 bits to hold the largest positive value (and typically
that means 16 bits on all machines). But if the implementation chooses
the +127.0 bound then it can fit values of the type in 8 bits.
out that the narrower range will allow storage in a smaller machine unit,
@item
-those that will narrow only if forced to by a @cite{'Size} clause, and
+those that will narrow only if forced to by a @code{'Size} clause, and
@item
those that will never narrow.
the categories (a), (b) or (c) above.
So, how do you get the compiler to do what you want? The answer is give the
-actual bounds you want, and then use a @cite{'Small} clause and a
-@cite{'Size} clause to absolutely pin down what the compiler does.
-E.g., for @cite{F2} above, we will write:
+actual bounds you want, and then use a @code{'Small} clause and a
+@code{'Size} clause to absolutely pin down what the compiler does.
+E.g., for @code{F2} above, we will write:
@example
My_Small : constant := 2.0**(-15);
types will be portable.
@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide
-@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{42d}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{42e}
+@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{437}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{438}
@section Compatibility with Ada 83
@end menu
@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83
-@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{42f}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{430}
+@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{439}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{43a}
@subsection Legal Ada 83 programs that are illegal in Ada 95
@emph{Character literals}
Some uses of character literals are ambiguous. Since Ada 95 has introduced
-@cite{Wide_Character} as a new predefined character type, some uses of
+@code{Wide_Character} as a new predefined character type, some uses of
character literals that were legal in Ada 83 are illegal in Ada 95.
For example:
@end example
The problem is that 'A' and 'Z' could be from either
-@cite{Character} or @cite{Wide_Character}. The simplest correction
+@code{Character} or @code{Wide_Character}. The simplest correction
is to make the type explicit; e.g.:
@example
@item
@emph{New reserved words}
-The identifiers @cite{abstract}, @cite{aliased}, @cite{protected},
-@cite{requeue}, @cite{tagged}, and @cite{until} are reserved in Ada 95.
+The identifiers @code{abstract}, @code{aliased}, @code{protected},
+@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95.
Existing Ada 83 code using any of these identifiers must be edited to
use some alternative name.
body if it is empty, or, if it is non-empty, introduce a dummy declaration
into the spec that makes the body required. One approach is to add a private
part to the package declaration (if necessary), and define a parameterless
-procedure called @cite{Requires_Body}, which must then be given a dummy
+procedure called @code{Requires_Body}, which must then be given a dummy
procedure body in the package body, which then becomes required.
Another approach (assuming that this does not introduce elaboration
-circularities) is to add an @cite{Elaborate_Body} pragma to the package spec,
+circularities) is to add an @code{Elaborate_Body} pragma to the package spec,
since one effect of this pragma is to require the presence of a package body.
@item
@emph{Numeric_Error is the same exception as Constraint_Error}
-In Ada 95, the exception @cite{Numeric_Error} is a renaming of @cite{Constraint_Error}.
+In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}.
This means that it is illegal to have separate exception handlers for
the two exceptions. The fix is simply to remove the handler for the
-@cite{Numeric_Error} case (since even in Ada 83, a compiler was free to raise
-@cite{Constraint_Error} in place of @cite{Numeric_Error} in all cases).
+@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise
+@code{Constraint_Error} in place of @code{Numeric_Error} in all cases).
@item
@emph{Indefinite subtypes in generics}
-In Ada 83, it was permissible to pass an indefinite type (e.g, @cite{String})
+In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String})
as the actual for a generic formal private type, but then the instantiation
would be illegal if there were any instances of declarations of variables
of this type in the generic body. In Ada 95, to avoid this clear violation
of the methodological principle known as the 'contract model',
the generic declaration explicitly indicates whether
or not such instantiations are permitted. If a generic formal parameter
-has explicit unknown discriminants, indicated by using @cite{(<>)} after the
+has explicit unknown discriminants, indicated by using @code{(<>)} after the
subtype name, then it can be instantiated with indefinite types, but no
stand-alone variables can be declared of this type. Any attempt to declare
such a variable will result in an illegality at the time the generic is
-declared. If the @cite{(<>)} notation is not used, then it is illegal
+declared. If the @code{(<>)} notation is not used, then it is illegal
to instantiate the generic with an indefinite type.
This is the potential incompatibility issue when porting Ada 83 code to Ada 95.
It will show up as a compile time error, and
-the fix is usually simply to add the @cite{(<>)} to the generic declaration.
+the fix is usually simply to add the @code{(<>)} to the generic declaration.
@end itemize
@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83
-@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{431}@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{432}
+@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{43b}@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{43c}
@subsection More deterministic semantics
@end itemize
@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83
-@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{433}@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{434}
+@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{43d}@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{43e}
@subsection Changed semantics
Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not
possible in Ada 83. Fortunately this is extremely rare, but the one
situation that you should be alert to is the change in the predefined type
-@cite{Character} from 7-bit ASCII to 8-bit Latin-1.
+@code{Character} from 7-bit ASCII to 8-bit Latin-1.
@quotation
@itemize *
@item
-@emph{Range of type `Character`}
+@emph{Range of type `@w{`}Character`@w{`}}
-The range of @cite{Standard.Character} is now the full 256 characters
+The range of @code{Standard.Character} is now the full 256 characters
of Latin-1, whereas in most Ada 83 implementations it was restricted
to 128 characters. Although some of the effects of
this change will be manifest in compile-time rejection of legal
Ada 83 programs it is possible for a working Ada 83 program to have
a different effect in Ada 95, one that was not permitted in Ada 83.
As an example, the expression
-@cite{Character'Pos(Character'Last)} returned @cite{127} in Ada 83 and now
-delivers @cite{255} as its value.
+@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now
+delivers @code{255} as its value.
In general, you should look at the logic of any
character-processing Ada 83 program and see whether it needs to be adapted
to work correctly with Latin-1. Note that the predefined Ada 95 API has a
@end itemize
@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83
-@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{435}@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{436}
+@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{43f}@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{440}
@subsection Other language compatibility issues
as identifiers as in Ada 83. However,
in practice, it is usually advisable to make the necessary modifications
to the program to remove the need for using this switch.
-See the @cite{Compiling Different Versions of Ada} section in
+See the @code{Compiling Different Versions of Ada} section in
the @cite{GNAT User's Guide}.
@item
compilers are allowed, but not required, to implement these missing
elements. In contrast with some other compilers, GNAT implements all
such pragmas and attributes, eliminating this compatibility concern. These
-include @cite{pragma Interface} and the floating point type attributes
-(@cite{Emax}, @cite{Mantissa}, etc.), among other items.
+include @code{pragma Interface} and the floating point type attributes
+(@code{Emax}, @code{Mantissa}, etc.), among other items.
@end itemize
@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide
-@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{437}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{438}
+@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{441}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{442}
@section Compatibility between Ada 95 and Ada 2005
@item
@emph{New reserved words.}
-The words @cite{interface}, @cite{overriding} and @cite{synchronized} are
+The words @code{interface}, @code{overriding} and @code{synchronized} are
reserved in Ada 2005.
A pre-Ada 2005 program that uses any of these as an identifier will be
illegal.
@emph{New declarations in predefined packages.}
A number of packages in the predefined environment contain new declarations:
-@cite{Ada.Exceptions}, @cite{Ada.Real_Time}, @cite{Ada.Strings},
-@cite{Ada.Strings.Fixed}, @cite{Ada.Strings.Bounded},
-@cite{Ada.Strings.Unbounded}, @cite{Ada.Strings.Wide_Fixed},
-@cite{Ada.Strings.Wide_Bounded}, @cite{Ada.Strings.Wide_Unbounded},
-@cite{Ada.Tags}, @cite{Ada.Text_IO}, and @cite{Interfaces.C}.
-If an Ada 95 program does a @cite{with} and @cite{use} of any of these
+@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings},
+@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded},
+@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed},
+@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded},
+@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}.
+If an Ada 95 program does a @code{with} and @code{use} of any of these
packages, the new declarations may cause name clashes.
@item
are now ambiguous.
The ambiguity may be resolved either by applying a type conversion to the
expression, or by explicitly invoking the operation from package
-@cite{Standard}.
+@code{Standard}.
@item
@emph{Return-by-reference types.}
@end itemize
@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide
-@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{439}@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{43a}
+@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{443}@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{444}
@section Implementation-dependent characteristics
@end menu
@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics
-@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{43b}@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{43c}
+@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{445}@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{446}
@subsection Implementation-defined pragmas
Ada compilers are allowed to supplement the language-defined pragmas, and
these are a potential source of non-portability. All GNAT-defined pragmas
-are described in the @cite{Implementation Defined Pragmas} chapter of the
-@cite{GNAT Reference Manual}, and these include several that are specifically
+are described in @ref{7,,Implementation Defined Pragmas},
+and these include several that are specifically
intended to correspond to other vendors' Ada 83 pragmas.
-For migrating from VADS, the pragma @cite{Use_VADS_Size} may be useful.
+For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
For compatibility with HP Ada 83, GNAT supplies the pragmas
-@cite{Extend_System}, @cite{Ident}, @cite{Inline_Generic},
-@cite{Interface_Name}, @cite{Passive}, @cite{Suppress_All},
-and @cite{Volatile}.
-Other relevant pragmas include @cite{External} and @cite{Link_With}.
+@code{Extend_System}, @code{Ident}, @code{Inline_Generic},
+@code{Interface_Name}, @code{Passive}, @code{Suppress_All},
+and @code{Volatile}.
+Other relevant pragmas include @code{External} and @code{Link_With}.
Some vendor-specific
-Ada 83 pragmas (@cite{Share_Generic}, @cite{Subtitle}, and @cite{Title}) are
+Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are
recognized, thus
avoiding compiler rejection of units that contain such pragmas; they are not
relevant in a GNAT context and hence are not otherwise implemented.
@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics
-@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{43d}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{43e}
+@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{447}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{448}
@subsection Implementation-defined attributes
Analogous to pragmas, the set of attributes may be extended by an
implementation. All GNAT-defined attributes are described in
-@cite{Implementation Defined Attributes} section of the
-@cite{GNAT Reference Manual}, and these include several that are specifically intended
+@ref{8,,Implementation Defined Attributes},
+and these include several that are specifically intended
to correspond to other vendors' Ada 83 attributes. For migrating from VADS,
-the attribute @cite{VADS_Size} may be useful. For compatibility with HP
-Ada 83, GNAT supplies the attributes @cite{Bit}, @cite{Machine_Size} and
-@cite{Type_Class}.
+the attribute @code{VADS_Size} may be useful. For compatibility with HP
+Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
+@code{Type_Class}.
@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics
-@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{43f}@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{440}
+@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{449}@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{44a}
@subsection Libraries
@end itemize
@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics
-@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{441}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{442}
+@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{44b}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{44c}
@subsection Elaboration order
to invoke a subprogram before its body has been elaborated, or to instantiate
a generic before the generic body has been elaborated. By default GNAT
attempts to choose a safe order (one that will not encounter access before
-elaboration problems) by implicitly inserting @cite{Elaborate} or
-@cite{Elaborate_All} pragmas where
+elaboration problems) by implicitly inserting @code{Elaborate} or
+@code{Elaborate_All} pragmas where
needed. However, this can lead to the creation of elaboration circularities
and a resulting rejection of the program by gnatbind. This issue is
-thoroughly described in the @cite{Elaboration Order Handling in GNAT} appendix
+thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix
in the @cite{GNAT User's Guide}.
In brief, there are several
ways to deal with this situation:
elaboration-time code into explicitly-invoked procedures
@item
-Constrain the elaboration order by including explicit @cite{Elaborate_Body} or
-@cite{Elaborate} pragmas, and then inhibit the generation of implicit
-@cite{Elaborate_All}
+Constrain the elaboration order by including explicit @code{Elaborate_Body} or
+@code{Elaborate} pragmas, and then inhibit the generation of implicit
+@code{Elaborate_All}
pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally
(by selectively suppressing elaboration checks via pragma
-@cite{Suppress(Elaboration_Check)} when it is safe to do so).
+@code{Suppress(Elaboration_Check)} when it is safe to do so).
@end itemize
@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics
-@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{443}@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{444}
+@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{44d}@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{44e}
@subsection Target-specific aspects
Ada 2005 and Ada 2012) are sometimes
incompatible with typical Ada 83 compiler practices regarding implicit
packing, the meaning of the Size attribute, and the size of access values.
-GNAT's approach to these issues is described in @ref{445,,Representation Clauses}.
+GNAT's approach to these issues is described in @ref{44f,,Representation Clauses}.
@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide
-@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{446}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{447}
+@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{451}
@section Compatibility with Other Ada Systems
@end itemize
@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide
-@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{445}@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{448}
+@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{44f}@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{452}
@section Representation Clauses
Reference Manuals as implementation advice that is followed by GNAT.
The problem will show up as an error
message rejecting the size clause. The fix is simply to provide
-the explicit pragma @cite{Pack}, or for more fine tuned control, provide
+the explicit pragma @code{Pack}, or for more fine tuned control, provide
a Component_Size clause.
@item
The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as
the minimal number of bits required to hold values of the type. For example,
-on a 32-bit machine, the size of @cite{Natural} will typically be 31 and not
+on a 32-bit machine, the size of @code{Natural} will typically be 31 and not
32 (since no sign bit is required). Some Ada 83 compilers gave 31, and
some 32 in this situation. This problem will usually show up as a compile
time error, but not always. It is a good idea to check all uses of the
@end itemize
@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide
-@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{449}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{44a}
+@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{453}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{454}
@section Compatibility with HP Ada 83
@end itemize
@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top
-@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{44b}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{44c}
+@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{455}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{456}
@chapter GNU Free Documentation License
@copying
@quotation
-GNAT User's Guide for Native Platforms , Apr 25, 2017
+GNAT User's Guide for Native Platforms , Sep 08, 2017
AdaCore
* Naming Conventions for GNAT Source Files::
* Getting Internal Debugging Information::
* Stack Traceback::
+* Pretty-Printers for the GNAT runtime::
Stack Traceback
@itemize -
@item
-The @cite{gnatname}, @cite{gnatkr}, and @cite{gnatchop} tools
+The @code{gnatname}, @code{gnatkr}, and @code{gnatchop} tools
@item
@ref{14,,Configuration Pragmas}
@end itemize
@item
-The @cite{Compatibility and Porting Guide} appendix has been moved to the
+The @emph{Compatibility and Porting Guide} appendix has been moved to the
@cite{GNAT Reference Manual}. It now includes a section
-@cite{Writing Portable Fixed-Point Declarations} which was previously
+@emph{Writing Portable Fixed-Point Declarations} which was previously
a separate chapter in the @cite{GNAT User's Guide}.
@end itemize
@itemize *
@item
-@cite{Functions}, @cite{utility program names}, @cite{standard names},
-and @cite{classes}.
+@code{Functions}, @code{utility program names}, @code{standard names},
+and @code{classes}.
@item
-@cite{Option flags}
+@code{Option flags}
@item
@code{File names}
@item
-@cite{Variables}
+@code{Variables}
@item
@emph{Emphasis}
All appropriate object files must be linked to produce an executable.
@end itemize
-All three steps are most commonly handled by using the @emph{gnatmake}
+All three steps are most commonly handled by using the @code{gnatmake}
utility program that, given the name of the main program, automatically
performs the necessary compilation, binding and linking steps.
extension is @code{ads} for a
spec and @code{adb} for a body.
You can override this default file naming convention by use of the
-special pragma @cite{Source_File_Name} (for further information please
+special pragma @code{Source_File_Name} (for further information please
see @ref{35,,Using Other File Names}).
Alternatively, if you want to rename your files according to this default
convention, which is probably more convenient if you will be using GNAT
-for all your compilations, then the @cite{gnatchop} utility
+for all your compilations, then the @code{gnatchop} utility
can be used to generate correctly-named source files
(see @ref{36,,Renaming Files with gnatchop}).
-You can compile the program using the following command (@cite{$} is used
+You can compile the program using the following command (@code{$} is used
as the command prompt in the examples in this document):
@example
$ gcc -c hello.adb
@end example
-@emph{gcc} is the command used to run the compiler. This compiler is
+@code{gcc} is the command used to run the compiler. This compiler is
capable of compiling programs in several languages, including Ada and
C. It assumes that you have given it an Ada program if the file extension is
either @code{.ads} or @code{.adb}, and it will then call
the GNAT compiler to compile the specified file.
-The @code{-c} switch is required. It tells @emph{gcc} to only do a
-compilation. (For C programs, @emph{gcc} can also do linking, but this
+The @code{-c} switch is required. It tells @code{gcc} to only do a
+compilation. (For C programs, @code{gcc} can also do linking, but this
capability is not used directly for Ada programs, so the @code{-c}
switch must always be present.)
which contains additional information used to check
that an Ada program is consistent.
To build an executable file,
-use @cite{gnatbind} to bind the program
-and @emph{gnatlink} to link it. The
-argument to both @cite{gnatbind} and @emph{gnatlink} is the name of the
+use @code{gnatbind} to bind the program
+and @code{gnatlink} to link it. The
+argument to both @code{gnatbind} and @code{gnatlink} is the name of the
@code{ALI} file, but the default extension of @code{.ali} can
be omitted. This means that in the most common case, the argument
is simply the name of the main program:
$ gnatlink hello
@end example
-A simpler method of carrying out these steps is to use @emph{gnatmake},
+A simpler method of carrying out these steps is to use @code{gnatmake},
a master program that invokes all the required
compilation, binding and linking tools in the correct order. In particular,
-@emph{gnatmake} automatically recompiles any sources that have been
+@code{gnatmake} automatically recompiles any sources that have been
modified since they were last compiled, or sources that depend
on such modified sources, so that 'version skew' is avoided.
-@geindex Version skew (avoided by *gnatmake*)
+@geindex Version skew (avoided by `@w{`}gnatmake`@w{`})
@example
$ gnatmake hello.adb
@item @emph{greetings.ads}
-spec of package @cite{Greetings}
+spec of package @code{Greetings}
@item @emph{greetings.adb}
-body of package @cite{Greetings}
+body of package @code{Greetings}
@item @emph{gmain.adb}
Although the compilation can be done in separate steps as in the
above example, in practice it is almost always more convenient
-to use the @emph{gnatmake} tool. All you need to know in this case
+to use the @code{gnatmake} tool. All you need to know in this case
is the name of the main program's source file. The effect of the above four
commands can be achieved with a single one:
$ gnatmake gmain.adb
@end example
-In the next section we discuss the advantages of using @emph{gnatmake} in
+In the next section we discuss the advantages of using @code{gnatmake} in
more detail.
@node Using the gnatmake Utility,,Running a Program with Multiple Units,Getting Started with GNAT
@anchor{gnat_ugn/getting_started_with_gnat using-the-gnatmake-utility}@anchor{39}@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{3a}
-@section Using the @emph{gnatmake} Utility
+@section Using the @code{gnatmake} Utility
If you work on a program by compiling single components at a time using
-@emph{gcc}, you typically keep track of the units you modify. In order to
+@code{gcc}, you typically keep track of the units you modify. In order to
build a consistent system, you compile not only these units, but also any
units that depend on the units you have modified.
For example, in the preceding case,
@code{greetings.adb} and @code{gmain.adb}, because both files contain
units that depend on @code{greetings.ads}.
-@emph{gnatbind} will warn you if you forget one of these compilation
+@code{gnatbind} will warn you if you forget one of these compilation
steps, so that it is impossible to generate an inconsistent program as a
result of forgetting to do a compilation. Nevertheless it is tedious and
error-prone to keep track of dependencies among units.
sure that the makefile is kept up-to-date manually, which is also an
error-prone process.
-The @emph{gnatmake} utility takes care of these details automatically.
+The @code{gnatmake} utility takes care of these details automatically.
Invoke it using either one of the following forms:
@example
@end example
The argument is the name of the file containing the main program;
-you may omit the extension. @emph{gnatmake}
+you may omit the extension. @code{gnatmake}
examines the environment, automatically recompiles any files that need
recompiling, and binds and links the resulting set of object files,
generating the executable file, @code{gmain}.
In a large program, it
-can be extremely helpful to use @emph{gnatmake}, because working out by hand
+can be extremely helpful to use @code{gnatmake}, because working out by hand
what needs to be recompiled can be difficult.
-Note that @emph{gnatmake} takes into account all the Ada rules that
+Note that @code{gnatmake} takes into account all the Ada rules that
establish dependencies among units. These include dependencies that result
from inlining subprogram bodies, and from
generic instantiation. Unlike some other
-Ada make tools, @emph{gnatmake} does not rely on the dependencies that were
+Ada make tools, @code{gnatmake} does not rely on the dependencies that were
found by the compiler on a previous compilation, which may possibly
-be wrong when sources change. @emph{gnatmake} determines the exact set of
+be wrong when sources change. @code{gnatmake} determines the exact set of
dependencies from scratch each time it is run.
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
@quotation
-@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx}
+@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx}
@item
Character
@tab
-@cite{16#0B#}
+@code{16#0B#}
@item
@tab
-@cite{16#09#}
+@code{16#09#}
@item
@tab
-@cite{16#0D#}
+@code{16#0D#}
@item
@tab
-@cite{16#0A#}
+@code{16#0A#}
@item
@tab
-@cite{16#0C#}
+@code{16#0C#}
@end multitable
Source files are in standard text file format. In addition, GNAT will
recognize a wide variety of stream formats, in which the end of
physical lines is marked by any of the following sequences:
-@cite{LF}, @cite{CR}, @cite{CR-LF}, or @cite{LF-CR}. This is useful
+@code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful
in accommodating files that are imported from other operating systems.
@geindex End of source file; Source file@comma{} end
@geindex SUB (control character)
The end of a source file is normally represented by the physical end of
-file. However, the control character @cite{16#1A#} (@code{SUB}) is also
+file. However, the control character @code{16#1A#} (@code{SUB}) is also
recognized as signalling the end of the source file. Again, this is
provided for compatibility with other operating systems where this
code is used to represent the end of file.
Each file contains a single Ada compilation unit, including any pragmas
associated with the unit. For example, this means you must place a
-package declaration (a package @cite{spec}) and the corresponding body in
-separate files. An Ada @cite{compilation} (which is a sequence of
+package declaration (a package @emph{spec}) and the corresponding body in
+separate files. An Ada @emph{compilation} (which is a sequence of
compilation units) is represented using a sequence of files. Similarly,
you will place each subunit or child unit in a separate file.
@geindex Latin-1
The basic character set is Latin-1. This character set is defined by ISO
-standard 8859, part 1. The lower half (character codes @cite{16#00#}
-... @cite{16#7F#)} is identical to standard ASCII coding, but the upper
+standard 8859, part 1. The lower half (character codes @code{16#00#}
+... @code{16#7F#)} is identical to standard ASCII coding, but the upper
half is used to represent additional characters. These include extended letters
used by European languages, such as French accents, the vowels with umlauts
used in German, and the extra letter A-ring used in Swedish.
@geindex Ada.Characters.Latin_1
For a complete list of Latin-1 codes and their encodings, see the source
-file of library unit @cite{Ada.Characters.Latin_1} in file
+file of library unit @code{Ada.Characters.Latin_1} in file
@code{a-chlat1.ads}.
You may use any of these extended characters freely in character or
string literals. In addition, the extended characters that represent
ESC a b c d
@end example
-where @cite{a}, @cite{b}, @cite{c}, @cite{d} are the four hexadecimal
+where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ESC A345 is used to represent the wide character with code
-@cite{16#A345#}.
+@code{16#A345#}.
This scheme is compatible with use of the full Wide_Character set.
@item @emph{Upper-Half Coding}
@geindex Upper-Half Coding
-The wide character with encoding @cite{16#abcd#} where the upper bit is on
+The wide character with encoding @code{16#abcd#} where the upper bit is on
(in other words, 'a' is in the range 8-F) is represented as two bytes,
-@cite{16#ab#} and @cite{16#cd#}. The second byte cannot be a format control
+@code{16#ab#} and @code{16#cd#}. The second byte cannot be a format control
character, but is not required to be in the upper half. This method can
be also used for shift-JIS or EUC, where the internal coding matches the
external coding.
@geindex Shift JIS Coding
A wide character is represented by a two-character sequence,
-@cite{16#ab#} and
-@cite{16#cd#}, with the restrictions described for upper-half encoding as
+@code{16#ab#} and
+@code{16#cd#}, with the restrictions described for upper-half encoding as
described above. The internal character code is the corresponding JIS
character according to the standard algorithm for Shift-JIS
conversion. Only characters defined in the JIS code set table can be
@geindex EUC Coding
A wide character is represented by a two-character sequence
-@cite{16#ab#} and
-@cite{16#cd#}, with both characters being in the upper half. The internal
+@code{16#ab#} and
+@code{16#cd#}, with both characters being in the upper half. The internal
character code is the corresponding JIS character according to the EUC
encoding algorithm. Only characters defined in the JIS code set table
can be used with this encoding method.
is a one, two, or three byte sequence:
@example
-16#0000#-16#007f#: 2#0`xxxxxxx`#
-16#0080#-16#07ff#: 2#110`xxxxx`# 2#10`xxxxxx`#
-16#0800#-16#ffff#: 2#1110`xxxx`# 2#10`xxxxxx`# 2#10`xxxxxx`#
+16#0000#-16#007f#: 2#0xxxxxxx#
+16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
+16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
@end example
-where the @cite{xxx} bits correspond to the left-padded bits of the
+where the @code{xxx} bits correspond to the left-padded bits of the
16-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
[ " a b c d " ]
@end example
-where @cite{a}, @cite{b}, @cite{c}, @cite{d} are the four hexadecimal
+where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ['A345'] is used to represent the wide character with code
-@cite{16#A345#}. It is also possible (though not required) to use the
+@code{16#A345#}. It is also possible (though not required) to use the
Brackets coding for upper half characters. For example, the code
-@cite{16#A3#} can be represented as @cite{['A3']}.
+@code{16#A3#} can be represented as @code{['A3']}.
This scheme is compatible with use of the full Wide_Character set,
and is also the method used for wide character encoding in some standard
10xxxxxx 10xxxxxx 10xxxxxx
@end example
-where the @cite{xxx} bits correspond to the left-padded bits of the
+where the @code{xxx} bits correspond to the left-padded bits of the
32-bit character value.
@item @emph{Brackets Coding}
[ " a b c d e f g h " ]
@end example
-where @cite{a-h} are the six or eight hexadecimal
+where @code{a-h} are the six or eight hexadecimal
characters (using uppercase letters) of the wide wide character code. For
example, ["1F4567"] is used to represent the wide wide character with code
-@cite{16#001F_4567#}.
+@code{16#001F_4567#}.
This scheme is compatible with use of the full Wide_Wide_Character set,
and is also the method used for wide wide character encoding in some standard
An exception arises if the file name generated by the above rules starts
with one of the characters
-@cite{a}, @cite{g}, @cite{i}, or @cite{s}, and the second character is a
+@code{a}, @code{g}, @code{i}, or @code{s}, and the second character is a
minus. In this case, the character tilde is used in place
of the minus. The reason for this special rule is to avoid clashes with
the standard names for child units of the packages System, Ada,
Interfaces, and GNAT, which use the prefixes
-@cite{s-}, @cite{a-}, @cite{i-}, and @cite{g-},
+@code{s-}, @code{a-}, @code{i-}, and @code{g-},
respectively.
The file extension is @code{.ads} for a spec and
(For details see @ref{36,,Renaming Files with gnatchop}.)
Note: in the case of Windows or Mac OS operating systems, case is not
-significant. So for example on @cite{Windows} if the canonical name is
-@cite{main-sub.adb}, you can use the file name @code{Main-Sub.adb} instead.
+significant. So for example on Windows if the canonical name is
+@code{main-sub.adb}, you can use the file name @code{Main-Sub.adb} instead.
However, case is significant for other operating systems, so for example,
if you want to use other than canonically cased file names on a Unix system,
you need to follow the procedures described in the next section.
source file name pragma. However, if the file name specified has an
extension other than @code{.ads} or @code{.adb} it is necessary to use
a special syntax when compiling the file. The name in this case must be
-preceded by the special sequence @emph{-x} followed by a space and the name
-of the language, here @cite{ada}, as in:
+preceded by the special sequence @code{-x} followed by a space and the name
+of the language, here @code{ada}, as in:
@example
$ gcc -c -x ada peculiar_file_name.sim
@end example
-@cite{gnatmake} handles non-standard file names in the usual manner (the
+@code{gnatmake} handles non-standard file names in the usual manner (the
non-standard file name for the main program is simply used as the
argument to gnatmake). Note that if the extension is also non-standard,
-then it must be included in the @cite{gnatmake} command, it may not
+then it must be included in the @code{gnatmake} command, it may not
be omitted.
@node Alternative File Naming Schemes,Handling Arbitrary File Naming Conventions with gnatname,Using Other File Names,File Naming Topics and Utilities
@geindex File names
-The previous section described the use of the @cite{Source_File_Name}
+The previous section described the use of the @code{Source_File_Name}
pragma to allow arbitrary names to be assigned to individual source files.
However, this approach requires one pragma for each file, and especially in
large systems can result in very long @code{gnat.adc} files, and also create
GNAT also provides a facility for specifying systematic file naming schemes
other than the standard default naming scheme previously described. An
alternative scheme for naming is specified by the use of
-@cite{Source_File_Name} pragmas having the following format:
+@code{Source_File_Name} pragmas having the following format:
@example
pragma Source_File_Name (
CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
@end example
-The @cite{FILE_NAME_PATTERN} string shows how the file name is constructed.
+The @code{FILE_NAME_PATTERN} string shows how the file name is constructed.
It contains a single asterisk character, and the unit name is substituted
systematically for this asterisk. The optional parameter
-@cite{Casing} indicates
+@code{Casing} indicates
whether the unit name is to be all upper-case letters, all lower-case letters,
or mixed-case. If no
-@cite{Casing} parameter is used, then the default is all
+@code{Casing} parameter is used, then the default is all
lower-case.
-The optional @cite{Dot_Replacement} string is used to replace any periods
-that occur in subunit or child unit names. If no @cite{Dot_Replacement}
+The optional @code{Dot_Replacement} string is used to replace any periods
+that occur in subunit or child unit names. If no @code{Dot_Replacement}
argument is used then separating dots appear unchanged in the resulting
file name.
Although the above syntax indicates that the
-@cite{Casing} argument must appear
-before the @cite{Dot_Replacement} argument, but it
+@code{Casing} argument must appear
+before the @code{Dot_Replacement} argument, but it
is also permissible to write these arguments in the opposite order.
As indicated, it is possible to specify different naming schemes for
bodies, specs, and subunits. Quite often the rule for subunits is the
same as the rule for bodies, in which case, there is no need to give
-a separate @cite{Subunit_File_Name} rule, and in this case the
-@cite{Body_File_name} rule is used for subunits as well.
+a separate @code{Subunit_File_Name} rule, and in this case the
+@code{Body_File_name} rule is used for subunits as well.
The separate rule for subunits can also be used to implement the rather
unusual case of a compilation environment (e.g., a single directory) which
@itemize *
@item
-If there is a specific @cite{Source_File_Name} pragma for the given unit,
+If there is a specific @code{Source_File_Name} pragma for the given unit,
then this is always used, and any general pattern rules are ignored.
@item
-If there is a pattern type @cite{Source_File_Name} pragma that applies to
+If there is a pattern type @code{Source_File_Name} pragma that applies to
the unit, then the resulting file name will be used if the file exists. If
more than one pattern matches, the latest one will be tried first, and the
first attempt resulting in a reference to a file that exists will be used.
@item
-If no pattern type @cite{Source_File_Name} pragma that applies to the unit
+If no pattern type @code{Source_File_Name} pragma that applies to the unit
for which the corresponding file exists, then the standard GNAT default
naming rules are used.
@end itemize
@node Handling Arbitrary File Naming Conventions with gnatname,File Name Krunching with gnatkr,Alternative File Naming Schemes,File Naming Topics and Utilities
@anchor{gnat_ugn/the_gnat_compilation_model handling-arbitrary-file-naming-conventions-with-gnatname}@anchor{59}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{5a}
-@subsection Handling Arbitrary File Naming Conventions with @cite{gnatname}
+@subsection Handling Arbitrary File Naming Conventions with @code{gnatname}
@geindex File Naming Conventions
The GNAT compiler must be able to know the source file name of a compilation
unit. When using the standard GNAT default file naming conventions
-(@cite{.ads} for specs, @cite{.adb} for bodies), the GNAT compiler
+(@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler
does not need additional information.
When the source file names do not follow the standard GNAT default file naming
a configuration pragmas file (@ref{14,,Configuration Pragmas})
or a project file.
When the non-standard file naming conventions are well-defined,
-a small number of pragmas @cite{Source_File_Name} specifying a naming pattern
+a small number of pragmas @code{Source_File_Name} specifying a naming pattern
(@ref{58,,Alternative File Naming Schemes}) may be sufficient. However,
if the file naming conventions are irregular or arbitrary, a number
-of pragma @cite{Source_File_Name} for individual compilation units
+of pragma @code{Source_File_Name} for individual compilation units
must be defined.
To help maintain the correspondence between compilation unit names and
source file names within the compiler,
-GNAT provides a tool @cite{gnatname} to generate the required pragmas for a
+GNAT provides a tool @code{gnatname} to generate the required pragmas for a
set of files.
@node Running gnatname,Switches for gnatname,Arbitrary File Naming Conventions,Handling Arbitrary File Naming Conventions with gnatname
@anchor{gnat_ugn/the_gnat_compilation_model running-gnatname}@anchor{5d}@anchor{gnat_ugn/the_gnat_compilation_model id14}@anchor{5e}
-@subsubsection Running @cite{gnatname}
+@subsubsection Running @code{gnatname}
-The usual form of the @cite{gnatname} command is:
+The usual form of the @code{gnatname} command is:
@example
-$ gnatname [`switches`] `naming_pattern` [`naming_patterns`]
- [--and [`switches`] `naming_pattern` [`naming_patterns`]]
+$ gnatname [ switches ] naming_pattern [ naming_patterns ]
+ [--and [ switches ] naming_pattern [ naming_patterns ]]
@end example
All of the arguments are optional. If invoked without any argument,
-@cite{gnatname} will display its usage.
+@code{gnatname} will display its usage.
-When used with at least one naming pattern, @cite{gnatname} will attempt to
+When used with at least one naming pattern, @code{gnatname} will attempt to
find all the compilation units in files that follow at least one of the
naming patterns. To find these compilation units,
-@cite{gnatname} will use the GNAT compiler in syntax-check-only mode on all
+@code{gnatname} will use the GNAT compiler in syntax-check-only mode on all
regular files.
-One or several Naming Patterns may be given as arguments to @cite{gnatname}.
+One or several Naming Patterns may be given as arguments to @code{gnatname}.
Each Naming Pattern is enclosed between double quotes (or single
quotes on Windows).
A Naming Pattern is a regular expression similar to the wildcard patterns
used in file names by the Unix shells or the DOS prompt.
-@cite{gnatname} may be called with several sections of directories/patterns.
-Sections are separated by switch @cite{--and}. In each section, there must be
+@code{gnatname} may be called with several sections of directories/patterns.
+Sections are separated by the switch @code{--and}. In each section, there must be
at least one pattern. If no directory is specified in a section, the current
-directory (or the project directory is @cite{-P} is used) is implied.
+directory (or the project directory if @code{-P} is used) is implied.
The options other that the directory switches and the patterns apply globally
even if they are in different sections.
see the second kind of regular expressions described in @code{g-regexp.ads}
(the 'Glob' regular expressions).
-When invoked with no switch @cite{-P}, @cite{gnatname} will create a
+When invoked without the switch @code{-P}, @code{gnatname} will create a
configuration pragmas file @code{gnat.adc} in the current working directory,
-with pragmas @cite{Source_File_Name} for each file that contains a valid Ada
+with pragmas @code{Source_File_Name} for each file that contains a valid Ada
unit.
@node Switches for gnatname,Examples of gnatname Usage,Running gnatname,Handling Arbitrary File Naming Conventions with gnatname
@anchor{gnat_ugn/the_gnat_compilation_model id15}@anchor{5f}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{60}
-@subsubsection Switches for @cite{gnatname}
+@subsubsection Switches for @code{gnatname}
-Switches for @cite{gnatname} must precede any specified Naming Pattern.
+Switches for @code{gnatname} must precede any specified Naming Pattern.
-You may specify any of the following switches to @cite{gnatname}:
+You may specify any of the following switches to @code{gnatname}:
@geindex --version (gnatname)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@item @code{--subdirs=@emph{dir}}
Create a configuration pragmas file @code{filename} (instead of the default
@code{gnat.adc}).
-There may be zero, one or more space between @emph{-c} and
+There may be zero, one or more space between @code{-c} and
@code{filename}.
@code{filename} may include directory information. @code{filename} must be
-writable. There may be only one switch @emph{-c}.
-When a switch @emph{-c} is
-specified, no switch @emph{-P} may be specified (see below).
+writable. There may be only one switch @code{-c}.
+When a switch @code{-c} is
+specified, no switch @code{-P} may be specified (see below).
@end table
@geindex -d (gnatname)
@item @code{-d@emph{dir}}
Look for source files in directory @code{dir}. There may be zero, one or more
-spaces between @emph{-d} and @code{dir}.
-@code{dir} may end with @cite{/**}, that is it may be of the form
-@cite{root_dir/**}. In this case, the directory @cite{root_dir} and all of its
+spaces between @code{-d} and @code{dir}.
+@code{dir} may end with @code{/**}, that is it may be of the form
+@code{root_dir/**}. In this case, the directory @code{root_dir} and all of its
subdirectories, recursively, have to be searched for sources.
-When a switch @emph{-d}
+When a switch @code{-d}
is specified, the current working directory will not be searched for source
-files, unless it is explicitly specified with a @emph{-d}
-or @emph{-D} switch.
-Several switches @emph{-d} may be specified.
+files, unless it is explicitly specified with a @code{-d}
+or @code{-D} switch.
+Several switches @code{-d} may be specified.
If @code{dir} is a relative path, it is relative to the directory of
the configuration pragmas file specified with switch
-@emph{-c},
+@code{-c},
or to the directory of the project file specified with switch
-@emph{-P} or,
-if neither switch @emph{-c}
-nor switch @emph{-P} are specified, it is relative to the
+@code{-P} or,
+if neither switch @code{-c}
+nor switch @code{-P} are specified, it is relative to the
current working directory. The directory
-specified with switch @emph{-d} must exist and be readable.
+specified with switch @code{-d} must exist and be readable.
@end table
@geindex -D (gnatname)
@item @code{-D@emph{filename}}
Look for source files in all directories listed in text file @code{filename}.
-There may be zero, one or more spaces between @emph{-D}
+There may be zero, one or more spaces between @code{-D}
and @code{filename}.
@code{filename} must be an existing, readable text file.
Each nonempty line in @code{filename} must be a directory.
-Specifying switch @emph{-D} is equivalent to specifying as many
-switches @emph{-d} as there are nonempty lines in
+Specifying switch @code{-D} is equivalent to specifying as many
+switches @code{-d} as there are nonempty lines in
@code{file}.
@item @code{-eL}
@item @code{-P@emph{proj}}
Create or update project file @code{proj}. There may be zero, one or more space
-between @emph{-P} and @code{proj}. @code{proj} may include directory
+between @code{-P} and @code{proj}. @code{proj} may include directory
information. @code{proj} must be writable.
-There may be only one switch @emph{-P}.
-When a switch @emph{-P} is specified,
-no switch @emph{-c} may be specified.
-On all platforms, except on VMS, when @cite{gnatname} is invoked for an
+There may be only one switch @code{-P}.
+When a switch @code{-P} is specified,
+no switch @code{-c} may be specified.
+On all platforms, except on VMS, when @code{gnatname} is invoked for an
existing project file <proj>.gpr, a backup copy of the project file is created
in the project directory with file name <proj>.gpr.saved_x. 'x' is the first
non negative number that makes this backup copy a new file.
@node Examples of gnatname Usage,,Switches for gnatname,Handling Arbitrary File Naming Conventions with gnatname
@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatname-usage}@anchor{61}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{62}
-@subsubsection Examples of @cite{gnatname} Usage
+@subsubsection Examples of @code{gnatname} Usage
@example
In this example, the directory @code{/home/me} must already exist
and be writable. In addition, the directory
@code{/home/me/sources} (specified by
-@emph{-d sources}) must exist and be readable.
+@code{-d sources}) must exist and be readable.
-Note the optional spaces after @emph{-c} and @emph{-d}.
+Note the optional spaces after @code{-c} and @code{-d}.
@example
$ gnatname -P/home/me/proj -x "*_nt_body.ada"
-dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
@end example
-Note that several switches @emph{-d} may be used,
+Note that several switches @code{-d} may be used,
even in conjunction with one or several switches
-@emph{-D}. Several Naming Patterns and one excluded pattern
+@code{-D}. Several Naming Patterns and one excluded pattern
are used in this example.
@node File Name Krunching with gnatkr,Renaming Files with gnatchop,Handling Arbitrary File Naming Conventions with gnatname,File Naming Topics and Utilities
@anchor{gnat_ugn/the_gnat_compilation_model file-name-krunching-with-gnatkr}@anchor{63}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{64}
-@subsection File Name Krunching with @cite{gnatkr}
+@subsection File Name Krunching with @code{gnatkr}
@geindex gnatkr
This section discusses the method used by the compiler to shorten
the default file names chosen for Ada units so that they do not
exceed the maximum length permitted. It also describes the
-@cite{gnatkr} utility that can be used to determine the result of
+@code{gnatkr} utility that can be used to determine the result of
applying this shortening.
@menu
@node About gnatkr,Using gnatkr,,File Name Krunching with gnatkr
@anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{65}@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{66}
-@subsubsection About @cite{gnatkr}
+@subsubsection About @code{gnatkr}
The default file naming rule in GNAT
circuit that limits file names to nn characters (where nn is a decimal
integer).
-The @cite{gnatkr} utility can be used to determine the krunched name for
+The @code{gnatkr} utility can be used to determine the krunched name for
a given file, when krunched to a specified maximum length.
@node Using gnatkr,Krunching Method,About gnatkr,File Name Krunching with gnatkr
@anchor{gnat_ugn/the_gnat_compilation_model id19}@anchor{67}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{54}
-@subsubsection Using @cite{gnatkr}
+@subsubsection Using @code{gnatkr}
-The @cite{gnatkr} command has the form:
+The @code{gnatkr} command has the form:
@example
-$ gnatkr `name` [`length`]
+$ gnatkr name [ length ]
@end example
-@cite{name} is the uncrunched file name, derived from the name of the unit
+@code{name} is the uncrunched file name, derived from the name of the unit
in the standard manner described in the previous section (i.e., in particular
all dots are replaced by hyphens). The file name may or may not have an
extension (defined as a suffix of the form period followed by arbitrary
be preserved in the output. For example, when krunching @code{hellofile.ads}
to eight characters, the result will be hellofil.ads.
-Note: for compatibility with previous versions of @cite{gnatkr} dots may
+Note: for compatibility with previous versions of @code{gnatkr} dots may
appear in the name instead of hyphens, but the last dot will always be
-taken as the start of an extension. So if @cite{gnatkr} is given an argument
+taken as the start of an extension. So if @code{gnatkr} is given an argument
such as @code{Hello.World.adb} it will be treated exactly as if the first
period had been a hyphen, and for example krunching to eight characters
gives the result @code{hellworl.adb}.
Note that the result is always all lower case.
Characters of the other case are folded as required.
-@cite{length} represents the length of the krunched name. The default
+@code{length} represents the length of the krunched name. The default
when no argument is given is 8 characters. A length of zero stands for
unlimited, in other words do not chop except for system files where the
implied crunching length is always eight characters.
for all letters, except that a hyphen in the second character position is
replaced by a tilde if the first character is
@code{a}, @code{i}, @code{g}, or @code{s}.
-The extension is @cite{.ads} for a
-spec and @cite{.adb} for a body.
+The extension is @code{.ads} for a
+spec and @code{.adb} for a body.
Krunching does not affect the extension, but the file name is shortened to
the specified length by following these rules:
Of course no file shortening algorithm can guarantee uniqueness over all
possible unit names, and if file name krunching is used then it is your
responsibility to ensure that no name clashes occur. The utility
-program @cite{gnatkr} is supplied for conveniently determining the
+program @code{gnatkr} is supplied for conveniently determining the
krunched name of a file.
@node Examples of gnatkr Usage,,Krunching Method,File Name Krunching with gnatkr
@anchor{gnat_ugn/the_gnat_compilation_model id21}@anchor{6a}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatkr-usage}@anchor{6b}
-@subsubsection Examples of @cite{gnatkr} Usage
+@subsubsection Examples of @code{gnatkr} Usage
@example
@node Renaming Files with gnatchop,,File Name Krunching with gnatkr,File Naming Topics and Utilities
@anchor{gnat_ugn/the_gnat_compilation_model id22}@anchor{6c}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{36}
-@subsection Renaming Files with @cite{gnatchop}
+@subsection Renaming Files with @code{gnatchop}
@geindex gnatchop
This section discusses how to handle files with multiple units by using
-the @cite{gnatchop} utility. This utility is also useful in renaming
+the @code{gnatchop} utility. This utility is also useful in renaming
files to meet the standard GNAT default file naming conventions.
@menu
compiler have only one unit and there be a strict correspondence
between the file name and the unit name.
-The @cite{gnatchop} utility allows both of these rules to be relaxed,
+The @code{gnatchop} utility allows both of these rules to be relaxed,
allowing GNAT to process files which contain multiple compilation units
-and files with arbitrary file names. @cite{gnatchop}
+and files with arbitrary file names. @code{gnatchop}
reads the specified file and generates one or more output files,
containing one unit per file. The unit and the file name correspond,
as required by GNAT.
If you want to permanently restructure a set of 'foreign' files so that
they match the GNAT rules, and do the remaining development using the
-GNAT structure, you can simply use @emph{gnatchop} once, generate the
+GNAT structure, you can simply use @code{gnatchop} once, generate the
new set of files and work with them from that point on.
Alternatively, if you want to keep your files in the 'foreign' format,
perhaps to maintain compatibility with some other Ada compilation
-system, you can set up a procedure where you use @emph{gnatchop} each
+system, you can set up a procedure where you use @code{gnatchop} each
time you compile, regarding the source files that it writes as temporary
files that you throw away.
@subsubsection Operating gnatchop in Compilation Mode
-The basic function of @cite{gnatchop} is to take a file with multiple units
+The basic function of @code{gnatchop} is to take a file with multiple units
and split it into separate files. The boundary between files is reasonably
clear, except for the issue of comments and pragmas. In default mode, the
rule is that any pragmas between units belong to the previous unit, except
the split point without needing to mark it explicitly and most users will
find this default to be what they want. In this default mode it is incorrect to
submit a file containing only configuration pragmas, or one that ends in
-configuration pragmas, to @cite{gnatchop}.
+configuration pragmas, to @code{gnatchop}.
However, using a special option to activate 'compilation mode',
-@cite{gnatchop}
+@code{gnatchop}
can perform another function, which is to provide exactly the semantics
required by the RM for handling of configuration pragmas in a compilation.
In the absence of configuration pragmas (at the main file level), this
option has no effect, but it causes such configuration pragmas to be handled
in a quite different manner.
-First, in compilation mode, if @cite{gnatchop} is given a file that consists of
+First, in compilation mode, if @code{gnatchop} is given a file that consists of
only configuration pragmas, then this file is appended to the
@code{gnat.adc} file in the current directory. This behavior provides
the required behavior described in the RM for the actions to be taken
of a compilation environment. For more information on the
@code{gnat.adc} file, see @ref{56,,Handling of Configuration Pragmas}.
-Second, in compilation mode, if @cite{gnatchop}
+Second, in compilation mode, if @code{gnatchop}
is given a file that starts with
configuration pragmas, and contains one or more units, then these
configuration pragmas are prepended to each of the chopped files. This
pragmas other than those preceding the first compilation unit of a
compilation.
-For most purposes, @cite{gnatchop} will be used in default mode. The
+For most purposes, @code{gnatchop} will be used in default mode. The
compilation mode described above is used only if you need exactly
accurate behavior with respect to compilations, and you have files
that contain multiple units and configuration pragmas. In this
-circumstance the use of @cite{gnatchop} with the compilation mode
+circumstance the use of @code{gnatchop} with the compilation mode
switch provides the required behavior, and is for example the mode
in which GNAT processes the ACVC tests.
@node Command Line for gnatchop,Switches for gnatchop,Operating gnatchop in Compilation Mode,Renaming Files with gnatchop
@anchor{gnat_ugn/the_gnat_compilation_model id25}@anchor{71}@anchor{gnat_ugn/the_gnat_compilation_model command-line-for-gnatchop}@anchor{72}
-@subsubsection Command Line for @cite{gnatchop}
+@subsubsection Command Line for @code{gnatchop}
-The @cite{gnatchop} command has the form:
+The @code{gnatchop} command has the form:
@example
$ gnatchop switches file_name [file_name ...]
contains one or more Ada units, in normal GNAT format, concatenated
together. As shown, more than one file may be presented to be chopped.
-When run in default mode, @cite{gnatchop} generates one output file in
+When run in default mode, @code{gnatchop} generates one output file in
the current directory for each unit in each of the files.
-@cite{directory}, if specified, gives the name of the directory to which
+@code{directory}, if specified, gives the name of the directory to which
the output files will be written. If it is not specified, all files are
written to the current directory.
@node Switches for gnatchop,Examples of gnatchop Usage,Command Line for gnatchop,Renaming Files with gnatchop
@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatchop}@anchor{73}@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{74}
-@subsubsection Switches for @cite{gnatchop}
+@subsubsection Switches for @code{gnatchop}
-@emph{gnatchop} recognizes the following switches:
+@code{gnatchop} recognizes the following switches:
@geindex --version (gnatchop)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-c}
-Causes @cite{gnatchop} to operate in compilation mode, in which
+Causes @code{gnatchop} to operate in compilation mode, in which
configuration pragmas are handled according to strict RM rules. See
previous section for a full description of this mode.
@item @code{-gnat@emph{xxx}}
-This passes the given @emph{-gnat`xxx*` switch to `gnat` which is
-used to parse the given file. Not all `xxx` options make sense,
-but for example, the use of *-gnati2} allows @cite{gnatchop} to
+This passes the given @code{-gnat@emph{xxx}} switch to @code{gnat} which is
+used to parse the given file. Not all @emph{xxx} options make sense,
+but for example, the use of @code{-gnati2} allows @code{gnatchop} to
process a source file that uses Latin-2 coding for identifiers.
@item @code{-h}
-Causes @cite{gnatchop} to generate a brief help summary to the standard
+Causes @code{gnatchop} to generate a brief help summary to the standard
output file showing usage information.
@end table
@item @code{-k@emph{mm}}
-Limit generated file names to the specified number @cite{mm}
+Limit generated file names to the specified number @code{mm}
of characters.
This is useful if the
resulting set of files is required to be interoperable with systems
which limit the length of file names.
-No space is allowed between the @emph{-k} and the numeric value. The numeric
-value may be omitted in which case a default of @emph{-k8},
+No space is allowed between the @code{-k} and the numeric value. The numeric
+value may be omitted in which case a default of @code{-k8},
suitable for use
-with DOS-like file systems, is used. If no @emph{-k} switch
+with DOS-like file systems, is used. If no @code{-k} switch
is present then
there is no limit on the length of file names.
@end table
Causes the file modification time stamp of the input file to be
preserved and used for the time stamp of the output file(s). This may be
useful for preserving coherency of time stamps in an environment where
-@cite{gnatchop} is used as part of a standard build process.
+@code{gnatchop} is used as part of a standard build process.
@end table
@geindex -q (gnatchop)
@item @code{-r}
-Generate @cite{Source_Reference} pragmas. Use this switch if the output
+Generate @code{Source_Reference} pragmas. Use this switch if the output
files are regarded as temporary and development is to be done in terms
of the original unchopped file. This switch causes
-@cite{Source_Reference} pragmas to be inserted into each of the
+@code{Source_Reference} pragmas to be inserted into each of the
generated files to refers back to the original file name and line number.
The result is that all error messages refer back to the original
unchopped file.
In addition, the debugging information placed into the object file (when
-the @emph{-g} switch of @emph{gcc} or @emph{gnatmake} is
+the @code{-g} switch of @code{gcc} or @code{gnatmake} is
specified)
also refers back to this original file so that tools like profilers and
debuggers will give information in terms of the original unchopped file.
If the original file to be chopped itself contains
-a @cite{Source_Reference}
+a @code{Source_Reference}
pragma referencing a third file, then gnatchop respects
-this pragma, and the generated @cite{Source_Reference} pragmas
+this pragma, and the generated @code{Source_Reference} pragmas
in the chopped file refer to the original file, with appropriate
-line numbers. This is particularly useful when @cite{gnatchop}
-is used in conjunction with @cite{gnatprep} to compile files that
+line numbers. This is particularly useful when @code{gnatchop}
+is used in conjunction with @code{gnatprep} to compile files that
contain preprocessing statements and multiple units.
@end table
@item @code{-v}
-Causes @cite{gnatchop} to operate in verbose mode. The version
+Causes @code{gnatchop} to operate in verbose mode. The version
number and copyright notice are output, as well as exact copies of
the gnat1 commands spawned to obtain the chop control information.
@end table
@item @code{-w}
-Overwrite existing file names. Normally @cite{gnatchop} regards it as a
+Overwrite existing file names. Normally @code{gnatchop} regards it as a
fatal error if there is already a file with the same name as a
file it would otherwise output, in other words if the files to be
chopped contain duplicated units. This switch bypasses this
@node Examples of gnatchop Usage,,Switches for gnatchop,Renaming Files with gnatchop
@anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{75}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{76}
-@subsubsection Examples of @cite{gnatchop} Usage
+@subsubsection Examples of @code{gnatchop} Usage
@example
Chops the source file @code{archive}
into the current directory. One
-useful application of @cite{gnatchop} is in sending sets of sources
+useful application of @code{gnatchop} is in sending sets of sources
around, for example in email messages. The required sources are simply
-concatenated (for example, using a Unix @cite{cat}
+concatenated (for example, using a Unix @code{cat}
command), and then
-@emph{gnatchop} is used at the other end to reconstitute the original
+@code{gnatchop} is used at the other end to reconstitute the original
file names.
@example
the resulting files in the directory @code{direc}. Note that if any units
occur more than once anywhere within this set of files, an error message
is generated, and no files are written. To override this check, use the
-@emph{-w} switch,
+@code{-w} switch,
in which case the last occurrence in the last file will
be the one that is output, and earlier duplicate occurrences for a given
unit will be skipped.
Configuration pragmas include those pragmas described as
such in the Ada Reference Manual, as well as
implementation-dependent pragmas that are configuration pragmas.
-See the @cite{Implementation_Defined_Pragmas} chapter in the
+See the @code{Implementation_Defined_Pragmas} chapter in the
@cite{GNAT_Reference_Manual} for details on these
additional GNAT-specific configuration pragmas.
-Most notably, the pragma @cite{Source_File_Name}, which allows
+Most notably, the pragma @code{Source_File_Name}, which allows
specifying non-default names for source files, is a configuration
pragma. The following is a complete list of configuration pragmas
recognized by GNAT:
Assertion_Policy
Assume_No_Invalid_Values
C_Pass_By_Copy
+Check_Float_Overflow
Check_Name
Check_Policy
Compile_Time_Error
Compile_Time_Warning
Compiler_Unit
+Compiler_Unit_Warning
Component_Alignment
Convention_Identifier
Debug_Policy
Detect_Blocking
+Default_Scalar_Storage_Order
Default_Storage_Pool
+Disable_Atomic_Synchronization
Discard_Names
Elaboration_Checks
Eliminate
+Enable_Atomic_Synchronization
Extend_System
Extensions_Allowed
External_Name_Casing
Fast_Math
Favor_Top_Level
-Float_Representation
+Ignore_Pragma
Implicit_Packing
Initialize_Scalars
Interrupt_State
License
Locking_Policy
-Long_Float
+No_Component_Reordering
+No_Heap_Finalization
No_Run_Time
No_Strict_Aliasing
Normalize_Scalars
Optimize_Alignment
+Overflow_Mode
+Overriding_Renamings
+Partition_Elaboration_Policy
Persistent_BSS
Polling
+Prefix_Exception_Messages
Priority_Specific_Dispatching
Profile
Profile_Warnings
Propagate_Exceptions
Queuing_Policy
+Rational
Ravenscar
Rename_Pragma
Restricted_Run_Time
Restrictions_Warnings
Reviewable
Short_Circuit_And_Or
+Short_Descriptors
Source_File_Name
Source_File_Name_Project
SPARK_Mode
Suppress
Suppress_Exception_Locations
Task_Dispatching_Policy
+Unevaluated_Use_Of_Old
Universal_Data
Unsuppress
Use_VADS_Size
Validity_Checks
+Warning_As_Error
Warnings
Wide_Character_Encoding
@end example
unit, or they can appear in a configuration pragma file to apply to
all compilations performed in a given compilation environment.
-GNAT also provides the @cite{gnatchop} utility to provide an automatic
+GNAT also provides the @code{gnatchop} utility to provide an automatic
way to handle configuration pragmas following the semantics for
compilations (that is, files with multiple units), described in the RM.
See @ref{6f,,Operating gnatchop in Compilation Mode} for details.
@code{gnat.adc} file that contains configuration pragmas directly,
as described in the following section.
-In the case of @cite{Restrictions} pragmas appearing as configuration
+In the case of @code{Restrictions} pragmas appearing as configuration
pragmas in individual compilation units, the exact handling depends on
the type of restriction.
Restrictions that require partition-wide consistency (like
-@cite{No_Tasking}) are
+@code{No_Tasking}) are
recognized wherever they appear
and can be freely inherited, e.g. from a @emph{with}ed unit to the @emph{with}ing
unit. This makes sense since the binder will in any case insist on seeing
directory is searched for a file whose name is @code{gnat.adc}. If
this file is present, it is expected to contain one or more
configuration pragmas that will be applied to the current compilation.
-However, if the switch @emph{-gnatA} is used, @code{gnat.adc} is not
+However, if the switch @code{-gnatA} is used, @code{gnat.adc} is not
considered. When taken into account, @code{gnat.adc} is added to the
dependencies, so that if @code{gnat.adc} is modified later, an invocation of
-@emph{gnatmake} will recompile the source.
+@code{gnatmake} will recompile the source.
Configuration pragmas may be entered into the @code{gnat.adc} file
-either by running @cite{gnatchop} on a source file that consists only of
+either by running @code{gnatchop} on a source file that consists only of
configuration pragmas, or more conveniently by direct editing of the
@code{gnat.adc} file, which is a standard format source file.
Besides @code{gnat.adc}, additional files containing configuration
pragmas may be applied to the current compilation using the switch
-@code{-gnatec=@emph{path}} where @cite{path} must designate an existing file that
+@code{-gnatec=@emph{path}} where @code{path} must designate an existing file that
contains only configuration pragmas. These configuration pragmas are
in addition to those found in @code{gnat.adc} (provided @code{gnat.adc}
-is present and switch @emph{-gnatA} is not used).
+is present and switch @code{-gnatA} is not used).
-It is allowable to specify several switches @emph{-gnatec=}, all of which
+It is allowable to specify several switches @code{-gnatec=}, all of which
will be taken into account.
Files containing configuration pragmas specified with switches
-@emph{-gnatec=} are added to the dependencies, unless they are
+@code{-gnatec=} are added to the dependencies, unless they are
temporary files. A file is considered temporary if its name ends in
@code{.tmp} or @code{.TMP}. Certain tools follow this naming
-convention because they pass information to @emph{gcc} via
+convention because they pass information to @code{gcc} via
temporary files that are immediately deleted; it doesn't make sense to
depend on a file that no longer exists. Such tools include
-@emph{gprbuild}, @emph{gnatmake}, and @emph{gnatcheck}.
+@code{gprbuild}, @code{gnatmake}, and @code{gnatcheck}.
If you are using project file, a separate mechanism is provided using
project attributes.
GNAT provides an option for compiling such files purely for the
purposes of checking correctness; such compilations are not required as
part of the process of building a program. To compile a file in this
-checking mode, use the @emph{-gnatc} switch.
+checking mode, use the @code{-gnatc} switch.
@node Source Dependencies,The Ada Library Information Files,Generating Object Files,The GNAT Compilation Model
@anchor{gnat_ugn/the_gnat_compilation_model id32}@anchor{7c}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{41}
A given object file clearly depends on the source file which is compiled
to produce it. Here we are using "depends" in the sense of a typical
-@cite{make} utility; in other words, an object file depends on a source
+@code{make} utility; in other words, an object file depends on a source
file if changes to the source file require the object file to be
recompiled.
In addition to this basic dependency, a given object may depend on
@itemize *
@item
-If a file being compiled @emph{with}s a unit @cite{X}, the object file
-depends on the file containing the spec of unit @cite{X}. This includes
+If a file being compiled @emph{with}s a unit @code{X}, the object file
+depends on the file containing the spec of unit @code{X}. This includes
files that are @emph{with}ed implicitly either because they are parents
of @emph{with}ed child units or they are run-time units required by the
language constructs used in a particular unit.
@item
If a file being compiled contains a call to a subprogram for which
-pragma @cite{Inline} applies and inlining is activated with the
-@emph{-gnatn} switch, the object file depends on the file containing the
+pragma @code{Inline} applies and inlining is activated with the
+@code{-gnatn} switch, the object file depends on the file containing the
body of this subprogram as well as on the file containing the spec. Note
that for inlining to actually occur as a result of the use of this switch,
it is necessary to compile in optimizing mode.
@geindex -gnatN switch
-The use of @emph{-gnatN} activates inlining optimization
+The use of @code{-gnatN} activates inlining optimization
that is performed by the front end of the compiler. This inlining does
-not require that the code generation be optimized. Like @emph{-gnatn},
+not require that the code generation be optimized. Like @code{-gnatn},
the use of this switch generates additional dependencies.
When using a gcc-based back end (in practice this means using any version
of GNAT other than for the JVM, .NET or GNAAMP platforms), then the use of
-@emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred.
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
The previous two rules meant that for purposes of computing dependencies and
recompilation, a body and all its subunits are treated as an indivisible whole.
-These rules are applied transitively: if unit @cite{A} @emph{with}s
-unit @cite{B}, whose elaboration calls an inlined procedure in package
-@cite{C}, the object file for unit @cite{A} will depend on the body of
-@cite{C}, in file @code{c.adb}.
+These rules are applied transitively: if unit @code{A} @emph{with}s
+unit @code{B}, whose elaboration calls an inlined procedure in package
+@code{C}, the object file for unit @code{A} will depend on the body of
+@code{C}, in file @code{c.adb}.
The set of dependent files described by these rules includes all the
files on which the unit is semantically dependent, as dictated by the
An object file must be recreated by recompiling the corresponding source
file if any of the source files on which it depends are modified. For
-example, if the @cite{make} utility is used to control compilation,
+example, if the @code{make} utility is used to control compilation,
the rule for an Ada object file must mention all the source files on
which the object file depends, according to the above definition.
The determination of the necessary
-recompilations is done automatically when one uses @emph{gnatmake}.
+recompilations is done automatically when one uses @code{gnatmake}.
@end itemize
@node The Ada Library Information Files,Binding an Ada Program,Source Dependencies,The GNAT Compilation Model
as well as the wide character encoding used during compilation).
@item
-List of arguments used in the @emph{gcc} command for the compilation
+List of arguments used in the @code{gcc} command for the compilation
@item
Attributes of the unit, including configuration pragmas used, an indication
checking.
@item
-Categorization information (e.g., use of pragma @cite{Pure}).
+Categorization information (e.g., use of pragma @code{Pure}).
@item
Information on all @emph{with}ed units, including presence of
-Elaborate` or @cite{Elaborate_All} pragmas.
+@code{Elaborate} or @code{Elaborate_All} pragmas.
@item
-Information from any @cite{Linker_Options} pragmas used in the unit
+Information from any @code{Linker_Options} pragmas used in the unit
@item
-Information on the use of @cite{Body_Version} or @cite{Version}
+Information on the use of @code{Body_Version} or @code{Version}
attributes in the unit.
@item
@item
Cross-reference data. Contains information on all entities referenced
-in the unit. Used by tools like @cite{gnatxref} and @cite{gnatfind} to
+in the unit. Used by tools like @code{gnatxref} and @code{gnatfind} to
provide cross-reference information.
@end itemize
For a full detailed description of the format of the @code{ALI} file,
-see the source of the body of unit @cite{Lib.Writ}, contained in file
+see the source of the body of unit @code{Lib.Writ}, contained in file
@code{lib-writ.adb} in the GNAT compiler sources.
@node Binding an Ada Program,GNAT and Libraries,The Ada Library Information Files,The GNAT Compilation Model
a call to the main program. This Ada program is compiled to generate the
object file for the main program. The name of
the Ada file is @code{b~xxx}.adb` (with the corresponding spec
-@code{b~xxx}.ads`) where @cite{xxx} is the name of the
+@code{b~xxx}.ads`) where @code{xxx} is the name of the
main program unit.
Finally, the linker is used to build the resulting executable program,
chapter of the @emph{GPRbuild User's Guide}).
A project is considered a library project, when two project-level attributes
-are defined in it: @cite{Library_Name} and @cite{Library_Dir}. In order to
+are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to
control different aspects of library configuration, additional optional
project-level attributes can be specified:
@table @asis
-@item @emph{Library_Kind}
+@item @code{Library_Kind}
This attribute controls whether the library is to be static or dynamic
@end table
@table @asis
-@item @emph{Library_Version}
+@item @code{Library_Version}
This attribute specifies the library version; this value is used
during dynamic linking of shared libraries to determine if the currently
@end table
@item
-@emph{Library_Options}
+@code{Library_Options}
@item
@table @asis
-@item @emph{Library_GCC}
+@item @code{Library_GCC}
These attributes specify additional low-level options to be used during
library generation, and redefine the actual application used to generate
with a conventional script. For simple libraries, it is also possible to create
a dummy main program which depends upon all the packages that comprise the
interface of the library. This dummy main program can then be given to
-@emph{gnatmake}, which will ensure that all necessary objects are built.
+@code{gnatmake}, which will ensure that all necessary objects are built.
After this task is accomplished, you should follow the standard procedure
of the underlying operating system to produce the static or shared library.
be @code{adalib}).
You can also specify a new default path to the run-time library at compilation
-time with the switch @emph{--RTS=rts-path}. You can thus choose / change
+time with the switch @code{--RTS=rts-path}. You can thus choose / change
the run-time library you want your program to be compiled with. This switch is
-recognized by @emph{gcc}, @emph{gnatmake}, @emph{gnatbind},
-@emph{gnatls}, @emph{gnatfind} and @emph{gnatxref}.
+recognized by @code{gcc}, @code{gnatmake}, @code{gnatbind},
+@code{gnatls}, @code{gnatfind} and @code{gnatxref}.
It is possible to install a library before or after the standard GNAT
library, by reordering the lines in the configuration files. In general, a
Once again, the project facility greatly simplifies the use of
libraries. In this context, using a library is just a matter of adding a
@emph{with} clause in the user project. For instance, to make use of the
-library @cite{My_Lib} shown in examples in earlier sections, you can
+library @code{My_Lib} shown in examples in earlier sections, you can
write:
@example
end Liba;
@end example
-This is an alternative to the use of @cite{pragma Linker_Options}. It is
+This is an alternative to the use of @code{pragma Linker_Options}. It is
especially interesting in the context of systems with several interdependent
static libraries where finding a proper linker order is not easy and best be
left to the tools having visibility over project dependence information.
@code{ada_object_path}
@item
-a pragma @cite{Linker_Options} has been added to one of the sources.
+a pragma @code{Linker_Options} has been added to one of the sources.
For example:
@example
applications when a new version of the library is installed. Specifically,
if the interface sources have not changed, client applications do not need to
be recompiled. If, furthermore, a SAL is provided in the shared form and its
-version, controlled by @cite{Library_Version} attribute, is not changed,
+version, controlled by @code{Library_Version} attribute, is not changed,
then the clients do not need to be relinked.
SALs also allow the library providers to minimize the amount of library source
stand-alone libraries; see the @emph{Stand-alone Library Projects} section
in the @emph{GNAT Project Manager} chapter of the @emph{GPRbuild User's Guide}.
To be a Stand-alone Library Project, in addition to the two attributes
-that make a project a Library Project (@cite{Library_Name} and
-@cite{Library_Dir}; see the @emph{Library Projects} section in the
+that make a project a Library Project (@code{Library_Name} and
+@code{Library_Dir}; see the @emph{Library Projects} section in the
@emph{GNAT Project Manager} chapter of the @emph{GPRbuild User's Guide}),
-the attribute @cite{Library_Interface} must be defined. For example:
+the attribute @code{Library_Interface} must be defined. For example:
@example
for Library_Dir use "lib_dir";
for Library_Interface use ("int1", "int1.child");
@end example
-Attribute @cite{Library_Interface} has a non-empty string list value,
+Attribute @code{Library_Interface} has a non-empty string list value,
each string in the list designating a unit contained in an immediate source
of the project file.
(@code{b~dummy.ads/b} in the example above).
This binder-generated package includes initialization and
finalization procedures whose
-names depend on the library name (@cite{dummyinit} and @cite{dummyfinal}
+names depend on the library name (@code{dummyinit} and @code{dummyfinal}
in the example
above). The object corresponding to this package is included in the library.
You must ensure timely (e.g., prior to any use of interfaces in the SAL)
calling of these procedures if a static SAL is built, or if a shared SAL
is built
-with the project-level attribute @cite{Library_Auto_Init} set to
-@cite{"false"}.
+with the project-level attribute @code{Library_Auto_Init} set to
+@code{"false"}.
For a Stand-Alone Library, only the @code{ALI} files of the Interface Units
-(those that are listed in attribute @cite{Library_Interface}) are copied to
+(those that are listed in attribute @code{Library_Interface}) are copied to
the Library Directory. As a consequence, only the Interface Units may be
imported from Ada units outside of the library. If other units are imported,
the binding phase will fail.
libraries. So an encapsulated library only depends on system
libraries, all other code, including the GNAT runtime, is embedded. To
build an encapsulated library the attribute
-@cite{Library_Standalone} must be set to @cite{encapsulated}:
+@code{Library_Standalone} must be set to @code{encapsulated}:
@example
for Library_Dir use "lib_dir";
for Library_Standalone use "encapsulated";
@end example
-The default value for this attribute is @cite{standard} in which case
+The default value for this attribute is @code{standard} in which case
a stand-alone library is built.
-The attribute @cite{Library_Src_Dir} may be specified for a
-Stand-Alone Library. @cite{Library_Src_Dir} is a simple attribute that has a
+The attribute @code{Library_Src_Dir} may be specified for a
+Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
single string value. Its value must be the path (absolute or relative to the
project directory) of an existing directory. This directory cannot be the
object directory or one of the source directories, but it can be the same as
Units of the library that are needed by an Ada client of the library will be
copied to the designated directory, called the Interface Copy directory.
These sources include the specs of the Interface Units, but they may also
-include bodies and subunits, when pragmas @cite{Inline} or @cite{Inline_Always}
+include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
are used, or when there is a generic unit in the spec. Before the sources
are copied to the Interface Copy directory, an attempt is made to delete all
files in the Interface Copy directory.
Compile all library sources.
@item
-Invoke the binder with the switch @emph{-n} (No Ada main program),
+Invoke the binder with the switch @code{-n} (No Ada main program),
with all the @code{ALI} files of the interfaces, and
-with the switch @emph{-L} to give specific names to the @cite{init}
-and @cite{final} procedures. For example:
+with the switch @code{-L} to give specific names to the @code{init}
+and @code{final} procedures. For example:
@example
$ gnatbind -n int1.ali int2.ali -Lsal1
@item
Link the dynamic library with all the necessary object files,
-indicating to the linker the names of the @cite{init} (and possibly
-@cite{final}) procedures for automatic initialization (and finalization).
+indicating to the linker the names of the @code{init} (and possibly
+@code{final}) procedures for automatic initialization (and finalization).
The built library should be placed in a directory different from
the object directory.
@item
-Copy the @cite{ALI} files of the interface to the library directory,
+Copy the @code{ALI} files of the interface to the library directory,
add in this copy an indication that it is an interface to a SAL
-(i.e., add a word @emph{SL} on the line in the @code{ALI} file that starts
+(i.e., add a word @code{SL} on the line in the @code{ALI} file that starts
with letter 'P') and make the modified copy of the @code{ALI} file
read-only.
@end itemize
a non-Ada context.
The only extra step required is to ensure that library interface subprograms
-are compatible with the main program, by means of @cite{pragma Export}
-or @cite{pragma Convention}.
+are compatible with the main program, by means of @code{pragma Export}
+or @code{pragma Convention}.
Here is an example of simple library interface for use with C main program:
library interface; remember that it should contain elaboration routines in
addition to interface subprograms.
-The example below shows the content of @cite{mylib_interface.h} (note
+The example below shows the content of @code{mylib_interface.h} (note
that there is no rule for the naming of this file, any name can be used)
@example
@end example
Libraries built as explained above can be used from any program, provided
-that the elaboration procedures (named @cite{mylibinit} in the previous
+that the elaboration procedures (named @code{mylibinit} in the previous
example) are called before the library services are used. Any number of
libraries can be used simultaneously, as long as the elaboration
procedure of each library is called.
-Below is an example of a C program that uses the @cite{mylib} library.
+Below is an example of a C program that uses the @code{mylib} library.
@example
#include "mylib_interface.h"
@end example
Note that invoking any library finalization procedure generated by
-@cite{gnatbind} shuts down the Ada run-time environment.
+@code{gnatbind} shuts down the Ada run-time environment.
Consequently, the
finalization of all Ada libraries must be performed at the end of the program.
No call to these libraries or to the Ada run-time library should be made
@itemize *
@item
-pragma @cite{Locking_Policy}
+pragma @code{Locking_Policy}
@item
-pragma @cite{Partition_Elaboration_Policy}
+pragma @code{Partition_Elaboration_Policy}
@item
-pragma @cite{Queuing_Policy}
+pragma @code{Queuing_Policy}
@item
-pragma @cite{Task_Dispatching_Policy}
+pragma @code{Task_Dispatching_Policy}
@item
-pragma @cite{Unreserve_All_Interrupts}
+pragma @code{Unreserve_All_Interrupts}
@end itemize
When using a library that contains such pragmas, the user must make sure
that all libraries use the same pragmas with the same values. Otherwise,
-@cite{Program_Error} will
+@code{Program_Error} will
be raised during the elaboration of the conflicting
libraries. The usage of these pragmas and its consequences for the user
should therefore be well documented.
Otherwise, Program_Error will be raised during the elaboration of the
conflicting libraries.
-If the @cite{Version} or @cite{Body_Version}
+If the @code{Version} or @code{Body_Version}
attributes are used inside a library, then you need to
-perform a @cite{gnatbind} step that specifies all @code{ALI} files in all
+perform a @code{gnatbind} step that specifies all @code{ALI} files in all
libraries, so that version identifiers can be properly computed.
In practice these attributes are rarely used, so this is unlikely
to be a consideration.
It may be useful to recompile the GNAT library in various contexts, the
most important one being the use of partition-wide configuration pragmas
-such as @cite{Normalize_Scalars}. A special Makefile called
-@cite{Makefile.adalib} is provided to that effect and can be found in
+such as @code{Normalize_Scalars}. A special Makefile called
+@code{Makefile.adalib} is provided to that effect and can be found in
the directory containing the GNAT library. The location of this
directory depends on the way the GNAT environment has been installed and can
be determined by means of the command:
end if;
@end example
-Not only will the code inside the @cite{if} statement not be executed if
-the constant Boolean is @cite{False}, but it will also be completely
+Not only will the code inside the @code{if} statement not be executed if
+the constant Boolean is @code{False}, but it will also be completely
deleted from the program.
-However, the code is only deleted after the @cite{if} statement
+However, the code is only deleted after the @code{if} statement
has been checked for syntactic and semantic correctness.
(In contrast, with preprocessors the code is deleted before the
compiler ever gets to see it, so it is not checked until the switch
end Config;
@end example
-The @cite{Config} package exists in multiple forms for the various targets,
-with an appropriate script selecting the version of @cite{Config} needed.
+The @code{Config} package exists in multiple forms for the various targets,
+with an appropriate script selecting the version of @code{Config} needed.
Then any other unit requiring conditional compilation can do a @emph{with}
-of @cite{Config} to make the constants visible.
+of @code{Config} to make the constants visible.
@node Debugging - A Special Case,Conditionalizing Declarations,Use of Boolean Constants,Modeling Conditional Compilation in Ada
@anchor{gnat_ugn/the_gnat_compilation_model debugging-a-special-case}@anchor{9d}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{9e}
Since this is a common case, there are special features to deal with
this in a convenient manner. For the case of tests, Ada 2005 has added
-a pragma @cite{Assert} that can be used for such tests. This pragma is modeled
-on the @cite{Assert} pragma that has always been available in GNAT, so this
+a pragma @code{Assert} that can be used for such tests. This pragma is modeled
+on the @code{Assert} pragma that has always been available in GNAT, so this
feature may be used with GNAT even if you are not using Ada 2005 features.
-The use of pragma @cite{Assert} is described in the
+The use of pragma @code{Assert} is described in the
@cite{GNAT_Reference_Manual}, but as an
example, the last test could be written:
@end example
In both cases, if assertions are active and the temperature is excessive,
-the exception @cite{Assert_Failure} will be raised, with the given string in
+the exception @code{Assert_Failure} will be raised, with the given string in
the first case or a string indicating the location of the pragma in the second
case used as the exception message.
@geindex pragma Assertion_Policy
-You can turn assertions on and off by using the @cite{Assertion_Policy}
+You can turn assertions on and off by using the @code{Assertion_Policy}
pragma.
@geindex -gnata switch
This is an Ada 2005 pragma which is implemented in all modes by
-GNAT. Alternatively, you can use the @emph{-gnata} switch
+GNAT. Alternatively, you can use the @code{-gnata} switch
to enable assertions from the command line, which applies to
all versions of Ada.
@geindex pragma Debug
-For the example above with the @cite{Put_Line}, the GNAT-specific pragma
-@cite{Debug} can be used:
+For the example above with the @code{Put_Line}, the GNAT-specific pragma
+@code{Debug} can be used:
@example
pragma Debug (Put_Line ("got to the first stage!"));
@end example
If debug pragmas are enabled, the argument, which must be of the form of
-a procedure call, is executed (in this case, @cite{Put_Line} will be called).
+a procedure call, is executed (in this case, @code{Put_Line} will be called).
Only one call can be present, but of course a special debugging procedure
containing any code you like can be included in the program and then
-called in a pragma @cite{Debug} argument as needed.
+called in a pragma @code{Debug} argument as needed.
-One advantage of pragma @cite{Debug} over the @cite{if Debugging then}
-construct is that pragma @cite{Debug} can appear in declarative contexts,
+One advantage of pragma @code{Debug} over the @code{if Debugging then}
+construct is that pragma @code{Debug} can appear in declarative contexts,
such as at the very beginning of a procedure, before local declarations have
been elaborated.
@geindex pragma Debug_Policy
-Debug pragmas are enabled using either the @emph{-gnata} switch that also
+Debug pragmas are enabled using either the @code{-gnata} switch that also
controls assertions, or with a separate Debug_Policy pragma.
The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used
in Ada 95 and Ada 83 programs as well), and is analogous to
-pragma @cite{Assertion_Policy} to control assertions.
+pragma @code{Assertion_Policy} to control assertions.
-@cite{Assertion_Policy} and @cite{Debug_Policy} are configuration pragmas,
+@code{Assertion_Policy} and @code{Debug_Policy} are configuration pragmas,
and thus they can appear in @code{gnat.adc} if you are not using a
project file, or in the file designated to contain configuration pragmas
in a project file.
They then apply to all subsequent compilations. In practice the use of
-the @emph{-gnata} switch is often the most convenient method of controlling
+the @code{-gnata} switch is often the most convenient method of controlling
the status of these pragmas.
Note that a pragma is not a statement, so in contexts where a statement
sequence is required, you can't just write a pragma on its own. You have
-to add a @cite{null} statement.
+to add a @code{null} statement.
@example
if ... then
compiler so this can only be used where both declarations are legal,
even though one of them will not be used.
-Another approach is to define integer constants, e.g., @cite{Bits_Per_Word},
-or Boolean constants, e.g., @cite{Little_Endian}, and then write declarations
+Another approach is to define integer constants, e.g., @code{Bits_Per_Word},
+or Boolean constants, e.g., @code{Little_Endian}, and then write declarations
that are parameterized by these constants. For example
@example
end record;
@end example
-If @cite{Bits_Per_Word} is set to 32, this generates either
+If @code{Bits_Per_Word} is set to 32, this generates either
@example
for Rec use
notation is usable for creating static constants, clever use of this
feature can often solve quite difficult problems in conditionalizing
compilation (note incidentally that in Ada 95, the little endian
-constant was introduced as @cite{System.Default_Bit_Order}, so you do not
+constant was introduced as @code{System.Default_Bit_Order}, so you do not
need to define this one yourself).
@node Use of Alternative Implementations,Preprocessing,Conditionalizing Declarations,Modeling Conditional Compilation in Ada
end if;
@end example
-where @cite{Ada_2005} is a Boolean constant.
+where @code{Ada_2005} is a Boolean constant.
-But this won't work when @cite{Ada_2005} is set to @cite{False},
-since the @cite{then} clause will be illegal for an Ada 95 compiler.
+But this won't work when @code{Ada_2005} is set to @code{False},
+since the @code{then} clause will be illegal for an Ada 95 compiler.
(Recall that although such unreachable code would eventually be deleted
by the compiler, it still needs to be legal. If it uses features
introduced in Ada 2005, it will be illegal in Ada 95.)
procedure Insert is separate;
@end example
-Then we have two files for the subunit @cite{Insert}, with the two sets of
+Then we have two files for the subunit @code{Insert}, with the two sets of
code.
-If the package containing this is called @cite{File_Queries}, then we might
+If the package containing this is called @code{File_Queries}, then we might
have two files
Another style for arranging alternative implementations is through Ada's
access-to-subprogram facility.
In case some functionality is to be conditionally included,
-you can declare an access-to-procedure variable @cite{Ref} that is initialized
-to designate a 'do nothing' procedure, and then invoke @cite{Ref.all}
+you can declare an access-to-procedure variable @code{Ref} that is initialized
+to designate a 'do nothing' procedure, and then invoke @code{Ref.all}
when appropriate.
-In some library package, set @cite{Ref} to @cite{Proc'Access} for some
-procedure @cite{Proc} that performs the relevant processing.
+In some library package, set @code{Ref} to @code{Proc'Access} for some
+procedure @code{Proc} that performs the relevant processing.
The initialization only occurs if the library package is included in the
program.
The same idea can also be implemented using tagged types and dispatching
The preprocessor may be used in two separate modes. It can be used quite
separately from the compiler, to generate a separate output source file
that is then fed to the compiler as a separate step. This is the
-@cite{gnatprep} utility, whose use is fully described in
+@code{gnatprep} utility, whose use is fully described in
@ref{17,,Preprocessing with gnatprep}.
The preprocessing language allows such constructs as
#end if;
@end example
-The values of the symbols @cite{DEBUG} and @cite{PRIORITY} can be
+The values of the symbols @code{DEBUG} and @code{PRIORITY} can be
defined either on the command line or in a separate file.
The other way of running the preprocessor is even closer to the C style and
often more convenient. In this approach the preprocessing is integrated into
the compilation process. The compiler is given the preprocessor input which
-includes @cite{#if} lines etc, and then the compiler carries out the
+includes @code{#if} lines etc, and then the compiler carries out the
preprocessing internally and processes the resulting output.
For more details on this approach, see @ref{18,,Integrated Preprocessing}.
@node Preprocessing with gnatprep,Integrated Preprocessing,Modeling Conditional Compilation in Ada,Conditional Compilation
@anchor{gnat_ugn/the_gnat_compilation_model id54}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{17}
-@subsection Preprocessing with @cite{gnatprep}
+@subsection Preprocessing with @code{gnatprep}
@geindex gnatprep
@geindex Preprocessing (gnatprep)
-This section discusses how to use GNAT's @cite{gnatprep} utility for simple
+This section discusses how to use GNAT's @code{gnatprep} utility for simple
preprocessing.
-Although designed for use with GNAT, @cite{gnatprep} does not depend on any
+Although designed for use with GNAT, @code{gnatprep} does not depend on any
special GNAT features.
For further discussion of conditional compilation in general, see
@ref{16,,Conditional Compilation}.
@node Using gnatprep,Switches for gnatprep,Preprocessing Symbols,Preprocessing with gnatprep
@anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{a8}@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{a9}
-@subsubsection Using @cite{gnatprep}
+@subsubsection Using @code{gnatprep}
-To call @cite{gnatprep} use:
+To call @code{gnatprep} use:
@example
-$ gnatprep [`switches`] `infile` `outfile` [`deffile`]
+$ gnatprep [ switches ] infile outfile [ deffile ]
@end example
where
is the full name of the output file, which is an Ada source
in standard Ada form. When used with GNAT, this file name will
-normally have an @emph{ads} or @emph{adb} suffix.
+normally have an @code{ads} or @code{adb} suffix.
@end table
@item
@table @asis
-@item @emph{deffile}
+@item @code{deffile}
is the full name of a text file containing definitions of
preprocessing symbols to be referenced by the preprocessor. This argument is
-optional, and can be replaced by the use of the @emph{-D} switch.
+optional, and can be replaced by the use of the @code{-D} switch.
@end table
@end itemize
@node Switches for gnatprep,Form of Definitions File,Using gnatprep,Preprocessing with gnatprep
@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatprep}@anchor{aa}@anchor{gnat_ugn/the_gnat_compilation_model id57}@anchor{ab}
-@subsubsection Switches for @cite{gnatprep}
+@subsubsection Switches for @code{gnatprep}
@geindex --version (gnatprep)
Causes both preprocessor lines and the lines deleted
by preprocessing to be retained in the output source as comments marked
-with the special string @cite{"--! "}. This option will result in line numbers
+with the special string @code{"--! "}. This option will result in line numbers
being preserved in the output file.
@end table
@item @code{-D@emph{symbol}[=@emph{value}]}
Defines a new preprocessing symbol with the specified value. If no value is given
-on the command line, then symbol is considered to be @cite{True}. This switch
+on the command line, then symbol is considered to be @code{True}. This switch
can be used in place of a definition file.
@end table
@item @code{-r}
-Causes a @cite{Source_Reference} pragma to be generated that
+Causes a @code{Source_Reference} pragma to be generated that
references the original input file, so that error messages will use
the file name of this original file. The use of this switch implies
that preprocessor lines are not to be removed from the file, so its
-use will force @emph{-b} mode if @emph{-c}
+use will force @code{-b} mode if @code{-c}
has not been specified explicitly.
Note that if the file to be preprocessed contains multiple units, then
-it will be necessary to @cite{gnatchop} the output file from
-@cite{gnatprep}. If a @cite{Source_Reference} pragma is present
+it will be necessary to @code{gnatchop} the output file from
+@code{gnatprep}. If a @code{Source_Reference} pragma is present
in the preprocessed file, it will be respected by
-@cite{gnatchop -r}
+@code{gnatchop -r}
so that the final chopped files will correctly refer to the original
-input source file for @cite{gnatprep}.
+input source file for @code{gnatprep}.
@end table
@geindex -s (gnatprep)
Causes undefined symbols to be treated as having the value FALSE in the context
of a preprocessor test. In the absence of this option, an undefined symbol in
-a @cite{#if} or @cite{#elsif} test will be treated as an error.
+a @code{#if} or @code{#elsif} test will be treated as an error.
@end table
@geindex -v (gnatprep)
Verbose mode: generates more output about work done.
@end table
-Note: if neither @emph{-b} nor @emph{-c} is present,
+Note: if neither @code{-b} nor @code{-c} is present,
then preprocessor lines and
deleted lines are completely removed from the output, unless -r is
specified, in which case -b is assumed.
symbol := value
@end example
-where @cite{symbol} is a preprocessing symbol, and @cite{value} is one of the following:
+where @code{symbol} is a preprocessing symbol, and @code{value} is one of the following:
@itemize *
@node Form of Input Text for gnatprep,,Form of Definitions File,Preprocessing with gnatprep
@anchor{gnat_ugn/the_gnat_compilation_model id59}@anchor{ae}@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{af}
-@subsubsection Form of Input Text for @cite{gnatprep}
+@subsubsection Form of Input Text for @code{gnatprep}
The input text may contain preprocessor conditional inclusion lines,
For the first test (<expression> ::= <symbol>) the symbol must have
either the value true or false, that is to say the right-hand of the
symbol definition must be one of the (case-insensitive) literals
-@cite{True} or @cite{False}. If the value is true, then the
+@code{True} or @code{False}. If the value is true, then the
corresponding lines are included, and if the value is false, they are
excluded.
in the range 0 .. 2**31-1 are supported.
The test (<expression> ::= <symbol>'Defined) is true only if
-the symbol has been defined in the definition file or by a @emph{-D}
+the symbol has been defined in the definition file or by a @code{-D}
switch on the command line. Otherwise, the test is false.
The equality tests are case insensitive, as are all the preprocessor lines.
If the symbol referenced is not defined in the symbol definitions file,
-then the effect depends on whether or not switch @emph{-u}
+then the effect depends on whether or not switch @code{-u}
is specified. If so, then the symbol is treated as if it had the value
false and the test fails. If this switch is not specified, then
it is an error to reference an undefined symbol. It is also an error to
-reference a symbol that is defined with a value other than @cite{True}
-or @cite{False}.
+reference a symbol that is defined with a value other than @code{True}
+or @code{False}.
-The use of the @cite{not} operator inverts the sense of this logical test.
-The @cite{not} operator cannot be combined with the @cite{or} or @cite{and}
+The use of the @code{not} operator inverts the sense of this logical test.
+The @code{not} operator cannot be combined with the @code{or} or @code{and}
operators, without parentheses. For example, "if not X or Y then" is not
allowed, but "if (not X) or Y then" and "if not (X or Y) then" are.
-The @cite{then} keyword is optional as shown
+The @code{then} keyword is optional as shown
-The @cite{#} must be the first non-blank character on a line, but
+The @code{#} must be the first non-blank character on a line, but
otherwise the format is free form. Spaces or tabs may appear between
-the @cite{#} and the keyword. The keywords and the symbols are case
+the @code{#} and the keyword. The keywords and the symbols are case
insensitive as in normal Ada code. Comments may be used on a
preprocessor line, but other than that, no other tokens may appear on a
-preprocessor line. Any number of @cite{elsif} clauses can be present,
-including none at all. The @cite{else} is optional, as in Ada.
+preprocessor line. Any number of @code{elsif} clauses can be present,
+including none at all. The @code{else} is optional, as in Ada.
-The @cite{#} marking the start of a preprocessor line must be the first
+The @code{#} marking the start of a preprocessor line must be the first
non-blank character on the line, i.e., it must be preceded only by
spaces or horizontal tabs.
anywhere within a source line, except in a comment or within a
string literal. The identifier
-following the @cite{$} must match one of the symbols defined in the symbol
+following the @code{$} must match one of the symbols defined in the symbol
definition file, and the result is to substitute the value of the
-symbol in place of @cite{$symbol} in the output file.
+symbol in place of @code{$symbol} in the output file.
Note that although the substitution of strings within a string literal
is not possible, it is possible to have a symbol whose defined value is
-a string literal. So instead of setting XYZ to @cite{hello} and writing:
+a string literal. So instead of setting XYZ to @code{hello} and writing:
@example
Header : String := "$XYZ";
@end example
-you should set XYZ to @cite{"hello"} and write:
+you should set XYZ to @code{"hello"} and write:
@example
Header : String := $XYZ;
As noted above, a file to be preprocessed consists of Ada source code
in which preprocessing lines have been inserted. However,
-instead of using @emph{gnatprep} to explicitly preprocess a file as a separate
+instead of using @code{gnatprep} to explicitly preprocess a file as a separate
step before compilation, you can carry out the preprocessing implicitly
as part of compilation. Such @emph{integrated preprocessing}, which is the common
style with C, is performed when either or both of the following switches
With integrated preprocessing, the output from the preprocessor is not,
by default, written to any external file. Instead it is passed
internally to the compiler. To preserve the result of
-preprocessing in a file, either run @emph{gnatprep}
+preprocessing in a file, either run @code{gnatprep}
in standalone mode or else supply the @code{-gnateG} switch
(described below) to the compiler.
-The @emph{gnatmake} switch @code{-s} should be used with integrated
+The @code{gnatmake} switch @code{-s} should be used with integrated
preprocessing; otherwise the use of a different preprocessor data file
without changing the sources will not cause recompilation.
-Note that the @emph{gnatmake} switch @code{-m} will almost
+Note that the @code{gnatmake} switch @code{-m} will almost
always trigger recompilation for sources that are preprocessed,
-because @emph{gnatmake} cannot compute the checksum of the source after
+because @code{gnatmake} cannot compute the checksum of the source after
preprocessing.
The actual preprocessing function is described in detail in
A preprocessor data file is a text file that contains @emph{preprocessor
control lines}. A preprocessor control line directs the preprocessing of
-either a particular source file, or, analogous to @emph{others} in Ada,
+either a particular source file, or, analogous to @code{others} in Ada,
all sources not specified elsewhere in the preprocessor data file.
A preprocessor control line
can optionally identify a @emph{definition file} that assigns values to
directory as a source directory through the @code{-I} switch; otherwise
the compiler would not find the definition file.
-Finally, switches similar to those of @emph{gnatprep} may optionally appear:
+Finally, switches similar to those of @code{gnatprep} may optionally appear:
@table @asis
@item @code{-D@emph{symbol}=@emph{new_value}}
-Define or redefine @emph{symbol} to have @emph{new_value} as its value.
-The permitted form for @emph{symbol} is either an Ada identifier, or any Ada reserved word
-aside from @cite{if},
-@cite{else}, @cite{elsif}, @cite{end}, @cite{and}, @cite{or} and @cite{then}.
-The permitted form for @cite{new_value} is a literal string, an Ada identifier or any Ada reserved
+Define or redefine @code{symbol} to have @code{new_value} as its value.
+The permitted form for @code{symbol} is either an Ada identifier, or any Ada reserved word
+aside from @code{if},
+@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
+The permitted form for @code{new_value} is a literal string, an Ada identifier or any Ada reserved
word. A symbol declared with this switch replaces a symbol with the
same name defined in a definition file.
@item @code{-u}
-Causes undefined symbols to be treated as having the value @cite{FALSE}
+Causes undefined symbols to be treated as having the value @code{FALSE}
in the context
of a preprocessor test. In the absence of this option, an undefined symbol in
-a @cite{#if} or @cite{#elsif} test will be treated as an error.
+a @code{#if} or @code{#elsif} test will be treated as an error.
@end table
@end table
@item @code{-gnateD@emph{symbol}[=@emph{new_value}]}
-Define or redefine @emph{symbol} to have @emph{new_value} as its value. If no value
-is supplied, then the value of @emph{symbol} is @cite{True}.
-The form of @emph{symbol} is an identifier, following normal Ada (case-insensitive)
-rules for its syntax, and @emph{new_value} is either an arbitrary string between double
+Define or redefine @code{symbol} to have @code{new_value} as its value. If no value
+is supplied, then the value of @code{symbol} is @code{True}.
+The form of @code{symbol} is an identifier, following normal Ada (case-insensitive)
+rules for its syntax, and @code{new_value} is either an arbitrary string between double
quotes or any sequence (including an empty sequence) of characters from the
set (letters, digits, period, underline).
-Ada reserved words may be used as symbols, with the exceptions of @cite{if},
-@cite{else}, @cite{elsif}, @cite{end}, @cite{and}, @cite{or} and @cite{then}.
+Ada reserved words may be used as symbols, with the exceptions of @code{if},
+@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
Examples:
symbol with the same name either in a definition file or specified with a
switch @code{-D} in the preprocessor data file.
-This switch is similar to switch @code{-D} of @cite{gnatprep}.
+This switch is similar to switch @code{-D} of @code{gnatprep}.
@item @code{-gnateG}
Interfacing Ada with a foreign language such as C involves using
compiler directives to import and/or export entity definitions in each
-language -- using @cite{extern} statements in C, for instance, and the
-@cite{Import}, @cite{Export}, and @cite{Convention} pragmas in Ada.
+language -- using @code{extern} statements in C, for instance, and the
+@code{Import}, @code{Export}, and @code{Convention} pragmas in Ada.
A full treatment of these topics is provided in Appendix B, section 1
of the Ada Reference Manual.
@end itemize
Depending on the circumstances (for example when your non-Ada main object
-does not provide symbol @cite{main}), you may also need to instruct the
+does not provide symbol @code{main}), you may also need to instruct the
GNAT linker not to include the standard startup objects by passing the
-@code{-nostartfiles} switch to @cite{gnatlink}.
+@code{-nostartfiles} switch to @code{gnatlink}.
@node Calling Conventions,Building Mixed Ada and C++ Programs,Interfacing to C,Mixed Language Programming
@anchor{gnat_ugn/the_gnat_compilation_model calling-conventions}@anchor{b5}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{b6}
@table @asis
-@item @emph{Ada}
+@item @code{Ada}
This indicates that the standard Ada calling sequence will be
used and all Ada data items may be passed without any limitations in the
@table @asis
-@item @emph{Assembler}
+@item @code{Assembler}
Specifies assembler as the convention. In practice this has the
same effect as convention Ada (but is not equivalent in the sense of being
@table @asis
-@item @emph{Asm}
+@item @code{Asm}
Equivalent to Assembler.
@table @asis
-@item @emph{COBOL}
+@item @code{COBOL}
Data will be passed according to the conventions described
in section B.4 of the Ada Reference Manual.
@table @asis
-@item @emph{C}
+@item @code{C}
Data will be passed according to the conventions described
in section B.3 of the Ada Reference Manual.
@geindex varargs function interfaces
-In C, @cite{varargs} allows a function to take a variable number of
+In C, @code{varargs} allows a function to take a variable number of
arguments. There is no direct equivalent in this to Ada. One
approach that can be used is to create a C wrapper for each
different profile and then interface to this C wrapper. For
-example, to print an @cite{int} value using @cite{printf},
-create a C function @cite{printfi} that takes two arguments, a
-pointer to a string and an int, and calls @cite{printf}.
-Then in the Ada program, use pragma @cite{Import} to
-interface to @cite{printfi}.
+example, to print an @code{int} value using @code{printf},
+create a C function @code{printfi} that takes two arguments, a
+pointer to a string and an int, and calls @code{printf}.
+Then in the Ada program, use pragma @code{Import} to
+interface to @code{printfi}.
It may work on some platforms to directly interface to
-a @cite{varargs} function by providing a specific Ada profile
+a @code{varargs} function by providing a specific Ada profile
for a particular call. However, this does not work on
all platforms, since there is no guarantee that the
calling sequence for a two argument normal C function
-is the same as for calling a @cite{varargs} C function with
+is the same as for calling a @code{varargs} C function with
the same two arguments.
@end quotation
@end table
@table @asis
-@item @emph{Default}
+@item @code{Default}
Equivalent to C.
@end table
@table @asis
-@item @emph{External}
+@item @code{External}
Equivalent to C.
@end table
@table @asis
-@item @emph{C_Plus_Plus (or CPP)}
+@item @code{C_Plus_Plus} (or @code{CPP})
This stands for C++. For most purposes this is identical to C.
See the separate description of the specialized GNAT pragmas relating to
@table @asis
-@item @emph{Fortran}
+@item @code{Fortran}
Data will be passed according to the conventions described
in section B.5 of the Ada Reference Manual.
-@item @emph{Intrinsic}
+@item @code{Intrinsic}
This applies to an intrinsic operation, as defined in the Ada
Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram,
General subprogram entities. This is used to bind an Ada subprogram
declaration to
a compiler builtin by name with back-ends where such interfaces are
-available. A typical example is the set of @cite{__builtin} functions
+available. A typical example is the set of @code{__builtin} functions
exposed by the GCC back-end, as in the following example:
@example
@table @asis
-@item @emph{Stdcall}
+@item @code{Stdcall}
This is relevant only to Windows implementations of GNAT,
-and specifies that the @cite{Stdcall} calling sequence will be used,
+and specifies that the @code{Stdcall} calling sequence will be used,
as defined by the NT API. Nevertheless, to ease building
-cross-platform bindings this convention will be handled as a @cite{C} calling
+cross-platform bindings this convention will be handled as a @code{C} calling
convention on non-Windows platforms.
@end table
@table @asis
-@item @emph{DLL}
+@item @code{DLL}
-This is equivalent to @cite{Stdcall}.
+This is equivalent to @code{Stdcall}.
@end table
@geindex Win32
@table @asis
-@item @emph{Win32}
+@item @code{Win32}
-This is equivalent to @cite{Stdcall}.
+This is equivalent to @code{Stdcall}.
@end table
@geindex Stubbed
@table @asis
-@item @emph{Stubbed}
+@item @code{Stubbed}
This is a special convention that indicates that the compiler
-should provide a stub body that raises @cite{Program_Error}.
+should provide a stub body that raises @code{Program_Error}.
@end table
-GNAT additionally provides a useful pragma @cite{Convention_Identifier}
+GNAT additionally provides a useful pragma @code{Convention_Identifier}
that can be used to parameterize conventions and allow additional synonyms
to be specified. For example if you have legacy code in which the convention
identifier Fortran77 was used for Fortran, you can use the configuration
@end example
And from now on the identifier Fortran77 may be used as a convention
-identifier (for example in an @cite{Import} pragma) with the same
+identifier (for example in an @code{Import} pragma) with the same
meaning as Fortran.
@node Building Mixed Ada and C++ Programs,Generating Ada Bindings for C and C++ headers,Calling Conventions,Mixed Language Programming
Interface ---see @indicateurl{http://www.codesourcery.com/archives/cxx-abi}).
Interfacing can be done at 3 levels: simple data, subprograms, and
-classes. In the first two cases, GNAT offers a specific @cite{Convention C_Plus_Plus}
-(or @cite{CPP}) that behaves exactly like @cite{Convention C}.
+classes. In the first two cases, GNAT offers a specific @code{Convention C_Plus_Plus}
+(or @code{CPP}) that behaves exactly like @code{Convention C}.
Usually, C++ mangles the names of subprograms. To generate proper mangled
names automatically, see @ref{19,,Generating Ada Bindings for C and C++ headers}).
This problem can also be addressed manually in two ways:
@item
by modifying the C++ code in order to force a C convention using
-the @cite{extern "C"} syntax.
+the @code{extern "C"} syntax.
@item
-by figuring out the mangled name (using e.g. @emph{nm}) and using it as the
+by figuring out the mangled name (using e.g. @code{nm}) and using it as the
Link_Name argument of the pragma import.
@end itemize
Interfacing at the class level can be achieved by using the GNAT specific
-pragmas such as @cite{CPP_Constructor}. See the @cite{GNAT_Reference_Manual} for additional information.
+pragmas such as @code{CPP_Constructor}. See the @cite{GNAT_Reference_Manual} for additional information.
@node Linking a Mixed C++ & Ada Program,A Simple Example,Interfacing to C++,Building Mixed Ada and C++ Programs
@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-ada-program}@anchor{bb}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{bc}
@item
Using GNAT and G++ (GNU C++ compiler) from the same GCC installation:
The C++ linker can simply be called by using the C++ specific driver
-called @cite{g++}.
+called @code{g++}.
Note that if the C++ code uses inline functions, you will need to
-compile your C++ code with the @cite{-fkeep-inline-functions} switch in
+compile your C++ code with the @code{-fkeep-inline-functions} switch in
order to provide an existing function implementation that the Ada code can
link with.
improperly if set during invocation of the wrong compiler. It is also
very important that the linker uses the proper @code{libgcc.a} GCC
library -- that is, the one from the C++ compiler installation. The
-implicit link command as suggested in the @cite{gnatmake} command
+implicit link command as suggested in the @code{gnatmake} command
from the former example can be replaced by an explicit link command with
the full-verbosity option in order to verify which library is used:
a few more parameters to the link command line, depending on the exception
mechanism used.
-If the @cite{setjmp/longjmp} exception mechanism is used, only the paths
-to the libgcc libraries are required:
+If the @code{setjmp} / @code{longjmp} exception mechanism is used, only the paths
+to the @code{libgcc} libraries are required:
@example
$ cat ./my_script
#!/bin/sh
-CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a`
+CC $* gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
@end example
where CC is the name of the non-GNU C++ compiler.
-If the @cite{zero cost} exception mechanism is used, and the platform
+If the "zero cost" exception mechanism is used, and the platform
supports automatic registration of exception tables (e.g., Solaris),
paths to more objects are required:
@example
$ cat ./my_script
#!/bin/sh
-CC `gcc -print-file-name=crtbegin.o` $* \\
-`gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \\
-`gcc -print-file-name=crtend.o`
+CC gcc -print-file-name=crtbegin.o $* \\
+gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a \\
+gcc -print-file-name=crtend.o
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
@end example
In order to interface with C++ constructors GNAT provides the
-@cite{pragma CPP_Constructor} (see the @cite{GNAT_Reference_Manual}
+@code{pragma CPP_Constructor} (see the @cite{GNAT_Reference_Manual}
for additional information).
In this section we present some common uses of C++ constructors
in mixed-languages programs in GNAT.
@itemize *
@item
-On the right side of an initialization of an object of type @cite{T}.
+On the right side of an initialization of an object of type @code{T}.
@item
-On the right side of an initialization of a record component of type @cite{T}.
+On the right side of an initialization of a record component of type @code{T}.
@item
In an Ada 2005 limited aggregate.
The first two declarations are equivalent: in both cases the default C++
constructor is invoked (in the former case the call to the constructor is
implicit, and in the latter case the call is explicit in the object
-declaration). @cite{Obj3} is initialized by the C++ non-default constructor
-that takes an integer argument, and @cite{Obj4} is initialized by the
+declaration). @code{Obj3} is initialized by the C++ non-default constructor
+that takes an integer argument, and @code{Obj4} is initialized by the
non-default C++ constructor that takes two integers.
Let us derive the imported C++ class in the Ada side. For example:
Obj7 : DT := (Constructor (30,40) with C_Value => 50);
@end example
-The declaration of @cite{Obj5} invokes the default constructors: the
+The declaration of @code{Obj5} invokes the default constructors: the
C++ default constructor of the parent type takes care of the initialization
of the components inherited from Root, and GNAT takes care of the default
initialization of the additional Ada components of type DT (that is,
-@cite{C_Value} is initialized to value 2009). The order of invocation of
+@code{C_Value} is initialized to value 2009). The order of invocation of
the constructors is consistent with the order of elaboration required by
Ada and C++. That is, the constructor of the parent type is always called
before the constructor of the derived type.
end record;
@end example
-The initialization of an object of type @cite{Rec2} will call the
+The initialization of an object of type @code{Rec2} will call the
non-default C++ constructors specified for the imported components.
For example:
@end example
The above declaration uses an Ada 2005 limited aggregate to
-initialize @cite{Obj9}, and the C++ constructor that has two integer
-arguments is invoked to initialize the @cite{Data1} component instead
-of the constructor specified in the declaration of type @cite{Rec1}. In
+initialize @code{Obj9}, and the C++ constructor that has two integer
+arguments is invoked to initialize the @code{Data1} component instead
+of the constructor specified in the declaration of type @code{Rec1}. In
Ada 2005 the box in the aggregate indicates that unspecified components
are initialized using the expression (if any) available in the component
-declaration. That is, in this case discriminant @cite{D} is initialized
-to value @cite{20}, @cite{Value} is initialized to value 1000, and the
+declaration. That is, in this case discriminant @code{D} is initialized
+to value @code{20}, @code{Value} is initialized to value 1000, and the
non-default C++ constructor that handles two integers takes care of
-initializing component @cite{Data2} with values @cite{20@comma{}30}.
+initializing component @code{Data2} with values @code{20,30}.
In Ada 2005 we can use the extended return statement to build the Ada
equivalent to C++ non-default constructors. For example:
constructors are defined on the C++ side and imported from the Ada
side, and latter the reverse case.
-The root of our derivation will be the @cite{Animal} class, with a
-single private attribute (the @cite{Age} of the animal), a constructor,
+The root of our derivation will be the @code{Animal} class, with a
+single private attribute (the @code{Age} of the animal), a constructor,
and two public primitives to set and get the value of this attribute.
@example
Abstract interface types are defined in C++ by means of classes with pure
virtual functions and no data members. In our example we will use two
-interfaces that provide support for the common management of @cite{Carnivore}
-and @cite{Domestic} animals:
+interfaces that provide support for the common management of @code{Carnivore}
+and @code{Domestic} animals:
@example
class Carnivore @{
@};
@end example
-Using these declarations, we can now say that a @cite{Dog} is an animal that is
+Using these declarations, we can now say that a @code{Dog} is an animal that is
both Carnivore and Domestic, that is:
@example
@end example
In the following examples we will assume that the previous declarations are
-located in a file named @cite{animals.h}. The following package demonstrates
+located in a file named @code{animals.h}. The following package demonstrates
how to import these C++ declarations from the Ada side:
@example
the two languages.
Regarding the abstract interfaces, we must indicate to the GNAT compiler by
-means of a @cite{pragma Convention (C_Plus_Plus)}, the convention used to pass
+means of a @code{pragma Convention (C_Plus_Plus)}, the convention used to pass
the arguments to the called primitives will be the same as for C++. For the
-imported classes we use @cite{pragma Import} with convention @cite{C_Plus_Plus}
+imported classes we use @code{pragma Import} with convention @code{C_Plus_Plus}
to indicate that they have been defined on the C++ side; this is required
because the dispatch table associated with these tagged types will be built
in the C++ side and therefore will not contain the predefined Ada primitives
associated with each subprogram because it is assumed that all the calls to
these primitives will be dispatching calls. The only exception is the
constructor, which must be registered with the compiler by means of
-@cite{pragma CPP_Constructor} and needs to provide its associated C++
+@code{pragma CPP_Constructor} and needs to provide its associated C++
mangled name because the Ada compiler generates direct calls to it.
With the above packages we can now declare objects of type Dog on the Ada side
@end example
Compared with our previous example the only differences are the use of
-@cite{pragma Convention} (instead of @cite{pragma Import}), and the use of
-@cite{pragma Export} to indicate to the GNAT compiler that the primitives will
+@code{pragma Convention} (instead of @code{pragma Import}), and the use of
+@code{pragma Export} to indicate to the GNAT compiler that the primitives will
be available to C++. Thanks to the ABI compatibility, on the C++ side there is
nothing else to be done; as explained above, the only requirement is that all
the primitives and components are declared in exactly the same order.
For completeness, let us see a brief C++ main program that uses the
-declarations available in @cite{animals.h} (presented in our first example) to
+declarations available in @code{animals.h} (presented in our first example) to
import and use the declarations from the Ada side, properly initializing and
finalizing the Ada run-time system along the way:
@item
identifiers with identical name (except casing) will generate compilation
-errors (e.g. @cite{shm_get} vs @cite{SHM_GET}).
+errors (e.g. @code{shm_get} vs @code{SHM_GET}).
@end itemize
The code generated is using the Ada 2005 syntax, which makes it
@subsubsection Running the Binding Generator
-The binding generator is part of the @emph{gcc} compiler and can be
-invoked via the @emph{-fdump-ada-spec} switch, which will generate Ada
+The binding generator is part of the @code{gcc} compiler and can be
+invoked via the @code{-fdump-ada-spec} switch, which will generate Ada
spec files for the header files specified on the command line, and all
header files needed by these files transitively. For example:
will generate, under GNU/Linux, the following files: @code{time_h.ads},
@code{bits_time_h.ads}, @code{stddef_h.ads}, @code{bits_types_h.ads} which
correspond to the files @code{/usr/include/time.h},
-@code{/usr/include/bits/time.h}, etc..., and will then compile in Ada 2005
-mode these Ada specs.
+@code{/usr/include/bits/time.h}, etc..., and will then compile these Ada specs
+in Ada 2005 mode.
-The @cite{-C} switch tells @emph{gcc} to extract comments from headers,
+The @code{-C} switch tells @code{gcc} to extract comments from headers,
and will attempt to generate corresponding Ada comments.
If you want to generate a single Ada file and not the transitive closure, you
-can use instead the @emph{-fdump-ada-spec-slim} switch.
+can use instead the @code{-fdump-ada-spec-slim} switch.
You can optionally specify a parent unit, of which all generated units will
-be children, using @cite{-fada-spec-parent=<unit>}.
+be children, using @code{-fada-spec-parent=@emph{unit}}.
Note that we recommend when possible to use the @emph{g++} driver to
generate bindings, even for most C headers, since this will in general
mandatory to use the @emph{g++} command, or @emph{gcc -x c++} which
is equivalent in this case. If @emph{g++} cannot work on your C headers
because of incompatibilities between C and C++, then you can fallback to
-@emph{gcc} instead.
+@code{gcc} instead.
For an example of better bindings generated from the C++ front-end,
the name of the parameters (when available) are actually ignored by the C
extern void foo (int variable);
@end example
-with the C front-end, @cite{variable} is ignored, and the above is handled as:
+with the C front-end, @code{variable} is ignored, and the above is handled as:
@example
extern void foo (int);
@end example
In some cases, the generated bindings will be more complete or more meaningful
-when defining some macros, which you can do via the @emph{-D} switch. This
+when defining some macros, which you can do via the @code{-D} switch. This
is for example the case with @code{Xlib.h} under GNU/Linux:
@example
@end example
The above will generate more complete bindings than a straight call without
-the @emph{-DXLIB_ILLEGAL_ACCESS} switch.
+the @code{-DXLIB_ILLEGAL_ACCESS} switch.
In other cases, it is not possible to parse a header file in a stand-alone
manner, because other include files need to be included first. In this
case, the solution is to create a small header file including the needed
-@cite{#include} and possible @cite{#define} directives. For example, to
+@code{#include} and possible @code{#define} directives. For example, to
generate Ada bindings for @code{readline/readline.h}, you need to first
include @code{stdio.h}, so you can create a file with the following two
lines in e.g. @code{readline1.h}:
bindings by hand more extensively when using C++ headers.
In this mode, C++ classes will be mapped to Ada tagged types, constructors
-will be mapped using the @cite{CPP_Constructor} pragma, and when possible,
+will be mapped using the @code{CPP_Constructor} pragma, and when possible,
multiple inheritance of abstract classes will be mapped to Ada interfaces
(see the @emph{Interfacing to C++} section in the @cite{GNAT Reference Manual}
for additional information on interfacing to C++).
@item @code{-fada-spec-parent=@emph{unit}}
-Specifies that all files generated by @emph{-fdump-ada-spec*} are
+Specifies that all files generated by @code{-fdump-ada-spec} are
to be child units of the specified parent unit.
@end table
The C header generator is part of the GNAT compiler and can be invoked via
-the @emph{-gnatceg} combination of switches, which will generate a @code{.h}
+the @code{-gnatceg} combination of switches, which will generate a @code{.h}
file corresponding to the given input file (Ada spec or body). Note that
only spec files are processed in any case, so giving a spec or a body file
as input is equivalent. For example:
end Pack1;
@end example
-The above @cite{gcc} command will generate the following @code{pack1.h} file:
+The above @code{gcc} command will generate the following @code{pack1.h} file:
@example
/* Standard definitions skipped */
#endif /* PACK1_ADS */
@end example
-You can then @cite{include} @code{pack1.h} from a C source file and use the types,
+You can then @code{include} @code{pack1.h} from a C source file and use the types,
call subprograms, reference objects, and constants.
@node GNAT and Other Compilation Models,Using GNAT Files with External Tools,Mixed Language Programming,The GNAT Compilation Model
The GNAT model of compilation is close to the C and C++ models. You can
think of Ada specs as corresponding to header files in C. As in C, you
don't need to compile specs; they are compiled when they are used. The
-Ada @emph{with} is similar in effect to the @cite{#include} of a C
+Ada @emph{with} is similar in effect to the @code{#include} of a C
header.
One notable difference is that, in Ada, you may compile specs separately
issues. There are also elaboration issues in C++ that are handled
automatically. This automatic handling has the advantage of being
simpler to use, but the C++ programmer has no control over elaboration.
-Where @cite{gnatbind} might complain there was no valid order of
+Where @code{gnatbind} might complain there was no valid order of
elaboration, a C++ compiler would simply construct a program that
malfunctioned at run time.
@geindex pragma Export
-The variable @cite{MN} has a full expanded Ada name of @cite{QRS.MN}, so
-the corresponding link name is @cite{qrs__mn}.
-Of course if a @cite{pragma Export} is used this may be overridden:
+The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so
+the corresponding link name is @code{qrs__mn}.
+Of course if a @code{pragma Export} is used this may be overridden:
@example
package Exports is
end Exports;
@end example
-In this case, the link name for @cite{Var1} is whatever link name the
-C compiler would assign for the C function @cite{var1_name}. This typically
-would be either @cite{var1_name} or @cite{_var1_name}, depending on operating
+In this case, the link name for @code{Var1} is whatever link name the
+C compiler would assign for the C function @code{var1_name}. This typically
+would be either @code{var1_name} or @code{_var1_name}, depending on operating
system conventions, but other possibilities exist. The link name for
-@cite{Var2} is @cite{var2_link_name}, and this is not operating system
+@code{Var2} is @code{var2_link_name}, and this is not operating system
dependent.
One exception occurs for library level procedures. A potential ambiguity
-arises between the required name @cite{_main} for the C main program,
+arises between the required name @code{_main} for the C main program,
and the name we would otherwise assign to an Ada library level procedure
-called @cite{Main} (which might well not be the main program).
+called @code{Main} (which might well not be the main program).
-To avoid this ambiguity, we attach the prefix @cite{_ada_} to such
+To avoid this ambiguity, we attach the prefix @code{_ada_} to such
names. So if we have a library level procedure such as:
@example
procedure Hello (S : String);
@end example
-the external name of this procedure will be @cite{_ada_hello}.
+the external name of this procedure will be @code{_ada_hello}.
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
@node Building with gnatmake,Compiling with gcc,,Building Executable Programs with GNAT
@anchor{gnat_ugn/building_executable_programs_with_gnat the-gnat-make-program-gnatmake}@anchor{1b}@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{d9}
-@section Building with @emph{gnatmake}
+@section Building with @code{gnatmake}
@geindex gnatmake
The third step in particular can be tricky, because not only do the modified
files have to be compiled, but any files depending on these files must also be
recompiled. The dependency rules in Ada can be quite complex, especially
-in the presence of overloading, @cite{use} clauses, generics and inlined
+in the presence of overloading, @code{use} clauses, generics and inlined
subprograms.
-@emph{gnatmake} automatically takes care of the third and fourth steps
+@code{gnatmake} automatically takes care of the third and fourth steps
of this process. It determines which sources need to be compiled,
compiles them, and binds and links the resulting object files.
the GNAT compilation model makes this possible. This means that if
changes to the source program cause corresponding changes in
dependencies, they will always be tracked exactly correctly by
-@emph{gnatmake}.
+@code{gnatmake}.
Note that for advanced forms of project structure, we recommend creating
a project file as explained in the @emph{GNAT_Project_Manager} chapter in the
@emph{GPRbuild User's Guide}, and using the
-@emph{gprbuild} tool which supports building with project files and works similarly
-to @emph{gnatmake}.
+@code{gprbuild} tool which supports building with project files and works similarly
+to @code{gnatmake}.
@menu
* Running gnatmake::
@node Running gnatmake,Switches for gnatmake,,Building with gnatmake
@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{da}@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{db}
-@subsection Running @emph{gnatmake}
+@subsection Running @code{gnatmake}
-The usual form of the @emph{gnatmake} command is
+The usual form of the @code{gnatmake} command is
@example
$ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>]
@end example
-The only required argument is one @cite{file_name}, which specifies
-a compilation unit that is a main program. Several @cite{file_names} can be
+The only required argument is one @code{file_name}, which specifies
+a compilation unit that is a main program. Several @code{file_names} can be
specified: this will result in several executables being built.
-If @cite{switches} are present, they can be placed before the first
-@cite{file_name}, between @cite{file_names} or after the last @cite{file_name}.
-If @cite{mode_switches} are present, they must always be placed after
-the last @cite{file_name} and all @cite{switches}.
+If @code{switches} are present, they can be placed before the first
+@code{file_name}, between @code{file_names} or after the last @code{file_name}.
+If @code{mode_switches} are present, they must always be placed after
+the last @code{file_name} and all @code{switches}.
If you are using standard file extensions (@code{.adb} and
@code{.ads}), then the
-extension may be omitted from the @cite{file_name} arguments. However, if
+extension may be omitted from the @code{file_name} arguments. However, if
you are using non-standard extensions, then it is required that the
extension be given. A relative or absolute directory path can be
-specified in a @cite{file_name}, in which case, the input source file will
+specified in a @code{file_name}, in which case, the input source file will
be searched for in the specified directory only. Otherwise, the input
source file will first be searched in the directory where
-@emph{gnatmake} was invoked and if it is not found, it will be search on
+@code{gnatmake} was invoked and if it is not found, it will be search on
the source path of the compiler as described in
@ref{89,,Search Paths and the Run-Time Library (RTL)}.
-All @emph{gnatmake} output (except when you specify @emph{-M}) is sent to
+All @code{gnatmake} output (except when you specify @code{-M}) is sent to
@code{stderr}. The output produced by the
-@emph{-M} switch is sent to @code{stdout}.
+@code{-M} switch is sent to @code{stdout}.
@node Switches for gnatmake,Mode Switches for gnatmake,Running gnatmake,Building with gnatmake
@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatmake}@anchor{dc}@anchor{gnat_ugn/building_executable_programs_with_gnat id3}@anchor{dd}
-@subsection Switches for @emph{gnatmake}
+@subsection Switches for @code{gnatmake}
-You may specify any of the following switches to @emph{gnatmake}:
+You may specify any of the following switches to @code{gnatmake}:
@geindex --version (gnatmake)
@item @code{--GCC=@emph{compiler_name}}
Program used for compiling. The default is @code{gcc}. You need to use
-quotes around @cite{compiler_name} if @cite{compiler_name} contains
+quotes around @code{compiler_name} if @code{compiler_name} contains
spaces or other separator characters.
As an example @code{--GCC="foo -x -y"}
-will instruct @emph{gnatmake} to use @code{foo -x -y} as your
+will instruct @code{gnatmake} to use @code{foo -x -y} as your
compiler. A limitation of this syntax is that the name and path name of
the executable itself must not include any embedded spaces. Note that
switch @code{-c} is always inserted after your command name. Thus in the
-above example the compiler command that will be used by @emph{gnatmake}
+above example the compiler command that will be used by @code{gnatmake}
will be @code{foo -c -x -y}. If several @code{--GCC=compiler_name} are
-used, only the last @cite{compiler_name} is taken into account. However,
+used, only the last @code{compiler_name} is taken into account. However,
all the additional switches are also taken into account. Thus,
@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to
@code{--GCC="bar -x -y -z -t"}.
@item @code{--GNATBIND=@emph{binder_name}}
Program used for binding. The default is @code{gnatbind}. You need to
-use quotes around @cite{binder_name} if @cite{binder_name} contains spaces
+use quotes around @code{binder_name} if @code{binder_name} contains spaces
or other separator characters.
As an example @code{--GNATBIND="bar -x -y"}
-will instruct @emph{gnatmake} to use @cite{bar -x -y} as your
-binder. Binder switches that are normally appended by @emph{gnatmake}
-to @code{gnatbind} are now appended to the end of @cite{bar -x -y}.
+will instruct @code{gnatmake} to use @code{bar -x -y} as your
+binder. Binder switches that are normally appended by @code{gnatmake}
+to @code{gnatbind} are now appended to the end of @code{bar -x -y}.
A limitation of this syntax is that the name and path name of the executable
itself must not include any embedded spaces.
@end table
@item @code{--GNATLINK=@emph{linker_name}}
Program used for linking. The default is @code{gnatlink}. You need to
-use quotes around @cite{linker_name} if @cite{linker_name} contains spaces
+use quotes around @code{linker_name} if @code{linker_name} contains spaces
or other separator characters.
As an example @code{--GNATLINK="lan -x -y"}
-will instruct @emph{gnatmake} to use @code{lan -x -y} as your
+will instruct @code{gnatmake} to use @code{lan -x -y} as your
linker. Linker switches that are normally appended by @code{gnatmake} to
@code{gnatlink} are now appended to the end of @code{lan -x -y}.
A limitation of this syntax is that the name and path name of the executable
long time. If the source info file exists but cannot be parsed successfully,
the Project Manager will attempt to recreate it. If the Project Manager fails
to create the source info file, a message is issued, but gnatmake does not
-fail. @emph{gnatmake} "trusts" the source info file. This means that
+fail. @code{gnatmake} "trusts" the source info file. This means that
if the source files have changed (addition, deletion, moving to a different
source directory), then the source info file need to be deleted and recreated.
@end table
files (for example, the predefined Ada library files), as well as any
locked files. Locked files are files whose ALI file is write-protected.
By default,
-@emph{gnatmake} does not check these files,
+@code{gnatmake} does not check these files,
because the assumption is that the GNAT internal files are properly up
to date, and also that any write protected ALI files have been properly
installed. Note that if there is an installation problem, such that one
in conjunction with @code{-f}
if you need to recompile an entire application,
including run-time files, using special configuration pragmas,
-such as a @cite{Normalize_Scalars} pragma.
+such as a @code{Normalize_Scalars} pragma.
By default
@code{gnatmake -a} compiles all GNAT
@item @code{-b}
-Bind only. Can be combined with @emph{-c} to do
+Bind only. Can be combined with @code{-c} to do
compilation and binding, but no link.
-Can be combined with @emph{-l}
+Can be combined with @code{-l}
to do binding and linking. When not combined with
-@emph{-c}
+@code{-c}
all the units in the closure of the main program must have been previously
-compiled and must be up to date. The root unit specified by @cite{file_name}
+compiled and must be up to date. The root unit specified by @code{file_name}
may be given without extension, with the source extension or, if no GNAT
Project File is specified, with the ALI file extension.
@end table
@item @code{-c}
-Compile only. Do not perform binding, except when @emph{-b}
+Compile only. Do not perform binding, except when @code{-b}
is also specified. Do not perform linking, except if both
-@emph{-b} and
-@emph{-l} are also specified.
-If the root unit specified by @cite{file_name} is not a main unit, this is the
-default. Otherwise @emph{gnatmake} will attempt binding and linking
+@code{-b} and
+@code{-l} are also specified.
+If the root unit specified by @code{file_name} is not a main unit, this is the
+default. Otherwise @code{gnatmake} will attempt binding and linking
unless all objects are up to date and the executable is more recent than
the objects.
@end table
full directory information). A mapping file can make the compiler's
file searches faster, especially if there are many source directories,
or the sources are read over a slow network connection. If
-@emph{-P} is used, a mapping file is always used, so
-@emph{-C} is unnecessary; in this case the mapping file
+@code{-P} is used, a mapping file is always used, so
+@code{-C} is unnecessary; in this case the mapping file
is initially populated based on the project file. If
-@emph{-C} is used without
-@emph{-P},
+@code{-C} is used without
+@code{-P},
the mapping file is initially empty. Each invocation of the compiler
will add any newly accessed sources to the mapping file.
@end table
@item @code{-D @emph{dir}}
-Put all object files and ALI file in directory @cite{dir}.
-If the @emph{-D} switch is not used, all object files
+Put all object files and ALI file in directory @code{dir}.
+If the @code{-D} switch is not used, all object files
and ALI files go in the current working directory.
This switch cannot be used when using a project file.
Indicates that the main source is a multi-unit source and the rank of the unit
in the source file is nnn. nnn needs to be a positive number and a valid
-index in the source. This switch cannot be used when @emph{gnatmake} is
+index in the source. This switch cannot be used when @code{gnatmake} is
invoked for several mains.
@end table
Force recompilations. Recompile all sources, even though some object
files may be up to date, but don't recompile predefined or GNAT internal
files or locked files (files with a write-protected ALI file),
-unless the @emph{-a} switch is also specified.
+unless the @code{-a} switch is also specified.
@end table
@geindex -F (gnatmake)
@item @code{-i}
-In normal mode, @emph{gnatmake} compiles all object files and ALI files
-into the current directory. If the @emph{-i} switch is used,
+In normal mode, @code{gnatmake} compiles all object files and ALI files
+into the current directory. If the @code{-i} switch is used,
then instead object files and ALI files that already exist are overwritten
in place. This means that once a large project is organized into separate
-directories in the desired manner, then @emph{gnatmake} will automatically
+directories in the desired manner, then @code{gnatmake} will automatically
maintain and update this organization. If no ALI files are found on the
Ada object path (see @ref{89,,Search Paths and the Run-Time Library (RTL)}),
the new object and ALI files are created in the
directory containing the source being compiled. If another organization
is desired, where objects and sources are kept in different directories,
a useful technique is to create dummy ALI files in the desired directories.
-When detecting such a dummy file, @emph{gnatmake} will be forced to
+When detecting such a dummy file, @code{gnatmake} will be forced to
recompile the corresponding source file, and it will be put the resulting
object and ALI files in the directory where it found the dummy file.
@end table
@item @code{-j@emph{n}}
-Use @cite{n} processes to carry out the (re)compilations. On a multiprocessor
-machine compilations will occur in parallel. If @cite{n} is 0, then the
+Use @code{n} processes to carry out the (re)compilations. On a multiprocessor
+machine compilations will occur in parallel. If @code{n} is 0, then the
maximum number of parallel compilations is the number of core processors
on the platform. In the event of compilation errors, messages from various
-compilations might get interspersed (but @emph{gnatmake} will give you the
+compilations might get interspersed (but @code{gnatmake} will give you the
full ordered list of failing compiles at the end). If this is problematic,
rerun the make process with n set to 1 to get a clean list of messages.
@end table
Keep going. Continue as much as possible after a compilation error. To
ease the programmer's task in case of compilation errors, the list of
-sources for which the compile fails is given when @emph{gnatmake}
+sources for which the compile fails is given when @code{gnatmake}
terminates.
-If @emph{gnatmake} is invoked with several @code{file_names} and with this
+If @code{gnatmake} is invoked with several @code{file_names} and with this
switch, if there are compilation errors when building an executable,
-@emph{gnatmake} will not attempt to build the following executables.
+@code{gnatmake} will not attempt to build the following executables.
@end table
@geindex -l (gnatmake)
@item @code{-l}
-Link only. Can be combined with @emph{-b} to binding
+Link only. Can be combined with @code{-b} to binding
and linking. Linking will not be performed if combined with
-@emph{-c}
-but not with @emph{-b}.
-When not combined with @emph{-b}
+@code{-c}
+but not with @code{-b}.
+When not combined with @code{-b}
all the units in the closure of the main program must have been previously
compiled and must be up to date, and the main program needs to have been bound.
-The root unit specified by @cite{file_name}
+The root unit specified by @code{file_name}
may be given without extension, with the source extension or, if no GNAT
Project File is specified, with the ALI file extension.
@end table
@item @code{-m}
Specify that the minimum necessary amount of recompilations
-be performed. In this mode @emph{gnatmake} ignores time
+be performed. In this mode @code{gnatmake} ignores time
stamp differences when the only
modifications to a source file consist in adding/removing comments,
empty lines, spaces or tabs. This means that if you have changed the
comments in a source file or have simply reformatted it, using this
-switch will tell @emph{gnatmake} not to recompile files that depend on it
+switch will tell @code{gnatmake} not to recompile files that depend on it
(provided other sources on which these files depend have undergone no
semantic modifications). Note that the debugging information may be
-out of date with respect to the sources if the @emph{-m} switch causes
+out of date with respect to the sources if the @code{-m} switch causes
a compilation to be switched, so the use of this switch represents a
trade-off between compilation time and accurate debugging information.
@end table
dependences to @code{stdout} in a form that can be directly exploited in
a @code{Makefile}. By default, each source file is prefixed with its
(relative or absolute) directory name. This name is whatever you
-specified in the various @emph{-aI}
-and @emph{-I} switches. If you use
-@cite{gnatmake -M} @emph{-q}
+specified in the various @code{-aI}
+and @code{-I} switches. If you use
+@code{gnatmake -M} @code{-q}
(see below), only the source file names,
-without relative paths, are output. If you just specify the @emph{-M}
+without relative paths, are output. If you just specify the @code{-M}
switch, dependencies of the GNAT internal system files are omitted. This
is typically what you want. If you also specify
-the @emph{-a} switch,
+the @code{-a} switch,
dependencies of the GNAT internal files are also listed. Note that
dependencies of the objects in external Ada libraries (see
switch @code{-aL@emph{dir}} in the following list)
@item @code{-o @emph{exec_name}}
Output executable name. The name of the final executable program will be
-@cite{exec_name}. If the @emph{-o} switch is omitted the default
+@code{exec_name}. If the @code{-o} switch is omitted the default
name for the executable will be the name of the input file in appropriate form
for an executable file on the host system.
-This switch cannot be used when invoking @emph{gnatmake} with several
+This switch cannot be used when invoking @code{gnatmake} with several
@code{file_names}.
@end table
@item @code{-P@emph{project}}
-Use project file @cite{project}. Only one such switch can be used.
+Use project file @code{project}. Only one such switch can be used.
@end table
@c -- Comment:
@item @code{-q}
Quiet. When this flag is not set, the commands carried out by
-@emph{gnatmake} are displayed.
+@code{gnatmake} are displayed.
@end table
@geindex -s (gnatmake)
following way:
orders between different 'first letter' switches are ignored, but
orders between same switches are taken into account. For example,
-@emph{-O -O2} is different than @emph{-O2 -O}, but @emph{-g -O}
-is equivalent to @emph{-O -g}.
+@code{-O -O2} is different than @code{-O2 -O}, but @code{-g -O}
+is equivalent to @code{-O -g}.
This switch is recommended when Integrated Preprocessing is used.
@end table
@item @code{-v}
-Verbose. Display the reason for all recompilations @emph{gnatmake}
+Verbose. Display the reason for all recompilations @code{gnatmake}
decides are necessary, with the highest verbosity level.
@end table
Files may be compiled. The ALI file and the object file will be put in the
object directory of the main Project. The compilation switches used will only
be those specified on the command line. Even when
-@emph{-x} is used, mains specified on the
+@code{-x} is used, mains specified on the
command line need to be sources of a project file.
@item @code{-X@emph{name}=@emph{value}}
-Indicate that external variable @cite{name} has the value @cite{value}.
+Indicate that external variable @code{name} has the value @code{value}.
The Project Manager will use this value for occurrences of
-@cite{external(name)} when parsing the project file.
+@code{external(name)} when parsing the project file.
@ref{de,,Switches Related to Project Files}.
@end table
@subsubheading GCC switches
-Any uppercase or multi-character switch that is not a @emph{gnatmake} switch
-is passed to @emph{gcc} (e.g., @emph{-O}, @emph{-gnato,} etc.)
+Any uppercase or multi-character switch that is not a @code{gnatmake} switch
+is passed to @code{gcc} (e.g., @code{-O}, @code{-gnato,} etc.)
@subsubheading Source and library search path switches
@item @code{-aI@emph{dir}}
-When looking for source files also look in directory @cite{dir}.
+When looking for source files also look in directory @code{dir}.
The order in which source files search is undertaken is
described in @ref{89,,Search Paths and the Run-Time Library (RTL)}.
@end table
@item @code{-aL@emph{dir}}
-Consider @cite{dir} as being an externally provided Ada library.
-Instructs @emph{gnatmake} to skip compilation units whose @code{.ALI}
-files have been located in directory @cite{dir}. This allows you to have
-missing bodies for the units in @cite{dir} and to ignore out of date bodies
+Consider @code{dir} as being an externally provided Ada library.
+Instructs @code{gnatmake} to skip compilation units whose @code{.ALI}
+files have been located in directory @code{dir}. This allows you to have
+missing bodies for the units in @code{dir} and to ignore out of date bodies
for the same units. You still need to specify
the location of the specs for these units by using the switches
@code{-aI@emph{dir}} or @code{-I@emph{dir}}.
Note: this switch is provided for compatibility with previous versions
-of @emph{gnatmake}. The easier method of causing standard libraries
+of @code{gnatmake}. The easier method of causing standard libraries
to be excluded from consideration is to write-protect the corresponding
ALI files.
@end table
@item @code{-aO@emph{dir}}
When searching for library and object files, look in directory
-@cite{dir}. The order in which library files are searched is described in
+@code{dir}. The order in which library files are searched is described in
@ref{8c,,Search Paths for gnatbind}.
@end table
Do not look for source files in the directory containing the source
file named in the command line.
Do not look for ALI or object files in the directory
-where @emph{gnatmake} was invoked.
+where @code{gnatmake} was invoked.
@end table
@geindex -L (gnatmake)
@item @code{-L@emph{dir}}
-Add directory @cite{dir} to the list of directories in which the linker
+Add directory @code{dir} to the list of directories in which the linker
will search for libraries. This is equivalent to
@code{-largs} @code{-L@emph{dir}}.
Furthermore, under Windows, the sources pointed to by the libraries path
@node Mode Switches for gnatmake,Notes on the Command Line,Switches for gnatmake,Building with gnatmake
@anchor{gnat_ugn/building_executable_programs_with_gnat id4}@anchor{df}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{e0}
-@subsection Mode Switches for @emph{gnatmake}
+@subsection Mode Switches for @code{gnatmake}
-The mode switches (referred to as @cite{mode_switches}) allow the
+The mode switches (referred to as @code{mode_switches}) allow the
inclusion of switches that are to be passed to the compiler itself, the
binder or the linker. The effect of a mode switch is to cause all
subsequent switches up to the end of the switch list, or up to the next
@item @code{-cargs @emph{switches}}
-Compiler switches. Here @cite{switches} is a list of switches
-that are valid switches for @emph{gcc}. They will be passed on to
-all compile steps performed by @emph{gnatmake}.
+Compiler switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gcc}. They will be passed on to
+all compile steps performed by @code{gnatmake}.
@end table
@geindex -bargs (gnatmake)
@item @code{-bargs @emph{switches}}
-Binder switches. Here @cite{switches} is a list of switches
-that are valid switches for @cite{gnatbind}. They will be passed on to
-all bind steps performed by @emph{gnatmake}.
+Binder switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gnatbind}. They will be passed on to
+all bind steps performed by @code{gnatmake}.
@end table
@geindex -largs (gnatmake)
@item @code{-largs @emph{switches}}
-Linker switches. Here @cite{switches} is a list of switches
-that are valid switches for @emph{gnatlink}. They will be passed on to
-all link steps performed by @emph{gnatmake}.
+Linker switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gnatlink}. They will be passed on to
+all link steps performed by @code{gnatmake}.
@end table
@geindex -margs (gnatmake)
@item @code{-margs @emph{switches}}
-Make switches. The switches are directly interpreted by @emph{gnatmake},
-regardless of any previous occurrence of @emph{-cargs}, @emph{-bargs}
-or @emph{-largs}.
+Make switches. The switches are directly interpreted by @code{gnatmake},
+regardless of any previous occurrence of @code{-cargs}, @code{-bargs}
+or @code{-largs}.
@end table
@node Notes on the Command Line,How gnatmake Works,Mode Switches for gnatmake,Building with gnatmake
This section contains some additional useful notes on the operation
-of the @emph{gnatmake} command.
+of the @code{gnatmake} command.
@geindex Recompilation (by gnatmake)
@itemize *
@item
-If @emph{gnatmake} finds no ALI files, it recompiles the main program
+If @code{gnatmake} finds no ALI files, it recompiles the main program
and all other units required by the main program.
-This means that @emph{gnatmake}
+This means that @code{gnatmake}
can be used for the initial compile, as well as during subsequent steps of
the development cycle.
@item
If you enter @code{gnatmake foo.adb}, where @code{foo}
-is a subunit or body of a generic unit, @emph{gnatmake} recompiles
+is a subunit or body of a generic unit, @code{gnatmake} recompiles
@code{foo.adb} (because it finds no ALI) and stops, issuing a
warning.
@item
-In @emph{gnatmake} the switch @emph{-I}
+In @code{gnatmake} the switch @code{-I}
is used to specify both source and
-library file paths. Use @emph{-aI}
+library file paths. Use @code{-aI}
instead if you just want to specify
-source paths only and @emph{-aO}
+source paths only and @code{-aO}
if you want to specify library paths
only.
@item
-@emph{gnatmake} will ignore any files whose ALI file is write-protected.
+@code{gnatmake} will ignore any files whose ALI file is write-protected.
This may conveniently be used to exclude standard libraries from
consideration and in particular it means that the use of the
-@emph{-f} switch will not recompile these files
-unless @emph{-a} is also specified.
+@code{-f} switch will not recompile these files
+unless @code{-a} is also specified.
@item
-@emph{gnatmake} has been designed to make the use of Ada libraries
+@code{gnatmake} has been designed to make the use of Ada libraries
particularly convenient. Assume you have an Ada library organized
as follows: @emph{obj-dir} contains the objects and ALI files for
of your Ada compilation units,
whereas @emph{include-dir} contains the
specs of these units, but no bodies. Then to compile a unit
-stored in @cite{main.adb}, which uses this Ada library you would just type:
+stored in @code{main.adb}, which uses this Ada library you would just type:
@example
$ gnatmake -aI`include-dir` -aL`obj-dir` main
@end example
@item
-Using @emph{gnatmake} along with the @emph{-m (minimal recompilation)}
+Using @code{gnatmake} along with the @code{-m (minimal recompilation)}
switch provides a mechanism for avoiding unnecessary recompilations. Using
this switch,
you can update the comments/format of your
@node How gnatmake Works,Examples of gnatmake Usage,Notes on the Command Line,Building with gnatmake
@anchor{gnat_ugn/building_executable_programs_with_gnat id6}@anchor{e3}@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{e4}
-@subsection How @emph{gnatmake} Works
+@subsection How @code{gnatmake} Works
-Generally @emph{gnatmake} automatically performs all necessary
+Generally @code{gnatmake} automatically performs all necessary
recompilations and you don't need to worry about how it works. However,
-it may be useful to have some basic understanding of the @emph{gnatmake}
+it may be useful to have some basic understanding of the @code{gnatmake}
approach and in particular to understand how it uses the results of
previous compilations without incorrectly depending on them.
files that it depends on have been modified, and hence there is no need
to recompile this file.
-@emph{gnatmake} works by first checking if the specified main unit is up
+@code{gnatmake} works by first checking if the specified main unit is up
to date. If so, no compilations are required for the main unit. If not,
-@emph{gnatmake} compiles the main program to build a new ALI file that
+@code{gnatmake} compiles the main program to build a new ALI file that
reflects the latest sources. Then the ALI file of the main unit is
examined to find all the source files on which the main program depends,
-and @emph{gnatmake} recursively applies the above procedure on all these
+and @code{gnatmake} recursively applies the above procedure on all these
files.
-This process ensures that @emph{gnatmake} only trusts the dependencies
+This process ensures that @code{gnatmake} only trusts the dependencies
in an existing ALI file if they are known to be correct. Otherwise it
always recompiles to determine a new, guaranteed accurate set of
dependencies. As a result the program is compiled 'upside down' from what may
systems. In particular, clients are compiled before the units on which
they depend. The ability of GNAT to compile in any order is critical in
allowing an order of compilation to be chosen that guarantees that
-@emph{gnatmake} will recompute a correct set of new dependencies if
+@code{gnatmake} will recompute a correct set of new dependencies if
necessary.
-When invoking @emph{gnatmake} with several @cite{file_names}, if a unit is
+When invoking @code{gnatmake} with several @code{file_names}, if a unit is
imported by several of the executables, it will be recompiled at most once.
Note: when using non-standard naming conventions
(@ref{35,,Using Other File Names}), changing through a configuration pragmas
-file the version of a source and invoking @emph{gnatmake} to recompile may
+file the version of a source and invoking @code{gnatmake} to recompile may
have no effect, if the previous version of the source is still accessible
-by @emph{gnatmake}. It may be necessary to use the switch
+by @code{gnatmake}. It may be necessary to use the switch
-f.
@node Examples of gnatmake Usage,,How gnatmake Works,Building with gnatmake
@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatmake-usage}@anchor{e5}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{e6}
-@subsection Examples of @emph{gnatmake} Usage
+@subsection Examples of @code{gnatmake} Usage
@item @emph{gnatmake hello.adb}
Compile all files necessary to bind and link the main program
-@code{hello.adb} (containing unit @cite{Hello}) and bind and link the
+@code{hello.adb} (containing unit @code{Hello}) and bind and link the
resulting object files to generate an executable file @code{hello}.
@item @emph{gnatmake main1 main2 main3}
Compile all files necessary to bind and link the main programs
-@code{main1.adb} (containing unit @cite{Main1}), @code{main2.adb}
-(containing unit @cite{Main2}) and @code{main3.adb}
-(containing unit @cite{Main3}) and bind and link the resulting object files
+@code{main1.adb} (containing unit @code{Main1}), @code{main2.adb}
+(containing unit @code{Main2}) and @code{main3.adb}
+(containing unit @code{Main3}) and bind and link the resulting object files
to generate three executable files @code{main1},
@code{main2} and @code{main3}.
@item @emph{gnatmake -q Main_Unit -cargs -O2 -bargs -l}
Compile all files necessary to bind and link the main program unit
-@cite{Main_Unit} (from file @code{main_unit.adb}). All compilations will
+@code{Main_Unit} (from file @code{main_unit.adb}). All compilations will
be done with optimization level 2 and the order of elaboration will be
-listed by the binder. @emph{gnatmake} will operate in quiet mode, not
+listed by the binder. @code{gnatmake} will operate in quiet mode, not
displaying commands it is executing.
@end table
@node Compiling with gcc,Compiler Switches,Building with gnatmake,Building Executable Programs with GNAT
@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-with-gcc}@anchor{1c}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{e7}
-@section Compiling with @emph{gcc}
+@section Compiling with @code{gcc}
-This section discusses how to compile Ada programs using the @emph{gcc}
+This section discusses how to compile Ada programs using the @code{gcc}
command. It also describes the set of switches
that can be used to control the behavior of the compiler.
The first step in creating an executable program is to compile the units
-of the program using the @emph{gcc} command. You must compile the
+of the program using the @code{gcc} command. You must compile the
following files:
@geindex cannot generate code
If you attempt to compile any of these files, you will get one of the
-following error messages (where @cite{fff} is the name of the file you
+following error messages (where @code{fff} is the name of the file you
compiled):
@quotation
@example
-cannot generate code for file `fff` (package spec)
+cannot generate code for file `@w{`}fff`@w{`} (package spec)
to check package spec, use -gnatc
-cannot generate code for file `fff` (missing subunits)
+cannot generate code for file `@w{`}fff`@w{`} (missing subunits)
to check parent unit, use -gnatc
-cannot generate code for file `fff` (subprogram spec)
+cannot generate code for file `@w{`}fff`@w{`} (subprogram spec)
to check subprogram spec, use -gnatc
-cannot generate code for file `fff` (subunit)
+cannot generate code for file `@w{`}fff`@w{`} (subunit)
to check subunit, use -gnatc
@end example
@end quotation
As indicated by the above error messages, if you want to submit
one of these files to the compiler to check for correct semantics
-without generating code, then use the @emph{-gnatc} switch.
+without generating code, then use the @code{-gnatc} switch.
The basic command for compiling a file containing an Ada unit is:
$ gcc -c [switches] <file name>
@end example
-where @cite{file name} is the name of the Ada file (usually
+where @code{file name} is the name of the Ada file (usually
having an extension @code{.ads} for a spec or @code{.adb} for a body).
You specify the
-@code{-c} switch to tell @emph{gcc} to compile, but not link, the file.
+@code{-c} switch to tell @code{gcc} to compile, but not link, the file.
The result of a successful compilation is an object file, which has the
same name as the source file but an extension of @code{.o} and an Ada
Library Information (ALI) file, which also has the same name as the
file in any directory using an absolute or relative path specification
containing the directory information.
+TESTING: the @code{--foobar@emph{NN}} switch
+
@geindex gnat1
-@emph{gcc} is actually a driver program that looks at the extensions of
+@code{gcc} is actually a driver program that looks at the extensions of
the file arguments and loads the appropriate compiler. For example, the
GNU C compiler is @code{cc1}, and the Ada compiler is @code{gnat1}.
These programs are in directories known to the driver program (in some
configurations via environment variables you set), but need not be in
-your path. The @emph{gcc} driver also calls the assembler and any other
+your path. The @code{gcc} driver also calls the assembler and any other
utilities needed to complete the generation of the required object
files.
-It is possible to supply several file names on the same @emph{gcc}
-command. This causes @emph{gcc} to call the appropriate compiler for
+It is possible to supply several file names on the same @code{gcc}
+command. This causes @code{gcc} to call the appropriate compiler for
each file. For example, the following command lists two separate
files to be compiled:
$ gcc -c x.adb y.adb
@end example
-calls @cite{gnat1} (the Ada compiler) twice to compile @code{x.adb} and
+calls @code{gnat1} (the Ada compiler) twice to compile @code{x.adb} and
@code{y.adb}.
The compiler generates two object files @code{x.o} and @code{y.o}
and the two ALI files @code{x.ali} and @code{y.ali}.
Any switches apply to all the files listed, see @ref{ea,,Compiler Switches} for a
-list of available @emph{gcc} switches.
+list of available @code{gcc} switches.
@node Search Paths and the Run-Time Library RTL,Order of Compilation Issues,Compiling Programs,Compiling with gcc
@anchor{gnat_ugn/building_executable_programs_with_gnat id10}@anchor{eb}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{89}
(the file name on the command line).
@item
-Each directory named by an @emph{-I} switch given on the @emph{gcc}
+Each directory named by an @code{-I} switch given on the @code{gcc}
command line, in the order given.
@geindex ADA_PRJ_INCLUDE_FILE
@ref{87,,Installing a library}
@end itemize
-Specifying the switch @emph{-I-}
+Specifying the switch @code{-I-}
inhibits the use of the directory
containing the source file named in the command line. You can still
have this directory on your search path, but in this case it must be
-explicitly requested with a @emph{-I} switch.
+explicitly requested with a @code{-I} switch.
-Specifying the switch @emph{-nostdinc}
+Specifying the switch @code{-nostdinc}
inhibits the search of the default location for the GNAT Run Time
Library (RTL) source files.
The compiler outputs its object files and ALI files in the current
working directory.
-Caution: The object file can be redirected with the @emph{-o} switch;
-however, @emph{gcc} and @cite{gnat1} have not been coordinated on this
+Caution: The object file can be redirected with the @code{-o} switch;
+however, @code{gcc} and @code{gnat1} have not been coordinated on this
so the @code{ALI} file will not go to the right place. Therefore, you should
-avoid using the @emph{-o} switch.
+avoid using the @code{-o} switch.
@geindex System.IO
-The packages @cite{Ada}, @cite{System}, and @cite{Interfaces} and their
-children make up the GNAT RTL, together with the simple @cite{System.IO}
-package used in the @cite{"Hello World"} example. The sources for these units
+The packages @code{Ada}, @code{System}, and @code{Interfaces} and their
+children make up the GNAT RTL, together with the simple @code{System.IO}
+package used in the @code{"Hello World"} example. The sources for these units
are needed by the compiler and are kept together in one directory. Not
all of the bodies are needed, but all of the sources are kept together
anyway. In a normal installation, you need not specify these directory
names when compiling or binding. Either the environment variables or
the built-in defaults cause these files to be found.
-In addition to the language-defined hierarchies (@cite{System}, @cite{Ada} and
-@cite{Interfaces}), the GNAT distribution provides a fourth hierarchy,
-consisting of child units of @cite{GNAT}. This is a collection of generally
+In addition to the language-defined hierarchies (@code{System}, @code{Ada} and
+@code{Interfaces}), the GNAT distribution provides a fourth hierarchy,
+consisting of child units of @code{GNAT}. This is a collection of generally
useful types, subprograms, etc. See the @cite{GNAT_Reference_Manual}
for further details.
@subsection Order of Compilation Issues
-If, in our earlier example, there was a spec for the @cite{hello}
+If, in our earlier example, there was a spec for the @code{hello}
procedure, it would be contained in the file @code{hello.ads}; yet this
file would not have to be explicitly compiled. This is the result of the
model we chose to implement library management. Some of the consequences
@end example
Compile the child unit package in file @code{xyz-def.adb} with extensive
-optimizations, and pragma @cite{Assert}/@cite{Debug} statements
+optimizations, and pragma @code{Assert}/@cite{Debug} statements
enabled.
@example
@section Compiler Switches
-The @emph{gcc} command accepts switches that control the
+The @code{gcc} command accepts switches that control the
compilation process. These switches are fully described in this section:
first an alphabetical listing of all switches with a brief description,
and then functionally grouped sets of switches with more detailed
@item @code{-b @emph{target}}
-Compile your program to run on @cite{target}, which is the name of a
+Compile your program to run on @code{target}, which is the name of a
system configuration. You must have a GNAT cross-compiler built if
-@cite{target} is not the same as your host system.
+@code{target} is not the same as your host system.
@end table
@geindex -B (gcc)
@item @code{-B@emph{dir}}
-Load compiler executables (for example, @cite{gnat1}, the Ada compiler)
-from @cite{dir} instead of the default location. Only use this switch
+Load compiler executables (for example, @code{gnat1}, the Ada compiler)
+from @code{dir} instead of the default location. Only use this switch
when multiple versions of the GNAT compiler are available.
See the "Options for Directory Search" section in the
@cite{Using the GNU Compiler Collection (GCC)} manual for further details.
-You would normally use the @emph{-b} or @emph{-V} switch instead.
+You would normally use the @code{-b} or @code{-V} switch instead.
@end table
@geindex -c (gcc)
Compile. Always use this switch when compiling Ada programs.
-Note: for some other languages when using @emph{gcc}, notably in
+Note: for some other languages when using @code{gcc}, notably in
the case of C and C++, it is possible to use
-use @emph{gcc} without a @emph{-c} switch to
+use @code{gcc} without a @code{-c} switch to
compile and link in one step. In the case of GNAT, you
cannot use this approach, because the binder must be run
-and @emph{gcc} cannot be used to run the GNAT binder.
+and @code{gcc} cannot be used to run the GNAT binder.
@end table
@geindex -fcallgraph-info (gcc)
per-file basis. The information is generated in the VCG format. It can
be decorated with additional, per-node and/or per-edge information, if a
list of comma-separated markers is additionally specified. When the
-@cite{su} marker is specified, the callgraph is decorated with stack usage
-information; it is equivalent to @emph{-fstack-usage}. When the @cite{da}
+@code{su} marker is specified, the callgraph is decorated with stack usage
+information; it is equivalent to @code{-fstack-usage}. When the @code{da}
marker is specified, the callgraph is decorated with information about
dynamically allocated objects.
@end table
Generates cross reference information in GLI files for C and C++ sources.
The GLI files have the same syntax as the ALI files for Ada, and can be used
for source navigation in IDEs and on the command line using e.g. gnatxref
-and the @emph{--ext=gli} switch.
+and the @code{--ext=gli} switch.
@end table
@geindex -flto (gcc)
@item @code{-flto[=@emph{n}]}
Enables Link Time Optimization. This switch must be used in conjunction
-with the traditional @emph{-Ox} switches and instructs the compiler to
+with the traditional @code{-Ox} switches and instructs the compiler to
defer most optimizations until the link stage. The advantage of this
approach is that the compiler can do a whole-program analysis and choose
the best interprocedural optimization strategy based on a complete view
of the program, instead of a fragmentary view with the usual approach.
This can also speed up the compilation of big programs and reduce the
size of the executable, compared with a traditional per-unit compilation
-with inlining across modules enabled by the @emph{-gnatn} switch.
+with inlining across modules enabled by the @code{-gnatn} switch.
The drawback of this approach is that it may require more memory and that
the debugging information generated by -g with it might be hardly usable.
-The switch, as well as the accompanying @emph{-Ox} switches, must be
+The switch, as well as the accompanying @code{-Ox} switches, must be
specified both for the compilation and the link phases.
-If the @cite{n} parameter is specified, the optimization and final code
-generation at link time are executed using @cite{n} parallel jobs by
-means of an installed @emph{make} program.
+If the @code{n} parameter is specified, the optimization and final code
+generation at link time are executed using @code{n} parallel jobs by
+means of an installed @code{make} program.
@end table
@geindex -fno-inline (gcc)
@item @code{-fno-inline}
-Suppresses all inlining, unless requested with pragma @cite{Inline_Always}. The
+Suppresses all inlining, unless requested with pragma @code{Inline_Always}. The
effect is enforced regardless of other optimization or inlining switches.
Note that inlining can also be suppressed on a finer-grained basis with
-pragma @cite{No_Inline}.
+pragma @code{No_Inline}.
@end table
@geindex -fno-inline-functions (gcc)
@item @code{-fno-inline-functions}
Suppresses automatic inlining of subprograms, which is enabled
-if @emph{-O3} is used.
+if @code{-O3} is used.
@end table
@geindex -fno-inline-small-functions (gcc)
@item @code{-fno-inline-small-functions}
Suppresses automatic inlining of small subprograms, which is enabled
-if @emph{-O2} is used.
+if @code{-O2} is used.
@end table
@geindex -fno-inline-functions-called-once (gcc)
@item @code{-fno-inline-functions-called-once}
Suppresses inlining of subprograms local to the unit and called once
-from within it, which is enabled if @emph{-O1} is used.
+from within it, which is enabled if @code{-O1} is used.
@end table
@geindex -fno-ivopts (gcc)
@item @code{-fno-ivopts}
Suppresses high-level loop induction variable optimizations, which are
-enabled if @emph{-O1} is used. These optimizations are generally
+enabled if @code{-O1} is used. These optimizations are generally
profitable but, for some specific cases of loops with numerous uses
of the iteration variable that follow a common pattern, they may end
up destroying the regularity that could be exploited at a lower level
integer overflow. These rules specify that signed integer overflow will
result in a Constraint_Error exception at run time and are enforced in
default mode by the compiler, so this switch should not be necessary in
-normal operating mode. It might be useful in conjunction with @emph{-gnato0}
+normal operating mode. It might be useful in conjunction with @code{-gnato0}
for very peculiar cases of low-level programming.
@end table
Generate debugging information. This information is stored in the object
file and copied from there to the final executable file by the linker,
where it can be read by the debugger. You must use the
-@emph{-g} switch if you plan on using the debugger.
+@code{-g} switch if you plan on using the debugger.
@end table
@geindex -gnat05 (gcc)
@item @code{-gnat2005}
-Allow full Ada 2005 features (same as @emph{-gnat05})
+Allow full Ada 2005 features (same as @code{-gnat05})
@end table
@geindex -gnat2012 (gcc)
@item @code{-gnat2012}
-Allow full Ada 2012 features (same as @emph{-gnat12})
+Allow full Ada 2012 features (same as @code{-gnat12})
@item @code{-gnat83}
Enforce Ada 95 restrictions.
Note: for compatibility with some Ada 95 compilers which support only
-the @cite{overriding} keyword of Ada 2005, the @emph{-gnatd.D} switch can
-be used along with @emph{-gnat95} to achieve a similar effect with GNAT.
+the @code{overriding} keyword of Ada 2005, the @code{-gnatd.D} switch can
+be used along with @code{-gnat95} to achieve a similar effect with GNAT.
-@emph{-gnatd.D} instructs GNAT to consider @cite{overriding} as a keyword
+@code{-gnatd.D} instructs GNAT to consider @code{overriding} as a keyword
and handle its associated semantic checks, even in Ada 95 mode.
@end table
@item @code{-gnata}
-Assertions enabled. @cite{Pragma Assert} and @cite{pragma Debug} to be
+Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
activated. Note that these pragmas can also be controlled using the
-configuration pragmas @cite{Assertion_Policy} and @cite{Debug_Policy}.
-It also activates pragmas @cite{Check}, @cite{Precondition}, and
-@cite{Postcondition}. Note that these pragmas can also be controlled
-using the configuration pragma @cite{Check_Policy}. In Ada 2012, it
+configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}.
+It also activates pragmas @code{Check}, @code{Precondition}, and
+@code{Postcondition}. Note that these pragmas can also be controlled
+using the configuration pragma @code{Check_Policy}. In Ada 2012, it
also activates all assertions defined in the RM as aspects: preconditions,
postconditions, type invariants and (sub)type predicates. In all Ada modes,
corresponding pragmas for type invariants and (sub)type predicates are
@item @code{-gnatc}
Check syntax and semantics only (no code generation attempted). When the
-compiler is invoked by @emph{gnatmake}, if the switch @emph{-gnatc} is
-only given to the compiler (after @emph{-cargs} or in package Compiler of
-the project file, @emph{gnatmake} will fail because it will not find the
-object file after compilation. If @emph{gnatmake} is called with
-@emph{-gnatc} as a builder switch (before @emph{-cargs} or in package
-Builder of the project file) then @emph{gnatmake} will not fail because
+compiler is invoked by @code{gnatmake}, if the switch @code{-gnatc} is
+only given to the compiler (after @code{-cargs} or in package Compiler of
+the project file, @code{gnatmake} will fail because it will not find the
+object file after compilation. If @code{gnatmake} is called with
+@code{-gnatc} as a builder switch (before @code{-cargs} or in package
+Builder of the project file) then @code{gnatmake} will not fail because
it will not look for the object files after compilation, and it will not try
to build and link.
@end table
@item @code{-gnatd}
Specify debug options for the compiler. The string of characters after
-the @emph{-gnatd} specify the specific debug options. The possible
+the @code{-gnatd} specify the specific debug options. The possible
characters are 0-9, a-z, A-Z, optionally preceded by a dot. See
compiler source file @code{debug.adb} for details of the implemented
debug options. Certain debug options are relevant to applications
Create expanded source files for source level debugging. This switch
also suppresses generation of cross-reference information
-(see @emph{-gnatx}). Note that this switch is not allowed if a previous
+(see @code{-gnatx}). Note that this switch is not allowed if a previous
-gnatR switch has been given, since these two switches are not compatible.
@end table
Detect_Aliasing (Obj, Self (Obj));
@end example
-In the example above, the first call to @cite{Detect_Aliasing} fails with a
-@cite{Program_Error} at runtime because the actuals for @cite{Val_1} and
-@cite{Val_2} denote the same object. The second call executes without raising
-an exception because @cite{Self(Obj)} produces an anonymous object which does
-not share the memory location of @cite{Obj}.
+In the example above, the first call to @code{Detect_Aliasing} fails with a
+@code{Program_Error} at runtime because the actuals for @code{Val_1} and
+@code{Val_2} denote the same object. The second call executes without raising
+an exception because @code{Self(Obj)} produces an anonymous object which does
+not share the memory location of @code{Obj}.
@end table
@geindex -gnatec (gcc)
@item @code{-gnateC}
Generate CodePeer messages in a compiler-like format. This switch is only
-effective if @emph{-gnatcC} is also specified and requires an installation
+effective if @code{-gnatcC} is also specified and requires an installation
of CodePeer.
@end table
@item @code{-gnateDsymbol[=@emph{value}]}
-Defines a symbol, associated with @cite{value}, for preprocessing.
+Defines a symbol, associated with @code{value}, for preprocessing.
(@ref{18,,Integrated Preprocessing}).
@end table
Check for overflow on all floating-point operations, including those
for unconstrained predefined types. See description of pragma
-@cite{Check_Float_Overflow} in GNAT RM.
+@code{Check_Float_Overflow} in GNAT RM.
@end table
@geindex -gnateg (gcc)
@quotation
-The @cite{-gnatc} switch must always be specified before this switch, e.g.
-@cite{-gnatceg}. Generate a C header from the Ada input file. See
+The @code{-gnatc} switch must always be specified before this switch, e.g.
+@code{-gnatceg}. Generate a C header from the Ada input file. See
@ref{ca,,Generating C Headers for Ada Specifications} for more
information.
@end quotation
@item @code{-gnatei@emph{nnn}}
Set maximum number of instantiations during compilation of a single unit to
-@cite{nnn}. This may be useful in increasing the default maximum of 8000 for
+@code{nnn}. This may be useful in increasing the default maximum of 8000 for
the rare case when a single unit legitimately exceeds this limit.
@end table
@item @code{-gnateI@emph{nnn}}
Indicates that the source is a multi-unit source and that the index of the
-unit to compile is @cite{nnn}. @cite{nnn} needs to be a positive number and need
+unit to compile is @code{nnn}. @code{nnn} needs to be a positive number and need
to be a valid index in the multi-unit source.
@end table
This switch can be used with the static elaboration model to issue info
messages showing
-where implicit @cite{pragma Elaborate} and @cite{pragma Elaborate_All}
+where implicit @code{pragma Elaborate} and @code{pragma Elaborate_All}
are generated. This is useful in diagnosing elaboration circularities
caused by these implicit pragmas when using the static elaboration
model. See See the section in this guide on elaboration checking for
@item @code{-gnateS}
-Synonym of @emph{-fdump-scos}, kept for backwards compatibility.
+Synonym of @code{-fdump-scos}, kept for backwards compatibility.
@end table
@geindex -gnatet=file (gcc)
@item @code{-gnatet=@emph{path}}
Generate target dependent information. The format of the output file is
-described in the section about switch @emph{-gnateT}.
+described in the section about switch @code{-gnateT}.
@end table
@geindex -gnateT (gcc)
the machine on which the tool is run.
The following target dependent values should be defined,
-where @cite{Nat} denotes a natural integer value, @cite{Pos} denotes a
+where @code{Nat} denotes a natural integer value, @code{Pos} denotes a
positive integer value, and fields marked with a question mark are
boolean fields, where a value of 0 is False, and a value of 1 is True:
name value
@end example
-where @cite{name} is the name of the parameter, spelled out in full,
-and cased as in the above list, and @cite{value} is an unsigned decimal
+where @code{name} is the name of the parameter, spelled out in full,
+and cased as in the above list, and @code{value} is an unsigned decimal
integer. Two or more blanks separates the name from the value.
All the variables must be present, in alphabetical order (i.e. the
name digs float_rep size alignment
@end example
-where @cite{name} is the string name of the type (which can have
-single spaces embedded in the name (e.g. long double), @cite{digs} is
-the number of digits for the floating-point type, @cite{float_rep} is
+where @code{name} is the string name of the type (which can have
+single spaces embedded in the name (e.g. long double), @code{digs} is
+the number of digits for the floating-point type, @code{float_rep} is
the float representation (I/V/A for IEEE-754-Binary, Vax_Native,
-AAMP), @cite{size} is the size in bits, @cite{alignment} is the
+AAMP), @code{size} is the size in bits, @code{alignment} is the
alignment in bits. The name is followed by at least two blanks, fields
are separated by at least one blank, and a LF character immediately
follows the alignment field.
Internal GNAT implementation mode. This should not be used for
applications programs, it is intended only for use by the compiler
and its run-time library. For documentation, see the GNAT sources.
-Note that @emph{-gnatg} implies
-@emph{-gnatw.ge} and
-@emph{-gnatyg}
+Note that @code{-gnatg} implies
+@code{-gnatw.ge} and
+@code{-gnatyg}
so that all standard warnings and all standard style options are turned on.
All warnings and style messages are treated as errors.
@end table
@item @code{-gnati@emph{c}}
-Identifier character set (@cite{c} = 1/2/3/4/8/9/p/f/n/w).
-For details of the possible selections for @cite{c},
+Identifier character set (@code{c} = 1/2/3/4/8/9/p/f/n/w).
+For details of the possible selections for @code{c},
see @ref{48,,Character Set Control}.
@end table
are: enumeration_representation_clause, record_representation_clause,
and attribute_definition_clause for the following attributes:
Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
-Object_Size, Size, Small, Stream_Size, and Value_Size.
+Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
+and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
Note that this option should be used only for compiling -- the
code is likely to malfunction at run time.
-Note that when @cite{-gnatct} is used to generate trees for input
-into @cite{ASIS} tools, these representation clauses are removed
+Note that when @code{-gnatct} is used to generate trees for input
+into ASIS tools, these representation clauses are removed
from the tree and ignored. This means that the tool will not see them.
@end table
@item @code{-gnatj@emph{nn}}
-Reformat error messages to fit on @cite{nn} character lines
+Reformat error messages to fit on @code{nn} character lines
@end table
@geindex -gnatk (gcc)
@item @code{-gnatk=@emph{n}}
-Limit file names to @cite{n} (1-999) characters (@cite{k} = krunch).
+Limit file names to @code{n} (1-999) characters (@code{k} = krunch).
@end table
@geindex -gnatl (gcc)
@item @code{-gnatm=@emph{n}}
-Limit number of detected error or warning messages to @cite{n}
-where @cite{n} is in the range 1..999999. The default setting if
+Limit number of detected error or warning messages to @code{n}
+where @code{n} is in the range 1..999999. The default setting if
no switch is given is 9999. If the number of warnings reaches this
limit, then a message is output and further warnings are suppressed,
but the compilation is continued. If the number of error messages
@item @code{-gnatn[12]}
-Activate inlining across modules for subprograms for which pragma @cite{Inline}
+Activate inlining across modules for subprograms for which pragma @code{Inline}
is specified. This inlining is performed by the GCC back-end. An optional
digit sets the inlining level: 1 for moderate inlining across modules
or 2 for full inlining across modules. If no inlining level is specified,
@item @code{-gnatN}
Activate front end inlining for subprograms for which
-pragma @cite{Inline} is specified. This inlining is performed
+pragma @code{Inline} is specified. This inlining is performed
by the front end and will be visible in the
-@emph{-gnatG} output.
+@code{-gnatG} output.
When using a gcc-based back end (in practice this means using any version
of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
-@emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred.
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
@end table
Suppresses overflow checking. This causes the behavior of the compiler to
match the default for older versions where overflow checking was suppressed
by default. This is equivalent to having
-@cite{pragma Suppress (Overflow_Mode)} in a configuration pragma file.
+@code{pragma Suppress (Overflow_Check)} in a configuration pragma file.
@end table
@geindex -gnato?? (gcc)
@item @code{-gnato??}
Set default mode for handling generation of code to avoid intermediate
-arithmetic overflow. Here @cite{??} is two digits, a
-single digit, or nothing. Each digit is one of the digits @cite{1}
-through @cite{3}:
+arithmetic overflow. Here @code{??} is two digits, a
+single digit, or nothing. Each digit is one of the digits @code{1}
+through @code{3}:
-@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item
Digit
@tab
-All intermediate overflows checked against base type (@cite{STRICT})
+All intermediate overflows checked against base type (@code{STRICT})
@item
@tab
-Minimize intermediate overflows (@cite{MINIMIZED})
+Minimize intermediate overflows (@code{MINIMIZED})
@item
@tab
-Eliminate intermediate overflows (@cite{ELIMINATED})
+Eliminate intermediate overflows (@code{ELIMINATED})
@end multitable
assertions, pre/postconditions, and type invariants, and the second
applies within assertions, pre/postconditions, and type invariants.
-If no digits follow the @emph{-gnato}, then it is equivalent to
-@emph{-gnato11},
+If no digits follow the @code{-gnato}, then it is equivalent to
+@code{-gnato11},
causing all intermediate overflows to be handled in strict
mode.
This switch also causes arithmetic overflow checking to be performed
-(as though @cite{pragma Unsuppress (Overflow_Mode)} had been specified).
+(as though @code{pragma Unsuppress (Overflow_Check)} had been specified).
-The default if no option @emph{-gnato} is given is that overflow handling
-is in @cite{STRICT} mode (computations done using the base type), and that
+The default if no option @code{-gnato} is given is that overflow handling
+is in @code{STRICT} mode (computations done using the base type), and that
overflow checking is enabled.
Note that division by zero is a separate check that is not
@item @code{-gnatp}
Suppress all checks. See @ref{f9,,Run-Time Checks} for details. This switch
-has no effect if cancelled by a subsequent @emph{-gnat-p} switch.
+has no effect if cancelled by a subsequent @code{-gnat-p} switch.
@end table
@geindex -gnat-p (gcc)
@item @code{-gnat-p}
-Cancel effect of previous @emph{-gnatp} switch.
+Cancel effect of previous @code{-gnatp} switch.
@end table
@geindex -gnatP (gcc)
Enable polling. This is required on some systems (notably Windows NT) to
obtain asynchronous abort and asynchronous transfer of control capability.
-See @cite{Pragma_Polling} in the @cite{GNAT_Reference_Manual} for full
+See @code{Pragma_Polling} in the @cite{GNAT_Reference_Manual} for full
details.
@end table
Don't quit. Generate @code{ALI} and tree files even if illegalities.
Note that code generation is still suppressed in the presence of any
-errors, so even with @emph{-gnatQ} no object file is generated.
+errors, so even with @code{-gnatQ} no object file is generated.
@end table
@geindex -gnatr (gcc)
@table @asis
-@item @code{-gnatR[0/1/2/3[s]]}
+@item @code{-gnatR[0/1/2/3][e][m][s]}
-Output representation information for declared types and objects.
-Note that this switch is not allowed if a previous @cite{-gnatD} switch has
-been given, since these two switches are not compatible.
-
-@item @code{-gnatRm[s]}
-
-Output convention and parameter passing mechanisms for all subprograms.
+Output representation information for declared types, objects and
+subprograms. Note that this switch is not allowed if a previous
+@code{-gnatD} switch has been given, since these two switches
+are not compatible.
@end table
@geindex -gnats (gcc)
@item @code{-gnatT@emph{nnn}}
-All compiler tables start at @cite{nnn} times usual starting size.
+All compiler tables start at @code{nnn} times usual starting size.
@end table
@geindex -gnatu (gcc)
@item @code{-gnatw@emph{xxx}}
Warning mode where
-@cite{xxx} is a string of option letters that denotes
+@code{xxx} is a string of option letters that denotes
the exact warnings that
are enabled or disabled (@ref{fa,,Warning Message Control}).
@end table
@item @code{-gnatW@emph{e}}
Wide character encoding method
-(@cite{e}=n/h/u/s/e/8).
+(@code{e}=n/h/u/s/e/8).
@end table
@geindex -gnatx (gcc)
@item @code{-gnatz@emph{m}}
Distribution stub generation and compilation
-(@cite{m}=r/c for receiver/caller stubs).
+(@code{m}=r/c for receiver/caller stubs).
@end table
@geindex -I (gcc)
@geindex RTL
-Direct GNAT to search the @cite{dir} directory for source files needed by
+Direct GNAT to search the @code{dir} directory for source files needed by
the current compilation
(see @ref{89,,Search Paths and the Run-Time Library (RTL)}).
@end table
@item @code{-o @emph{file}}
-This switch is used in @emph{gcc} to redirect the generated object file
+This switch is used in @code{gcc} to redirect the generated object file
and its associated ALI file. Beware of this switch with GNAT, because it may
cause the object file and ALI file to have different names which in turn
may confuse the binder and the linker.
@item @code{-O[@emph{n}]}
-@cite{n} controls the optimization level:
+@code{n} controls the optimization level:
-@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item
@emph{n}
@tab
-No optimization, the default setting if no @emph{-O} appears
+No optimization, the default setting if no @code{-O} appears
@item
@tab
-Normal optimization, the default if you specify @emph{-O} without an
+Normal optimization, the default if you specify @code{-O} without an
operand. A good compromise between code quality and compilation
time.
@tab
-Same as @emph{-O2}, and also includes inline expansion for small
+Same as @code{-O2}, and also includes inline expansion for small
subprograms in the same unit.
@item
@item @code{--RTS=@emph{rts-path}}
Specifies the default location of the runtime library. Same meaning as the
-equivalent @emph{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
+equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
@end table
@geindex -S (gcc)
@item @code{-S}
-Used in place of @emph{-c} to
+Used in place of @code{-c} to
cause the assembler source file to be
generated, using @code{.s} as the extension,
instead of the object file.
@item @code{-fverbose-asm}
-Used in conjunction with @emph{-S}
+Used in conjunction with @code{-S}
to cause the generated assembly code file to be annotated with variable
names, making it significantly easier to follow.
@end table
@item @code{-v}
-Show commands generated by the @emph{gcc} driver. Normally used only for
+Show commands generated by the @code{gcc} driver. Normally used only for
debugging purposes or if you need to be sure what version of the
compiler you are executing.
@end table
@item @code{-V @emph{ver}}
-Execute @cite{ver} version of the compiler. This is the @emph{gcc}
+Execute @code{ver} version of the compiler. This is the @code{gcc}
version, not the GNAT version.
@end table
Turn off warnings generated by the back end of the compiler. Use of
this switch also causes the default for front end warnings to be set
-to suppress (as though @emph{-gnatws} had appeared at the start of
+to suppress (as though @code{-gnatws} had appeared at the start of
the options).
@end table
@itemize *
@item
-The switch @emph{-gnatc} if combined with other switches must come
+The switch @code{-gnatc} if combined with other switches must come
first in the string.
@item
-The switch @emph{-gnats} if combined with other switches must come
+The switch @code{-gnats} if combined with other switches must come
first in the string.
@item
The switches
-@emph{-gnatzc} and @emph{-gnatzr} may not be combined with any other
+@code{-gnatzc} and @code{-gnatzr} may not be combined with any other
switches, and only one of them may appear in the command line.
@item
-The switch @emph{-gnat-p} may not be combined with any other switch.
+The switch @code{-gnat-p} may not be combined with any other switch.
@item
-Once a 'y' appears in the string (that is a use of the @emph{-gnaty}
+Once a 'y' appears in the string (that is a use of the @code{-gnaty}
switch), then all further characters in the switch are interpreted
-as style modifiers (see description of @emph{-gnaty}).
+as style modifiers (see description of @code{-gnaty}).
@item
-Once a 'd' appears in the string (that is a use of the @emph{-gnatd}
+Once a 'd' appears in the string (that is a use of the @code{-gnatd}
switch), then all further characters in the switch are interpreted
-as debug flags (see description of @emph{-gnatd}).
+as debug flags (see description of @code{-gnatd}).
@item
-Once a 'w' appears in the string (that is a use of the @emph{-gnatw}
+Once a 'w' appears in the string (that is a use of the @code{-gnatw}
switch), then all further characters in the switch are interpreted
-as warning mode modifiers (see description of @emph{-gnatw}).
+as warning mode modifiers (see description of @code{-gnatw}).
@item
-Once a 'V' appears in the string (that is a use of the @emph{-gnatV}
+Once a 'V' appears in the string (that is a use of the @code{-gnatV}
switch), then all further characters in the switch are interpreted
as validity checking options (@ref{f6,,Validity Checking}).
The first integer after the file name is the line number in the file,
and the second integer is the column number within the line.
-@cite{GPS} can parse the error messages
+@code{GPS} can parse the error messages
and point to the referenced character.
The following switches provide control over the error message
format:
@item @code{-gnatv}
-The @cite{v} stands for verbose.
+The @code{v} stands for verbose.
The effect of this setting is to write long-format error
messages to @code{stdout} (the standard output file.
The same program compiled with the
-@emph{-gnatv} switch would generate:
+@code{-gnatv} switch would generate:
@example
3. funcion X (Q : Integer)
@item @code{-gnatl}
-The @cite{l} stands for list.
+The @code{l} stands for list.
This switch causes a full listing of
the file to be generated. In the case where a body is
compiled, the corresponding spec is also listed, along
5. end;
@end example
-When you specify the @emph{-gnatv} or @emph{-gnatl} switches and
+When you specify the @code{-gnatv} or @code{-gnatl} switches and
standard output is redirected, a brief summary is written to
@code{stderr} (standard error) giving the number of error messages and
warning messages generated.
@item @code{-gnatl=@emph{fname}}
-This has the same effect as @emph{-gnatl} except that the output is
+This has the same effect as @code{-gnatl} except that the output is
written to a file instead of to standard output. If the given name
@code{fname} does not start with a period, then it is the full name
of the file to be written. If @code{fname} is an extension, it is
appended to the name of the file being compiled. For example, if
-file @code{xyz.adb} is compiled with @emph{-gnatl=.lst},
+file @code{xyz.adb} is compiled with @code{-gnatl=.lst},
then the output is written to file xyz.adb.lst.
@end table
@item @code{-gnatb}
-The @cite{b} stands for brief.
+The @code{b} stands for brief.
This switch causes GNAT to generate the
brief format error messages to @code{stderr} (the standard error
file) as well as the verbose
@item @code{-gnatm=@emph{n}}
-The @cite{m} stands for maximum.
-@cite{n} is a decimal integer in the
+The @code{m} stands for maximum.
+@code{n} is a decimal integer in the
range of 1 to 999999 and limits the number of error or warning
messages to be generated. For example, using
-@emph{-gnatm2} might yield
+@code{-gnatm2} might yield
@example
e.adb:3:04: Incorrect spelling of keyword "function"
is abandoned. A value of zero means that no limit applies.
Note that the equal sign is optional, so the switches
-@emph{-gnatm2} and @emph{-gnatm=2} are equivalent.
+@code{-gnatm2} and @code{-gnatm=2} are equivalent.
@end table
@geindex -gnatf (gcc)
@geindex Error messages
@geindex suppressing
-The @cite{f} stands for full.
+The @code{f} stands for full.
Normally, the compiler suppresses error messages that are likely to be
redundant. This switch causes all error
messages to be generated. In particular, in the case of
@end example
where the parenthetical comment warns that there are additional
-references to the variable @cite{V}. Compiling the same program with the
-@emph{-gnatf} switch yields
+references to the variable @code{V}. Compiling the same program with the
+@code{-gnatf} switch yields
@example
e.adb:7:07: "V" is undefined
e.adb:9:12: "V" is undefined
@end example
-The @emph{-gnatf} switch also generates additional information for
+The @code{-gnatf} switch also generates additional information for
some error messages. Some examples are:
@item @code{-gnatjnn}
-In normal operation mode (or if @emph{-gnatj0} is used), then error messages
+In normal operation mode (or if @code{-gnatj0} is used), then error messages
with continuation lines are treated as though the continuation lines were
separate messages (and so a warning with two continuation lines counts as
three warnings, and is listed as three separate messages).
-If the @emph{-gnatjnn} switch is used with a positive value for nn, then
+If the @code{-gnatjnn} switch is used with a positive value for nn, then
messages are output in a different manner. A message and all its continuation
lines are treated as a unit, and count as only one warning or message in the
statistics totals. Furthermore, the message is reformatted so that no line
@item @code{-gnatq}
-The @cite{q} stands for quit (really 'don't quit').
+The @code{q} stands for quit (really 'don't quit').
In normal operation mode, the compiler first parses the program and
determines if there are any syntax errors. If there are, appropriate
error messages are generated and compilation is immediately terminated.
@item @code{-gnatQ}
In normal operation mode, the @code{ALI} file is not generated if any
-illegalities are detected in the program. The use of @emph{-gnatQ} forces
+illegalities are detected in the program. The use of @code{-gnatQ} forces
generation of the @code{ALI} file. This file is marked as being in
error, so it cannot be used for binding purposes, but it does contain
reasonably complete cross-reference information, and thus may be useful
for use by tools (e.g., semantic browsing tools or integrated development
environments) that are driven from the @code{ALI} file. This switch
-implies @emph{-gnatq}, since the semantic phase must be run to get a
+implies @code{-gnatq}, since the semantic phase must be run to get a
meaningful ALI file.
-In addition, if @emph{-gnatt} is also specified, then the tree file is
+In addition, if @code{-gnatt} is also specified, then the tree file is
generated even if there are illegalities. It may be useful in this case
-to also specify @emph{-gnatq} to ensure that full semantic processing
+to also specify @code{-gnatq} to ensure that full semantic processing
occurs. The resulting tree file can be processed by ASIS, for the purpose
of providing partial information about illegal units, but if the error
causes the tree to be badly malformed, then ASIS may crash during the
analysis.
-When @emph{-gnatQ} is used and the generated @code{ALI} file is marked as
-being in error, @emph{gnatmake} will attempt to recompile the source when it
-finds such an @code{ALI} file, including with switch @emph{-gnatc}.
+When @code{-gnatQ} is used and the generated @code{ALI} file is marked as
+being in error, @code{gnatmake} will attempt to recompile the source when it
+finds such an @code{ALI} file, including with switch @code{-gnatc}.
-Note that @emph{-gnatQ} has no effect if @emph{-gnats} is specified,
-since ALI files are never generated if @emph{-gnats} is set.
+Note that @code{-gnatQ} has no effect if @code{-gnats} is specified,
+since ALI files are never generated if @code{-gnats} is set.
@end table
@node Warning Message Control,Debugging and Assertion Control,Output and Error Message Control,Compiler Switches
for the generation of warning messages. As always, warnings are not
definite indications of errors. For example, if you do an out-of-range
assignment with the deliberate intention of raising a
-@cite{Constraint_Error} exception, then the warning that may be
+@code{Constraint_Error} exception, then the warning that may be
issued does not indicate an error. Some of the situations for which GNAT
issues warnings (at least some of the time) are given in the following
list. This list is not complete, and new warnings are often added to
Variables that are referenced before being initialized
@item
-Task entries with no corresponding @cite{accept} statement
+Task entries with no corresponding @code{accept} statement
@item
-Duplicate accepts for the same task entry in a @cite{select}
+Duplicate accepts for the same task entry in a @code{select}
@item
Objects that take too much storage
Unchecked conversion between types of differing sizes
@item
-Missing @cite{return} statement along some execution path in a function
+Missing @code{return} statement along some execution path in a function
@item
Incorrect (unrecognized) pragmas
Unused @emph{with} clauses
@item
-@cite{Bit_Order} usage that does not have any effect
+@code{Bit_Order} usage that does not have any effect
@item
-@cite{Standard.Duration} used to resolve universal fixed expression
+@code{Standard.Duration} used to resolve universal fixed expression
@item
Dereference of possibly null value
@item
Unreferenced or unmodified variables. Note that a special
exemption applies to variables which contain any of the substrings
-@cite{DISCARD@comma{} DUMMY@comma{} IGNORE@comma{} JUNK@comma{} UNUSED}, in any casing. Such variables
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED}, in any casing. Such variables
are considered likely to be intentionally used in a situation where
otherwise a warning would be given, so warnings of this kind are
always suppressed for such variables.
Access before elaboration detected at compile time
@item
-A range in a @cite{for} loop that is known to be null or might be null
+A range in a @code{for} loop that is known to be null or might be null
@end itemize
The following section lists compiler switches that are available
@item
@code{-gnatw.o} (values set by out parameters ignored)
+@item
+@code{-gnatw.q} (questionable layout of record types)
+
@item
@code{-gnatw.s} (overridden size clause)
This switch suppresses all optional warning messages, see remaining list
in this section for details on optional warning messages that can be
-individually controlled. Note that unlike switch @emph{-gnatws}, the
-use of switch @emph{-gnatwA} does not suppress warnings that are
+individually controlled. Note that unlike switch @code{-gnatws}, the
+use of switch @code{-gnatwA} does not suppress warnings that are
normally given unconditionally and cannot be individually controlled
(for example, the warning about a missing exit path in a function).
-Also, again unlike switch @emph{-gnatws}, warnings suppressed by
-the use of switch @emph{-gnatwA} can be individually turned back
-on. For example the use of switch @emph{-gnatwA} followed by
-switch @emph{-gnatwd} will suppress all optional warnings except
+Also, again unlike switch @code{-gnatws}, warnings suppressed by
+the use of switch @code{-gnatwA} can be individually turned back
+on. For example the use of switch @code{-gnatwA} followed by
+switch @code{-gnatwd} will suppress all optional warnings except
the warnings for implicit dereferencing.
@end table
If the compiler can tell that only the equality condition is possible,
then it will warn that the '>' or '<' part of the test
is useless and that the operator could be replaced by '='.
-An example would be comparing a @cite{Natural} variable <= 0.
+An example would be comparing a @code{Natural} variable <= 0.
This warning option also generates warnings if
one or both tests is optimized away in a membership test for integer
enumeration types are not included, since it is common for such tests
to include an end point.
-This warning can also be turned on using @emph{-gnatwa}.
+This warning can also be turned on using @code{-gnatwa}.
@end table
@geindex -gnatwC (gcc)
If this switch is set, then the use of a prefix of an access type
in an indexed component, slice, or selected component without an
-explicit @cite{.all} will generate a warning. With this warning
+explicit @code{.all} will generate a warning. With this warning
enabled, access checks occur only at points where an explicit
-@cite{.all} appears in the source code (assuming no warnings are
+@code{.all} appears in the source code (assuming no warnings are
generated as a result of this switch). The default is that such
warnings are not generated.
@end table
@item
@emph{[-gnatw?]}
-Used to tag warnings controlled by the switch @emph{-gnatwx} where x
+Used to tag warnings controlled by the switch @code{-gnatwx} where x
is a letter a-z.
@item
@emph{[-gnatw.?]}
-Used to tag warnings controlled by the switch @emph{-gnatw.x} where x
+Used to tag warnings controlled by the switch @code{-gnatw.x} where x
is a letter a-z.
@item
@emph{[-gnatel]}
Used to tag elaboration information (info) messages generated when the
-static model of elaboration is used and the @emph{-gnatel} switch is set.
+static model of elaboration is used and the @code{-gnatel} switch is set.
@item
@emph{[restriction warning]}
Used to tag warning messages for restriction violations, activated by use
-of the pragma @emph{Restriction_Warnings}.
+of the pragma @code{Restriction_Warnings}.
@item
@emph{[warning-as-error]}
@emph{[enabled by default]}
Used to tag all other warnings that are always given by default, unless
warnings are completely suppressed using pragma @emph{Warnings(Off)} or
-the switch @emph{-gnatws}.
+the switch @code{-gnatws}.
@end itemize
@end quotation
@end table
If this switch is set, then warning messages return to the default
mode in which warnings and info messages are not tagged as described above for
-@cite{-gnatw.d}.
+@code{-gnatw.d}.
@end table
@geindex -gnatwe (gcc)
@geindex activate every optional warning
This switch activates all optional warnings, including those which
-are not activated by @cite{-gnatwa}. The use of this switch is not
+are not activated by @code{-gnatwa}. The use of this switch is not
recommended for normal use. If you turn this switch on, it is almost
certain that you will get large numbers of useless warnings. The
-warnings that are excluded from @cite{-gnatwa} are typically highly
+warnings that are excluded from @code{-gnatwa} are typically highly
specialized warnings that are suitable for use only in code that has
been specifically designed according to specialized coding rules.
@end table
+@geindex -gnatwE (gcc)
+
+@geindex Warnings
+@geindex treat as error
+
+
+@table @asis
+
+@item @code{-gnatwE}
+
+@emph{Treat all run-time exception warnings as errors.}
+
+This switch causes warning messages regarding errors that will be raised
+during run-time execution to be treated as errors.
+@end table
+
@geindex -gnatwf (gcc)
This switch causes a warning to be generated if a formal parameter
is not referenced in the body of the subprogram. This warning can
-also be turned on using @emph{-gnatwu}. The
+also be turned on using @code{-gnatwu}. The
default is that these warnings are not generated.
@end table
This switch suppresses warnings for unreferenced formal
parameters. Note that the
-combination @emph{-gnatwu} followed by @emph{-gnatwF} has the
+combination @code{-gnatwu} followed by @code{-gnatwF} has the
effect of warning on unreferenced entities other than subprogram
formals.
@end table
This switch sets the warning categories that are used by the standard
GNAT style. Currently this is equivalent to
-@emph{-gnatwAao.sI.C.V.X}
+@code{-gnatwAao.q.s.CI.V.X.Z}
but more warnings may be added in the future without advanced notice.
@end table
@emph{Activate warnings on implementation units.}
This switch activates warnings for a @emph{with} of an internal GNAT
-implementation unit, defined as any unit from the @cite{Ada},
-@cite{Interfaces}, @cite{GNAT},
-or @cite{System}
+implementation unit, defined as any unit from the @code{Ada},
+@code{Interfaces}, @code{GNAT},
+or @code{System}
hierarchies that is not
documented in either the Ada Reference Manual or the GNAT
Programmer's Reference Manual. Such units are intended only
@geindex Obsolescent features
If this warning option is activated, then warnings are generated for
-calls to subprograms marked with @cite{pragma Obsolescent} and
+calls to subprograms marked with @code{pragma Obsolescent} and
for use of features in Annex J of the Ada Reference Manual. In the
case of Annex J, not all features are flagged. In particular use
-of the renamed packages (like @cite{Text_IO}) and use of package
-@cite{ASCII} are not flagged, since these are very common and
+of the renamed packages (like @code{Text_IO}) and use of package
+@code{ASCII} are not flagged, since these are very common and
would generate many annoying positive warnings. The default is that
such warnings are not generated.
In addition to the above cases, warnings are also generated for
GNAT features that have been provided in past versions but which
have been superseded (typically by features in the new Ada standard).
-For example, @cite{pragma Ravenscar} will be flagged since its
-function is replaced by @cite{pragma Profile(Ravenscar)}, and
-@cite{pragma Interface_Name} will be flagged since its function
-is replaced by @cite{pragma Import}.
+For example, @code{pragma Ravenscar} will be flagged since its
+function is replaced by @code{pragma Profile(Ravenscar)}, and
+@code{pragma Interface_Name} will be flagged since its function
+is replaced by @code{pragma Import}.
Note that this warning option functions differently from the
-restriction @cite{No_Obsolescent_Features} in two respects.
+restriction @code{No_Obsolescent_Features} in two respects.
First, the restriction applies only to annex J features.
-Second, the restriction does flag uses of package @cite{ASCII}.
+Second, the restriction does flag uses of package @code{ASCII}.
@end table
@geindex -gnatwJ (gcc)
This switch activates warnings for possible elaboration problems,
including suspicious use
-of @cite{Elaborate} pragmas, when using the static elaboration model, and
-possible situations that may raise @cite{Program_Error} when using the
+of @code{Elaborate} pragmas, when using the static elaboration model, and
+possible situations that may raise @code{Program_Error} when using the
dynamic elaboration model.
See the section in this guide on elaboration checking for further details.
The default is that such warnings
This switch sets normal warning mode, in which enabled warnings are
issued and treated as warnings rather than errors. This is the default
-mode. the switch @emph{-gnatwn} can be used to cancel the effect of
-an explicit @emph{-gnatws} or
-@emph{-gnatwe}. It also cancels the effect of the
-implicit @emph{-gnatwe} that is activated by the
-use of @emph{-gnatg}.
+mode. the switch @code{-gnatwn} can be used to cancel the effect of
+an explicit @code{-gnatws} or
+@code{-gnatwe}. It also cancels the effect of the
+implicit @code{-gnatwe} that is activated by the
+use of @code{-gnatg}.
@end table
@geindex -gnatw.n (gcc)
@emph{Activate warnings on ineffective pragma Inlines.}
This switch activates warnings for failure of front end inlining
-(activated by @emph{-gnatN}) to inline a particular call. There are
+(activated by @code{-gnatN}) to inline a particular call. There are
many reasons for not being able to inline a call, including most
commonly that the call is too complex to inline. The default is
that such warnings are not given.
clear and the use of parentheses is preferred.
@end table
+@geindex -gnatw.q (gcc)
+
+@geindex Layout
+@geindex warnings
+
+
+@table @asis
+
+@item @code{-gnatw.q}
+
+@emph{Activate warnings on questionable layout of record types.}
+
+This switch activates warnings for cases where the default layout of
+a record type, that is to say the layout of its components in textual
+order of the source code, would very likely cause inefficiencies in
+the code generated by the compiler, both in terms of space and speed
+during execution. One warning is issued for each problematic component
+without representation clause in the nonvariant part and then in each
+variant recursively, if any.
+
+The purpose of these warnings is neither to prescribe an optimal layout
+nor to force the use of representation clauses, but rather to get rid of
+the most blatant inefficiencies in the layout. Therefore, the default
+layout is matched against the following synthetic ordered layout and
+the deviations are flagged on a component-by-component basis:
+
+
+@itemize *
+
+@item
+first all components or groups of components whose length is fixed
+and a multiple of the storage unit,
+
+@item
+then the remaining components whose length is fixed and not a multiple
+of the storage unit,
+
+@item
+then the remaining components whose length doesn't depend on discriminants
+(that is to say, with variable but uniform length for all objects),
+
+@item
+then all components whose length depends on discriminants,
+
+@item
+finally the variant part (if any),
+@end itemize
+
+for the nonvariant part and for each variant recursively, if any.
+
+The exact wording of the warning depends on whether the compiler is allowed
+to reorder the components in the record type or precluded from doing it by
+means of pragma @code{No_Component_Reordering}.
+
+The default is that these warnings are not given.
+@end table
+
+@geindex -gnatw.Q (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.Q}
+
+@emph{Suppress warnings on questionable layout of record types.}
+
+This switch suppresses warnings for cases where the default layout of
+a record type would very likely cause inefficiencies.
+@end table
+
@geindex -gnatwr (gcc)
Type conversion that converts an expression to its own type.
@item
-Use of the attribute @cite{Base} where @cite{typ'Base} is the same
-as @cite{typ}.
+Use of the attribute @code{Base} where @code{typ'Base} is the same
+as @code{typ}.
@item
-Use of pragma @cite{Pack} when all components are placed by a record
+Use of pragma @code{Pack} when all components are placed by a record
representation clause.
@item
to be non-negative
@item
-Comparison of boolean expressions to an explicit True value.
+Comparison of an object or (unary or binary) operation of boolean type to
+an explicit True value.
@end itemize
The default is that warnings for redundant constructs are not given.
both warnings that can be controlled by switches described in this
section, and those that are normally given unconditionally. The
effect of this suppress action can only be cancelled by a subsequent
-use of the switch @emph{-gnatwn}.
+use of the switch @code{-gnatwn}.
-Note that switch @emph{-gnatws} does not suppress
-warnings from the @emph{gcc} back end.
-To suppress these back end warnings as well, use the switch @emph{-w}
-in addition to @emph{-gnatws}. Also this switch has no effect on the
+Note that switch @code{-gnatws} does not suppress
+warnings from the @code{gcc} back end.
+To suppress these back end warnings as well, use the switch @code{-w}
+in addition to @code{-gnatws}. Also this switch has no effect on the
handling of style check messages.
@end table
@emph{Activate warnings on suspicious contracts.}
This switch activates warnings on suspicious contracts. This includes
-warnings on suspicious postconditions (whether a pragma @cite{Postcondition} or a
-@cite{Post} aspect in Ada 2012) and suspicious contract cases (pragma or aspect
-@cite{Contract_Cases}). A function postcondition or contract case is suspicious
+warnings on suspicious postconditions (whether a pragma @code{Postcondition} or a
+@code{Post} aspect in Ada 2012) and suspicious contract cases (pragma or aspect
+@code{Contract_Cases}). A function postcondition or contract case is suspicious
when no postcondition or contract case for this function mentions the result
of the function. A procedure postcondition or contract case is suspicious
when it only refers to the pre-state of the procedure, because in that case
and not
referenced. In the case of packages, a warning is also generated if
no entities in the package are referenced. This means that if a with'ed
-package is referenced but the only references are in @cite{use}
-clauses or @cite{renames}
+package is referenced but the only references are in @code{use}
+clauses or @code{renames}
declarations, a warning is still generated. A warning is also generated
for a generic package that is @emph{with}ed but never instantiated.
In the case where a package or subprogram body is compiled, and there
@emph{with} can be moved to the body. The default is that
such warnings are not generated.
This switch also activates warnings on unreferenced formals
-(it includes the effect of @emph{-gnatwf}).
+(it includes the effect of @code{-gnatwf}).
@end table
@geindex -gnatwU (gcc)
This switch suppresses warnings for unused entities and packages.
It also turns off warnings on unreferenced formals (and thus includes
-the effect of @emph{-gnatwF}).
+the effect of @code{-gnatwF}).
@end table
@geindex -gnatw.u (gcc)
@emph{Activate warnings on unordered enumeration types.}
This switch causes enumeration types to be considered as conceptually
-unordered, unless an explicit pragma @cite{Ordered} is given for the type.
+unordered, unless an explicit pragma @code{Ordered} is given for the type.
The effect is to generate warnings in clients that use explicit comparisons
or subranges, since these constructs both treat objects of the type as
ordered. (A @emph{client} is defined as a unit that is other than the unit in
which the type is declared, or its body or subunits.) Please refer to
-the description of pragma @cite{Ordered} in the
+the description of pragma @code{Ordered} in the
@cite{GNAT Reference Manual} for further details.
The default is that such warnings are not generated.
@end table
@emph{Activate warnings on Warnings Off pragmas.}
-This switch activates warnings for use of @cite{pragma Warnings (Off@comma{} entity)}
+This switch activates warnings for use of @code{pragma Warnings (Off, entity)}
where either the pragma is entirely useless (because it suppresses no
-warnings), or it could be replaced by @cite{pragma Unreferenced} or
-@cite{pragma Unmodified}.
+warnings), or it could be replaced by @code{pragma Unreferenced} or
+@code{pragma Unmodified}.
Also activates warnings for the case of
Warnings (Off, String), where either there is no matching
Warnings (On, String), or the Warnings (Off) did not suppress any warning.
@emph{Suppress warnings on unnecessary Warnings Off pragmas.}
-This switch suppresses warnings for use of @cite{pragma Warnings (Off@comma{} ...)}.
+This switch suppresses warnings for use of @code{pragma Warnings (Off, ...)}.
@end table
@geindex -gnatwx (gcc)
with older versions. For example, Ada 2005 programs will almost
always work when compiled as Ada 2012.
However there are some exceptions (for example the fact that
-@cite{some} is now a reserved word in Ada 2012). This
+@code{some} is now a reserved word in Ada 2012). This
switch activates several warnings to help in identifying
and correcting such incompatibilities. The default is that
these warnings are generated. Note that at one point Ada 2005
@emph{Activate warnings for size not a multiple of alignment.}
This switch activates warnings for cases of record types with
-specified @cite{Size} and @cite{Alignment} attributes where the
+specified @code{Size} and @code{Alignment} attributes where the
size is not a multiple of the alignment, resulting in an object
size that is greater than the specified size. The default
is that such warnings are generated.
@emph{Suppress warnings for size not a multiple of alignment.}
This switch suppresses warnings for cases of record types with
-specified @cite{Size} and @cite{Alignment} attributes where the
+specified @code{Size} and @code{Alignment} attributes where the
size is not a multiple of the alignment, resulting in an object
size that is greater than the specified size.
The warning can also be
-suppressed by giving an explicit @cite{Object_Size} value.
+suppressed by giving an explicit @code{Object_Size} value.
@end table
@geindex -Wunused (gcc)
@item @code{-Wunused}
-The warnings controlled by the @emph{-gnatw} switch are generated by
-the front end of the compiler. The @emph{GCC} back end can provide
-additional warnings and they are controlled by the @emph{-W} switch.
-For example, @emph{-Wunused} activates back end
+The warnings controlled by the @code{-gnatw} switch are generated by
+the front end of the compiler. The GCC back end can provide
+additional warnings and they are controlled by the @code{-W} switch.
+For example, @code{-Wunused} activates back end
warnings for entities that are declared but not referenced.
@end table
@item @code{-Wuninitialized}
-Similarly, @emph{-Wuninitialized} activates
+Similarly, @code{-Wuninitialized} activates
the back end warning for uninitialized variables. This switch must be
used in conjunction with an optimization level greater than zero.
@end table
@item @code{-Wstack-usage=@emph{len}}
-Warn if the stack usage of a subprogram might be larger than @cite{len} bytes.
+Warn if the stack usage of a subprogram might be larger than @code{len} bytes.
See @ref{f5,,Static Stack Usage Analysis} for details.
@end table
@item @code{-Wall}
-This switch enables most warnings from the @emph{GCC} back end.
+This switch enables most warnings from the GCC back end.
The code generator detects a number of warning situations that are missed
-by the @emph{GNAT} front end, and this switch can be used to activate them.
+by the GNAT front end, and this switch can be used to activate them.
The use of this switch also sets the default front end warning mode to
-@emph{-gnatwa}, that is, most front end warnings activated as well.
+@code{-gnatwa}, that is, most front end warnings activated as well.
@end table
@geindex -w (gcc)
@item @code{-w}
-Conversely, this switch suppresses warnings from the @emph{GCC} back end.
+Conversely, this switch suppresses warnings from the GCC back end.
The use of this switch also sets the default front end warning mode to
-@emph{-gnatws}, that is, front end warnings suppressed as well.
+@code{-gnatws}, that is, front end warnings suppressed as well.
@end table
@geindex -Werror (gcc)
@item @code{-Werror}
-This switch causes warnings from the @emph{GCC} back end to be treated as
+This switch causes warnings from the GCC back end to be treated as
errors. The warning string still appears, but the warning messages are
counted as errors, and prevent the generation of an object file.
@end table
will turn on all optional warnings except for unrecognized pragma warnings,
and also specify that warnings should be treated as errors.
-When no switch @emph{-gnatw} is used, this is equivalent to:
+When no switch @code{-gnatw} is used, this is equivalent to:
@quotation
@item
@code{-gnatwq}
+@item
+@code{-gnatw.Q}
+
@item
@code{-gnatwR}
@geindex Subtype predicates
-The @cite{-gnata} option is equivalent to the following Assertion_Policy pragma:
+The @code{-gnata} option is equivalent to the following @code{Assertion_Policy} pragma:
@example
pragma Assertion_Policy (Check);
Type_Invariant'Class => Check);
@end example
-The pragmas @cite{Assert} and @cite{Debug} normally have no effect and
-are ignored. This switch, where @code{a} stands for assert, causes
-pragmas @cite{Assert} and @cite{Debug} to be activated. This switch also
+The pragmas @code{Assert} and @code{Debug} normally have no effect and
+are ignored. This switch, where @code{a} stands for 'assert', causes
+pragmas @code{Assert} and @code{Debug} to be activated. This switch also
causes preconditions, postconditions, subtype predicates, and
type invariants to be activated.
=> <Boolean-expression>;
@end example
-The @cite{Assert} pragma causes @cite{Boolean-expression} to be tested.
-If the result is @cite{True}, the pragma has no effect (other than
+The @code{Assert} pragma causes @code{Boolean-expression} to be tested.
+If the result is @code{True}, the pragma has no effect (other than
possible side effects from evaluating the expression). If the result is
-@cite{False}, the exception @cite{Assert_Failure} declared in the package
-@cite{System.Assertions} is raised (passing @cite{static-string-expression}, if
+@code{False}, the exception @code{Assert_Failure} declared in the package
+@code{System.Assertions} is raised (passing @code{static-string-expression}, if
present, as the message associated with the exception). If no string
expression is given, the default is a string containing the file name and
line number of the pragma.
-The @cite{Debug} pragma causes @cite{procedure} to be called. Note that
-@cite{pragma Debug} may appear within a declaration sequence, allowing
+The @code{Debug} pragma causes @code{procedure} to be called. Note that
+@code{pragma Debug} may appear within a declaration sequence, allowing
debugging procedures to be called between declarations.
-For the aspect specification, the @cite{<Boolean-expression>} is evaluated.
-If the result is @cite{True}, the aspect has no effect. If the result
-is @cite{False}, the exception @cite{Assert_Failure} is raised.
+For the aspect specification, the @code{Boolean-expression} is evaluated.
+If the result is @code{True}, the aspect has no effect. If the result
+is @code{False}, the exception @code{Assert_Failure} is raised.
@end table
@node Validity Checking,Style Checking,Debugging and Assertion Control,Compiler Switches
It is an error to read an invalid value, but the RM does not require
run-time checks to detect such errors, except for some minimal
checking to prevent erroneous execution (i.e. unpredictable
-behavior). This corresponds to the @emph{-gnatVd} switch below,
+behavior). This corresponds to the @code{-gnatVd} switch below,
which is the default. For example, by default, if the expression of a
case statement is invalid, it will raise Constraint_Error rather than
causing a wild jump, and if an array index on the left-hand side of an
assignment is invalid, it will raise Constraint_Error rather than
overwriting an arbitrary memory location.
-The @emph{-gnatVa} may be used to enable additional validity checks,
+The @code{-gnatVa} may be used to enable additional validity checks,
which are not required by the RM. These checks are often very
expensive (which is why the RM does not require them). These checks
are useful in tracking down uninitialized variables, but they are
If performance is a consideration, leading to the need to optimize,
then the validity checking options should not be used.
-The other @emph{-gnatV}@code{x} switches below allow finer-grained
+The other @code{-gnatV@emph{x}} switches below allow finer-grained
control; you can enable whichever validity checks you desire. However,
-for most debugging purposes, @emph{-gnatVa} is sufficient, and the
-default @emph{-gnatVd} (i.e. standard Ada behavior) is usually
+for most debugging purposes, @code{-gnatVa} is sufficient, and the
+default @code{-gnatVd} (i.e. standard Ada behavior) is usually
sufficient for non-debugging use.
-The @emph{-gnatB} switch tells the compiler to assume that all
+The @code{-gnatB} switch tells the compiler to assume that all
values are valid (that is, within their declared subtype range)
except in the context of a use of the Valid attribute. This means
the compiler can generate more efficient code, since the range
of values is better known at compile time. However, an uninitialized
variable can cause wild jumps and memory corruption in this mode.
-The @emph{-gnatV}@code{x} switch allows control over the validity
+The @code{-gnatV@emph{x}} switch allows control over the validity
checking mode as described below.
The @code{x} argument is a string of letters that
indicate validity checks that are performed or not performed in addition
@emph{All validity checks.}
All validity checks are turned on.
-That is, @emph{-gnatVa} is
-equivalent to @emph{gnatVcdfimorst}.
+That is, @code{-gnatVa} is
+equivalent to @code{gnatVcdfimorst}.
@end table
@geindex -gnatVc (gcc)
of the subtype. If it is not, Constraint_Error is raised.
For assignments to array components, a check is done that the expression used
as index is within the range. If it is not, Constraint_Error is raised.
-Both these validity checks may be turned off using switch @emph{-gnatVD}.
-They are turned on by default. If @emph{-gnatVD} is specified, a subsequent
-switch @emph{-gnatVd} will leave the checks turned on.
-Switch @emph{-gnatVD} should be used only if you are sure that all such
+Both these validity checks may be turned off using switch @code{-gnatVD}.
+They are turned on by default. If @code{-gnatVD} is specified, a subsequent
+switch @code{-gnatVd} will leave the checks turned on.
+Switch @code{-gnatVD} should be used only if you are sure that all such
expressions have valid values. If you use this switch and invalid values
are present, then the program is erroneous, and wild jumps or memory
overwriting may occur.
In the absence of this switch, assignments to record or array components are
not validity checked, even if validity checks for assignments generally
-(@emph{-gnatVc}) are turned on. In Ada, assignment of composite values do not
+(@code{-gnatVc}) are turned on. In Ada, assignment of composite values do not
require valid data, but assignment of individual components does. So for
example, there is a difference between copying the elements of an array with a
slice assignment, compared to assigning element by element in a loop. This
@emph{Validity checks for floating-point values.}
In the absence of this switch, validity checking occurs only for discrete
-values. If @emph{-gnatVf} is specified, then validity checking also applies
+values. If @code{-gnatVf} is specified, then validity checking also applies
for floating-point values, and NaNs and infinities are considered invalid,
as well as out of range values for constrained types. Note that this means
that standard IEEE infinity mode is not allowed. The exact contexts
in which floating-point values are checked depends on the setting of other
-options. For example, @emph{-gnatVif} or @emph{-gnatVfi}
+options. For example, @code{-gnatVif} or @code{-gnatVfi}
(the order does not matter) specifies that floating-point parameters of mode
-@cite{in} should be validity checked.
+@code{in} should be validity checked.
@end table
@geindex -gnatVi (gcc)
@item @code{-gnatVi}
-@emph{Validity checks for `in` mode parameters.}
+@emph{Validity checks for `@w{`}in`@w{`} mode parameters.}
-Arguments for parameters of mode @cite{in} are validity checked in function
+Arguments for parameters of mode @code{in} are validity checked in function
and procedure calls at the point of call.
@end table
@item @code{-gnatVm}
-@emph{Validity checks for `in out` mode parameters.}
+@emph{Validity checks for `@w{`}in out`@w{`} mode parameters.}
-Arguments for parameters of mode @cite{in out} are validity checked in
-procedure calls at the point of call. The @cite{'m'} here stands for
+Arguments for parameters of mode @code{in out} are validity checked in
+procedure calls at the point of call. The @code{'m'} here stands for
modify, since this concerns parameters that can be modified by the call.
-Note that there is no specific option to test @cite{out} parameters,
+Note that there is no specific option to test @code{out} parameters,
but any reference within the subprogram will be tested in the usual
manner, and if an invalid value is copied back, any reference to it
will be subject to validity checking.
This switch turns off all validity checking, including the default checking
for case statements and left hand side subscripts. Note that the use of
-the switch @emph{-gnatp} suppresses all run-time checks, including
-validity checks, and thus implies @emph{-gnatVn}. When this switch
-is used, it cancels any other @emph{-gnatV} previously issued.
+the switch @code{-gnatp} suppresses all run-time checks, including
+validity checks, and thus implies @code{-gnatVn}. When this switch
+is used, it cancels any other @code{-gnatV} previously issued.
@end table
@geindex -gnatVo (gcc)
@emph{Validity checks for operator and attribute operands.}
Arguments for predefined operators and attributes are validity checked.
-This includes all operators in package @cite{Standard},
-the shift operators defined as intrinsic in package @cite{Interfaces}
-and operands for attributes such as @cite{Pos}. Checks are also made
+This includes all operators in package @code{Standard},
+the shift operators defined as intrinsic in package @code{Interfaces}
+and operands for attributes such as @code{Pos}. Checks are also made
on individual component values for composite comparisons, and on the
expressions in type conversions and qualified expressions. Checks are
also made on explicit ranges using @code{..} (e.g., slices, loops etc).
@emph{Validity checks for parameters.}
This controls the treatment of parameters within a subprogram (as opposed
-to @emph{-gnatVi} and @emph{-gnatVm} which control validity testing
+to @code{-gnatVi} and @code{-gnatVm} which control validity testing
of parameters on a call. If either of these call options is used, then
normally an assumption is made within a subprogram that the input arguments
have been validity checking at the point of call, and do not need checking
-again within a subprogram). If @emph{-gnatVp} is set, then this assumption
+again within a subprogram). If @code{-gnatVp} is set, then this assumption
is not made, and parameters are not assumed to be valid, so their validity
will be checked (or rechecked) within the subprogram.
@end table
@emph{Validity checks for function returns.}
-The expression in @cite{return} statements in functions is validity
+The expression in @code{return} statements in functions is validity
checked.
@end table
@emph{Validity checks for tests.}
-Expressions used as conditions in @cite{if}, @cite{while} or @cite{exit}
+Expressions used as conditions in @code{if}, @code{while} or @code{exit}
statements are checked, as well as guard expressions in entry calls.
@end table
-The @emph{-gnatV} switch may be followed by a string of letters
+The @code{-gnatV} switch may be followed by a string of letters
to turn on a series of validity checking options.
For example, @code{-gnatVcr}
specifies that in addition to the default validity checking, copies and
function return expressions are to be validity checked.
In order to make it easier to specify the desired combination of effects,
-the upper case letters @cite{CDFIMORST} may
+the upper case letters @code{CDFIMORST} may
be used to turn off the corresponding lower case option.
Thus @code{-gnatVaM} turns on all validity checking options except for
-checking of @cite{**in out**} procedure arguments.
+checking of @code{in out} parameters.
The specification of additional validity checking generates extra code (and
-in the case of @emph{-gnatVa} the code expansion can be substantial).
+in the case of @code{-gnatVa} the code expansion can be substantial).
However, these additional checks can be very useful in detecting
uninitialized variables, incorrect use of unchecked conversion, and other
-errors leading to invalid values. The use of pragma @cite{Initialize_Scalars}
+errors leading to invalid values. The use of pragma @code{Initialize_Scalars}
is useful in conjunction with the extra validity checking, since this
ensures that wherever possible uninitialized variables have invalid values.
-See also the pragma @cite{Validity_Checks} which allows modification of
+See also the pragma @code{Validity_Checks} which allows modification of
the validity checking mode at the program source level, and also allows for
temporary disabling of validity checks.
@geindex -gnaty (gcc)
-The @emph{-gnatyx} switch causes the compiler to
+The @code{-gnatyx} switch causes the compiler to
enforce specified style rules. A limited set of style rules has been used
in writing the GNAT sources themselves. This switch allows user programs
to activate all or some of these checks. If the source program fails a
specified style check, an appropriate message is given, preceded by
the character sequence '(style)'. This message does not prevent
-successful compilation (unless the @emph{-gnatwe} switch is used).
+successful compilation (unless the @code{-gnatwe} switch is used).
Note that this is by no means intended to be a general facility for
checking arbitrary coding standards. It is simply an embedding of the
some subset of them.
-The string @cite{x} is a sequence of letters or digits
+The string @code{x} is a sequence of letters or digits
indicating the particular style
checks to be performed. The following checks are defined:
@emph{Specify indentation level.}
If a digit from 1-9 appears
-in the string after @emph{-gnaty}
+in the string after @code{-gnaty}
then proper indentation is checked, with the digit indicating the
indentation level required. A value of zero turns off this style check.
The general style of required indentation is as specified by
the examples in the Ada Reference Manual. Full line comments must be
-aligned with the @cite{--} starting on a column that is a multiple of
+aligned with the @code{--} starting on a column that is a multiple of
the alignment level, or they may be aligned the same way as the following
non-blank line (this is useful when full line comments appear in the middle
of a statement, or they may be aligned with the source line on the previous
@emph{Check attribute casing.}
-Attribute names, including the case of keywords such as @cite{digits}
+Attribute names, including the case of keywords such as @code{digits}
used as attributes names, must be written in mixed case, that is, the
initial letter and any letter following an underscore must be uppercase.
All other letters must be lowercase.
The use of AND/OR operators is not permitted except in the cases of modular
operands, array operands, and simple stand-alone boolean variables or
-boolean constants. In all other cases @cite{and then}/@cite{or else} are
+boolean constants. In all other cases @code{and then}/@cite{or else} are
required.
@end table
@itemize *
@item
-The '@cite{--}' that starts the column must either start in column one,
+The @code{--} that starts the column must either start in column one,
or else at least one blank must precede this sequence.
@item
Comments that follow other tokens on a line must have at least one blank
-following the '@cite{--}' at the start of the comment.
+following the @code{--} at the start of the comment.
@item
Full line comments must have at least two blanks following the
-'@cite{--}' that starts the comment, with the following exceptions.
+@code{--} that starts the comment, with the following exceptions.
@item
-A line consisting only of the '@cite{--}' characters, possibly preceded
+A line consisting only of the @code{--} characters, possibly preceded
by blanks is permitted.
@item
-A comment starting with '@cite{--x}' where @cite{x} is a special character
+A comment starting with @code{--x} where @code{x} is a special character
is permitted.
-This allows proper processing of the output generated by specialized tools
-including @emph{gnatprep} (where '@cite{--!}' is used) and the SPARK
+This allows proper processing of the output from specialized tools
+such as @code{gnatprep} (where @code{--!} is used) and in earlier versions of the SPARK
annotation
-language (where '@cite{--#}' is used). For the purposes of this rule, a
+language (where @code{--#} is used). For the purposes of this rule, a
special character is defined as being in one of the ASCII ranges
-@cite{16#21#...16#2F#} or @cite{16#3A#...16#3F#}.
+@code{16#21#...16#2F#} or @code{16#3A#...16#3F#}.
Note that this usage is not permitted
-in GNAT implementation units (i.e., when @emph{-gnatg} is used).
+in GNAT implementation units (i.e., when @code{-gnatg} is used).
@item
A line consisting entirely of minus signs, possibly preceded by blanks, is
signs are used to form the top and bottom of the box.
@item
-A comment that starts and ends with '@cite{--}' is permitted as long as at
-least one blank follows the initial '@cite{--}'. Together with the preceding
+A comment that starts and ends with @code{--} is permitted as long as at
+least one blank follows the initial @code{--}. Together with the preceding
rule, this allows the construction of box comments, as shown in the following
example:
@emph{Check comments, single space.}
-This is identical to @cite{c} except that only one space
-is required following the @cite{--} of a comment instead of two.
+This is identical to @code{c} except that only one space
+is required following the @code{--} of a comment instead of two.
@end table
@geindex -gnatyd (gcc)
@emph{Check end/exit labels.}
-Optional labels on @cite{end} statements ending subprograms and on
-@cite{exit} statements exiting named loops, are required to be present.
+Optional labels on @code{end} statements ending subprograms and on
+@code{exit} statements exiting named loops, are required to be present.
@end table
@geindex -gnatyf (gcc)
The set of style check switches is set to match that used by the GNAT sources.
This may be useful when developing code that is eventually intended to be
-incorporated into GNAT. Currently this is equivalent to @emph{-gnatwydISux})
+incorporated into GNAT. Currently this is equivalent to @code{-gnatwydISux})
but additional style switches may be added to this set in the future without
advance notice.
@end table
@emph{Check if-then layout.}
-The keyword @cite{then} must appear either on the same
-line as corresponding @cite{if}, or on a line on its own, lined
-up under the @cite{if}.
+The keyword @code{then} must appear either on the same
+line as corresponding @code{if}, or on a line on its own, lined
+up under the @code{if}.
@end table
@geindex -gnatyI (gcc)
@emph{check mode IN keywords.}
-Mode @cite{in} (the default mode) is not
-allowed to be given explicitly. @cite{in out} is fine,
-but not @cite{in} on its own.
+Mode @code{in} (the default mode) is not
+allowed to be given explicitly. @code{in out} is fine,
+but not @code{in} on its own.
@end table
@geindex -gnatyk (gcc)
@emph{Check keyword casing.}
All keywords must be in lower case (with the exception of keywords
-such as @cite{digits} used as attribute names to which this check
+such as @code{digits} used as attribute names to which this check
does not apply).
@end table
Layout of statement and declaration constructs must follow the
recommendations in the Ada Reference Manual, as indicated by the
-form of the syntax rules. For example an @cite{else} keyword must
-be lined up with the corresponding @cite{if} keyword.
+form of the syntax rules. For example an @code{else} keyword must
+be lined up with the corresponding @code{if} keyword.
There are two respects in which the style rule enforced by this check
option are more liberal than those in the Ada Reference Manual. First
in the case of record declarations, it is permissible to put the
-@cite{record} keyword on the same line as the @cite{type} keyword, and
-then the @cite{end} in @cite{end record} must line up under @cite{type}.
+@code{record} keyword on the same line as the @code{type} keyword, and
+then the @code{end} in @code{end record} must line up under @code{type}.
This is also permitted when the type declaration is split on two lines.
For example, any of the following three layouts is acceptable:
@end example
Second, in the case of a block statement, a permitted alternative
-is to put the block label on the same line as the @cite{declare} or
-@cite{begin} keyword, and then line the @cite{end} keyword up under
+is to put the block label on the same line as the @code{declare} or
+@code{begin} keyword, and then line the @code{end} keyword up under
the block label. For example both the following are permitted:
@example
Any identifier from Standard must be cased
to match the presentation in the Ada Reference Manual (for example,
-@cite{Integer} and @cite{ASCII.NUL}).
+@code{Integer} and @code{ASCII.NUL}).
@end table
@geindex -gnatyN (gcc)
@emph{Check no statements after then/else.}
No statements are allowed
-on the same line as a @cite{then} or @cite{else} keyword following the
-keyword in an @cite{if} statement. @cite{or else} and @cite{and then} are not
-affected, and a special exception allows a pragma to appear after @cite{else}.
+on the same line as a @code{then} or @code{else} keyword following the
+keyword in an @code{if} statement. @code{or else} and @code{and then} are not
+affected, and a special exception allows a pragma to appear after @code{else}.
@end table
@geindex -gnatyt (gcc)
@itemize *
@item
-The keywords @cite{abs} and @cite{not} must be followed by a space.
+The keywords @code{abs} and @code{not} must be followed by a space.
@item
-The token @cite{=>} must be surrounded by spaces.
+The token @code{=>} must be surrounded by spaces.
@item
-The token @cite{<>} must be preceded by a space or a left parenthesis.
+The token @code{<>} must be preceded by a space or a left parenthesis.
@item
-Binary operators other than @cite{**} must be surrounded by spaces.
-There is no restriction on the layout of the @cite{**} binary operator.
+Binary operators other than @code{**} must be surrounded by spaces.
+There is no restriction on the layout of the @code{**} binary operator.
@item
Colon must be surrounded by spaces.
@end itemize
Exactly one blank (and no other white space) must appear between
-a @cite{not} token and a following @cite{in} token.
+a @code{not} token and a following @code{in} token.
@end table
@geindex -gnatyu (gcc)
@emph{Check extra parentheses.}
Unnecessary extra level of parentheses (C-style) are not allowed
-around conditions in @cite{if} statements, @cite{while} statements and
-@cite{exit} statements.
+around conditions in @code{if} statements, @code{while} statements and
+@code{exit} statements.
@end table
@geindex -gnatyy (gcc)
@emph{Set all standard style check options.}
-This is equivalent to @cite{gnaty3aAbcefhiklmnprst}, that is all checking
-options enabled with the exception of @emph{-gnatyB}, @emph{-gnatyd},
-@emph{-gnatyI}, @emph{-gnatyLnnn}, @emph{-gnatyo}, @emph{-gnatyO},
-@emph{-gnatyS}, @emph{-gnatyu}, and @emph{-gnatyx}.
+This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
+options enabled with the exception of @code{-gnatyB}, @code{-gnatyd},
+@code{-gnatyI}, @code{-gnatyLnnn}, @code{-gnatyo}, @code{-gnatyO},
+@code{-gnatyS}, @code{-gnatyu}, and @code{-gnatyx}.
@end table
@geindex -gnaty- (gcc)
This causes any subsequent options in the string to act as canceling the
corresponding style check option. To cancel maximum nesting level control,
-use @emph{L} parameter witout any integer value after that, because any
-digit following @emph{-} in the parameter string of the @emph{-gnaty}
-option will be threated as canceling indentation check. The same is true
-for @emph{M} parameter. @emph{y} and @emph{N} parameters are not
+use the @code{L} parameter without any integer value after that, because any
+digit following @emph{-} in the parameter string of the @code{-gnaty}
+option will be treated as canceling the indentation check. The same is true
+for the @code{M} parameter. @code{y} and @code{N} parameters are not
allowed after @emph{-}.
@end table
details on the violation. The initial characters of such messages are
always '@cite{(style)}'. Note that these messages are treated as warning
messages, so they normally do not prevent the generation of an object
-file. The @emph{-gnatwe} switch can be used to treat warning messages,
+file. The @code{-gnatwe} switch can be used to treat warning messages,
including style messages, as fatal errors.
The switch @code{-gnaty} on its own (that is not
followed by any letters or digits) is equivalent
-to the use of @emph{-gnatyy} as described above, that is all
+to the use of @code{-gnatyy} as described above, that is all
built-in standard style check options are enabled.
The switch @code{-gnatyN} clears any previously set style checks.
By default, the following checks are suppressed: stack overflow
checks, and checks for access before elaboration on subprogram
calls. All other checks, including overflow checks, range checks and
-array bounds checks, are turned on by default. The following @emph{gcc}
+array bounds checks, are turned on by default. The following @code{gcc}
switches refine this default behavior.
@geindex -gnatp (gcc)
@geindex suppressing
This switch causes the unit to be compiled
-as though @cite{pragma Suppress (All_checks)}
+as though @code{pragma Suppress (All_checks)}
had been present in the source. Validity checks are also eliminated (in
-other words @emph{-gnatp} also implies @emph{-gnatVn}.
+other words @code{-gnatp} also implies @code{-gnatVn}.
Use this switch to improve the performance
of the code at the expense of safety in the presence of invalid data or
program bugs.
execution if that assumption is wrong.
The checks subject to suppression include all the checks defined by the Ada
-standard, the additional implementation defined checks @cite{Alignment_Check},
-@cite{Duplicated_Tag_Check}, @cite{Predicate_Check}, Container_Checks, Tampering_Check,
-and @cite{Validity_Check}, as well as any checks introduced using @cite{pragma Check_Name}. Note that @cite{Atomic_Synchronization} is not automatically
-suppressed by use of this option.
+standard, the additional implementation defined checks @code{Alignment_Check},
+@code{Duplicated_Tag_Check}, @code{Predicate_Check}, @code{Container_Checks}, @code{Tampering_Check},
+and @code{Validity_Check}, as well as any checks introduced using @code{pragma Check_Name}.
+Note that @code{Atomic_Synchronization} is not automatically suppressed by use of this option.
If the code depends on certain checks being active, you can use
-pragma @cite{Unsuppress} either as a configuration pragma or as
+pragma @code{Unsuppress} either as a configuration pragma or as
a local pragma to make sure that a specified check is performed
-even if @emph{gnatp} is specified.
+even if @code{gnatp} is specified.
-The @emph{-gnatp} switch has no effect if a subsequent
-@emph{-gnat-p} switch appears.
+The @code{-gnatp} switch has no effect if a subsequent
+@code{-gnat-p} switch appears.
@end table
@geindex -gnat-p (gcc)
@item @code{-gnat-p}
-This switch cancels the effect of a previous @emph{gnatp} switch.
+This switch cancels the effect of a previous @code{gnatp} switch.
@end table
@geindex -gnato?? (gcc)
In MINIMIZED mode, overflows in intermediate operations are avoided
where possible by using a larger integer type for the computation
-(typically @cite{Long_Long_Integer}). Overflow checking ensures that
+(typically @code{Long_Long_Integer}). Overflow checking ensures that
the result fits in this larger integer type.
@item @emph{3 = ELIMINATED}
has no effect on intermediate operations (since overflow is impossible).
@end table
-If two digits are present after @emph{-gnato} then the first digit
+If two digits are present after @code{-gnato} then the first digit
sets the mode for expressions outside assertions, and the second digit
sets the mode for expressions within assertions. Here assertions is used
in the technical sense (which includes for example precondition and
If no digits are present, the default is to enable overflow checks
and set STRICT mode for both kinds of expressions. This is compatible
-with the use of @emph{-gnato} in previous versions of GNAT.
+with the use of @code{-gnato} in previous versions of GNAT.
@geindex Machine_Overflows
-Note that the @emph{-gnato??} switch does not affect the code generated
+Note that the @code{-gnato??} switch does not affect the code generated
for any floating-point operations; it applies only to integer semantics.
-For floating-point, GNAT has the @cite{Machine_Overflows}
-attribute set to @cite{False} and the normal mode of operation is to
+For floating-point, GNAT has the @code{Machine_Overflows}
+attribute set to @code{False} and the normal mode of operation is to
generate IEEE NaN and infinite values on overflow or invalid operations
(such as dividing 0.0 by 0.0).
checking is also quite expensive in time and space, since in general it
requires the use of double length arithmetic.
-Note again that the default is @emph{-gnato11} (equivalent to @emph{-gnato1}),
+Note again that the default is @code{-gnato11} (equivalent to @code{-gnato1}),
so overflow checking is performed in STRICT mode by default.
@end table
Enables dynamic checks for access-before-elaboration
on subprogram calls and generic instantiations.
-Note that @emph{-gnatE} is not necessary for safety, because in the
+Note that @code{-gnatE} is not necessary for safety, because in the
default mode, GNAT ensures statically that the checks would not fail.
For full details of the effect and use of this switch,
@ref{1c,,Compiling with gcc}.
@geindex Unsuppress
The setting of these switches only controls the default setting of the
-checks. You may modify them using either @cite{Suppress} (to remove
-checks) or @cite{Unsuppress} (to add back suppressed checks) pragmas in
+checks. You may modify them using either @code{Suppress} (to remove
+checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in
the program source.
@node Using gcc for Syntax Checking,Using gcc for Semantic Checking,Run-Time Checks,Compiler Switches
@anchor{gnat_ugn/building_executable_programs_with_gnat id20}@anchor{105}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{106}
-@subsection Using @emph{gcc} for Syntax Checking
+@subsection Using @code{gcc} for Syntax Checking
@geindex -gnats (gcc)
@item @code{-gnats}
-The @cite{s} stands for 'syntax'.
+The @code{s} stands for 'syntax'.
Run GNAT in syntax checking only mode. For
example, the command
compiles file @code{x.adb} in syntax-check-only mode. You can check a
series of files in a single command
, and can use wild cards to specify such a group of files.
-Note that you must specify the @emph{-c} (compile
-only) flag in addition to the @emph{-gnats} flag.
+Note that you must specify the @code{-c} (compile
+only) flag in addition to the @code{-gnats} flag.
-You may use other switches in conjunction with @emph{-gnats}. In
-particular, @emph{-gnatl} and @emph{-gnatv} are useful to control the
+You may use other switches in conjunction with @code{-gnats}. In
+particular, @code{-gnatl} and @code{-gnatv} are useful to control the
format of any generated error messages.
When the source file is empty or contains only empty lines and/or comments,
Otherwise, the output is simply the error messages, if any. No object file or
ALI file is generated by a syntax-only compilation. Also, no units other
-than the one specified are accessed. For example, if a unit @cite{X}
-@emph{with}s a unit @cite{Y}, compiling unit @cite{X} in syntax
+than the one specified are accessed. For example, if a unit @code{X}
+@emph{with}s a unit @code{Y}, compiling unit @code{X} in syntax
check only mode does not access the source file containing unit
-@cite{Y}.
+@code{Y}.
@geindex Multiple units
@geindex syntax checking
Normally, GNAT allows only a single unit in a source file. However, this
restriction does not apply in syntax-check-only mode, and it is possible
to check a file containing multiple compilation units concatenated
-together. This is primarily used by the @cite{gnatchop} utility
+together. This is primarily used by the @code{gnatchop} utility
(@ref{36,,Renaming Files with gnatchop}).
@end table
@node Using gcc for Semantic Checking,Compiling Different Versions of Ada,Using gcc for Syntax Checking,Compiler Switches
@anchor{gnat_ugn/building_executable_programs_with_gnat id21}@anchor{107}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{108}
-@subsection Using @emph{gcc} for Semantic Checking
+@subsection Using @code{gcc} for Semantic Checking
@geindex -gnatc (gcc)
@item @code{-gnatc}
-The @cite{c} stands for 'check'.
+The @code{c} stands for 'check'.
Causes the compiler to operate in semantic check mode,
with full checking for all illegalities specified in the
Ada Reference Manual, but without generation of any object code
Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
specifies that the program is to be compiled in Ada 83 mode. With
-@emph{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83
+@code{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83
semantics where this can be done easily.
It is not possible to guarantee this switch does a perfect
job; some subtle tests, such as are
where, due to contractual reasons, existing code needs to be maintained
using only Ada 83 features.
-With few exceptions (most notably the need to use @cite{<>} on
+With few exceptions (most notably the need to use @code{<>} on
unconstrained
@geindex Generic formal parameters
generic formal parameters,
the use of the new Ada 95 / Ada 2005
reserved words, and the use of packages
with optional bodies), it is not necessary to specify the
-@emph{-gnat83} switch when compiling Ada 83 programs, because, with rare
+@code{-gnat83} switch when compiling Ada 83 programs, because, with rare
exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
a correct Ada 83 program is usually also a correct program
in these later versions of the language standard. For further information
-please refer to the @cite{Compatibility_and_Porting_Guide} chapter in the
+please refer to the @emph{Compatibility and Porting Guide} chapter in the
@cite{GNAT Reference Manual}.
@end table
language.
Since Ada 95 is almost completely upwards
compatible with Ada 83, Ada 83 programs may generally be compiled using
-this switch (see the description of the @emph{-gnat83} switch for further
+this switch (see the description of the @code{-gnat83} switch for further
information about Ada 83 mode).
If an Ada 2005 program is compiled in Ada 95 mode,
uses of the new Ada 2005 features will cause error
messages or warnings.
This switch also can be used to cancel the effect of a previous
-@emph{-gnat83}, @emph{-gnat05/2005}, or @emph{-gnat12/2012}
+@code{-gnat83}, @code{-gnat05/2005}, or @code{-gnat12/2012}
switch earlier in the command line.
@end table
Since Ada 2005 is almost completely upwards
compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
may generally be compiled using this switch (see the description of the
-@emph{-gnat83} and @emph{-gnat95} switches for further
+@code{-gnat83} and @code{-gnat95} switches for further
information).
@end table
compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
Ada 83 and Ada 95 programs
may generally be compiled using this switch (see the description of the
-@emph{-gnat83}, @emph{-gnat95}, and @emph{-gnat05/2005} switches
+@code{-gnat83}, @code{-gnat95}, and @code{-gnat05/2005} switches
for further information).
@end table
Normally GNAT recognizes the Latin-1 character set in source program
identifiers, as described in the Ada Reference Manual.
This switch causes
-GNAT to recognize alternate character sets in identifiers. @cite{c} is a
+GNAT to recognize alternate character sets in identifiers. @code{c} is a
single character indicating the character set, as follows:
@item @code{-gnatW@emph{e}}
Specify the method of encoding for wide characters.
-@cite{e} is one of the following:
+@code{e} is one of the following:
@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
For full details on these encoding
methods see @ref{4e,,Wide_Character Encodings}.
Note that brackets coding is always accepted, even if one of the other
-options is specified, so for example @emph{-gnatW8} specifies that both
+options is specified, so for example @code{-gnatW8} specifies that both
brackets and UTF-8 encodings will be recognized. The units that are
with'ed directly or indirectly will be scanned using the specified
representation scheme, and so if one of the non-brackets scheme is
brackets are considered to be normal graphic characters, and bracket sequences
are never recognized as wide characters.
-If no @emph{-gnatW?} parameter is present, then the default
+If no @code{-gnatW?} parameter is present, then the default
representation is normally Brackets encoding only. However, if the
first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
byte order mark or BOM for UTF-8), then these three characters are
parameter.
@end table
-When no @emph{-gnatW?} is specified, then characters (other than wide
+When no @code{-gnatW?} is specified, then characters (other than wide
characters represented using brackets notation) are treated as 8-bit
Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
and ASCII format effectors (CR, LF, HT, VT). Other lower half control
@item @code{-gnatk@emph{n}}
-Activates file name 'krunching'. @cite{n}, a decimal integer in the range
+Activates file name 'krunching'. @code{n}, a decimal integer in the range
1-999, indicates the maximum allowable length of a file name (not
including the @code{.ads} or @code{.adb} extension). The default is not
to enable file name krunching.
@item @code{-gnatn[12]}
-The @cite{n} here is intended to suggest the first syllable of the word 'inline'.
-GNAT recognizes and processes @cite{Inline} pragmas. However, for inlining to
+The @code{n} here is intended to suggest the first syllable of the word 'inline'.
+GNAT recognizes and processes @code{Inline} pragmas. However, for inlining to
actually occur, optimization must be enabled and, by default, inlining of
subprograms across modules is not performed. If you want to additionally
-enable inlining of subprograms specified by pragma @cite{Inline} across modules,
+enable inlining of subprograms specified by pragma @code{Inline} across modules,
you must also specify this switch.
In the absence of this switch, GNAT does not attempt inlining across modules
-and does not access the bodies of subprograms for which @cite{pragma Inline} is
+and does not access the bodies of subprograms for which @code{pragma Inline} is
specified if they are not in the current unit.
You can optionally specify the inlining level: 1 for moderate inlining across
modules, which is a good compromise between compilation times and performances
at run time, or 2 for full inlining across modules, which may bring about
longer compilation times. If no inlining level is specified, the compiler will
-pick it based on the optimization level: 1 for @emph{-O1}, @emph{-O2} or
-@emph{-Os} and 2 for @emph{-O3}.
+pick it based on the optimization level: 1 for @code{-O1}, @code{-O2} or
+@code{-Os} and 2 for @code{-O3}.
If you specify this switch the compiler will access these bodies,
creating an extra source dependency for the resulting object file, and
When using a gcc-based back end (in practice this means using any version
of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
-@emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred.
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
@end table
Typically
these tools do the necessary compilations automatically, so you should
not have to specify this switch in normal operation.
-Note that the combination of switches @emph{-gnatct}
+Note that the combination of switches @code{-gnatct}
generates a tree in the form required by ASIS applications.
@end table
@item @code{-pass-exit-codes}
-If this switch is not used, the exit code returned by @emph{gcc} when
+If this switch is not used, the exit code returned by @code{gcc} when
compiling multiple files indicates whether all source files have
been successfully used to generate object files or not.
-When @emph{-pass-exit-codes} is used, @emph{gcc} exits with an extended
+When @code{-pass-exit-codes} is used, @code{gcc} exits with an extended
exit status and allows an integrated development environment to better
react to a compilation failure. Those exit status are:
@item @code{-gnatd@emph{x}}
-Activate internal debugging switches. @cite{x} is a letter or digit, or
+Activate internal debugging switches. @code{x} is a letter or digit, or
string of letters or digits, which specifies the type of debugging
outputs desired. Normally these are used only for internal development
or system debugging purposes. You can find full documentation for these
-switches in the body of the @cite{Debug} unit in the compiler source
+switches in the body of the @code{Debug} unit in the compiler source
file @code{debug.adb}.
@end table
This is very useful in understanding the implications of various Ada
usage on the efficiency of the generated code. There are many cases in
Ada (e.g., the use of controlled types), where simple Ada statements can
-generate a lot of run-time code. By using @emph{-gnatG} you can identify
+generate a lot of run-time code. By using @code{-gnatG} you can identify
these cases, and consider whether it may be desirable to modify the coding
approach to improve efficiency.
-The optional parameter @cite{nn} if present after -gnatG specifies an
+The optional parameter @code{nn} if present after -gnatG specifies an
alternative maximum line length that overrides the normal default of 72.
This value is in the range 40-999999, values less than 40 being silently
reset to 40. The equal sign is optional.
additions correspond to low level features used in the generated code that
do not have any exact analogies in pure Ada source form. The following
is a partial list of these special constructions. See the spec
-of package @cite{Sprint} in file @code{sprint.ads} for a full list.
+of package @code{Sprint} in file @code{sprint.ads} for a full list.
@geindex -gnatL (gcc)
-If the switch @emph{-gnatL} is used in conjunction with
-@emph{-gnatG}, then the original source lines are interspersed
+If the switch @code{-gnatL} is used in conjunction with
+@code{-gnatG}, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
@item @code{(if @emph{expr} then @emph{expr} else @emph{expr})}
-Conditional expression equivalent to the @cite{x?y:z} construction in C.
+Conditional expression equivalent to the @code{x?y:z} construction in C.
@item @code{@emph{target}^(@emph{source})}
@item @code{free @emph{expr} [storage_pool = @emph{xxx}]}
-Shows the storage pool associated with a @cite{free} statement.
+Shows the storage pool associated with a @code{free} statement.
@item @code{[subtype or type declaration]}
@item @code{freeze @emph{type-name} [@emph{actions}]}
-Shows the point at which @cite{type-name} is frozen, with possible
+Shows the point at which @code{type-name} is frozen, with possible
associated actions to be performed at the freeze point.
@item @code{reference @emph{itype}}
-Reference (and hence definition) to internal type @cite{itype}.
+Reference (and hence definition) to internal type @code{itype}.
@item @code{@emph{function-name}! (@emph{arg}, @emph{arg}, @emph{arg})}
@item @code{@emph{label-name} : label}
-Declaration of label @cite{labelname}.
+Declaration of label @code{labelname}.
@item @code{#$ @emph{subprogram-name}}
@item @code{@emph{expr} && @emph{expr} && @emph{expr} ... && @emph{expr}}
-A multiple concatenation (same effect as @cite{expr} & @cite{expr} &
-@cite{expr}, but handled more efficiently).
+A multiple concatenation (same effect as @code{expr} & @code{expr} &
+@code{expr}, but handled more efficiently).
@item @code{[constraint_error]}
-Raise the @cite{Constraint_Error} exception.
+Raise the @code{Constraint_Error} exception.
@item @code{@emph{expression}'reference}
@item @code{@emph{target-type}!(@emph{source-expression})}
-An unchecked conversion of @cite{source-expression} to @cite{target-type}.
+An unchecked conversion of @code{source-expression} to @code{target-type}.
@item @code{[@emph{numerator}/@emph{denominator}]}
@item @code{-gnatD[=nn]}
-When used in conjunction with @emph{-gnatG}, this switch causes
+When used in conjunction with @code{-gnatG}, this switch causes
the expanded source, as described above for
-@emph{-gnatG} to be written to files with names
+@code{-gnatG} to be written to files with names
@code{xxx.dg}, where @code{xxx} is the normal file name,
instead of to the standard output file. For
example, if the source file name is @code{hello.adb}, then a file
@code{hello.adb.dg} will be written. The debugging
-information generated by the @emph{gcc} @emph{-g} switch
+information generated by the @code{gcc} @code{-g} switch
will refer to the generated @code{xxx.dg} file. This allows
you to do source level debugging using the generated code which is
sometimes useful for complex code, for example to find out exactly
which part of a complex construction raised an exception. This switch
also suppresses generation of cross-reference information (see
-@emph{-gnatx}) since otherwise the cross-reference information
+@code{-gnatx}) since otherwise the cross-reference information
would refer to the @code{.dg} file, which would cause
confusion since this is not the original source file.
-Note that @emph{-gnatD} actually implies @emph{-gnatG}
+Note that @code{-gnatD} actually implies @code{-gnatG}
automatically, so it is not necessary to give both options.
-In other words @emph{-gnatD} is equivalent to @emph{-gnatDG}).
+In other words @code{-gnatD} is equivalent to @code{-gnatDG}).
@geindex -gnatL (gcc)
-If the switch @emph{-gnatL} is used in conjunction with
-@emph{-gnatDG}, then the original source lines are interspersed
+If the switch @code{-gnatL} is used in conjunction with
+@code{-gnatDG}, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
-The optional parameter @cite{nn} if present after -gnatD specifies an
+The optional parameter @code{nn} if present after -gnatD specifies an
alternative maximum line length that overrides the normal default of 72.
This value is in the range 40-999999, values less than 40 being silently
reset to 40. The equal sign is optional.
@table @asis
-@item @code{-gnatR[0|1|2|3[s]]}
+@item @code{-gnatR[0|1|2|3][e][m][s]}
This switch controls output from the compiler of a listing showing
-representation information for declared types and objects. For
-@emph{-gnatR0}, no information is output (equivalent to omitting
-the @emph{-gnatR} switch). For @emph{-gnatR1} (which is the default,
-so @emph{-gnatR} with no parameter has the same effect), size and alignment
-information is listed for declared array and record types. For
-@emph{-gnatR2}, size and alignment information is listed for all
-declared types and objects. The @cite{Linker_Section} is also listed for any
-entity for which the @cite{Linker_Section} is set explicitly or implicitly (the
-latter case occurs for objects of a type for which a @cite{Linker_Section}
+representation information for declared types, objects and subprograms.
+For @code{-gnatR0}, no information is output (equivalent to omitting
+the @code{-gnatR} switch). For @code{-gnatR1} (which is the default,
+so @code{-gnatR} with no parameter has the same effect), size and
+alignment information is listed for declared array and record types.
+For @code{-gnatR2}, size and alignment information is listed for all
+declared types and objects. The @code{Linker_Section} is also listed for any
+entity for which the @code{Linker_Section} is set explicitly or implicitly (the
+latter case occurs for objects of a type for which a @code{Linker_Section}
is set).
-Finally @emph{-gnatR3} includes symbolic
-expressions for values that are computed at run time for
-variant records. These symbolic expressions have a mostly obvious
-format with #n being used to represent the value of the n'th
-discriminant. See source files @code{repinfo.ads/adb} in the
-@cite{GNAT} sources for full details on the format of @emph{-gnatR3}
-output. If the switch is followed by an s (e.g., @emph{-gnatR2s}), then
-the output is to a file with the name @code{file.rep} where
-file is the name of the corresponding source file.
+For @code{-gnatR3}, symbolic expressions for values that are computed
+at run time for records are included. These symbolic expressions have
+a mostly obvious format with #n being used to represent the value of the
+n'th discriminant. See source files @code{repinfo.ads/adb} in the
+GNAT sources for full details on the format of @code{-gnatR3} output.
-@item @code{-gnatRm[s]}
+If the switch is followed by an @code{e} (e.g. @code{-gnatR2e}), then
+extended representation information for record sub-components of records
+are included.
-This form of the switch controls output of subprogram conventions
-and parameter passing mechanisms for all subprograms. A following
-@cite{s} means output to a file as described above.
+If the switch is followed by an @code{m} (e.g. @code{-gnatRm}), then
+subprogram conventions and parameter passing mechanisms for all the
+subprograms are included.
+
+If the switch is followed by an @code{s} (e.g., @code{-gnatR3s}), then
+the output is to a file with the name @code{file.rep} where file is
+the name of the corresponding source file.
Note that it is possible for record components to have zero size. In
this case, the component clause uses an obvious extension of permitted
-Ada syntax, for example @cite{at 0 range 0 .. -1}.
+Ada syntax, for example @code{at 0 range 0 .. -1}.
@end table
@geindex -gnatS (gcc)
@item @code{-gnatS}
-The use of the switch @emph{-gnatS} for an
+The use of the switch @code{-gnatS} for an
Ada compilation will cause the compiler to output a
representation of package Standard in a form very
close to standard Ada. It is not quite possible to
Normally the compiler generates full cross-referencing information in
the @code{ALI} file. This information is used by a number of tools,
-including @cite{gnatfind} and @cite{gnatxref}. The @emph{-gnatx} switch
+including @code{gnatfind} and @code{gnatxref}. The @code{-gnatx} switch
suppresses this information. This saves some space and may slightly
speed up compilation, but means that these tools cannot be used.
@end table
GNAT uses two methods for handling exceptions at run-time. The
-@cite{setjmp/longjmp} method saves the context when entering
+@code{setjmp/longjmp} method saves the context when entering
a frame with an exception handler. Then when an exception is
raised, the context can be restored immediately, without the
need for tracing stack frames. This method provides very fast
exception handlers if no exception is raised. Note that in this
mode and in the context of mixed Ada and C/C++ programming,
to propagate an exception through a C/C++ code, the C/C++ code
-must be compiled with the @emph{-funwind-tables} GCC's
+must be compiled with the @code{-funwind-tables} GCC's
option.
The following switches may be used to control which of the
is available for the target in use, otherwise it will generate an error.
@end table
-The same option @emph{--RTS} must be used both for @emph{gcc}
-and @emph{gnatbind}. Passing this option to @emph{gnatmake}
+The same option @code{--RTS} must be used both for @code{gcc}
+and @code{gnatbind}. Passing this option to @code{gnatmake}
(@ref{dc,,Switches for gnatmake}) will ensure the required consistency
through the compilation and binding steps.
compiler, but mapping files can improve efficiency, particularly when
sources are read over a slow network connection. In normal operation,
you need not be concerned with the format or use of mapping files,
-and the @emph{-gnatem} switch is not a switch that you would use
+and the @code{-gnatem} switch is not a switch that you would use
explicitly. It is intended primarily for use by automatic tools such as
-@emph{gnatmake} running under the project file facility. The
+@code{gnatmake} running under the project file facility. The
description here of the format of mapping files is provided
for completeness and for possible use by other tools.
A mapping file is a sequence of sets of three lines. In each set, the
-first line is the unit name, in lower case, with @cite{%s} appended
-for specs and @cite{%b} appended for bodies; the second line is the
+first line is the unit name, in lower case, with @code{%s} appended
+for specs and @code{%b} appended for bodies; the second line is the
file name; and the third line is the path name.
Example:
/gnat/project1/sources/main.2.ada
@end example
-When the switch @emph{-gnatem} is specified, the compiler will
+When the switch @code{-gnatem} is specified, the compiler will
create in memory the two mappings from the specified file. If there is
any problem (nonexistent file, truncated file or duplicate entries),
no mapping will be created.
-Several @emph{-gnatem} switches may be specified; however, only the
+Several @code{-gnatem} switches may be specified; however, only the
last one on the command line will be taken into account.
-When using a project file, @emph{gnatmake} creates a temporary
+When using a project file, @code{gnatmake} creates a temporary
mapping file and communicates it to the compiler using this switch.
@end table
architectures. This includes variations in instruction sets (e.g.,
different members of the power pc family), and different requirements
for optimal arrangement of instructions (e.g., different members of
-the x86 family). The list of available @emph{-m} switches may be
+the x86 family). The list of available @code{-m} switches may be
found in the GCC documentation.
-Use of these @emph{-m} switches may in some cases result in improved
+Use of these @code{-m} switches may in some cases result in improved
code performance.
The GNAT technology is tested and qualified without any
successfully with GNAT, and many customers have reported successful
use of these options.
-Our general advice is to avoid the use of @emph{-m} switches unless
+Our general advice is to avoid the use of @code{-m} switches unless
special needs lead to requirements in this area. In particular,
-there is no point in using @emph{-m} switches to improve performance
+there is no point in using @code{-m} switches to improve performance
unless you actually see a performance improvement.
@node Linker Switches,Binding with gnatbind,Compiler Switches,Building Executable Programs with GNAT
@node Binding with gnatbind,Linking with gnatlink,Linker Switches,Building Executable Programs with GNAT
@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-gnatbind}@anchor{1d}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{11b}
-@section Binding with @cite{gnatbind}
+@section Binding with @code{gnatbind}
@geindex gnatbind
-This chapter describes the GNAT binder, @cite{gnatbind}, which is used
+This chapter describes the GNAT binder, @code{gnatbind}, which is used
to bind compiled GNAT objects.
-Note: to invoke @cite{gnatbind} with a project file, use the @cite{gnat}
-driver (see The_GNAT_Driver_and_Project_Files).
-
-The @cite{gnatbind} program performs four separate functions:
+The @code{gnatbind} program performs four separate functions:
@itemize *
This program is a small Ada package (body and spec) that
must be subsequently compiled
using the GNAT compiler. The necessary compilation step is usually
-performed automatically by @emph{gnatlink}. The two most important
+performed automatically by @code{gnatlink}. The two most important
functions of this program
are to call the elaboration routines of units in an appropriate order
and to call the main program.
@item
Determines the set of object files required by the given main program.
This information is output in the forms of comments in the generated program,
-to be read by the @emph{gnatlink} utility used to link the Ada application.
+to be read by the @code{gnatlink} utility used to link the Ada application.
@end itemize
@menu
@node Running gnatbind,Switches for gnatbind,,Binding with gnatbind
@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{11c}@anchor{gnat_ugn/building_executable_programs_with_gnat id33}@anchor{11d}
-@subsection Running @cite{gnatbind}
+@subsection Running @code{gnatbind}
-The form of the @cite{gnatbind} command is
+The form of the @code{gnatbind} command is
@example
-$ gnatbind [`switches`] `mainprog`[.ali] [`switches`]
+$ gnatbind [ switches ] mainprog[.ali] [ switches ]
@end example
where @code{mainprog.adb} is the Ada file containing the main program
-unit body. @cite{gnatbind} constructs an Ada
+unit body. @code{gnatbind} constructs an Ada
package in two files whose names are
@code{b~mainprog.ads}, and @code{b~mainprog.adb}.
For example, if given the
When doing consistency checking, the binder takes into consideration
any source files it can locate. For example, if the binder determines
-that the given main program requires the package @cite{Pack}, whose
+that the given main program requires the package @code{Pack}, whose
@code{.ALI}
file is @code{pack.ali} and whose corresponding source spec file is
@code{pack.ads}, it attempts to locate the source file @code{pack.ads}
(using the same search path conventions as previously described for the
-@emph{gcc} command). If it can locate this source file, it checks that
+@code{gcc} command). If it can locate this source file, it checks that
the time stamps
or source checksums of the source and its references to in @code{ALI} files
match. In other words, any @code{ALI} files that mentions this spec must have
error messages to be generated by the binder.
For example, suppose you have a main program @code{hello.adb} and a
-package @cite{P}, from file @code{p.ads} and you perform the following
+package @code{P}, from file @code{p.ads} and you perform the following
steps:
@itemize *
@item
-Enter @cite{gcc -c hello.adb} to compile the main program.
+Enter @code{gcc -c hello.adb} to compile the main program.
@item
-Enter @cite{gcc -c p.ads} to compile package @cite{P}.
+Enter @code{gcc -c p.ads} to compile package @code{P}.
@item
Edit file @code{p.ads}.
@item
-Enter @cite{gnatbind hello}.
+Enter @code{gnatbind hello}.
@end itemize
At this point, the file @code{p.ali} contains an out-of-date time stamp
with the contents of this file, but for reference purposes a sample
binder output file is given in @ref{e,,Example of Binder Output File}.
-In most normal usage, the default mode of @emph{gnatbind} which is to
+In most normal usage, the default mode of @code{gnatbind} which is to
generate the main package in Ada, as described in the previous section.
In particular, this means that any Ada programmer can read and understand
the generated main program. It can also be debugged just like any other
-Ada code provided the @emph{-g} switch is used for
-@emph{gnatbind} and @emph{gnatlink}.
+Ada code provided the @code{-g} switch is used for
+@code{gnatbind} and @code{gnatlink}.
@node Switches for gnatbind,Command-Line Access,Running gnatbind,Binding with gnatbind
@anchor{gnat_ugn/building_executable_programs_with_gnat id34}@anchor{11e}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{11f}
-@subsection Switches for @emph{gnatbind}
+@subsection Switches for @code{gnatbind}
-The following switches are available with @cite{gnatbind}; details will
+The following switches are available with @code{gnatbind}; details will
be presented in subsequent sections.
@geindex --version (gnatbind)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-d@emph{nn}[k|m]}
This switch can be used to change the default task stack size value
-to a specified size @cite{nn}, which is expressed in bytes by default, or
-in kilobytes when suffixed with @cite{k} or in megabytes when suffixed
-with @cite{m}.
+to a specified size @code{nn}, which is expressed in bytes by default, or
+in kilobytes when suffixed with @code{k} or in megabytes when suffixed
+with @code{m}.
In the absence of a @code{[k|m]} suffix, this switch is equivalent,
in effect, to completing all task specs with
@item @code{-D@emph{nn}[k|m]}
This switch can be used to change the default secondary stack size value
-to a specified size @cite{nn}, which is expressed in bytes by default, or
-in kilobytes when suffixed with @cite{k} or in megabytes when suffixed
-with @cite{m}.
+to a specified size @code{nn}, which is expressed in bytes by default, or
+in kilobytes when suffixed with @code{k} or in megabytes when suffixed
+with @code{m}.
The secondary stack is used to deal with functions that return a variable
sized result, for example a function returning an unconstrained
The "a" is for "address"; tracebacks will contain hexadecimal addresses,
unless symbolic tracebacks are enabled.
-See also the packages @cite{GNAT.Traceback} and
-@cite{GNAT.Traceback.Symbolic} for more information.
-Note that on x86 ports, you must not use @emph{-fomit-frame-pointer}
-@emph{gcc} option.
+See also the packages @code{GNAT.Traceback} and
+@code{GNAT.Traceback.Symbolic} for more information.
+Note that on x86 ports, you must not use @code{-fomit-frame-pointer}
+@code{gcc} option.
@end table
@geindex -Es (gnatbind)
@item @code{-E}
-Currently the same as @cite{-Ea}.
+Currently the same as @code{-Ea}.
@end table
@geindex -f (gnatbind)
@item @code{-F}
-Force the checks of elaboration flags. @emph{gnatbind} does not normally
+Force the checks of elaboration flags. @code{gnatbind} does not normally
generate checks of elaboration flags for the main executable, except when
a Stand-Alone Library is used. However, there are cases when this cannot be
detected by gnatbind. An example is importing an interface of a Stand-Alone
@item @code{-H32}
-Use 32-bit allocations for @cite{__gnat_malloc} (and thus for access types).
+Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types).
For further details see @ref{120,,Dynamic Allocation Control}.
@geindex -H64 (gnatbind)
@item @code{-H64}
-Use 64-bit allocations for @cite{__gnat_malloc} (and thus for access types).
+Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types).
For further details see @ref{120,,Dynamic Allocation Control}.
@geindex -I (gnatbind)
@item @code{-I-}
-Do not look for sources in the current directory where @cite{gnatbind} was
+Do not look for sources in the current directory where @code{gnatbind} was
invoked, and do not look for ALI files in the directory containing the
-ALI file named in the @cite{gnatbind} command line.
+ALI file named in the @code{gnatbind} command line.
@geindex -l (gnatbind)
@item @code{-L@emph{xxx}}
-Bind the units for library building. In this case the adainit and
-adafinal procedures (@ref{b4,,Binding with Non-Ada Main Programs})
-are renamed to @cite{xxx`init and `xxx`final. Implies -n. (:ref:`GNAT_and_Libraries}, for more details.)
+Bind the units for library building. In this case the @code{adainit} and
+@code{adafinal} procedures (@ref{b4,,Binding with Non-Ada Main Programs})
+are renamed to @code{@emph{xxx}init} and
+@code{@emph{xxx}final}.
+Implies -n.
+(@ref{15,,GNAT and Libraries}, for more details.)
@geindex -M (gnatbind)
@item @code{-m@emph{n}}
-Limit number of detected errors or warnings to @cite{n}, where @cite{n} is
+Limit number of detected errors or warnings to @code{n}, where @code{n} is
in the range 1..999999. The default value if no switch is
given is 9999. If the number of warnings reaches this limit, then a
message is output and further warnings are suppressed, the bind
@item @code{--RTS=@emph{rts-path}}
Specifies the default location of the runtime library. Same meaning as the
-equivalent @emph{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
+equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
@geindex -o (gnatbind)
@item @code{-o @emph{file}}
-Name the output file @cite{file} (default is @code{b~`xxx}.adb`).
+Name the output file @code{file} (default is @code{b~`xxx}.adb`).
Note that if this option is used, then linking must be done manually,
gnatlink cannot be used.
@item @code{-Ra}
-Like @emph{-R} but the list includes run-time units.
+Like @code{-R} but the list includes run-time units.
@geindex -s (gnatbind)
Specifies the value to be used when detecting uninitialized scalar
objects with pragma Initialize_Scalars.
-The @cite{xxx} string specified with the switch is one of:
+The @code{xxx} string specified with the switch is one of:
@itemize *
(see body of package System.Scalar_Values for exact values).
@item
-@cite{xx} for hex value (two hex digits).
+@code{xx} for hex value (two hex digits).
The underlying scalar is set to a value consisting of repeated bytes, whose
value corresponds to the given value. For example if @code{BF} is given,
@geindex GNAT_INIT_SCALARS
-In addition, you can specify @emph{-Sev} to indicate that the value is
+In addition, you can specify @code{-Sev} to indicate that the value is
to be set at run time. In this case, the program will look for an environment
-variable of the form @code{GNAT_INIT_SCALARS=@emph{yy}}, where @cite{yy} is one
-of @emph{in/lo/hi/`xx*` with the same meanings as above.
+variable of the form @code{GNAT_INIT_SCALARS=@emph{yy}}, where @code{yy} is one
+of @code{in/lo/hi/@emph{xx}} with the same meanings as above.
If no environment variable is found, or if it does not have a valid value,
-then the default is *in} (invalid values).
+then the default is @code{in} (invalid values).
@end table
@geindex -static (gnatbind)
@item @code{-T@emph{n}}
-Set the time slice value to @cite{n} milliseconds. If the system supports
+Set the time slice value to @code{n} milliseconds. If the system supports
the specification of a specific time slice value, then the indicated value
is used. If the system does not support specific time slice values, but
does support some general notion of round-robin scheduling, then any
slicing, and in addition, indicates to the tasking run time that the
semantics should match as closely as possible the Annex D
requirements of the Ada RM, and in particular sets the default
-scheduling policy to @cite{FIFO_Within_Priorities}.
+scheduling policy to @code{FIFO_Within_Priorities}.
@geindex -u (gnatbind)
@item @code{-u@emph{n}}
-Enable dynamic stack usage, with @cite{n} results stored and displayed
+Enable dynamic stack usage, with @code{n} results stored and displayed
at program termination. A result is generated when a task
terminates. Results that can't be stored are displayed on the fly, at
task termination. This option is currently not supported on Itanium
@item @code{-V@emph{key}=@emph{value}}
-Store the given association of @cite{key} to @cite{value} in the bind environment.
+Store the given association of @code{key} to @code{value} in the bind environment.
Values stored this way can be retrieved at run time using
-@cite{GNAT.Bind_Environment}.
+@code{GNAT.Bind_Environment}.
@geindex -w (gnatbind)
@item @code{-w@emph{x}}
-Warning mode; @cite{x} = s/e for suppress/treat as error.
+Warning mode; @code{x} = s/e for suppress/treat as error.
@geindex -Wx (gnatbind)
@item @code{-y}
-Enable leap seconds support in @cite{Ada.Calendar} and its children.
+Enable leap seconds support in @code{Ada.Calendar} and its children.
@geindex -z (gnatbind)
No main subprogram.
@end table
-You may obtain this listing of switches by running @cite{gnatbind} with
+You may obtain this listing of switches by running @code{gnatbind} with
no arguments.
@menu
@subsubsection Consistency-Checking Modes
-As described earlier, by default @cite{gnatbind} checks
+As described earlier, by default @code{gnatbind} checks
that object files are consistent with one another and are consistent
with any source files it can locate. The following switches control binder
access to sources.
Normally the default wide character encoding method used for standard
[Wide_[Wide_]]Text_IO files is taken from the encoding specified for
the main source input (see description of switch
-@emph{-gnatWx} for the compiler). The
+@code{-gnatWx} for the compiler). The
use of this switch for the binder (which has the same set of
possible arguments) overrides this default as specified.
If a source file has been edited since it was last compiled, and you
specify this switch, the binder will not detect that the object
file is out of date with respect to the source file. Note that this is the
-mode that is automatically used by @emph{gnatmake} because in this
+mode that is automatically used by @code{gnatmake} because in this
case the checking against sources has already been performed by
-@emph{gnatmake} in the course of compilation (i.e., before binding).
+@code{gnatmake} in the course of compilation (i.e., before binding).
@end table
@node Binder Error Message Control,Elaboration Control,Consistency-Checking Modes,Switches for gnatbind
Generate brief error messages to @code{stderr} even if verbose mode is
specified. This is relevant only when used with the
-@emph{-v} switch.
+@code{-v} switch.
@geindex -m (gnatbind)
@item @code{-m@emph{n}}
-Limits the number of error messages to @cite{n}, a decimal integer in the
+Limits the number of error messages to @code{n}, a decimal integer in the
range 1-999. The binder terminates immediately if this limit is reached.
@geindex -M (gnatbind)
@item @code{-M@emph{xxx}}
-Renames the generated main program from @cite{main} to @cite{xxx}.
+Renames the generated main program from @code{main} to @code{xxx}.
This is useful in the case of some cross-building environments, where
the actual main program is separate from the one generated
-by @cite{gnatbind}.
+by @code{gnatbind}.
@geindex -ws (gnatbind)
Check that checksums of a given source unit are consistent
@item
-Check that consistent versions of @cite{GNAT} were used for compilation
+Check that consistent versions of @code{GNAT} were used for compilation
@item
Check consistency of configuration pragmas as required
generated which abort the binder and prevent the output of a binder
file and subsequent link to obtain an executable.
-The @emph{-t} switch converts these error messages
+The @code{-t} switch converts these error messages
into warnings, so that
binding and linking can continue to completion even in the presence of such
errors. The result may be a failed link (due to missing symbols), or a
@cartouche
@quotation Note
-This means that @emph{-t} should be used only in unusual situations,
+This means that @code{-t} should be used only in unusual situations,
with extreme care.
@end quotation
@end cartouche
Force elaboration order.
-@cite{elab-order} should be the name of a "forced elaboration order file", that
+@code{elab-order} should be the name of a "forced elaboration order file", that
is, a text file containing library item names, one per line. A name of the
form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
name of the form "some.unit%b" or "some.unit (body)" denotes the body of
dependences are already required by Ada rules, so this file is really just
forcing the body of This to be elaborated before the spec of That.
-The given order must be consistent with Ada rules, or else @cite{gnatbind} will
+The given order must be consistent with Ada rules, or else @code{gnatbind} will
give elaboration cycle errors. For example, if you say x (body) should be
elaborated before x (spec), there will be a cycle, because Ada rules require
x (spec) to be elaborated before x (body); you can't have the spec and body
Normally the binder attempts to choose an elaboration order that is
likely to minimize the likelihood of an elaboration order error resulting
-in raising a @cite{Program_Error} exception. This switch reverses the
+in raising a @code{Program_Error} exception. This switch reverses the
action of the binder, and requests that it deliberately choose an order
that is likely to maximize the likelihood of an elaboration error.
This is useful in ensuring portability and avoiding dependence on
accidental fortuitous elaboration ordering.
-Normally it only makes sense to use the @emph{-p}
+Normally it only makes sense to use the @code{-p}
switch if dynamic
-elaboration checking is used (@emph{-gnatE} switch used for compilation).
+elaboration checking is used (@code{-gnatE} switch used for compilation).
This is because in the default static elaboration mode, all necessary
-@cite{Elaborate} and @cite{Elaborate_All} pragmas are implicitly inserted.
+@code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted.
These implicit pragmas are still respected by the binder in
-@emph{-p} mode, so a
+@code{-p} mode, so a
safe elaboration order is assured.
-Note that @emph{-p} is not intended for
+Note that @code{-p} is not intended for
production use; it is more for debugging/experimental use.
@end table
Output linker options to @code{stdout}. Includes library search paths,
contents of pragmas Ident and Linker_Options, and libraries added
-by @cite{gnatbind}.
+by @code{gnatbind}.
@geindex -l (gnatbind)
@item @code{-o @emph{file}}
-Set name of output file to @cite{file} instead of the normal
-@code{b~`mainprog}.adb` default. Note that @cite{file} denote the Ada
+Set name of output file to @code{file} instead of the normal
+@code{b~`mainprog}.adb` default. Note that @code{file} denote the Ada
binder generated body filename.
Note that if this option is used, then linking must be done manually.
It is not possible to use gnatlink in this case, since it cannot locate
@item @code{-r}
-Generate list of @cite{pragma Restrictions} that could be applied to
+Generate list of @code{pragma Restrictions} that could be applied to
the current unit. This is useful for code audit purposes, and also may
be used to improve code generation in some cases.
@end table
@subsubsection Dynamic Allocation Control
-The heap control switches -- @emph{-H32} and @emph{-H64} --
+The heap control switches -- @code{-H32} and @code{-H64} --
determine whether dynamic allocation uses 32-bit or 64-bit memory.
-They only affect compiler-generated allocations via @cite{__gnat_malloc};
-explicit calls to @cite{malloc} and related functions from the C
+They only affect compiler-generated allocations via @code{__gnat_malloc};
+explicit calls to @code{malloc} and related functions from the C
run-time library are unaffected.
@item @code{-H64}
Allocate memory on 64-bit heap. This is the default
-unless explicitly overridden by a @cite{'Size} clause on the access type.
+unless explicitly overridden by a @code{'Size} clause on the access type.
@end table
These switches are only effective on VMS platforms.
The description so far has assumed that the main
program is in Ada, and that the task of the binder is to generate a
-corresponding function @cite{main} that invokes this Ada main
+corresponding function @code{main} that invokes this Ada main
program. GNAT also supports the building of executable programs where
the main program is not in Ada, but some of the called routines are
written in Ada and compiled using GNAT (@ref{44,,Mixed Language Programming}).
@table @asis
-@item @emph{adainit}
+@item @code{adainit}
You must call this routine to initialize the Ada part of the program by
-calling the necessary elaboration routines. A call to @cite{adainit} is
+calling the necessary elaboration routines. A call to @code{adainit} is
required before the first call to an Ada subprogram.
Note that it is assumed that the basic execution environment must be setup
@table @asis
-@item @emph{adafinal}
+@item @code{adafinal}
You must call this routine to perform any library-level finalization
-required by the Ada subprograms. A call to @cite{adafinal} is required
+required by the Ada subprograms. A call to @code{adafinal} is required
after the last call to an Ada subprogram, and before the program
terminates.
@end table
@geindex Binder
@geindex multiple input files
-If the @emph{-n} switch
+If the @code{-n} switch
is given, more than one ALI file may appear on
-the command line for @cite{gnatbind}. The normal @emph{closure}
+the command line for @code{gnatbind}. The normal @code{closure}
calculation is performed for each of the specified units. Calculating
the closure means finding out the set of units involved by tracing
@emph{with} references. The reason it is necessary to be able to
more quite separate groups of Ada units.
The binder takes the name of its output file from the last specified ALI
-file, unless overridden by the use of the @emph{-o file}.
+file, unless overridden by the use of the @code{-o file}.
@geindex -o (gnatbind)
The output is an Ada unit in source form that can be compiled with GNAT.
-This compilation occurs automatically as part of the @emph{gnatlink}
+This compilation occurs automatically as part of the @code{gnatlink}
processing.
Currently the GNAT run time requires a FPU using 80 bits mode
that the default wide character encoding method for standard Text_IO
files is always set to Brackets if this switch is set (you can use
the binder switch
-@emph{-Wx} to override this default).
+@code{-Wx} to override this default).
@end table
@node Command-Line Access,Search Paths for gnatbind,Switches for gnatbind,Binding with gnatbind
@subsection Command-Line Access
-The package @cite{Ada.Command_Line} provides access to the command-line
+The package @code{Ada.Command_Line} provides access to the command-line
arguments and program name. In order for this interface to operate
correctly, the two variables
@geindex gnat_argc
are declared in one of the GNAT library routines. These variables must
-be set from the actual @cite{argc} and @cite{argv} values passed to the
-main program. With no @emph{n} present, @cite{gnatbind}
+be set from the actual @code{argc} and @code{argv} values passed to the
+main program. With no @emph{n} present, @code{gnatbind}
generates the C main program to automatically set these variables.
If the @emph{n} switch is used, there is no automatic way to
set these variables. If they are not set, the procedures in
-@cite{Ada.Command_Line} will not be available, and any attempt to use
-them will raise @cite{Constraint_Error}. If command line access is
-required, your main program must set @cite{gnat_argc} and
-@cite{gnat_argv} from the @cite{argc} and @cite{argv} values passed to
+@code{Ada.Command_Line} will not be available, and any attempt to use
+them will raise @code{Constraint_Error}. If command line access is
+required, your main program must set @code{gnat_argc} and
+@code{gnat_argv} from the @code{argc} and @code{argv} values passed to
it.
@node Search Paths for gnatbind,Examples of gnatbind Usage,Command-Line Access,Binding with gnatbind
@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-for-gnatbind}@anchor{8c}@anchor{gnat_ugn/building_executable_programs_with_gnat id43}@anchor{130}
-@subsection Search Paths for @cite{gnatbind}
+@subsection Search Paths for @code{gnatbind}
The binder takes the name of an ALI file as its argument and needs to
locate source files as well as other ALI files to verify object consistency.
-For source files, it follows exactly the same search rules as @emph{gcc}
+For source files, it follows exactly the same search rules as @code{gcc}
(see @ref{89,,Search Paths and the Run-Time Library (RTL)}). For ALI files the
directories searched are:
@item
The directory containing the ALI file named in the command line, unless
-the switch @emph{-I-} is specified.
+the switch @code{-I-} is specified.
@item
-All directories specified by @emph{-I}
-switches on the @cite{gnatbind}
+All directories specified by @code{-I}
+switches on the @code{gnatbind}
command line, in the order given.
@geindex ADA_PRJ_OBJECTS_FILE
@item
The content of the @code{ada_object_path} file which is part of the GNAT
installation tree and is used to store standard libraries such as the
-GNAT Run Time Library (RTL) unless the switch @emph{-nostdlib} is
+GNAT Run Time Library (RTL) unless the switch @code{-nostdlib} is
specified. See @ref{87,,Installing a library}
@end itemize
@geindex -aO (gnatbind)
-In the binder the switch @emph{-I}
+In the binder the switch @code{-I}
is used to specify both source and
-library file paths. Use @emph{-aI}
+library file paths. Use @code{-aI}
instead if you want to specify
-source paths only, and @emph{-aO}
+source paths only, and @code{-aO}
if you want to specify library paths
only. This means that for the binder
@code{-I@emph{dir}} is equivalent to
@geindex GNAT
-The packages @cite{Ada}, @cite{System}, and @cite{Interfaces} and their
+The packages @code{Ada}, @code{System}, and @code{Interfaces} and their
children make up the GNAT Run-Time Library, together with the package
GNAT and its children, which contain a set of useful additional
library functions provided by GNAT. The sources for these units are
@node Examples of gnatbind Usage,,Search Paths for gnatbind,Binding with gnatbind
@anchor{gnat_ugn/building_executable_programs_with_gnat id44}@anchor{131}@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatbind-usage}@anchor{132}
-@subsection Examples of @cite{gnatbind} Usage
+@subsection Examples of @code{gnatbind} Usage
-Here are some examples of @cite{gnatbind} invovations:
+Here are some examples of @code{gnatbind} invovations:
@quotation
gnatbind hello
@end example
-The main program @cite{Hello} (source program in @code{hello.adb}) is
+The main program @code{Hello} (source program in @code{hello.adb}) is
bound using the standard switch settings. The generated main program is
@code{b~hello.adb}. This is the normal, default use of the binder.
gnatbind hello -o mainprog.adb
@end example
-The main program @cite{Hello} (source program in @code{hello.adb}) is
+The main program @code{Hello} (source program in @code{hello.adb}) is
bound using the standard switch settings. The generated main program is
@code{mainprog.adb} with the associated spec in
@code{mainprog.ads}. Note that you must specify the body here not the
@node Linking with gnatlink,Using the GNU make Utility,Binding with gnatbind,Building Executable Programs with GNAT
@anchor{gnat_ugn/building_executable_programs_with_gnat id45}@anchor{133}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{1e}
-@section Linking with @emph{gnatlink}
+@section Linking with @code{gnatlink}
@geindex gnatlink
-This chapter discusses @emph{gnatlink}, a tool that links
+This chapter discusses @code{gnatlink}, a tool that links
an Ada program and builds an executable file. This utility
-invokes the system linker (via the @emph{gcc} command)
+invokes the system linker (via the @code{gcc} command)
with a correct list of object files and library references.
-@emph{gnatlink} automatically determines the list of files and
+@code{gnatlink} automatically determines the list of files and
references for the Ada part of a program. It uses the binder file
-generated by the @emph{gnatbind} to determine this list.
+generated by the @code{gnatbind} to determine this list.
Note: to invoke @cite{gnatlink} with a project file, use the @cite{gnat}
driver (see The_GNAT_Driver_and_Project_Files).
@node Running gnatlink,Switches for gnatlink,,Linking with gnatlink
@anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{134}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{135}
-@subsection Running @emph{gnatlink}
+@subsection Running @code{gnatlink}
-The form of the @emph{gnatlink} command is
+The form of the @code{gnatlink} command is
@example
-$ gnatlink [`switches`] `mainprog`[.ali]
- [`non-Ada objects`] [`linker options`]
+$ gnatlink [ switches ] mainprog [.ali]
+ [ non-Ada objects ] [ linker options ]
@end example
-The arguments of @emph{gnatlink} (switches, main @code{ALI} file,
+The arguments of @code{gnatlink} (switches, main @code{ALI} file,
non-Ada objects
or linker options) may be in any order, provided that no non-Ada object may
be mistaken for a main @code{ALI} file.
@code{mainprog.ali} references the ALI file of the main program.
The @code{.ali} extension of this file can be omitted. From this
-reference, @emph{gnatlink} locates the corresponding binder file
+reference, @code{gnatlink} locates the corresponding binder file
@code{b~mainprog.adb} and, using the information in this file along
with the list of non-Ada objects and linker options, constructs a
linker command file to create the executable.
-The arguments other than the @emph{gnatlink} switches and the main
+The arguments other than the @code{gnatlink} switches and the main
@code{ALI} file are passed to the linker uninterpreted.
They typically include the names of
object files for units written in other languages than Ada and any library
references required to resolve references in any of these foreign language
-units, or in @cite{Import} pragmas in any Ada units.
+units, or in @code{Import} pragmas in any Ada units.
-@cite{linker options} is an optional list of linker specific
+@code{linker options} is an optional list of linker specific
switches.
-The default linker called by gnatlink is @emph{gcc} which in
+The default linker called by gnatlink is @code{gcc} which in
turn calls the appropriate system linker.
-One useful option for the linker is @emph{-s}: it reduces the size of the
+One useful option for the linker is @code{-s}: it reduces the size of the
executable by removing all symbol table and relocation information from the
executable.
-Standard options for the linker such as @emph{-lmy_lib} or
-@emph{-Ldir} can be added as is.
+Standard options for the linker such as @code{-lmy_lib} or
+@code{-Ldir} can be added as is.
For options that are not recognized by
-@emph{gcc} as linker options, use the @emph{gcc} switches
-@emph{-Xlinker} or @emph{-Wl,}.
+@code{gcc} as linker options, use the @code{gcc} switches
+@code{-Xlinker} or @code{-Wl,}.
Refer to the GCC documentation for
details.
$ gnatlink my_prog -Wl,-Map,MAPFILE
@end example
-Using @cite{linker options} it is possible to set the program stack and
+Using @code{linker options} it is possible to set the program stack and
heap size.
See @ref{136,,Setting Stack Size from gnatlink} and
@ref{137,,Setting Heap Size from gnatlink}.
-@emph{gnatlink} determines the list of objects required by the Ada
+@code{gnatlink} determines the list of objects required by the Ada
program and prepends them to the list of objects passed to the linker.
-@emph{gnatlink} also gathers any arguments set by the use of
-@cite{pragma Linker_Options} and adds them to the list of arguments
+@code{gnatlink} also gathers any arguments set by the use of
+@code{pragma Linker_Options} and adds them to the list of arguments
presented to the linker.
@node Switches for gnatlink,,Running gnatlink,Linking with gnatlink
@anchor{gnat_ugn/building_executable_programs_with_gnat id47}@anchor{138}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{139}
-@subsection Switches for @emph{gnatlink}
+@subsection Switches for @code{gnatlink}
-The following switches are available with the @emph{gnatlink} utility:
+The following switches are available with the @code{gnatlink} utility:
@geindex --version (gnatlink)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-f}
-On some targets, the command line length is limited, and @emph{gnatlink}
+On some targets, the command line length is limited, and @code{gnatlink}
will generate a separate file for the linker if the list of object files
is too long.
-The @emph{-f} switch forces this file
+The @code{-f} switch forces this file
to be generated even if
the limit is not exceeded. This is useful in some cases to deal with
special situations where the command line length is exceeded.
@item @code{-g}
The option to include debugging information causes the Ada bind file (in
-other words, @code{b~mainprog.adb}) to be compiled with @emph{-g}.
+other words, @code{b~mainprog.adb}) to be compiled with @code{-g}.
In addition, the binder does not delete the @code{b~mainprog.adb},
@code{b~mainprog.o} and @code{b~mainprog.ali} files.
-Without @emph{-g}, the binder removes these files by default.
+Without @code{-g}, the binder removes these files by default.
@end table
@geindex -n (gnatlink)
@item @code{-o @emph{exec-name}}
-@cite{exec-name} specifies an alternate name for the generated
+@code{exec-name} specifies an alternate name for the generated
executable program. If this switch is omitted, the executable has the same
-name as the main unit. For example, @cite{gnatlink try.ali} creates
+name as the main unit. For example, @code{gnatlink try.ali} creates
an executable called @code{try}.
@end table
@item @code{-b @emph{target}}
-Compile your program to run on @cite{target}, which is the name of a
+Compile your program to run on @code{target}, which is the name of a
system configuration. You must have a GNAT cross-compiler built if
-@cite{target} is not the same as your host system.
+@code{target} is not the same as your host system.
@end table
@geindex -B (gnatlink)
@item @code{-B@emph{dir}}
-Load compiler executables (for example, @cite{gnat1}, the Ada compiler)
-from @cite{dir} instead of the default location. Only use this switch
+Load compiler executables (for example, @code{gnat1}, the Ada compiler)
+from @code{dir} instead of the default location. Only use this switch
when multiple versions of the GNAT compiler are available.
-See the @cite{Directory Options} section in @cite{The_GNU_Compiler_Collection}
-for further details. You would normally use the @emph{-b} or
-@emph{-V} switch instead.
+See the @code{Directory Options} section in @cite{The_GNU_Compiler_Collection}
+for further details. You would normally use the @code{-b} or
+@code{-V} switch instead.
@end table
@geindex -M (gnatlink)
@item @code{-M=@emph{mapfile}}
When linking an executable, create a map file. The name of the map file is
-@cite{mapfile}.
+@code{mapfile}.
@end table
@geindex --GCC=compiler_name (gnatlink)
@item @code{--GCC=@emph{compiler_name}}
Program used for compiling the binder file. The default is
-@code{gcc}. You need to use quotes around @cite{compiler_name} if
-@cite{compiler_name} contains spaces or other separator characters.
-As an example @code{--GCC="foo -x -y"} will instruct @emph{gnatlink} to
+@code{gcc}. You need to use quotes around @code{compiler_name} if
+@code{compiler_name} contains spaces or other separator characters.
+As an example @code{--GCC="foo -x -y"} will instruct @code{gnatlink} to
use @code{foo -x -y} as your compiler. Note that switch @code{-c} is always
inserted after your command name. Thus in the above example the compiler
-command that will be used by @emph{gnatlink} will be @code{foo -c -x -y}.
+command that will be used by @code{gnatlink} will be @code{foo -c -x -y}.
A limitation of this syntax is that the name and path name of the executable
itself must not include any embedded spaces. If the compiler executable is
different from the default one (gcc or <prefix>-gcc), then the back-end
switches in the ALI file are not used to compile the binder generated source.
For example, this is the case with @code{--GCC="foo -x -y"}. But the back end
switches will be used for @code{--GCC="gcc -gnatv"}. If several
-@code{--GCC=compiler_name} are used, only the last @cite{compiler_name}
+@code{--GCC=compiler_name} are used, only the last @code{compiler_name}
is taken into account. However, all the additional switches are also taken
into account. Thus,
@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to
@item @code{--LINK=@emph{name}}
-@cite{name} is the name of the linker to be invoked. This is especially
+@code{name} is the name of the linker to be invoked. This is especially
useful in mixed language programs since languages such as C++ require
their own linker to be used. When this switch is omitted, the default
-name for the linker is @emph{gcc}. When this switch is used, the
-specified linker is called instead of @emph{gcc} with exactly the same
-parameters that would have been passed to @emph{gcc} so if the desired
+name for the linker is @code{gcc}. When this switch is used, the
+specified linker is called instead of @code{gcc} with exactly the same
+parameters that would have been passed to @code{gcc} so if the desired
linker requires different parameters it is necessary to use a wrapper
script that massages the parameters before invoking the real linker. It
may be useful to control the exact invocation by using the verbose
@node Using the GNU make Utility,,Linking with gnatlink,Building Executable Programs with GNAT
@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{1f}@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{13a}
-@section Using the GNU @cite{make} Utility
+@section Using the GNU @code{make} Utility
@geindex make (GNU)
This chapter offers some examples of makefiles that solve specific
problems. It does not explain how to write a makefile, nor does it try to replace the
-@emph{gnatmake} utility (@ref{1b,,Building with gnatmake}).
+@code{gnatmake} utility (@ref{1b,,Building with gnatmake}).
All the examples in this section are specific to the GNU version of
-make. Although @emph{make} is a standard utility, and the basic language
+make. Although @code{make} is a standard utility, and the basic language
is the same, these examples use some advanced features found only in
-@cite{GNU make}.
+@code{GNU make}.
@menu
* Using gnatmake in a Makefile::
each step of the build process.
The list of dependencies are handled automatically by
-@emph{gnatmake}. The Makefile is simply used to call gnatmake in each of
+@code{gnatmake}. The Makefile is simply used to call gnatmake in each of
the appropriate directories.
Note that you should also read the example on how to automatically
The example below presents two methods. The first one, although less
general, gives you more control over the list. It involves wildcard
-characters, that are automatically expanded by @emph{make}. Its
+characters, that are automatically expanded by @code{make}. Its
shortcoming is that you need to explicitly specify some of the
organization of your project, such as for instance the directory tree
depth, whether some directories are found in a separate tree, etc.
The second method is the most general one. It requires an external
-program, called @emph{find}, which is standard on all Unix systems. All
+program, called @code{find}, which is standard on all Unix systems. All
the directories found under a given root directory will be added to the
list.
# Note that the argument(s) to wildcard below should end with a '/'.
# Since wildcards also return file names, we have to filter them out
# to avoid duplicate directory names.
-# We thus use make's `dir` and `sort` functions.
+# We thus use make's `@w{`}dir`@w{`} and `@w{`}sort`@w{`} functions.
# It sets DIRs to the following value (note that the directories aaa and baa
# are not given, unless you change the arguments to wildcard).
# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
gnatmake the list of source and object directories.
This example shows how you can set up environment variables, which will
-make @emph{gnatmake} behave exactly as if the directories had been
+make @code{gnatmake} behave exactly as if the directories had been
specified on the command line, but have a much higher length limit (or
even none on most systems).
Note a small trick in the Makefile below: for efficiency reasons, we
create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
-expanded immediately by @cite{make}. This way we overcome the standard
+expanded immediately by @code{make}. This way we overcome the standard
make behavior which is to expand the variables only when they are
actually used.
@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs
@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{145}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{20}
-@section The File Cleanup Utility @emph{gnatclean}
+@section The File Cleanup Utility @code{gnatclean}
@geindex File cleanup tool
@geindex gnatclean
-@cite{gnatclean} is a tool that allows the deletion of files produced by the
+@code{gnatclean} is a tool that allows the deletion of files produced by the
compiler, binder and linker, including ALI files, object files, tree files,
expanded source files, library files, interface copy source files, binder
generated files and executable files.
@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean
@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{146}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{147}
-@subsection Running @cite{gnatclean}
+@subsection Running @code{gnatclean}
-The @cite{gnatclean} command has the form:
+The @code{gnatclean} command has the form:
@quotation
@example
-$ gnatclean switches `names`
+$ gnatclean switches names
@end example
@end quotation
-where @cite{names} is a list of source file names. Suffixes @code{.ads} and
+where @code{names} is a list of source file names. Suffixes @code{.ads} and
@code{adb} may be omitted. If a project file is specified using switch
-@code{-P}, then @cite{names} may be completely omitted.
+@code{-P}, then @code{names} may be completely omitted.
-In normal mode, @cite{gnatclean} delete the files produced by the compiler and,
-if switch @cite{-c} is not specified, by the binder and
+In normal mode, @code{gnatclean} delete the files produced by the compiler and,
+if switch @code{-c} is not specified, by the binder and
the linker. In informative-only mode, specified by switch
-@cite{-n}, the list of files that would have been deleted in
+@code{-n}, the list of files that would have been deleted in
normal mode is listed, but no file is actually deleted.
@node Switches for gnatclean,,Running gnatclean,The File Cleanup Utility gnatclean
@anchor{gnat_ugn/gnat_utility_programs id4}@anchor{148}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{149}
-@subsection Switches for @cite{gnatclean}
+@subsection Switches for @code{gnatclean}
-@cite{gnatclean} recognizes the following switches:
+@code{gnatclean} recognizes the following switches:
@geindex --version (gnatclean)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@item @code{--subdirs=@emph{subdir}}
@item @code{-D @emph{dir}}
-Indicate that ALI and object files should normally be found in directory @cite{dir}.
+Indicate that ALI and object files should normally be found in directory @code{dir}.
@end table
@geindex -F (gnatclean)
@item @code{-h}
-Output a message explaining the usage of @cite{gnatclean}.
+Output a message explaining the usage of @code{gnatclean}.
@end table
@geindex -n (gnatclean)
@item @code{-P@emph{project}}
-Use project file @cite{project}. Only one such switch can be used.
+Use project file @code{project}. Only one such switch can be used.
When cleaning a project file, the files produced by the compilation of the
immediate sources or inherited sources of the project files are to be
deleted. This is not depending on the presence or not of executable names
@item @code{-X@emph{name}=@emph{value}}
-Indicates that external variable @cite{name} has the value @cite{value}.
+Indicates that external variable @code{name} has the value @code{value}.
The Project Manager will use this value for occurrences of
-@cite{external(name)} when parsing the project file.
-@ref{de,,Switches Related to Project Files}.
+@code{external(name)} when parsing the project file.
+See @ref{de,,Switches Related to Project Files}.
@end table
@geindex -aO (gnatclean)
@item @code{-aO@emph{dir}}
-When searching for ALI and object files, look in directory @cite{dir}.
+When searching for ALI and object files, look in directory @code{dir}.
@end table
@geindex -I (gnatclean)
@item @code{-I-}
Do not look for ALI or object files in the directory
-where @cite{gnatclean} was invoked.
+where @code{gnatclean} was invoked.
@end table
@node The GNAT Library Browser gnatls,The Cross-Referencing Tools gnatxref and gnatfind,The File Cleanup Utility gnatclean,GNAT Utility Programs
@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{21}@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{14a}
-@section The GNAT Library Browser @cite{gnatls}
+@section The GNAT Library Browser @code{gnatls}
@geindex Library browser
@geindex gnatls
-@cite{gnatls} is a tool that outputs information about compiled
+@code{gnatls} is a tool that outputs information about compiled
units. It gives the relationship between objects, unit names and source
files. It can also be used to check the source dependencies of a unit
as well as various characteristics.
@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls
@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{14b}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{14c}
-@subsection Running @cite{gnatls}
+@subsection Running @code{gnatls}
-The @cite{gnatls} command has the form
+The @code{gnatls} command has the form
@quotation
@example
-$ gnatls switches `object_or_ali_file`
+$ gnatls switches object_or_ali_file
@end example
@end quotation
(see @ref{42,,The Ada Library Information Files})
for which information is requested.
-In normal mode, without additional option, @cite{gnatls} produces a
+In normal mode, without additional option, @code{gnatls} produces a
four-column listing. Each line represents information for a specific
object. The first column gives the full path of the object, the second
column gives the name of the principal unit in this object, the third
The version of the source file used for the compilation of the
specified unit differs from the actual source file but not enough to
-require recompilation. If you use gnatmake with the qualifier
-@emph{-m (minimal recompilation)}, a file marked
+require recompilation. If you use gnatmake with the option
+@code{-m} (minimal recompilation), a file marked
MOK will not be recompiled.
@item @emph{DIF (modified)}
@node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls
@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{14d}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{14e}
-@subsection Switches for @cite{gnatls}
+@subsection Switches for @code{gnatls}
-@cite{gnatls} recognizes the following switches:
+@code{gnatls} recognizes the following switches:
@geindex --version (gnatls)
@table @asis
-@item @code{*--help}
+@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-a}
Consider all units, including those of the predefined Ada library.
-Especially useful with @emph{-d}.
+Especially useful with @code{-d}.
@end table
@geindex -d (gnatls)
@item @code{-files=@emph{file}}
-Take as arguments the files listed in text file @cite{file}.
-Text file @cite{file} may contain empty lines that are ignored.
+Take as arguments the files listed in text file @code{file}.
+Text file @code{file} may contain empty lines that are ignored.
Each nonempty line should contain the name of an existing file.
Several such switches may be specified simultaneously.
@end table
@item @code{-aO@emph{dir}}, @code{-aI@emph{dir}}, @code{-I@emph{dir}}, @code{-I-}, @code{-nostdinc}
-Source path manipulation. Same meaning as the equivalent @emph{gnatmake}
+Source path manipulation. Same meaning as the equivalent @code{gnatmake}
flags (@ref{dc,,Switches for gnatmake}).
@end table
@item @code{-aP@emph{dir}}
-Add @cite{dir} at the beginning of the project search dir.
+Add @code{dir} at the beginning of the project search dir.
@end table
@geindex --RTS (gnatls)
@item @code{--RTS=@emph{rts-path}`}
Specifies the default location of the runtime library. Same meaning as the
-equivalent @emph{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
+equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
@end table
@geindex -v (gnatls)
@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls
@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{14f}@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{150}
-@subsection Example of @cite{gnatls} Usage
+@subsection Example of @code{gnatls} Usage
Example of using the verbose switch. Note how the source and
@node The Cross-Referencing Tools gnatxref and gnatfind,The Ada to HTML Converter gnathtml,The GNAT Library Browser gnatls,GNAT Utility Programs
@anchor{gnat_ugn/gnat_utility_programs the-cross-referencing-tools-gnatxref-and-gnatfind}@anchor{22}@anchor{gnat_ugn/gnat_utility_programs id9}@anchor{151}
-@section The Cross-Referencing Tools @cite{gnatxref} and @cite{gnatfind}
+@section The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind}
@geindex gnatxref
application, so that GNAT gets a chance to generate the cross-referencing
information.
-The two tools @cite{gnatxref} and @cite{gnatfind} take advantage of this
+The two tools @code{gnatxref} and @code{gnatfind} take advantage of this
information to provide the user with the capability to easily locate the
declaration and references to an entity. These tools are quite similar,
-the difference being that @cite{gnatfind} is intended for locating
+the difference being that @code{gnatfind} is intended for locating
definitions and/or references to a specified entity or entities, whereas
-@cite{gnatxref} is oriented to generating a full report of all
+@code{gnatxref} is oriented to generating a full report of all
cross-references.
To use these tools, you must not compile your application using the
-@emph{-gnatx} switch on the @emph{gnatmake} command line
+@code{-gnatx} switch on the @code{gnatmake} command line
(see @ref{1b,,Building with gnatmake}). Otherwise, cross-referencing
information will not be generated.
@node gnatxref Switches,gnatfind Switches,,The Cross-Referencing Tools gnatxref and gnatfind
@anchor{gnat_ugn/gnat_utility_programs id10}@anchor{152}@anchor{gnat_ugn/gnat_utility_programs gnatxref-switches}@anchor{153}
-@subsection @cite{gnatxref} Switches
+@subsection @code{gnatxref} Switches
-The command invocation for @cite{gnatxref} is:
+The command invocation for @code{gnatxref} is:
@quotation
@example
-$ gnatxref [`switches`] `sourcefile1` [`sourcefile2` ...]
+$ gnatxref [ switches ] sourcefile1 [ sourcefile2 ... ]
@end example
@end quotation
@table @asis
-@item @emph{sourcefile1} [, @emph{sourcefile2} ...]
+@item @code{sourcefile1} [, @code{sourcefile2} ...]
identify the source files for which a report is to be generated. The
-'with'ed units will be processed too. You must provide at least one file.
+@code{with}ed units will be processed too. You must provide at least one file.
These file names are considered to be regular expressions, so for instance
specifying @code{source*.adb} is the same as giving every file in the current
directory whose name starts with @code{source} and whose extension is
@code{adb}.
-You shouldn't specify any directory name, just base names. @emph{gnatxref}
-and @emph{gnatfind} will be able to locate these files by themselves using
+You shouldn't specify any directory name, just base names. @code{gnatxref}
+and @code{gnatfind} will be able to locate these files by themselves using
the source path. If you specify directories, no result is produced.
@end table
-The following switches are available for @emph{gnatxref}:
+The following switches are available for @code{gnatxref}:
@geindex --version (gnatxref)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-a}
-If this switch is present, @cite{gnatfind} and @cite{gnatxref} will parse
+If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
the read-only files found in the library search path. Otherwise, these files
will be ignored. This option can be used to protect Gnat sources or your own
-libraries from being parsed, thus making @cite{gnatfind} and @cite{gnatxref}
+libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
much faster, and their output much smaller. Read-only here refers to access
or permissions status in the file system for the current user.
@end table
@item @code{-aI@emph{DIR}}
When looking for source files also look in directory DIR. The order in which
-source file search is undertaken is the same as for @emph{gnatmake}.
+source file search is undertaken is the same as for @code{gnatmake}.
@end table
@geindex -aODIR (gnatxref)
When -searching for library and object files, look in directory
DIR. The order in which library files are searched is the same as for
-@emph{gnatmake}.
+@code{gnatmake}.
@end table
@geindex -nostdinc (gnatxref)
@item @code{--ext=@emph{extension}}
-Specify an alternate ali file extension. The default is @cite{ali} and other
-extensions (e.g. @cite{gli} for C/C++ sources when using @emph{-fdump-xref})
+Specify an alternate ali file extension. The default is @code{ali} and other
+extensions (e.g. @code{gli} for C/C++ sources when using @code{-fdump-xref})
may be specified via this switch. Note that if this switch overrides the
default, which means that only the new extension will be considered.
@end table
@item @code{--RTS=@emph{rts-path}}
Specifies the default location of the runtime library. Same meaning as the
-equivalent @emph{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
+equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
@end table
@geindex -d (gnatxref)
@item @code{-d}
-If this switch is set @cite{gnatxref} will output the parent type
+If this switch is set @code{gnatxref} will output the parent type
reference for each matching derived types.
@end table
If this switch is set, information is output only for library-level
entities, ignoring local entities. The use of this switch may accelerate
-@cite{gnatfind} and @cite{gnatxref}.
+@code{gnatfind} and @code{gnatxref}.
@end table
@geindex -IDIR (gnatxref)
@item @code{-u}
Output only unused symbols. This may be really useful if you give your
-main compilation unit on the command line, as @cite{gnatxref} will then
+main compilation unit on the command line, as @code{gnatxref} will then
display every unused entity and 'with'ed package.
@item @code{-v}
-Instead of producing the default output, @cite{gnatxref} will generate a
+Instead of producing the default output, @code{gnatxref} will generate a
@code{tags} file that can be used by vi. For examples how to use this
feature, see @ref{155,,Examples of gnatxref Usage}. The tags file is output
to the standard output, thus you will have to redirect it to a file.
@node gnatfind Switches,Configuration Files for gnatxref and gnatfind,gnatxref Switches,The Cross-Referencing Tools gnatxref and gnatfind
@anchor{gnat_ugn/gnat_utility_programs id11}@anchor{156}@anchor{gnat_ugn/gnat_utility_programs gnatfind-switches}@anchor{157}
-@subsection @cite{gnatfind} Switches
+@subsection @code{gnatfind} Switches
-The command invocation for @cite{gnatfind} is:
+The command invocation for @code{gnatfind} is:
@quotation
@example
-$ gnatfind [`switches`] `pattern`[:`sourcefile`[:`line`[:`column`]]]
- [`file1` `file2` ...]
+$ gnatfind [ switches ] pattern[:sourcefile[:line[:column]]]
+ [file1 file2 ...]
@end example
@end quotation
@item @emph{pattern}
An entity will be output only if it matches the regular expression found
-in @cite{pattern}, see @ref{158,,Regular Expressions in gnatfind and gnatxref}.
+in @emph{pattern}, see @ref{158,,Regular Expressions in gnatfind and gnatxref}.
Omitting the pattern is equivalent to specifying @code{*}, which
will match any entity. Note that if you do not provide a pattern, you
@item @emph{sourcefile}
-@cite{gnatfind} will look for references, bodies or declarations
-of symbols referenced in @code{sourcefile}, at line @cite{line}
-and column @cite{column}. See @ref{159,,Examples of gnatfind Usage}
+@code{gnatfind} will look for references, bodies or declarations
+of symbols referenced in @code{sourcefile}, at line @code{line}
+and column @code{column}. See @ref{159,,Examples of gnatfind Usage}
for syntax examples.
@item @emph{line}
occurrences of the entity in the separate units of the ones given on the
command line will also be displayed.
-Note that if you specify at least one file in this part, @cite{gnatfind} may
+Note that if you specify at least one file in this part, @code{gnatfind} may
sometimes not be able to find the body of the subprograms.
@end table
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-a}
-If this switch is present, @cite{gnatfind} and @cite{gnatxref} will parse
+If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
the read-only files found in the library search path. Otherwise, these files
will be ignored. This option can be used to protect Gnat sources or your own
-libraries from being parsed, thus making @cite{gnatfind} and @cite{gnatxref}
+libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
much faster, and their output much smaller. Read-only here refers to access
or permission status in the file system for the current user.
@end table
@item @code{-aI@emph{DIR}}
When looking for source files also look in directory DIR. The order in which
-source file search is undertaken is the same as for @emph{gnatmake}.
+source file search is undertaken is the same as for @code{gnatmake}.
@end table
@geindex -aODIR (gnatfind)
When searching for library and object files, look in directory
DIR. The order in which library files are searched is the same as for
-@emph{gnatmake}.
+@code{gnatmake}.
@end table
@geindex -nostdinc (gnatfind)
@item @code{--ext=@emph{extension}}
-Specify an alternate ali file extension. The default is @cite{ali} and other
-extensions (e.g. @cite{gli} for C/C++ sources when using @emph{-fdump-xref})
+Specify an alternate ali file extension. The default is @code{ali} and other
+extensions (e.g. @code{gli} for C/C++ sources when using @code{-fdump-xref})
may be specified via this switch. Note that if this switch overrides the
default, which means that only the new extension will be considered.
@end table
@item @code{--RTS=@emph{rts-path}}
Specifies the default location of the runtime library. Same meaning as the
-equivalent @emph{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
+equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
@end table
@geindex -d (gnatfind)
@item @code{-d}
-If this switch is set, then @cite{gnatfind} will output the parent type
+If this switch is set, then @code{gnatfind} will output the parent type
reference for each matching derived types.
@end table
@item @code{-e}
-By default, @cite{gnatfind} accept the simple regular expression set for
-@cite{pattern}. If this switch is set, then the pattern will be
+By default, @code{gnatfind} accept the simple regular expression set for
+@code{pattern}. If this switch is set, then the pattern will be
considered as full Unix-style regular expression.
@end table
If this switch is set, information is output only for library-level
entities, ignoring local entities. The use of this switch may accelerate
-@cite{gnatfind} and @cite{gnatxref}.
+@code{gnatfind} and @code{gnatxref}.
@end table
@geindex -IDIR (gnatfind)
@item @code{-r}
-By default, @cite{gnatfind} will output only the information about the
+By default, @code{gnatfind} will output only the information about the
declaration, body or type completion of the entities. If this switch is
-set, the @cite{gnatfind} will locate every reference to the entities in
+set, the @code{gnatfind} will locate every reference to the entities in
the files specified on the command line (or in every file in the search
path if no file is given on the command line).
@end table
@item @code{-s}
-If this switch is set, then @cite{gnatfind} will output the content
+If this switch is set, then @code{gnatfind} will output the content
of the Ada source file lines were the entity was found.
@end table
@item @code{-t}
-If this switch is set, then @cite{gnatfind} will output the type hierarchy for
+If this switch is set, then @code{gnatfind} will output the type hierarchy for
the specified type. It act like -d option but recursively from parent
type to parent type. When this switch is set it is not possible to
specify more than one file.
you can say @code{gnatxref -ag} instead of
@code{gnatxref -a -g}.
-As stated previously, gnatfind will search in every directory in the
+As stated previously, @code{gnatfind} will search in every directory in the
search path. You can force it to look only in the current directory if
-you specify @cite{*} at the end of the command line.
+you specify @code{*} at the end of the command line.
@node Configuration Files for gnatxref and gnatfind,Regular Expressions in gnatfind and gnatxref,gnatfind Switches,The Cross-Referencing Tools gnatxref and gnatfind
@anchor{gnat_ugn/gnat_utility_programs configuration-files-for-gnatxref-and-gnatfind}@anchor{154}@anchor{gnat_ugn/gnat_utility_programs id12}@anchor{15a}
-@subsection Configuration Files for @emph{gnatxref} and @emph{gnatfind}
+@subsection Configuration Files for @code{gnatxref} and @code{gnatfind}
-Configuration files are used by @cite{gnatxref} and @cite{gnatfind} to specify
+Configuration files are used by @code{gnatxref} and @code{gnatfind} to specify
the list of source and object directories to consider. They can be
specified via the @code{-p} switch.
@item @emph{src_dir=DIR}
-[default: @cite{"./"}].
-Specifies a directory where to look for source files. Multiple @cite{src_dir}
+[default: @code{"./"}].
+Specifies a directory where to look for source files. Multiple @code{src_dir}
lines can be specified and they will be searched in the order they
are specified.
@end table
@item @emph{obj_dir=DIR}
-[default: @cite{"./"}].
+[default: @code{"./"}].
Specifies a directory where to look for object and library files. Multiple
-@cite{obj_dir} lines can be specified, and they will be searched in the order
+@code{obj_dir} lines can be specified, and they will be searched in the order
they are specified
@end table
@end itemize
@node Regular Expressions in gnatfind and gnatxref,Examples of gnatxref Usage,Configuration Files for gnatxref and gnatfind,The Cross-Referencing Tools gnatxref and gnatfind
@anchor{gnat_ugn/gnat_utility_programs id13}@anchor{15b}@anchor{gnat_ugn/gnat_utility_programs regular-expressions-in-gnatfind-and-gnatxref}@anchor{158}
-@subsection Regular Expressions in @cite{gnatfind} and @cite{gnatxref}
+@subsection Regular Expressions in @code{gnatfind} and @code{gnatxref}
-As specified in the section about @emph{gnatfind}, the pattern can be a
+As specified in the section about @code{gnatfind}, the pattern can be a
regular expression. Two kinds of regular expressions
are recognized:
@node Examples of gnatxref Usage,Examples of gnatfind Usage,Regular Expressions in gnatfind and gnatxref,The Cross-Referencing Tools gnatxref and gnatfind
@anchor{gnat_ugn/gnat_utility_programs examples-of-gnatxref-usage}@anchor{155}@anchor{gnat_ugn/gnat_utility_programs id14}@anchor{15c}
-@subsection Examples of @cite{gnatxref} Usage
+@subsection Examples of @code{gnatxref} Usage
@menu
@item
@code{gnatxref main.adb}
-@cite{gnatxref} generates cross-reference information for main.adb
+@code{gnatxref} generates cross-reference information for main.adb
and every unit 'with'ed by main.adb.
The output would be:
@end example
@end quotation
-This shows that the entity @cite{Main} is declared in main.ads, line 2, column 9,
+This shows that the entity @code{Main} is declared in main.ads, line 2, column 9,
its body is in main.adb, line 1, column 14 and is not referenced any where.
-The entity @cite{Print} is declared in bar.ads, line 2, column 15 and it
-is referenced in main.adb, line 6 column 12 and line 7 column 12.
+The entity @code{Print} is declared in @code{bar.ads}, line 2, column 15 and it
+is referenced in @code{main.adb}, line 6 column 12 and line 7 column 12.
@item
@code{gnatxref package1.adb package2.ads}
-@cite{gnatxref} will generates cross-reference information for
-package1.adb, package2.ads and any other package 'with'ed by any
+@code{gnatxref} will generates cross-reference information for
+@code{package1.adb}, @code{package2.ads} and any other package @code{with}ed by any
of these.
@end itemize
@end quotation
@node Using gnatxref with vi,,General Usage,Examples of gnatxref Usage
@anchor{gnat_ugn/gnat_utility_programs using-gnatxref-with-vi}@anchor{15e}
-@subsubsection Using gnatxref with vi
+@subsubsection Using @code{gnatxref} with @code{vi}
-@cite{gnatxref} can generate a tags file output, which can be used
-directly from @emph{vi}. Note that the standard version of @emph{vi}
+@code{gnatxref} can generate a tags file output, which can be used
+directly from @code{vi}. Note that the standard version of @code{vi}
will not work properly with overloaded symbols. Consider using another
-free implementation of @emph{vi}, such as @emph{vim}.
+free implementation of @code{vi}, such as @code{vim}.
@quotation
@end example
@end quotation
-The following command will generate the tags file for @cite{gnatfind} itself
+The following command will generate the tags file for @code{gnatfind} itself
(if the sources are in the search path!):
@quotation
@end example
@end quotation
-From @emph{vi}, you can then use the command @code{:tag @emph{entity}}
-(replacing @cite{entity} by whatever you are looking for), and vi will
+From @code{vi}, you can then use the command @code{:tag @emph{entity}}
+(replacing @code{entity} by whatever you are looking for), and vi will
display a new file with the corresponding declaration of entity.
@node Examples of gnatfind Usage,,Examples of gnatxref Usage,The Cross-Referencing Tools gnatxref and gnatfind
@anchor{gnat_ugn/gnat_utility_programs id15}@anchor{15f}@anchor{gnat_ugn/gnat_utility_programs examples-of-gnatfind-usage}@anchor{159}
-@subsection Examples of @cite{gnatfind} Usage
+@subsection Examples of @code{gnatfind} Usage
@item
@code{gnatfind -fs xyz:main.adb}
-This is the same command as the previous one, but @cite{gnatfind} will
+This is the same command as the previous one, but @code{gnatfind} will
display the content of the Ada source file lines.
The output will look like:
@node The Ada to HTML Converter gnathtml,,The Cross-Referencing Tools gnatxref and gnatfind,GNAT Utility Programs
@anchor{gnat_ugn/gnat_utility_programs the-ada-to-html-converter-gnathtml}@anchor{23}@anchor{gnat_ugn/gnat_utility_programs id16}@anchor{160}
-@section The Ada to HTML Converter @cite{gnathtml}
+@section The Ada to HTML Converter @code{gnathtml}
@geindex gnathtml
-@emph{gnathtml} is a Perl script that allows Ada source files to be browsed using
+@code{gnathtml} is a Perl script that allows Ada source files to be browsed using
standard Web browsers. For installation information, see @ref{161,,Installing gnathtml}.
Ada reserved keywords are highlighted in a bold font and Ada comments in
-a blue font. Unless your program was compiled with the gcc @emph{-gnatx}
+a blue font. Unless your program was compiled with the gcc @code{-gnatx}
switch to suppress the generation of cross-referencing information, user
defined variables and types will appear in a different color; you will
be able to click on any identifier and go to its declaration.
@node Invoking gnathtml,Installing gnathtml,,The Ada to HTML Converter gnathtml
@anchor{gnat_ugn/gnat_utility_programs invoking-gnathtml}@anchor{162}@anchor{gnat_ugn/gnat_utility_programs id17}@anchor{163}
-@subsection Invoking @emph{gnathtml}
+@subsection Invoking @code{gnathtml}
The command line is as follows:
@quotation
@example
-$ perl gnathtml.pl [`switches`] `ada-files`
+$ perl gnathtml.pl [ switches ] ada-files
@end example
@end quotation
-You can specify as many Ada files as you want. @cite{gnathtml} will generate
+You can specify as many Ada files as you want. @code{gnathtml} will generate
an html file for every ada file, and a global file called @code{index.htm}.
This file is an index of every identifier defined in the files.
@item @code{d}
If the Ada files depend on some other files (for instance through
-@cite{with} clauses, the latter files will also be converted to html.
+@code{with} clauses, the latter files will also be converted to html.
Only the files in the user project will be converted to html, not the files
in the run-time library itself.
@end table
@item @code{D}
-This command is the same as @emph{-d} above, but @emph{gnathtml} will
+This command is the same as @code{-d} above, but @code{gnathtml} will
also look for files in the run-time library, and generate html files for them.
@end table
By default, gnathtml will generate html links only for global entities
('with'ed units, global variables and types,...). If you specify
-@emph{-f} on the command line, then links will be generated for local
+@code{-f} on the command line, then links will be generated for local
entities too.
@end table
@item @code{l @emph{number}}
-If this switch is provided and @cite{number} is not 0, then
-@cite{gnathtml} will number the html files every @cite{number} line.
+If this switch is provided and @code{number} is not 0, then
+@code{gnathtml} will number the html files every @code{number} line.
@end table
@geindex -I (gnathtml)
@node Installing gnathtml,,Invoking gnathtml,The Ada to HTML Converter gnathtml
@anchor{gnat_ugn/gnat_utility_programs installing-gnathtml}@anchor{161}@anchor{gnat_ugn/gnat_utility_programs id18}@anchor{164}
-@subsection Installing @cite{gnathtml}
+@subsection Installing @code{gnathtml}
-@cite{Perl} needs to be installed on your machine to run this script.
-@cite{Perl} is freely available for almost every architecture and
+@code{Perl} needs to be installed on your machine to run this script.
+@code{Perl} is freely available for almost every architecture and
operating system via the Internet.
On Unix systems, you may want to modify the first line of the script
-@cite{gnathtml}, to explicitly specify where Perl
+@code{gnathtml}, to explicitly specify where Perl
is located. The syntax of this line is:
@quotation
@quotation
@example
-$ perl gnathtml.pl [`switches`] `files`
+$ perl gnathtml.pl [ switches ] files
@end example
@end quotation
* Naming Conventions for GNAT Source Files::
* Getting Internal Debugging Information::
* Stack Traceback::
+* Pretty-Printers for the GNAT runtime::
@end menu
@subsection The GNAT Debugger GDB
-@cite{GDB} is a general purpose, platform-independent debugger that
-can be used to debug mixed-language programs compiled with @emph{gcc},
+@code{GDB} is a general purpose, platform-independent debugger that
+can be used to debug mixed-language programs compiled with @code{gcc},
and in particular is capable of debugging Ada programs compiled with
-GNAT. The latest versions of @cite{GDB} are Ada-aware and can handle
+GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
complex Ada data structures.
See @cite{Debugging with GDB},
-for full details on the usage of @cite{GDB}, including a section on
+for full details on the usage of @code{GDB}, including a section on
its usage on programs. This manual should be consulted for full
details. The section that follows is a brief introduction to the
-philosophy and use of @cite{GDB}.
+philosophy and use of @code{GDB}.
When GNAT programs are compiled, the compiler optionally writes debugging
information into the generated object file, including information on
larger, but it does not add to the size of the actual executable that
will be loaded into memory, and has no impact on run-time performance. The
generation of debug information is triggered by the use of the
--g switch in the @emph{gcc} or @emph{gnatmake} command
+@code{-g} switch in the @code{gcc} or @code{gnatmake} command
used to carry out the compilations. It is important to emphasize that
the use of these options does not change the generated code.
standard C formats. Details of this encoding scheme may be found in
the file exp_dbug.ads in the GNAT source distribution. However, the
details of this encoding are, in general, of no interest to a user,
-since @cite{GDB} automatically performs the necessary decoding.
+since @code{GDB} automatically performs the necessary decoding.
When a program is bound and linked, the debugging information is
collected from the object files, and stored in the executable image of
the normal manner, it runs exactly as if the debug information were
not present, and takes no more actual memory.
-However, if the program is run under control of @cite{GDB}, the
+However, if the program is run under control of @code{GDB}, the
debugger is activated. The image of the program is loaded, at which
point it is ready to run. If a run command is given, then the program
-will run exactly as it would have if @cite{GDB} were not present. This
-is a crucial part of the @cite{GDB} design philosophy. @cite{GDB} is
+will run exactly as it would have if @code{GDB} were not present. This
+is a crucial part of the @code{GDB} design philosophy. @code{GDB} is
entirely non-intrusive until a breakpoint is encountered. If no
breakpoint is ever hit, the program will run exactly as it would if no
-debugger were present. When a breakpoint is hit, @cite{GDB} accesses
+debugger were present. When a breakpoint is hit, @code{GDB} accesses
the debugging information and can respond to user commands to inspect
variables, and more generally to report on the state of execution.
This section describes how to initiate the debugger.
-The debugger can be launched from a @cite{GPS} menu or
+The debugger can be launched from a @code{GPS} menu or
directly from the command line. The description below covers the latter use.
-All the commands shown can be used in the @cite{GPS} debug console window,
+All the commands shown can be used in the @code{GPS} debug console window,
but there are usually more GUI-based ways to achieve the same effect.
-The command to run @cite{GDB} is
+The command to run @code{GDB} is
@quotation
@end example
@end quotation
-where @cite{program} is the name of the executable file. This
+where @code{program} is the name of the executable file. This
activates the debugger and results in a prompt for debugger commands.
-The simplest command is simply @cite{run}, which causes the program to run
+The simplest command is simply @code{run}, which causes the program to run
exactly as if the debugger were not present. The following section
-describes some of the additional commands that can be given to @cite{GDB}.
+describes some of the additional commands that can be given to @code{GDB}.
@node Introduction to GDB Commands,Using Ada Expressions,Running GDB,Running and Debugging Ada Programs
@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{172}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{173}
@subsection Introduction to GDB Commands
-@cite{GDB} contains a large repertoire of commands.
+@code{GDB} contains a large repertoire of commands.
See @cite{Debugging with GDB} for extensive documentation on the use
of these commands, together with examples of their use. Furthermore,
the command @emph{help} invoked from within GDB activates a simple help
facility which summarizes the available commands and their options.
In this section we summarize a few of the most commonly
-used commands to give an idea of what @cite{GDB} is about. You should create
+used commands to give an idea of what @code{GDB} is about. You should create
a simple program with debugging information and experiment with the use of
-these @cite{GDB} commands on the program as you read through the
+these @code{GDB} commands on the program as you read through the
following section.
@table @asis
-@item @emph{set args `arguments`}
+@item @code{set args @emph{arguments}}
-The @cite{arguments} list above is a list of arguments to be passed to
+The @emph{arguments} list above is a list of arguments to be passed to
the program on a subsequent run command, just as though the arguments
-had been entered on a normal invocation of the program. The @cite{set args}
+had been entered on a normal invocation of the program. The @code{set args}
command is not needed if the program does not require arguments.
@end table
@table @asis
-@item @emph{run}
+@item @code{run}
-The @cite{run} command causes execution of the program to start from
+The @code{run} command causes execution of the program to start from
the beginning. If the program is already running, that is to say if
you are currently positioned at a breakpoint, then a prompt will ask
for confirmation that you want to abandon the current execution and
@table @asis
-@item @emph{breakpoint `location`}
+@item @code{breakpoint @emph{location}}
The breakpoint command sets a breakpoint, that is to say a point at which
-execution will halt and @cite{GDB} will await further
-commands. @cite{location} is
-either a line number within a file, given in the format @cite{file:linenumber},
+execution will halt and @code{GDB} will await further
+commands. @emph{location} is
+either a line number within a file, given in the format @code{file:linenumber},
or it is the name of a subprogram. If you request that a breakpoint be set on
a subprogram that is overloaded, a prompt will ask you to specify on which of
those subprograms you want to breakpoint. You can also
specify that all of them should be breakpointed. If the program is run
and execution encounters the breakpoint, then the program
-stops and @cite{GDB} signals that the breakpoint was encountered by
+stops and @code{GDB} signals that the breakpoint was encountered by
printing the line of code before which the program is halted.
@end table
@table @asis
-@item @emph{catch exception `name`}
+@item @code{catch exception @emph{name}}
This command causes the program execution to stop whenever exception
-@cite{name} is raised. If @cite{name} is omitted, then the execution is
+@code{name} is raised. If @code{name} is omitted, then the execution is
suspended when any exception is raised.
@end table
@table @asis
-@item @emph{print `expression`}
+@item @code{print @emph{expression}}
This will print the value of the given expression. Most simple
-Ada expression formats are properly handled by @cite{GDB}, so the expression
+Ada expression formats are properly handled by @code{GDB}, so the expression
can contain function calls, variables, operators, and attribute references.
@end table
@table @asis
-@item @emph{continue}
+@item @code{continue}
Continues execution following a breakpoint, until the next breakpoint or the
termination of the program.
@table @asis
-@item @emph{step}
+@item @code{step}
Executes a single line after a breakpoint. If the next statement
is a subprogram call, execution continues into (the first statement of)
@table @asis
-@item @emph{next}
+@item @code{next}
Executes a single line. If this line is a subprogram call, executes and
returns from the call.
@table @asis
-@item @emph{list}
+@item @code{list}
Lists a few lines around the current source location. In practice, it
is usually more convenient to have a separate edit window open with the
@table @asis
-@item @emph{backtrace}
+@item @code{backtrace}
Displays a backtrace of the call chain. This command is typically
used after a breakpoint has occurred, to examine the sequence of calls that
@table @asis
-@item @emph{up}
+@item @code{up}
-At a breakpoint, @cite{GDB} can display the values of variables local
-to the current frame. The command @cite{up} can be used to
+At a breakpoint, @code{GDB} can display the values of variables local
+to the current frame. The command @code{up} can be used to
examine the contents of other active frames, by moving the focus up
the stack, that is to say from callee to caller, one frame at a time.
@end table
@table @asis
-@item @emph{down}
+@item @code{down}
-Moves the focus of @cite{GDB} down from the frame currently being
+Moves the focus of @code{GDB} down from the frame currently being
examined to the frame of its callee (the reverse of the previous command),
@end table
@table @asis
-@item @emph{frame `n`}
+@item @code{frame @emph{n}}
Inspect the frame with the given number. The value 0 denotes the frame
of the current breakpoint, that is to say the top of the call stack.
@table @asis
-@item @emph{kill}
+@item @code{kill}
Kills the child process in which the program is running under GDB.
This may be useful for several purposes:
@end itemize
The above list is a very short introduction to the commands that
-@cite{GDB} provides. Important additional capabilities, including conditional
+@code{GDB} provides. Important additional capabilities, including conditional
breakpoints, the ability to execute command sequences on a breakpoint,
the ability to debug at the machine instruction level and many other
features are described in detail in @cite{Debugging with GDB}.
@geindex Ada expressions (in gdb)
-@cite{GDB} supports a fairly large subset of Ada expression syntax, with some
+@code{GDB} supports a fairly large subset of Ada expression syntax, with some
extensions. The philosophy behind the design of this subset is
@quotation
@itemize *
@item
-That @cite{GDB} should provide basic literals and access to operations for
+That @code{GDB} should provide basic literals and access to operations for
arithmetic, dereferencing, field selection, indexing, and subprogram calls,
leaving more sophisticated computations to subprograms written into the
-program (which therefore may be called from @cite{GDB}).
+program (which therefore may be called from @code{GDB}).
@item
That type safety and strict adherence to Ada language restrictions
are not particularly relevant in a debugging context.
@item
-That brevity is important to the @cite{GDB} user.
+That brevity is important to the @code{GDB} user.
@end itemize
@end quotation
Thus, for brevity, the debugger acts as if there were
-implicit @cite{with} and @cite{use} clauses in effect for all user-written
+implicit @code{with} and @code{use} clauses in effect for all user-written
packages, thus making it unnecessary to fully qualify most names with
their packages, regardless of context. Where this causes ambiguity,
-@cite{GDB} asks the user's intent.
+@code{GDB} asks the user's intent.
For details on the supported Ada syntax, see @cite{Debugging with GDB}.
@subsection Calling User-Defined Subprograms
-An important capability of @cite{GDB} is the ability to call user-defined
+An important capability of @code{GDB} is the ability to call user-defined
subprograms while debugging. This is achieved simply by entering
a subprogram call statement in the form:
@end example
@end quotation
-The keyword @cite{call} can be omitted in the normal case where the
-@cite{subprogram-name} does not coincide with any of the predefined
-@cite{GDB} commands.
+The keyword @code{call} can be omitted in the normal case where the
+@code{subprogram-name} does not coincide with any of the predefined
+@code{GDB} commands.
The effect is to invoke the given subprogram, passing it the
list of parameters that is supplied. The parameters can be expressions and
can include variables from the program being debugged. The
subprogram must be defined
-at the library level within your program, and @cite{GDB} will call the
+at the library level within your program, and @code{GDB} will call the
subprogram within the environment of your program execution (which
means that the subprogram is free to access or even modify variables
within your program).
in your program. Such debugging routines can be written to provide a suitably
high-level description of an abstract type, rather than a low-level dump
of its physical layout. After all, the standard
-@cite{GDB print} command only knows the physical layout of your
+@code{GDB print} command only knows the physical layout of your
types, not their abstract meaning. Debugging routines can provide information
at the desired semantic level and are thus enormously useful.
the contents of the tree nodes used to represent the program internally.
But tree nodes are represented simply by an integer value (which in turn
is an index into a table of nodes).
-Using the @cite{print} command on a tree node would simply print this integer
+Using the @code{print} command on a tree node would simply print this integer
value, which is not very useful. But the PN routine (defined in file
treepr.adb in the GNAT sources) takes a tree node as input, and displays
a useful high level representation of the tree node, which includes the
@subsection Using the @emph{next} Command in a Function
-When you use the @cite{next} command in a function, the current source
+When you use the @code{next} command in a function, the current source
location will advance to the next statement as usual. A special case
-arises in the case of a @cite{return} statement.
+arises in the case of a @code{return} statement.
Part of the code for a return statement is the 'epilogue' of the function.
This is the code that returns to the caller. There is only one copy of
implementations, this epilogue is associated with the first statement
of the function.
-The result is that if you use the @cite{next} command from a return
+The result is that if you use the @code{next} command from a return
statement that is not the last return statement of the function you
may see a strange apparent jump to the last return statement or to
the start of the function. You should simply ignore this odd jump.
@table @asis
-@item @emph{catch exception}
+@item @code{catch exception}
Set a catchpoint that stops execution whenever (any task in the) program
raises any exception.
@table @asis
-@item @emph{catch exception `name`}
+@item @code{catch exception @emph{name}}
Set a catchpoint that stops execution whenever (any task in the) program
-raises the exception @cite{name}.
+raises the exception @emph{name}.
@end table
@item
@table @asis
-@item @emph{catch exception unhandled}
+@item @code{catch exception unhandled}
Set a catchpoint that stops executing whenever (any task in the) program
raises an exception for which there is no handler.
@table @asis
-@item @emph{info exceptions}, @emph{info exceptions `regexp`}
+@item @code{info exceptions}, @code{info exceptions @emph{regexp}}
-The @cite{info exceptions} command permits the user to examine all defined
-exceptions within Ada programs. With a regular expression, @cite{regexp}, as
-argument, prints out only those exceptions whose name matches @cite{regexp}.
+The @code{info exceptions} command permits the user to examine all defined
+exceptions within Ada programs. With a regular expression, @emph{regexp}, as
+argument, prints out only those exceptions whose name matches @emph{regexp}.
@end table
@end itemize
@subsection Ada Tasks
-@cite{GDB} allows the following task-related commands:
+@code{GDB} allows the following task-related commands:
@itemize *
@table @asis
-@item @emph{info tasks}
+@item @code{info tasks}
This command shows a list of current Ada tasks, as in the following example:
@itemize *
@item
-@emph{break `linespec` task `taskid`}, @emph{break `linespec` task `taskid` if ...}
+@code{break`@w{`}*linespec* `@w{`}task} @emph{taskid}, @code{break} @emph{linespec} @code{task} @emph{taskid} @code{if} ...
@quotation
-These commands are like the @cite{break ... thread ...}.
-@cite{linespec} specifies source lines.
+These commands are like the @code{break ... thread ...}.
+@emph{linespec} specifies source lines.
Use the qualifier @code{task @emph{taskid}} with a breakpoint command
-to specify that you only want @cite{GDB} to stop the program when a
-particular Ada task reaches this breakpoint. @cite{taskid} is one of the
-numeric task identifiers assigned by @cite{GDB}, shown in the first
+to specify that you only want @code{GDB} to stop the program when a
+particular Ada task reaches this breakpoint. @emph{taskid} is one of the
+numeric task identifiers assigned by @code{GDB}, shown in the first
column of the @code{info tasks} display.
If you do not specify @code{task @emph{taskid}} when you set a
breakpoint, the breakpoint applies to @emph{all} tasks of your
program.
-You can use the @cite{task} qualifier on conditional breakpoints as
+You can use the @code{task} qualifier on conditional breakpoints as
well; in this case, place @code{task @emph{taskid}} before the
-breakpoint condition (before the @cite{if}).
+breakpoint condition (before the @code{if}).
@end quotation
@end itemize
@itemize *
@item
-@emph{task `taskno`}
+@code{task @emph{taskno}}
@quotation
-This command allows switching to the task referred by @cite{taskno}. In
+This command allows switching to the task referred by @emph{taskno}. In
particular, this allows browsing of the backtrace of the specified
task. It is advisable to switch back to the original task before
continuing execution otherwise the scheduling of the program may be
made, with appropriate substitutions of formals by actuals.
It is not possible to refer to the original generic entities in
-@cite{GDB}, but it is always possible to debug a particular instance of
+@code{GDB}, but it is always possible to debug a particular instance of
a generic, by using the appropriate expanded names. For example, if we have
@quotation
@itemize *
@item
-Run @emph{gcc} with the @emph{-gnatf}. This first
+Run @code{gcc} with the @code{-gnatf}. This first
switch causes all errors on a given line to be reported. In its absence,
only the first error on a line is displayed.
-The @emph{-gnatdO} switch causes errors to be displayed as soon as they
+The @code{-gnatdO} switch causes errors to be displayed as soon as they
are encountered, rather than after compilation is terminated. If GNAT
terminates prematurely or goes into an infinite loop, the last error
message displayed may help to pinpoint the culprit.
@item
-Run @emph{gcc} with the @emph{-v (verbose)} switch. In this
-mode, @emph{gcc} produces ongoing information about the progress of the
+Run @code{gcc} with the @code{-v} (verbose) switch. In this
+mode, @code{gcc} produces ongoing information about the progress of the
compilation and provides the name of each procedure as code is
generated. This switch allows you to find which Ada procedure was being
compiled when it encountered a code generation problem.
@itemize *
@item
-Run @emph{gcc} with the @emph{-gnatdc} switch. This is a GNAT specific
-switch that does for the front-end what @emph{-v} does
+Run @code{gcc} with the @code{-gnatdc} switch. This is a GNAT specific
+switch that does for the front-end what @code{-v} does
for the back end. The system prints the name of each unit,
either a compilation unit or nested unit, as it is being analyzed.
@item
Finally, you can start
-@cite{gdb} directly on the @cite{gnat1} executable. @cite{gnat1} is the
+@code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the
front-end of GNAT, and can be run independently (normally it is just
-called from @emph{gcc}). You can use @cite{gdb} on @cite{gnat1} as you
+called from @code{gcc}). You can use @code{gdb} on @code{gnat1} as you
would on a C program (but @ref{16e,,The GNAT Debugger GDB} for caveats). The
-@cite{where} command is the first line of attack; the variable
-@cite{lineno} (seen by @cite{print lineno}), used by the second phase of
-@cite{gnat1} and by the @emph{gcc} backend, indicates the source line at
-which the execution stopped, and @cite{input_file name} indicates the name of
+@code{where} command is the first line of attack; the variable
+@code{lineno} (seen by @code{print lineno}), used by the second phase of
+@code{gnat1} and by the @code{gcc} backend, indicates the source line at
+which the execution stopped, and @code{input_file name} indicates the name of
the source file.
@end itemize
@geindex Annex A (in Ada Reference Manual)
@item
-Ada files with the prefix @code{a-} are children of @cite{Ada}, as
+Ada files with the prefix @code{a-} are children of @code{Ada}, as
defined in Annex A.
@geindex Annex B (in Ada reference Manual)
@item
-Files with prefix @code{i-} are children of @cite{Interfaces}, as
+Files with prefix @code{i-} are children of @code{Interfaces}, as
defined in Annex B.
@geindex System (package in Ada Reference Manual)
@item
-Files with prefix @code{s-} are children of @cite{System}. This includes
+Files with prefix @code{s-} are children of @code{System}. This includes
both language-defined children and GNAT run-time routines.
@geindex GNAT (package)
@item
-Files with prefix @code{g-} are children of @cite{GNAT}. These are useful
+Files with prefix @code{g-} are children of @code{GNAT}. These are useful
general-purpose packages, fully documented in their specs. All
-the other @code{.c} files are modifications of common @emph{gcc} files.
+the other @code{.c} files are modifications of common @code{gcc} files.
@end itemize
@node Getting Internal Debugging Information,Stack Traceback,Naming Conventions for GNAT Source Files,Running and Debugging Ada Programs
@geindex stack unwinding
-@node Stack Traceback,,Getting Internal Debugging Information,Running and Debugging Ada Programs
+@node Stack Traceback,Pretty-Printers for the GNAT runtime,Getting Internal Debugging Information,Running and Debugging Ada Programs
@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{188}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{189}
@subsection Stack Traceback
A runtime non-symbolic traceback is a list of addresses of call instructions.
-To enable this feature you must use the @emph{-E}
-@cite{gnatbind}'s option. With this option a stack traceback is stored as part
+To enable this feature you must use the @code{-E}
+@code{gnatbind} option. With this option a stack traceback is stored as part
of exception information. You can retrieve this information using the
-@cite{addr2line} tool.
+@code{addr2line} tool.
Here is a simple example:
@end quotation
As we see the traceback lists a sequence of addresses for the unhandled
-exception @cite{CONSTRAINT_ERROR} raised in procedure P1. It is easy to
+exception @code{CONSTRAINT_ERROR} raised in procedure P1. It is easy to
guess that this exception come from procedure P1. To translate these
addresses into the source lines where the calls appear, the
-@cite{addr2line} tool, described below, is invaluable. The use of this tool
+@code{addr2line} tool, described below, is invaluable. The use of this tool
requires the program to be compiled with debug information.
@quotation
@end example
@end quotation
-The @cite{addr2line} tool has several other useful options:
+The @code{addr2line} tool has several other useful options:
@quotation
@ref{11c,,Running gnatbind}. The remaining entries are assorted runtime routines,
and the output will vary from platform to platform.
-It is also possible to use @cite{GDB} with these traceback addresses to debug
+It is also possible to use @code{GDB} with these traceback addresses to debug
the program. For example, we can break at a given code location, as reported
in the stack traceback:
@subsubheading Tracebacks From Exception Occurrences
-Non-symbolic tracebacks are obtained by using the @emph{-E} binder argument.
+Non-symbolic tracebacks are obtained by using the @code{-E} binder argument.
The stack traceback is attached to the exception information string, and can
be retrieved in an exception handler within the Ada program, by means of the
-Ada facilities defined in @cite{Ada.Exceptions}. Here is a simple example:
+Ada facilities defined in @code{Ada.Exceptions}. Here is a simple example:
@quotation
It is also possible to retrieve a stack traceback from anywhere in a
program. For this you need to
-use the @cite{GNAT.Traceback} API. This package includes a procedure called
-@cite{Call_Chain} that computes a complete stack traceback, as well as useful
+use the @code{GNAT.Traceback} API. This package includes a procedure called
+@code{Call_Chain} that computes a complete stack traceback, as well as useful
display procedures described below. It is not necessary to use the
-@emph{-E gnatbind} option in this case, because the stack traceback mechanism
+@code{-E} @code{gnatbind} option in this case, because the stack traceback mechanism
is invoked explicitly.
In the following example we compute a traceback at a specific location in
-the program, and we display it using @cite{GNAT.Debug_Utilities.Image} to
+the program, and we display it using @code{GNAT.Debug_Utilities.Image} to
convert addresses to strings:
@quotation
@end example
@end quotation
-You can then get further information by invoking the @cite{addr2line}
+You can then get further information by invoking the @code{addr2line}
tool as described earlier (note that the hexadecimal addresses
need to be specified in C format, with a leading '0x').
@end example
@end quotation
-In the above example the @code{.\} syntax in the @emph{gnatmake} command
-is currently required by @emph{addr2line} for files that are in
+In the above example the @code{.\} syntax in the @code{gnatmake} command
+is currently required by @code{addr2line} for files that are in
the current working directory.
Moreover, the exact sequence of linker options may vary from platform
to platform.
-The above @emph{-largs} section is for Windows platforms. By contrast,
-under Unix there is no need for the @emph{-largs} section.
+The above @code{-largs} section is for Windows platforms. By contrast,
+under Unix there is no need for the @code{-largs} section.
Differences across platforms are due to details of linker implementation.
@subsubheading Tracebacks From Anywhere in a Program
It is possible to get a symbolic stack traceback
from anywhere in a program, just as for non-symbolic tracebacks.
The first step is to obtain a non-symbolic
-traceback, and then call @cite{Symbolic_Traceback} to compute the symbolic
+traceback, and then call @code{Symbolic_Traceback} to compute the symbolic
information. Here is an example:
@quotation
Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as
-in @cite{gprbuild -g ... -bargs -Es}).
+in @code{gprbuild -g ... -bargs -Es}).
This will cause the Exception_Information to contain a symbolic traceback,
which will also be printed if an unhandled exception terminates the
program.
+@node Pretty-Printers for the GNAT runtime,,Stack Traceback,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{18e}@anchor{gnat_ugn/gnat_and_program_execution pretty-printers-for-the-gnat-runtime}@anchor{18f}
+@subsection Pretty-Printers for the GNAT runtime
+
+
+As discussed in @cite{Calling User-Defined Subprograms}, GDB's
+@code{print} command only knows about the physical layout of program data
+structures and therefore normally displays only low-level dumps, which
+are often hard to understand.
+
+An example of this is when trying to display the contents of an Ada
+standard container, such as @code{Ada.Containers.Ordered_Maps.Map}:
+
+@quotation
+
+@example
+with Ada.Containers.Ordered_Maps;
+
+procedure PP is
+ package Int_To_Nat is
+ new Ada.Containers.Ordered_Maps (Integer, Natural);
+
+ Map : Int_To_Nat.Map;
+begin
+ Map.Insert (1, 10);
+ Map.Insert (2, 20);
+ Map.Insert (3, 30);
+
+ Map.Clear; -- BREAK HERE
+end PP;
+@end example
+@end quotation
+
+When this program is built with debugging information and run under
+GDB up to the @code{Map.Clear} statement, trying to print @code{Map} will
+yield information that is only relevant to the developers of our standard
+containers:
+
+@quotation
+
+@example
+(gdb) print map
+$1 = (
+ tree => (
+ first => 0x64e010,
+ last => 0x64e070,
+ root => 0x64e040,
+ length => 3,
+ tc => (
+ busy => 0,
+ lock => 0
+ )
+ )
+)
+@end example
+@end quotation
+
+Fortunately, GDB has a feature called pretty-printers@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Introduction},
+which allows customizing how GDB displays data structures. The GDB
+shipped with GNAT embeds such pretty-printers for the most common
+containers in the standard library. To enable them, either run the
+following command manually under GDB or add it to your @code{.gdbinit} file:
+
+@quotation
+
+@example
+python import gnatdbg; gnatdbg.setup()
+@end example
+@end quotation
+
+Once this is done, GDB's @code{print} command will automatically use
+these pretty-printers when appropriate. Using the previous example:
+
+@quotation
+
+@example
+(gdb) print map
+$1 = pp.int_to_nat.map of length 3 = @{
+ [1] = 10,
+ [2] = 20,
+ [3] = 30
+@}
+@end example
+@end quotation
+
+Pretty-printers are invoked each time GDB tries to display a value,
+including when displaying the arguments of a called subprogram (in
+GDB's @code{backtrace} command) or when printing the value returned by a
+function (in GDB's @code{finish} command).
+
+To display a value without involving pretty-printers, @code{print} can be
+invoked with its @code{/r} option:
+
+@quotation
+
+@example
+(gdb) print/r map
+$1 = (
+ tree => (...
+@end example
+@end quotation
+
+Finer control of pretty-printers is also possible: see GDB's online documentation@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Commands}
+for more information.
+
@geindex Code Coverage
@geindex Profiling
@node Code Coverage and Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-and-profiling}@anchor{25}
+@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-and-profiling}@anchor{25}
@section Code Coverage and Profiling
-This section describes how to use the @cite{gcov} coverage testing tool and
-the @cite{gprof} profiler tool on Ada programs.
+This section describes how to use the @code{gcov} coverage testing tool and
+the @code{gprof} profiler tool on Ada programs.
@geindex gcov
@end menu
@node Code Coverage of Ada Programs with gcov,Profiling an Ada Program with gprof,,Code Coverage and Profiling
-@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{18e}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-of-ada-programs-with-gcov}@anchor{18f}
+@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{190}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-of-ada-programs-with-gcov}@anchor{191}
@subsection Code Coverage of Ada Programs with gcov
-@cite{gcov} is a test coverage program: it analyzes the execution of a given
+@code{gcov} is a test coverage program: it analyzes the execution of a given
program on selected tests, to help you determine the portions of the program
that are still untested.
-@cite{gcov} is part of the GCC suite, and is described in detail in the GCC
+@code{gcov} is part of the GCC suite, and is described in detail in the GCC
User's Guide. You can refer to this documentation for a more complete
description.
@end menu
@node Quick startup guide,GNAT specifics,,Code Coverage of Ada Programs with gcov
-@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{190}@anchor{gnat_ugn/gnat_and_program_execution quick-startup-guide}@anchor{191}
+@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{192}@anchor{gnat_ugn/gnat_and_program_execution quick-startup-guide}@anchor{193}
@subsubsection Quick startup guide
-In order to perform coverage analysis of a program using @cite{gcov}, several
+In order to perform coverage analysis of a program using @code{gcov}, several
steps are needed:
Execute the instrumented program, and
@item
-Invoke the @cite{gcov} tool to generate the coverage results.
+Invoke the @code{gcov} tool to generate the coverage results.
@end enumerate
@geindex -fprofile-arcs (gcc)
inserted by gcc during the compilation process. To compile your code with code
coverage activated, you need to recompile your whole project using the
switches
-@cite{-fprofile-arcs} and @cite{-ftest-coverage}, and link it using
-@cite{-fprofile-arcs}.
+@code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using
+@code{-fprofile-arcs}.
@quotation
will update those files, so that a cumulative result of the covered
portions of the program is generated.
-Finally, you need to call the @cite{gcov} tool. The different options of
-@cite{gcov} are described in the GCC User's Guide, section 'Invoking gcov'.
+Finally, you need to call the @code{gcov} tool. The different options of
+@code{gcov} are described in the GCC User's Guide, section @emph{Invoking gcov}.
This will create annotated source files with a @code{.gcov} extension:
@code{my_main.adb} file will be analyzed in @code{my_main.adb.gcov}.
@node GNAT specifics,,Quick startup guide,Code Coverage of Ada Programs with gcov
-@anchor{gnat_ugn/gnat_and_program_execution gnat-specifics}@anchor{192}@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{193}
+@anchor{gnat_ugn/gnat_and_program_execution gnat-specifics}@anchor{194}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{195}
@subsubsection GNAT specifics
several object files. This is the case for example when generics are
involved, when inlining is active or when declarations generate initialisation
calls. In order to take
-into account this shared code, you need to call @cite{gcov} on all
+into account this shared code, you need to call @code{gcov} on all
source files of the tested program at once.
The list of source files might exceed the system's maximum command line
length. In order to bypass this limitation, a new mechanism has been
-implemented in @cite{gcov}: you can now list all your project's files into a
+implemented in @code{gcov}: you can now list all your project's files into a
text file, and provide this file to gcov as a parameter, preceded by a @code{@@}
(e.g. @code{gcov @@mysrclist.txt}).
-Note that on AIX compiling a static library with @cite{-fprofile-arcs} is
+Note that on AIX compiling a static library with @code{-fprofile-arcs} is
not supported as there can be unresolved symbols during the final link.
@geindex gprof
@geindex Profiling
@node Profiling an Ada Program with gprof,,Code Coverage of Ada Programs with gcov,Code Coverage and Profiling
-@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{194}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{195}
+@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{196}@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{197}
@subsection Profiling an Ada Program with gprof
-This section is not meant to be an exhaustive documentation of @cite{gprof}.
+This section is not meant to be an exhaustive documentation of @code{gprof}.
Full documentation for it can be found in the @cite{GNU Profiler User's Guide}
documentation that is part of this GNAT distribution.
Profiling a program helps determine the parts of a program that are executed
most often, and are therefore the most time-consuming.
-@cite{gprof} is the standard GNU profiling tool; it has been enhanced to
+@code{gprof} is the standard GNU profiling tool; it has been enhanced to
better handle Ada programs and multitasking.
It is currently supported on the following platforms
windows x86
@end itemize
-In order to profile a program using @cite{gprof}, several steps are needed:
+In order to profile a program using @code{gprof}, several steps are needed:
@enumerate
input.
@item
-Analyze the results using the @cite{gprof} tool.
+Analyze the results using the @code{gprof} tool.
@end enumerate
The following sections detail the different steps, and indicate how
@end menu
@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{196}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{197}
+@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{198}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{199}
@subsubsection Compilation for profiling
gnatmake switch to force full recompilation.
@node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{198}@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{199}
+@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{19a}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{19b}
@subsubsection Program execution
already exists, it will be overwritten.
@node Running gprof,Interpretation of profiling results,Program execution,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{19a}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{19b}
+@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{19c}@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{19d}
@subsubsection Running gprof
-The @cite{gprof} tool is called as follow:
+The @code{gprof} tool is called as follow:
@quotation
@end example
@end quotation
-@cite{gprof} supports numerous switches. The order of these
+@code{gprof} supports numerous switches. The order of these
switch does not matter. The full list of options can be found in
the GNU Profiler User's Guide documentation that comes with this documentation.
@item @code{-e @emph{function_name}}
-The @code{-e @emph{function}} option tells @cite{gprof} not to print
-information about the function @cite{function_name} (and its
+The @code{-e @emph{function}} option tells @code{gprof} not to print
+information about the function @code{function_name} (and its
children...) in the call graph. The function will still be listed
as a child of any functions that call it, but its index number will be
shown as @code{[not printed]}. More than one @code{-e} option may be
-given; only one @cite{function_name} may be indicated with each @code{-e}
+given; only one @code{function_name} may be indicated with each @code{-e}
option.
@end table
execution time spent in the function (and children who were not called from
anywhere else), will not be used to compute the percentages-of-time for
the call graph. More than one @code{-E} option may be given; only one
-@cite{function_name} may be indicated with each @code{-E} option.
+@code{function_name} may be indicated with each @code{-E`} option.
@end table
@geindex -f (gprof)
@item @code{-f @emph{function_name}}
-The @code{-f @emph{function}} option causes @cite{gprof} to limit the
-call graph to the function @cite{function_name} and its children (and
+The @code{-f @emph{function}} option causes @code{gprof} to limit the
+call graph to the function @code{function_name} and its children (and
their children...). More than one @code{-f} option may be given;
-only one @cite{function_name} may be indicated with each @code{-f}
+only one @code{function_name} may be indicated with each @code{-f}
option.
@end table
only time spent in the function and its children (and their
children...) will be used to determine total-time and
percentages-of-time for the call graph. More than one @code{-F} option
-may be given; only one @cite{function_name} may be indicated with each
+may be given; only one @code{function_name} may be indicated with each
@code{-F} option. The @code{-F} option overrides the @code{-E} option.
@end table
@node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{19c}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{19d}
+@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{19f}
@subsubsection Interpretation of profiling results
spent in each of those callers/called subprograms.
@node Improving Performance,Overflow Check Handling in GNAT,Code Coverage and Profiling,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{26}@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{169}
+@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{169}@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{26}
@section Improving Performance
@end menu
@node Performance Considerations,Text_IO Suggestions,,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{19f}
+@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{1a1}
@subsection Performance Considerations
@end menu
@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{1a1}
+@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{1a2}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{1a3}
@subsubsection Controlling Run-Time Checks
@geindex -gnato (gcc)
-The gnat switch, @emph{-gnatp} allows this default to be modified. See
+The gnat switch, @code{-gnatp} allows this default to be modified. See
@ref{f9,,Run-Time Checks}.
Our experience is that the default is suitable for most development
For validity checks, the minimal checks required by the Ada Reference
Manual (for case statements and assignments to array elements) are on
-by default. These can be suppressed by use of the @emph{-gnatVn} switch.
+by default. These can be suppressed by use of the @code{-gnatVn} switch.
Note that in Ada 83, there were no validity checks, so if the Ada 83 mode
is acceptable (or when comparing GNAT performance with an Ada 83 compiler),
-it may be reasonable to routinely use @emph{-gnatVn}. Validity checks
-are also suppressed entirely if @emph{-gnatp} is used.
+it may be reasonable to routinely use @code{-gnatVn}. Validity checks
+are also suppressed entirely if @code{-gnatp} is used.
@geindex Overflow checks
@geindex pragma Unsuppress
Note that the setting of the switches controls the default setting of
-the checks. They may be modified using either @cite{pragma Suppress} (to
-remove checks) or @cite{pragma Unsuppress} (to add back suppressed
+the checks. They may be modified using either @code{pragma Suppress} (to
+remove checks) or @code{pragma Unsuppress} (to add back suppressed
checks) in the program source.
@node Use of Restrictions,Optimization Levels,Controlling Run-Time Checks,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{1a2}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{1a3}
+@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{1a4}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{1a5}
@subsubsection Use of Restrictions
exception handlers are used. The reason is that certain sections of code
have to be marked as non-abortable.
-If you use neither the @cite{abort} statement, nor asynchronous transfer
-of control (@cite{select ... then abort}), then this distributed overhead
+If you use neither the @code{abort} statement, nor asynchronous transfer
+of control (@code{select ... then abort}), then this distributed overhead
is removed, which may have a general positive effect in improving
overall performance. Especially code involving frequent use of tasking
constructs and controlled types will show much improved performance.
possibility of an immediate abort at any point.
@node Optimization Levels,Debugging Optimized Code,Use of Restrictions,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{1a4}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{fc}
+@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{1a6}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{fc}
@subsubsection Optimization Levels
times, but GNAT makes absolutely no attempt to optimize, and the
generated programs are considerably larger and slower than when
optimization is enabled. You can use the
-@emph{-O} switch (the permitted forms are @emph{-O0}, @emph{-O1}
-@emph{-O2}, @emph{-O3}, and @emph{-Os})
-to @emph{gcc} to control the optimization level:
+@code{-O} switch (the permitted forms are @code{-O0}, @code{-O1}
+@code{-O2}, @code{-O3}, and @code{-Os})
+to @code{gcc} to control the optimization level:
@itemize *
@table @asis
-@item @emph{-O0}
+@item @code{-O0}
No optimization (the default);
generates unoptimized code but has
the fastest compilation time.
-Note that many other compilers do fairly extensive optimization
-even if 'no optimization' is specified. With gcc, it is
-very unusual to use -O0 for production if
-execution time is of any concern, since -O0
-really does mean no optimization at all. This difference between
-gcc and other compilers should be kept in mind when doing
-performance comparisons.
+Note that many other compilers do substantial optimization even
+if 'no optimization' is specified. With gcc, it is very unusual
+to use @code{-O0} for production if execution time is of any concern,
+since @code{-O0} means (almost) no optimization. This difference
+between gcc and other compilers should be kept in mind when
+doing performance comparisons.
@end table
@item
@table @asis
-@item @emph{-O1}
+@item @code{-O1}
Moderate optimization;
optimizes reasonably well but does not
@table @asis
-@item @emph{-O2}
+@item @code{-O2}
Full optimization;
generates highly optimized code and has
@table @asis
-@item @emph{-O3}
+@item @code{-O3}
-Full optimization as in @emph{-O2};
+Full optimization as in @code{-O2};
also uses more aggressive automatic inlining of subprograms within a unit
(@ref{10f,,Inlining of Subprograms}) and attempts to vectorize loops.
@end table
@table @asis
-@item @emph{-Os}
+@item @code{-Os}
Optimize space usage (code and data) of resulting program.
@end table
See the @emph{Options That Control Optimization} section in
@cite{Using the GNU Compiler Collection (GCC)}
for details about
-the @emph{-O} settings and a number of @emph{-f} options that
+the @code{-O} settings and a number of @code{-f} options that
individually enable or disable specific optimizations.
-Unlike some other compilation systems, @emph{gcc} has
+Unlike some other compilation systems, @code{gcc} has
been tested extensively at all optimization levels. There are some bugs
which appear only with optimization turned on, but there have also been
bugs which show up only in @emph{unoptimized} code. Selecting a lower
generator, which in practice is highly reliable at all optimization
levels.
-Note regarding the use of @emph{-O3}: The use of this optimization level
-is generally discouraged with GNAT, since it often results in larger
-executables which may run more slowly. See further discussion of this point
-in @ref{10f,,Inlining of Subprograms}.
+Note regarding the use of @code{-O3}: The use of this optimization level
+ought not to be automatically preferred over that of level @code{-O2},
+since it often results in larger executables which may run more slowly.
+See further discussion of this point in @ref{10f,,Inlining of Subprograms}.
@node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{1a6}
+@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{1a7}@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{1a8}
@subsubsection Debugging Optimized Code
For example, if a loop is strength-reduced, the loop
control variable may be completely eliminated and thus cannot be
displayed in the debugger.
-This can only happen at @emph{-O2} or @emph{-O3}.
+This can only happen at @code{-O2} or @code{-O3}.
Explicit temporary variables that you code might be eliminated at
-level @emph{-O1} or higher.
+level @code{-O1} or higher.
@geindex -g (gcc)
-The use of the @emph{-g} switch,
+The use of the @code{-g} switch,
which is needed for source-level debugging,
affects the size of the program executable on disk,
and indeed the debugging information can be quite large.
@itemize *
@item
-@emph{The 'hopping Program Counter':} Repeated @cite{step} or @cite{next}
+@emph{The 'hopping Program Counter':} Repeated @code{step} or @code{next}
commands show
the PC bouncing back and forth in the code. This may result from any of
the following optimizations:
jumps to a statement that is not supposed to be executed, simply because
it (and the code following) translates to the same thing as the code
that @emph{was} supposed to be executed. This effect is typically seen in
-sequences that end in a jump, such as a @cite{goto}, a @cite{return}, or
-a @cite{break} in a C @cite{switch} statement.
+sequences that end in a jump, such as a @code{goto}, a @code{return}, or
+a @code{break} in a C @code{switch} statement.
@item
@emph{The 'roving variable':} The symptom is an unexpected value in a variable.
assignments later.
@end itemize
-In light of such anomalies, a recommended technique is to use @emph{-O0}
+In light of such anomalies, a recommended technique is to use @code{-O0}
early in the software development cycle, when extensive debugging capabilities
-are most needed, and then move to @emph{-O1} and later @emph{-O2} as
+are most needed, and then move to @code{-O1} and later @code{-O2} as
the debugger becomes less critical.
-Whether to use the @emph{-g} switch in the release version is
+Whether to use the @code{-g} switch in the release version is
a release management issue.
-Note that if you use @emph{-g} you can then use the @emph{strip} program
+Note that if you use @code{-g} you can then use the @code{strip} program
on the resulting executable,
which removes both debugging information and global symbols.
@node Inlining of Subprograms,Floating_Point_Operations,Debugging Optimized Code,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{1a7}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{10f}
+@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{1a9}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{10f}
@subsubsection Inlining of Subprograms
@itemize *
@item
-The optimization level is at least @emph{-O1}.
+The optimization level is at least @code{-O1}.
@item
The called subprogram is suitable for inlining: It must be small enough
-and not contain something that @emph{gcc} cannot support in inlined
+and not contain something that @code{gcc} cannot support in inlined
subprograms.
@geindex pragma Inline
@geindex Inline
@item
-Any one of the following applies: @cite{pragma Inline} is applied to the
+Any one of the following applies: @code{pragma Inline} is applied to the
subprogram; the subprogram is local to the unit and called once from
-within it; the subprogram is small and optimization level @emph{-O2} is
-specified; optimization level @emph{-O3} is specified.
+within it; the subprogram is small and optimization level @code{-O2} is
+specified; optimization level @code{-O3} is specified.
@end itemize
Calls to subprograms in @emph{with}ed units are normally not inlined.
@itemize *
@item
-The optimization level is at least @emph{-O1}.
+The optimization level is at least @code{-O1}.
@item
The called subprogram is suitable for inlining: It must be small enough
-and not contain something that @emph{gcc} cannot support in inlined
+and not contain something that @code{gcc} cannot support in inlined
subprograms.
@item
-There is a @cite{pragma Inline} for the subprogram.
+There is a @code{pragma Inline} for the subprogram.
@item
-The @emph{-gnatn} switch is used on the command line.
+The @code{-gnatn} switch is used on the command line.
@end itemize
Even if all these conditions are met, it may not be possible for
or features in the body that make it impossible for the compiler
to do the inlining.
-Note that specifying the @emph{-gnatn} switch causes additional
+Note that specifying the @code{-gnatn} switch causes additional
compilation dependencies. Consider the following:
@quotation
@end example
@end quotation
-With the default behavior (no @emph{-gnatn} switch specified), the
-compilation of the @cite{Main} procedure depends only on its own source,
+With the default behavior (no @code{-gnatn} switch specified), the
+compilation of the @code{Main} procedure depends only on its own source,
@code{main.adb}, and the spec of the package in file @code{r.ads}. This
-means that editing the body of @cite{R} does not require recompiling
-@cite{Main}.
+means that editing the body of @code{R} does not require recompiling
+@code{Main}.
-On the other hand, the call @cite{R.Q} is not inlined under these
-circumstances. If the @emph{-gnatn} switch is present when @cite{Main}
-is compiled, the call will be inlined if the body of @cite{Q} is small
-enough, but now @cite{Main} depends on the body of @cite{R} in
+On the other hand, the call @code{R.Q} is not inlined under these
+circumstances. If the @code{-gnatn} switch is present when @code{Main}
+is compiled, the call will be inlined if the body of @code{Q} is small
+enough, but now @code{Main} depends on the body of @code{R} in
@code{r.adb} as well as on the spec. This means that if this body is edited,
the main program must be recompiled. Note that this extra dependency
-occurs whether or not the call is in fact inlined by @emph{gcc}.
+occurs whether or not the call is in fact inlined by @code{gcc}.
-The use of front end inlining with @emph{-gnatN} generates similar
+The use of front end inlining with @code{-gnatN} generates similar
additional dependencies.
@geindex -fno-inline (gcc)
-Note: The @emph{-fno-inline} switch overrides all other conditions and ensures that
-no inlining occurs, unless requested with pragma Inline_Always for @emph{gcc}
-back-ends. The extra dependences resulting from @emph{-gnatn} will still be active,
+Note: The @code{-fno-inline} switch overrides all other conditions and ensures that
+no inlining occurs, unless requested with pragma Inline_Always for @code{gcc}
+back-ends. The extra dependences resulting from @code{-gnatn} will still be active,
even if this switch is used to suppress the resulting inlining actions.
@geindex -fno-inline-functions (gcc)
-Note: The @emph{-fno-inline-functions} switch can be used to prevent
-automatic inlining of subprograms if @emph{-O3} is used.
+Note: The @code{-fno-inline-functions} switch can be used to prevent
+automatic inlining of subprograms if @code{-O3} is used.
@geindex -fno-inline-small-functions (gcc)
-Note: The @emph{-fno-inline-small-functions} switch can be used to prevent
-automatic inlining of small subprograms if @emph{-O2} is used.
+Note: The @code{-fno-inline-small-functions} switch can be used to prevent
+automatic inlining of small subprograms if @code{-O2} is used.
@geindex -fno-inline-functions-called-once (gcc)
-Note: The @emph{-fno-inline-functions-called-once} switch
+Note: The @code{-fno-inline-functions-called-once} switch
can be used to prevent inlining of subprograms local to the unit
-and called once from within it if @emph{-O1} is used.
-
-Note regarding the use of @emph{-O3}: @emph{-gnatn} is made up of two
-sub-switches @emph{-gnatn1} and @emph{-gnatn2} that can be directly
-specified in lieu of it, @emph{-gnatn} being translated into one of them
-based on the optimization level. With @emph{-O2} or below, @emph{-gnatn}
-is equivalent to @emph{-gnatn1} which activates pragma @cite{Inline} with
-moderate inlining across modules. With @emph{-O3}, @emph{-gnatn} is
-equivalent to @emph{-gnatn2} which activates pragma @cite{Inline} with
-full inlining across modules. If you have used pragma @cite{Inline} in
-appropriate cases, then it is usually much better to use @emph{-O2}
-and @emph{-gnatn} and avoid the use of @emph{-O3} which has the additional
+and called once from within it if @code{-O1} is used.
+
+Note regarding the use of @code{-O3}: @code{-gnatn} is made up of two
+sub-switches @code{-gnatn1} and @code{-gnatn2} that can be directly
+specified in lieu of it, @code{-gnatn} being translated into one of them
+based on the optimization level. With @code{-O2} or below, @code{-gnatn}
+is equivalent to @code{-gnatn1} which activates pragma @code{Inline} with
+moderate inlining across modules. With @code{-O3}, @code{-gnatn} is
+equivalent to @code{-gnatn2} which activates pragma @code{Inline} with
+full inlining across modules. If you have used pragma @code{Inline} in
+appropriate cases, then it is usually much better to use @code{-O2}
+and @code{-gnatn} and avoid the use of @code{-O3} which has the additional
effect of inlining subprograms you did not think should be inlined. We have
-found that the use of @emph{-O3} may slow down the compilation and increase
+found that the use of @code{-O3} may slow down the compilation and increase
the code size by performing excessive inlining, leading to increased
instruction cache pressure from the increased code size and thus minor
performance improvements. So the bottom line here is that you should not
-automatically assume that @emph{-O3} is better than @emph{-O2}, and
-indeed you should use @emph{-O3} only if tests show that it actually
+automatically assume that @code{-O3} is better than @code{-O2}, and
+indeed you should use @code{-O3} only if tests show that it actually
improves performance for your program.
@node Floating_Point_Operations,Vectorization of loops,Inlining of Subprograms,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{1a8}@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{1a9}
+@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{1ab}
@subsubsection Floating_Point_Operations
switches.
@node Vectorization of loops,Other Optimization Switches,Floating_Point_Operations,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{1ab}
+@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{1ac}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{1ad}
@subsubsection Vectorization of loops
@geindex Optimization Switches
-You can take advantage of the auto-vectorizer present in the @emph{gcc}
+You can take advantage of the auto-vectorizer present in the @code{gcc}
back end to vectorize loops with GNAT. The corresponding command line switch
-is @emph{-ftree-vectorize} but, as it is enabled by default at @emph{-O3}
+is @code{-ftree-vectorize} but, as it is enabled by default at @code{-O3}
and other aggressive optimizations helpful for vectorization also are enabled
-by default at this level, using @emph{-O3} directly is recommended.
+by default at this level, using @code{-O3} directly is recommended.
You also need to make sure that the target architecture features a supported
SIMD instruction set. For example, for the x86 architecture, you should at
-least specify @emph{-msse2} to get significant vectorization (but you don't
+least specify @code{-msse2} to get significant vectorization (but you don't
need to specify it for x86-64 as it is part of the base 64-bit architecture).
-Similarly, for the PowerPC architecture, you should specify @emph{-maltivec}.
+Similarly, for the PowerPC architecture, you should specify @code{-maltivec}.
-The preferred loop form for vectorization is the @cite{for} iteration scheme.
-Loops with a @cite{while} iteration scheme can also be vectorized if they are
+The preferred loop form for vectorization is the @code{for} iteration scheme.
+Loops with a @code{while} iteration scheme can also be vectorized if they are
very simple, but the vectorizer will quickly give up otherwise. With either
iteration scheme, the flow of control must be straight, in particular no
-@cite{exit} statement may appear in the loop body. The loop may however
+@code{exit} statement may appear in the loop body. The loop may however
contain a single nested loop, if it can be vectorized when considered alone:
@quotation
The vectorizable operations depend on the targeted SIMD instruction set, but
the adding and some of the multiplying operators are generally supported, as
well as the logical operators for modular types. Note that compiling
-with @emph{-gnatp} might well reveal cases where some checks do thwart
+with @code{-gnatp} might well reveal cases where some checks do thwart
vectorization.
Type conversions may also prevent vectorization if they involve semantics that
@end example
@end quotation
-if @cite{S} is the subtype of floating-point object @cite{F}.
+if @code{S} is the subtype of floating-point object @code{F}.
In most cases, the vectorizable loops are loops that iterate over arrays.
All kinds of array types are supported, i.e. constrained array types with
fix things up at run time.
It is possible to specify that a given loop should be subject to vectorization
-preferably to other optimizations by means of pragma @cite{Loop_Optimize}:
+preferably to other optimizations by means of pragma @code{Loop_Optimize}:
@quotation
omit the non-vectorized version of the loop as well as the run-time test.
@node Other Optimization Switches,Optimization and Strict Aliasing,Vectorization of loops,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{1ac}@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{1ad}
+@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{1ae}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{1af}
@subsubsection Other Optimization Switches
@geindex Optimization Switches
-Since @cite{GNAT} uses the @emph{gcc} back end, all the specialized
-@emph{gcc} optimization switches are potentially usable. These switches
+Since GNAT uses the @code{gcc} back end, all the specialized
+@code{gcc} optimization switches are potentially usable. These switches
have not been extensively tested with GNAT but can generally be expected
-to work. Examples of switches in this category are @emph{-funroll-loops}
-and the various target-specific @emph{-m} options (in particular, it has
-been observed that @emph{-march=xxx} can significantly improve performance
+to work. Examples of switches in this category are @code{-funroll-loops}
+and the various target-specific @code{-m} options (in particular, it has
+been observed that @code{-march=xxx} can significantly improve performance
on appropriate machines). For full details of these switches, see
-the @cite{Submodel Options} section in the @cite{Hardware Models and Configurations}
+the @emph{Submodel Options} section in the @emph{Hardware Models and Configurations}
chapter of @cite{Using the GNU Compiler Collection (GCC)}.
@node Optimization and Strict Aliasing,Aliased Variables and Optimization,Other Optimization Switches,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{f3}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{1ae}
+@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{f3}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{1b0}
@subsubsection Optimization and Strict Aliasing
@end example
@end quotation
-In this example, since the variable @cite{Int1V} can only access objects
-of type @cite{Int1}, and @cite{Int2V} can only access objects of type
-@cite{Int2}, there is no possibility that the assignment to
-@cite{Int2V.all} affects the value of @cite{Int1V.all}. This means that
-the compiler optimizer can "know" that the value @cite{Int1V.all} is constant
+In this example, since the variable @code{Int1V} can only access objects
+of type @code{Int1}, and @code{Int2V} can only access objects of type
+@code{Int2}, there is no possibility that the assignment to
+@code{Int2V.all} affects the value of @code{Int1V.all}. This means that
+the compiler optimizer can "know" that the value @code{Int1V.all} is constant
for all iterations of the loop and avoid the extra memory reference
required to dereference it each time through the loop.
This kind of optimization, called strict aliasing analysis, is
-triggered by specifying an optimization level of @emph{-O2} or
-higher or @emph{-Os} and allows @cite{GNAT} to generate more efficient code
+triggered by specifying an optimization level of @code{-O2} or
+higher or @code{-Os} and allows GNAT to generate more efficient code
when access values are involved.
However, although this optimization is always correct in terms of
the formal semantics of the Ada Reference Manual, difficulties can
-arise if features like @cite{Unchecked_Conversion} are used to break
+arise if features like @code{Unchecked_Conversion} are used to break
the typing system. Consider the following complete program example:
@quotation
@end example
@end quotation
-This program prints out 0 in @emph{-O0} or @emph{-O1}
-mode, but it prints out 1 in @emph{-O2} mode. That's
+This program prints out 0 in @code{-O0} or @code{-O1}
+mode, but it prints out 1 in @code{-O2} mode. That's
because in strict aliasing mode, the compiler can and
-does assume that the assignment to @cite{v2.all} could not
-affect the value of @cite{v1.all}, since different types
+does assume that the assignment to @code{v2.all} could not
+affect the value of @code{v1.all}, since different types
are involved.
This behavior is not a case of non-conformance with the standard, since
bit pattern is not a correct value of the target type can result in an
abnormal value and attempting to reference an abnormal value makes the
execution of a program erroneous. That's the case here since the result
-does not point to an object of type @cite{int2}. This means that the
+does not point to an object of type @code{int2}. This means that the
effect is entirely unpredictable.
However, although that explanation may satisfy a language
@end quotation
Unfortunately the problem is recognized when compiling the body of
-package @cite{p2}, but the actual "bad" code is generated while
-compiling the body of @cite{m} and this latter compilation does not see
-the suspicious @cite{Unchecked_Conversion}.
+package @code{p2}, but the actual "bad" code is generated while
+compiling the body of @code{m} and this latter compilation does not see
+the suspicious @code{Unchecked_Conversion}.
As implied by the warning message, there are approaches you can use to
avoid the unwanted strict aliasing optimization in a case like this.
-One possibility is to simply avoid the use of @emph{-O2}, but
+One possibility is to simply avoid the use of @code{-O2}, but
that is a bit drastic, since it throws away a number of useful
optimizations that do not involve strict aliasing assumptions.
A less drastic approach is to compile the program using the
-option @emph{-fno-strict-aliasing}. Actually it is only the
+option @code{-fno-strict-aliasing}. Actually it is only the
unit containing the dereferencing of the suspicious pointer
that needs to be compiled. So in this case, if we compile
-unit @cite{m} with this switch, then we get the expected
+unit @code{m} with this switch, then we get the expected
value of zero printed. Analyzing which units might need
the switch can be painful, so a more reasonable approach
-is to compile the entire program with options @emph{-O2}
-and @emph{-fno-strict-aliasing}. If the performance is
+is to compile the entire program with options @code{-O2}
+and @code{-fno-strict-aliasing}. If the performance is
satisfactory with this combination of options, then the
advantage is that the entire issue of possible "wrong"
optimization due to strict aliasing is avoided.
To avoid the use of compiler switches, the configuration
-pragma @cite{No_Strict_Aliasing} with no parameters may be
+pragma @code{No_Strict_Aliasing} with no parameters may be
used to specify that for all access types, the strict
aliasing optimization should be suppressed.
First, if a careful analysis of uses of the pointer shows
that there are no possible problematic references, then
the warning can be suppressed by bracketing the
-instantiation of @cite{Unchecked_Conversion} to turn
+instantiation of @code{Unchecked_Conversion} to turn
the warning off:
@quotation
The first possibility is to move the instantiation of unchecked
conversion to the unit in which the type is declared. In
this example, we would move the instantiation of
-@cite{Unchecked_Conversion} from the body of package
-@cite{p2} to the spec of package @cite{p1}. Now the
+@code{Unchecked_Conversion} from the body of package
+@code{p2} to the spec of package @code{p1}. Now the
warning disappears. That's because any use of the
access type knows there is a suspicious unchecked
conversion, and the strict aliasing optimization
If it is not practical to move the unchecked conversion to the same unit
in which the destination access type is declared (perhaps because the
source type is not visible in that unit), you may use pragma
-@cite{No_Strict_Aliasing} for the type. This pragma must occur in the
+@code{No_Strict_Aliasing} for the type. This pragma must occur in the
same declarative sequence as the declaration of the access type:
@quotation
@end quotation
Here again, the compiler now knows that the strict aliasing optimization
-should be suppressed for any reference to type @cite{a2} and the
+should be suppressed for any reference to type @code{a2} and the
expected behavior is obtained.
Finally, note that although the compiler can generate warnings for
application code where the time is increased by up to 5% by turning
this optimization off. If you have code that includes significant
usage of unchecked conversion, you might want to just stick with
-@emph{-O1} and avoid the entire issue. If you get adequate
+@code{-O1} and avoid the entire issue. If you get adequate
performance at this level of optimization level, that's probably
the safest approach. If tests show that you really need higher
-levels of optimization, then you can experiment with @emph{-O2}
-and @emph{-O2 -fno-strict-aliasing} to see how much effect this
+levels of optimization, then you can experiment with @code{-O2}
+and @code{-O2 -fno-strict-aliasing} to see how much effect this
has on size and speed of the code. If you really need to use
-@emph{-O2} with strict aliasing in effect, then you should
+@code{-O2} with strict aliasing in effect, then you should
review any uses of unchecked conversion of access types,
particularly if you are getting the warnings described above.
@node Aliased Variables and Optimization,Atomic Variables and Optimization,Optimization and Strict Aliasing,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{1af}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{1b0}
+@anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{1b1}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{1b2}
@subsubsection Aliased Variables and Optimization
@end quotation
where Get_String is a C function that uses the address in Temp to
-modify the variable @cite{Name}. This code is dubious, and arguably
+modify the variable @code{Name}. This code is dubious, and arguably
erroneous, and the compiler would be entitled to assume that
-@cite{Name} is never modified, and generate code accordingly.
+@code{Name} is never modified, and generate code accordingly.
However, in practice, this would cause some existing code that
seems to work with no optimization to start failing at high
that is, it will produce the expected results.
@node Atomic Variables and Optimization,Passive Task Optimization,Aliased Variables and Optimization,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{1b1}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{1b2}
+@anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{1b3}@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{1b4}
@subsubsection Atomic Variables and Optimization
@end example
@end quotation
-You cannot assume that the reference to @cite{RV.B}
+You cannot assume that the reference to @code{RV.B}
will read the entire 32-bit
variable with a single load instruction. It is perfectly legitimate if
the hardware allows it to do a byte read of just the B field. This read
examine the assembly language and see a full 32-bit load, this might
change in a future version of the compiler.
-If your application requires that all accesses to @cite{RV} in this
+If your application requires that all accesses to @code{RV} in this
example be full 32-bit loads, you need to make a copy for the access
as in:
useful to disable it.
@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{1b3}@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{1b4}
+@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{1b5}@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{1b6}
@subsubsection Passive Task Optimization
to be modified, only the task definition itself.
@node Text_IO Suggestions,Reducing Size of Executables with Unused Subprogram/Data Elimination,Performance Considerations,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{1b5}@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{1b6}
-@subsection @cite{Text_IO} Suggestions
+@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{1b7}@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{1b8}
+@subsection @code{Text_IO} Suggestions
@geindex Text_IO and performance
-The @cite{Ada.Text_IO} package has fairly high overheads due in part to
+The @code{Ada.Text_IO} package has fairly high overheads due in part to
the requirement of maintaining page and line counts. If performance
-is critical, a recommendation is to use @cite{Stream_IO} instead of
-@cite{Text_IO} for volume output, since this package has less overhead.
+is critical, a recommendation is to use @code{Stream_IO} instead of
+@code{Text_IO} for volume output, since this package has less overhead.
-If @cite{Text_IO} must be used, note that by default output to the standard
+If @code{Text_IO} must be used, note that by default output to the standard
output and standard error files is unbuffered (this provides better
behavior when output statements are used for debugging, or if the
progress of a program is observed by tracking the output, e.g. by
using the Unix @emph{tail -f} command to watch redirected output.
-If you are generating large volumes of output with @cite{Text_IO} and
+If you are generating large volumes of output with @code{Text_IO} and
performance is an important factor, use a designated file instead
of the standard output file, or change the standard output file to
-be buffered using @cite{Interfaces.C_Streams.setvbuf}.
+be buffered using @code{Interfaces.C_Streams.setvbuf}.
@node Reducing Size of Executables with Unused Subprogram/Data Elimination,,Text_IO Suggestions,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{1b7}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{1b8}
+@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{1b9}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{1ba}
@subsection Reducing Size of Executables with Unused Subprogram/Data Elimination
@end menu
@node About unused subprogram/data elimination,Compilation options,,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{1b9}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{1ba}
+@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{1bb}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{1bc}
@subsubsection About unused subprogram/data elimination
In both cases GNU binutils version 2.16 or later are required to enable it.
@node Compilation options,Example of unused subprogram/data elimination,About unused subprogram/data elimination,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{1bb}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{1bc}
+@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{1bd}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{1be}
@subsubsection Compilation options
In order to do this, it has to work with objects compiled with the
following options:
-@emph{-ffunction-sections} @emph{-fdata-sections}.
+@code{-ffunction-sections} @code{-fdata-sections}.
These options are usable with C and Ada files.
They will place respectively each
Once the objects and static libraries are created with these options, the
linker can perform the dead code elimination. You can do this by setting
-the @emph{-Wl,--gc-sections} option to gcc command or in the
-@emph{-largs} section of @emph{gnatmake}. This will perform a
+the @code{-Wl,--gc-sections} option to gcc command or in the
+@code{-largs} section of @code{gnatmake}. This will perform a
garbage collection of code and data never referenced.
-If the linker performs a partial link (@emph{-r} linker option), then you
-will need to provide the entry point using the @emph{-e} / @emph{--entry}
+If the linker performs a partial link (@code{-r} linker option), then you
+will need to provide the entry point using the @code{-e} / @code{--entry}
linker option.
-Note that objects compiled without the @emph{-ffunction-sections} and
-@emph{-fdata-sections} options can still be linked with the executable.
+Note that objects compiled without the @code{-ffunction-sections} and
+@code{-fdata-sections} options can still be linked with the executable.
However, no dead code elimination will be performed on those objects (they will
be linked as is).
and data of the GNAT library from your executable.
@node Example of unused subprogram/data elimination,,Compilation options,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{1bd}@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{1be}
+@anchor{gnat_ugn/gnat_and_program_execution id47}@anchor{1bf}@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{1c0}
@subsubsection Example of unused subprogram/data elimination
@end example
@end quotation
-@cite{Unused} and @cite{Unused_Data} are never referenced in this code
+@code{Unused} and @code{Unused_Data} are never referenced in this code
excerpt, and hence they may be safely removed from the final executable.
@quotation
@end example
@end quotation
-It can be observed that the procedure @cite{Unused} and the object
-@cite{Unused_Data} are removed by the linker when using the
+It can be observed that the procedure @code{Unused} and the object
+@code{Unused_Data} are removed by the linker when using the
appropriate options.
@geindex Overflow checks
@node Overflow Check Handling in GNAT,Performing Dimensionality Analysis in GNAT,Improving Performance,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id54}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{27}
+@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{27}
@section Overflow Check Handling in GNAT
@end menu
@node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{1bf}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{1c0}
+@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{1c1}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{1c2}
@subsection Background
@end example
@end quotation
-If @cite{A} has the value @cite{Integer'Last}, then the addition may cause
-overflow since the result is out of range of the type @cite{Integer}.
-In this case @cite{Constraint_Error} will be raised if checks are
+If @code{A} has the value @code{Integer'Last}, then the addition may cause
+overflow since the result is out of range of the type @code{Integer}.
+In this case @code{Constraint_Error} will be raised if checks are
enabled.
A trickier situation arises in examples like the following:
@end example
@end quotation
-where @cite{A} is @cite{Integer'Last} and @cite{C} is @cite{-1}.
+where @code{A} is @code{Integer'Last} and @code{C} is @code{-1}.
Now the final result of the expression on the right hand side is
-@cite{Integer'Last} which is in range, but the question arises whether the
-intermediate addition of @cite{(A + 1)} raises an overflow error.
+@code{Integer'Last} which is in range, but the question arises whether the
+intermediate addition of @code{(A + 1)} raises an overflow error.
The (perhaps surprising) answer is that the Ada language
definition does not answer this question. Instead it leaves
@itemize *
@item
-raise an exception (@cite{Constraint_Error}), or
+raise an exception (@code{Constraint_Error}), or
@item
yield the correct mathematical result which is then used in
@end itemize
If the compiler chooses the first approach, then the assignment of this
-example will indeed raise @cite{Constraint_Error} if overflow checking is
+example will indeed raise @code{Constraint_Error} if overflow checking is
enabled, or result in erroneous execution if overflow checks are suppressed.
But if the compiler
One often wants to regard arithmetic in a context like this from
a mathematical point of view. So for example, if the two actual parameters
-for a call to @cite{P} are both @cite{Integer'Last}, then
+for a call to @code{P} are both @code{Integer'Last}, then
the precondition should be regarded as False. If we are executing
in a mode with run-time checks enabled for preconditions, then we would
like this precondition to fail, rather than raising an exception
because of the intermediate overflow.
However, the language definition leaves the specification of
-whether the above condition fails (raising @cite{Assert_Error}) or
-causes an intermediate overflow (raising @cite{Constraint_Error})
+whether the above condition fails (raising @code{Assert_Error}) or
+causes an intermediate overflow (raising @code{Constraint_Error})
up to the implementation.
The situation is worse in a case such as the following:
would prefer this precondition to be considered True at run time).
@node Management of Overflows in GNAT,Specifying the Desired Mode,Background,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{1c1}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1c2}
+@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1c3}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1c4}
@subsection Management of Overflows in GNAT
@itemize *
@item
-@emph{Use base type for intermediate operations} (@cite{STRICT})
+@emph{Use base type for intermediate operations} (@code{STRICT})
In this mode, all intermediate results for predefined arithmetic
operators are computed using the base type, and the result must
This is the normal default mode.
@item
-@emph{Most intermediate overflows avoided} (@cite{MINIMIZED})
+@emph{Most intermediate overflows avoided} (@code{MINIMIZED})
In this mode, the compiler attempts to avoid intermediate overflows by
-using a larger integer type, typically @cite{Long_Long_Integer},
+using a larger integer type, typically @code{Long_Long_Integer},
as the type in which arithmetic is
performed for predefined arithmetic operators. This may be slightly more
expensive at
the cost is negligible on modern 64-bit machines. For the examples given
earlier, no intermediate overflows would have resulted in exceptions,
since the intermediate results are all in the range of
-@cite{Long_Long_Integer} (typically 64-bits on nearly all implementations
+@code{Long_Long_Integer} (typically 64-bits on nearly all implementations
of GNAT). In addition, if checks are enabled, this reduces the number of
checks that must be made, so this choice may actually result in an
improvement in space and time behavior.
-However, there are cases where @cite{Long_Long_Integer} is not large
+However, there are cases where @code{Long_Long_Integer} is not large
enough, consider the following example:
@quotation
@end example
@end quotation
-where @cite{A} = @cite{B} = @cite{C} = @cite{D} = @cite{Integer'Last}.
+where @code{A} = @code{B} = @code{C} = @code{D} = @code{Integer'Last}.
Now the intermediate results are
-out of the range of @cite{Long_Long_Integer} even though the final result
+out of the range of @code{Long_Long_Integer} even though the final result
is in range and the precondition is True (from a mathematical point
of view). In such a case, operating in this mode, an overflow occurs
for the intermediate computation (which is why this mode
execution is erroneous if overflow checks are suppressed.
@item
-@emph{All intermediate overflows avoided} (@cite{ELIMINATED})
+@emph{All intermediate overflows avoided} (@code{ELIMINATED})
In this mode, the compiler avoids all intermediate overflows
by using arbitrary precision arithmetic as required. In this
-mode, the above example with @cite{A**2 * B**2} would
+mode, the above example with @code{A**2 * B**2} would
not cause intermediate overflow, because the intermediate result
would be evaluated using sufficient precision, and the result
of evaluating the precondition would be True.
Note that in this mode, the behavior is unaffected by whether or
not overflow checks are suppressed, since overflow does not occur.
It is possible for gigantic intermediate expressions to raise
-@cite{Storage_Error} as a result of attempting to compute the
-results of such expressions (e.g. @cite{Integer'Last ** Integer'Last})
+@code{Storage_Error} as a result of attempting to compute the
+results of such expressions (e.g. @code{Integer'Last ** Integer'Last})
but overflow is impossible.
@end itemize
are enabled
then fixed-point values are always checked for overflow against the
base type for intermediate expressions (that is such checks always
-operate in the equivalent of @cite{STRICT} mode).
+operate in the equivalent of @code{STRICT} mode).
-For floating-point, on nearly all architectures, @cite{Machine_Overflows}
+For floating-point, on nearly all architectures, @code{Machine_Overflows}
is False, and IEEE infinities are generated, so overflow exceptions
are never raised. If you want to avoid infinities, and check that
final results of expressions are in range, then you can declare a
range checks).
@node Specifying the Desired Mode,Default Settings,Management of Overflows in GNAT,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{f8}@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1c3}
+@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{f8}@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1c5}
@subsection Specifying the Desired Mode
@geindex pragma Overflow_Mode
The desired mode of for handling intermediate overflow can be specified using
-either the @cite{Overflow_Mode} pragma or an equivalent compiler switch.
+either the @code{Overflow_Mode} pragma or an equivalent compiler switch.
The pragma has the form
@quotation
@end example
@end quotation
-where @cite{MODE} is one of
+where @code{MODE} is one of
@itemize *
@item
-@cite{STRICT}: intermediate overflows checked (using base type)
+@code{STRICT}: intermediate overflows checked (using base type)
@item
-@cite{MINIMIZED}: minimize intermediate overflows
+@code{MINIMIZED}: minimize intermediate overflows
@item
-@cite{ELIMINATED}: eliminate intermediate overflows
+@code{ELIMINATED}: eliminate intermediate overflows
@end itemize
-The case is ignored, so @cite{MINIMIZED}, @cite{Minimized} and
-@cite{minimized} all have the same effect.
+The case is ignored, so @code{MINIMIZED}, @code{Minimized} and
+@code{minimized} all have the same effect.
-If only the @cite{General} parameter is present, then the given @cite{MODE}
-applies
+If only the @code{General} parameter is present, then the given @code{MODE} applies
to expressions both within and outside assertions. If both arguments
-are present, then @cite{General} applies to expressions outside assertions,
-and @cite{Assertions} applies to expressions within assertions. For example:
+are present, then @code{General} applies to expressions outside assertions,
+and @code{Assertions} applies to expressions within assertions. For example:
@quotation
the behavior at run time matches the expected mathematical
behavior.
-The @cite{Overflow_Mode} pragma has the same scoping and placement
-rules as pragma @cite{Suppress}, so it can occur either as a
+The @code{Overflow_Mode} pragma has the same scoping and placement
+rules as pragma @code{Suppress}, so it can occur either as a
configuration pragma, specifying a default for the whole
program, or in a declarative scope, where it applies to the
remaining declarations and statements in that scope.
-Note that pragma @cite{Overflow_Mode} does not affect whether
+Note that pragma @code{Overflow_Mode} does not affect whether
overflow checks are enabled or suppressed. It only controls the
method used to compute intermediate values. To control whether
-overflow checking is enabled or suppressed, use pragma @cite{Suppress}
-or @cite{Unsuppress} in the usual manner
+overflow checking is enabled or suppressed, use pragma @code{Suppress}
+or @code{Unsuppress} in the usual manner.
@geindex -gnato? (gcc)
@geindex -gnato?? (gcc)
-Additionally, a compiler switch @emph{-gnato?} or @emph{-gnato??}
+Additionally, a compiler switch @code{-gnato?} or @code{-gnato??}
can be used to control the checking mode default (which can be subsequently
overridden using pragmas).
@quotation
-@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item
@code{1}
@tab
-use base type for intermediate operations (@cite{STRICT})
+use base type for intermediate operations (@code{STRICT})
@item
@tab
-minimize intermediate overflows (@cite{MINIMIZED})
+minimize intermediate overflows (@code{MINIMIZED})
@item
@tab
-eliminate intermediate overflows (@cite{ELIMINATED})
+eliminate intermediate overflows (@code{ELIMINATED})
@end multitable
cases; if two digits are given, then the first applies outside
assertions, and the second within assertions. Thus the equivalent
of the example pragma above would be
-@emph{-gnato23}.
+@code{-gnato23}.
-If no digits follow the @emph{-gnato}, then it is equivalent to
-@emph{-gnato11},
+If no digits follow the @code{-gnato}, then it is equivalent to
+@code{-gnato11},
causing all intermediate operations to be computed using the base
-type (@cite{STRICT} mode).
+type (@code{STRICT} mode).
@node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1c4}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1c5}
+@anchor{gnat_ugn/gnat_and_program_execution id59}@anchor{1c6}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1c7}
@subsection Default Settings
The
@geindex -gnato (gcc)
-switch @emph{-gnato} (with no digits following)
+switch @code{-gnato} (with no digits following)
is equivalent to
@quotation
which causes overflow checking of all intermediate overflows
both inside and outside assertions against the base type.
-The pragma @cite{Suppress (Overflow_Check)} disables overflow
+The pragma @code{Suppress (Overflow_Check)} disables overflow
checking, but it has no effect on the method used for computing
intermediate results.
-The pragma @cite{Unsuppress (Overflow_Check)} enables overflow
+The pragma @code{Unsuppress (Overflow_Check)} enables overflow
checking, but it has no effect on the method used for computing
intermediate results.
@node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1c6}@anchor{gnat_ugn/gnat_and_program_execution id59}@anchor{1c7}
+@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1c8}@anchor{gnat_ugn/gnat_and_program_execution id60}@anchor{1c9}
@subsection Implementation Notes
-In practice on typical 64-bit machines, the @cite{MINIMIZED} mode is
+In practice on typical 64-bit machines, the @code{MINIMIZED} mode is
reasonably efficient, and can be generally used. It also helps
to ensure compatibility with code imported from some other
compiler to GNAT.
-Setting all intermediate overflows checking (@cite{CHECKED} mode)
+Setting all intermediate overflows checking (@code{CHECKED} mode)
makes sense if you want to
make sure that your code is compatible with any other possible
Ada implementation. This may be useful in ensuring portability
The Ada standard allows the reassociation of expressions at
the same precedence level if no parentheses are present. For
-example, @cite{A+B+C} parses as though it were @cite{(A+B)+C}, but
-the compiler can reintepret this as @cite{A+(B+C)}, possibly
+example, @code{A+B+C} parses as though it were @code{(A+B)+C}, but
+the compiler can reintepret this as @code{A+(B+C)}, possibly
introducing or eliminating an overflow exception. The GNAT
compiler never takes advantage of this freedom, and the
-expression @cite{A+B+C} will be evaluated as @cite{(A+B)+C}.
+expression @code{A+B+C} will be evaluated as @code{(A+B)+C}.
If you need the other order, you can write the parentheses
-explicitly @cite{A+(B+C)} and GNAT will respect this order.
+explicitly @code{A+(B+C)} and GNAT will respect this order.
-The use of @cite{ELIMINATED} mode will cause the compiler to
+The use of @code{ELIMINATED} mode will cause the compiler to
automatically include an appropriate arbitrary precision
integer arithmetic package. The compiler will make calls
to this package, though only in cases where it cannot be
-sure that @cite{Long_Long_Integer} is sufficient to guard against
+sure that @code{Long_Long_Integer} is sufficient to guard against
intermediate overflows. This package does not use dynamic
alllocation, but it does use the secondary stack, so an
appropriate secondary stack package must be present (this
is always true for standard full Ada, but may require
specific steps for restricted run times such as ZFP).
-Although @cite{ELIMINATED} mode causes expressions to use arbitrary
+Although @code{ELIMINATED} mode causes expressions to use arbitrary
precision arithmetic, avoiding overflow, the final result
must be in an appropriate range. This is true even if the
-final result is of type @cite{[Long_[Long_]]Integer'Base}, which
+final result is of type @code{[Long_[Long_]]Integer'Base}, which
still has the same bounds as its associated constrained
type at run-time.
-Currently, the @cite{ELIMINATED} mode is only available on target
-platforms for which @cite{Long_Long_Integer} is 64-bits (nearly all GNAT
+Currently, the @code{ELIMINATED} mode is only available on target
+platforms for which @code{Long_Long_Integer} is 64-bits (nearly all GNAT
platforms).
@node Performing Dimensionality Analysis in GNAT,Stack Related Facilities,Overflow Check Handling in GNAT,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{28}@anchor{gnat_ugn/gnat_and_program_execution id60}@anchor{16b}
+@anchor{gnat_ugn/gnat_and_program_execution id61}@anchor{16b}@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{28}
@section Performing Dimensionality Analysis in GNAT
This feature depends on Ada 2012 aspect specifications, and is available from
version 7.0.1 of GNAT onwards.
-The GNAT-specific aspect @cite{Dimension_System}
-allows you to define a system of units; the aspect @cite{Dimension}
+The GNAT-specific aspect @code{Dimension_System}
+allows you to define a system of units; the aspect @code{Dimension}
then allows the user to declare dimensioned quantities within a given system.
(These aspects are described in the @emph{Implementation Defined Aspects}
chapter of the @emph{GNAT Reference Manual}).
@geindex MKS_Type type
The simplest way to impose dimensionality checking on a computation is to make
-use of the package @cite{System.Dim.Mks},
+use of the package @code{System.Dim.Mks},
which is part of the GNAT library. This
-package defines a floating-point type @cite{MKS_Type},
+package defines a floating-point type @code{MKS_Type},
for which a sequence of
dimension names are specified, together with their conventional abbreviations.
The following should be read together with the full specification of the
@end example
@end quotation
-and similarly for @cite{Mass}, @cite{Time}, @cite{Electric_Current},
-@cite{Thermodynamic_Temperature}, @cite{Amount_Of_Substance}, and
-@cite{Luminous_Intensity} (the standard set of units of the SI system).
+and similarly for @code{Mass}, @code{Time}, @code{Electric_Current},
+@code{Thermodynamic_Temperature}, @code{Amount_Of_Substance}, and
+@code{Luminous_Intensity} (the standard set of units of the SI system).
The package also defines conventional names for values of each unit, for
example:
@end quotation
@node Stack Related Facilities,Memory Management Issues,Performing Dimensionality Analysis in GNAT,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id61}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{29}
+@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{29}@anchor{gnat_ugn/gnat_and_program_execution id62}@anchor{16c}
@section Stack Related Facilities
@end menu
@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id62}@anchor{1c8}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{f4}
+@anchor{gnat_ugn/gnat_and_program_execution id63}@anchor{1ca}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{f4}
@subsection Stack Overflow Checking
@geindex -fstack-check (gcc)
-For most operating systems, @emph{gcc} does not perform stack overflow
+For most operating systems, @code{gcc} does not perform stack overflow
checking by default. This means that if the main environment task or
some other task exceeds the available stack space, then unpredictable
behavior will occur. Most native systems offer some level of protection by
the exception propagation code. Enabling stack checking avoids
such situations.
-To activate stack checking, compile all units with the gcc option
-@cite{-fstack-check}. For example:
+To activate stack checking, compile all units with the @code{gcc} option
+@code{-fstack-check}. For example:
@quotation
Units compiled with this option will generate extra instructions to check
that any use of the stack (for procedure calls or for declaring local
variables in declare blocks) does not exceed the available stack space.
-If the space is exceeded, then a @cite{Storage_Error} exception is raised.
+If the space is exceeded, then a @code{Storage_Error} exception is raised.
For declared tasks, the stack size is controlled by the size
-given in an applicable @cite{Storage_Size} pragma or by the value specified
+given in an applicable @code{Storage_Size} pragma or by the value specified
at bind time with @code{-d} (@ref{11f,,Switches for gnatbind}) or is set to
the default size as defined in the GNAT runtime otherwise.
appropriate operating systems commands.
@node Static Stack Usage Analysis,Dynamic Stack Usage Analysis,Stack Overflow Checking,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{f5}@anchor{gnat_ugn/gnat_and_program_execution id63}@anchor{1c9}
+@anchor{gnat_ugn/gnat_and_program_execution id64}@anchor{1cb}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{f5}
@subsection Static Stack Usage Analysis
A number of bytes.
@item
-One or more qualifiers: @cite{static}, @cite{dynamic}, @cite{bounded}.
+One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
@end itemize
The second field corresponds to the size of the known part of the function
frame.
-The qualifier @cite{static} means that the function frame size
+The qualifier @code{static} means that the function frame size
is purely static.
It usually means that all local variables have a static size.
In this case, the second field is a reliable measure of the function stack
utilization.
-The qualifier @cite{dynamic} means that the function frame size is not static.
+The qualifier @code{dynamic} means that the function frame size is not static.
It happens mainly when some local variables have a dynamic size. When this
qualifier appears alone, the second field is not a reliable measure
-of the function stack analysis. When it is qualified with @cite{bounded}, it
+of the function stack analysis. When it is qualified with @code{bounded}, it
means that the second field is a reliable maximum of the function stack
utilization.
bytes. The wording is in keeping with the qualifier documented above.
@node Dynamic Stack Usage Analysis,,Static Stack Usage Analysis,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id64}@anchor{1ca}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{121}
+@anchor{gnat_ugn/gnat_and_program_execution id65}@anchor{1cc}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{121}
@subsection Dynamic Stack Usage Analysis
It is possible to measure the maximum amount of stack used by a task, by
-adding a switch to @emph{gnatbind}, as:
+adding a switch to @code{gnatbind}, as:
@quotation
The environment task stack, e.g., the stack that contains the main unit, is
only processed when the environment variable GNAT_STACK_LIMIT is set.
-The package @cite{GNAT.Task_Stack_Usage} provides facilities to get
+The package @code{GNAT.Task_Stack_Usage} provides facilities to get
stack usage reports at run-time. See its body for the details.
@node Memory Management Issues,,Stack Related Facilities,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id65}@anchor{16d}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{2a}
+@anchor{gnat_ugn/gnat_and_program_execution id66}@anchor{16d}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{2a}
@section Memory Management Issues
@end menu
@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id66}@anchor{1cb}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1cc}
+@anchor{gnat_ugn/gnat_and_program_execution id67}@anchor{1cd}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1ce}
@subsection Some Useful Memory Pools
@geindex storage
@geindex pool
-The @cite{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool
-storage pool. Allocations use the standard system call @cite{malloc} while
-deallocations use the standard system call @cite{free}. No reclamation is
+The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool
+storage pool. Allocations use the standard system call @code{malloc} while
+deallocations use the standard system call @code{free}. No reclamation is
performed when the pool goes out of scope. For performance reasons, the
standard default Ada allocators/deallocators do not use any explicit storage
pools but if they did, they could use this storage pool without any change in
@end example
@end quotation
-The @cite{System.Pool_Local} package offers the Unbounded_Reclaim_Pool storage
-pool. The allocation strategy is similar to @cite{Pool_Local}'s
+The @code{System.Pool_Local} package offers the @code{Unbounded_Reclaim_Pool} storage
+pool. The allocation strategy is similar to @code{Pool_Local}
except that the all
storage allocated with this pool is reclaimed when the pool object goes out of
scope. This pool provides a explicit mechanism similar to the implicit one
@end example
@end quotation
-The @cite{System.Pool_Size} package implements the Stack_Bounded_Pool used when
-@cite{Storage_Size} is specified for an access type.
+The @code{System.Pool_Size} package implements the @code{Stack_Bounded_Pool} used when
+@code{Storage_Size} is specified for an access type.
The whole storage for the pool is
allocated at once, usually on the stack at the point where the access type is
elaborated. It is automatically reclaimed when exiting the scope where the
@end quotation
@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id67}@anchor{1cd}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1ce}
+@anchor{gnat_ugn/gnat_and_program_execution id68}@anchor{1cf}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1d0}
@subsection The GNAT Debug Pool Facility
references are usually difficult to tackle because the symptoms can be
very remote from the origin of the problem. In such cases, it is
very helpful to detect the problem as early as possible. This is the
-purpose of the Storage Pool provided by @cite{GNAT.Debug_Pools}.
+purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}.
In order to use the GNAT specific debugging pool, the user must
associate a debug pool object with each of the access types that may be
@end example
@end quotation
-@cite{GNAT.Debug_Pools} is derived from a GNAT-specific kind of
-pool: the @cite{Checked_Pool}. Such pools, like standard Ada storage pools,
+@code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of
+pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools,
allow the user to redefine allocation and deallocation strategies. They
also provide a checkpoint for each dereference, through the use of
-the primitive operation @cite{Dereference} which is implicitly called at
+the primitive operation @code{Dereference} which is implicitly called at
each dereference of an access value.
Once an access type has been associated with a debug pool, operations on
@itemize *
@item
-@cite{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
+@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
@item
-@cite{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
+@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
@item
-@cite{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
+@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
@item
-@cite{GNAT.Debug_Pools.Freeing_Deallocated_Storage}
+@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage}
@end itemize
For types associated with a Debug_Pool, dynamic allocation is performed using
provided, whereupon the user can choose to release the memory to the system,
keep it allocated for further invalid access checks, or fill it with an easily
recognizable pattern for debug sessions. The memory pattern is the old IBM
-hexadecimal convention: @cite{16#DEADBEEF#}.
+hexadecimal convention: @code{16#DEADBEEF#}.
See the documentation in the file g-debpoo.ads for more information on the
various strategies.
Upon each dereference, a check is made that the access value denotes a
properly allocated memory location. Here is a complete example of use of
-@cite{Debug_Pools}, that includes typical instances of memory corruption:
+@code{Debug_Pools}, that includes typical instances of memory corruption:
@quotation
@c -- E.g. Ada |nbsp| 95
@node Platform-Specific Information,Example of Binder Output File,GNAT and Program Execution,Top
-@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}@anchor{gnat_ugn/platform_specific_information doc}@anchor{1cf}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1d0}
+@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}@anchor{gnat_ugn/platform_specific_information doc}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1d2}
@chapter Platform-Specific Information
@end menu
@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id2}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{2b}
+@anchor{gnat_ugn/platform_specific_information id2}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{2b}
@section Run-Time Libraries
@end menu
@node Summary of Run-Time Configurations,,,Run-Time Libraries
-@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1d2}@anchor{gnat_ugn/platform_specific_information id3}@anchor{1d3}
+@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1d4}@anchor{gnat_ugn/platform_specific_information id3}@anchor{1d5}
@subsection Summary of Run-Time Configurations
@node Specifying a Run-Time Library,Microsoft Windows Topics,Run-Time Libraries,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1d4}@anchor{gnat_ugn/platform_specific_information id4}@anchor{1d5}
+@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1d6}@anchor{gnat_ugn/platform_specific_information id4}@anchor{1d7}
@section Specifying a Run-Time Library
@geindex --RTS option
Selecting another run-time library temporarily can be
-achieved by using the @emph{--RTS} switch, e.g., @emph{--RTS=sjlj}
-@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1d6}
+achieved by using the @code{--RTS} switch, e.g., @code{--RTS=sjlj}
+@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1d8}
@geindex SCHED_FIFO scheduling policy
@geindex SCHED_RR scheduling policy
@end menu
@node Choosing the Scheduling Policy,Solaris-Specific Considerations,,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id5}@anchor{1d7}
+@anchor{gnat_ugn/platform_specific_information id5}@anchor{1d9}
@subsection Choosing the Scheduling Policy
When using a POSIX threads implementation, you have a choice of several
-scheduling policies: @cite{SCHED_FIFO}, @cite{SCHED_RR} and @cite{SCHED_OTHER}.
+scheduling policies: @code{SCHED_FIFO}, @code{SCHED_RR} and @code{SCHED_OTHER}.
-Typically, the default is @cite{SCHED_OTHER}, while using @cite{SCHED_FIFO}
-or @cite{SCHED_RR} requires special (e.g., root) privileges.
+Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO}
+or @code{SCHED_RR} requires special (e.g., root) privileges.
@geindex pragma Time_Slice
@geindex pragma Task_Dispatching_Policy
-By default, GNAT uses the @cite{SCHED_OTHER} policy. To specify
-@cite{SCHED_FIFO},
+By default, GNAT uses the @code{SCHED_OTHER} policy. To specify
+@code{SCHED_FIFO},
you can use one of the following:
@itemize *
@item
-@cite{pragma Time_Slice (0.0)}
+@code{pragma Time_Slice (0.0)}
@item
-the corresponding binder option @emph{-T0}
+the corresponding binder option @code{-T0}
@item
-@cite{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
+@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
@end itemize
-To specify @cite{SCHED_RR},
-you should use @cite{pragma Time_Slice} with a
-value greater than 0.0, or else use the corresponding @emph{-T}
+To specify @code{SCHED_RR},
+you should use @code{pragma Time_Slice} with a
+value greater than 0.0, or else use the corresponding @code{-T}
binder option.
To make sure a program is running as root, you can put something like
@geindex Solaris Sparc threads libraries
@node Solaris-Specific Considerations,Solaris Threads Issues,Choosing the Scheduling Policy,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id6}@anchor{1d8}@anchor{gnat_ugn/platform_specific_information solaris-specific-considerations}@anchor{1d9}
+@anchor{gnat_ugn/platform_specific_information id6}@anchor{1da}@anchor{gnat_ugn/platform_specific_information solaris-specific-considerations}@anchor{1db}
@subsection Solaris-Specific Considerations
@geindex rts-pthread threads library
@node Solaris Threads Issues,AIX-Specific Considerations,Solaris-Specific Considerations,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id7}@anchor{1da}@anchor{gnat_ugn/platform_specific_information solaris-threads-issues}@anchor{1db}
+@anchor{gnat_ugn/platform_specific_information id7}@anchor{1dc}@anchor{gnat_ugn/platform_specific_information solaris-threads-issues}@anchor{1dd}
@subsection Solaris Threads Issues
This run-time library has the advantage of being mostly shared across all
POSIX-compliant thread implementations, and it also provides under
-Solaris 8 the @cite{PTHREAD_PRIO_INHERIT}
-and @cite{PTHREAD_PRIO_PROTECT}
+Solaris 8 the @code{PTHREAD_PRIO_INHERIT}
+and @code{PTHREAD_PRIO_PROTECT}
semantics that can be selected using the predefined pragma
-@cite{Locking_Policy}
+@code{Locking_Policy}
with respectively
-@cite{Inheritance_Locking} and @cite{Ceiling_Locking} as the policy.
+@code{Inheritance_Locking} and @code{Ceiling_Locking} as the policy.
As explained above, the native run-time library is based on the Solaris thread
-library (@cite{libthread}) and is the default library.
+library (@code{libthread}) and is the default library.
@geindex GNAT_PROCESSOR environment variable (on Sparc Solaris)
@quotation
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@headitem
@code{GNAT_PROCESSOR} Value
@item
-@emph{-2}
+@code{-2}
@tab
Use the default configuration (run the program on all
-available processors) - this is the same as having @cite{GNAT_PROCESSOR}
+available processors) - this is the same as having @code{GNAT_PROCESSOR}
unset
@item
-@emph{-1}
+@code{-1}
@tab
@item
-@emph{0 .. Last_Proc}
+@code{0 .. Last_Proc}
@tab
Run the program on the specified processor.
-@cite{Last_Proc} is equal to @cite{_SC_NPROCESSORS_CONF - 1}
-(where @cite{_SC_NPROCESSORS_CONF} is a system variable).
+@code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1}
+(where @code{_SC_NPROCESSORS_CONF} is a system variable).
@end multitable
@end quotation
@node AIX-Specific Considerations,,Solaris Threads Issues,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information aix-specific-considerations}@anchor{1dc}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1dd}
+@anchor{gnat_ugn/platform_specific_information aix-specific-considerations}@anchor{1de}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1df}
@subsection AIX-Specific Considerations
@geindex AIX resolver library
On AIX, the resolver library initializes some internal structure on
-the first call to @cite{get*by*} functions, which are used to implement
-@cite{GNAT.Sockets.Get_Host_By_Name} and
-@cite{GNAT.Sockets.Get_Host_By_Address}.
+the first call to @code{get*by*} functions, which are used to implement
+@code{GNAT.Sockets.Get_Host_By_Name} and
+@code{GNAT.Sockets.Get_Host_By_Address}.
If such initialization occurs within an Ada task, and the stack size for
the task is the default size, a stack overflow may occur.
To avoid this overflow, the user should either ensure that the first call
-to @cite{GNAT.Sockets.Get_Host_By_Name} or
-@cite{GNAT.Sockets.Get_Host_By_Addrss}
-occurs in the environment task, or use @cite{pragma Storage_Size} to
+to @code{GNAT.Sockets.Get_Host_By_Name} or
+@code{GNAT.Sockets.Get_Host_By_Addrss}
+occurs in the environment task, or use @code{pragma Storage_Size} to
specify a sufficiently large size for the stack of the task that contains
this call.
@geindex Windows 98
@node Microsoft Windows Topics,Mac OS Topics,Specifying a Run-Time Library,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{2c}@anchor{gnat_ugn/platform_specific_information id9}@anchor{1de}
+@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{2c}@anchor{gnat_ugn/platform_specific_information id9}@anchor{1e0}
@section Microsoft Windows Topics
@end menu
@node Using GNAT on Windows,Using a network installation of GNAT,,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1df}@anchor{gnat_ugn/platform_specific_information id10}@anchor{1e0}
+@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1e1}@anchor{gnat_ugn/platform_specific_information id10}@anchor{1e2}
@subsection Using GNAT on Windows
One of the strengths of the GNAT technology is that its tool set
-(@emph{gcc}, @emph{gnatbind}, @emph{gnatlink}, @emph{gnatmake}, the
-@cite{gdb} debugger, etc.) is used in the same way regardless of the
+(@code{gcc}, @code{gnatbind}, @code{gnatlink}, @code{gnatmake}, the
+@code{gdb} debugger, etc.) is used in the same way regardless of the
platform.
On Windows this tool set is complemented by a number of Microsoft-specific
@itemize *
@item
-You can build applications using the @cite{CONSOLE} or @cite{WINDOWS}
+You can build applications using the @code{CONSOLE} or @code{WINDOWS}
subsystems.
@item
@itemize *
@item
-It is not possible to use @cite{GetLastError} and @cite{SetLastError}
+It is not possible to use @code{GetLastError} and @code{SetLastError}
when tasking, protected records, or exceptions are used. In these
cases, in order to implement Ada semantics, the GNAT run-time system
calls certain Win32 routines that set the last error variable to 0 upon
-success. It should be possible to use @cite{GetLastError} and
-@cite{SetLastError} when tasking, protected record, and exception
+success. It should be possible to use @code{GetLastError} and
+@code{SetLastError} when tasking, protected record, and exception
features are not used, but it is not guaranteed to work.
@item
@end itemize
@node Using a network installation of GNAT,CONSOLE and WINDOWS subsystems,Using GNAT on Windows,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id11}@anchor{1e1}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1e2}
+@anchor{gnat_ugn/platform_specific_information id11}@anchor{1e3}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1e4}
@subsection Using a network installation of GNAT
Make sure the system on which GNAT is installed is accessible from the
current machine, i.e., the install location is shared over the network.
Shared resources are accessed on Windows by means of UNC paths, which
-have the format @cite{\\server\sharename\path}
+have the format @code{\\\\server\\sharename\\path}
In order to use such a network installation, simply add the UNC path of the
@code{bin} directory of your GNAT installation in front of your PATH. For
serious performance penalty.
@node CONSOLE and WINDOWS subsystems,Temporary Files,Using a network installation of GNAT,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id12}@anchor{1e3}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{1e4}
+@anchor{gnat_ugn/platform_specific_information id12}@anchor{1e5}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{1e6}
@subsection CONSOLE and WINDOWS subsystems
@geindex -mwindows
-There are two main subsystems under Windows. The @cite{CONSOLE} subsystem
+There are two main subsystems under Windows. The @code{CONSOLE} subsystem
(which is the default subsystem) will always create a console when
launching the application. This is not something desirable when the
application has a Windows GUI. To get rid of this console the
-application must be using the @cite{WINDOWS} subsystem. To do so
-the @emph{-mwindows} linker option must be specified.
+application must be using the @code{WINDOWS} subsystem. To do so
+the @code{-mwindows} linker option must be specified.
@quotation
@end quotation
@node Temporary Files,Disabling Command Line Argument Expansion,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id13}@anchor{1e5}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1e6}
+@anchor{gnat_ugn/platform_specific_information id13}@anchor{1e7}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1e8}
@subsection Temporary Files
directories.
@node Disabling Command Line Argument Expansion,Mixed-Language Programming on Windows,Temporary Files,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1e7}
+@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1e9}
@subsection Disabling Command Line Argument Expansion
@geindex Command Line Argument Expansion
-By default, an executable compiled for the @strong{Windows} platform will do
+By default, an executable compiled for the Windows platform will do
the following postprocessing on the arguments passed on the command
line:
@end example
@end itemize
-Note that if the program is launched from a shell such as @strong{Cygwin} @strong{Bash}
+Note that if the program is launched from a shell such as Cygwin Bash
then quote removal might be performed by the shell.
In some contexts it might be useful to disable this feature (for example if
the program performs its own argument expansion). In order to do this, a C
symbol needs to be defined and set to @code{0}. You can do this by
-adding the following code fragment in one of your @strong{Ada} units:
+adding the following code fragment in one of your Ada units:
@example
Do_Argv_Expansion : Integer := 0;
@end example
@node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Disabling Command Line Argument Expansion,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1e8}@anchor{gnat_ugn/platform_specific_information id14}@anchor{1e9}
+@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1ea}@anchor{gnat_ugn/platform_specific_information id14}@anchor{1eb}
@subsection Mixed-Language Programming on Windows
Windows C/C++ development environment conditions your overall
interoperability strategy.
-If you use @emph{gcc} or Microsoft C to compile the non-Ada part of
+If you use @code{gcc} or Microsoft C to compile the non-Ada part of
your application, there are no Windows-specific restrictions that
affect the overall interoperability with your Ada code. If you do want
to use the Microsoft tools for your C++ code, you have two choices:
Encapsulate your C++ code in a DLL to be linked with your Ada
application. In this case, use the Microsoft or whatever environment to
build the DLL and use GNAT to build your executable
-(@ref{1ea,,Using DLLs with GNAT}).
+(@ref{1ec,,Using DLLs with GNAT}).
@item
Or you can encapsulate your Ada code in a DLL to be linked with the
other part of your application. In this case, use GNAT to build the DLL
-(@ref{1eb,,Building DLLs with GNAT Project files}) and use the Microsoft
+(@ref{1ed,,Building DLLs with GNAT Project files}) and use the Microsoft
or whatever environment to build your executable.
@end itemize
@end menu
@node Windows Calling Conventions,Introduction to Dynamic Link Libraries DLLs,,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1ec}@anchor{gnat_ugn/platform_specific_information id15}@anchor{1ed}
+@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1ee}@anchor{gnat_ugn/platform_specific_information id15}@anchor{1ef}
@subsubsection Windows Calling Conventions
calling convention. All convention specifiers are ignored on this
platform.
-When a subprogram @cite{F} (caller) calls a subprogram @cite{G}
-(callee), there are several ways to push @cite{G}'s parameters on the
+When a subprogram @code{F} (caller) calls a subprogram @code{G}
+(callee), there are several ways to push @code{G}'s parameters on the
stack and there are several possible scenarios to clean up the stack
-upon @cite{G}'s return. A calling convention is an agreed upon software
-protocol whereby the responsibilities between the caller (@cite{F}) and
-the callee (@cite{G}) are clearly defined. Several calling conventions
+upon @code{G}'s return. A calling convention is an agreed upon software
+protocol whereby the responsibilities between the caller (@code{F}) and
+the callee (@code{G}) are clearly defined. Several calling conventions
are available for Windows:
@itemize *
@item
-@cite{C} (Microsoft defined)
+@code{C} (Microsoft defined)
@item
-@cite{Stdcall} (Microsoft defined)
+@code{Stdcall} (Microsoft defined)
@item
-@cite{Win32} (GNAT specific)
+@code{Win32} (GNAT specific)
@item
-@cite{DLL} (GNAT specific)
+@code{DLL} (GNAT specific)
@end itemize
@menu
@end menu
@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1ee}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1ef}
-@subsubsection @cite{C} Calling Convention
+@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1f0}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1f1}
+@subsubsection @code{C} Calling Convention
This is the default calling convention used when interfacing to C/C++
-routines compiled with either @emph{gcc} or Microsoft Visual C++.
+routines compiled with either @code{gcc} or Microsoft Visual C++.
-In the @cite{C} calling convention subprogram parameters are pushed on the
+In the @code{C} calling convention subprogram parameters are pushed on the
stack by the caller from right to left. The caller itself is in charge of
cleaning up the stack after the call. In addition, the name of a routine
-with @cite{C} calling convention is mangled by adding a leading underscore.
+with @code{C} calling convention is mangled by adding a leading underscore.
The name to use on the Ada side when importing (or exporting) a routine
-with @cite{C} calling convention is the name of the routine. For
+with @code{C} calling convention is the name of the routine. For
instance the C function:
@quotation
@end example
@end quotation
-Note that in this particular case the @cite{External_Name} parameter could
+Note that in this particular case the @code{External_Name} parameter could
have been omitted since, when missing, this parameter is taken to be the
-name of the Ada entity in lower case. When the @cite{Link_Name} parameter
+name of the Ada entity in lower case. When the @code{Link_Name} parameter
is missing, as in the above example, this parameter is set to be the
-@cite{External_Name} with a leading underscore.
+@code{External_Name} with a leading underscore.
-When importing a variable defined in C, you should always use the @cite{C}
+When importing a variable defined in C, you should always use the @code{C}
calling convention unless the object containing the variable is part of a
-DLL (in which case you should use the @cite{Stdcall} calling
-convention, @ref{1f0,,Stdcall Calling Convention}).
+DLL (in which case you should use the @code{Stdcall} calling
+convention, @ref{1f2,,Stdcall Calling Convention}).
@node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1f0}@anchor{gnat_ugn/platform_specific_information id17}@anchor{1f1}
-@subsubsection @cite{Stdcall} Calling Convention
+@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1f2}@anchor{gnat_ugn/platform_specific_information id17}@anchor{1f3}
+@subsubsection @code{Stdcall} Calling Convention
This convention, which was the calling convention used for Pascal
efficiency reasons. It must be used to import any routine for which this
convention was specified.
-In the @cite{Stdcall} calling convention subprogram parameters are pushed
+In the @code{Stdcall} calling convention subprogram parameters are pushed
on the stack by the caller from right to left. The callee (and not the
caller) is in charge of cleaning the stack on routine exit. In addition,
-the name of a routine with @cite{Stdcall} calling convention is mangled by
-adding a leading underscore (as for the @cite{C} calling convention) and a
-trailing @code{@@@emph{nn}}, where @cite{nn} is the overall size (in
+the name of a routine with @code{Stdcall} calling convention is mangled by
+adding a leading underscore (as for the @code{C} calling convention) and a
+trailing @code{@@@emph{nn}}, where @code{nn} is the overall size (in
bytes) of the parameters passed to the routine.
The name to use on the Ada side when importing a C routine with a
-@cite{Stdcall} calling convention is the name of the C routine. The leading
+@code{Stdcall} calling convention is the name of the C routine. The leading
underscore and trailing @code{@@@emph{nn}} are added automatically by
the compiler. For instance the Win32 function:
@end example
@end quotation
-As for the @cite{C} calling convention, when the @cite{External_Name}
+As for the @code{C} calling convention, when the @code{External_Name}
parameter is missing, it is taken to be the name of the Ada entity in lower
case. If instead of writing the above import pragma you write:
@end example
@end quotation
-then the imported routine is @cite{_retrieve_val@@4}. However, if instead
-of specifying the @cite{External_Name} parameter you specify the
-@cite{Link_Name} as in the following example:
+then the imported routine is @code{_retrieve_val@@4}. However, if instead
+of specifying the @code{External_Name} parameter you specify the
+@code{Link_Name} as in the following example:
@quotation
@end example
@end quotation
-then the imported routine is @cite{retrieve_val}, that is, there is no
+then the imported routine is @code{retrieve_val}, that is, there is no
decoration at all. No leading underscore and no Stdcall suffix
@code{@@@emph{nn}}.
@end quotation
Note that to ease building cross-platform bindings this convention
-will be handled as a @cite{C} calling convention on non-Windows platforms.
+will be handled as a @code{C} calling convention on non-Windows platforms.
@node Win32 Calling Convention,DLL Calling Convention,Stdcall Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information id18}@anchor{1f2}@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1f3}
-@subsubsection @cite{Win32} Calling Convention
+@anchor{gnat_ugn/platform_specific_information id18}@anchor{1f4}@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1f5}
+@subsubsection @code{Win32} Calling Convention
This convention, which is GNAT-specific is fully equivalent to the
-@cite{Stdcall} calling convention described above.
+@code{Stdcall} calling convention described above.
@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information id19}@anchor{1f4}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1f5}
-@subsubsection @cite{DLL} Calling Convention
+@anchor{gnat_ugn/platform_specific_information id19}@anchor{1f6}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1f7}
+@subsubsection @code{DLL} Calling Convention
This convention, which is GNAT-specific is fully equivalent to the
-@cite{Stdcall} calling convention described above.
+@code{Stdcall} calling convention described above.
@node Introduction to Dynamic Link Libraries DLLs,Using DLLs with GNAT,Windows Calling Conventions,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id20}@anchor{1f6}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1f7}
+@anchor{gnat_ugn/platform_specific_information id20}@anchor{1f8}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1f9}
@subsubsection Introduction to Dynamic Link Libraries (DLLs)
of the routines and variables in @code{API.dll}.
@item
-If present in @code{API.dll}, routines @cite{DllMain} or
-@cite{DllMainCRTStartup} are invoked. These routines typically contain
+If present in @code{API.dll}, routines @code{DllMain} or
+@code{DllMainCRTStartup} are invoked. These routines typically contain
the initialization code needed for the well-being of the routines and
variables exported by the DLL.
@end itemize
application, a conflict will occur and the application will run
incorrectly. Hence, when possible, it is always preferable to use and
build relocatable DLLs. Both relocatable and non-relocatable DLLs are
-supported by GNAT. Note that the @emph{-s} linker option (see GNU Linker
+supported by GNAT. Note that the @code{-s} linker option (see GNU Linker
User's Guide) removes the debugging symbols from the DLL but the DLL can
still be relocated.
Unix shared libraries, is the fact that on most Unix systems all public
routines are exported by default in a Unix shared library, while under
Windows it is possible (but not required) to list exported routines in
-a definition file (see @ref{1f8,,The Definition File}).
+a definition file (see @ref{1fa,,The Definition File}).
@node Using DLLs with GNAT,Building DLLs with GNAT Project files,Introduction to Dynamic Link Libraries DLLs,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id21}@anchor{1f9}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1ea}
+@anchor{gnat_ugn/platform_specific_information id21}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1ec}
@subsubsection Using DLLs with GNAT
@end itemize
Once you have all the above, to compile an Ada application that uses the
-services of @code{API.dll} and whose main subprogram is @cite{My_Ada_App},
+services of @code{API.dll} and whose main subprogram is @code{My_Ada_App},
you simply issue the command
@quotation
@end example
@end quotation
-The argument @emph{-largs -lAPI} at the end of the @emph{gnatmake} command
+The argument @code{-largs -lAPI} at the end of the @code{gnatmake} command
tells the GNAT linker to look for an import library. The linker will
look for a library name in this specific order:
@end example
@end quotation
-you do not have to add @emph{-largs -lAPI} at the end of the
-@emph{gnatmake} command.
+you do not have to add @code{-largs -lAPI} at the end of the
+@code{gnatmake} command.
If any one of the items above is missing you will have to create it
yourself. The following sections explain how to do so using as an
@end menu
@node Creating an Ada Spec for the DLL Services,Creating an Import Library,,Using DLLs with GNAT
-@anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{1fa}@anchor{gnat_ugn/platform_specific_information id22}@anchor{1fb}
+@anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{1fc}@anchor{gnat_ugn/platform_specific_information id22}@anchor{1fd}
@subsubsection Creating an Ada Spec for the DLL Services
@end quotation
@node Creating an Import Library,,Creating an Ada Spec for the DLL Services,Using DLLs with GNAT
-@anchor{gnat_ugn/platform_specific_information id23}@anchor{1fc}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1fd}
+@anchor{gnat_ugn/platform_specific_information id23}@anchor{1fe}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1ff}
@subsubsection Creating an Import Library
DLL. Otherwise read on.
@geindex Definition file
-@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1f8}
+@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1fa}
@subsubheading The Definition File
As previously mentioned, and unlike Unix systems, the list of symbols
that are exported from a DLL must be provided explicitly in Windows.
The main goal of a definition file is precisely that: list the symbols
-exported by a DLL. A definition file (usually a file with a @cite{.def}
+exported by a DLL. A definition file (usually a file with a @code{.def}
suffix) has the following structure:
@quotation
@example
-[LIBRARY `name`]
-[DESCRIPTION `string`]
+[LIBRARY `@w{`}name`@w{`}]
+[DESCRIPTION `@w{`}string`@w{`}]
EXPORTS
- `symbol1`
- `symbol2`
+ `@w{`}symbol1`@w{`}
+ `@w{`}symbol2`@w{`}
...
@end example
@end quotation
@table @asis
-@item @emph{LIBRARY `name`}
+@item @emph{LIBRARY name}
This section, which is optional, gives the name of the DLL.
-@item @emph{DESCRIPTION `string`}
+@item @emph{DESCRIPTION string}
This section, which is optional, gives a description string that will be
embedded in the import library.
@item @emph{EXPORTS}
This section gives the list of exported symbols (procedures, functions or
-variables). For instance in the case of @code{API.dll} the @cite{EXPORTS}
+variables). For instance in the case of @code{API.dll} the @code{EXPORTS}
section of @code{API.def} looks like:
@example
@end table
Note that you must specify the correct suffix (@code{@@@emph{nn}})
-(see @ref{1ec,,Windows Calling Conventions}) for a Stdcall
+(see @ref{1ee,,Windows Calling Conventions}) for a Stdcall
calling convention function in the exported symbols list.
There can actually be other sections in a definition file, but these
sections are not relevant to the discussion at hand.
-@anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{1fe}
+@anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{200}
@subsubheading Creating a Definition File Automatically
You can automatically create the definition file @code{API.def}
-(see @ref{1f8,,The Definition File}) from a DLL.
-For that use the @cite{dlltool} program as follows:
+(see @ref{1fa,,The Definition File}) from a DLL.
+For that use the @code{dlltool} program as follows:
@quotation
$ dlltool API.dll -z API.def --export-all-symbols
@end example
-Note that if some routines in the DLL have the @cite{Stdcall} convention
-(@ref{1ec,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}}
+Note that if some routines in the DLL have the @code{Stdcall} convention
+(@ref{1ee,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}}
suffix then you'll have to edit @code{api.def} to add it, and specify
-@emph{-k} to @emph{gnatdll} when creating the import library.
+@code{-k} to @code{gnatdll} when creating the import library.
Here are some hints to find the right @code{@@@emph{nn}} suffix.
@item
If you have the Microsoft import library (.lib), it is possible to get
-the right symbols by using Microsoft @cite{dumpbin} tool (see the
+the right symbols by using Microsoft @code{dumpbin} tool (see the
corresponding Microsoft documentation for further details).
@example
definition file and add the right suffix.
@end itemize
@end quotation
-@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1ff}
+@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{201}
@subsubheading GNAT-Style Import Library
To create a static import library from @code{API.dll} with the GNAT tools
-you should create the .def file, then use @cite{gnatdll} tool
-(see @ref{200,,Using gnatdll}) as follows:
+you should create the .def file, then use @code{gnatdll} tool
+(see @ref{202,,Using gnatdll}) as follows:
@quotation
$ gnatdll -e API.def -d API.dll
@end example
-@cite{gnatdll} takes as input a definition file @code{API.def} and the
+@code{gnatdll} takes as input a definition file @code{API.def} and the
name of the DLL containing the services listed in the definition file
@code{API.dll}. The name of the static import library generated is
computed from the name of the definition file as follows: if the
-definition file name is @cite{xyz`}.def`, the import library name will
-be @cite{lib`@w{`}xyz`}.a`. Note that in the previous example option
-@emph{-e} could have been removed because the name of the definition
-file (before the '@cite{.def}' suffix) is the same as the name of the
-DLL (@ref{200,,Using gnatdll} for more information about @cite{gnatdll}).
+definition file name is @code{xyz.def}, the import library name will
+be @code{libxyz.a}. Note that in the previous example option
+@code{-e} could have been removed because the name of the definition
+file (before the @code{.def} suffix) is the same as the name of the
+DLL (@ref{202,,Using gnatdll} for more information about @code{gnatdll}).
@end quotation
-@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{201}
+@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{203}
@subsubheading Microsoft-Style Import Library
A Microsoft import library is needed only if you plan to make an
Ada DLL available to applications developed with Microsoft
-tools (@ref{1e8,,Mixed-Language Programming on Windows}).
+tools (@ref{1ea,,Mixed-Language Programming on Windows}).
To create a Microsoft-style import library for @code{API.dll} you
should create the .def file, then build the actual import library using
-Microsoft's @cite{lib} utility:
+Microsoft's @code{lib} utility:
@quotation
@end example
See the Microsoft documentation for further details about the usage of
-@cite{lib}.
+@code{lib}.
@end quotation
@node Building DLLs with GNAT Project files,Building DLLs with GNAT,Using DLLs with GNAT,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id24}@anchor{202}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1eb}
+@anchor{gnat_ugn/platform_specific_information id24}@anchor{204}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1ed}
@subsubsection Building DLLs with GNAT Project files
chapter of the @emph{GPRbuild User's Guide}.
Due to a system limitation, it is not possible under Windows to create threads
-when inside the @cite{DllMain} routine which is used for auto-initialization
+when inside the @code{DllMain} routine which is used for auto-initialization
of shared libraries, so it is not possible to have library level tasks in SALs.
@node Building DLLs with GNAT,Building DLLs with gnatdll,Building DLLs with GNAT Project files,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{203}@anchor{gnat_ugn/platform_specific_information id25}@anchor{204}
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{205}@anchor{gnat_ugn/platform_specific_information id25}@anchor{206}
@subsubsection Building DLLs with GNAT
@item
Building object files.
The first step is to build all objects files that are to be included
-into the DLL. This is done by using the standard @emph{gnatmake} tool.
+into the DLL. This is done by using the standard @code{gnatmake} tool.
@item
Building the DLL.
-To build the DLL you must use @emph{gcc}'s @emph{-shared} and
-@emph{-shared-libgcc} options. It is quite simple to use this method:
+To build the DLL you must use the @code{gcc} @code{-shared} and
+@code{-shared-libgcc} options. It is quite simple to use this method:
@example
$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ...
It is important to note that in this case all symbols found in the
object files are automatically exported. It is possible to restrict
-the set of symbols to export by passing to @emph{gcc} a definition
-file (see @ref{1f8,,The Definition File}).
+the set of symbols to export by passing to @code{gcc} a definition
+file (see @ref{1fa,,The Definition File}).
For example:
@example
At this point it is possible to use the DLL by directly linking
against it. Note that you must use the GNAT shared runtime when using
-GNAT shared libraries. This is achieved by using @emph{-shared} binder's
+GNAT shared libraries. This is achieved by using the @code{-shared} binder
option.
@quotation
@end quotation
@node Building DLLs with gnatdll,Ada DLLs and Finalization,Building DLLs with GNAT,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{205}@anchor{gnat_ugn/platform_specific_information id26}@anchor{206}
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{207}@anchor{gnat_ugn/platform_specific_information id26}@anchor{208}
@subsubsection Building DLLs with gnatdll
@geindex building
Note that it is preferred to use GNAT Project files
-(@ref{1eb,,Building DLLs with GNAT Project files}) or the built-in GNAT
-DLL support (@ref{203,,Building DLLs with GNAT}) or to build DLLs.
+(@ref{1ed,,Building DLLs with GNAT Project files}) or the built-in GNAT
+DLL support (@ref{205,,Building DLLs with GNAT}) or to build DLLs.
This section explains how to build DLLs containing Ada code using
-@cite{gnatdll}. These DLLs will be referred to as Ada DLLs in the
+@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the
remainder of this section.
The steps required to build an Ada DLL that is to be used by Ada as well as
@itemize *
@item
-You need to mark each Ada @emph{entity} exported by the DLL with a @cite{C} or
-@cite{Stdcall} calling convention to avoid any Ada name mangling for the
+You need to mark each Ada entity exported by the DLL with a @code{C} or
+@code{Stdcall} calling convention to avoid any Ada name mangling for the
entities exported by the DLL
-(see @ref{207,,Exporting Ada Entities}). You can
+(see @ref{209,,Exporting Ada Entities}). You can
skip this step if you plan to use the Ada DLL only from Ada applications.
@item
Your Ada code must export an initialization routine which calls the routine
-@cite{adainit} generated by @emph{gnatbind} to perform the elaboration of
-the Ada code in the DLL (@ref{208,,Ada DLLs and Elaboration}). The initialization
+@code{adainit} generated by @code{gnatbind} to perform the elaboration of
+the Ada code in the DLL (@ref{20a,,Ada DLLs and Elaboration}). The initialization
routine exported by the Ada DLL must be invoked by the clients of the DLL
to initialize the DLL.
@item
When useful, the DLL should also export a finalization routine which calls
-routine @cite{adafinal} generated by @emph{gnatbind} to perform the
-finalization of the Ada code in the DLL (@ref{209,,Ada DLLs and Finalization}).
+routine @code{adafinal} generated by @code{gnatbind} to perform the
+finalization of the Ada code in the DLL (@ref{20b,,Ada DLLs and Finalization}).
The finalization routine exported by the Ada DLL must be invoked by the
clients of the DLL when the DLL services are no further needed.
@item
You must provide a definition file listing the exported entities
-(@ref{1f8,,The Definition File}).
+(@ref{1fa,,The Definition File}).
@item
-Finally you must use @cite{gnatdll} to produce the DLL and the import
-library (@ref{200,,Using gnatdll}).
+Finally you must use @code{gnatdll} to produce the DLL and the import
+library (@ref{202,,Using gnatdll}).
@end itemize
-Note that a relocatable DLL stripped using the @cite{strip}
+Note that a relocatable DLL stripped using the @code{strip}
binutils tool will not be relocatable anymore. To build a DLL without
-debug information pass @cite{-largs -s} to @cite{gnatdll}. This
+debug information pass @code{-largs -s} to @code{gnatdll}. This
restriction does not apply to a DLL built using a Library Project.
See the @emph{Library Projects} section in the @emph{GNAT Project Manager}
chapter of the @emph{GPRbuild User's Guide}.
@end menu
@node Limitations When Using Ada DLLs from Ada,Exporting Ada Entities,,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{20a}
+@anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{20c}
@subsubsection Limitations When Using Ada DLLs from Ada
It is therefore not possible to exchange GNAT run-time objects between the
Ada DLL and the main Ada program. Example of GNAT run-time objects are file
-handles (e.g., @cite{Text_IO.File_Type}), tasks types, protected objects
+handles (e.g., @code{Text_IO.File_Type}), tasks types, protected objects
types, etc.
It is completely safe to exchange plain elementary, array or record types,
Windows object handles, etc.
@node Exporting Ada Entities,Ada DLLs and Elaboration,Limitations When Using Ada DLLs from Ada,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{207}@anchor{gnat_ugn/platform_specific_information id27}@anchor{20b}
+@anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{209}@anchor{gnat_ugn/platform_specific_information id27}@anchor{20d}
@subsubsection Exporting Ada Entities
Building a DLL is a way to encapsulate a set of services usable from any
application. As a result, the Ada entities exported by a DLL should be
-exported with the @cite{C} or @cite{Stdcall} calling conventions to avoid
+exported with the @code{C} or @code{Stdcall} calling conventions to avoid
any Ada name mangling. As an example here is an Ada package
-@cite{API}, spec and body, exporting two procedures, a function, and a
+@code{API}, spec and body, exporting two procedures, a function, and a
variable:
@quotation
@end quotation
If the Ada DLL you are building will only be used by Ada applications
-you do not have to export Ada entities with a @cite{C} or @cite{Stdcall}
+you do not have to export Ada entities with a @code{C} or @code{Stdcall}
convention. As an example, the previous package could be written as
follows:
@end example
@end quotation
-Note that if you do not export the Ada entities with a @cite{C} or
-@cite{Stdcall} convention you will have to provide the mangled Ada names
+Note that if you do not export the Ada entities with a @code{C} or
+@code{Stdcall} convention you will have to provide the mangled Ada names
in the definition file of the Ada DLL
-(@ref{20c,,Creating the Definition File}).
+(@ref{20e,,Creating the Definition File}).
@node Ada DLLs and Elaboration,,Exporting Ada Entities,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{208}@anchor{gnat_ugn/platform_specific_information id28}@anchor{20d}
+@anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{20a}@anchor{gnat_ugn/platform_specific_information id28}@anchor{20f}
@subsubsection Ada DLLs and Elaboration
(@ref{f,,Elaboration Order Handling in GNAT}).
To achieve this you must export an initialization routine
-(@cite{Initialize_API} in the previous example), which must be invoked
+(@code{Initialize_API} in the previous example), which must be invoked
before using any of the DLL services. This elaboration routine must call
-the Ada elaboration routine @cite{adainit} generated by the GNAT binder
+the Ada elaboration routine @code{adainit} generated by the GNAT binder
(@ref{b4,,Binding with Non-Ada Main Programs}). See the body of
-@cite{Initialize_Api} for an example. Note that the GNAT binder is
-automatically invoked during the DLL build process by the @cite{gnatdll}
-tool (@ref{200,,Using gnatdll}).
+@code{Initialize_Api} for an example. Note that the GNAT binder is
+automatically invoked during the DLL build process by the @code{gnatdll}
+tool (@ref{202,,Using gnatdll}).
When a DLL is loaded, Windows systematically invokes a routine called
-@cite{DllMain}. It would therefore be possible to call @cite{adainit}
-directly from @cite{DllMain} without having to provide an explicit
+@code{DllMain}. It would therefore be possible to call @code{adainit}
+directly from @code{DllMain} without having to provide an explicit
initialization routine. Unfortunately, it is not possible to call
-@cite{adainit} from the @cite{DllMain} if your program has library level
-tasks because access to the @cite{DllMain} entry point is serialized by
+@code{adainit} from the @code{DllMain} if your program has library level
+tasks because access to the @code{DllMain} entry point is serialized by
the system (that is, only a single thread can execute 'through' it at a
time), which means that the GNAT run time will deadlock waiting for the
newly created task to complete its initialization.
@node Ada DLLs and Finalization,Creating a Spec for Ada DLLs,Building DLLs with gnatdll,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id29}@anchor{20e}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{209}
+@anchor{gnat_ugn/platform_specific_information id29}@anchor{210}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{20b}
@subsubsection Ada DLLs and Finalization
invoke the DLL finalization routine, if available. The DLL finalization
routine is in charge of releasing all resources acquired by the DLL. In the
case of the Ada code contained in the DLL, this is achieved by calling
-routine @cite{adafinal} generated by the GNAT binder
+routine @code{adafinal} generated by the GNAT binder
(@ref{b4,,Binding with Non-Ada Main Programs}).
-See the body of @cite{Finalize_Api} for an
+See the body of @code{Finalize_Api} for an
example. As already pointed out the GNAT binder is automatically invoked
-during the DLL build process by the @cite{gnatdll} tool
-(@ref{200,,Using gnatdll}).
+during the DLL build process by the @code{gnatdll} tool
+(@ref{202,,Using gnatdll}).
@node Creating a Spec for Ada DLLs,GNAT and Windows Resources,Ada DLLs and Finalization,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id30}@anchor{20f}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{210}
+@anchor{gnat_ugn/platform_specific_information id30}@anchor{211}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{212}
@subsubsection Creating a Spec for Ada DLLs
To use the services exported by the Ada DLL from another programming
language (e.g., C), you have to translate the specs of the exported Ada
-entities in that language. For instance in the case of @cite{API.dll},
+entities in that language. For instance in the case of @code{API.dll},
the corresponding C header file could look like:
@quotation
It is important to understand that when building an Ada DLL to be used by
other Ada applications, you need two different specs for the packages
contained in the DLL: one for building the DLL and the other for using
-the DLL. This is because the @cite{DLL} calling convention is needed to
+the DLL. This is because the @code{DLL} calling convention is needed to
use a variable defined in a DLL, but when building the DLL, the variable
-must have either the @cite{Ada} or @cite{C} calling convention. As an
-example consider a DLL comprising the following package @cite{API}:
+must have either the @code{Ada} or @code{C} calling convention. As an
+example consider a DLL comprising the following package @code{API}:
@quotation
@end example
@end quotation
-After producing a DLL containing package @cite{API}, the spec that
-must be used to import @cite{API.Count} from Ada code outside of the
+After producing a DLL containing package @code{API}, the spec that
+must be used to import @code{API.Count} from Ada code outside of the
DLL is:
@quotation
@end menu
@node Creating the Definition File,Using gnatdll,,Creating a Spec for Ada DLLs
-@anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{20c}@anchor{gnat_ugn/platform_specific_information id31}@anchor{211}
+@anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{20e}@anchor{gnat_ugn/platform_specific_information id31}@anchor{213}
@subsubsection Creating the Definition File
The definition file is the last file needed to build the DLL. It lists
the exported symbols. As an example, the definition file for a DLL
-containing only package @cite{API} (where all the entities are exported
-with a @cite{C} calling convention) is:
+containing only package @code{API} (where all the entities are exported
+with a @code{C} calling convention) is:
@quotation
@end example
@end quotation
-If the @cite{C} calling convention is missing from package @cite{API},
+If the @code{C} calling convention is missing from package @code{API},
then the definition file contains the mangled Ada names of the above
entities, which in this case are:
@end quotation
@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs
-@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{200}@anchor{gnat_ugn/platform_specific_information id32}@anchor{212}
-@subsubsection Using @cite{gnatdll}
+@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{202}@anchor{gnat_ugn/platform_specific_information id32}@anchor{214}
+@subsubsection Using @code{gnatdll}
@geindex gnatdll
-@cite{gnatdll} is a tool to automate the DLL build process once all the Ada
+@code{gnatdll} is a tool to automate the DLL build process once all the Ada
and non-Ada sources that make up your DLL have been compiled.
-@cite{gnatdll} is actually in charge of two distinct tasks: build the
+@code{gnatdll} is actually in charge of two distinct tasks: build the
static import library for the DLL and the actual DLL. The form of the
-@cite{gnatdll} command is
+@code{gnatdll} command is
@quotation
@example
-$ gnatdll [`switches`] `list-of-files` [-largs `opts`]
+$ gnatdll [ switches ] list-of-files [ -largs opts ]
@end example
@end quotation
-where @cite{list-of-files} is a list of ALI and object files. The object
+where @code{list-of-files} is a list of ALI and object files. The object
file list must be the exact list of objects corresponding to the non-Ada
sources whose services are to be included in the DLL. The ALI file list
must be the exact list of ALI files for the corresponding Ada sources
-whose services are to be included in the DLL. If @cite{list-of-files} is
+whose services are to be included in the DLL. If @code{list-of-files} is
missing, only the static import library is generated.
-You may specify any of the following switches to @cite{gnatdll}:
+You may specify any of the following switches to @code{gnatdll}:
@quotation
@item @code{-a[@emph{address}]}
-Build a non-relocatable DLL at @cite{address}. If @cite{address} is not
-specified the default address @cite{0x11000000} will be used. By default,
-when this switch is missing, @cite{gnatdll} builds relocatable DLL. We
+Build a non-relocatable DLL at @code{address}. If @code{address} is not
+specified the default address @code{0x11000000} will be used. By default,
+when this switch is missing, @code{gnatdll} builds relocatable DLL. We
advise the reader to build relocatable DLL.
@geindex -b (gnatdll)
@item @code{-b @emph{address}}
Set the relocatable DLL base address. By default the address is
-@cite{0x11000000}.
+@code{0x11000000}.
@geindex -bargs (gnatdll)
@item @code{-bargs @emph{opts}}
-Binder options. Pass @cite{opts} to the binder.
+Binder options. Pass @code{opts} to the binder.
@geindex -d (gnatdll)
@item @code{-d @emph{dllfile}}
-@cite{dllfile} is the name of the DLL. This switch must be present for
-@cite{gnatdll} to do anything. The name of the generated import library is
-obtained algorithmically from @cite{dllfile} as shown in the following
-example: if @cite{dllfile} is @cite{xyz.dll}, the import library name is
-@cite{libxyz.dll.a}. The name of the definition file to use (if not specified
-by option @emph{-e}) is obtained algorithmically from @cite{dllfile}
+@code{dllfile} is the name of the DLL. This switch must be present for
+@code{gnatdll} to do anything. The name of the generated import library is
+obtained algorithmically from @code{dllfile} as shown in the following
+example: if @code{dllfile} is @code{xyz.dll}, the import library name is
+@code{libxyz.dll.a}. The name of the definition file to use (if not specified
+by option @code{-e}) is obtained algorithmically from @code{dllfile}
as shown in the following example:
-if @cite{dllfile} is @cite{xyz.dll}, the definition
-file used is @cite{xyz.def}.
+if @code{dllfile} is @code{xyz.dll}, the definition
+file used is @code{xyz.def}.
@geindex -e (gnatdll)
@item @code{-e @emph{deffile}}
-@cite{deffile} is the name of the definition file.
+@code{deffile} is the name of the definition file.
@geindex -g (gnatdll)
Generate debugging information. This information is stored in the object
file and copied from there to the final DLL file by the linker,
where it can be read by the debugger. You must use the
-@emph{-g} switch if you plan on using the debugger or the symbolic
+@code{-g} switch if you plan on using the debugger or the symbolic
stack traceback.
@geindex -h (gnatdll)
@item @code{-h}
-Help mode. Displays @cite{gnatdll} switch usage information.
+Help mode. Displays @code{gnatdll} switch usage information.
@geindex -I (gnatdll)
@item @code{-I@emph{dir}}
-Direct @cite{gnatdll} to search the @cite{dir} directory for source and
+Direct @code{gnatdll} to search the @code{dir} directory for source and
object files needed to build the DLL.
(@ref{89,,Search Paths and the Run-Time Library (RTL)}).
Removes the @code{@@@emph{nn}} suffix from the import library's exported
names, but keeps them for the link names. You must specify this
-option if you want to use a @cite{Stdcall} function in a DLL for which
+option if you want to use a @code{Stdcall} function in a DLL for which
the @code{@@@emph{nn}} suffix has been removed. This is the case for most
of the Windows NT DLL for example. This option has no effect when
-@emph{-n} option is specified.
+@code{-n} option is specified.
@geindex -l (gnatdll)
@item @code{-l @emph{file}}
The list of ALI and object files used to build the DLL are listed in
-@cite{file}, instead of being given in the command line. Each line in
-@cite{file} contains the name of an ALI or object file.
+@code{file}, instead of being given in the command line. Each line in
+@code{file} contains the name of an ALI or object file.
@geindex -n (gnatdll)
@item @code{-largs @emph{opts}}
-Linker options. Pass @cite{opts} to the linker.
+Linker options. Pass @code{opts} to the linker.
@end table
-@subsubheading @cite{gnatdll} Example
+@subsubheading @code{gnatdll} Example
As an example the command to build a relocatable DLL from @code{api.adb}
@end example
@end quotation
-@subsubheading @cite{gnatdll} behind the Scenes
+@subsubheading @code{gnatdll} behind the Scenes
-This section details the steps involved in creating a DLL. @cite{gnatdll}
+This section details the steps involved in creating a DLL. @code{gnatdll}
does these steps for you. Unless you are interested in understanding what
goes on behind the scenes, you should skip this section.
-We use the previous example of a DLL containing the Ada package @cite{API},
+We use the previous example of a DLL containing the Ada package @code{API},
to illustrate the steps necessary to build a DLL. The starting point is a
set of objects that will make up the DLL and the corresponding ALI
files. In the case of this example this means that @code{api.o} and
-@code{api.ali} are available. To build a relocatable DLL, @cite{gnatdll} does
+@code{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does
the following:
@itemize *
@item
-@cite{gnatdll} builds the base file (@code{api.base}). A base file gives
+@code{gnatdll} builds the base file (@code{api.base}). A base file gives
the information necessary to generate relocation information for the
DLL.
$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
@end example
-In addition to the base file, the @emph{gnatlink} command generates an
-output file @code{api.jnk} which can be discarded. The @emph{-mdll} switch
-asks @emph{gnatlink} to generate the routines @cite{DllMain} and
-@cite{DllMainCRTStartup} that are called by the Windows loader when the DLL
+In addition to the base file, the @code{gnatlink} command generates an
+output file @code{api.jnk} which can be discarded. The @code{-mdll} switch
+asks @code{gnatlink} to generate the routines @code{DllMain} and
+@code{DllMainCRTStartup} that are called by the Windows loader when the DLL
is loaded into memory.
@item
-@cite{gnatdll} uses @cite{dlltool} (see @ref{213,,Using dlltool}) to build the
+@code{gnatdll} uses @code{dlltool} (see @ref{215,,Using dlltool}) to build the
export table (@code{api.exp}). The export table contains the relocation
information in a form which can be used during the final link to ensure
that the Windows loader is able to place the DLL anywhere in memory.
@end example
@item
-@cite{gnatdll} builds the base file using the new export table. Note that
-@emph{gnatbind} must be called once again since the binder generated file
-has been deleted during the previous call to @emph{gnatlink}.
+@code{gnatdll} builds the base file using the new export table. Note that
+@code{gnatbind} must be called once again since the binder generated file
+has been deleted during the previous call to @code{gnatlink}.
@example
$ gnatbind -n api
@end example
@item
-@cite{gnatdll} builds the new export table using the new base file and
+@code{gnatdll} builds the new export table using the new base file and
generates the DLL import library @code{libAPI.dll.a}.
@example
@end example
@item
-Finally @cite{gnatdll} builds the relocatable DLL using the final export
+Finally @code{gnatdll} builds the relocatable DLL using the final export
table.
@example
$ gnatlink api api.exp -o api.dll -mdll
@end example
@end itemize
-@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{213}
-@subsubheading Using @cite{dlltool}
+@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{215}
+@subsubheading Using @code{dlltool}
-@cite{dlltool} is the low-level tool used by @cite{gnatdll} to build
+@code{dlltool} is the low-level tool used by @code{gnatdll} to build
DLLs and static import libraries. This section summarizes the most
-common @cite{dlltool} switches. The form of the @cite{dlltool} command
+common @code{dlltool} switches. The form of the @code{dlltool} command
is
@quotation
@end example
@end quotation
-@cite{dlltool} switches include:
+@code{dlltool} switches include:
@geindex --base-file (dlltool)
@item @code{--base-file @emph{basefile}}
-Read the base file @cite{basefile} generated by the linker. This switch
+Read the base file @code{basefile} generated by the linker. This switch
is used to create a relocatable DLL.
@end table
@item @code{--dllname @emph{name}}
Gives the name of the DLL. This switch is used to embed the name of the
-DLL in the static import library generated by @cite{dlltool} with switch
-@emph{--output-lib}.
+DLL in the static import library generated by @code{dlltool} with switch
+@code{--output-lib}.
@end table
@geindex -k (dlltool)
@item @code{-k}
Kill @code{@@@emph{nn}} from exported names
-(@ref{1ec,,Windows Calling Conventions}
-for a discussion about @cite{Stdcall}-style symbols.
+(@ref{1ee,,Windows Calling Conventions}
+for a discussion about @code{Stdcall}-style symbols.
@end table
@geindex --help (dlltool)
@item @code{--help}
-Prints the @cite{dlltool} switches with a concise description.
+Prints the @code{dlltool} switches with a concise description.
@end table
@geindex --output-exp (dlltool)
@item @code{--output-exp @emph{exportfile}}
-Generate an export file @cite{exportfile}. The export file contains the
+Generate an export file @code{exportfile}. The export file contains the
export table (list of symbols in the DLL) and is used to create the DLL.
@end table
@item @code{--output-lib @emph{libfile}}
-Generate a static import library @cite{libfile}.
+Generate a static import library @code{libfile}.
@end table
@geindex -v (dlltool)
@item @code{--as @emph{assembler-name}}
-Use @cite{assembler-name} as the assembler. The default is @cite{as}.
+Use @code{assembler-name} as the assembler. The default is @code{as}.
@end table
@node GNAT and Windows Resources,Using GNAT DLLs from Microsoft Visual Studio Applications,Creating a Spec for Ada DLLs,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{214}@anchor{gnat_ugn/platform_specific_information id33}@anchor{215}
+@anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{216}@anchor{gnat_ugn/platform_specific_information id33}@anchor{217}
@subsubsection GNAT and Windows Resources
@end example
@end quotation
-The value @cite{0809} (langID) is for the U.K English language and
-@cite{04E4} (charsetID), which is equal to @cite{1252} decimal, for
+The value @code{0809} (langID) is for the U.K English language and
+@code{04E4} (charsetID), which is equal to @code{1252} decimal, for
multilingual.
This section explains how to build, compile and use resources. Note that this
@end menu
@node Building Resources,Compiling Resources,,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{216}@anchor{gnat_ugn/platform_specific_information id34}@anchor{217}
+@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{218}@anchor{gnat_ugn/platform_specific_information id34}@anchor{219}
@subsubsection Building Resources
A resource file is an ASCII file. By convention resource files have an
@code{.rc} extension.
The easiest way to build a resource file is to use Microsoft tools
-such as @cite{imagedit.exe} to build bitmaps, icons and cursors and
-@cite{dlgedit.exe} to build dialogs.
+such as @code{imagedit.exe} to build bitmaps, icons and cursors and
+@code{dlgedit.exe} to build dialogs.
It is always possible to build an @code{.rc} file yourself by writing a
resource script.
Microsoft documentation.
@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{218}@anchor{gnat_ugn/platform_specific_information id35}@anchor{219}
+@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{21a}@anchor{gnat_ugn/platform_specific_information id35}@anchor{21b}
@subsubsection Compiling Resources
This section describes how to build a GNAT-compatible (COFF) object file
containing the resources. This is done using the Resource Compiler
-@cite{windres} as follows:
+@code{windres} as follows:
@quotation
@end example
@end quotation
-By default @cite{windres} will run @emph{gcc} to preprocess the @code{.rc}
+By default @code{windres} will run @code{gcc} to preprocess the @code{.rc}
file. You can specify an alternate preprocessor (usually named
-@code{cpp.exe}) using the @cite{windres} @emph{--preprocessor}
+@code{cpp.exe}) using the @code{windres} @code{--preprocessor}
parameter. A list of all possible options may be obtained by entering
-the command @cite{windres} @emph{--help}.
+the command @code{windres} @code{--help}.
-It is also possible to use the Microsoft resource compiler @cite{rc.exe}
+It is also possible to use the Microsoft resource compiler @code{rc.exe}
to produce a @code{.res} file (binary resource file). See the
corresponding Microsoft documentation for further details. In this case
-you need to use @cite{windres} to translate the @code{.res} file to a
+you need to use @code{windres} to translate the @code{.res} file to a
GNAT-compatible object file as follows:
@quotation
@end quotation
@node Using Resources,,Compiling Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information id36}@anchor{21a}@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{21b}
+@anchor{gnat_ugn/platform_specific_information id36}@anchor{21c}@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{21d}
@subsubsection Using Resources
To include the resource file in your program just add the
GNAT-compatible object file for the resource(s) to the linker
-arguments. With @emph{gnatmake} this is done by using the @emph{-largs}
+arguments. With @code{gnatmake} this is done by using the @code{-largs}
option:
@quotation
@end quotation
@node Using GNAT DLLs from Microsoft Visual Studio Applications,Debugging a DLL,GNAT and Windows Resources,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{21c}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{21d}
+@anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{21e}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{21f}
@subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications
@item
First develop and build the GNAT shared library using a library project
-(let's assume the project is @cite{mylib.gpr}, producing the library @cite{libmylib.dll}):
+(let's assume the project is @code{mylib.gpr}, producing the library @code{libmylib.dll}):
@end enumerate
@quotation
@item
Produce a .def file for the symbols you need to interface with, either by
hand or automatically with possibly some manual adjustments
-(see @ref{1fe,,Creating Definition File Automatically}):
+(see @ref{200,,Creating Definition File Automatically}):
@end enumerate
@quotation
Make sure that MSVS command-line tools are accessible on the path.
@item
-Create the Microsoft-style import library (see @ref{201,,MSVS-Style Import Library}):
+Create the Microsoft-style import library (see @ref{203,,MSVS-Style Import Library}):
@end enumerate
@quotation
@end enumerate
@node Debugging a DLL,Setting Stack Size from gnatlink,Using GNAT DLLs from Microsoft Visual Studio Applications,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id37}@anchor{21e}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{21f}
+@anchor{gnat_ugn/platform_specific_information id37}@anchor{220}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{221}
@subsubsection Debugging a DLL
@itemize *
@item
-The program and the DLL are built with @cite{GCC/GNAT}.
+The program and the DLL are built with GCC/GNAT.
@item
The program is built with foreign tools and the DLL is built with
-@cite{GCC/GNAT}.
+GCC/GNAT.
@item
-The program is built with @cite{GCC/GNAT} and the DLL is built with
+The program is built with GCC/GNAT and the DLL is built with
foreign tools.
@end itemize
In this section we address only cases one and two above.
There is no point in trying to debug
-a DLL with @cite{GNU/GDB}, if there is no GDB-compatible debugging
+a DLL with GNU/GDB, if there is no GDB-compatible debugging
information in it. To do so you must use a debugger compatible with the
tools suite used to build the DLL.
@end menu
@node Program and DLL Both Built with GCC/GNAT,Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Debugging a DLL
-@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{220}@anchor{gnat_ugn/platform_specific_information id38}@anchor{221}
+@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{222}@anchor{gnat_ugn/platform_specific_information id38}@anchor{223}
@subsubsection Program and DLL Both Built with GCC/GNAT
-This is the simplest case. Both the DLL and the program have @cite{GDB}
+This is the simplest case. Both the DLL and the program have @code{GDB}
compatible debugging information. It is then possible to break anywhere in
the process. Let's suppose here that the main procedure is named
-@cite{ada_main} and that in the DLL there is an entry point named
-@cite{ada_dll}.
+@code{ada_main} and that in the DLL there is an entry point named
+@code{ada_dll}.
-The DLL (@ref{1f7,,Introduction to Dynamic Link Libraries (DLLs)}) and
+The DLL (@ref{1f9,,Introduction to Dynamic Link Libraries (DLLs)}) and
program must have been built with the debugging information (see GNAT -g
switch). Here are the step-by-step instructions for debugging it:
@itemize *
@item
-Launch @cite{GDB} on the main program.
+Launch @code{GDB} on the main program.
@example
$ gdb -nw ada_main
(@ref{24,,Running and Debugging Ada Programs}).
@node Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Program and DLL Both Built with GCC/GNAT,Debugging a DLL
-@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{222}@anchor{gnat_ugn/platform_specific_information id39}@anchor{223}
+@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{224}@anchor{gnat_ugn/platform_specific_information id39}@anchor{225}
@subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT
In this case things are slightly more complex because it is not possible to
start the main program and then break at the beginning to load the DLL and the
associated DLL debugging information. It is not possible to break at the
-beginning of the program because there is no @cite{GDB} debugging information,
+beginning of the program because there is no @code{GDB} debugging information,
and therefore there is no direct way of getting initial control. This
section addresses this issue by describing some methods that can be used
to break somewhere in the DLL to debug it.
-First suppose that the main procedure is named @cite{main} (this is for
+First suppose that the main procedure is named @code{main} (this is for
example some C code built with Microsoft Visual C) and that there is a
-DLL named @cite{test.dll} containing an Ada entry point named
-@cite{ada_dll}.
+DLL named @code{test.dll} containing an Ada entry point named
+@code{ada_dll}.
-The DLL (see @ref{1f7,,Introduction to Dynamic Link Libraries (DLLs)}) must have
-been built with debugging information (see GNAT @cite{-g} option).
+The DLL (see @ref{1f9,,Introduction to Dynamic Link Libraries (DLLs)}) must have
+been built with debugging information (see the GNAT @code{-g} option).
@subsubheading Debugging the DLL Directly
@geindex DLL debugging
@geindex attach to process
-With @cite{GDB} it is always possible to debug a running process by
+With @code{GDB} it is always possible to debug a running process by
attaching to it. It is possible to debug a DLL this way. The limitation
of this approach is that the DLL must run long enough to perform the
attach operation. It may be useful for instance to insert a time wasting
@ref{24,,Running and Debugging Ada Programs}.
@node Setting Stack Size from gnatlink,Setting Heap Size from gnatlink,Debugging a DLL,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{136}@anchor{gnat_ugn/platform_specific_information id40}@anchor{224}
-@subsubsection Setting Stack Size from @emph{gnatlink}
+@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{136}@anchor{gnat_ugn/platform_specific_information id40}@anchor{226}
+@subsubsection Setting Stack Size from @code{gnatlink}
It is possible to specify the program stack size at link time. On modern
In particular, Stack Overflow checks are made against this
link-time specified size.
-This setting can be done with @emph{gnatlink} using either of the following:
+This setting can be done with @code{gnatlink} using either of the following:
@itemize *
@item
-@emph{-Xlinker} linker option
+@code{-Xlinker} linker option
@example
$ gnatlink hello -Xlinker --stack=0x10000,0x1000
size to 0x1000 bytes.
@item
-@emph{-Wl} linker option
+@code{-Wl} linker option
@example
$ gnatlink hello -Wl,--stack=0x1000000
@end example
This sets the stack reserve size to 0x1000000 bytes. Note that with
-@emph{-Wl} option it is not possible to set the stack commit size
+@code{-Wl} option it is not possible to set the stack commit size
because the comma is a separator for this option.
@end itemize
@node Setting Heap Size from gnatlink,,Setting Stack Size from gnatlink,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{137}@anchor{gnat_ugn/platform_specific_information id41}@anchor{225}
-@subsubsection Setting Heap Size from @emph{gnatlink}
+@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{137}@anchor{gnat_ugn/platform_specific_information id41}@anchor{227}
+@subsubsection Setting Heap Size from @code{gnatlink}
Under Windows systems, it is possible to specify the program heap size from
-@emph{gnatlink} using either of the following:
+@code{gnatlink} using either of the following:
@itemize *
@item
-@emph{-Xlinker} linker option
+@code{-Xlinker} linker option
@example
$ gnatlink hello -Xlinker --heap=0x10000,0x1000
size to 0x1000 bytes.
@item
-@emph{-Wl} linker option
+@code{-Wl} linker option
@example
$ gnatlink hello -Wl,--heap=0x1000000
@end example
This sets the heap reserve size to 0x1000000 bytes. Note that with
-@emph{-Wl} option it is not possible to set the heap commit size
+@code{-Wl} option it is not possible to set the heap commit size
because the comma is a separator for this option.
@end itemize
@node Windows Specific Add-Ons,,Mixed-Language Programming on Windows,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{226}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{227}
+@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{228}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{229}
@subsection Windows Specific Add-Ons
@end menu
@node Win32Ada,wPOSIX,,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{228}@anchor{gnat_ugn/platform_specific_information id42}@anchor{229}
+@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{22a}@anchor{gnat_ugn/platform_specific_information id42}@anchor{22b}
@subsubsection Win32Ada
@end quotation
@node wPOSIX,,Win32Ada,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information id43}@anchor{22a}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{22b}
+@anchor{gnat_ugn/platform_specific_information id43}@anchor{22c}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{22d}
@subsubsection wPOSIX
@end quotation
@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{2d}@anchor{gnat_ugn/platform_specific_information id44}@anchor{22c}
+@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{2d}@anchor{gnat_ugn/platform_specific_information id44}@anchor{22e}
@section Mac OS Topics
@end menu
@node Codesigning the Debugger,,,Mac OS Topics
-@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{22d}
+@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{22f}
@subsection Codesigning the Debugger
in the Unix group @code{_developer}.
@node Example of Binder Output File,Elaboration Order Handling in GNAT,Platform-Specific Information,Top
-@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{22e}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{22f}
+@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{230}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{231}
@chapter Example of Binder Output File
The Ada code in the above example is exactly what is generated by the
binder. We have added comments to more clearly indicate the function
-of each part of the generated @cite{Ada_Main} package.
+of each part of the generated @code{Ada_Main} package.
The code is standard Ada in all respects, and can be processed by any
tools that handle Ada. In particular, it is possible to use the debugger
-in Ada mode to debug the generated @cite{Ada_Main} package. For example,
+in Ada mode to debug the generated @code{Ada_Main} package. For example,
suppose that for reasons that you do not understand, your program is crashing
-during elaboration of the body of @cite{Ada.Text_IO}. To locate this bug,
+during elaboration of the body of @code{Ada.Text_IO}. To locate this bug,
you can place a breakpoint on the call:
@quotation
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
@node Elaboration Order Handling in GNAT,Inline Assembler,Example of Binder Output File,Top
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{230}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{231}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{232}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{233}
@chapter Elaboration Order Handling in GNAT
@end menu
@node Elaboration Code,Checking the Elaboration Order,,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{232}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{233}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{234}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{235}
@section Elaboration Code
@item
@emph{Package initialization code}
-Code in a @cite{BEGIN-END} section at the outer level of a package body is
+Code in a @code{begin} ... `@w{`} end`@w{`} section at the outer level of a package body is
executed as part of the package body elaboration code.
@item
have is a series of elaboration code sections, potentially one section
for each unit in the program. It is important that these execute
in the correct order. Correctness here means that, taking the above
-example of the declaration of @cite{Sqrt_Half},
+example of the declaration of @code{Sqrt_Half},
if some other piece of
-elaboration code references @cite{Sqrt_Half},
+elaboration code references @code{Sqrt_Half},
then it must run after the
section of elaboration code that contains the declaration of
-@cite{Sqrt_Half}.
+@code{Sqrt_Half}.
There would never be any order of elaboration problem if we made a rule
that whenever you @emph{with} a unit, you must elaborate both the spec and body
package Unit_2 is ...
@end example
-would require that both the body and spec of @cite{Unit_1} be elaborated
-before the spec of @cite{Unit_2}. However, a rule like that would be far too
+would require that both the body and spec of @code{Unit_1} be elaborated
+before the spec of @code{Unit_2}. However, a rule like that would be far too
restrictive. In particular, it would make it impossible to have routines
in separate packages that were mutually recursive.
but in the general case, this is not possible. Consider the following
example.
-In the body of @cite{Unit_1}, we have a procedure @cite{Func_1}
+In the body of @code{Unit_1}, we have a procedure @code{Func_1}
that references
-the variable @cite{Sqrt_1}, which is declared in the elaboration code
-of the body of @cite{Unit_1}:
+the variable @code{Sqrt_1}, which is declared in the elaboration code
+of the body of @code{Unit_1}:
@example
Sqrt_1 : Float := Sqrt (0.1);
@end example
-The elaboration code of the body of @cite{Unit_1} also contains:
+The elaboration code of the body of @code{Unit_1} also contains:
@example
if expression_1 = 1 then
end if;
@end example
-@cite{Unit_2} is exactly parallel,
-it has a procedure @cite{Func_2} that references
-the variable @cite{Sqrt_2}, which is declared in the elaboration code of
-the body @cite{Unit_2}:
+@code{Unit_2} is exactly parallel,
+it has a procedure @code{Func_2} that references
+the variable @code{Sqrt_2}, which is declared in the elaboration code of
+the body @code{Unit_2}:
@example
Sqrt_2 : Float := Sqrt (0.1);
@end example
-The elaboration code of the body of @cite{Unit_2} also contains:
+The elaboration code of the body of @code{Unit_2} also contains:
@example
if expression_2 = 2 then
If you carefully analyze the flow here, you will see that you cannot tell
at compile time the answer to this question.
-If @cite{expression_1} is not equal to 1,
-and @cite{expression_2} is not equal to 2,
+If @code{expression_1} is not equal to 1,
+and @code{expression_2} is not equal to 2,
then either order is acceptable, because neither of the function calls is
executed. If both tests evaluate to true, then neither order is acceptable
and in fact there is no correct order.
If one of the two expressions is true, and the other is false, then one
of the above orders is correct, and the other is incorrect. For example,
-if @cite{expression_1} /= 1 and @cite{expression_2} = 2,
-then the call to @cite{Func_1}
-will occur, but not the call to @cite{Func_2.}
+if @code{expression_1} /= 1 and @code{expression_2} = 2,
+then the call to @code{Func_1}
+will occur, but not the call to @code{Func_2.}
This means that it is essential
-to elaborate the body of @cite{Unit_1} before
-the body of @cite{Unit_2}, so the first
+to elaborate the body of @code{Unit_1} before
+the body of @code{Unit_2}, so the first
order of elaboration is correct and the second is wrong.
-By making @cite{expression_1} and @cite{expression_2}
+By making @code{expression_1} and @code{expression_2}
depend on input data, or perhaps
the time of day, we can make it impossible for the compiler or binder
to figure out which of these expressions will be true, and hence it
is impossible to guarantee a safe order of elaboration at run time.
@node Checking the Elaboration Order,Controlling the Elaboration Order,Elaboration Code,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{234}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{235}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{236}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{237}
@section Checking the Elaboration Order
Dynamic checks are made at run time, so that if some entity is accessed
before it is elaborated (typically by means of a subprogram call)
-then the exception (@cite{Program_Error}) is raised.
+then the exception (@code{Program_Error}) is raised.
@item
@emph{Elaboration control}
has been elaborated. The rules for elaboration given above guarantee
that the spec of the subprogram has been elaborated before the
call, but not the body. If this rule is violated, then the
-exception @cite{Program_Error} is raised.
+exception @code{Program_Error} is raised.
@item
@emph{Restrictions on instantiations}
unit has been elaborated. Again, the rules for elaboration given above
guarantee that the spec of the generic unit has been elaborated
before the instantiation, but not the body. If this rule is
-violated, then the exception @cite{Program_Error} is raised.
+violated, then the exception @code{Program_Error} is raised.
@end itemize
The idea is that if the body has been elaborated, then any variables
A Boolean variable is associated with each subprogram
and each generic unit. This variable is initialized to False, and is set to
True at the point body is elaborated. Every call or instantiation checks the
-variable, and raises @cite{Program_Error} if the variable is False.
+variable, and raises @code{Program_Error} if the variable is False.
Note that one might think that it would be good enough to have one Boolean
variable for each package, but that would not deal with cases of trying
to call a body in the same package as the call
that has not been elaborated yet.
Of course a compiler may be able to do enough analysis to optimize away
-some of the Boolean variables as unnecessary, and @cite{GNAT} indeed
+some of the Boolean variables as unnecessary, and GNAT indeed
does such optimizations, but still the easiest conceptual model is to
think of there being one variable per subprogram.
@node Controlling the Elaboration Order,Controlling Elaboration in GNAT - Internal Calls,Checking the Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{236}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order}@anchor{237}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{238}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order}@anchor{239}
@section Controlling the Elaboration Order
In the previous section we discussed the rules in Ada which ensure
-that @cite{Program_Error} is raised if an incorrect elaboration order is
+that @code{Program_Error} is raised if an incorrect elaboration order is
chosen. This prevents erroneous executions, but we need mechanisms to
specify a correct execution and avoid the exception altogether.
To achieve this, Ada provides a number of features for controlling
end Definitions;
@end example
-A package that @emph{with}s @cite{Definitions} may safely instantiate
-@cite{Definitions.Subp} because the compiler can determine that there
+A package that @emph{with}s @code{Definitions} may safely instantiate
+@code{Definitions.Subp} because the compiler can determine that there
definitely is no package body to worry about in this case
@end itemize
@emph{pragma Elaborate_Body}
This pragma requires that the body of a unit be elaborated immediately
-after its spec. Suppose a unit @cite{A} has such a pragma,
-and unit @cite{B} does
-a @emph{with} of unit @cite{A}. Recall that the standard rules require
-the spec of unit @cite{A}
+after its spec. Suppose a unit @code{A} has such a pragma,
+and unit @code{B} does
+a @emph{with} of unit @code{A}. Recall that the standard rules require
+the spec of unit @code{A}
to be elaborated before the @emph{with}ing unit; given the pragma in
-@cite{A}, we also know that the body of @cite{A}
-will be elaborated before @cite{B}, so
-that calls to @cite{A} are safe and do not need a check.
+@code{A}, we also know that the body of @code{A}
+will be elaborated before @code{B}, so
+that calls to @code{A} are safe and do not need a check.
-Note that, unlike pragma @cite{Pure} and pragma @cite{Preelaborate},
-the use of @cite{Elaborate_Body} does not guarantee that the program is
+Note that, unlike pragma @code{Pure} and pragma @code{Preelaborate},
+the use of @code{Elaborate_Body} does not guarantee that the program is
free of elaboration problems, because it may not be possible
to satisfy the requested elaboration order.
-Let's go back to the example with @cite{Unit_1} and @cite{Unit_2}.
-If a programmer marks @cite{Unit_1} as @cite{Elaborate_Body},
-and not @cite{Unit_2@comma{}} then the order of
+Let's go back to the example with @code{Unit_1} and @code{Unit_2}.
+If a programmer marks @code{Unit_1} as @code{Elaborate_Body},
+and not @code{Unit_2,} then the order of
elaboration will be:
@example
Body of Unit_2
@end example
-Now that means that the call to @cite{Func_1} in @cite{Unit_2}
+Now that means that the call to @code{Func_1} in @code{Unit_2}
need not be checked,
-it must be safe. But the call to @cite{Func_2} in
-@cite{Unit_1} may still fail if
-@cite{Expression_1} is equal to 1,
+it must be safe. But the call to @code{Func_2} in
+@code{Unit_1} may still fail if
+@code{Expression_1} is equal to 1,
and the programmer must still take
responsibility for this not being the case.
-If all units carry a pragma @cite{Elaborate_Body}, then all problems are
+If all units carry a pragma @code{Elaborate_Body}, then all problems are
eliminated, except for calls entirely within a body, which are
in any case fully under programmer control. However, using the pragma
everywhere is not always possible.
-In particular, for our @cite{Unit_1}/@cite{Unit_2} example, if
-we marked both of them as having pragma @cite{Elaborate_Body}, then
+In particular, for our @code{Unit_1}/@cite{Unit_2} example, if
+we marked both of them as having pragma @code{Elaborate_Body}, then
clearly there would be no possible elaboration order.
@end itemize
The above pragmas allow a server to guarantee safe use by clients, and
clearly this is the preferable approach. Consequently a good rule
-is to mark units as @cite{Pure} or @cite{Preelaborate} if possible,
+is to mark units as @code{Pure} or @code{Preelaborate} if possible,
and if this is not possible,
-mark them as @cite{Elaborate_Body} if possible.
+mark them as @code{Elaborate_Body} if possible.
As we have seen, there are situations where neither of these
three pragmas can be used.
So we also provide methods for clients to control the
Unit B |withs| unit C, and B.Func calls C.Func
@end example
-Now if we put a pragma @cite{Elaborate (B)}
-in unit @cite{A}, this ensures that the
-body of @cite{B} is elaborated before the call, but not the
-body of @cite{C}, so
-the call to @cite{C.Func} could still cause @cite{Program_Error} to
+Now if we put a pragma @code{Elaborate (B)}
+in unit @code{A}, this ensures that the
+body of @code{B} is elaborated before the call, but not the
+body of @code{C}, so
+the call to @code{C.Func} could still cause @code{Program_Error} to
be raised.
-The effect of a pragma @cite{Elaborate_All} is stronger, it requires
+The effect of a pragma @code{Elaborate_All} is stronger, it requires
not only that the body of the named unit be elaborated before the
unit doing the @emph{with}, but also the bodies of all units that the
named unit uses, following @emph{with} links transitively. For example,
-if we put a pragma @cite{Elaborate_All (B)} in unit @cite{A},
-then it requires not only that the body of @cite{B} be elaborated before @cite{A},
-but also the body of @cite{C}, because @cite{B} @emph{with}s @cite{C}.
+if we put a pragma @code{Elaborate_All (B)} in unit @code{A},
+then it requires not only that the body of @code{B} be elaborated before @code{A},
+but also the body of @code{C}, because @code{B} @emph{with}s @code{C}.
@end itemize
We are now in a position to give a usage rule in Ada for avoiding
indirectly make a call to a subprogram in a |withed| unit, or instantiate
a generic package in a |withed| unit,
then if the |withed| unit does not have
-pragma `Pure` or `Preelaborate`, then the client should have
-a pragma `Elaborate_All`for the |withed| unit.*}
+pragma `@w{`}Pure`@w{`} or `@w{`}Preelaborate`@w{`}, then the client should have
+a pragma `@w{`}Elaborate_All`@w{`}for the |withed| unit.*}
By following this rule a client is
assured that calls can be made without risk of an exception.
For generic subprogram instantiations, the rule can be relaxed to
-require only a pragma @cite{Elaborate} since elaborating the body
+require only a pragma @code{Elaborate} since elaborating the body
of a subprogram cannot cause any transitive elaboration (we are
not calling the subprogram in this case, just elaborating its
declaration).
@emph{No order exists}
No order of elaboration exists which follows the rules, taking into
-account any @cite{Elaborate}, @cite{Elaborate_All},
-or @cite{Elaborate_Body} pragmas. In
+account any @code{Elaborate}, @code{Elaborate_All},
+or @code{Elaborate_Body} pragmas. In
this case, an Ada compiler must diagnose the situation at bind
time, and refuse to build an executable program.
One or more acceptable elaboration orders exist, and all of them
generate an elaboration order problem. In this case, the binder
-can build an executable program, but @cite{Program_Error} will be raised
+can build an executable program, but @code{Program_Error} will be raised
when the program is run.
@item
@end itemize
Note that one additional advantage of following our rules on the use
-of @cite{Elaborate} and @cite{Elaborate_All}
+of @code{Elaborate} and @code{Elaborate_All}
is that the program continues to stay in the ideal (all orders OK) state
even if maintenance
changes some bodies of some units. Conversely, if a program that does
may deteriorate silently as a result of maintenance changes.
You may have noticed that the above discussion did not mention
-the use of @cite{Elaborate_Body}. This was a deliberate omission. If you
-@emph{with} an @cite{Elaborate_Body} unit, it still may be the case that
+the use of @code{Elaborate_Body}. This was a deliberate omission. If you
+@emph{with} an @code{Elaborate_Body} unit, it still may be the case that
code in the body makes calls to some other unit, so it is still necessary
-to use @cite{Elaborate_All} on such units.
+to use @code{Elaborate_All} on such units.
@node Controlling Elaboration in GNAT - Internal Calls,Controlling Elaboration in GNAT - External Calls,Controlling the Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{238}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-elaboration-in-gnat-internal-calls}@anchor{239}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{23a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-elaboration-in-gnat-internal-calls}@anchor{23b}
@section Controlling Elaboration in GNAT - Internal Calls
end One;
@end example
-will obviously raise @cite{Program_Error} at run time, because function
+will obviously raise @code{Program_Error} at run time, because function
One will be called before its body is elaborated. In this case GNAT will
-generate a warning that the call will raise @cite{Program_Error}:
+generate a warning that the call will raise @code{Program_Error}:
@example
1. procedure y is
@end example
Note that in this particular case, it is likely that the call is safe, because
-the function @cite{One} does not access any global variables.
+the function @code{One} does not access any global variables.
Nevertheless in Ada, we do not want the validity of the check to depend on
the contents of the body (think about the separate compilation case), so this
is still wrong, as we discussed in the previous sections.
The error is easily corrected by rearranging the declarations so that the
-body of @cite{One} appears before the declaration containing the call
+body of @code{One} appears before the declaration containing the call
(note that in Ada 95 as well as later versions of the Ada standard,
declarations can appear in any order, so there is no restriction that
would prevent this reordering, and if we write:
@end example
then all is well, no warning is generated, and no
-@cite{Program_Error} exception
+@code{Program_Error} exception
will be raised.
Things are more complicated when a chain of subprograms is executed:
function A return Integer is begin return 1; end;
@end example
-Now the call to @cite{C}
-at elaboration time in the declaration of @cite{X} is correct, because
-the body of @cite{C} is already elaborated,
-and the call to @cite{B} within the body of
-@cite{C} is correct, but the call
-to @cite{A} within the body of @cite{B} is incorrect, because the body
-of @cite{A} has not been elaborated, so @cite{Program_Error}
-will be raised on the call to @cite{A}.
+Now the call to @code{C}
+at elaboration time in the declaration of @code{X} is correct, because
+the body of @code{C} is already elaborated,
+and the call to @code{B} within the body of
+@code{C} is correct, but the call
+to @code{A} within the body of @code{B} is incorrect, because the body
+of @code{A} has not been elaborated, so @code{Program_Error}
+will be raised on the call to @code{A}.
In this case GNAT will generate a
-warning that @cite{Program_Error} may be
+warning that @code{Program_Error} may be
raised at the point of the call. Let's look at the warning:
@example
Note that the message here says 'may raise', instead of the direct case,
where the message says 'will be raised'. That's because whether
-@cite{A} is
+@code{A} is
actually called depends in general on run-time flow of control.
-For example, if the body of @cite{B} said
+For example, if the body of @code{B} said
@example
function B return Integer is
@end example
then we could not know until run time whether the incorrect call to A would
-actually occur, so @cite{Program_Error} might
+actually occur, so @code{Program_Error} might
or might not be raised. It is possible for a compiler to
do a better job of analyzing bodies, to
-determine whether or not @cite{Program_Error}
+determine whether or not @code{Program_Error}
might be raised, but it certainly
couldn't do a perfect job (that would require solving the halting problem
and is provably impossible), and because this is a warning anyway, it does
@itemize *
@item
-Compile with the @emph{-gnatws} switch set
+Compile with the @code{-gnatws} switch set
@item
-Suppress @cite{Elaboration_Check} for the called subprogram
+Suppress @code{Elaboration_Check} for the called subprogram
@item
-Use pragma @cite{Warnings_Off} to turn warnings off for the call
+Use pragma @code{Warnings_Off} to turn warnings off for the call
@end itemize
For the internal elaboration check case,
GNAT by default generates the
necessary run-time checks to ensure
-that @cite{Program_Error} is raised if any
+that @code{Program_Error} is raised if any
call fails an elaboration check. Of course this can only happen if a
warning has been issued as described above. The use of pragma
-@cite{Suppress (Elaboration_Check)} may (but is not guaranteed to) suppress
+@code{Suppress (Elaboration_Check)} may (but is not guaranteed to) suppress
some of these checks, meaning that it may be possible (but is not
guaranteed) for a program to be able to call a subprogram whose body
-is not yet elaborated, without raising a @cite{Program_Error} exception.
+is not yet elaborated, without raising a @code{Program_Error} exception.
@node Controlling Elaboration in GNAT - External Calls,Default Behavior in GNAT - Ensuring Safety,Controlling Elaboration in GNAT - Internal Calls,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{23a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-elaboration-in-gnat-external-calls}@anchor{23b}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{23c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-elaboration-in-gnat-external-calls}@anchor{23d}
@section Controlling Elaboration in GNAT - External Calls
end Main;
@end example
-where @cite{Main} is the main program. When this program is executed, the
+where @code{Main} is the main program. When this program is executed, the
elaboration code must first be executed, and one of the jobs of the
binder is to determine the order in which the units of a program are
to be elaborated. In this case we have four units: the spec and body
-of @cite{Math},
-the spec of @cite{Stuff} and the body of @cite{Main}).
+of @code{Math},
+the spec of @code{Stuff} and the body of @code{Main}).
In what order should the four separate sections of elaboration code
be executed?
There are some restrictions in the order of elaboration that the binder
can choose. In particular, if unit U has a @emph{with}
-for a package @cite{X}, then you
-are assured that the spec of @cite{X}
+for a package @code{X}, then you
+are assured that the spec of @code{X}
is elaborated before U , but you are
-not assured that the body of @cite{X}
+not assured that the body of @code{X}
is elaborated before U.
This means that in the above case, the binder is allowed to choose the
order:
body of Main
@end example
-but that's not good, because now the call to @cite{Math.Sqrt}
+but that's not good, because now the call to @code{Math.Sqrt}
that happens during
-the elaboration of the @cite{Stuff}
-spec happens before the body of @cite{Math.Sqrt} is
-elaborated, and hence causes @cite{Program_Error} exception to be raised.
+the elaboration of the @code{Stuff}
+spec happens before the body of @code{Math.Sqrt} is
+elaborated, and hence causes @code{Program_Error} exception to be raised.
At first glance, one might say that the binder is misbehaving, because
obviously you want to elaborate the body of something you @emph{with} first, but
that is not a general rule that can be followed in all cases. Consider
problems that might arise in connection with elaboration code, this works fine.
A rule that says that you must first elaborate the body of anything you
@emph{with} cannot work in this case:
-the body of @cite{X} @emph{with}s @cite{Y},
+the body of @code{X} @emph{with}s @code{Y},
which means you would have to
-elaborate the body of @cite{Y} first, but that @emph{with}s @cite{X},
+elaborate the body of @code{Y} first, but that @emph{with}s @code{X},
which means
-you have to elaborate the body of @cite{X} first, but ... and we have a
+you have to elaborate the body of @code{X} first, but ... and we have a
loop that cannot be broken.
It is true that the binder can in many cases guess an order of elaboration
-that is unlikely to cause a @cite{Program_Error}
+that is unlikely to cause a @code{Program_Error}
exception to be raised, and it tries to do so (in the
-above example of @cite{Math/Stuff/Spec}, the GNAT binder will
+above example of @code{Math/Stuff/Spec}, the GNAT binder will
by default
-elaborate the body of @cite{Math} right after its spec, so all will be well).
+elaborate the body of @code{Math} right after its spec, so all will be well).
However, a program that blindly relies on the binder to be helpful can
get into trouble, as we discussed in the previous sections, so GNAT
developing programs that are robust with respect to elaboration order.
@node Default Behavior in GNAT - Ensuring Safety,Treatment of Pragma Elaborate,Controlling Elaboration in GNAT - External Calls,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{23c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat default-behavior-in-gnat-ensuring-safety}@anchor{23d}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{23e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat default-behavior-in-gnat-ensuring-safety}@anchor{23f}
@section Default Behavior in GNAT - Ensuring Safety
@emph{If a unit has elaboration code that can directly or indirectly make a
call to a subprogram in a |withed| unit, or instantiate a generic
package in a |withed| unit, then if the |withed| unit
-does not have pragma `Pure` or `Preelaborate`, then the client should have an
-`Elaborate_All` pragma for the |withed| unit.}
+does not have pragma `@w{`}Pure`@w{`} or `@w{`}Preelaborate`@w{`}, then the client should have an
+`@w{`}Elaborate_All`@w{`} pragma for the |withed| unit.}
@emph{In the case of instantiating a generic subprogram, it is always
-sufficient to have only an `Elaborate` pragma for the
+sufficient to have only an `@w{`}Elaborate`@w{`} pragma for the
|withed| unit.}
By following this rule a client is assured that calls and instantiations
can be made without risk of an exception.
In this mode GNAT traces all calls that are potentially made from
-elaboration code, and puts in any missing implicit @cite{Elaborate}
-and @cite{Elaborate_All} pragmas.
+elaboration code, and puts in any missing implicit @code{Elaborate}
+and @code{Elaborate_All} pragmas.
The advantage of this approach is that no elaboration problems
are possible if the binder can find an elaboration order that is
-consistent with these implicit @cite{Elaborate} and
-@cite{Elaborate_All} pragmas. The
+consistent with these implicit @code{Elaborate} and
+@code{Elaborate_All} pragmas. The
disadvantage of this approach is that no such order may exist.
If the binder does not generate any diagnostics, then it means that it has
found an elaboration order that is guaranteed to be safe. However, the binder
-may still be relying on implicitly generated @cite{Elaborate} and
-@cite{Elaborate_All} pragmas so portability to other compilers than GNAT is not
+may still be relying on implicitly generated @code{Elaborate} and
+@code{Elaborate_All} pragmas so portability to other compilers than GNAT is not
guaranteed.
If it is important to guarantee portability, then the compilations should
-use the @emph{-gnatel}
+use the @code{-gnatel}
(info messages for elaboration pragmas) switch. This will cause info messages
-to be generated indicating the missing @cite{Elaborate} and
-@cite{Elaborate_All} pragmas.
+to be generated indicating the missing @code{Elaborate} and
+@code{Elaborate_All} pragmas.
Consider the following source program:
@example
@end example
where it is clear that there
-should be a pragma @cite{Elaborate_All}
-for unit @cite{k}. An implicit pragma will be generated, and it is
+should be a pragma @code{Elaborate_All}
+for unit @code{k}. An implicit pragma will be generated, and it is
likely that the binder will be able to honor it. However, if you want
to port this program to some other Ada compiler than GNAT.
it is safer to include the pragma explicitly in the source. If this
-unit is compiled with the @emph{-gnatel}
+unit is compiled with the @code{-gnatel}
switch, then the compiler outputs an information message:
@example
the missing pragmas. It is usually a bad idea to use this
option during development. That's because it will tell you when
you need to put in a pragma, but cannot tell you when it is time
-to take it out. So the use of pragma @cite{Elaborate_All} may lead to
+to take it out. So the use of pragma @code{Elaborate_All} may lead to
unnecessary dependencies and even false circularities.
This default mode is more restrictive than the Ada Reference
standard dynamic model of elaboration with run-time checks.
In GNAT, this standard mode can be achieved either by the use of
-the @emph{-gnatE} switch on the compiler (@emph{gcc} or
-@emph{gnatmake}) command, or by the use of the configuration pragma:
+the @code{-gnatE} switch on the compiler (@code{gcc} or
+@code{gnatmake}) command, or by the use of the configuration pragma:
@example
pragma Elaboration_Checks (DYNAMIC);
run-time checks. However, in the case of legacy code, it may be
difficult to meet the requirements of the static model. This
issue is further discussed in
-@ref{23e,,What to Do If the Default Elaboration Behavior Fails}.
+@ref{240,,What to Do If the Default Elaboration Behavior Fails}.
Note that the static model provides a strict subset of the allowed
behavior and programs of the Ada Reference Manual, so if you do
pragma Elaborate statements from the source.
@node Treatment of Pragma Elaborate,Elaboration Issues for Library Tasks,Default Behavior in GNAT - Ensuring Safety,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat treatment-of-pragma-elaborate}@anchor{23f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{240}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat treatment-of-pragma-elaborate}@anchor{241}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{242}
@section Treatment of Pragma Elaborate
@geindex Pragma Elaborate
-The use of @cite{pragma Elaborate}
+The use of @code{pragma Elaborate}
should generally be avoided in Ada 95 and Ada 2005 programs,
since there is no guarantee that transitive calls
will be properly handled. Indeed at one point, this pragma was placed
in Annex J (Obsolescent Features), on the grounds that it is never useful.
Now that's a bit restrictive. In practice, the case in which
-@cite{pragma Elaborate} is useful is when the caller knows that there
+@code{pragma Elaborate} is useful is when the caller knows that there
are no transitive calls, or that the called unit contains all necessary
-transitive @cite{pragma Elaborate} statements, and legacy code often
+transitive @code{pragma Elaborate} statements, and legacy code often
contains such uses.
Strictly speaking the static mode in GNAT should ignore such pragmas,
since there is no assurance at compile time that the necessary safety
conditions are met. In practice, this would cause GNAT to be incompatible
with correctly written Ada 83 code that had all necessary
-@cite{pragma Elaborate} statements in place. Consequently, we made the
+@code{pragma Elaborate} statements in place. Consequently, we made the
decision that GNAT in its default mode will believe that if it encounters
-a @cite{pragma Elaborate} then the programmer knows what they are doing,
+a @code{pragma Elaborate} then the programmer knows what they are doing,
and it will trust that no elaboration errors can occur.
The result of this decision is two-fold. First to be safe using the
-static mode, you should remove all @cite{pragma Elaborate} statements.
+static mode, you should remove all @code{pragma Elaborate} statements.
Second, when fixing circularities in existing code, you can selectively
-use @cite{pragma Elaborate} statements to convince the static mode of
-GNAT that it need not generate an implicit @cite{pragma Elaborate_All}
+use @code{pragma Elaborate} statements to convince the static mode of
+GNAT that it need not generate an implicit @code{pragma Elaborate_All}
statement.
-When using the static mode with @emph{-gnatwl}, any use of
-@cite{pragma Elaborate} will generate a warning about possible
+When using the static mode with @code{-gnatwl}, any use of
+@code{pragma Elaborate} will generate a warning about possible
problems.
@node Elaboration Issues for Library Tasks,Mixing Elaboration Models,Treatment of Pragma Elaborate,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-issues-for-library-tasks}@anchor{241}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{242}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-issues-for-library-tasks}@anchor{243}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{244}
@section Elaboration Issues for Library Tasks
If the above example is compiled in the default static elaboration
mode, then a circularity occurs. The circularity comes from the call
-@cite{Utils.Put_Val} in the task body of @cite{Decls.Lib_Task}. Since
+@code{Utils.Put_Val} in the task body of @code{Decls.Lib_Task}. Since
this call occurs in elaboration code, we need an implicit pragma
-@cite{Elaborate_All} for @cite{Utils}. This means that not only must
-the spec and body of @cite{Utils} be elaborated before the body
-of @cite{Decls}, but also the spec and body of any unit that is
-@emph{with}ed by the body of @cite{Utils} must also be elaborated before
-the body of @cite{Decls}. This is the transitive implication of
-pragma @cite{Elaborate_All} and it makes sense, because in general
-the body of @cite{Put_Val} might have a call to something in a
+@code{Elaborate_All} for @code{Utils}. This means that not only must
+the spec and body of @code{Utils} be elaborated before the body
+of @code{Decls}, but also the spec and body of any unit that is
+@emph{with}ed by the body of @code{Utils} must also be elaborated before
+the body of @code{Decls}. This is the transitive implication of
+pragma @code{Elaborate_All} and it makes sense, because in general
+the body of @code{Put_Val} might have a call to something in a
@emph{with}ed unit.
In this case, the body of Utils (actually its spec) @emph{with}s
-@cite{Decls}. Unfortunately this means that the body of @cite{Decls}
+@code{Decls}. Unfortunately this means that the body of @code{Decls}
must be elaborated before itself, in case there is a call from the
-body of @cite{Utils}.
+body of @code{Utils}.
Here is the exact chain of events we are worrying about:
@itemize *
@item
-In the body of @cite{Decls} a call is made from within the body of a library
-task to a subprogram in the package @cite{Utils}. Since this call may
+In the body of @code{Decls} a call is made from within the body of a library
+task to a subprogram in the package @code{Utils}. Since this call may
occur at elaboration time (given that the task is activated at elaboration
time), we have to assume the worst, i.e., that the
call does happen at elaboration time.
@item
-This means that the body and spec of @cite{Util} must be elaborated before
-the body of @cite{Decls} so that this call does not cause an access before
+This means that the body and spec of @code{Util} must be elaborated before
+the body of @code{Decls} so that this call does not cause an access before
elaboration.
@item
-Within the body of @cite{Util}, specifically within the body of
-@cite{Util.Put_Val} there may be calls to any unit @emph{with}ed
+Within the body of @code{Util}, specifically within the body of
+@code{Util.Put_Val} there may be calls to any unit @emph{with}ed
by this package.
@item
-One such @emph{with}ed package is package @cite{Decls}, so there
-might be a call to a subprogram in @cite{Decls} in @cite{Put_Val}.
+One such @emph{with}ed package is package @code{Decls}, so there
+might be a call to a subprogram in @code{Decls} in @code{Put_Val}.
In fact there is such a call in this example, but we would have to
assume that there was such a call even if it were not there, since
-we are not supposed to write the body of @cite{Decls} knowing what
-is in the body of @cite{Utils}; certainly in the case of the
+we are not supposed to write the body of @code{Decls} knowing what
+is in the body of @code{Utils}; certainly in the case of the
static elaboration model, the compiler does not know what is in
other bodies and must assume the worst.
@item
-This means that the spec and body of @cite{Decls} must also be
+This means that the spec and body of @code{Decls} must also be
elaborated before we elaborate the unit containing the call, but
-that unit is @cite{Decls}! This means that the body of @cite{Decls}
+that unit is @code{Decls}! This means that the body of @code{Decls}
must be elaborated before itself, and that's a circularity.
@end itemize
-Indeed, if you add an explicit pragma @cite{Elaborate_All} for @cite{Utils} in
-the body of @cite{Decls} you will get a true Ada Reference Manual
+Indeed, if you add an explicit pragma @code{Elaborate_All} for @code{Utils} in
+the body of @code{Decls} you will get a true Ada Reference Manual
circularity that makes the program illegal.
In practice, we have found that problems with the static model of
we must address this particular situation.
Note that if we compile and run the program above, using the dynamic model of
-elaboration (that is to say use the @emph{-gnatE} switch),
+elaboration (that is to say use the @code{-gnatE} switch),
then it compiles, binds,
links, and runs, printing the expected result of 2. Therefore in some sense
the circularity here is only apparent, and we need to capture
@item
Use the dynamic model of elaboration.
-If we use the @emph{-gnatE} switch, then as noted above, the program works.
+If we use the @code{-gnatE} switch, then as noted above, the program works.
Why is this? If we examine the task body, it is apparent that the task cannot
proceed past the
-@cite{accept} statement until after elaboration has been completed, because
+@code{accept} statement until after elaboration has been completed, because
the corresponding entry call comes from the main program, not earlier.
This is why the dynamic model works here. But that's really giving
up on a precise analysis, and we prefer to take this approach only if we cannot
end;
@end example
-All we have done is to split @cite{Decls} into two packages, one
+All we have done is to split @code{Decls} into two packages, one
containing the library task, and one containing everything else. Now
there is no cycle, and the program compiles, binds, links and executes
using the default static model of elaboration.
end;
@end example
-What we have done here is to replace the @cite{task} declaration in
-package @cite{Decls} with a @cite{task type} declaration. Then we
-introduce a separate package @cite{Declst} to contain the actual
+What we have done here is to replace the @code{task} declaration in
+package @code{Decls} with a @code{task type} declaration. Then we
+introduce a separate package @code{Declst} to contain the actual
task object. This separates the elaboration issues for
-the @cite{task type}
+the @code{task type}
declaration, which causes no trouble, from the elaboration issues
of the task object, which is also unproblematic, since it is now independent
-of the elaboration of @cite{Utils}.
+of the elaboration of @code{Utils}.
This separation of concerns also corresponds to
a generally sound engineering principle of separating declarations
from instances. This version of the program also compiles, binds, links,
Let us consider more carefully why our original sample program works
under the dynamic model of elaboration. The reason is that the code
-in the task body blocks immediately on the @cite{accept}
+in the task body blocks immediately on the @code{accept}
statement. Now of course there is nothing to prohibit elaboration
code from making entry calls (for example from another library level task),
so we cannot tell in isolation that
However, in practice it is very unusual to see elaboration code
make any entry calls, and the pattern of tasks starting
-at elaboration time and then immediately blocking on @cite{accept} or
-@cite{select} statements is very common. What this means is that
+at elaboration time and then immediately blocking on @code{accept} or
+@code{select} statements is very common. What this means is that
the compiler is being too pessimistic when it analyzes the
whole package body as though it might be executed at elaboration
time.
in the presence of a @code{gnat.adc} containing the above pragma,
then once again, we can compile, bind, link, and execute, obtaining
the expected result. In the presence of this pragma, the compiler does
-not trace calls in a task body, that appear after the first @cite{accept}
-or @cite{select} statement, and therefore does not report a potential
+not trace calls in a task body, that appear after the first @code{accept}
+or @code{select} statement, and therefore does not report a potential
circularity in the original program.
The compiler will check to the extent it can that the above
@end itemize
@node Mixing Elaboration Models,What to Do If the Default Elaboration Behavior Fails,Elaboration Issues for Library Tasks,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{243}@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{244}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{245}@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{246}
@section Mixing Elaboration Models
be |withed| by a unit compiled with the dynamic model}.
The reason for this is that in the static model, a unit assumes that
its clients guarantee to use (the equivalent of) pragma
-@cite{Elaborate_All} so that no elaboration checks are required
+@code{Elaborate_All} so that no elaboration checks are required
in inner subprograms, and this assumption is violated if the
client is compiled with dynamic checks.
@item
The @emph{with}ed unit is itself compiled with dynamic elaboration
-checks (that is with the @emph{-gnatE} switch.
+checks (that is with the @code{-gnatE} switch.
@item
The @emph{with}ed unit is an internal GNAT implementation unit from
@item
The @emph{with}ing unit (that is the client) has an explicit pragma
-@cite{Elaborate_All} for the @emph{with}ed unit.
+@code{Elaborate_All} for the @emph{with}ed unit.
@end itemize
If this rule is violated, that is if a unit with dynamic elaboration
checks @emph{with}s a unit that does not meet one of the above four
-criteria, then the binder (@cite{gnatbind}) will issue a warning
+criteria, then the binder (@code{gnatbind}) will issue a warning
similar to that in the following example:
@example
These warnings indicate that the rule has been violated, and that as a result
elaboration checks may be missed in the resulting executable file.
-This warning may be suppressed using the @emph{-ws} binder switch
+This warning may be suppressed using the @code{-ws} binder switch
in the usual manner.
One useful application of this mixing rule is in the case of a subsystem
using the more reliable default static model.
@node What to Do If the Default Elaboration Behavior Fails,Elaboration for Indirect Calls,Mixing Elaboration Models,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{245}@anchor{gnat_ugn/elaboration_order_handling_in_gnat what-to-do-if-the-default-elaboration-behavior-fails}@anchor{23e}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{247}@anchor{gnat_ugn/elaboration_order_handling_in_gnat what-to-do-if-the-default-elaboration-behavior-fails}@anchor{240}
@section What to Do If the Default Elaboration Behavior Fails
@end example
In this case we have a cycle that the binder cannot break. On the one
-hand, there is an explicit pragma Elaborate in @cite{proc} for
-@cite{pack}. This means that the body of @cite{pack} must be elaborated
-before the body of @cite{proc}. On the other hand, there is elaboration
-code in @cite{pack} that calls a subprogram in @cite{proc}. This means
+hand, there is an explicit pragma Elaborate in @code{proc} for
+@code{pack}. This means that the body of @code{pack} must be elaborated
+before the body of @code{proc}. On the other hand, there is elaboration
+code in @code{pack} that calls a subprogram in @code{proc}. This means
that for maximum safety, there should really be a pragma
-Elaborate_All in @cite{pack} for @cite{proc} which would require that
-the body of @cite{proc} be elaborated before the body of
-@cite{pack}. Clearly both requirements cannot be satisfied.
+Elaborate_All in @code{pack} for @code{proc} which would require that
+the body of @code{proc} be elaborated before the body of
+@code{pack}. Clearly both requirements cannot be satisfied.
Faced with a circularity of this kind, you have three different options.
@item
@emph{Perform dynamic checks}
-If the compilations are done using the @emph{-gnatE}
+If the compilations are done using the @code{-gnatE}
(dynamic elaboration check) switch, then GNAT behaves in a quite different
manner. Dynamic checks are generated for all calls that could possibly result
in raising an exception. With this switch, the compiler does not generate
-implicit @cite{Elaborate} or @cite{Elaborate_All} pragmas. The behavior then is
+implicit @code{Elaborate} or @code{Elaborate_All} pragmas. The behavior then is
exactly as specified in the @cite{Ada Reference Manual}.
The binder will generate
-an executable program that may or may not raise @cite{Program_Error}, and then
+an executable program that may or may not raise @code{Program_Error}, and then
it is the programmer's job to ensure that it does not raise an exception. Note
that it is important to compile all units with the switch, it cannot be used
selectively.
are absolutely sure that your program cannot raise any elaboration
exceptions, and you still want to use the dynamic elaboration model,
then you can use the configuration pragma
-@cite{Suppress (Elaboration_Check)} to suppress all such checks. For
+@code{Suppress (Elaboration_Check)} to suppress all such checks. For
example this pragma could be placed in the @code{gnat.adc} file.
@item
When you know that certain calls or instantiations in elaboration code cannot
possibly lead to an elaboration error, and the binder nevertheless complains
-about implicit @cite{Elaborate} and @cite{Elaborate_All} pragmas that lead to
+about implicit @code{Elaborate} and @code{Elaborate_All} pragmas that lead to
elaboration circularities, it is possible to remove those warnings locally and
obtain a program that will bind. Clearly this can be unsafe, and it is the
responsibility of the programmer to make sure that the resulting program has no
-elaboration anomalies. The pragma @cite{Suppress (Elaboration_Check)} can be
+elaboration anomalies. The pragma @code{Suppress (Elaboration_Check)} can be
used with different granularity to suppress warnings and break elaboration
circularities:
@item
Use Pragma Elaborate.
-As previously described in section @ref{23f,,Treatment of Pragma Elaborate},
-GNAT in static mode assumes that a @cite{pragma} Elaborate indicates correctly
+As previously described in section @ref{241,,Treatment of Pragma Elaborate},
+GNAT in static mode assumes that a @code{pragma} Elaborate indicates correctly
that no elaboration checks are required on calls to the designated unit.
There may be cases in which the caller knows that no transitive calls
-can occur, so that a @cite{pragma Elaborate} will be sufficient in a
-case where @cite{pragma Elaborate_All} would cause a circularity.
+can occur, so that a @code{pragma Elaborate} will be sufficient in a
+case where @code{pragma Elaborate_All} would cause a circularity.
@end itemize
These five cases are listed in order of decreasing safety, and therefore
info: "pack1 (body)"
@end example
-The sources of the circularity are the two calls to @cite{Pack2.Pure} and
-@cite{Pack2.F2} in the body of @cite{Pack1}. We can see that the call to
+The sources of the circularity are the two calls to @code{Pack2.Pure} and
+@code{Pack2.F2} in the body of @code{Pack1}. We can see that the call to
F2 is safe, even though F2 calls F1, because the call appears after the
elaboration of the body of F1. Therefore the pragma (1) is safe, and will
remove the warning on the call. It is also possible to use pragma (2)
because there are no other potentially unsafe calls in the block.
-The call to @cite{Pure} is safe because this function does not depend on the
-state of @cite{Pack2}. Therefore any call to this function is safe, and it
+The call to @code{Pure} is safe because this function does not depend on the
+state of @code{Pack2}. Therefore any call to this function is safe, and it
is correct to place pragma (3) in the corresponding package spec.
-Finally, we could place pragma (4) in the spec of @cite{Pack2} to disable
+Finally, we could place pragma (4) in the spec of @code{Pack2} to disable
warnings on all calls to functions declared therein. Note that this is not
necessarily safe, and requires more detailed examination of the subprogram
-bodies involved. In particular, a call to @cite{F2} requires that @cite{F1}
+bodies involved. In particular, a call to @code{F2} requires that @code{F1}
be already elaborated.
@end itemize
It is hard to generalize on which of these four approaches should be
taken. Obviously if it is possible to fix the program so that the default
treatment works, this is preferable, but this may not always be practical.
-It is certainly simple enough to use @emph{-gnatE}
+It is certainly simple enough to use @code{-gnatE}
but the danger in this case is that, even if the GNAT binder
finds a correct elaboration order, it may not always do so,
and certainly a binder from another Ada compiler might not. A
combination of testing and analysis (for which the
-information messages generated with the @emph{-gnatel}
+information messages generated with the @code{-gnatel}
switch can be useful) must be used to ensure that the program is free
of errors. One switch that is useful in this testing is the
-@emph{-p (pessimistic elaboration order)} switch for @cite{gnatbind}.
+@code{-p} (pessimistic elaboration order) switch for @code{gnatbind}.
Normally the binder tries to find an order that has the best chance
of avoiding elaboration problems. However, if this switch is used, the binder
plays a devil's advocate role, and tries to choose the order that
a correct order statically, and it checks that an exception is indeed
raised at run time.
-This one test must be compiled and run using the @emph{-gnatE}
+This one test must be compiled and run using the @code{-gnatE}
switch, and then it passes. Alternatively, the entire suite can
be run using this switch. It is never wrong to run with the dynamic
elaboration switch if your code is correct, and we assume that the
not a factor in running the ACATS tests.)
@node Elaboration for Indirect Calls,Summary of Procedures for Elaboration Control,What to Do If the Default Elaboration Behavior Fails,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{246}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-for-indirect-calls}@anchor{247}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{248}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-for-indirect-calls}@anchor{249}
@section Elaboration for Indirect Calls
dispatching calls to not-yet-elaborated subprograms. In such cases, we
fall back to run-time checks; premature calls to any primitive
operation of a tagged type before the body of the operation has been
-elaborated will raise @cite{Program_Error}.
+elaborated will raise @code{Program_Error}.
Access-to-subprogram types, however, are handled conservatively in many
cases. This was not true in earlier versions of the compiler; you can use
-the @emph{-gnatd.U} debug switch to revert to the old behavior if the new
+the @code{-gnatd.U} debug switch to revert to the old behavior if the new
conservative behavior causes elaboration cycles. Here, 'conservative' means
-that if you do @cite{P'Access} during elaboration, the compiler will normally
-assume that you might call @cite{P} indirectly during elaboration, so it adds an
-implicit @cite{pragma Elaborate_All} on the library unit containing @cite{P}. The
-@emph{-gnatd.U} switch is safe if you know there are no such calls. If the
-program worked before, it will continue to work with @emph{-gnatd.U}. But beware
+that if you do @code{P'Access} during elaboration, the compiler will normally
+assume that you might call @code{P} indirectly during elaboration, so it adds an
+implicit @code{pragma Elaborate_All} on the library unit containing @code{P}. The
+@code{-gnatd.U} switch is safe if you know there are no such calls. If the
+program worked before, it will continue to work with @code{-gnatd.U}. But beware
that code modifications such as adding an indirect call can cause erroneous
-behavior in the presence of @emph{-gnatd.U}.
+behavior in the presence of @code{-gnatd.U}.
These implicit Elaborate_All pragmas are not added in all cases, because
they cause elaboration cycles in certain common code patterns. If you want
-even more conservative handling of P'Access, you can use the @emph{-gnatd.o}
+even more conservative handling of P'Access, you can use the @code{-gnatd.o}
switch.
-See @cite{debug.adb} for documentation on the @emph{-gnatd...} debug switches.
+See @code{debug.adb} for documentation on the @code{-gnatd...} debug switches.
@node Summary of Procedures for Elaboration Control,Other Elaboration Order Considerations,Elaboration for Indirect Calls,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{248}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{249}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{24a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{24b}
@section Summary of Procedures for Elaboration Control
raised by the use of access-to-subprogram types and dynamic dispatching,
the program is free of elaboration errors. If it is important that the
program be portable to other compilers than GNAT, then use the
-@emph{-gnatel}
-switch to generate messages about missing @cite{Elaborate} or
-@cite{Elaborate_All} pragmas, and supply the missing pragmas.
+@code{-gnatel}
+switch to generate messages about missing @code{Elaborate} or
+@code{Elaborate_All} pragmas, and supply the missing pragmas.
If the program fails to bind using the default static elaboration
handling, then you can fix the program to eliminate the binder
message, or recompile the entire program with the
-@emph{-gnatE} switch to generate dynamic elaboration checks,
+@code{-gnatE} switch to generate dynamic elaboration checks,
and, if you are sure there really are no elaboration problems,
-use a global pragma @cite{Suppress (Elaboration_Check)}.
+use a global pragma @code{Suppress (Elaboration_Check)}.
@node Other Elaboration Order Considerations,Determining the Chosen Elaboration Order,Summary of Procedures for Elaboration Control,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{24a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat other-elaboration-order-considerations}@anchor{24b}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{24c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat other-elaboration-order-considerations}@anchor{24d}
@section Other Elaboration Order Considerations
There is no language rule to prefer one or the other, both are correct
from an order of elaboration point of view. But the programmatic effects
of the two orders are very different. In the first, the elaboration routine
-of @cite{Calc} initializes @cite{Z} to zero, and then the main program
+of @code{Calc} initializes @code{Z} to zero, and then the main program
runs with this value of zero. But in the second order, the elaboration
-routine of @cite{Calc} runs after the body of Init_Constants has set
-@cite{X} and @cite{Y} and thus @cite{Z} is set to 7 before @cite{Main} runs.
+routine of @code{Calc} runs after the body of Init_Constants has set
+@code{X} and @code{Y} and thus @code{Z} is set to 7 before @code{Main} runs.
One could perhaps by applying pretty clever non-artificial intelligence
to the situation guess that it is more likely that the second order of
pragma Elaborate_All (Constants);
@end example
-which requires that the body (if any) and spec of @cite{Constants},
+which requires that the body (if any) and spec of @code{Constants},
as well as the body and spec of any unit @emph{with}ed by
-@cite{Constants} be elaborated before @cite{Calc} is elaborated.
+@code{Constants} be elaborated before @code{Calc} is elaborated.
Clearly no automatic method can always guess which alternative you require,
and if you are working with legacy code that had constraints of this kind
-which were not properly specified by adding @cite{Elaborate} or
-@cite{Elaborate_All} pragmas, then indeed it is possible that two different
+which were not properly specified by adding @code{Elaborate} or
+@code{Elaborate_All} pragmas, then indeed it is possible that two different
compilers can choose different orders.
However, GNAT does attempt to diagnose the common situation where there
in which a pragma Elaborate_Body is usually desirable, and GNAT will generate
a warning that suggests this addition if it detects this situation.
-The @cite{gnatbind} @emph{-p} switch may be useful in smoking
+The @code{gnatbind` :switch:`-p` switch may be useful in smoking
out problems. This switch causes bodies to be elaborated as late as possible
instead of as early as possible. In the example above, it would have forced
the choice of the first elaboration order. If you get different results
when using this switch, and particularly if one set of results is right,
and one is wrong as far as you are concerned, it shows that you have some
-missing @cite{Elaborate} pragmas. For the example above, we have the
+missing `@w{`}Elaborate} pragmas. For the example above, we have the
following output:
@example
it is up to you in a case like this to investigate the source of the
difference, by looking at the two elaboration orders that are chosen,
and figuring out which is correct, and then adding the necessary
-@cite{Elaborate} or @cite{Elaborate_All} pragmas to ensure the desired order.
+@code{Elaborate} or @code{Elaborate_All} pragmas to ensure the desired order.
@node Determining the Chosen Elaboration Order,,Other Elaboration Order Considerations,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat determining-the-chosen-elaboration-order}@anchor{24c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id15}@anchor{24d}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat determining-the-chosen-elaboration-order}@anchor{24e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id15}@anchor{24f}
@section Determining the Chosen Elaboration Order
You can also ask the binder to generate a more
readable list of the elaboration order using the
-@cite{-l} switch when invoking the binder. Here is
+@code{-l} switch when invoking the binder. Here is
an example of the output generated by this switch:
@example
@end example
@node Inline Assembler,GNU Free Documentation License,Elaboration Order Handling in GNAT,Top
-@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}@anchor{gnat_ugn/inline_assembler doc}@anchor{24e}@anchor{gnat_ugn/inline_assembler id1}@anchor{24f}
+@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}@anchor{gnat_ugn/inline_assembler doc}@anchor{250}@anchor{gnat_ugn/inline_assembler id1}@anchor{251}
@chapter Inline Assembler
supported by GNAT. However, for small sections of code it may be simpler
or more efficient to include assembly language statements directly
in your Ada source program, using the facilities of the implementation-defined
-package @cite{System.Machine_Code}, which incorporates the gcc
+package @code{System.Machine_Code}, which incorporates the gcc
Inline Assembler. The Inline Assembler approach offers a number of advantages,
including the following:
@end menu
@node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id2}@anchor{250}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{251}
+@anchor{gnat_ugn/inline_assembler id2}@anchor{252}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{253}
@section Basic Assembler Syntax
The assembler used by GNAT and gcc is based not on the Intel assembly
language, but rather on a language that descends from the AT&T Unix
-assembler @emph{as} (and which is often referred to as 'AT&T syntax').
-The following table summarizes the main features of @emph{as} syntax
+assembler @code{as} (and which is often referred to as 'AT&T syntax').
+The following table summarizes the main features of @code{as} syntax
and points out the differences from the Intel conventions.
-See the gcc @emph{as} and @emph{gas} (an @emph{as} macro
+See the gcc @code{as} and @code{gas} (an @code{as} macro
pre-processor) documentation for further information.
@display
@emph{Register names}@w{ }
@display
-gcc / @emph{as}: Prefix with '%'; for example @cite{%eax}@w{ }
-Intel: No extra punctuation; for example @cite{eax}@w{ }
+gcc / @code{as}: Prefix with '%'; for example @code{%eax}@w{ }
+Intel: No extra punctuation; for example @code{eax}@w{ }
@end display
@end display
@display
@emph{Immediate operand}@w{ }
@display
-gcc / @emph{as}: Prefix with '$'; for example @cite{$4}@w{ }
-Intel: No extra punctuation; for example @cite{4}@w{ }
+gcc / @code{as}: Prefix with '$'; for example @code{$4}@w{ }
+Intel: No extra punctuation; for example @code{4}@w{ }
@end display
@end display
@display
@emph{Address}@w{ }
@display
-gcc / @emph{as}: Prefix with '$'; for example @cite{$loc}@w{ }
-Intel: No extra punctuation; for example @cite{loc}@w{ }
+gcc / @code{as}: Prefix with '$'; for example @code{$loc}@w{ }
+Intel: No extra punctuation; for example @code{loc}@w{ }
@end display
@end display
@display
@emph{Memory contents}@w{ }
@display
-gcc / @emph{as}: No extra punctuation; for example @cite{loc}@w{ }
-Intel: Square brackets; for example @cite{[loc]}@w{ }
+gcc / @code{as}: No extra punctuation; for example @code{loc}@w{ }
+Intel: Square brackets; for example @code{[loc]}@w{ }
@end display
@end display
@display
@emph{Register contents}@w{ }
@display
-gcc / @emph{as}: Parentheses; for example @cite{(%eax)}@w{ }
-Intel: Square brackets; for example @cite{[eax]}@w{ }
+gcc / @code{as}: Parentheses; for example @code{(%eax)}@w{ }
+Intel: Square brackets; for example @code{[eax]}@w{ }
@end display
@end display
@display
@emph{Hexadecimal numbers}@w{ }
@display
-gcc / @emph{as}: Leading '0x' (C language syntax); for example @cite{0xA0}@w{ }
-Intel: Trailing 'h'; for example @cite{A0h}@w{ }
+gcc / @code{as}: Leading '0x' (C language syntax); for example @code{0xA0}@w{ }
+Intel: Trailing 'h'; for example @code{A0h}@w{ }
@end display
@end display
@display
@emph{Operand size}@w{ }
@display
-gcc / @emph{as}: Explicit in op code; for example @cite{movw} to move a 16-bit word@w{ }
-Intel: Implicit, deduced by assembler; for example @cite{mov}@w{ }
+gcc / @code{as}: Explicit in op code; for example @code{movw} to move a 16-bit word@w{ }
+Intel: Implicit, deduced by assembler; for example @code{mov}@w{ }
@end display
@end display
@display
@emph{Instruction repetition}@w{ }
@display
-gcc / @emph{as}: Split into two lines; for example@w{ }
+gcc / @code{as}: Split into two lines; for example@w{ }
@display
-@cite{rep}@w{ }
-@cite{stosl}@w{ }
+@code{rep}@w{ }
+@code{stosl}@w{ }
@end display
-Intel: Keep on one line; for example @cite{rep stosl}@w{ }
+Intel: Keep on one line; for example @code{rep stosl}@w{ }
@end display
@end display
@display
@emph{Order of operands}@w{ }
@display
-gcc / @emph{as}: Source first; for example @cite{movw $4@comma{} %eax}@w{ }
-Intel: Destination first; for example @cite{mov eax@comma{} 4}@w{ }
+gcc / @code{as}: Source first; for example @code{movw $4, %eax}@w{ }
+Intel: Destination first; for example @code{mov eax, 4}@w{ }
@end display
@end display
@node A Simple Example of Inline Assembler,Output Variables in Inline Assembler,Basic Assembler Syntax,Inline Assembler
-@anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{252}@anchor{gnat_ugn/inline_assembler id3}@anchor{253}
+@anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{254}@anchor{gnat_ugn/inline_assembler id3}@anchor{255}
@section A Simple Example of Inline Assembler
The following example will generate a single assembly language statement,
-@cite{nop}, which does nothing. Despite its lack of run-time effect,
+@code{nop}, which does nothing. Despite its lack of run-time effect,
the example will be useful in illustrating the basics of
the Inline Assembler facility.
@end example
@end quotation
-@cite{Asm} is a procedure declared in package @cite{System.Machine_Code};
+@code{Asm} is a procedure declared in package @code{System.Machine_Code};
here it takes one parameter, a @emph{template string} that must be a static
expression and that will form the generated instruction.
-@cite{Asm} may be regarded as a compile-time procedure that parses
+@code{Asm} may be regarded as a compile-time procedure that parses
the template string and additional parameters (none here),
from which it generates a sequence of assembly language instructions.
The examples in this chapter will illustrate several of the forms
-for invoking @cite{Asm}; a complete specification of the syntax
-is found in the @cite{Machine_Code_Insertions} section of the
+for invoking @code{Asm}; a complete specification of the syntax
+is found in the @code{Machine_Code_Insertions} section of the
@cite{GNAT Reference Manual}.
-Under the standard GNAT conventions, the @cite{Nothing} procedure
+Under the standard GNAT conventions, the @code{Nothing} procedure
should be in a file named @code{nothing.adb}.
You can build the executable in the usual way:
@end itemize
This gives a human-readable assembler version of the code. The resulting
-file will have the same name as the Ada source file, but with a @cite{.s}
+file will have the same name as the Ada source file, but with a @code{.s}
extension. In our example, the file @code{nothing.s} has the following
contents:
@end quotation
The assembly code you included is clearly indicated by
-the compiler, between the @cite{#APP} and @cite{#NO_APP}
+the compiler, between the @code{#APP} and @code{#NO_APP}
delimiters. The character before the 'APP' and 'NOAPP'
can differ on different targets. For example, GNU/Linux uses '#APP' while
on NT you will see '/APP'.
will report this error in a temporary file, which will be deleted when
the compilation is finished. Generating an assembler file will help
in such cases, since you can assemble this file separately using the
-@emph{as} assembler that comes with gcc.
+@code{as} assembler that comes with gcc.
Assembling the file using the command
will give you error messages whose lines correspond to the assembler
input file, so you can easily find and correct any mistakes you made.
-If there are no errors, @emph{as} will generate an object file
+If there are no errors, @code{as} will generate an object file
@code{nothing.out}.
@node Output Variables in Inline Assembler,Input Variables in Inline Assembler,A Simple Example of Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id4}@anchor{254}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{255}
+@anchor{gnat_ugn/inline_assembler id4}@anchor{256}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{257}
@section Output Variables in Inline Assembler
When writing Inline Assembler instructions, you need to precede each register
and variable name with a percent sign. Since the assembler already requires
a percent sign at the beginning of a register name, you need two consecutive
-percent signs for such names in the Asm template string, thus @cite{%%eax}.
+percent signs for such names in the Asm template string, thus @code{%%eax}.
In the generated assembly code, one of the percent signs will be stripped off.
-Names such as @cite{%0}, @cite{%1}, @cite{%2}, etc., denote input or output
-variables: operands you later define using @cite{Input} or @cite{Output}
-parameters to @cite{Asm}.
+Names such as @code{%0}, @code{%1}, @code{%2}, etc., denote input or output
+variables: operands you later define using @code{Input} or @code{Output}
+parameters to @code{Asm}.
An output variable is illustrated in
the third statement in the Asm template string:
@end quotation
The intent is to store the contents of the eax register in a variable that can
-be accessed in Ada. Simply writing @cite{movl %%eax@comma{} Flags} would not
+be accessed in Ada. Simply writing @code{movl %%eax, Flags} would not
necessarily work, since the compiler might optimize by using a register
-to hold Flags, and the expansion of the @cite{movl} instruction would not be
+to hold Flags, and the expansion of the @code{movl} instruction would not be
aware of this optimization. The solution is not to store the result directly
but rather to advise the compiler to choose the correct operand form;
-that is the purpose of the @cite{%0} output variable.
+that is the purpose of the @code{%0} output variable.
-Information about the output variable is supplied in the @cite{Outputs}
-parameter to @cite{Asm}:
+Information about the output variable is supplied in the @code{Outputs}
+parameter to @code{Asm}:
@quotation
@end example
@end quotation
-The output is defined by the @cite{Asm_Output} attribute of the target type;
+The output is defined by the @code{Asm_Output} attribute of the target type;
the general format is
@quotation
@end example
@end quotation
-the @cite{"m"} (memory) constraint tells the compiler that the variable
-@cite{Flags} should be stored in a memory variable, thus preventing
+the @code{"m"} (memory) constraint tells the compiler that the variable
+@code{Flags} should be stored in a memory variable, thus preventing
the optimizer from keeping it in a register. In contrast,
@quotation
@end example
@end quotation
-uses the @cite{"r"} (register) constraint, telling the compiler to
+uses the @code{"r"} (register) constraint, telling the compiler to
store the variable in a register.
If the constraint is preceded by the equal character '=', it tells
the compiler that the variable will be used to store data into it.
-In the @cite{Get_Flags} example, we used the @cite{"g"} (global) constraint,
+In the @code{Get_Flags} example, we used the @code{"g"} (global) constraint,
allowing the optimizer to choose whatever it deems best.
There are a fairly large number of constraints, but the ones that are
@end quotation
-The full set of constraints is described in the gcc and @emph{as}
+The full set of constraints is described in the gcc and @code{as}
documentation; note that it is possible to combine certain constraints
in one constraint string.
@end example
@end quotation
-@cite{%0} will be replaced in the expanded code by the appropriate operand,
+@code{%0} will be replaced in the expanded code by the appropriate operand,
whatever
-the compiler decided for the @cite{Flags} variable.
+the compiler decided for the @code{Flags} variable.
In general, you may have any number of output variables:
@itemize *
@item
-Count the operands starting at 0; thus @cite{%0}, @cite{%1}, etc.
+Count the operands starting at 0; thus @code{%0}, @code{%1}, etc.
@item
-Specify the @cite{Outputs} parameter as a parenthesized comma-separated list
-of @cite{Asm_Output} attributes
+Specify the @code{Outputs} parameter as a parenthesized comma-separated list
+of @code{Asm_Output} attributes
@end itemize
For example:
@end example
@end quotation
-where @cite{Var_A}, @cite{Var_B}, and @cite{Var_C} are variables
+where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables
in the Ada program.
-As a variation on the @cite{Get_Flags} example, we can use the constraints
-string to direct the compiler to store the eax register into the @cite{Flags}
+As a variation on the @code{Get_Flags} example, we can use the constraints
+string to direct the compiler to store the eax register into the @code{Flags}
variable, instead of including the store instruction explicitly in the
-@cite{Asm} template string:
+@code{Asm} template string:
@quotation
@end example
@end quotation
-The @cite{"a"} constraint tells the compiler that the @cite{Flags}
+The @code{"a"} constraint tells the compiler that the @code{Flags}
variable will come from the eax register. Here is the resulting code:
@quotation
@end quotation
@node Input Variables in Inline Assembler,Inlining Inline Assembler Code,Output Variables in Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id5}@anchor{256}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{257}
+@anchor{gnat_ugn/inline_assembler id5}@anchor{258}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{259}
@section Input Variables in Inline Assembler
@end example
@end quotation
-The @cite{Outputs} parameter to @cite{Asm} specifies
+The @code{Outputs} parameter to @code{Asm} specifies
that the result will be in the eax register and that it is to be stored
-in the @cite{Result} variable.
+in the @code{Result} variable.
-The @cite{Inputs} parameter looks much like the @cite{Outputs} parameter,
-but with an @cite{Asm_Input} attribute.
-The @cite{"="} constraint, indicating an output value, is not present.
+The @code{Inputs} parameter looks much like the @code{Outputs} parameter,
+but with an @code{Asm_Input} attribute.
+The @code{"="} constraint, indicating an output value, is not present.
You can have multiple input variables, in the same way that you can have more
than one output variable.
The parameter count (%0, %1) etc, still starts at the first output statement,
and continues with the input statements.
-Just as the @cite{Outputs} parameter causes the register to be stored into the
+Just as the @code{Outputs} parameter causes the register to be stored into the
target variable after execution of the assembler statements, so does the
-@cite{Inputs} parameter cause its variable to be loaded into the register
+@code{Inputs} parameter cause its variable to be loaded into the register
before execution of the assembler statements.
-Thus the effect of the @cite{Asm} invocation is:
+Thus the effect of the @code{Asm} invocation is:
@itemize *
@item
-load the 32-bit value of @cite{Value} into eax
+load the 32-bit value of @code{Value} into eax
@item
-execute the @cite{incl %eax} instruction
+execute the @code{incl %eax} instruction
@item
-store the contents of eax into the @cite{Result} variable
+store the contents of eax into the @code{Result} variable
@end itemize
-The resulting assembler file (with @emph{-O2} optimization) contains:
+The resulting assembler file (with @code{-O2} optimization) contains:
@quotation
@end quotation
@node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id6}@anchor{258}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{259}
+@anchor{gnat_ugn/inline_assembler id6}@anchor{25a}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{25b}
@section Inlining Inline Assembler Code
-For a short subprogram such as the @cite{Incr} function in the previous
+For a short subprogram such as the @code{Incr} function in the previous
section, the overhead of the call and return (creating / deleting the stack
frame) can be significant, compared to the amount of code in the subprogram
-body. A solution is to apply Ada's @cite{Inline} pragma to the subprogram,
+body. A solution is to apply Ada's @code{Inline} pragma to the subprogram,
which directs the compiler to expand invocations of the subprogram at the
point(s) of call, instead of setting up a stack frame for out-of-line calls.
Here is the resulting program:
@end example
@end quotation
-Compile the program with both optimization (@emph{-O2}) and inlining
-(@emph{-gnatn}) enabled.
+Compile the program with both optimization (@code{-O2}) and inlining
+(@code{-gnatn}) enabled.
-The @cite{Incr} function is still compiled as usual, but at the
-point in @cite{Increment} where our function used to be called:
+The @code{Incr} function is still compiled as usual, but at the
+point in @code{Increment} where our function used to be called:
@quotation
thus saving the overhead of stack frame setup and an out-of-line call.
@node Other Asm Functionality,,Inlining Inline Assembler Code,Inline Assembler
-@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{25a}@anchor{gnat_ugn/inline_assembler id7}@anchor{25b}
-@section Other @cite{Asm} Functionality
+@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{25c}@anchor{gnat_ugn/inline_assembler id7}@anchor{25d}
+@section Other @code{Asm} Functionality
-This section describes two important parameters to the @cite{Asm}
-procedure: @cite{Clobber}, which identifies register usage;
-and @cite{Volatile}, which inhibits unwanted optimizations.
+This section describes two important parameters to the @code{Asm}
+procedure: @code{Clobber}, which identifies register usage;
+and @code{Volatile}, which inhibits unwanted optimizations.
@menu
* The Clobber Parameter::
@end menu
@node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{25c}@anchor{gnat_ugn/inline_assembler id8}@anchor{25d}
-@subsection The @cite{Clobber} Parameter
+@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{25e}@anchor{gnat_ugn/inline_assembler id8}@anchor{25f}
+@subsection The @code{Clobber} Parameter
One of the dangers of intermixing assembly language and a compiled language
such as Ada is that the compiler needs to be aware of which registers are
being used by the assembly code. In some cases, such as the earlier examples,
the constraint string is sufficient to indicate register usage (e.g.,
-@cite{"a"} for
+@code{"a"} for
the eax register). But more generally, the compiler needs an explicit
identification of the registers that are used by the Inline Assembly
statements.
Using a register that the compiler doesn't know about
-could be a side effect of an instruction (like @cite{mull}
+could be a side effect of an instruction (like @code{mull}
storing its result in both eax and edx).
It can also arise from explicit register usage in your
assembly code; for example:
@end example
@end quotation
-where the compiler (since it does not analyze the @cite{Asm} template string)
+where the compiler (since it does not analyze the @code{Asm} template string)
does not know you are using the ebx register.
-In such cases you need to supply the @cite{Clobber} parameter to @cite{Asm},
+In such cases you need to supply the @code{Clobber} parameter to @code{Asm},
to identify the registers that will be used by your assembly code:
@quotation
The Clobber parameter is a static string expression specifying the
register(s) you are using. Note that register names are @emph{not} prefixed
by a percent sign. Also, if more than one register is used then their names
-are separated by commas; e.g., @cite{"eax@comma{} ebx"}
+are separated by commas; e.g., @code{"eax, ebx"}
-The @cite{Clobber} parameter has several additional uses:
+The @code{Clobber} parameter has several additional uses:
@itemize *
@item
-Use 'register' name @cite{cc} to indicate that flags might have changed
+Use 'register' name @code{cc} to indicate that flags might have changed
@item
-Use 'register' name @cite{memory} if you changed a memory location
+Use 'register' name @code{memory} if you changed a memory location
@end itemize
@node The Volatile Parameter,,The Clobber Parameter,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{25e}@anchor{gnat_ugn/inline_assembler id9}@anchor{25f}
-@subsection The @cite{Volatile} Parameter
+@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{260}@anchor{gnat_ugn/inline_assembler id9}@anchor{261}
+@subsection The @code{Volatile} Parameter
@geindex Volatile parameter
Compiler optimizations in the presence of Inline Assembler may sometimes have
-unwanted effects. For example, when an @cite{Asm} invocation with an input
+unwanted effects. For example, when an @code{Asm} invocation with an input
variable is inside a loop, the compiler might move the loading of the input
variable outside the loop, regarding it as a one-time initialization.
If this effect is not desired, you can disable such optimizations by setting
-the @cite{Volatile} parameter to @cite{True}; for example:
+the @code{Volatile} parameter to @code{True}; for example:
@quotation
@end example
@end quotation
-By default, @cite{Volatile} is set to @cite{False} unless there is no
-@cite{Outputs} parameter.
+By default, @code{Volatile} is set to @code{False} unless there is no
+@code{Outputs} parameter.
-Although setting @cite{Volatile} to @cite{True} prevents unwanted
+Although setting @code{Volatile} to @code{True} prevents unwanted
optimizations, it will also disable other optimizations that might be
-important for efficiency. In general, you should set @cite{Volatile}
-to @cite{True} only if the compiler's optimizations have created
+important for efficiency. In general, you should set @code{Volatile}
+to @code{True} only if the compiler's optimizations have created
problems.
@node GNU Free Documentation License,Index,Inline Assembler,Top
-@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{260}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{261}
+@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{262}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{263}
@chapter GNU Free Documentation License
projects / gcc.git / commitdiff